@statelyai/sdk 0.15.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,22 @@
1
1
  import { i as StatelyGraph } from "./graph-DuOeLGvh.mjs";
2
2
 
3
3
  //#region src/protocol.d.ts
4
- type EmbedMode = "editing" | "viewing" | "simulating" | "inspecting";
4
+ /** Query parameter carrying the unguessable inspection room capability. */
5
+ declare const INSPECTION_ROOM_QUERY_PARAM = "r";
6
+ interface InspectionRoomUrls {
7
+ roomId: string;
8
+ relayUrl: string;
9
+ inspectorUrl: string;
10
+ }
11
+ /** Resolve the transport and browser URLs required by the inspection protocol. */
12
+ declare function createInspectionRoomUrls(options: {
13
+ url: string;
14
+ roomId: string;
15
+ inspectorBaseUrl?: string;
16
+ }): InspectionRoomUrls;
17
+ /** Read a room capability from a conforming relay or inspector URL. */
18
+ declare function getInspectionRoomId(value: string | URL): string | null;
19
+ type EmbedMode = 'editing' | 'viewing' | 'simulating' | 'inspecting';
5
20
  interface CommentsConfig {
6
21
  roomId: string;
7
22
  userId?: string | null;
@@ -17,7 +32,7 @@ interface ProjectEmbedMachine {
17
32
  interface ValidationIssue {
18
33
  nodeIds: string[];
19
34
  edgeIds: string[];
20
- level: "info" | "warning" | "error";
35
+ level: 'info' | 'warning' | 'error';
21
36
  message: string;
22
37
  }
23
38
  interface EditorCapabilities {
@@ -31,11 +46,11 @@ interface EditorCapabilities {
31
46
  panels?: string[];
32
47
  commands?: string[];
33
48
  }
34
- type ReadOnlyReason = "free-plan" | "access-unverified";
35
- type CapabilityDeniedCapability = "edit" | "export" | "ai" | "simulate" | "inspect" | "navigateHierarchy" | "panel" | "mode";
49
+ type ReadOnlyReason = 'free-plan' | 'access-unverified';
50
+ type CapabilityDeniedCapability = 'edit' | 'export' | 'ai' | 'simulate' | 'inspect' | 'navigateHierarchy' | 'panel' | 'mode';
36
51
  interface CapabilityDeniedEvent {
37
52
  capability: CapabilityDeniedCapability;
38
- action: "openPanel" | "openDialog" | "editSource" | "navigateHierarchy" | "setMode" | "simulationStart" | "inspectStart" | "retrieve";
53
+ action: 'openPanel' | 'openDialog' | 'editSource' | 'navigateHierarchy' | 'setMode' | 'simulationStart' | 'inspectStart' | 'retrieve';
39
54
  requested?: string;
40
55
  message: string;
41
56
  dedupeKey: string;
@@ -52,12 +67,12 @@ interface SourceLocation {
52
67
  }
53
68
  interface StateSourceLocation extends SourceLocation {
54
69
  path: string[];
55
- kind: "inline" | "objectReference" | "createStateConfig";
70
+ kind: 'inline' | 'objectReference' | 'createStateConfig';
56
71
  symbol?: string;
57
72
  keyRange?: SourceRange;
58
73
  referenceRange?: SourceRange;
59
74
  keySource?: {
60
- kind: "const" | "enumMember" | "computedLiteral";
75
+ kind: 'const' | 'enumMember' | 'computedLiteral';
61
76
  symbol?: string;
62
77
  valueRange?: SourceRange;
63
78
  machineLocal?: boolean;
@@ -87,7 +102,7 @@ interface ExportFormatMap {
87
102
  options: object;
88
103
  result: string;
89
104
  };
90
- "xstate-json": {
105
+ 'xstate-json': {
91
106
  options: {
92
107
  version?: 4 | 5;
93
108
  };
@@ -119,11 +134,11 @@ interface ExportFormatMap {
119
134
  options: object;
120
135
  result: string;
121
136
  };
122
- "asl-json": {
137
+ 'asl-json': {
123
138
  options: object;
124
139
  result: string;
125
140
  };
126
- "asl-yaml": {
141
+ 'asl-yaml': {
127
142
  options: object;
128
143
  result: string;
129
144
  };
@@ -133,7 +148,7 @@ interface ExportFormatMap {
133
148
  };
134
149
  }
135
150
  type ExportFormat = keyof ExportFormatMap;
136
- type ExportCallOptions<F extends ExportFormat> = ExportFormatMap[F]["options"] & {
151
+ type ExportCallOptions<F extends ExportFormat> = ExportFormatMap[F]['options'] & {
137
152
  timeout?: number;
138
153
  };
139
154
  interface EmbedEventMap {
@@ -179,7 +194,7 @@ interface MachineInitOptions {
179
194
  machine: unknown;
180
195
  format?: string;
181
196
  mode?: EmbedMode;
182
- theme?: "light" | "dark";
197
+ theme?: 'light' | 'dark';
183
198
  readOnly?: boolean;
184
199
  readOnlyReason?: ReadOnlyReason;
185
200
  depth?: number;
@@ -206,14 +221,14 @@ interface MachineInitOptions {
206
221
  */
207
222
  unsavedIndicator?: {
208
223
  enabled?: boolean;
209
- mode?: "structural" | "all";
224
+ mode?: 'structural' | 'all';
210
225
  };
211
226
  }
212
227
  interface ProjectInitOptions {
213
228
  machines: ProjectEmbedMachine[];
214
229
  currentMachineId?: string;
215
230
  mode?: EmbedMode;
216
- theme?: "light" | "dark";
231
+ theme?: 'light' | 'dark';
217
232
  readOnly?: boolean;
218
233
  depth?: number;
219
234
  capabilities?: EditorCapabilities;
@@ -226,16 +241,16 @@ interface ProjectInitOptions {
226
241
  settings?: Record<string, unknown>;
227
242
  unsavedIndicator?: {
228
243
  enabled?: boolean;
229
- mode?: "structural" | "all";
244
+ mode?: 'structural' | 'all';
230
245
  };
231
246
  }
232
247
  type InitOptions = MachineInitOptions | ProjectInitOptions;
233
248
  interface InitMessage {
234
- type: "@statelyai.init";
249
+ type: '@statelyai.init';
235
250
  machine: unknown;
236
251
  format?: string;
237
252
  mode?: EmbedMode;
238
- theme?: "light" | "dark";
253
+ theme?: 'light' | 'dark';
239
254
  readOnly?: boolean;
240
255
  readOnlyReason?: ReadOnlyReason;
241
256
  depth?: number;
@@ -249,21 +264,19 @@ interface InitMessage {
249
264
  /** Mirror of `InitOptions.unsavedIndicator`. */
250
265
  unsavedIndicator?: {
251
266
  enabled?: boolean;
252
- mode?: "structural" | "all";
267
+ mode?: 'structural' | 'all';
253
268
  };
254
- /** Optional session id override (multiplexed clients only). */
255
- sessionId?: string;
256
269
  }
257
270
  interface SetApiKeyMessage {
258
- type: "@statelyai.setApiKey";
271
+ type: '@statelyai.setApiKey';
259
272
  apiKey: string;
260
273
  }
261
274
  interface ProjectInitMessage {
262
- type: "@statelyai.project.init";
275
+ type: '@statelyai.project.init';
263
276
  machines: ProjectEmbedMachine[];
264
277
  currentMachineId?: string;
265
278
  mode?: EmbedMode;
266
- theme?: "light" | "dark";
279
+ theme?: 'light' | 'dark';
267
280
  readOnly?: boolean;
268
281
  depth?: number;
269
282
  capabilities?: EditorCapabilities;
@@ -274,67 +287,63 @@ interface ProjectInitMessage {
274
287
  settings?: Record<string, unknown>;
275
288
  unsavedIndicator?: {
276
289
  enabled?: boolean;
277
- mode?: "structural" | "all";
290
+ mode?: 'structural' | 'all';
278
291
  };
279
292
  sessionId?: string;
280
293
  }
281
294
  interface ProjectUpdateMessage {
282
- type: "@statelyai.project.update";
295
+ type: '@statelyai.project.update';
283
296
  machines: ProjectEmbedMachine[];
284
297
  currentMachineId?: string;
285
298
  commentsByMachineId?: Record<string, CommentsConfig>;
286
299
  }
287
300
  interface ProjectSelectMachineMessage {
288
- type: "@statelyai.project.selectMachine";
301
+ type: '@statelyai.project.selectMachine';
289
302
  machineId: string;
290
303
  }
291
304
  interface UpdateMessage {
292
- type: "@statelyai.update";
305
+ type: '@statelyai.update';
293
306
  machine: unknown;
294
307
  format?: string;
295
308
  sourceLocations?: MachineSourceLocations;
296
309
  }
297
310
  interface SetModeMessage {
298
- type: "@statelyai.setMode";
311
+ type: '@statelyai.setMode';
299
312
  mode: EmbedMode;
300
313
  }
301
314
  interface SetThemeMessage {
302
- type: "@statelyai.setTheme";
303
- theme: "light" | "dark";
315
+ type: '@statelyai.setTheme';
316
+ theme: 'light' | 'dark';
304
317
  }
305
318
  interface SetSettingsMessage {
306
- type: "@statelyai.setSettings";
319
+ type: '@statelyai.setSettings';
307
320
  settings: Record<string, unknown>;
308
321
  }
309
322
  interface RetrieveMessage {
310
- type: "@statelyai.retrieve";
323
+ type: '@statelyai.retrieve';
311
324
  requestId: string;
312
325
  format: ExportFormat;
313
326
  options?: Record<string, unknown>;
314
327
  }
315
328
  interface ToastMessage {
316
- type: "@statelyai.toast";
329
+ type: '@statelyai.toast';
317
330
  message: string;
318
- toastType?: "success" | "error" | "info" | "warning";
331
+ toastType?: 'success' | 'error' | 'info' | 'warning';
319
332
  }
320
333
  interface InspectSnapshotMessage {
321
- type: "@statelyai.inspectSnapshot";
334
+ type: '@statelyai.inspectSnapshot';
322
335
  snapshot: unknown;
323
336
  event: unknown | null;
324
- /**
325
- * Optional session id override. Used by multiplexed clients that share one
326
- * WebSocket across many actor sessions. When omitted, the relay routes
327
- * to the connection's primary sessionId.
328
- */
337
+ /** Global actor session id, when this snapshot belongs to an actor. */
329
338
  sessionId?: string;
330
339
  }
331
340
  interface ActorSystemEntry {
332
- /** The xstate `actor.sessionId` — unique within the system. */
341
+ /** Globally unique xstate `actor.sessionId`. */
342
+ sessionId: string;
343
+ /** System-local xstate `actor.id`. */
333
344
  actorId: string;
334
345
  /** Parent actor's sessionId, or `null` for the root. */
335
- parentActorId: string | null;
336
- /** Human-facing id (`actor.id`). */
337
- id: string;
346
+ parentSessionId: string | null;
338
347
  /** Machine configuration used to render the state chart. */
339
348
  machine: unknown;
340
349
  /** Optional current snapshot (`{value, status, ...}`). */
@@ -356,21 +365,21 @@ interface InspectionTakenTransition {
356
365
  }
357
366
  /** JSON-safe record of an event sent or scheduled during a transition. */
358
367
  interface InspectionSentEvent {
359
- targetActorId?: string;
368
+ targetSessionId?: string;
360
369
  targetId: string;
361
370
  event: unknown;
362
371
  delay?: number;
363
372
  id?: string;
364
373
  }
365
374
  interface SystemInitMessage {
366
- type: "@statelyai.system.init";
367
- protocolVersion?: number;
375
+ type: '@statelyai.system.init';
376
+ protocolVersion: number;
368
377
  /** All known actors at the moment the system is first streamed. */
369
378
  actors: ActorSystemEntry[];
370
- /** Actor id the viz should focus first. Defaults to the root. */
371
- selectedActorId?: string;
379
+ /** Actor session id the viz should focus first. Defaults to the root. */
380
+ selectedSessionId?: string;
372
381
  mode?: EmbedMode;
373
- theme?: "light" | "dark";
382
+ theme?: 'light' | 'dark';
374
383
  readOnly?: boolean;
375
384
  depth?: number;
376
385
  capabilities?: EditorCapabilities;
@@ -381,36 +390,36 @@ interface SystemInitMessage {
381
390
  }
382
391
  /** Change the focused actor without re-initializing the system. */
383
392
  interface SystemSelectActorMessage {
384
- type: "@statelyai.system.selectActor";
385
- actorId: string;
393
+ type: '@statelyai.system.selectActor';
394
+ sessionId: string;
386
395
  }
387
396
  /** A new actor joined the system after init. */
388
397
  interface SystemActorRegisteredMessage {
389
- type: "@statelyai.system.actorRegistered";
398
+ type: '@statelyai.system.actorRegistered';
399
+ sessionId: string;
390
400
  actorId: string;
391
- parentActorId: string | null;
392
- id: string;
401
+ parentSessionId: string | null;
393
402
  machine: unknown;
394
403
  snapshot?: unknown;
395
404
  }
396
405
  /** An event was observed targeting an actor, before processing completed. */
397
406
  interface SystemActorEventMessage {
398
- type: "@statelyai.system.actorEvent";
399
- actorId: string;
407
+ type: '@statelyai.system.actorEvent';
408
+ sessionId: string;
400
409
  event: unknown;
401
- /** The actorId of the actor that sent the event, if known. */
402
- sourceActorId?: string | null;
410
+ /** Global session id of the actor that sent the event, if known. */
411
+ sourceSessionId?: string | null;
403
412
  }
404
413
  /** An actor's snapshot updated. */
405
414
  interface SystemActorSnapshotMessage {
406
- type: "@statelyai.system.actorSnapshot";
407
- actorId: string;
415
+ type: '@statelyai.system.actorSnapshot';
416
+ sessionId: string;
408
417
  /** Snapshot before the event was processed. */
409
418
  previousSnapshot?: unknown | null;
410
419
  snapshot: unknown;
411
420
  event?: unknown | null;
412
- /** The actorId of the actor that sent the triggering event, if known. */
413
- sourceActorId?: string | null;
421
+ /** Global session id of the actor that sent the triggering event, if known. */
422
+ sourceSessionId?: string | null;
414
423
  /** Actions executed while processing the event. */
415
424
  actions?: InspectionAction[];
416
425
  /** State transitions taken across every microstep. */
@@ -420,21 +429,21 @@ interface SystemActorSnapshotMessage {
420
429
  }
421
430
  /** An actor reached a final state / was stopped. */
422
431
  interface SystemActorStoppedMessage {
423
- type: "@statelyai.system.actorStopped";
424
- actorId: string;
432
+ type: '@statelyai.system.actorStopped';
433
+ sessionId: string;
425
434
  }
426
435
  interface ReadyMessage {
427
- type: "@statelyai.ready";
436
+ type: '@statelyai.ready';
428
437
  version: string;
429
438
  }
430
439
  interface LoadedMessage {
431
- type: "@statelyai.loaded";
440
+ type: '@statelyai.loaded';
432
441
  graph: StatelyGraph;
433
442
  machineId?: string;
434
443
  sourceLocations?: MachineSourceLocations;
435
444
  }
436
445
  interface ChangeMessage {
437
- type: "@statelyai.change";
446
+ type: '@statelyai.change';
438
447
  graph: StatelyGraph;
439
448
  machineConfig: unknown;
440
449
  machineId?: string;
@@ -442,7 +451,7 @@ interface ChangeMessage {
442
451
  sourceLocations?: MachineSourceLocations;
443
452
  }
444
453
  interface SaveMessage {
445
- type: "@statelyai.save";
454
+ type: '@statelyai.save';
446
455
  graph: StatelyGraph;
447
456
  machineConfig: unknown;
448
457
  machineId?: string;
@@ -451,22 +460,22 @@ interface SaveMessage {
451
460
  sourceLocations?: MachineSourceLocations;
452
461
  }
453
462
  interface ProjectMachineSelectedMessage {
454
- type: "@statelyai.project.machineSelected";
463
+ type: '@statelyai.project.machineSelected';
455
464
  machineId: string;
456
465
  }
457
466
  interface RetrievedMessage {
458
- type: "@statelyai.retrieved";
467
+ type: '@statelyai.retrieved';
459
468
  requestId: string;
460
469
  data: unknown;
461
470
  }
462
471
  interface ErrorMessage {
463
- type: "@statelyai.error";
472
+ type: '@statelyai.error';
464
473
  code: string;
465
474
  message: string;
466
475
  requestId?: string;
467
476
  }
468
477
  interface CapabilityDeniedMessage extends CapabilityDeniedEvent {
469
- type: "@statelyai.capabilityDenied";
478
+ type: '@statelyai.capabilityDenied';
470
479
  }
471
480
  /** File metadata sent from viz to SDK when a file needs uploading. */
472
481
  interface UploadFileInfo {
@@ -490,21 +499,21 @@ interface UploadResult {
490
499
  }
491
500
  /** Viz requests the parent to upload a file. */
492
501
  interface UploadRequestMessage {
493
- type: "@statelyai.uploadRequest";
502
+ type: '@statelyai.uploadRequest';
494
503
  requestId: string;
495
504
  file: UploadFileInfo;
496
505
  stateNodeId: string;
497
506
  }
498
507
  /** Parent tells the viz the upload capabilities on init. */
499
508
  interface UploadCapabilitiesMessage {
500
- type: "@statelyai.uploadCapabilities";
509
+ type: '@statelyai.uploadCapabilities';
501
510
  enabled: boolean;
502
511
  accept?: string[];
503
512
  maxFileSize?: number;
504
513
  }
505
514
  /** Parent sends the upload result back to the viz. */
506
515
  interface UploadResponseMessage {
507
- type: "@statelyai.uploadResponse";
516
+ type: '@statelyai.uploadResponse';
508
517
  requestId: string;
509
518
  result: UploadResult;
510
519
  }
@@ -513,50 +522,28 @@ type ClientMessage = InitMessage | SetApiKeyMessage | ProjectInitMessage | Proje
513
522
  /** All messages the viz can send back to a client. */
514
523
  type VizMessage = ReadyMessage | LoadedMessage | ChangeMessage | SaveMessage | ProjectMachineSelectedMessage | RetrievedMessage | ErrorMessage | CapabilityDeniedMessage | UploadRequestMessage;
515
524
  interface RegisterMessage {
516
- type: "@statelyai.register";
517
- protocolVersion?: number;
518
- role: "client" | "viz";
519
- sessionId: string;
525
+ type: '@statelyai.register';
526
+ protocolVersion: number;
527
+ role: 'producer' | 'viewer';
528
+ producerId?: string;
520
529
  metadata?: {
521
530
  name?: string;
522
531
  machineId?: string;
523
532
  };
524
533
  }
525
534
  interface RegisteredMessage {
526
- type: "@statelyai.registered";
527
- protocolVersion?: number;
528
- sessionId: string;
529
- }
530
- /**
531
- * Client → relay: add another sessionId to an existing connection. Used by
532
- * multiplexed clients that want one WebSocket to serve many actor sessions.
533
- * Order of operations for a multiplexed client:
534
- *
535
- * 1. Connect WebSocket
536
- * 2. Send `@statelyai.register { sessionId: primary }`
537
- * 3. Send `@statelyai.addSession { sessionId }` for each additional session
538
- * 4. Send regular messages; each can include an explicit `sessionId` at
539
- * the root to target a specific session (falls back to primary).
540
- */
541
- interface AddSessionMessage {
542
- type: "@statelyai.addSession";
543
- sessionId: string;
544
- metadata?: {
545
- name?: string;
546
- machineId?: string;
547
- };
548
- }
549
- /** Relay → client: acknowledgement that a session was added. */
550
- interface SessionAddedMessage {
551
- type: "@statelyai.sessionAdded";
552
- sessionId: string;
553
- }
554
- /** All session-management messages for the WS relay. */
555
- type SessionMessage = RegisterMessage | RegisteredMessage | AddSessionMessage | SessionAddedMessage;
556
- /** Any valid protocol message. */
557
- type ProtocolMessage = ClientMessage | VizMessage | SessionMessage;
535
+ type: '@statelyai.registered';
536
+ protocolVersion: number;
537
+ producerId?: string;
538
+ }
539
+ /** All registration messages for the WebSocket relay. */
540
+ type SessionMessage = RegisterMessage | RegisteredMessage;
541
+ /** Any valid protocol message. Relays add/consume `producerId` as an envelope. */
542
+ type ProtocolMessage = (ClientMessage | VizMessage | SessionMessage) & {
543
+ producerId?: string;
544
+ };
558
545
  declare const PREFIX = "@statelyai.";
559
546
  /** Current WebSocket inspection protocol version. */
560
- declare const INSPECTION_PROTOCOL_VERSION = 1;
547
+ declare const INSPECTION_PROTOCOL_VERSION = 2;
561
548
  //#endregion
562
- export { ActorSystemEntry, AddSessionMessage, CapabilityDeniedCapability, CapabilityDeniedEvent, CapabilityDeniedMessage, ChangeMessage, ClientMessage, CommentsConfig, EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ErrorMessage, ExportCallOptions, ExportFormat, ExportFormatMap, INSPECTION_PROTOCOL_VERSION, InitMessage, InitOptions, InspectSnapshotMessage, InspectionAction, InspectionSentEvent, InspectionTakenTransition, LoadedMessage, MachineInitOptions, MachineSourceLocations, PREFIX, ProjectEmbedMachine, ProjectInitMessage, ProjectInitOptions, ProjectMachineSelectedMessage, ProjectSelectMachineMessage, ProjectUpdateMessage, ProtocolMessage, ReadOnlyReason, ReadyMessage, RegisterMessage, RegisteredMessage, RetrieveMessage, RetrievedMessage, SaveMessage, SessionAddedMessage, SessionMessage, SetApiKeyMessage, SetModeMessage, SetSettingsMessage, SetThemeMessage, SourceLocation, SourceRange, StateSourceLocation, SystemActorEventMessage, SystemActorRegisteredMessage, SystemActorSnapshotMessage, SystemActorStoppedMessage, SystemInitMessage, SystemSelectActorMessage, ToastMessage, UpdateMessage, UploadCapabilitiesMessage, UploadFileInfo, UploadRequestMessage, UploadResponseMessage, UploadResult, ValidationIssue, VizMessage };
549
+ export { ActorSystemEntry, CapabilityDeniedCapability, CapabilityDeniedEvent, CapabilityDeniedMessage, ChangeMessage, ClientMessage, CommentsConfig, EditorCapabilities, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedMode, ErrorMessage, ExportCallOptions, ExportFormat, ExportFormatMap, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, InitMessage, InitOptions, InspectSnapshotMessage, InspectionAction, InspectionRoomUrls, InspectionSentEvent, InspectionTakenTransition, LoadedMessage, MachineInitOptions, MachineSourceLocations, PREFIX, ProjectEmbedMachine, ProjectInitMessage, ProjectInitOptions, ProjectMachineSelectedMessage, ProjectSelectMachineMessage, ProjectUpdateMessage, ProtocolMessage, ReadOnlyReason, ReadyMessage, RegisterMessage, RegisteredMessage, RetrieveMessage, RetrievedMessage, SaveMessage, SessionMessage, SetApiKeyMessage, SetModeMessage, SetSettingsMessage, SetThemeMessage, SourceLocation, SourceRange, StateSourceLocation, SystemActorEventMessage, SystemActorRegisteredMessage, SystemActorSnapshotMessage, SystemActorStoppedMessage, SystemInitMessage, SystemSelectActorMessage, ToastMessage, UpdateMessage, UploadCapabilitiesMessage, UploadFileInfo, UploadRequestMessage, UploadResponseMessage, UploadResult, ValidationIssue, VizMessage, createInspectionRoomUrls, getInspectionRoomId };
package/dist/protocol.mjs CHANGED
@@ -1,7 +1,38 @@
1
1
  //#region src/protocol.ts
2
+ /** Query parameter carrying the unguessable inspection room capability. */
3
+ const INSPECTION_ROOM_QUERY_PARAM = "r";
4
+ /** Resolve the transport and browser URLs required by the inspection protocol. */
5
+ function createInspectionRoomUrls(options) {
6
+ const relayUrl = new URL(options.url);
7
+ if (relayUrl.protocol !== "ws:" && relayUrl.protocol !== "wss:") throw new Error("Inspection relay URLs must use ws: or wss:.");
8
+ const existingRoomId = relayUrl.searchParams.get(INSPECTION_ROOM_QUERY_PARAM);
9
+ if (existingRoomId && existingRoomId !== options.roomId) throw new Error("Inspection relay URL room does not match roomId.");
10
+ relayUrl.searchParams.set(INSPECTION_ROOM_QUERY_PARAM, options.roomId);
11
+ if (options.inspectorBaseUrl) {
12
+ const inspectorUrl = new URL(options.inspectorBaseUrl);
13
+ inspectorUrl.searchParams.set("ws", relayUrl.toString());
14
+ inspectorUrl.searchParams.set(INSPECTION_ROOM_QUERY_PARAM, options.roomId);
15
+ return {
16
+ roomId: options.roomId,
17
+ relayUrl: relayUrl.toString(),
18
+ inspectorUrl: inspectorUrl.toString()
19
+ };
20
+ }
21
+ const inspectorUrl = new URL(relayUrl);
22
+ inspectorUrl.protocol = relayUrl.protocol === "wss:" ? "https:" : "http:";
23
+ return {
24
+ roomId: options.roomId,
25
+ relayUrl: relayUrl.toString(),
26
+ inspectorUrl: inspectorUrl.toString()
27
+ };
28
+ }
29
+ /** Read a room capability from a conforming relay or inspector URL. */
30
+ function getInspectionRoomId(value) {
31
+ return new URL(value).searchParams.get(INSPECTION_ROOM_QUERY_PARAM)?.trim() || null;
32
+ }
2
33
  const PREFIX = "@statelyai.";
3
34
  /** Current WebSocket inspection protocol version. */
4
- const INSPECTION_PROTOCOL_VERSION = 1;
35
+ const INSPECTION_PROTOCOL_VERSION = 2;
5
36
 
6
37
  //#endregion
7
- export { INSPECTION_PROTOCOL_VERSION, PREFIX };
38
+ export { INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, PREFIX, createInspectionRoomUrls, getInspectionRoomId };
package/dist/relay.d.mts CHANGED
@@ -1,15 +1,14 @@
1
1
  import { ProtocolMessage } from "./protocol.mjs";
2
2
 
3
3
  //#region src/relay.d.ts
4
- type InspectionRelayRole = 'client' | 'viz';
4
+ type InspectionRelayRole = 'producer' | 'viewer';
5
5
  interface InspectionRelayPeer {
6
6
  id: string;
7
7
  role: InspectionRelayRole;
8
- primarySessionId: string;
9
- sessionIds: string[];
8
+ producerId?: string;
10
9
  }
11
10
  interface InspectionRelaySnapshot {
12
- sessions: Record<string, ProtocolMessage[]>;
11
+ producers: Record<string, ProtocolMessage[]>;
13
12
  }
14
13
  type InspectionRelayEffect = {
15
14
  type: 'send';
@@ -23,20 +22,20 @@ interface InspectionRelay {
23
22
  clear(): void;
24
23
  peer(peerId: string): InspectionRelayPeer | undefined;
25
24
  receive(peerId: string, raw: unknown): InspectionRelayEffect[];
26
- snapshot(): InspectionRelaySnapshot;
25
+ snapshot(producerId?: string): InspectionRelaySnapshot;
27
26
  }
28
27
  interface CreateInspectionRelayOptions {
29
28
  snapshot?: InspectionRelaySnapshot;
30
29
  maxReplayMessages?: number;
31
- /** Maximum sessions retained for late-join replay. Default 100. */
32
- maxReplaySessions?: number;
30
+ /** Maximum producers retained for late-join replay. Default 100. */
31
+ maxReplayProducers?: number;
33
32
  }
34
33
  /**
35
- * Runtime-neutral WebSocket inspection room.
34
+ * Runtime-neutral implementation of one inspection room.
36
35
  *
37
- * It owns protocol registration, routing, multiplexed session membership, and
38
- * bounded late-join replay. Node and Durable Object adapters only translate
39
- * `send` effects to their native WebSocket APIs and persist `snapshot()`.
36
+ * The hosting adapter selects the room from the WebSocket URL. This module
37
+ * owns protocol registration, multi-producer/viewer routing, and bounded
38
+ * per-producer replay.
40
39
  */
41
40
  declare function createInspectionRelay(options?: CreateInspectionRelayOptions): InspectionRelay;
42
41
  //#endregion