@powerhousedao/powerhouse-vetra-packages 6.2.2-dev.42 → 6.2.2-dev.44

package/dist/node/{editor-Cr-mNQca.mjs → editor-ClZqmnoh.mjs}

@@ -1,13 +1,14 @@
-import { E as $ZodError, T as parseAsync, a as snakeCase, h as object, n as constantCase, p as literal, r as pascalCase, v as string, w as parse, x as url, y as union } from "./dist-DT7jI9ol.mjs";
-import { $ as generateId, B as setModelId, D as deleteModule, F as setAuthorName, G as setOperationErrorName, H as setModuleName, I as setAuthorWebsite, J as setStateSchema, K as setOperationName, L as setInitialState, O as deleteOperation, R as setModelDescription, V as setModelName, W as setOperationDescription, h as addOperationError, k as deleteOperationError, m as addOperation, p as addModule, q as setOperationSchema, z as setModelExtension } from "./document-drive-CI0J7nMj.mjs";
-import { _ as Primitive, c as Controller, d as get, f as set, i as DocumentToolbar, l as FormProvider, m as useFormContext, p as useForm, u as appendErrors, v as Slot } from "./connect-wMkkAckX.mjs";
+import { E as $ZodError, T as parseAsync, a as snakeCase, h as object, n as constantCase, p as literal, r as pascalCase, v as string, w as parse$1, x as url, y as union } from "./dist-DT7jI9ol.mjs";
+import { $ as setOperationSchema, G as setModelExtension, H as setAuthorWebsite, J as setModuleName, K as setModelId, M as deleteModule, N as deleteOperation, P as deleteOperationError, Q as setOperationName, U as setInitialState, V as setAuthorName, W as setModelDescription, X as setOperationDescription, Z as setOperationErrorName, _ as addOperationError, at as generateId, et as setStateSchema, g as addOperation, h as addModule, q as setModelName, z as releaseNewVersion } from "./document-drive-DrBAR9as.mjs";
+import { t as require_graphql } from "./graphql-BfAoPeWM.mjs";
+import { _ as Modal, a as DocumentToolbar, b as Primitive, c as ModalButton, d as FormProvider, f as appendErrors, g as useFormContext, h as useForm, m as set, p as get, r as ConnectSelect, u as Controller, x as Slot } from "./connect-CkBYxX_q.mjs";
 import { w as twMerge } from "./dist-CzYOpeXN.mjs";
