@statelyai/sdk 0.33.0 → 0.34.0

package/dist/{protocol-CQL9Ubt9.d.mts → protocol-AeHm956D.d.mts}

@@ -1,6 +1,6 @@
-import { i as ProfileManifest } from "./index-DlOZxzrW.mjs";
-import { i as StatelyGraph } from "./graph-CR_g-mOq.mjs";
-import { c as EditorSyncSourceLocation, f as MachineSourceLocations$1, l as EditorSyncSourceRange, t as EditorCapabilities$1, u as EditorSyncStateSourceLocation } from "./editor-sync-types-CPpzTSnT.mjs";
+import { i as ProfileManifest } from "./index-DZivqh0u.mjs";
+import { i as StatelyGraph } from "./graph-Ciocekxl.mjs";
+import { c as EditorSyncSourceLocation, f as MachineSourceLocations$1, l as EditorSyncSourceRange, t as EditorCapabilities$1, u as EditorSyncStateSourceLocation } from "./editor-sync-types-D7YYz6fb.mjs";
 
 //#region src/embedPanel.d.ts
 type EmbedPanelPosition = 'left' | 'right' | 'bottom';
@@ -14,6 +14,11 @@ interface EmbedPanelConfig {
   initiallyOpen?: boolean;
 }
 //#endregion
+//#region src/inspectorSettings.d.ts
+/** Also filters untrusted wire data to the inspection presentation subset. */
+declare function mergeInspectorSettings(previous: InspectorSettings, value: unknown): InspectorSettings;
+declare function resolveInspectorSettings(options: Pick<ViewerOptions<unknown>, 'settings' | 'theme' | 'viewMode'>): InspectorSettings;
+//#endregion
 //#region src/protocol.d.ts
 /** Query parameter carrying the unguessable inspection room capability. */
 declare const INSPECTION_ROOM_QUERY_PARAM = "r";
@@ -345,23 +350,46 @@ declare function isEmbedExampleMachine(value: unknown): value is Record<string,
 declare function isEmbedExample(value: unknown): value is EmbedExample;
 /** Reject malformed host-provided examples before creating an init message. */
 declare function assertEmbedExamples(examples: readonly EmbedExample[] | undefined): void;
-interface MachineInitOptions {
-  machine: unknown;
-  /** Ephemeral, read-only reference documents owned by the embed host. */
+/** Display configuration shared by embeds and inspectors. */
+interface ViewerOptions<Settings = Record<string, unknown>> {
+  /** Ephemeral, read-only reference documents owned by the host. */
   documents?: EmbedDocument[];
-  format?: string;
-  extensions?: EmbedExtensionsManifest;
-  mode?: EmbedMode;
+  panels?: EmbedPanelConfig[];
   theme?: 'light' | 'dark';
+  viewMode?: 'graph' | 'list';
+  settings?: Settings;
   readOnly?: boolean;
-  readOnlyReason?: ReadOnlyReason;
   depth?: number;
   capabilities?: EditorCapabilities;
+}
+/** Inspection only accepts presentation preferences, never authoring settings. */
+interface InspectorSettings {
+  appearance?: {
+    colorMode?: 'light' | 'dark' | 'system';
+  };
+  canvas?: {
+    viewMode?: 'graph' | 'list';
+    showGrid?: boolean;
+    dimUnselected?: boolean;
+    edgeHighlightWidth?: number;
+  };
+}
+/** A viewer mounted and its selected surface is usable (including an empty system). */
+interface InspectorLoadedEvent {
+  producerId?: string;
+}
+interface SystemLoadedMessage extends InspectorLoadedEvent {
+  type: '@statelyai.system.loaded';
+}
+interface MachineInitOptions extends ViewerOptions {
+  machine: unknown;
+  format?: string;
+  extensions?: EmbedExtensionsManifest;
+  mode?: EmbedMode;
+  readOnlyReason?: ReadOnlyReason;
   examples?: readonly EmbedExample[];
-  panels?: EmbedPanelConfig[];
   comments?: CommentsConfig;
   sourceLocations?: MachineSourceLocations;
-  settings?: Record<string, unknown>;
   /**
    * Show a persistent "Save to apply" pill in the embed whenever Viz has
    * local edits that have not yet been saved. Intended for contexts like
@@ -381,27 +409,19 @@ interface MachineInitOptions {
   /** Omit to disable automatic version requests. */
   versionAutoSave?: MachineVersionAutoSaveOptions;
 }
-interface ProjectInitOptions {
+interface ProjectInitOptions extends ViewerOptions {
   machines: ProjectEmbedMachine[];
   /** Optional project-level chrome owned by the embed host. */
   chrome?: {
     /** Reserve a header row above the editor canvas. */header?: boolean;
   };
-  /** Ephemeral, read-only reference documents shared across the project. */
-  documents?: EmbedDocument[];
   currentMachineId?: string;
   mode?: EmbedMode;
-  theme?: 'light' | 'dark';
-  readOnly?: boolean;
   readOnlyReason?: ReadOnlyReason;
-  depth?: number;
-  capabilities?: EditorCapabilities;
   examples?: readonly EmbedExample[];
-  panels?: EmbedPanelConfig[];
   commentsByMachineId?: Record<string, CommentsConfig>;
   projectWorkspace?: ProjectWorkspaceConfig;
   projectWorkspaceOpen?: boolean;
-  settings?: Record<string, unknown>;
   unsavedIndicator?: {
     enabled?: boolean;
     mode?: 'structural' | 'all';
@@ -410,35 +430,14 @@ interface ProjectInitOptions {
   versionAutoSave?: MachineVersionAutoSaveOptions;
 }
 type InitOptions = MachineInitOptions | ProjectInitOptions;
-interface InitMessage {
+interface InitMessage extends MachineInitOptions {
   type: '@statelyai.init';
-  machine: unknown;
-  documents?: EmbedDocument[];
-  format?: string;
-  extensions?: EmbedExtensionsManifest;
-  mode?: EmbedMode;
-  theme?: 'light' | 'dark';
-  readOnly?: boolean;
-  readOnlyReason?: ReadOnlyReason;
-  depth?: number;
-  capabilities?: EditorCapabilities;
-  examples?: readonly EmbedExample[];
-  panels?: EmbedPanelConfig[];
   /** @deprecated Use `panels`. */
   leftPanels?: string[];
   /** @deprecated Use `panels`. */
   rightPanels?: string[];
   /** @deprecated Use `panels[].initiallyOpen`. */
   activePanels?: string[];
-  comments?: CommentsConfig;
-  sourceLocations?: MachineSourceLocations;
-  settings?: Record<string, unknown>;
-  /** Mirror of `InitOptions.unsavedIndicator`. */
-  unsavedIndicator?: {
-    enabled?: boolean;
-    mode?: 'structural' | 'all';
-  };
-  versionAutoSave?: MachineVersionAutoSaveOptions;
 }
 interface SetApiKeyMessage {
   type: '@statelyai.setApiKey';
@@ -468,37 +467,14 @@ interface ClipboardWriteMessage {
   requestId: string;
   text: string;
 }
-interface ProjectInitMessage {
+interface ProjectInitMessage extends ProjectInitOptions {
   type: '@statelyai.project.init';
-  machines: ProjectEmbedMachine[];
-  chrome?: {
-    header?: boolean;
-  };
-  documents?: EmbedDocument[];
-  currentMachineId?: string;
-  mode?: EmbedMode;
-  theme?: 'light' | 'dark';
-  readOnly?: boolean;
-  readOnlyReason?: ReadOnlyReason;
-  depth?: number;
-  capabilities?: EditorCapabilities;
-  examples?: readonly EmbedExample[];
-  panels?: EmbedPanelConfig[];
   /** @deprecated Use `panels`. */
   leftPanels?: string[];
   /** @deprecated Use `panels`. */
   rightPanels?: string[];
   /** @deprecated Use `panels[].initiallyOpen`. */
   activePanels?: string[];
-  commentsByMachineId?: Record<string, CommentsConfig>;
-  projectWorkspace?: ProjectWorkspaceConfig;
-  projectWorkspaceOpen?: boolean;
-  settings?: Record<string, unknown>;
-  unsavedIndicator?: {
-    enabled?: boolean;
-    mode?: 'structural' | 'all';
-  };
-  versionAutoSave?: MachineVersionAutoSaveOptions;
   sessionId?: string;
 }
 interface ProjectUpdateMessage {
@@ -597,7 +573,7 @@ interface InspectionSentEvent {
   delay?: number;
   id?: string;
 }
-interface SystemInitMessage {
+interface SystemInitMessage extends ViewerOptions<InspectorSettings> {
   type: '@statelyai.system.init';
   protocolVersion: number;
   /** All known actors at the moment the system is first streamed. */
@@ -606,13 +582,7 @@ interface SystemInitMessage {
   machines?: Record<string, MachinePayload>;
   /** Actor session id the viz should focus first. Defaults to the root. */
   selectedSessionId?: string;
-  documents?: EmbedDocument[];
   mode?: EmbedMode;
-  theme?: 'light' | 'dark';
-  readOnly?: boolean;
-  depth?: number;
-  capabilities?: EditorCapabilities;
-  panels?: EmbedPanelConfig[];
   /** @deprecated Use `panels`. */
   leftPanels?: string[];
   /** @deprecated Use `panels`. */
@@ -833,7 +803,7 @@ interface ExtensionResultMessage {
 /** All messages a client (embed/inspector) can send to the viz. */
 type ClientMessage = InitMessage | SetApiKeyMessage | EditorHandshakeMessage | SavedMessage | ClipboardReadResponseMessage | ClipboardWriteResponseMessage | ProjectInitMessage | ProjectUpdateMessage | ProjectSelectMachineMessage | ProjectSetWorkspaceOpenMessage | UpdateMessage | SetModeMessage | SetThemeMessage | SetSettingsMessage | RetrieveMessage | ToastMessage | ToastDismissMessage | InspectSnapshotMessage | SystemInitMessage | SystemSelectActorMessage | SystemActorRegisteredMessage | SystemActorEventMessage | SystemActorSnapshotMessage | SystemActorStoppedMessage | UploadCapabilitiesMessage | UploadResponseMessage | ExtensionResultMessage | ErrorMessage;
 /** All messages the viz can send back to a client. */
-type VizMessage = ReadyMessage | LoadedMessage | ChangeMessage | SaveMessage | VersionSaveRequestedMessage | ProjectMachineSelectedMessage | ProjectWorkspaceActionMessage | ProjectWorkspaceOpenChangedMessage | ViewModeChangedMessage | PanelChangedMessage | ModeChangedMessage | RetrievedMessage | ErrorMessage | CapabilityDeniedMessage | ClipboardReadMessage | ClipboardWriteMessage | UploadRequestMessage | ExtensionCallMessage;
+type VizMessage = SystemLoadedMessage | ReadyMessage | LoadedMessage | ChangeMessage | SaveMessage | VersionSaveRequestedMessage | ProjectMachineSelectedMessage | ProjectWorkspaceActionMessage | ProjectWorkspaceOpenChangedMessage | ViewModeChangedMessage | PanelChangedMessage | ModeChangedMessage | RetrievedMessage | ErrorMessage | CapabilityDeniedMessage | ClipboardReadMessage | ClipboardWriteMessage | UploadRequestMessage | ExtensionCallMessage;
 interface InspectionClientMetadata {
   name?: string;
   machineId?: string;
@@ -862,4 +832,4 @@ declare const PREFIX = "@statelyai.";
 /** Current WebSocket inspection protocol version. */
 declare const INSPECTION_PROTOCOL_VERSION = 2;
 //#endregion
-export { ProjectMachineSelectedMessage as $, EmbedPanelConfig as $t, ExtensionCallMessage as A, SystemActorRegisteredMessage as At, InspectionSentEvent as B, UploadRequestMessage as Bt, EmbedFormatManifest as C, SetModeMessage as Ct, ExportCallOptions as D, SourceRange as Dt, ErrorMessage as E, SourceLocation as Et, InitOptions as F, ToastDismissMessage as Ft, MachineSourceLocations as G, ViewModeChangedMessage as Gt, LoadedMessage as H, UploadResult as Ht, InspectSnapshotMessage as I, ToastMessage as It, PREFIX as J, createInspectionActorId as Jt, MachineVersionAutoSaveOptions as K, VizMessage as Kt, InspectionAction as L, UpdateMessage as Lt, INSPECTION_PROTOCOL_VERSION as M, SystemActorStoppedMessage as Mt, INSPECTION_ROOM_QUERY_PARAM as N, SystemInitMessage as Nt, ExportFormat as O, StateSourceLocation as Ot, InitMessage as P, SystemSelectActorMessage as Pt, ProjectInitOptions as Q, isEmbedExampleMachine as Qt, InspectionClientMetadata as R, UploadCapabilitiesMessage as Rt, EmbedExtensionsManifest as S, SetApiKeyMessage as St, ErrorCode as T, SetThemeMessage as Tt, MachineInitOptions as U, ValidationIssue as Ut, InspectionTakenTransition as V, UploadResponseMessage as Vt, MachinePayload as W, VersionSaveRequestedMessage as Wt, ProjectEmbedMachine as X, getInspectionRoomId as Xt, PanelChangedMessage as Y, createInspectionRoomUrls as Yt, ProjectInitMessage as Z, isEmbedExample as Zt, EmbedDocumentLanguage as _, RetrieveMessage as _t, ChangeMessage as a, ProjectWorkspaceActionMessage as at, EmbedEventName as b, SavedMessage as bt, ClipboardReadResponseMessage as c, ProjectWorkspaceMachine as ct, CommentsConfig as d, ProjectWorkspaceProject as dt, EmbedPanelPosition as en, ProjectSelectMachineMessage as et, EMBED_DOCUMENT_LANGUAGES as f, ProtocolMessage as ft, EmbedDocument as g, RegisteredMessage as gt, EditorHandshakeMessage as h, RegisterMessage as ht, CapabilityDeniedMessage as i, ProjectWorkspaceActionIcon as it, ExtensionResultMessage as j, SystemActorSnapshotMessage as jt, ExportFormatMap as k, SystemActorEventMessage as kt, ClipboardWriteMessage as l, ProjectWorkspaceMachineOrigin as lt, EditorCapabilities as m, ReadyMessage as mt, CapabilityDeniedCapability as n, ProjectUpdateMessage as nt, ClientMessage as o, ProjectWorkspaceCapabilities as ot, EMBED_DOCUMENT_LIMITS as p, ReadOnlyReason as pt, ModeChangedMessage as q, assertEmbedExamples as qt, CapabilityDeniedEvent as r, ProjectWorkspaceAction as rt, ClipboardReadMessage as s, ProjectWorkspaceConfig as st, ActorSystemEntry as t, ProjectSetWorkspaceOpenMessage as tt, ClipboardWriteResponseMessage as u, ProjectWorkspaceOpenChangedMessage as ut, EmbedEventHandler as v, RetrievedMessage as vt, EmbedMode as w, SetSettingsMessage as wt, EmbedExample as x, SessionMessage as xt, EmbedEventMap as y, SaveMessage as yt, InspectionRoomUrls as z, UploadFileInfo as zt };
+export { ProjectInitMessage as $, createInspectionRoomUrls as $t, ExtensionCallMessage as A, StateSourceLocation as At, InspectionSentEvent as B, UpdateMessage as Bt, EmbedFormatManifest as C, SessionMessage as Ct, ExportCallOptions as D, SetThemeMessage as Dt, ErrorMessage as E, SetSettingsMessage as Et, InitOptions as F, SystemInitMessage as Ft, MachineInitOptions as G, UploadResult as Gt, InspectorLoadedEvent as H, UploadFileInfo as Ht, InspectSnapshotMessage as I, SystemLoadedMessage as It, MachineVersionAutoSaveOptions as J, ViewModeChangedMessage as Jt, MachinePayload as K, ValidationIssue as Kt, InspectionAction as L, SystemSelectActorMessage as Lt, INSPECTION_PROTOCOL_VERSION as M, SystemActorRegisteredMessage as Mt, INSPECTION_ROOM_QUERY_PARAM as N, SystemActorSnapshotMessage as Nt, ExportFormat as O, SourceLocation as Ot, InitMessage as P, SystemActorStoppedMessage as Pt, ProjectEmbedMachine as Q, createInspectionActorId as Qt, InspectionClientMetadata as R, ToastDismissMessage as Rt, EmbedExtensionsManifest as S, SavedMessage as St, ErrorCode as T, SetModeMessage as Tt, InspectorSettings as U, UploadRequestMessage as Ut, InspectionTakenTransition as V, UploadCapabilitiesMessage as Vt, LoadedMessage as W, UploadResponseMessage as Wt, PREFIX as X, VizMessage as Xt, ModeChangedMessage as Y, ViewerOptions as Yt, PanelChangedMessage as Z, assertEmbedExamples as Zt, EmbedDocumentLanguage as _, RegisterMessage as _t, ChangeMessage as a, EmbedPanelConfig as an, ProjectWorkspaceAction as at, EmbedEventName as b, RetrievedMessage as bt, ClipboardReadResponseMessage as c, ProjectWorkspaceCapabilities as ct, CommentsConfig as d, ProjectWorkspaceMachineOrigin as dt, getInspectionRoomId as en, ProjectInitOptions as et, EMBED_DOCUMENT_LANGUAGES as f, ProjectWorkspaceOpenChangedMessage as ft, EmbedDocument as g, ReadyMessage as gt, EditorHandshakeMessage as h, ReadOnlyReason as ht, CapabilityDeniedMessage as i, resolveInspectorSettings as in, ProjectUpdateMessage as it, ExtensionResultMessage as j, SystemActorEventMessage as jt, ExportFormatMap as k, SourceRange as kt, ClipboardWriteMessage as l, ProjectWorkspaceConfig as lt, EditorCapabilities as m, ProtocolMessage as mt, CapabilityDeniedCapability as n, isEmbedExampleMachine as nn, ProjectSelectMachineMessage as nt, ClientMessage as o, EmbedPanelPosition as on, ProjectWorkspaceActionIcon as ot, EMBED_DOCUMENT_LIMITS as p, ProjectWorkspaceProject as pt, MachineSourceLocations as q, VersionSaveRequestedMessage as qt, CapabilityDeniedEvent as r, mergeInspectorSettings as rn, ProjectSetWorkspaceOpenMessage as rt, ClipboardReadMessage as s, ProjectWorkspaceActionMessage as st, ActorSystemEntry as t, isEmbedExample as tn, ProjectMachineSelectedMessage as tt, ClipboardWriteResponseMessage as u, ProjectWorkspaceMachine as ut, EmbedEventHandler as v, RegisteredMessage as vt, EmbedMode as w, SetApiKeyMessage as wt, EmbedExample as x, SaveMessage as xt, EmbedEventMap as y, RetrieveMessage as yt, InspectionRoomUrls as z, ToastMessage as zt };

package/dist/protocol-BsBGRISR.mjs

@@ -0,0 +1,116 @@
+//#region src/inspectorSettings.ts
+const record = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+/** Also filters untrusted wire data to the inspection presentation subset. */
+function mergeInspectorSettings(previous, value) {
+	const input = record(value);
+	const appearance = record(input.appearance);
+	const canvas = record(input.canvas);
+	const result = {
+		appearance: { ...previous.appearance },
+		canvas: { ...previous.canvas }
+	};
+	if ([
+		"light",
+		"dark",
+		"system"
+	].includes(String(appearance.colorMode))) result.appearance.colorMode = appearance.colorMode;
+	if (canvas.viewMode === "graph" || canvas.viewMode === "list") result.canvas.viewMode = canvas.viewMode;
+	for (const key of ["showGrid", "dimUnselected"]) if (typeof canvas[key] === "boolean") result.canvas[key] = canvas[key];
+	if (typeof canvas.edgeHighlightWidth === "number" && Number.isFinite(canvas.edgeHighlightWidth) && canvas.edgeHighlightWidth >= 0) result.canvas.edgeHighlightWidth = canvas.edgeHighlightWidth;
+	return result;
+}
+function resolveInspectorSettings(options) {
+	return mergeInspectorSettings(mergeInspectorSettings({}, options.settings), {
+		appearance: { colorMode: options.theme },
+		canvas: { viewMode: options.viewMode }
+	});
+}
+
+//#endregion
+//#region src/protocol.ts
+/** Query parameter carrying the unguessable inspection room capability. */
+const INSPECTION_ROOM_QUERY_PARAM = "r";
+/**
+* Create the room-global identity for one producer-local actor session.
+* Runtime and producer-resolved session ids may use different uniqueness
+* domains; the producer id supplies a stable room namespace.
+*/
+function createInspectionActorId(producerId, sessionId) {
+	return `${encodeURIComponent(producerId)}:${encodeURIComponent(sessionId)}`;
+}
+/** Resolve the transport and browser URLs required by the inspection protocol. */
+function createInspectionRoomUrls(options) {
+	const relayUrl = new URL(options.url);
+	if (relayUrl.protocol !== "ws:" && relayUrl.protocol !== "wss:") throw new Error("Inspection relay URLs must use ws: or wss:.");
+	const existingRoomId = relayUrl.searchParams.get(INSPECTION_ROOM_QUERY_PARAM);
+	if (existingRoomId && existingRoomId !== options.roomId) throw new Error("Inspection relay URL room does not match roomId.");
+	relayUrl.searchParams.set(INSPECTION_ROOM_QUERY_PARAM, options.roomId);
+	if (options.inspectorBaseUrl) {
+		const inspectorUrl = new URL(options.inspectorBaseUrl);
+		inspectorUrl.searchParams.set("ws", relayUrl.toString());
+		inspectorUrl.searchParams.set(INSPECTION_ROOM_QUERY_PARAM, options.roomId);
+		return {
+			roomId: options.roomId,
+			relayUrl: relayUrl.toString(),
+			inspectorUrl: inspectorUrl.toString()
+		};
+	}
+	const inspectorUrl = new URL(relayUrl);
+	inspectorUrl.protocol = relayUrl.protocol === "wss:" ? "https:" : "http:";
+	return {
+		roomId: options.roomId,
+		relayUrl: relayUrl.toString(),
+		inspectorUrl: inspectorUrl.toString()
+	};
+}
+/** Read a room capability from a conforming relay or inspector URL. */
+function getInspectionRoomId(value) {
+	return new URL(value).searchParams.get(INSPECTION_ROOM_QUERY_PARAM)?.trim() || null;
+}
+const EMBED_DOCUMENT_LANGUAGES = [
+	"markdown",
+	"typescript",
+	"javascript",
+	"json",
+	"xml",
+	"mermaid",
+	"text"
+];
+const EMBED_DOCUMENT_LIMITS = {
+	maxDocuments: 100,
+	maxDocumentLength: 512 * 1024,
+	maxTotalLength: 2 * 1024 * 1024
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOwn(value, key) {
+	return Object.prototype.hasOwnProperty.call(value, key);
+}
+/** Check whether an example machine has a shape supported by the editor. */
+function isEmbedExampleMachine(value) {
+	if (!isRecord(value)) return false;
+	if (hasOwn(value, "rootNode")) return isRecord(value.rootNode);
+	if (hasOwn(value, "root") && hasOwn(value, "states")) return isRecord(value.states);
+	if (hasOwn(value, "states")) return isRecord(value.states);
+	if (hasOwn(value, "States")) return isRecord(value.States);
+	return hasOwn(value, "nodes") && Array.isArray(value.nodes) && hasOwn(value, "edges") && Array.isArray(value.edges) && hasOwn(value, "data") && isRecord(value.data);
+}
+/** Check whether an unknown value is a valid serialized embed example. */
+function isEmbedExample(value) {
+	return isRecord(value) && typeof value.id === "string" && typeof value.title === "string" && typeof value.description === "string" && typeof value.category === "string" && isEmbedExampleMachine(value.machine);
+}
+/** Reject malformed host-provided examples before creating an init message. */
+function assertEmbedExamples(examples) {
+	if (examples === void 0) return;
+	if (!Array.isArray(examples)) throw new TypeError("Embed examples must be an array.");
+	examples.forEach((example, index) => {
+		if (!isEmbedExample(example)) throw new TypeError(`Invalid embed example at index ${index}.`);
+	});
+}
+const PREFIX = "@statelyai.";
+/** Current WebSocket inspection protocol version. */
+const INSPECTION_PROTOCOL_VERSION = 2;
+
+//#endregion
+export { PREFIX as a, createInspectionRoomUrls as c, isEmbedExampleMachine as d, mergeInspectorSettings as f, INSPECTION_ROOM_QUERY_PARAM as i, getInspectionRoomId as l, EMBED_DOCUMENT_LIMITS as n, assertEmbedExamples as o, resolveInspectorSettings as p, INSPECTION_PROTOCOL_VERSION as r, createInspectionActorId as s, EMBED_DOCUMENT_LANGUAGES as t, isEmbedExample as u };

package/dist/protocol.d.mts

@@ -1,2 +1,2 @@
-import { $ as ProjectMachineSelectedMessage, $t as EmbedPanelConfig, A as ExtensionCallMessage, At as SystemActorRegisteredMessage, B as InspectionSentEvent, Bt as UploadRequestMessage, C as EmbedFormatManifest, Ct as SetModeMessage, D as ExportCallOptions, Dt as SourceRange, E as ErrorMessage, Et as SourceLocation, F as InitOptions, Ft as ToastDismissMessage, G as MachineSourceLocations, Gt as ViewModeChangedMessage, H as LoadedMessage, Ht as UploadResult, I as InspectSnapshotMessage, It as ToastMessage, J as PREFIX, Jt as createInspectionActorId, K as MachineVersionAutoSaveOptions, Kt as VizMessage, L as InspectionAction, Lt as UpdateMessage, M as INSPECTION_PROTOCOL_VERSION, Mt as SystemActorStoppedMessage, N as INSPECTION_ROOM_QUERY_PARAM, Nt as SystemInitMessage, O as ExportFormat, Ot as StateSourceLocation, P as InitMessage, Pt as SystemSelectActorMessage, Q as ProjectInitOptions, Qt as isEmbedExampleMachine, R as InspectionClientMetadata, Rt as UploadCapabilitiesMessage, S as EmbedExtensionsManifest, St as SetApiKeyMessage, T as ErrorCode, Tt as SetThemeMessage, U as MachineInitOptions, Ut as ValidationIssue, V as InspectionTakenTransition, Vt as UploadResponseMessage, W as MachinePayload, Wt as VersionSaveRequestedMessage, X as ProjectEmbedMachine, Xt as getInspectionRoomId, Y as PanelChangedMessage, Yt as createInspectionRoomUrls, Z as ProjectInitMessage, Zt as isEmbedExample, _ as EmbedDocumentLanguage, _t as RetrieveMessage, a as ChangeMessage, at as ProjectWorkspaceActionMessage, b as EmbedEventName, bt as SavedMessage, c as ClipboardReadResponseMessage, ct as ProjectWorkspaceMachine, d as CommentsConfig, dt as ProjectWorkspaceProject, en as EmbedPanelPosition, et as ProjectSelectMachineMessage, f as EMBED_DOCUMENT_LANGUAGES, ft as ProtocolMessage, g as EmbedDocument, gt as RegisteredMessage, h as EditorHandshakeMessage, ht as RegisterMessage, i as CapabilityDeniedMessage, it as ProjectWorkspaceActionIcon, j as ExtensionResultMessage, jt as SystemActorSnapshotMessage, k as ExportFormatMap, kt as SystemActorEventMessage, l as ClipboardWriteMessage, lt as ProjectWorkspaceMachineOrigin, m as EditorCapabilities, mt as ReadyMessage, n as CapabilityDeniedCapability, nt as ProjectUpdateMessage, o as ClientMessage, ot as ProjectWorkspaceCapabilities, p as EMBED_DOCUMENT_LIMITS, pt as ReadOnlyReason, q as ModeChangedMessage, qt as assertEmbedExamples, r as CapabilityDeniedEvent, rt as ProjectWorkspaceAction, s as ClipboardReadMessage, st as ProjectWorkspaceConfig, t as ActorSystemEntry, tt as ProjectSetWorkspaceOpenMessage, u as ClipboardWriteResponseMessage, ut as ProjectWorkspaceOpenChangedMessage, v as EmbedEventHandler, vt as RetrievedMessage, w as EmbedMode, wt as SetSettingsMessage, x as EmbedExample, xt as SessionMessage, y as EmbedEventMap, yt as SaveMessage, z as InspectionRoomUrls, zt as UploadFileInfo } from "./protocol-CQL9Ubt9.mjs";
-export { ActorSystemEntry, CapabilityDeniedCapability, CapabilityDeniedEvent, CapabilityDeniedMessage, ChangeMessage, ClientMessage, ClipboardReadMessage, ClipboardReadResponseMessage, ClipboardWriteMessage, ClipboardWriteResponseMessage, CommentsConfig, EMBED_DOCUMENT_LANGUAGES, EMBED_DOCUMENT_LIMITS, EditorCapabilities, EditorHandshakeMessage, EmbedDocument, EmbedDocumentLanguage, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedExample, EmbedExtensionsManifest, EmbedFormatManifest, EmbedMode, EmbedPanelConfig, EmbedPanelPosition, ErrorCode, ErrorMessage, ExportCallOptions, ExportFormat, ExportFormatMap, ExtensionCallMessage, ExtensionResultMessage, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, InitMessage, InitOptions, InspectSnapshotMessage, InspectionAction, InspectionClientMetadata, InspectionRoomUrls, InspectionSentEvent, InspectionTakenTransition, LoadedMessage, MachineInitOptions, MachinePayload, MachineSourceLocations, MachineVersionAutoSaveOptions, ModeChangedMessage, PREFIX, PanelChangedMessage, ProjectEmbedMachine, ProjectInitMessage, ProjectInitOptions, ProjectMachineSelectedMessage, ProjectSelectMachineMessage, ProjectSetWorkspaceOpenMessage, ProjectUpdateMessage, ProjectWorkspaceAction, ProjectWorkspaceActionIcon, ProjectWorkspaceActionMessage, ProjectWorkspaceCapabilities, ProjectWorkspaceConfig, ProjectWorkspaceMachine, ProjectWorkspaceMachineOrigin, ProjectWorkspaceOpenChangedMessage, ProjectWorkspaceProject, ProtocolMessage, ReadOnlyReason, ReadyMessage, RegisterMessage, RegisteredMessage, RetrieveMessage, RetrievedMessage, SaveMessage, SavedMessage, SessionMessage, SetApiKeyMessage, SetModeMessage, SetSettingsMessage, SetThemeMessage, SourceLocation, SourceRange, StateSourceLocation, SystemActorEventMessage, SystemActorRegisteredMessage, SystemActorSnapshotMessage, SystemActorStoppedMessage, SystemInitMessage, SystemSelectActorMessage, ToastDismissMessage, ToastMessage, UpdateMessage, UploadCapabilitiesMessage, UploadFileInfo, UploadRequestMessage, UploadResponseMessage, UploadResult, ValidationIssue, VersionSaveRequestedMessage, ViewModeChangedMessage, VizMessage, assertEmbedExamples, createInspectionActorId, createInspectionRoomUrls, getInspectionRoomId, isEmbedExample, isEmbedExampleMachine };
+import { $ as ProjectInitMessage, $t as createInspectionRoomUrls, A as ExtensionCallMessage, At as StateSourceLocation, B as InspectionSentEvent, Bt as UpdateMessage, C as EmbedFormatManifest, Ct as SessionMessage, D as ExportCallOptions, Dt as SetThemeMessage, E as ErrorMessage, Et as SetSettingsMessage, F as InitOptions, Ft as SystemInitMessage, G as MachineInitOptions, Gt as UploadResult, H as InspectorLoadedEvent, Ht as UploadFileInfo, I as InspectSnapshotMessage, It as SystemLoadedMessage, J as MachineVersionAutoSaveOptions, Jt as ViewModeChangedMessage, K as MachinePayload, Kt as ValidationIssue, L as InspectionAction, Lt as SystemSelectActorMessage, M as INSPECTION_PROTOCOL_VERSION, Mt as SystemActorRegisteredMessage, N as INSPECTION_ROOM_QUERY_PARAM, Nt as SystemActorSnapshotMessage, O as ExportFormat, Ot as SourceLocation, P as InitMessage, Pt as SystemActorStoppedMessage, Q as ProjectEmbedMachine, Qt as createInspectionActorId, R as InspectionClientMetadata, Rt as ToastDismissMessage, S as EmbedExtensionsManifest, St as SavedMessage, T as ErrorCode, Tt as SetModeMessage, U as InspectorSettings, Ut as UploadRequestMessage, V as InspectionTakenTransition, Vt as UploadCapabilitiesMessage, W as LoadedMessage, Wt as UploadResponseMessage, X as PREFIX, Xt as VizMessage, Y as ModeChangedMessage, Yt as ViewerOptions, Z as PanelChangedMessage, Zt as assertEmbedExamples, _ as EmbedDocumentLanguage, _t as RegisterMessage, a as ChangeMessage, an as EmbedPanelConfig, at as ProjectWorkspaceAction, b as EmbedEventName, bt as RetrievedMessage, c as ClipboardReadResponseMessage, ct as ProjectWorkspaceCapabilities, d as CommentsConfig, dt as ProjectWorkspaceMachineOrigin, en as getInspectionRoomId, et as ProjectInitOptions, f as EMBED_DOCUMENT_LANGUAGES, ft as ProjectWorkspaceOpenChangedMessage, g as EmbedDocument, gt as ReadyMessage, h as EditorHandshakeMessage, ht as ReadOnlyReason, i as CapabilityDeniedMessage, in as resolveInspectorSettings, it as ProjectUpdateMessage, j as ExtensionResultMessage, jt as SystemActorEventMessage, k as ExportFormatMap, kt as SourceRange, l as ClipboardWriteMessage, lt as ProjectWorkspaceConfig, m as EditorCapabilities, mt as ProtocolMessage, n as CapabilityDeniedCapability, nn as isEmbedExampleMachine, nt as ProjectSelectMachineMessage, o as ClientMessage, on as EmbedPanelPosition, ot as ProjectWorkspaceActionIcon, p as EMBED_DOCUMENT_LIMITS, pt as ProjectWorkspaceProject, q as MachineSourceLocations, qt as VersionSaveRequestedMessage, r as CapabilityDeniedEvent, rn as mergeInspectorSettings, rt as ProjectSetWorkspaceOpenMessage, s as ClipboardReadMessage, st as ProjectWorkspaceActionMessage, t as ActorSystemEntry, tn as isEmbedExample, tt as ProjectMachineSelectedMessage, u as ClipboardWriteResponseMessage, ut as ProjectWorkspaceMachine, v as EmbedEventHandler, vt as RegisteredMessage, w as EmbedMode, wt as SetApiKeyMessage, x as EmbedExample, xt as SaveMessage, y as EmbedEventMap, yt as RetrieveMessage, z as InspectionRoomUrls, zt as ToastMessage } from "./protocol-AeHm956D.mjs";
+export { ActorSystemEntry, CapabilityDeniedCapability, CapabilityDeniedEvent, CapabilityDeniedMessage, ChangeMessage, ClientMessage, ClipboardReadMessage, ClipboardReadResponseMessage, ClipboardWriteMessage, ClipboardWriteResponseMessage, CommentsConfig, EMBED_DOCUMENT_LANGUAGES, EMBED_DOCUMENT_LIMITS, EditorCapabilities, EditorHandshakeMessage, EmbedDocument, EmbedDocumentLanguage, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedExample, EmbedExtensionsManifest, EmbedFormatManifest, EmbedMode, EmbedPanelConfig, EmbedPanelPosition, ErrorCode, ErrorMessage, ExportCallOptions, ExportFormat, ExportFormatMap, ExtensionCallMessage, ExtensionResultMessage, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, InitMessage, InitOptions, InspectSnapshotMessage, InspectionAction, InspectionClientMetadata, InspectionRoomUrls, InspectionSentEvent, InspectionTakenTransition, InspectorLoadedEvent, InspectorSettings, LoadedMessage, MachineInitOptions, MachinePayload, MachineSourceLocations, MachineVersionAutoSaveOptions, ModeChangedMessage, PREFIX, PanelChangedMessage, ProjectEmbedMachine, ProjectInitMessage, ProjectInitOptions, ProjectMachineSelectedMessage, ProjectSelectMachineMessage, ProjectSetWorkspaceOpenMessage, ProjectUpdateMessage, ProjectWorkspaceAction, ProjectWorkspaceActionIcon, ProjectWorkspaceActionMessage, ProjectWorkspaceCapabilities, ProjectWorkspaceConfig, ProjectWorkspaceMachine, ProjectWorkspaceMachineOrigin, ProjectWorkspaceOpenChangedMessage, ProjectWorkspaceProject, ProtocolMessage, ReadOnlyReason, ReadyMessage, RegisterMessage, RegisteredMessage, RetrieveMessage, RetrievedMessage, SaveMessage, SavedMessage, SessionMessage, SetApiKeyMessage, SetModeMessage, SetSettingsMessage, SetThemeMessage, SourceLocation, SourceRange, StateSourceLocation, SystemActorEventMessage, SystemActorRegisteredMessage, SystemActorSnapshotMessage, SystemActorStoppedMessage, SystemInitMessage, SystemLoadedMessage, SystemSelectActorMessage, ToastDismissMessage, ToastMessage, UpdateMessage, UploadCapabilitiesMessage, UploadFileInfo, UploadRequestMessage, UploadResponseMessage, UploadResult, ValidationIssue, VersionSaveRequestedMessage, ViewModeChangedMessage, ViewerOptions, VizMessage, assertEmbedExamples, createInspectionActorId, createInspectionRoomUrls, getInspectionRoomId, isEmbedExample, isEmbedExampleMachine, mergeInspectorSettings, resolveInspectorSettings };

package/dist/protocol.mjs

@@ -1,87 +1,3 @@
-//#region src/protocol.ts
-/** Query parameter carrying the unguessable inspection room capability. */
-const INSPECTION_ROOM_QUERY_PARAM = "r";
-/**
-* Create the room-global identity for one producer-local actor session.
-* Runtime and producer-resolved session ids may use different uniqueness
-* domains; the producer id supplies a stable room namespace.
-*/
-function createInspectionActorId(producerId, sessionId) {
-	return `${encodeURIComponent(producerId)}:${encodeURIComponent(sessionId)}`;
-}
-/** Resolve the transport and browser URLs required by the inspection protocol. */
-function createInspectionRoomUrls(options) {
-	const relayUrl = new URL(options.url);
-	if (relayUrl.protocol !== "ws:" && relayUrl.protocol !== "wss:") throw new Error("Inspection relay URLs must use ws: or wss:.");
-	const existingRoomId = relayUrl.searchParams.get(INSPECTION_ROOM_QUERY_PARAM);
-	if (existingRoomId && existingRoomId !== options.roomId) throw new Error("Inspection relay URL room does not match roomId.");
-	relayUrl.searchParams.set(INSPECTION_ROOM_QUERY_PARAM, options.roomId);
-	if (options.inspectorBaseUrl) {
-		const inspectorUrl = new URL(options.inspectorBaseUrl);
-		inspectorUrl.searchParams.set("ws", relayUrl.toString());
-		inspectorUrl.searchParams.set(INSPECTION_ROOM_QUERY_PARAM, options.roomId);
-		return {
-			roomId: options.roomId,
-			relayUrl: relayUrl.toString(),
-			inspectorUrl: inspectorUrl.toString()
-		};
-	}
-	const inspectorUrl = new URL(relayUrl);
-	inspectorUrl.protocol = relayUrl.protocol === "wss:" ? "https:" : "http:";
-	return {
-		roomId: options.roomId,
-		relayUrl: relayUrl.toString(),
-		inspectorUrl: inspectorUrl.toString()
-	};
-}
-/** Read a room capability from a conforming relay or inspector URL. */
-function getInspectionRoomId(value) {
-	return new URL(value).searchParams.get(INSPECTION_ROOM_QUERY_PARAM)?.trim() || null;
-}
-const EMBED_DOCUMENT_LANGUAGES = [
-	"markdown",
-	"typescript",
-	"javascript",
-	"json",
-	"xml",
-	"mermaid",
-	"text"
-];
-const EMBED_DOCUMENT_LIMITS = {
-	maxDocuments: 100,
-	maxDocumentLength: 512 * 1024,
-	maxTotalLength: 2 * 1024 * 1024
-};
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function hasOwn(value, key) {
-	return Object.prototype.hasOwnProperty.call(value, key);
-}
-/** Check whether an example machine has a shape supported by the editor. */
-function isEmbedExampleMachine(value) {
-	if (!isRecord(value)) return false;
-	if (hasOwn(value, "rootNode")) return isRecord(value.rootNode);
-	if (hasOwn(value, "root") && hasOwn(value, "states")) return isRecord(value.states);
-	if (hasOwn(value, "states")) return isRecord(value.states);
-	if (hasOwn(value, "States")) return isRecord(value.States);
-	return hasOwn(value, "nodes") && Array.isArray(value.nodes) && hasOwn(value, "edges") && Array.isArray(value.edges) && hasOwn(value, "data") && isRecord(value.data);
-}
-/** Check whether an unknown value is a valid serialized embed example. */
-function isEmbedExample(value) {
-	return isRecord(value) && typeof value.id === "string" && typeof value.title === "string" && typeof value.description === "string" && typeof value.category === "string" && isEmbedExampleMachine(value.machine);
-}
-/** Reject malformed host-provided examples before creating an init message. */
-function assertEmbedExamples(examples) {
-	if (examples === void 0) return;
-	if (!Array.isArray(examples)) throw new TypeError("Embed examples must be an array.");
-	examples.forEach((example, index) => {
-		if (!isEmbedExample(example)) throw new TypeError(`Invalid embed example at index ${index}.`);
-	});
-}
-const PREFIX = "@statelyai.";
-/** Current WebSocket inspection protocol version. */
-const INSPECTION_PROTOCOL_VERSION = 2;
+import { a as PREFIX, c as createInspectionRoomUrls, d as isEmbedExampleMachine, f as mergeInspectorSettings, i as INSPECTION_ROOM_QUERY_PARAM, l as getInspectionRoomId, n as EMBED_DOCUMENT_LIMITS, o as assertEmbedExamples, p as resolveInspectorSettings, r as INSPECTION_PROTOCOL_VERSION, s as createInspectionActorId, t as EMBED_DOCUMENT_LANGUAGES, u as isEmbedExample } from "./protocol-BsBGRISR.mjs";
 
-//#endregion
-export { EMBED_DOCUMENT_LANGUAGES, EMBED_DOCUMENT_LIMITS, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, PREFIX, assertEmbedExamples, createInspectionActorId, createInspectionRoomUrls, getInspectionRoomId, isEmbedExample, isEmbedExampleMachine };
+export { EMBED_DOCUMENT_LANGUAGES, EMBED_DOCUMENT_LIMITS, INSPECTION_PROTOCOL_VERSION, INSPECTION_ROOM_QUERY_PARAM, PREFIX, assertEmbedExamples, createInspectionActorId, createInspectionRoomUrls, getInspectionRoomId, isEmbedExample, isEmbedExampleMachine, mergeInspectorSettings, resolveInspectorSettings };

package/dist/relay.d.mts

@@ -1,4 +1,4 @@
-import { ft as ProtocolMessage } from "./protocol-CQL9Ubt9.mjs";
+import { mt as ProtocolMessage } from "./protocol-AeHm956D.mjs";
 
 //#region src/relay.d.ts
 type InspectionRelayRole = 'producer' | 'viewer';

package/dist/relay.mjs

@@ -1,4 +1,4 @@
-import { INSPECTION_PROTOCOL_VERSION, PREFIX } from "./protocol.mjs";
+import { a as PREFIX, f as mergeInspectorSettings, p as resolveInspectorSettings, r as INSPECTION_PROTOCOL_VERSION } from "./protocol-BsBGRISR.mjs";
 
 //#region src/relay.ts
 const REPLAYABLE_MESSAGE_TYPES = new Set([
@@ -8,15 +8,17 @@ const REPLAYABLE_MESSAGE_TYPES = new Set([
 	"@statelyai.system.actorRegistered",
 	"@statelyai.system.actorEvent",
 	"@statelyai.system.actorSnapshot",
-	"@statelyai.system.actorStopped"
+	"@statelyai.system.actorStopped",
+	"@statelyai.setSettings",
+	"@statelyai.system.selectActor"
 ]);
 const FORWARD_ONLY_MESSAGE_TYPES = new Set([
-	"@statelyai.system.selectActor",
 	"@statelyai.retrieve",
 	"@statelyai.retrieved",
 	"@statelyai.error",
 	"@statelyai.ready",
 	"@statelyai.loaded",
+	"@statelyai.system.loaded",
 	"@statelyai.capabilityDenied",
 	"@statelyai.register",
 	"@statelyai.registered"
@@ -39,6 +41,7 @@ function validationError(message) {
 	if (!isSupportedMessageType(message.type)) return `Unsupported inspection message type ${String(message.type)}`;
 	const hasString = (key) => typeof message[key] === "string" && message[key] !== "";
 	switch (message.type) {
+		case "@statelyai.setSettings": return message.settings && typeof message.settings === "object" && !Array.isArray(message.settings) ? null : "setSettings requires a settings object";
 		case "@statelyai.system.init": return message.protocolVersion === INSPECTION_PROTOCOL_VERSION && Array.isArray(message.actors) ? null : "system.init requires the current protocolVersion and actors array";
 		case "@statelyai.system.selectActor":
 		case "@statelyai.system.actorStopped": return hasString("sessionId") ? null : `${message.type} requires sessionId`;
@@ -61,6 +64,23 @@ function errorMessage(code, message) {
 function compactReplay(replay, message, max) {
 	const record = message;
 	const type = record.type;
+	if (type === "@statelyai.setSettings" || type === "@statelyai.system.selectActor") {
+		const index = replay.findIndex((entry) => entry.type === "@statelyai.system.init");
+		const init = replay[index];
+		if (init?.type === "@statelyai.system.init") {
+			if (type === "@statelyai.setSettings") {
+				const { theme: _theme, viewMode: _viewMode, ...rest } = init;
+				replay[index] = {
+					...rest,
+					settings: mergeInspectorSettings(resolveInspectorSettings(init), record.settings)
+				};
+			} else replay[index] = {
+				...init,
+				selectedSessionId: record.sessionId
+			};
+			return;
+		}
+	}
 	if (type === "@statelyai.system.init") for (let index = replay.length - 1; index >= 0; index--) {
 		const replayType = replay[index].type;
 		if (replayType === "@statelyai.system.init" || replayType.startsWith("@statelyai.system.actor")) replay.splice(index, 1);

package/dist/{studio-rSI54Ese.mjs → studio-BZP6DaIO.mjs}

@@ -145,15 +145,11 @@ const entitlementsResultSchema = object({
 	}).nullable(),
 	entitlements: array(string())
 });
-const projectSummarySchema = object({
-	projectId: string(),
-	projectVersionId: string(),
-	name: string(),
-	description: string().nullable(),
-	visibility: projectVisibilitySchema,
-	createdAt: string(),
-	updatedAt: string()
-});
+/**
+* Which editor format a machine's stored definition is in: `digraph` is the
+* original (legacy) editor's format, `xgraph` the current one.
+*/
+const machineDefinitionFormatSchema = _enum(["digraph", "xgraph"]);
 /**
 * `name` and `updatedAt` are optional: some upstream project envelopes only
 * return machine ids. Providers that can supply them cheaply should.
@@ -161,13 +157,31 @@ const projectSummarySchema = object({
 const projectMachineSummarySchema = object({
 	machineId: string(),
 	name: string().optional(),
-	updatedAt: string().optional()
+	updatedAt: string().optional(),
+	format: machineDefinitionFormatSchema.optional()
+});
+/**
+* A project list row. It carries the project's machine roster, not just its
+* metadata, so a client can mount a whole workspace from one `projects.list`
+* response and fetch definitions lazily.
+*/
+const projectSummarySchema = object({
+	projectId: string(),
+	projectVersionId: string(),
+	name: string(),
+	description: string().nullable(),
+	visibility: projectVisibilitySchema,
+	createdAt: string(),
+	updatedAt: string(),
+	rootMachineId: string().nullable().optional(),
+	machines: array(projectMachineSummarySchema).optional(),
+	permissions: object({ canEdit: boolean() }).optional(),
+	allowedVisibility: array(projectVisibilitySchema).optional()
 });
 const projectSchema = projectSummarySchema.extend({
 	rootMachineId: string().nullable(),
 	machines: array(projectMachineSummarySchema),
-	permissions: object({ canEdit: boolean() }),
-	allowedVisibility: array(projectVisibilitySchema).optional()
+	permissions: object({ canEdit: boolean() })
 });
 const machineSchema = object({
 	machineId: string(),
@@ -177,7 +191,8 @@ const machineSchema = object({
 	definition: unknown(),
 	graph: xgraphSchema.optional(),
 	createdAt: string().optional(),
-	updatedAt: string().optional()
+	updatedAt: string().optional(),
+	format: machineDefinitionFormatSchema.optional()
 });
 const machineVersionSchema = object({
 	machineVersionId: string(),
@@ -186,7 +201,8 @@ const machineVersionSchema = object({
 	name: string(),
 	definition: unknown(),
 	createdAt: string(),
-	updatedAt: string()
+	updatedAt: string(),
+	format: machineDefinitionFormatSchema.optional()
 });
 /** Version-history row without the definition payload. */
 const machineVersionSummarySchema = object({
@@ -197,7 +213,8 @@ const machineVersionSummarySchema = object({
 	status: string(),
 	parentVersionId: string().nullable(),
 	createdAt: string(),
-	updatedAt: string()
+	updatedAt: string(),
+	format: machineDefinitionFormatSchema.optional()
 });
 /** Result of converting a machine's stored definition to XGraph in place. */
 const machinesConvertResultSchema = object({
@@ -249,6 +266,18 @@ const machinesRestoreLegacyResultSchema = object({
 		name: string().nullable()
 	})
 });
+/**
+* Result of restoring a machine to one of its own versions.
+*
+* `capturedVersion` is the new version holding the machine's *pre-restore*
+* definition, so the restore itself is undoable. It is `null` when the restore
+* was a no-op (the machine already held that version's definition), which is
+* the signal that no history row was added.
+*/
+const machinesRestoreVersionResultSchema = object({
+	machine: machineSchema,
+	capturedVersion: machineVersionSummarySchema.nullable()
+});
 const extractedMachinesSchema = object({ machines: array(object({
 	config: record(string(), unknown()),
 	machineIndex: number().int().nonnegative().optional()
@@ -306,6 +335,7 @@ const machinesRestoreLegacyRequestSchema = object({
 	expectedUpdatedAt: string().min(1),
 	reason: string().optional()
 });
+const machinesRestoreVersionRequestSchema = object({ expectedUpdatedAt: string().min(1).optional() });
 const codeExtractMachinesRequestSchema = object({
 	code: string().min(1),
 	xstateVersion: xstateVersionSchema.optional()
@@ -328,6 +358,7 @@ const machinesConvertDefinitionResponseSchema = machinesConvertResultSchema;
 const machinesForkResponseSchema = machinesForkResultSchema;
 const machinesGetLegacyVersionResponseSchema = machineLegacyVersionSchema;
 const machinesRestoreLegacyResponseSchema = machinesRestoreLegacyResultSchema;
+const machinesRestoreVersionResponseSchema = machinesRestoreVersionResultSchema;
 const codeExtractMachinesResponseSchema = extractedMachinesSchema;
 /**
 * Request/response schema pairs keyed by resource capability name. Kept here
@@ -376,6 +407,10 @@ const resourceOperationSchemas = {
 	"machines.restoreLegacy": {
 		request: machinesRestoreLegacyRequestSchema,
 		response: machinesRestoreLegacyResponseSchema
+	},
+	"machines.restoreVersion": {
+		request: machinesRestoreVersionRequestSchema,
+		response: machinesRestoreVersionResponseSchema
 	}
 };
 /** Provider-independent operations implemented by this repository. */