-import { M as usePHToast, p as useSelectedDocumentOfType, v as useSetPHDocumentEditorConfig } from "./dist-CUHBOv3P.mjs";
-import { a as handleModelNameChange, c as makeEmptyOperationSchema, d as makeOperationInitialDoc, i as compareStringsWithoutWhitespace, l as makeInitialSchemaDoc, o as initializeModelSchema, p as renameSchemaType, s as isEmptyOperationSchema, t as ensureValidOperationSchemaInputName } from "./linting-BjvRPjCY.mjs";
+import { P as usePHToast, m as useSelectedDocumentOfType, y as useSetPHDocumentEditorConfig } from "./dist-CS8QwZwZ.mjs";
+import { a as compareStringsWithoutWhitespace, c as isEmptyOperationSchema, f as makeOperationInitialDoc, l as makeEmptyOperationSchema, m as renameSchemaType, n as ensureValidOperationSchemaInputName, o as handleModelNameChange, s as initializeModelSchema, t as Button, u as makeInitialSchemaDoc } from "./button-Da7CxMn7.mjs";
 import { t as SchemaContextProvider } from "./schema-context-DL8jhi_d.mjs";
 import * as React$1 from "react";
 import React, { Suspense, forwardRef, lazy, useCallback, useEffect, useId, useImperativeHandle, useRef, useState } from "react";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region ../../node_modules/.pnpm/clsx@2.0.0/node_modules/clsx/dist/clsx.mjs
 function r$1(e) {
 	var t, f, n = "";
@@ -196,7 +197,7 @@ function a(o$1, a, u) {
 	}(o$1)) return function(s, c, f) {
 		try {
 			return Promise.resolve(t(function() {
-				return Promise.resolve(("sync" === u.mode ? parse : parseAsync)(o$1, s, a)).then(function(e) {
+				return Promise.resolve(("sync" === u.mode ? parse$1 : parseAsync)(o$1, s, a)).then(function(e) {
 					return f.shouldUseNativeValidation && o({}, f), {
 						errors: {},
 						values: u.raw ? Object.assign({}, s) : e
@@ -756,7 +757,7 @@ function OperationErrors({ operation, addOperationError, deleteOperationError, s
 }
 //#endregion
 //#region editors/document-model-editor/components/operation.tsx
-const GraphqlEditor = lazy(() => import("./graphql-editor-Dd2_z5QJ.mjs"));
+const GraphqlEditor = lazy(() => import("./graphql-editor-DP0o3W7f.mjs"));
 function Operation(props) {
 	const { operation, module, allOperationNames, lastCreatedOperationId, onAddOperationAndInitialSchema, updateOperationName, deleteOperation, updateOperationSchema, setOperationDescription, addOperationError, deleteOperationError, setOperationErrorName, toggleNoInputRequired } = props;
 	const noInputRequired = isEmptyOperationSchema(operation.schema);
@@ -969,6 +970,226 @@ function Modules({ modules, allOperations, addModule, updateModuleName, deleteMo
 	});
 }
 //#endregion
+//#region editors/document-model-editor/components/version-controls.tsx
+const compactButtonStyle$1 = "min-h-0 min-w-0 flex-none rounded-lg px-6 py-1.5 text-sm whitespace-nowrap";
+function VersionControls(props) {
+	const { specifications, viewedVersion, onViewVersion, onReleaseNewVersion } = props;
+	const [showReleaseModal, setShowReleaseModal] = useState(false);
+	const latestVersion = specifications[specifications.length - 1].version;
+	const nextVersion = latestVersion + 1;
+	return /* @__PURE__ */ jsxs("div", {
+		className: "mb-4 flex items-center justify-between gap-4",
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-2",
+				children: [/* @__PURE__ */ jsxs("span", {
+					className: "rounded-md bg-muted px-2 py-0.5 font-mono text-xs text-foreground",
+					"data-testid": "model-version-badge",
+					children: ["Version ", viewedVersion]
+				}), specifications.length >= 2 && /* @__PURE__ */ jsx("div", {
+					"aria-label": "Document model version",
+					"data-testid": "model-version-switcher",
+					children: /* @__PURE__ */ jsx(ConnectSelect, {
+						absolutePositionMenu: true,
+						containerClassName: "z-10 [&_svg]:size-4",
+						id: "model-version-switcher",
+						itemClassName: "gap-1 px-2 py-1 font-mono text-xs leading-none [&_p:empty]:hidden",
+						items: specifications.map((spec) => ({
+							value: String(spec.version),
+							displayValue: /* @__PURE__ */ jsx("span", {
+								className: "normal-case",
+								children: spec.version === latestVersion ? `v${spec.version} (latest)` : `v${spec.version} (frozen)`
+							})
+						})),
+						listClassName: "border border-t-0 border-border shadow-md",
+						menuClassName: "min-w-0 pr-1.5",
+						onChange: (value) => {
+							const version = Number(value);
+							onViewVersion(version === latestVersion ? "latest" : version);
+						},
+						value: String(viewedVersion)
+					})
+				})]
+			}),
+			/* @__PURE__ */ jsx(Button, {
+				className: "inline-flex h-8 items-center justify-center py-0",
+				"data-testid": "release-new-version-button",
+				onClick: () => setShowReleaseModal(true),
+				type: "button",
+				children: "Release new version"
+			}),
+			/* @__PURE__ */ jsx(Modal, {
+				open: showReleaseModal,
+				onOpenChange: (status) => {
+					if (!status) setShowReleaseModal(false);
+				},
+				children: /* @__PURE__ */ jsxs("div", {
+					className: "w-[440px] p-6",
+					children: [
+						/* @__PURE__ */ jsxs("div", {
+							className: "pb-2 text-2xl font-bold text-foreground",
+							children: ["Release version ", nextVersion]
+						}),
+						/* @__PURE__ */ jsxs("div", {
+							className: "my-4 rounded-md bg-background p-4 text-left text-sm text-foreground",
+							children: [/* @__PURE__ */ jsxs("p", { children: [
+								"Version ",
+								latestVersion,
+								" will be frozen as-is. Version",
+								" ",
+								nextVersion,
+								" starts as an identical copy, and all further edits apply to version ",
+								nextVersion,
+								"."
+							] }), /* @__PURE__ */ jsxs("p", {
+								className: "mt-3",
+								children: [
+									"Existing version ",
+									latestVersion,
+									" documents will be upgradeable once you define the migration."
+								]
+							})]
+						}),
+						/* @__PURE__ */ jsxs("div", {
+							className: "mt-4 flex justify-between gap-3",
+							children: [/* @__PURE__ */ jsx(ModalButton, {
+								className: compactButtonStyle$1,
+								onClick: () => setShowReleaseModal(false),
+								variant: "cancel",
+								children: "Cancel"
+							}), /* @__PURE__ */ jsxs(ModalButton, {
+								className: compactButtonStyle$1,
+								"data-testid": "confirm-release-button",
+								onClick: () => {
+									setShowReleaseModal(false);
+									onReleaseNewVersion();
+								},
+								variant: "confirm",
+								children: ["Release version ", nextVersion]
+							})]
+						})
+					]
+				})
+			})
+		]
+	});
+}
+function FrozenVersionBanner(props) {
+	const { viewedVersion, latestVersion } = props;
+	return /* @__PURE__ */ jsxs("div", {
+		className: "mb-4 rounded-md border border-border bg-muted p-3 text-sm text-foreground",
+		"data-testid": "frozen-version-banner",
+		children: [
+			"Version ",
+			viewedVersion,
+			" is frozen. You're viewing it read-only. Edits go to version ",
+			latestVersion,
+			"."
+		]
+	});
+}
+//#endregion
+//#region editors/document-model-editor/components/version-advisory-modal.tsx
+const compactButtonStyle = "min-h-0 min-w-0 flex-none rounded-lg px-4 py-1.5 text-sm whitespace-nowrap";
+function FieldDiffList(props) {
+	const { label, fields } = props;
+	if (fields.length === 0) return null;
+	return /* @__PURE__ */ jsxs("div", {
+		className: "mt-3",
+		children: [/* @__PURE__ */ jsx("p", {
+			className: "mb-1.5",
+			children: label
+		}), /* @__PURE__ */ jsx("div", {
+			className: "flex flex-col items-start gap-1",
+			children: fields.map((field) => /* @__PURE__ */ jsx("span", {
+				className: "rounded-md bg-muted px-2 py-0.5 font-mono text-xs text-foreground",
+				children: field
+			}, field))
+		})]
+	});
+}
+function VersionAdvisoryModal(props) {
+	const { prompt, onReleaseFirst, onKeepEditing, onCancel } = props;
+	if (!prompt) return null;
+	const { version, reason, diff } = prompt;
+	const nextVersion = version + 1;
+	return /* @__PURE__ */ jsx(Modal, {
+		open: true,
+		onOpenChange: (status) => {
+			if (!status) onCancel();
+		},
+		children: /* @__PURE__ */ jsxs("div", {
+			className: "w-[440px] p-6",
+			"data-testid": "version-advisory-modal",
+			children: [
+				/* @__PURE__ */ jsxs("div", {
+					className: "pb-2 text-2xl font-bold text-foreground",
+					children: [
+						"Is version ",
+						version,
+						" of this model already in use?"
+					]
+				}),
+				/* @__PURE__ */ jsxs("div", {
+					className: "my-4 rounded-md bg-background p-4 text-left text-sm text-foreground",
+					children: [
+						/* @__PURE__ */ jsxs("p", { children: [
+							reason,
+							" Documents that were already created with version ",
+							version,
+							" ",
+							"may stop working correctly."
+						] }),
+						diff && /* @__PURE__ */ jsxs(Fragment$1, { children: [
+							/* @__PURE__ */ jsx(FieldDiffList, {
+								fields: diff.addedFields,
+								label: "New fields:"
+							}),
+							/* @__PURE__ */ jsx(FieldDiffList, {
+								fields: diff.removedFields,
+								label: "Removed fields:"
+							}),
+							/* @__PURE__ */ jsx(FieldDiffList, {
+								fields: diff.changedFields,
+								label: "Changed fields:"
+							})
+						] }),
+						/* @__PURE__ */ jsxs("p", {
+							className: "mt-3",
+							children: [
+								"If others are already using version ",
+								version,
+								", release version",
+								" ",
+								nextVersion,
+								" first. Your change will go into version ",
+								nextVersion,
+								", and existing documents can be updated safely."
+							]
+						})
+					]
+				}),
+				/* @__PURE__ */ jsxs("div", {
+					className: "mt-4 flex flex-col gap-2",
+					children: [/* @__PURE__ */ jsx(ModalButton, {
+						className: compactButtonStyle,
+						"data-testid": "advisory-release-first",
+						onClick: onReleaseFirst,
+						variant: "confirm",
+						children: `It's in use — release v${nextVersion} first`
+					}), /* @__PURE__ */ jsxs(ModalButton, {
+						className: compactButtonStyle,
+						"data-testid": "advisory-keep-editing",
+						onClick: onKeepEditing,
+						variant: "cancel",
+						children: ["Still in development — keep editing v", version]
+					})]
+				})
+			]
+		})
+	});
+}
+//#endregion
 //#region editors/document-model-editor/config.ts
 const editorConfig = { isExternalControlsEnabled: false };
 //#endregion
@@ -977,8 +1198,305 @@ function useSelectedDocumentModelDocument() {
 	return useSelectedDocumentOfType("powerhouse/document-model");
 }
 //#endregion
+//#region editors/document-model-editor/utils/change-classification.ts
+var import_graphql = require_graphql();
+function isShapeTypeNode(node) {
+	return node.kind === import_graphql.Kind.OBJECT_TYPE_DEFINITION || node.kind === import_graphql.Kind.INPUT_OBJECT_TYPE_DEFINITION || node.kind === import_graphql.Kind.ENUM_TYPE_DEFINITION;
+}
+function collectTypeFields(doc) {
+	const types = /* @__PURE__ */ new Map();
+	for (const definition of doc.definitions) {
+		if (!isShapeTypeNode(definition)) continue;
+		const fields = /* @__PURE__ */ new Map();
+		if (definition.kind === import_graphql.Kind.ENUM_TYPE_DEFINITION) for (const value of definition.values ?? []) fields.set(value.name.value, "value");
+		else for (const field of definition.fields ?? []) fields.set(field.name.value, (0, import_graphql.print)(field.type));
+		types.set(definition.name.value, fields);
+	}
+	return types;
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function replaceTypeName(printedType, oldName, newName) {
+	return printedType.replace(new RegExp(`\\b${escapeRegExp(oldName)}\\b`, "g"), newName);
+}
+function typeSignature(name, fields) {
+	return [...fields.entries()].map(([field, type]) => `${field}:${replaceTypeName(type, name, "__SELF__")}`).sort().join("|");
+}
+function detectTypeRenames(oldTypes, newTypes) {
+	const renames = /* @__PURE__ */ new Map();
+	const removed = [...oldTypes.keys()].filter((name) => !newTypes.has(name));
+	const added = new Set([...newTypes.keys()].filter((name) => !oldTypes.has(name)));
+	for (const oldName of removed) {
+		const oldSignature = typeSignature(oldName, oldTypes.get(oldName));
+		for (const newName of added) if (typeSignature(newName, newTypes.get(newName)) === oldSignature) {
+			renames.set(oldName, newName);
+			added.delete(newName);
+			break;
+		}
+	}
+	return renames;
+}
+function flattenFields(types, renames) {
+	const fields = /* @__PURE__ */ new Map();
+	for (const [typeName, typeFields] of types) {
+		const resolvedTypeName = renames.get(typeName) ?? typeName;
+		for (const [fieldName, printedType] of typeFields) {
+			let resolvedType = printedType;
+			for (const [oldName, newName] of renames) resolvedType = replaceTypeName(resolvedType, oldName, newName);
+			fields.set(`${resolvedTypeName}.${fieldName}`, resolvedType);
+		}
+	}
+	return fields;
+}
+function hasShapeChange(diff) {
+	return diff.addedFields.length > 0 || diff.removedFields.length > 0 || diff.changedFields.length > 0;
+}
+function diffSdlShapes(oldSdl, newSdl) {
+	const empty = {
+		addedFields: [],
+		removedFields: [],
+		changedFields: []
+	};
+	let oldDoc;
+	let newDoc;
+	try {
+		oldDoc = (0, import_graphql.parse)(oldSdl);
+		newDoc = (0, import_graphql.parse)(newSdl);
+	} catch {
+		return empty;
+	}
+	const oldTypes = collectTypeFields(oldDoc);
+	const newTypes = collectTypeFields(newDoc);
+	const oldFields = flattenFields(oldTypes, detectTypeRenames(oldTypes, newTypes));
+	const newFields = flattenFields(newTypes, /* @__PURE__ */ new Map());
+	const diff = {
+		addedFields: [],
+		removedFields: [],
+		changedFields: []
+	};
+	for (const [key, newType] of newFields) {
+		const oldType = oldFields.get(key);
+		if (oldType === void 0) diff.addedFields.push(key);
+		else if (oldType !== newType) diff.changedFields.push(`${key}: ${oldType} → ${newType}`);
+	}
+	for (const key of oldFields.keys()) if (!newFields.has(key)) diff.removedFields.push(key);
+	return diff;
+}
+const SAFE = { kind: "safe" };
+function isBlank(value) {
+	return !value || !value.trim() || value.trim() === "{}";
+}
+/**
+* True for a blank SDL, or an SDL whose types contain nothing but the
+* `_placeholder` field the editor seeds new state/operation schemas with
+* (see `makeInitialSchemaDoc` / `makeOperationInitialDoc` in ./helpers.ts).
+* Replacing a placeholder-only schema with real fields is a user's first
+* edit on a brand-new model, not a version-relevant change.
+*/
+function isPlaceholderOnlySchema(sdl) {
+	if (isBlank(sdl)) return true;
+	let doc;
+	try {
+		doc = (0, import_graphql.parse)(sdl);
+	} catch {
+		return false;
+	}
+	return [...collectTypeFields(doc).values()].every((fields) => fields.size === 0 || fields.size === 1 && fields.has("_placeholder"));
+}
+function findOperation(spec, operationId) {
+	for (const module of spec.modules) {
+		const operation = module.operations.find((op) => op.id === operationId);
+		if (operation) return operation;
+	}
+}
+function addedSinceLastRelease(operationId, previousSpec) {
+	return previousSpec !== void 0 && !findOperation(previousSpec, operationId);
+}
+function classifySetStateSchema(input, latestSpec) {
+	const currentSchema = input.scope === "local" ? latestSpec.state.local.schema : latestSpec.state.global.schema;
+	if (isPlaceholderOnlySchema(currentSchema)) return SAFE;
+	const diff = diffSdlShapes(currentSchema, input.schema);
+	if (!hasShapeChange(diff)) return SAFE;
+	return {
+		kind: "version-relevant",
+		reason: input.scope === "local" ? `You're changing the local fields that version ${latestSpec.version} documents store.` : `You're changing the fields that version ${latestSpec.version} documents store.`,
+		diff
+	};
+}
+/**
+* The editor pre-fills a fresh model's initial value from the placeholder
+* schema, so a value that is blank or carries only the `_placeholder` key is
+* still being initialized rather than changed.
+*/
+function isPlaceholderOnlyInitialValue(value) {
+	if (isBlank(value)) return true;
+	let parsed;
+	try {
+		parsed = JSON.parse(value);
+	} catch {
+		return false;
+	}
+	if (typeof parsed !== "object" || parsed === null) return false;
+	return Object.keys(parsed).every((key) => key === "_placeholder");
+}
+function classifySetInitialState(input, latestSpec) {
+	const currentValue = input.scope === "local" ? latestSpec.state.local.initialValue : latestSpec.state.global.initialValue;
+	if (isPlaceholderOnlyInitialValue(currentValue)) return SAFE;
+	if (compareStringsWithoutWhitespace(currentValue, input.initialValue)) return SAFE;
+	return {
+		kind: "version-relevant",
+		reason: `You're changing the starting content that version ${latestSpec.version} documents are built on.`
+	};
+}
+function classifyOperationChange(action, operationId, latestSpec, previousSpec) {
+	if (addedSinceLastRelease(operationId, previousSpec)) return SAFE;
+	const operation = findOperation(latestSpec, operationId);
+	if (!operation) return SAFE;
+	const operationLabel = operation.name || "an operation";
+	switch (action.type) {
+		case "DELETE_OPERATION": return {
+			kind: "version-relevant",
+			reason: `You're removing the "${operationLabel}" operation from version ${latestSpec.version}.`
+		};
+		case "SET_OPERATION_NAME":
+			if (isBlank(operation.name)) return SAFE;
+			return {
+				kind: "version-relevant",
+				reason: `You're renaming the "${operationLabel}" operation in version ${latestSpec.version}.`
+			};
+		case "SET_OPERATION_SCHEMA": {
+			if (isPlaceholderOnlySchema(operation.schema ?? "")) return SAFE;
+			if (isBlank(action.input.schema)) return {
+				kind: "version-relevant",
+				reason: `You're changing the information that the "${operationLabel}" operation accepts in version ${latestSpec.version}.`
+			};
+			const diff = diffSdlShapes(operation.schema ?? "", action.input.schema ?? "");
+			if (!hasShapeChange(diff)) return SAFE;
+			return {
+				kind: "version-relevant",
+				reason: `You're changing the information that the "${operationLabel}" operation accepts in version ${latestSpec.version}.`,
+				diff
+			};
+		}
+		default: return SAFE;
+	}
+}
+function classifyDeleteModule(moduleId, latestSpec, previousSpec) {
+	const module = latestSpec.modules.find((candidate) => candidate.id === moduleId);
+	if (!module || module.operations.length === 0) return SAFE;
+	if (module.operations.every((operation) => addedSinceLastRelease(operation.id, previousSpec))) return SAFE;
+	return {
+		kind: "version-relevant",
+		reason: `You're removing the "${module.name}" module and all of its operations from version ${latestSpec.version}.`
+	};
+}
+/**
+* Classifies a document-model action as version-relevant (would break
+* documents created with the current version) or safe. `previousSpec` is the
+* last released specification, used to exempt operations added since the
+* release.
+*/
+function classifyDocumentModelAction(action, latestSpec, previousSpec) {
+	switch (action.type) {
+		case "SET_STATE_SCHEMA": return classifySetStateSchema(action.input, latestSpec);
+		case "SET_INITIAL_STATE": return classifySetInitialState(action.input, latestSpec);
+		case "DELETE_OPERATION":
+		case "SET_OPERATION_NAME":
+		case "SET_OPERATION_SCHEMA": return classifyOperationChange(action, action.input.id, latestSpec, previousSpec);
+		case "DELETE_MODULE": return classifyDeleteModule(action.input.id, latestSpec, previousSpec);
+		default: return SAFE;
+	}
+}
+/**
+* Pure decision core of the version advisory: given the actions about to be
+* dispatched, decide whether to dispatch immediately or prompt the user.
+*/
+function decideDispatch(actions, latestSpec, previousSpec, hasSessionChoice) {
+	if (hasSessionChoice) return { kind: "dispatch" };
+	for (const action of actions) {
+		const classification = classifyDocumentModelAction(action, latestSpec, previousSpec);
+		if (classification.kind === "version-relevant") return {
+			kind: "prompt",
+			reason: classification.reason,
+			diff: classification.diff
+		};
+	}
+	return { kind: "dispatch" };
+}
+//#endregion
+//#region editors/document-model-editor/hooks/useVersionAdvisory.ts
+/**
+* Versions the user has confirmed as "still in development" (or that were
+* just created via an explicit release) for this browser session. Keyed by
+* `${documentId}:${version}`. Deliberately in-memory: a publisher returning
+* in a later session is asked again, which is when the reminder matters.
+*/
+const sessionVersionChoices = /* @__PURE__ */ new Set();
+function useVersionAdvisory(args) {
+	const { documentId, latestSpec, previousSpec, dispatch, onReleaseError } = args;
+	const [prompt, setPrompt] = useState(void 0);
+	const pendingRef = useRef(void 0);
+	const choiceKey = `${documentId}:${latestSpec.version}`;
+	const guardedDispatch = (...dispatchArgs) => {
+		const [action] = dispatchArgs;
+		const decision = decideDispatch((Array.isArray(action) ? action : [action]).filter((candidate) => candidate !== void 0), latestSpec, previousSpec, sessionVersionChoices.has(choiceKey));
+		if (decision.kind === "dispatch") {
+			dispatch(...dispatchArgs);
+			return;
+		}
+		pendingRef.current = dispatchArgs;
+		setPrompt({
+			version: latestSpec.version,
+			reason: decision.reason,
+			diff: decision.diff
+		});
+	};
+	const flushPending = () => {
+		const pending = pendingRef.current;
+		pendingRef.current = void 0;
+		if (pending) dispatch(...pending);
+	};
+	const releaseFirst = () => {
+		setPrompt(void 0);
+		if (!pendingRef.current) return;
+		dispatch(releaseNewVersion(), (errors) => {
+			if (errors.length > 0) {
+				pendingRef.current = void 0;
+				onReleaseError?.(errors[0].message);
+			}
+		}, () => {
+			if (!pendingRef.current) return;
+			sessionVersionChoices.add(`${documentId}:${latestSpec.version + 1}`);
+			flushPending();
+		});
+	};
+	const keepEditing = () => {
+		sessionVersionChoices.add(choiceKey);
+		setPrompt(void 0);
+		flushPending();
+	};
+	const cancelAdvisory = () => {
+		pendingRef.current = void 0;
+		setPrompt(void 0);
+	};
+	const markVersionInDevelopment = (version) => {
+		sessionVersionChoices.add(`${documentId}:${version}`);
+	};
+	return {
+		guardedDispatch,
+		prompt,
+		releaseFirst,
+		keepEditing,
+		cancelAdvisory,
+		markVersionInDevelopment
+	};
+}
+//#endregion
 //#region editors/document-model-editor/editor.tsx
-const StateSchemas = lazy(() => import("./state-schemas-BSLgTw2O.mjs"));
+const StateSchemas = lazy(() => import("./state-schemas-CylQoH3Q.mjs"));
+const noopSetStateSchema = () => void 0;
+const noopSetInitialState = () => void 0;
 function Editor() {
 	useSetPHDocumentEditorConfig(editorConfig);
 	const toast = usePHToast();
@@ -986,9 +1504,17 @@ function Editor() {
 	const [scope, setScope] = useState("global");
 	const documentNodeName = document.header.name;
 	const { name: modelName, id: documentType, extension, description, author: { name: authorName, website: authorWebsite } } = document.state.global;
-	const { state: { global: { schema: globalStateSchema, initialValue: globalStateInitialValue }, local: { schema: localStateSchema, initialValue: localStateInitialValue } }, modules } = document.state.global.specifications[0];
+	const specifications = document.state.global.specifications;
+	const latestSpec = specifications[specifications.length - 1];
+	const previousSpec = specifications.length >= 2 ? specifications[specifications.length - 2] : void 0;
+	const [viewedVersion, setViewedVersion] = useState("latest");
+	const viewedSpec = viewedVersion === "latest" ? latestSpec : specifications.find((spec) => spec.version === viewedVersion) ?? latestSpec;
+	const isViewingFrozenVersion = viewedSpec.version !== latestSpec.version;
+	const { state: { global: { schema: globalStateSchema, initialValue: globalStateInitialValue }, local: { schema: localStateSchema, initialValue: localStateInitialValue } }, modules } = viewedSpec;
 	const operations = modules.flatMap((module) => module.operations);
-	const shouldSetInitialName = useRef(!modelName && !!documentNodeName && operations.length === 0);
+	const { state: { global: { schema: latestGlobalStateSchema, initialValue: latestGlobalStateInitialValue }, local: { schema: latestLocalStateSchema, initialValue: latestLocalStateInitialValue } }, modules: latestModules } = latestSpec;
+	const latestOperations = latestModules.flatMap((module) => module.operations);
+	const shouldSetInitialName = useRef(!modelName && !!documentNodeName && latestOperations.length === 0);
 	useEffect(() => {
 		if (!shouldSetInitialName.current || !documentNodeName) return;
 		const initialSchemaDoc = initializeModelSchema(documentNodeName);
@@ -998,41 +1524,59 @@ function Editor() {
 		})]);
 		shouldSetInitialName.current = false;
 	}, [documentNodeName, dispatch]);
+	const { guardedDispatch, prompt, releaseFirst, keepEditing, cancelAdvisory, markVersionInDevelopment } = useVersionAdvisory({
+		documentId: document.header.id,
+		latestSpec,
+		previousSpec,
+		dispatch,
+		onReleaseError: (message) => {
+			if (toast) toast(message, { type: "connect-warning" });
+		}
+	});
+	const handleReleaseNewVersion = () => {
+		const nextVersion = latestSpec.version + 1;
+		dispatch(releaseNewVersion(), (errors) => {
+			if (errors.length > 0 && toast) toast(errors[0].message, { type: "connect-warning" });
+		}, () => {
+			markVersionInDevelopment(nextVersion);
+			setViewedVersion("latest");
+		});
+	};
 	const operationSchemasSdl = operations.flatMap((operation) => operation.schema ?? []).join("\n");
 	const handleSetModelId = (id) => {
 		if (compareStringsWithoutWhitespace(id, documentType)) return;
-		dispatch([setModelId({ id })]);
+		guardedDispatch([setModelId({ id })]);
 	};
 	const handleSetModelDescription = (newDescription) => {
 		if (compareStringsWithoutWhitespace(newDescription, description)) return;
-		dispatch(setModelDescription({ description: newDescription }));
+		guardedDispatch(setModelDescription({ description: newDescription }));
 	};
 	const handleSetModelExtension = (newExtension) => {
 		if (compareStringsWithoutWhitespace(newExtension, extension)) return;
-		dispatch(setModelExtension({ extension: newExtension }));
+		guardedDispatch(setModelExtension({ extension: newExtension }));
 	};
 	const handleSetModelName = (newName) => {
 		if (compareStringsWithoutWhitespace(newName, modelName)) return;
-		dispatch(setModelName({ name: newName }));
+		guardedDispatch(setModelName({ name: newName }));
 	};
 	const handleSetAuthorName = (newAuthorName) => {
 		if (compareStringsWithoutWhitespace(newAuthorName, authorName)) return;
-		dispatch(setAuthorName({ authorName: newAuthorName }));
+		guardedDispatch(setAuthorName({ authorName: newAuthorName }));
 	};
 	const handleSetAuthorWebsite = (newAuthorWebsite) => {
 		if (compareStringsWithoutWhitespace(newAuthorWebsite, authorWebsite ?? "")) return;
-		dispatch(setAuthorWebsite({ authorWebsite: newAuthorWebsite }));
+		guardedDispatch(setAuthorWebsite({ authorWebsite: newAuthorWebsite }));
 	};
 	const handleSetStateSchema = (newSchema, scope) => {
-		if (compareStringsWithoutWhitespace(newSchema, scope === "global" ? globalStateSchema : localStateSchema)) return;
-		dispatch(setStateSchema({
+		if (compareStringsWithoutWhitespace(newSchema, scope === "global" ? latestGlobalStateSchema : latestLocalStateSchema)) return;
+		guardedDispatch(setStateSchema({
 			schema: newSchema,
 			scope
 		}));
 	};
 	const handleSetInitialState = (newInitialValue, scope) => {
-		if (compareStringsWithoutWhitespace(newInitialValue, scope === "global" ? globalStateInitialValue : localStateInitialValue)) return;
-		dispatch(setInitialState({
+		if (compareStringsWithoutWhitespace(newInitialValue, scope === "global" ? latestGlobalStateInitialValue : latestLocalStateInitialValue)) return;
+		guardedDispatch(setInitialState({
 			initialValue: newInitialValue,
 			scope
 		}));
@@ -1040,12 +1584,12 @@ function Editor() {
 	const handleAddModule = (name) => {
 		return new Promise((resolve) => {
 			try {
-				if (modules.some((module) => compareStringsWithoutWhitespace(module.name, name))) {
+				if (latestModules.some((module) => compareStringsWithoutWhitespace(module.name, name))) {
 					resolve(void 0);
 					return;
 				}
 				const id = generateId();
-				dispatch(addModule({
+				guardedDispatch(addModule({
 					id,
 					name
 				}));
@@ -1057,19 +1601,19 @@ function Editor() {
 		});
 	};
 	const handleSetModuleName = (id, name) => {
-		if (modules.some((module) => compareStringsWithoutWhitespace(module.name, name))) return;
-		dispatch(setModuleName({
+		if (latestModules.some((module) => compareStringsWithoutWhitespace(module.name, name))) return;
+		guardedDispatch(setModuleName({
 			id,
 			name
 		}));
 	};
 	const handleDeleteModule = (id) => {
-		dispatch(deleteModule({ id }));
+		guardedDispatch(deleteModule({ id }));
 	};
 	const handleAddOperation = (moduleId, name) => {
 		return new Promise((resolve) => {
 			const id = generateId();
-			dispatch(addOperation({
+			guardedDispatch(addOperation({
 				id,
 				moduleId,
 				name,
@@ -1083,7 +1627,7 @@ function Editor() {
 		});
 	};
 	const handleSetOperationName = (id, name) => {
-		dispatch(setOperationName({
+		guardedDispatch(setOperationName({
 			id,
 			name
 		}), (errors) => {
@@ -1091,44 +1635,44 @@ function Editor() {
 		});
 	};
 	const handleSetOperationSchema = (id, newSchema) => {
-		const operation = operations.find((operation) => operation.id === id);
+		const operation = latestOperations.find((operation) => operation.id === id);
 		if (operation?.schema && compareStringsWithoutWhitespace(newSchema, operation.schema)) return;
-		dispatch(setOperationSchema({
+		guardedDispatch(setOperationSchema({
 			id,
 			schema: newSchema
 		}));
 	};
 	const handleToggleNoInputRequired = (id, noInputRequired) => {
-		const operation = operations.find((op) => op.id === id);
+		const operation = latestOperations.find((op) => op.id === id);
 		if (!operation?.name) return;
-		if (noInputRequired) dispatch(setOperationSchema({
+		if (noInputRequired) guardedDispatch(setOperationSchema({
 			id,
 			schema: makeEmptyOperationSchema(operation.name)
 		}));
-		else dispatch(setOperationSchema({
+		else guardedDispatch(setOperationSchema({
 			id,
 			schema: makeOperationInitialDoc(operation.name)
 		}));
 	};
 	const handleSetOperationDescription = (id, newDescription) => {
-		if (compareStringsWithoutWhitespace(operations.find((operation) => operation.id === id)?.description ?? "", newDescription)) return;
-		dispatch(setOperationDescription({
+		if (compareStringsWithoutWhitespace(latestOperations.find((operation) => operation.id === id)?.description ?? "", newDescription)) return;
+		guardedDispatch(setOperationDescription({
 			id,
 			description: newDescription
 		}));
 	};
 	const handleDeleteOperation = (id) => {
-		dispatch(deleteOperation({ id }));
+		guardedDispatch(deleteOperation({ id }));
 	};
 	const handleAddOperationError = (operationId, errorName) => {
 		return new Promise((resolve) => {
 			try {
-				if ((operations.find((operation) => operation.id === operationId)?.errors.map((error) => error.name).filter(Boolean) ?? []).some((name) => compareStringsWithoutWhitespace(name, errorName))) {
+				if ((latestOperations.find((operation) => operation.id === operationId)?.errors.map((error) => error.name).filter(Boolean) ?? []).some((name) => compareStringsWithoutWhitespace(name, errorName))) {
 					resolve(void 0);
 					return;
 				}
 				const id = generateId();
-				dispatch(addOperationError({
+				guardedDispatch(addOperationError({
 					id,
 					operationId,
 					errorName,
@@ -1142,11 +1686,11 @@ function Editor() {
 		});
 	};
 	const handleDeleteOperationError = (id) => {
-		dispatch(deleteOperationError({ id }));
+		guardedDispatch(deleteOperationError({ id }));
 	};
 	const handleSetOperationErrorName = (operationId, errorId, errorName) => {
-		if ((operations.find((operation) => operation.id === operationId)?.errors.map((error) => error.name).filter(Boolean) ?? []).some((name) => compareStringsWithoutWhitespace(name, errorName))) return;
-		dispatch(setOperationErrorName({
+		if ((latestOperations.find((operation) => operation.id === operationId)?.errors.map((error) => error.name).filter(Boolean) ?? []).some((name) => compareStringsWithoutWhitespace(name, errorName))) return;
+		guardedDispatch(setOperationErrorName({
 			id: errorId,
 			errorName
 		}));
@@ -1169,74 +1713,97 @@ function Editor() {
 	};
 	return /* @__PURE__ */ jsxs("main", {
 		className: "min-h-dvh bg-background p-6",
-		children: [/* @__PURE__ */ jsx(DocumentToolbar, {}), /* @__PURE__ */ jsx(SchemaContextProvider, {
-			globalStateSchemaSdl: globalStateSchema,
-			localStateSchemaSdl: localStateSchema,
-			operationSchemasSdl,
-			children: /* @__PURE__ */ jsxs("div", {
-				className: "mx-auto max-w-6xl px-4 pt-8",
-				children: [
-					/* @__PURE__ */ jsx(ModelMetadata, {
-						name: modelName,
-						documentType,
-						extension,
-						description,
-						authorName,
-						authorWebsite: authorWebsite ?? "",
-						globalStateSchema,
-						localStateSchema,
-						setModelId: handleSetModelId,
-						setModelDescription: handleSetModelDescription,
-						setModelExtension: handleSetModelExtension,
-						setModelName: handleSetModelName,
-						setAuthorName: handleSetAuthorName,
-						setAuthorWebsite: handleSetAuthorWebsite,
-						setStateSchema: handleSetStateSchema
-					}),
-					/* @__PURE__ */ jsx(Divider, {}),
-					/* @__PURE__ */ jsxs("div", { children: [
-						/* @__PURE__ */ jsx(Suspense, { children: /* @__PURE__ */ jsx(StateSchemas, {
-							modelName,
-							globalStateSchema,
-							globalStateInitialValue,
-							localStateSchema,
-							localStateInitialValue,
-							setStateSchema: handleSetStateSchema,
-							setInitialState: handleSetInitialState,
-							currentScope: scope,
-							onScopeChange: setScope
-						}) }),
+		children: [
+			/* @__PURE__ */ jsx(DocumentToolbar, {}),
+			/* @__PURE__ */ jsx(SchemaContextProvider, {
+				globalStateSchemaSdl: globalStateSchema,
+				localStateSchemaSdl: localStateSchema,
+				operationSchemasSdl,
+				children: /* @__PURE__ */ jsxs("div", {
+					className: "mx-auto max-w-6xl px-4 pt-8",
+					children: [
+						/* @__PURE__ */ jsx(VersionControls, {
+							specifications,
+							viewedVersion: viewedSpec.version,
+							onViewVersion: setViewedVersion,
+							onReleaseNewVersion: handleReleaseNewVersion
+						}),
+						/* @__PURE__ */ jsx(ModelMetadata, {
+							name: modelName,
+							documentType,
+							extension,
+							description,
+							authorName,
+							authorWebsite: authorWebsite ?? "",
+							globalStateSchema: latestGlobalStateSchema,
+							localStateSchema: latestLocalStateSchema,
+							setModelId: handleSetModelId,
+							setModelDescription: handleSetModelDescription,
+							setModelExtension: handleSetModelExtension,
+							setModelName: handleSetModelName,
+							setAuthorName: handleSetAuthorName,
+							setAuthorWebsite: handleSetAuthorWebsite,
+							setStateSchema: handleSetStateSchema
+						}),
 						/* @__PURE__ */ jsx(Divider, {}),
-						/* @__PURE__ */ jsxs("h3", {
-							className: "mb-6 text-lg text-foreground capitalize",
-							children: [scope, " Operations"]
+						isViewingFrozenVersion && /* @__PURE__ */ jsx(FrozenVersionBanner, {
+							latestVersion: latestSpec.version,
+							viewedVersion: viewedSpec.version
 						}),
-						/* @__PURE__ */ jsx(Modules, {
-							modules: modules.map((module) => ({
-								...module,
-								operations: module.operations.filter((op) => op.scope === scope)
-							})),
-							allOperations: operations,
-							addModule: handleAddModule,
-							updateModuleName: handleSetModuleName,
-							deleteModule: handleDeleteModule,
-							updateOperationName: handleSetOperationName,
-							updateOperationSchema: handleSetOperationSchema,
-							setOperationDescription: handleSetOperationDescription,
-							deleteOperation: handleDeleteOperation,
-							addOperationError: handleAddOperationError,
-							deleteOperationError: handleDeleteOperationError,
-							setOperationErrorName: handleSetOperationErrorName,
-							addOperationAndInitialSchema,
-							toggleNoInputRequired: handleToggleNoInputRequired
+						/* @__PURE__ */ jsxs("div", {
+							className: isViewingFrozenVersion ? "pointer-events-none opacity-80 select-none" : void 0,
+							inert: isViewingFrozenVersion || void 0,
+							children: [
+								/* @__PURE__ */ jsx(Suspense, { children: /* @__PURE__ */ jsx(StateSchemas, {
+									modelName,
+									globalStateSchema,
+									globalStateInitialValue,
+									localStateSchema,
+									localStateInitialValue,
+									setStateSchema: isViewingFrozenVersion ? noopSetStateSchema : handleSetStateSchema,
+									setInitialState: isViewingFrozenVersion ? noopSetInitialState : handleSetInitialState,
+									currentScope: scope,
+									onScopeChange: setScope
+								}) }),
+								/* @__PURE__ */ jsx(Divider, {}),
+								/* @__PURE__ */ jsxs("h3", {
+									className: "mb-6 text-lg text-foreground capitalize",
+									children: [scope, " Operations"]
+								}),
+								/* @__PURE__ */ jsx(Modules, {
+									modules: modules.map((module) => ({
+										...module,
+										operations: module.operations.filter((op) => op.scope === scope)
+									})),
+									allOperations: operations,
+									addModule: handleAddModule,
+									updateModuleName: handleSetModuleName,
+									deleteModule: handleDeleteModule,
+									updateOperationName: handleSetOperationName,
+									updateOperationSchema: handleSetOperationSchema,
+									setOperationDescription: handleSetOperationDescription,
+									deleteOperation: handleDeleteOperation,
+									addOperationError: handleAddOperationError,
+									deleteOperationError: handleDeleteOperationError,
+									setOperationErrorName: handleSetOperationErrorName,
+									addOperationAndInitialSchema,
+									toggleNoInputRequired: handleToggleNoInputRequired
+								})
+							]
 						})
-					] })
-				]
+					]
+				})
+			}),
+			/* @__PURE__ */ jsx(VersionAdvisoryModal, {
+				prompt,
+				onReleaseFirst: releaseFirst,
+				onKeepEditing: keepEditing,
+				onCancel: cancelAdvisory
 			})
-		})]
+		]
 	});
 }
 //#endregion
 export { Editor as default };
 
-//# sourceMappingURL=editor-Cr-mNQca.mjs.map
+//# sourceMappingURL=editor-ClZqmnoh.mjs.map