@react-querybuilder/core 8.21.1 → 8.22.0

package/dist/react-querybuilder_core.mjs

@@ -1,5 +1,5 @@
 import { numericQuantity, numericRegex as numericRegex$1 } from "numeric-quantity";
-import { current, isDraft, produce } from "immer";
+import { current, freeze, isDraft, produce } from "immer";
 //#region src/defaults.ts
 /**
 * @group Defaults
@@ -130,6 +130,14 @@ const defaultTranslations = {
 		label: "˅",
 		title: "Shift down"
 	},
+	undo: {
+		label: "↶",
+		title: "Undo"
+	},
+	redo: {
+		label: "↷",
+		title: "Redo"
+	},
 	dragHandle: {
 		label: "⁞⁞",
 		title: "Drag handle"
@@ -454,6 +462,9 @@ const standardClassnames = {
 	valid: "queryBuilder-valid",
 	invalid: "queryBuilder-invalid",
 	shiftActions: "shiftActions",
+	undoRedoActions: "undoRedoActions",
+	undoAction: "undoRedoActions-undo",
+	redoAction: "undoRedoActions-redo",
 	dndDragging: "dndDragging",
 	dndOver: "dndOver",
 	dndCopy: "dndCopy",
@@ -502,6 +513,9 @@ const defaultControlClassnames = {
 	value: "",
 	removeRule: "",
 	shiftActions: "",
+	undoRedoActions: "",
+	undoAction: "",
+	redoAction: "",
 	dragHandle: "",
 	lockRule: "",
 	lockGroup: "",
@@ -559,6 +573,9 @@ const TestID = {
 	valueEditor: "value-editor",
 	notToggle: "not-toggle",
 	shiftActions: "shift-actions",
+	undoRedoActions: "undo-redo-actions",
+	undoAction: "undo-action",
+	redoAction: "redo-action",
 	dragHandle: "drag-handle",
 	lockRule: "lock-rule",
 	lockGroup: "lock-group",
@@ -605,6 +622,7 @@ const queryBuilderFlagDefaults = {
 	enableDragAndDrop: false,
 	enableMountQueryChange: true,
 	listsAsArrays: false,
+	preserveQueryStateOnUnmount: false,
 	resetOnFieldChange: true,
 	resetOnOperatorChange: false,
 	showCloneButtons: false,
@@ -613,8 +631,22 @@ const queryBuilderFlagDefaults = {
 	showMuteButtons: false,
 	showNotToggle: false,
 	showShiftActions: false,
+	showUndoRedo: false,
 	suppressStandardClassnames: false
 };
+/**
+* Default maximum number of undo steps retained by query history.
+*
+* @group Defaults
+*/
+const defaultMaxHistory = 50;
+/**
+* Default time window (in milliseconds) within which consecutive changes to the same
+* property of the same rule are coalesced into a single undo step.
+*
+* @group Defaults
+*/
+const defaultCoalesceMs = 500;
 //#endregion
 //#region src/utils/arrayUtils.ts
 /**
@@ -800,6 +832,178 @@ function convertQuery(query) {
 	return isRuleGroupTypeIC(query) ? convertFromIC(query) : convertToIC(query);
 }
 //#endregion
+//#region src/utils/deriveClassNames.ts
+const ruleClassnameSources = {
+	shiftActions: ["shiftActions"],
+	dragHandle: ["dragHandle"],
+	fields: ["valueSelector", "fields"],
+	matchMode: ["valueSelector", "matchMode"],
+	matchThreshold: ["valueSelector", "matchThreshold"],
+	operators: ["valueSelector", "operators"],
+	valueSource: ["valueSelector", "valueSource"],
+	value: ["value"],
+	cloneRule: ["actionElement", "cloneRule"],
+	lockRule: ["actionElement", "lockRule"],
+	muteRule: ["actionElement", "muteRule"],
+	removeRule: ["actionElement", "removeRule"],
+	valueListItem: ["valueListItem"]
+};
+const ruleGroupClassnameSources = {
+	header: {
+		sources: ["header"],
+		conditions: [
+			{
+				key: "dndOver",
+				when: (s) => s.isOver,
+				standardOnly: true
+			},
+			{
+				key: "dndCopy",
+				when: (s) => s.isOver && s.dropEffect === "copy"
+			},
+			{
+				key: "dndDropNotAllowed",
+				when: (s) => s.dropNotAllowed
+			}
+		]
+	},
+	shiftActions: ["shiftActions"],
+	undoRedoActions: ["undoRedoActions"],
+	undoAction: ["actionElement", "undoAction"],
+	redoAction: ["actionElement", "redoAction"],
+	dragHandle: ["dragHandle"],
+	combinators: ["valueSelector", "combinators"],
+	notToggle: ["notToggle"],
+	addRule: ["actionElement", "addRule"],
+	addGroup: ["actionElement", "addGroup"],
+	cloneGroup: ["actionElement", "cloneGroup"],
+	lockGroup: ["actionElement", "lockGroup"],
+	muteGroup: ["actionElement", "muteGroup"],
+	removeGroup: ["actionElement", "removeGroup"],
+	body: ["body"]
+};
+/**
+* Conditional classes applied to a rule's wrapper element.
+*
+* Note that this is deliberately _not_ the same set as {@link ruleGroupOuterConditions}: a rule
+* reflects more drag-and-drop states than a group does. Declaring each set separately is what
+* keeps an implementation from assuming they're symmetric.
+*/
+const ruleOuterConditions = [
+	{
+		key: "disabled",
+		when: (s) => s.disabled
+	},
+	{
+		key: "muted",
+		when: (s) => s.muted
+	},
+	{
+		key: "dndDragging",
+		when: (s) => s.isDragging
+	},
+	{
+		key: "dndOver",
+		when: (s) => s.isOver
+	},
+	{
+		key: "dndCopy",
+		when: (s) => s.isOver && s.dropEffect === "copy"
+	},
+	{
+		key: "dndGroup",
+		when: (s) => s.isOver && s.groupItems
+	},
+	{
+		key: "dndDropNotAllowed",
+		when: (s) => s.dropNotAllowed
+	},
+	{
+		key: "hasSubQuery",
+		when: (s) => s.hasSubQuery
+	}
+];
+/** Conditional classes applied to a rule group's wrapper element. */
+const ruleGroupOuterConditions = [
+	{
+		key: "disabled",
+		when: (s) => s.disabled
+	},
+	{
+		key: "muted",
+		when: (s) => s.muted
+	},
+	{
+		key: "dndDragging",
+		when: (s) => s.isDragging
+	},
+	{
+		key: "dndGroup",
+		when: (s) => s.isOver && s.groupItems
+	}
+];
+/**
+* Expands conditions into `clsx` arguments: every custom class first (in declaration order),
+* then a single object of standard classes.
+*/
+const conditionArgs = (conditions, state, { classNames, suppressStandardClassnames }) => {
+	const evaluated = conditions.map((condition) => [condition, !!condition.when(state)]);
+	return [...evaluated.filter(([condition]) => !condition.standardOnly).map(([condition, active]) => active && classNames?.[condition.key]), suppressStandardClassnames || Object.fromEntries(evaluated.map(([condition, active]) => [standardClassnames[condition.key], active]))];
+};
+/** Composes the classname for a single entry of a spec map. */
+const deriveFromSpec = (key, spec, state, options) => {
+	const { sources, conditions } = Array.isArray(spec) ? { sources: spec } : spec;
+	return clsx(options.suppressStandardClassnames || standardClassnames[key], ...sources.map((source) => options.classNames?.[source]), ...conditions ? conditionArgs(conditions, state, options) : []);
+};
+const deriveFromSpecs = (specs, state, options) => {
+	const result = {};
+	for (const [key, spec] of Object.entries(specs)) result[key] = deriveFromSpec(key, spec, state, options);
+	return result;
+};
+/**
+* Classnames for each element rendered by a rule. This is the framework-agnostic core of the
+* `classNames` object returned by the `useRule` hook.
+*
+* @group Query Tools
+*/
+const deriveRuleClassNames = (options) => deriveFromSpecs(ruleClassnameSources, {}, options);
+/**
+* The classname for a single element of a rule, composed from the same table as
+* {@link deriveRuleClassNames}. Useful where only one is needed, such as the items of a
+* multi-value editor.
+*
+* @group Query Tools
+*/
+const deriveRuleClassName = (key, options) => deriveFromSpec(key, ruleClassnameSources[key], {}, options);
+/**
+* Classnames for each element rendered by a rule group, including its conditionally-classed
+* `header`. This is the framework-agnostic core of the `classNames` object returned by the
+* `useRuleGroup` hook.
+*
+* @group Query Tools
+*/
+const deriveRuleGroupClassNames = (options) => deriveFromSpecs(ruleGroupClassnameSources, options, options);
+const deriveOuterClassName = (standardKey, conditions, options) => {
+	const { classNames, suppressStandardClassnames, leadingClassNames = [], validationClassName } = options;
+	return clsx(...leadingClassNames, suppressStandardClassnames || standardClassnames[standardKey], classNames?.[standardKey], ...conditionArgs(conditions, options, options), validationClassName);
+};
+/**
+* The outer (wrapper) classname for a rule, including every conditional state class.
+*
+* @group Query Tools
+*/
+const deriveRuleOuterClassName = (options) => deriveOuterClassName("rule", ruleOuterConditions, options);
+/**
+* The outer (wrapper) classname for a rule group, including every conditional state class.
+*
+* A group reflects fewer drag-and-drop states than a rule—`dndOver`, `dndCopy`,
+* `dndDropNotAllowed`, and `hasSubQuery` do not apply—so this is not interchangeable with
+* {@link deriveRuleOuterClassName}.
+*
+* @group Query Tools
+*/
+const deriveRuleGroupOuterClassName = (options) => deriveOuterClassName("ruleGroup", ruleGroupOuterConditions, options);
+//#endregion
 //#region src/utils/defaultValidator.ts
 /**
 * This is an example validation function you can pass to {@link react-querybuilder!QueryBuilder QueryBuilder} in the
@@ -1060,8 +1264,10 @@ const prepareOptionList = (props) => {
 			...op,
 			[placeholderName]: defaultOption
 		};
-	} else if (isFlexibleOptionGroupArray(optionList)) for (const og of optionList) for (const opt of og.options) optionsMap[opt.value ?? opt.name] = toFullOption(opt, baseOption);
-	else for (const opt of optionList) optionsMap[opt.value ?? opt.name] = toFullOption(opt, baseOption);
+	} else if (isFlexibleOptionGroupArray(optionList)) for (const og of optionList) for (const opt of og.options) optionsMap[opt.value ?? 
+	/* v8 ignore start -- @preserve */ opt.name] = toFullOption(opt, baseOption);
+	else for (const opt of optionList) optionsMap[opt.value ?? 
+	/* v8 ignore start -- @preserve */ opt.name] = toFullOption(opt, baseOption);
 	return {
 		defaultOption,
 		optionList,
@@ -1075,7 +1281,8 @@ const filterByComparator = (field, operator, fieldToCompare) => {
 	const fullFieldToCompare = toFullOption(fieldToCompare);
 	if (fullField.value === fullFieldToCompare.value) return false;
 	if (typeof fullField.comparator === "string") return fullField[fullField.comparator] === fullFieldToCompare[fullField.comparator];
-	return fullField.comparator?.(fullFieldToCompare, operator) ?? false;
+	return fullField.comparator?.(fullFieldToCompare, operator) ?? 
+	/* v8 ignore start -- @preserve */ false;
 };
 /**
 * For a given {@link FullField}, returns the `fields` list filtered for
@@ -1090,7 +1297,8 @@ const filterByComparator = (field, operator, fieldToCompare) => {
 */
 const filterFieldsByComparator = (field, fields, operator) => {
 	if (!field.comparator) {
-		const filterOutSameField = (f) => (f.value ?? f.name) !== (field.value ?? field.name);
+		const filterOutSameField = (f) => (f.value ?? /* v8 ignore start -- @preserve */ f.name) !== (field.value ?? 
+		/* v8 ignore start -- @preserve */ field.name);
 		if (isFlexibleOptionGroupArray(fields)) return fields.map((og) => ({
 			...og,
 			options: og.options.filter((v) => filterOutSameField(v))
@@ -1104,6 +1312,128 @@ const filterFieldsByComparator = (field, fields, operator) => {
 	return fields.filter((f) => filterByComparator(field, operator, f));
 };
 //#endregion
+//#region src/utils/deriveRuleContext.ts
+/**
+* Resolves the field configuration for a rule's `field`, falling back to a minimal option object
+* when the field isn't present in the field map.
+*/
+const getFieldData = (field, fieldMap) => fieldMap?.[field] ?? {
+	name: field,
+	value: field,
+	label: field
+};
+/**
+* The input type for a rule. A field's own `inputType` takes precedence over `getInputType`.
+*/
+const getRuleInputType = (field, operator, fieldData, getInputType) => fieldData.inputType ?? getInputType(field, operator, { fieldData });
+/**
+* Whether the value editor(s) should be hidden for an operator, based on its `arity`.
+*/
+const hideValueControlsForOperator = (operatorObject) => {
+	const arity = operatorObject?.arity;
+	return typeof arity === "string" && arity === "unary" || typeof arity === "number" && arity < 2;
+};
+/**
+* Value source options for a rule. A `valueSource` present on the rule but absent from the
+* configured list is appended, so the current selection is always representable.
+*/
+const getRuleValueSourceOptions = (rule, fieldData, getValueSources) => {
+	const configuredVSs = getValueSources(rule.field, rule.operator, { fieldData });
+	if (rule.valueSource && !getOption(configuredVSs, rule.valueSource)) return [...configuredVSs, {
+		name: rule.valueSource,
+		value: rule.valueSource,
+		label: rule.valueSource
+	}];
+	return configuredVSs;
+};
+/**
+* Normalizes the result of `getParameters` to a non-empty list or `null`.
+*/
+const getParametersAsList = (parameters) => parameters && parameters.length > 0 ? parameters : null;
+/**
+* The value editor type for a rule. `valueSource: "field"` always uses a select list, and
+* `valueSource: "parameter"` uses a (multi)select when parameters are available.
+*/
+const getRuleValueEditorType = (rule, fieldData, parametersAsList, getValueEditorType) => rule.valueSource === "field" ? "select" : rule.valueSource === "parameter" ? parametersAsList ? lc(rule.operator) === "in" || lc(rule.operator) === "notin" ? "multiselect" : "select" : "text" : getValueEditorType(rule.field, rule.operator, { fieldData });
+/**
+* The option list presented by a rule's value editor, resolved from its `valueSource`.
+*/
+const getRuleValues = (rule, fieldData, fields, parametersAsList, getValues) => {
+	const v = rule.valueSource === "field" ? filterFieldsByComparator(fieldData, fields, rule.operator) : rule.valueSource === "parameter" ? parametersAsList ?? [] : getValues(rule.field, rule.operator, { fieldData });
+	return isFlexibleOptionArray(v) || isFlexibleOptionGroupArray(v) ? toFullOptionList(v) : v;
+};
+/**
+* The validation result for a rule: the entry from a query-level {@link ValidationMap} if present,
+* otherwise the field's own `validator` result, otherwise `null`.
+*/
+const getRuleValidationResult = (rule, fieldData, validationMap = {}, id = rule.id ?? "") => validationMap[id] ?? (typeof fieldData.validator === "function" ? fieldData.validator(rule) : null);
+/**
+* Resolves everything about a single rule that depends on the field/operator configuration:
+* its field data, operators, value editor type, value list, value sources, match modes, and
+* validation result.
+*
+* This is the framework-agnostic core of the `useRule` hook, shared with
+* {@link QueryManager.getRuleContext} so that non-React implementations derive identical results.
+* It performs no memoization; callers are responsible for caching as appropriate.
+*
+* @group Query Tools
+*/
+const deriveRuleContext = (rule, resolvers, options = {}) => {
+	const { fields, fieldMap, getInputType, getMatchModes, getOperators, getParameters, getValueEditorType, getValues, getValueSources, getSubQueryBuilderProps } = resolvers;
+	const fieldData = getFieldData(rule.field, fieldMap);
+	const inputType = fieldData.inputType ?? getInputType(rule.field, rule.operator, { fieldData });
+	const matchModes = getMatchModes(rule.field, { fieldData });
+	const operators = getOperators(rule.field, { fieldData });
+	const operatorObject = getOption(operators, rule.operator);
+	const valueSourceOptions = getRuleValueSourceOptions(rule, fieldData, getValueSources);
+	const parameters = getParametersAsList(getParameters(rule.field, rule.operator, { fieldData }));
+	return {
+		fieldData,
+		hideValueControls: hideValueControlsForOperator(operatorObject),
+		inputType,
+		matchModes,
+		operatorObject,
+		operators,
+		parameters,
+		validationResult: getRuleValidationResult(rule, fieldData, options.validationMap, options.id),
+		valueEditorType: getRuleValueEditorType(rule, fieldData, parameters, getValueEditorType),
+		values: getRuleValues(rule, fieldData, fields, parameters, getValues),
+		valueSourceOptions,
+		valueSources: valueSourceOptions.map(({ value }) => value),
+		subQueryBuilderProps: getSubQueryBuilderProps?.(rule.field, { fieldData }) ?? {}
+	};
+};
+/**
+* The effective combinator for a group: its own `combinator` when it has one, otherwise the
+* first configured combinator (which is the case for groups with independent combinators).
+*
+* This intentionally covers only the current property-based API. The `RuleGroup` component
+* additionally falls back to its deprecated `combinator` prop; that fallback stays in the hook.
+*/
+const getRuleGroupCombinator = (ruleGroup, combinators) => isRuleGroupType(ruleGroup) ? ruleGroup.combinator : getFirstOption(combinators) ?? "";
+/**
+* Resolves everything about a rule group that depends on the combinator configuration, plus its
+* validation result.
+*
+* Note that unlike {@link deriveRuleContext}, there is no field-level validator fallback—a
+* group's validation result comes only from the query-level {@link ValidationMap}.
+*
+* @group Query Tools
+*/
+const deriveRuleGroupContext = (ruleGroup, combinators, options = {}) => {
+	const independentCombinators = isRuleGroupTypeIC(ruleGroup);
+	const combinator = getRuleGroupCombinator(ruleGroup, combinators);
+	const combinatorObject = getOption(combinators, combinator);
+	return {
+		combinator,
+		combinatorObject,
+		combinators,
+		combinatorBasedClassName: independentCombinators ? null : combinatorObject?.className ?? "",
+		independentCombinators,
+		validationResult: (options.validationMap ?? {})[options.id ?? ruleGroup.id ?? ""] ?? null
+	};
+};
+//#endregion
 //#region src/utils/parseNumber.ts
 /**
 * Converts a string to a number. Uses native `parseFloat` if `parseNumbers` is "native",
@@ -1123,6 +1453,104 @@ const parseNumber = (val, { parseNumbers, bigIntOnOverflow } = {}) => {
 	return typeof valAsNum === "bigint" || !Number.isNaN(valAsNum) ? valAsNum : val;
 };
 //#endregion
+//#region src/utils/deriveValueEditor.ts
+/** Operators whose value is a list rather than a single scalar. */
+const multiValueOperators = /* @__PURE__ */ new Set([
+	"between",
+	"notBetween",
+	"in",
+	"notIn"
+]);
+/**
+* Whether an operator's value is a list of two bounds.
+*
+* @group Value Editors
+*/
+const isBetweenOperator = (operator) => operator === "between" || operator === "notBetween";
+/**
+* Determines whether a rule's `value` needs to be collapsed to a single element because it no
+* longer represents a list, and what it should become.
+*
+* This happens when the value is an array (or a comma-containing string in a `number` input,
+* which `<input type="number">` can't display) while the operator is not one of the multi-value
+* operators and the editor is not a multiselect—typically right after the operator changes from
+* `"in"` or `"between"` to something else.
+*
+* The React `useValueEditor` hook applies the result in an effect; other implementations may
+* apply it wherever is idiomatic.
+*
+* @group Value Editors
+*/
+const getValueEditorReset = ({ skipHook, type, operator, value, inputType }) => {
+	return !skipHook && type !== "multiselect" && !multiValueOperators.has(operator) && (Array.isArray(value) || inputType === "number" && typeof value === "string" && value.includes(",")) ? {
+		reset: true,
+		value: toArray(value, { retainEmptyStrings: true })[0] ?? ""
+	} : {
+		reset: false,
+		value
+	};
+};
+/**
+* Produces the next value for a series of value editors when the editor at `index` changes.
+*
+* For `between`/`notBetween`, editing the first bound guarantees an array of at least two
+* elements, seeding the second from the first available option. The result is a comma-joined
+* string unless `listsAsArrays` is `true`.
+*
+* @group Value Editors
+*/
+const getMultiValueUpdate = ({ value, index, valueAsArray, operator, values, listsAsArrays, parseNumberMethod }) => {
+	const parsedVal = parseNumber(value, { parseNumbers: parseNumberMethod });
+	const needsBetweenFix = index === 0 && isBetweenOperator(operator) && (valueAsArray.length < 2 || valueAsArray[1] === void 0);
+	if (valueAsArray[index] === parsedVal && !needsBetweenFix) return listsAsArrays ? valueAsArray : joinWith(valueAsArray, ",");
+	const v = [...valueAsArray];
+	v[index] = parsedVal;
+	if (needsBetweenFix) v[1] = getFirstOption(values) ?? "";
+	return listsAsArrays ? v : joinWith(v, ",");
+};
+/**
+* Coerces a value to a `bigint`, falling back to the parsed number when it can't be represented
+* as one (an empty string or a decimal, for example).
+*
+* @group Value Editors
+*/
+const coerceBigIntValue = (value, parseNumberMethod) => {
+	const valAsMaybeNumber = parseNumber(value, {
+		parseNumbers: parseNumberMethod,
+		bigIntOnOverflow: true
+	});
+	try {
+		return BigInt(valAsMaybeNumber);
+	} catch {
+		return valAsMaybeNumber;
+	}
+};
+/**
+* The `type` attribute an `<input>` should use for a rule. `bigint` values and the `in`/`notIn`
+* operators (whose value is a comma-separated list) both require a text input.
+*
+* @group Value Editors
+*/
+const coerceInputType = (inputType, operator) => inputType === "bigint" || operator === "in" || operator === "notIn" ? "text" : inputType || "text";
+/**
+* Produces the next value for a value selector. Multiselect values are normalized to an array
+* first, then comma-joined unless `listsAsArrays` is `true`. Single-select values pass through.
+*
+* @group Value Editors
+*/
+const getValueSelectorUpdate = (value, { multiple, listsAsArrays } = {}) => {
+	if (!multiple) return value;
+	const valueAsArray = toArray(value);
+	return listsAsArrays ? valueAsArray : joinWith(valueAsArray, ",");
+};
+/**
+* Normalizes a value selector's current value for display. Multiselect values become an array of
+* strings so they match option names, which are always strings (e.g. `[42]` becomes `["42"]`).
+*
+* @group Value Editors
+*/
+const normalizeValueSelectorValue = (value, multiple) => multiple ? toArray(value).map(String) : value;
+//#endregion
 //#region src/utils/transformQuery.ts
 const remapProperties = (obj, propertyMap, deleteRemappedProperties) => {
 	const result = {};
@@ -1469,7 +1897,9 @@ const translationMatchFilter = (key, keyToTest, conditions) => keyToTest.startsW
 *
 * @group Export
 */
-const getNLTranslataion = (key, translations, conditions = []) => conditions.length === 0 ? translations[key] ?? defaultNLTranslations[key] ?? "" : Object.entries(translations).find(([keyToTest]) => translationMatchFilter(key, keyToTest, conditions))?.[1] ?? Object.entries(defaultNLTranslations).find(([keyToTest]) => translationMatchFilter(key, keyToTest, conditions))?.[1] ?? defaultNLTranslations[key] ?? "";
+const getNLTranslataion = (key, translations, conditions = []) => conditions.length === 0 ? translations[key] ?? defaultNLTranslations[key] ?? 
+/* v8 ignore start -- @preserve */ "" : Object.entries(translations).find(([keyToTest]) => translationMatchFilter(key, keyToTest, conditions))?.[1] ?? Object.entries(defaultNLTranslations).find(([keyToTest]) => translationMatchFilter(key, keyToTest, conditions))?.[1] ?? defaultNLTranslations[key] ?? 
+/* v8 ignore next -- @preserve */ "";
 /**
 * Transforms
 * - `match: { mode: "atLeast", threshold: 1 }` to `match: { mode: "some" }`
@@ -1495,6 +1925,21 @@ const processMatchMode = (rule) => {
 	};
 };
 /**
+* Base alias assigned to the element binding of a subquery generated for a rule's
+* {@link MatchMode `match` mode} (e.g. `unnest(field) as elem_alias`).
+*/
+const subqueryElementAliasBase = "elem_alias";
+/**
+* Returns the element alias for a subquery at the given nesting depth. Depth 0 (the common,
+* non-nested case) uses {@link subqueryElementAliasBase} unchanged; deeper levels are suffixed
+* with the depth, so a subquery nested within a subquery cannot shadow its parent's binding.
+*
+* Deterministic by depth rather than randomized, so output remains stable and snapshot-friendly.
+*
+* @group Export
+*/
+const getSubqueryElementAlias = (subqueryDepth = 0) => subqueryDepth > 0 ? `${subqueryElementAliasBase}_${subqueryDepth}` : subqueryElementAliasBase;
+/**
 * "Replacer" method for JSON.stringify's second argument. Converts `bigint` values to
 * objects with a `$bigint` property having a value of a string representation of
 * the actual `bigint`-type value.
@@ -1523,7 +1968,7 @@ const bigIntJsonParseReviver = (_key, value) => isPojo(value) && Object.keys(val
 const defaultRuleGroupProcessorCEL = (ruleGroup, options) => {
 	const { fields, fallbackExpression, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, validateRule, validationMap } = options;
 	const processRuleGroup = (rg, outermost) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermost ? fallbackExpression : "";
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return outermost ? fallbackExpression : "";
 		const processedRules = [];
 		let precedingCombinator = "";
 		let firstRule = true;
@@ -1587,11 +2032,16 @@ const defaultRuleProcessorCEL = (rule, opts = {}) => {
 	if (matchEval === false) return "";
 	else if (matchEval) {
 		const { mode, threshold } = matchEval;
-		const arrayElementAlias = "elem_alias";
-		const nestedArrayFilter = defaultRuleGroupProcessorCEL(transformQuery(rule.value, { ruleProcessor: (r) => ({
+		const subqueryDepth = opts.subqueryDepth ?? 0;
+		const arrayElementAlias = getSubqueryElementAlias(subqueryDepth);
+		const celQuery = transformQuery(rule.value, { ruleProcessor: (r) => ({
 			...r,
 			field: `${arrayElementAlias}${r.field ? `.${r.field}` : ""}`
-		}) }), opts);
+		}) });
+		const nestedArrayFilter = defaultRuleGroupProcessorCEL(celQuery, {
+			...opts,
+			subqueryDepth: subqueryDepth + 1
+		});
 		switch (mode) {
 			case "all": return `${field}.all(${arrayElementAlias}, ${nestedArrayFilter})`;
 			case "none":
@@ -1665,7 +2115,7 @@ const defaultRuleGroupProcessorMongoDBQuery = (ruleGroup, options, meta) => {
 	const { context, fields, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, validateRule, validationMap } = options;
 	const { inExpressionContext } = context ?? {};
 	const processRuleGroup = (rg, outermost) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermost ? mongoDbFallback : false;
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return outermost ? mongoDbFallback : false;
 		const combinator = `$${lc(rg.combinator)}`;
 		let hasChildRules = false;
 		const expressions = rg.rules.map((rule) => {
@@ -1843,7 +2293,7 @@ const defaultRuleProcessorMongoDB = (rule, options) => {
 const defaultRuleGroupProcessorSpEL = (ruleGroup, options) => {
 	const { fields, fallbackExpression, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, validateRule, validationMap } = options;
 	const processRuleGroup = (rg, outermost) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermost ? fallbackExpression : "";
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return outermost ? fallbackExpression : "";
 		const processedRules = [];
 		let precedingCombinator = "";
 		let firstRule = true;
@@ -2084,7 +2534,7 @@ const cypherCombinatorMap = {
 const defaultRuleGroupProcessorCypher = (ruleGroup, options) => {
 	const { fields, fallbackExpression, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, validateRule, validationMap } = options;
 	const processRuleGroup = (rg, outermost) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermost ? fallbackExpression : "";
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return outermost ? fallbackExpression : "";
 		const processedRules = [];
 		let precedingCombinator = "";
 		let firstRule = true;
@@ -2148,7 +2598,7 @@ const defaultRuleGroupProcessorDrizzle = (ruleGroup, options, _meta) => (columns
 	if (!columns || !drizzleOperators) return void 0;
 	const { and, not, or } = drizzleOperators;
 	const processRuleGroup = (rg, _outermost) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return;
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return;
 		const processedRules = rg.rules.map((rule) => {
 			if (isRuleGroup(rule)) return processRuleGroup(rule);
 			const [validationResult, fieldValidator] = validateRule(rule);
@@ -2181,7 +2631,7 @@ const defaultRuleGroupProcessorDrizzle = (ruleGroup, options, _meta) => (columns
 const defaultRuleGroupProcessorElasticSearch = (ruleGroup, options) => {
 	const { fields, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, validateRule, validationMap } = options;
 	const processRuleGroup = (rg) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return false;
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return false;
 		const processedRules = rg.rules.map((rule) => {
 			if (isRuleGroup(rule)) return processRuleGroup(rule);
 			const [validationResult, fieldValidator] = validateRule(rule);
@@ -2216,7 +2666,9 @@ const defaultRuleGroupProcessorGremlin = (ruleGroup, options) => {
 		// v8 ignore next -- @preserve
 		if (typeof rule === "string" || isRuleGroup(rule)) return void 0;
 		const [validationResult, fieldValidator] = validateRule(rule);
-		if (!isRuleOrGroupValid(rule, validationResult, fieldValidator) || rule.field === placeholderFieldName || rule.operator === placeholderOperatorName || placeholderValueName !== void 0 && rule.value === placeholderValueName) return;
+		if (!isRuleOrGroupValid(rule, validationResult, fieldValidator) || 
+		/* v8 ignore next 2 -- @preserve */
+		rule.field === placeholderFieldName || rule.operator === placeholderOperatorName || placeholderValueName !== void 0 && rule.value === placeholderValueName) return;
 		const fieldData = getOption(fields, rule.field);
 		return ruleProcessor(rule, {
 			...options,
@@ -2227,7 +2679,7 @@ const defaultRuleGroupProcessorGremlin = (ruleGroup, options) => {
 	};
 	/** Recursively processes a nested group into `.and()`/`.or()`/`.not()` form. */
 	const processNested = (rg) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return "";
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return "";
 		const predicates = [];
 		for (const rule of rg.rules) {
 			if (typeof rule === "string") continue;
@@ -2245,7 +2697,7 @@ const defaultRuleGroupProcessorGremlin = (ruleGroup, options) => {
 		if (predicates.length === 1 && !rg.not) return predicates[0];
 		return `.${prefix}(${predicates.map((p) => p.startsWith(".") ? `__${p}` : p).join(", ")})`;
 	};
-	if (!isRuleOrGroupValid(ruleGroup, validationMap[ruleGroup.id ?? ""])) return fallbackExpression;
+	if (!isRuleOrGroupValid(ruleGroup, validationMap[ruleGroup.id ?? /* v8 ignore start -- @preserve */ ""])) return fallbackExpression;
 	const steps = [];
 	for (const rule of ruleGroup.rules) {
 		if (typeof rule === "string") continue;
@@ -2270,7 +2722,7 @@ const defaultRuleGroupProcessorGremlin = (ruleGroup, options) => {
 const defaultRuleGroupProcessorJSONata = (ruleGroup, options) => {
 	const { fields, fallbackExpression, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, validateRule, validationMap } = options;
 	const processRuleGroup = (rg, outermost) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermost ? fallbackExpression : "";
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return outermost ? fallbackExpression : "";
 		const processedRules = [];
 		let precedingCombinator = "";
 		let firstRule = true;
@@ -2326,7 +2778,7 @@ const defaultRuleGroupProcessorJsonLogic = (ruleGroup, options) => {
 	const { fields, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, validateRule, validationMap } = options;
 	const query = convertFromIC(ruleGroup);
 	const processRuleGroup = (rg, _outermost) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return false;
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return false;
 		const processedRules = rg.rules.map((rule) => {
 			if (isRuleGroup(rule)) return processRuleGroup(rule);
 			const [validationResult, fieldValidator] = validateRule(rule);
@@ -2354,7 +2806,7 @@ const defaultRuleGroupProcessorJsonLogic = (ruleGroup, options) => {
 const defaultRuleGroupProcessorLDAP = (ruleGroup, options) => {
 	const { fields, fallbackExpression, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, validateRule, validationMap } = options;
 	const processRuleGroup = (rg, outermost) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermost ? fallbackExpression : "";
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return outermost ? fallbackExpression : "";
 		const rules = rg.rules.map((rule) => {
 			if (isRuleGroup(rule)) return processRuleGroup(rule);
 			const [validationResult, fieldValidator] = validateRule(rule);
@@ -2387,7 +2839,7 @@ const isBracketed = (str) => str.startsWith("{") && str.endsWith("}");
 const defaultRuleGroupProcessorMongoDB = (ruleGroup, options, meta) => {
 	const { fields, fallbackExpression, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, validateRule, validationMap } = options;
 	const processRuleGroup = (rg, outermost) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermost ? fallbackExpression : "";
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return outermost ? fallbackExpression : "";
 		const combinator = `"$${lc(rg.combinator)}"`;
 		let hasChildRules = false;
 		const expressions = rg.rules.map((rule) => {
@@ -2424,7 +2876,7 @@ const defaultRuleGroupProcessorMongoDB = (ruleGroup, options, meta) => {
 const defaultRuleGroupProcessorNL = (ruleGroup, options) => {
 	const { fields, fallbackExpression, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, translations, validateRule, validationMap } = options;
 	const processRuleGroup = (rg, outermostOrLonelyInGroup) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermostOrLonelyInGroup ? fallbackExpression : "";
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return outermostOrLonelyInGroup ? fallbackExpression : "";
 		const rg2 = isRuleGroupTypeIC(rg) && rg.rules.some((r) => typeof r === "string" && lc(r) === "xor") ? convertFromIC(rg) : rg;
 		const processedRules = [];
 		let precedingCombinator = "";
@@ -2435,7 +2887,8 @@ const defaultRuleGroupProcessorNL = (ruleGroup, options) => {
 				continue;
 			}
 			if (isRuleGroup(rule)) {
-				const processedGroup = processRuleGroup(rule, rg2.rules.length === 1 && !(rg2.not || /^xor$/i.test(rg2.combinator ?? "")));
+				const processedGroup = processRuleGroup(rule, rg2.rules.length === 1 && !(rg2.not || /^xor$/i.test(rg2.combinator ?? 
+				/* v8 ignore start -- @preserve */ "")));
 				// v8 ignore else
 				if (processedGroup) {
 					if (!firstRule && precedingCombinator) {
@@ -2522,7 +2975,7 @@ const defaultRuleGroupProcessorParameterized = (ruleGroup, options) => {
 		return sql;
 	};
 	const processRuleGroup = (rg, outermostOrLonelyInGroup) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermostOrLonelyInGroup ? fallbackExpression : "";
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return outermostOrLonelyInGroup ? fallbackExpression : "";
 		const processedRules = [];
 		let precedingCombinator = "";
 		let firstRule = true;
@@ -2582,7 +3035,7 @@ const prismaFallback = {};
 const defaultRuleGroupProcessorPrisma = (ruleGroup, options) => {
 	const { fields, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, validateRule, validationMap } = options;
 	const processRuleGroup = (rg, outermost) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermost ? prismaFallback : void 0;
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return outermost ? prismaFallback : void 0;
 		const combinator = rg.combinator.toUpperCase();
 		let hasChildRules = false;
 		const expressions = rg.rules.map((rule) => {
@@ -2621,7 +3074,7 @@ const defaultRuleGroupProcessorSequelize = (ruleGroup, options) => {
 	const { sequelizeOperators: Op } = context;
 	if (!Op) return void 0;
 	const processRuleGroup = (rg, _outermost) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return;
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return;
 		const combinator = rg.combinator.toUpperCase();
 		let hasChildRules = false;
 		const expressions = rg.rules.map((rule) => {
@@ -2660,7 +3113,7 @@ const defaultRuleGroupProcessorSequelize = (ruleGroup, options) => {
 const defaultRuleGroupProcessorSPARQL = (ruleGroup, options) => {
 	const { fields, fallbackExpression, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, validateRule, validationMap } = options;
 	const processRuleGroup = (rg, outermost) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermost ? fallbackExpression : "";
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return outermost ? fallbackExpression : "";
 		const processedRules = [];
 		let precedingCombinator = "";
 		let firstRule = true;
@@ -2715,7 +3168,7 @@ const defaultRuleGroupProcessorSPARQL = (ruleGroup, options) => {
 const defaultRuleGroupProcessorSQL = (ruleGroup, options) => {
 	const { fields, fallbackExpression, getParseNumberBoolean, placeholderFieldName, placeholderOperatorName, placeholderValueName, ruleProcessor, validateRule, validationMap } = options;
 	const processRuleGroup = (rg, outermostOrLonelyInGroup) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return outermostOrLonelyInGroup ? fallbackExpression : "";
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return outermostOrLonelyInGroup ? fallbackExpression : "";
 		const processedRules = [];
 		let precedingCombinator = "";
 		let firstRule = true;
@@ -2783,7 +3236,7 @@ const defaultRuleGroupProcessorTanStackDB = (ruleGroup, options) => (refs) => {
 	/* v8 ignore next -- @preserve */
 	if (refKeys.length === 0) return fallback;
 	const processRuleGroup = (rg) => {
-		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? ""])) return;
+		if (!isRuleOrGroupValid(rg, validationMap[rg.id ?? /* v8 ignore start -- @preserve */ ""])) return;
 		const processedRules = rg.rules.map((rule) => {
 			if (isRuleGroup(rule)) return processRuleGroup(rule);
 			const [validationResult, fieldValidator] = validateRule(rule);
@@ -3186,7 +3639,7 @@ const defaultRuleProcessorCypher = (rule, opts = {}) => {
 * @group Export
 */
 const defaultRuleProcessorDrizzle = (rule, _options) => {
-	const opts = _options ?? (	/* v8 ignore start -- @preserve */ {});
+	const opts = _options ?? /* v8 ignore start -- @preserve */ {};
 	// v8 ignore next
 	const { parseNumbers, preserveValueOrder, context = {} } = opts;
 	const { columns, drizzleOperators, useRawFields } = context;
@@ -3207,16 +3660,19 @@ const defaultRuleProcessorDrizzle = (rule, _options) => {
 	else if (matchEval) {
 		if (opts.preset !== "postgresql") return void 0;
 		const { mode, threshold } = matchEval;
-		const arrayElementAlias = "elem_alias";
-		const nestedArrayFilter = defaultRuleGroupProcessorDrizzle(transformQuery(rule.value, { ruleProcessor: (r) => ({
+		const subqueryDepth = opts.subqueryDepth ?? 0;
+		const arrayElementAlias = getSubqueryElementAlias(subqueryDepth);
+		const sqlQuery = transformQuery(rule.value, { ruleProcessor: (r) => ({
 			...r,
 			field: arrayElementAlias
-		}) }), {
+		}) });
+		const nestedArrayFilter = defaultRuleGroupProcessorDrizzle(sqlQuery, {
 			...opts,
 			context: {
 				...opts.context,
 				useRawFields: true
-			}
+			},
+			subqueryDepth: subqueryDepth + 1
 		});
 		switch (mode) {
 			case "all": return sql`(select count(*) from unnest(${column}) as ${sql.raw(arrayElementAlias)} where ${nestedArrayFilter({}, drizzleOperators)}) = array_length(${column}, 1)`;
@@ -3749,7 +4205,7 @@ const defaultValueProcessorNL = (rule, opts = {}) => {
 	const { escapeQuotes, fields, parseNumbers, quoteFieldNamesWith, quoteValuesWith, fieldIdentifierSeparator, translations } = opts;
 	const valueIsField = rule.valueSource === "field";
 	const operatorLowerCase = lc(rule.operator);
-	const quoteChar = quoteValuesWith || "'";
+	const quoteChar = quoteValuesWith || /* v8 ignore start -- @preserve */ "'";
 	const quoteValue = (v) => `${quoteChar}${v}${quoteChar}`;
 	const escapeValue = (v) => escapeStringValueQuotes(v, quoteChar, escapeQuotes);
 	const wrapAndEscape = (v) => quoteValue(escapeValue(v));
@@ -3757,7 +4213,7 @@ const defaultValueProcessorNL = (rule, opts = {}) => {
 		quoteFieldNamesWith,
 		fieldIdentifierSeparator
 	});
-	const t = translations ?? (	/* v8 ignore start -- @preserve */ {});
+	const t = translations ?? /* v8 ignore start -- @preserve */ {};
 	const orTL = t.or ?? "or";
 	const trueTL = t.true ?? "true";
 	const falseTL = t.false ?? "false";
@@ -3769,7 +4225,8 @@ const defaultValueProcessorNL = (rule, opts = {}) => {
 		case "between":
 		case "notbetween": {
 			if (!valueIsField) return defaultValueProcessorByRule(rule, opts);
-			const valueAsArray = toArray(rule.value, { retainEmptyStrings: true }).slice(0, 2).map((v) => wrapFieldName(getOption(fields ?? [], v)?.label ?? v));
+			const valueAsArray = toArray(rule.value, { retainEmptyStrings: true }).slice(0, 2).map((v) => wrapFieldName(getOption(fields ?? 
+			/* v8 ignore start -- @preserve */ [], v)?.label ?? v));
 			if (valueAsArray.length < 2 || !isValidValue(valueAsArray[0]) || !isValidValue(valueAsArray[1])) return "";
 			return defaultValueProcessorByRule({
 				...rule,
@@ -3780,14 +4237,16 @@ const defaultValueProcessorNL = (rule, opts = {}) => {
 		case "notin": {
 			const valueAsArray = toArray(rule.value);
 			if (valueAsArray.length === 0) return "";
-			const valStringArray = valueAsArray.map((v) => valueIsField ? wrapFieldName(getOption(fields ?? [], v)?.label ?? v) : shouldRenderAsNumber(v, parseNumbers) ? `${trimIfString(v)}` : `${wrapAndEscape(v)}`);
+			const valStringArray = valueAsArray.map((v) => valueIsField ? wrapFieldName(getOption(fields ?? 
+			/* v8 ignore start -- @preserve */ [], v)?.label ?? v) : shouldRenderAsNumber(v, parseNumbers) ? `${trimIfString(v)}` : `${wrapAndEscape(v)}`);
 			if (valStringArray.length === 1) return valStringArray[0];
 			const oxfordComma = useOxfordComma && valStringArray.length > 2 ? "," : "";
 			return `(${`${valStringArray.slice(0, -1).join(listSep)}${oxfordComma} ${orTL} ${valStringArray.at(-1)}`})`;
 		}
 	}
 	if (typeof rule.value === "boolean") return rule.value ? trueTL : falseTL;
-	return valueIsField ? wrapFieldName(getOption(fields ?? [], rule.value)?.label ?? rule.value) : shouldRenderAsNumber(rule.value, parseNumbers) ? `${trimIfString(rule.value)}` : `${wrapAndEscape(rule.value)}`;
+	return valueIsField ? wrapFieldName(getOption(fields ?? 
+	/* v8 ignore start -- @preserve */ [], rule.value)?.label ?? rule.value) : shouldRenderAsNumber(rule.value, parseNumbers) ? `${trimIfString(rule.value)}` : `${wrapAndEscape(rule.value)}`;
 };
 //#endregion
 //#region src/utils/formatQuery/defaultRuleProcessorNL.ts
@@ -3839,7 +4298,7 @@ const defaultOperatorProcessorNL = (rule, opts = {}) => {
 		name: field,
 		value: field,
 		label: field
-	} }) ?? []), normalizedOperator) ?? {
+	} }) ?? /* v8 ignore start -- @preserve */ []), normalizedOperator) ?? {
 		name: normalizedOperator,
 		value: normalizedOperator,
 		label: normalizedOperator
@@ -3855,7 +4314,7 @@ const defaultOperatorProcessorNL = (rule, opts = {}) => {
 const defaultRuleProcessorNL = (rule, opts) => {
 	const { field, operator } = rule;
 	// v8 ignore next
-	const { fieldData, quoteFieldNamesWith = ["", ""], fieldIdentifierSeparator = "", quoteValuesWith = `'`, operatorProcessor = defaultOperatorProcessorNL, valueProcessor = defaultValueProcessorNL, concatOperator = "||", wordOrder = "SVO" } = opts ?? (	/* v8 ignore start -- @preserve */ {});
+	const { fieldData, quoteFieldNamesWith = ["", ""], fieldIdentifierSeparator = "", quoteValuesWith = `'`, operatorProcessor = defaultOperatorProcessorNL, valueProcessor = defaultValueProcessorNL, concatOperator = "||", wordOrder = "SVO" } = opts ?? /* v8 ignore start -- @preserve */ {};
 	const processedField = getQuotedFieldName(fieldData?.label ?? field, {
 		quoteFieldNamesWith,
 		fieldIdentifierSeparator
@@ -3930,11 +4389,15 @@ const defaultRuleProcessorSQL = (rule, opts = {}) => {
 	else if (matchEval) {
 		if (opts?.preset !== "postgresql") return "";
 		const { mode, threshold } = matchEval;
-		const arrayElementAlias = "elem_alias";
+		const subqueryDepth = opts.subqueryDepth ?? 0;
+		const arrayElementAlias = getSubqueryElementAlias(subqueryDepth);
 		const nestedArrayFilter = defaultRuleGroupProcessorSQL(transformQuery(rule.value, { ruleProcessor: (r) => ({
 			...r,
 			field: arrayElementAlias
-		}) }), opts);
+		}) }), {
+			...opts,
+			subqueryDepth: subqueryDepth + 1
+		});
 		switch (mode) {
 			case "all": return `(select count(*) from unnest(${ruleField}) as ${wrapFieldName(arrayElementAlias)} where ${nestedArrayFilter}) = array_length(${ruleField}, 1)`;
 			case "none": return `not exists (select 1 from unnest(${ruleField}) as ${wrapFieldName(arrayElementAlias)} where ${nestedArrayFilter})`;
@@ -3992,13 +4455,15 @@ const defaultRuleProcessorParameterized = (rule, opts, meta) => {
 	else if (matchEval) {
 		if (opts?.preset !== "postgresql") return finalize("");
 		const { mode, threshold } = matchEval;
-		const arrayElementAlias = "elem_alias";
+		const subqueryDepth = opts.subqueryDepth ?? 0;
+		const arrayElementAlias = getSubqueryElementAlias(subqueryDepth);
 		const { sql: nestedSQL, params: nestedParams } = defaultRuleGroupProcessorParameterized(transformQuery(rule.value, { ruleProcessor: (r) => ({
 			...r,
 			field: arrayElementAlias
 		}) }), {
 			...opts,
-			fields: []
+			fields: [],
+			subqueryDepth: subqueryDepth + 1
 		});
 		if (Array.isArray(nestedParams)) params.push(...nestedParams);
 		else Object.assign(paramsNamed, nestedParams);
@@ -4070,7 +4535,7 @@ const defaultRuleProcessorParameterized = (rule, opts, meta) => {
 	}
 	let paramValue = rule.value;
 	if (typeof rule.value === "string") if (shouldRenderAsNumber(rule.value, parseNumbers)) paramValue = parseNumber(rule.value, { parseNumbers });
-	else paramValue = /^'.*'$/g.test(value) ? value.replaceAll(/(^'|'$)/g, "") : 	/* v8 ignore next -- @preserve */ value;
+	else paramValue = /^'.*'$/g.test(value) ? value.replaceAll(/(^'|'$)/g, "") : /* v8 ignore next -- @preserve */ value;
 	let paramName = "";
 	if (parameterized) params.push(paramValue);
 	else {
@@ -4287,7 +4752,7 @@ const defaultRuleProcessorSPARQL = (rule, opts = {}) => {
 * @group Export
 */
 const defaultRuleProcessorTanStackDB = (rule, _options) => {
-	const { parseNumbers, preserveValueOrder, context = {} } = _options ?? (	/* v8 ignore start -- @preserve */ {});
+	const { parseNumbers, preserveValueOrder, context = {} } = _options ?? /* v8 ignore start -- @preserve */ {};
 	const ops = context.tanStackDbOperators;
 	const refs = context._tanstackDbRefs;
 	const primaryRef = context._tanstackDbPrimaryRef;
@@ -4523,7 +4988,8 @@ function formatQuery(ruleGroup, optionParam = {}) {
 	const ruleProcessor = (typeof ruleProcessor_option === "function" ? ruleProcessor_option : null) ?? (valueProcessorCanActAsRuleProcessor.has(format) && typeof ruleProcessor_option !== "function" && valueProcessor_option ? valueProcessor : null) ?? defaultRuleProcessors[format] ?? defaultRuleProcessorSQL;
 	const quoteFieldNamesWith = getQuoteFieldNamesWithArray(quoteFieldNamesWith_option);
 	const fields = toFullOptionList(optObj.fields);
-	const getOperators = (f, m) => toFullOptionList(getOperators_option(f, m) ?? []);
+	const getOperators = (f, m) => toFullOptionList(getOperators_option(f, m) ?? 
+	/* v8 ignore start -- @preserve */ []);
 	const fallbackExpression = fallbackExpression_option ?? defaultFallbackExpressions[format] ?? defaultFallbackExpressions.sql;
 	let validationMap = {};
 	// v8 ignore else
@@ -4546,7 +5012,7 @@ function formatQuery(ruleGroup, optionParam = {}) {
 	const uniqueFields = toFlatOptionArray(fields);
 	for (const f of uniqueFields)
  // v8 ignore else
-	if (typeof f.validator === "function") validatorMap[f.value ?? f.name] = f.validator;
+	if (typeof f.validator === "function") validatorMap[f.value ?? /* v8 ignore start -- @preserve */ f.name] = f.validator;
 	const validateRule = (rule) => {
 		let validationResult;
 		let fieldValidator;
@@ -4717,12 +5183,20 @@ const getParentPath = (path) => path.slice(0, -1);
 /**
 * Determines if two paths (each `Path`) are equivalent.
 */
-const pathsAreEqual = (path1, path2) => path1.length === path2.length && path1.every((val, idx) => val === path2[idx]);
+const pathsAreEqual = (path1, path2) => {
+	if (path1.length !== path2.length) return false;
+	for (let i = 0; i < path1.length; i++) if (path1[i] !== path2[i]) return false;
+	return true;
+};
 /**
 * Determines if the first path is an ancestor of the second path. The first path must
 * be shorter and exactly match the second path up through the length of the first path.
 */
-const isAncestor = (maybeAncestor, path) => maybeAncestor.length < path.length && new RegExp(`^${maybeAncestor.join("-")}`).test(path.join("-"));
+const isAncestor = (maybeAncestor, path) => {
+	if (maybeAncestor.length >= path.length) return false;
+	for (let i = 0; i < maybeAncestor.length; i++) if (maybeAncestor[i] !== path[i]) return false;
+	return true;
+};
 /**
 * Finds the deepest/longest path that two paths have in common.
 */
@@ -4755,11 +5229,38 @@ const pathIsDisabled = (path, query) => {
 	}
 	return disabled;
 };
+/**
+* Determines if the rule or group at the specified path is disabled by `disabledPaths`—the array
+* form of the `QueryBuilder` `disabled` prop, which disables nodes by position rather than by a
+* `disabled` property on the node itself. A path is disabled if it appears in `disabledPaths` or
+* descends from a path that does.
+*
+* @group Paths
+*/
+const pathIsDisabledByPaths = (path, disabledPaths = []) => disabledPaths.some((p) => pathsAreEqual(p, path) || isAncestor(p, path));
+/**
+* Builds the {@link PathInfo} for each child of a group at `path`. A child is disabled if its
+* parent is disabled or if its own path appears in `disabledPaths`.
+*
+* @group Paths
+*/
+const derivePathInfo = (path, childCount, { disabled = false, disabledPaths = [] } = {}) => {
+	const paths = [];
+	for (let i = 0; i < childCount; i++) {
+		const thisPath = [...path, i];
+		paths[i] = {
+			path: thisPath,
+			disabled: disabled || disabledPaths.some((p) => pathsAreEqual(thisPath, p))
+		};
+	}
+	return paths;
+};
 //#endregion
 //#region src/utils/generateAccessibleDescription.ts
 const generateAccessibleDescription = (params) => pathsAreEqual([], params.path) ? `Query builder` : `Rule group at path ${params.path.join("-")}`;
 //#endregion
 //#region src/utils/generateID.ts
+/* v8 ignore file -- this is fine */
 const cryptoModule = globalThis.crypto;
 const uuidV4regex = /^[\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ab][\da-f]{3}-[\da-f]{12}$/i;
 /**
@@ -4808,7 +5309,7 @@ const dummyFD$1 = {
 * `FullOption<MatchMode>[]` of all match modes by default.
 */
 const getMatchModesUtil = (fieldData, getMatchModes) => {
-	const fd = fieldData ? toFullOption(fieldData) : 	/* v8 ignore next -- @preserve */ dummyFD$1;
+	const fd = fieldData ? toFullOption(fieldData) : /* v8 ignore next -- @preserve */ dummyFD$1;
 	let matchModes = fd.matchModes ?? false;
 	if (!matchModes && getMatchModes) matchModes = getMatchModes(fd.value, { fieldData: fd });
 	if (matchModes === true) return defaultMatchModes;
@@ -4826,7 +5327,7 @@ const getFirstOptionsFrom = (opts, r, listsAsArrays) => {
 	const firstOption = getFirstOption(opts);
 	if (r.operator === "between" || r.operator === "notBetween") {
 		const valueAsArray = [firstOption, firstOption];
-		return listsAsArrays ? valueAsArray : joinWith(valueAsArray.map((v) => v ?? ""), ",");
+		return listsAsArrays ? valueAsArray : joinWith(valueAsArray.map((v) => v ?? /* v8 ignore start -- @preserve */ ""), ",");
 	}
 	return firstOption;
 };
@@ -4962,6 +5463,9 @@ const mergeClassnames = (...args) => ({
 	removeRule: joinClassnamesByName("removeRule", args),
 	notToggle: joinClassnamesByName("notToggle", args),
 	shiftActions: joinClassnamesByName("shiftActions", args),
+	undoRedoActions: joinClassnamesByName("undoRedoActions", args),
+	undoAction: joinClassnamesByName("undoAction", args),
+	redoAction: joinClassnamesByName("redoAction", args),
 	dragHandle: joinClassnamesByName("dragHandle", args),
 	lockRule: joinClassnamesByName("lockRule", args),
 	lockGroup: joinClassnamesByName("lockGroup", args),
@@ -4991,6 +5495,58 @@ const mergeClassnames = (...args) => ({
 	valueDateTimeRelative: joinClassnamesByName("valueDateTimeRelative", args)
 });
 //#endregion
+//#region src/utils/optionResolvers.ts
+/**
+* Resolves the operator list for a field, applying the same precedence as the `QueryBuilder`
+* component: the field's own `operators`, then the `getOperators` callback, then the
+* query-level operator list.
+*
+* @group Option Lists
+*/
+const resolveOperatorList = ({ field, fieldData, getOperators, operators, placeholder, baseOption, autoSelectOption }) => prepareOptionList({
+	optionList: fieldData?.operators ?? getOperators?.(field, { fieldData }) ?? operators,
+	placeholder,
+	baseOption,
+	labelMap: defaultOperatorLabelMap,
+	autoSelectOption
+}).optionList;
+/**
+* Resolves the default operator for a field, applying the same precedence as the `QueryBuilder`
+* component: the field's own `defaultOperator`, then the `getDefaultOperator` option (a string or
+* a function), then the first available operator.
+*
+* @group Option Lists
+*/
+const resolveDefaultOperator = ({ field, fieldData, getDefaultOperator, getOperators }) => {
+	if (fieldData?.defaultOperator) return fieldData.defaultOperator;
+	if (getDefaultOperator) return typeof getDefaultOperator === "function" ? getDefaultOperator(field, { fieldData }) : getDefaultOperator;
+	return getFirstOption(getOperators(field, { fieldData })) ?? "";
+};
+/**
+* Resolves the value editor type for a field/operator pair, applying the same precedence as the
+* `QueryBuilder` component: the field's own `valueEditorType` (a string or a function of the
+* operator), then the `getValueEditorType` callback, then `"text"`.
+*
+* @group Option Lists
+*/
+const resolveValueEditorType = ({ field, operator, fieldData, getValueEditorType }) => {
+	if (fieldData?.valueEditorType) return typeof fieldData.valueEditorType === "function" ? fieldData.valueEditorType(operator) : fieldData.valueEditorType;
+	return getValueEditorType?.(field, operator, { fieldData }) ?? "text";
+};
+/**
+* Resolves the value option list for a field/operator pair, applying the same precedence as the
+* `QueryBuilder` component: the field's own `values`, then the `getValues` callback, then an
+* empty list.
+*
+* @group Option Lists
+*/
+const resolveValueList = ({ field, operator, fieldData, getValues, placeholder, baseOption, autoSelectOption }) => prepareOptionList({
+	optionList: fieldData?.values ?? getValues?.(field, operator, { fieldData }) ?? [],
+	placeholder,
+	baseOption,
+	autoSelectOption
+}).optionList;
+//#endregion
 //#region src/utils/preferProp.ts
 const preferPropDefaultTrue = (prop, context) => prop === false ? false : prop ? true : !(context === false);
 const preferPropDefaultFalse = (prop, context) => prop ? true : prop === false ? false : !!context;
@@ -5055,6 +5611,21 @@ const prepareRuleGroup = (queryObject, { idGenerator = generateID } = {}) => {
 * Ensures that a rule or group is valid. See {@link prepareRule} and {@link prepareRuleGroup}.
 */
 const prepareRuleOrGroup = (rg, { idGenerator = generateID } = {}) => isRuleGroup(rg) ? prepareRuleGroup(rg, { idGenerator }) : prepareRule(rg, { idGenerator });
+/**
+* Resolves the query a query builder should render from the available sources, in precedence
+* order: the controlled `query`, then whatever is already in the store, then the uncontrolled
+* `defaultQuery`, then a freshly created empty group.
+*
+* The result is prepared with {@link prepareRuleGroup} unless it already has an `id`, which is
+* taken to mean it has been prepared before—most often because the caller is passing back the
+* object it received from `onQueryChange`.
+*
+* @group Query Tools
+*/
+const resolveCandidateQuery = (sources, options) => {
+	const candidateQuery = sources.query ?? sources.storeQuery ?? sources.defaultQuery ?? sources.fallbackQuery;
+	return candidateQuery.id ? candidateQuery : prepareRuleGroup(candidateQuery, options);
+};
 //#endregion
 //#region src/utils/regenerateIDs.ts
 /**
@@ -5084,6 +5655,28 @@ const regenerateIDs = (subject, { idGenerator = generateID } = {}) => {
 //#endregion
 //#region src/utils/queryTools.ts
 /**
+* Whether a mutation targeting `pathOrID` is blocked by the given guards, and why.
+* Returns `null` when the mutation may proceed.
+*
+* Exported so that callers which run their own logic before mutating—such as a UI layer that
+* invokes a confirmation callback—can apply the same rules without duplicating them.
+*
+* @group Query Tools
+*/
+const getGuardAbortReason = (query, pathOrID, guards = {}, { asParent = false } = {}) => {
+	if (guards.queryDisabled) return asParent ? "parent-disabled" : "target-disabled";
+	if (!guards.respectDisabled || pathOrID === void 0) return null;
+	const path = Array.isArray(pathOrID) ? pathOrID : getPathOfID(pathOrID, query);
+	if (path && (pathIsDisabled(path, query) || pathIsDisabledByPaths(path, guards.disabledPaths))) return asParent ? "parent-disabled" : "target-disabled";
+	return null;
+};
+/**
+* Whether adding a group beneath `parentPath` would exceed `maxLevels`.
+*
+* @group Query Tools
+*/
+const exceedsMaxLevels = (parentPath, { maxLevels = Infinity } = {}) => !!parentPath && parentPath.length >= maxLevels;
+/**
 * Adds a rule or group to a query without mutating the original query.
 *
 * @returns A new query with the rule or group added.
@@ -5099,9 +5692,42 @@ const add = (query, ruleOrGroup, parentPathOrID, options = {}) => produce(query,
 * @group Query Tools
 */
 const addInPlace = (query, ruleOrGroup, parentPathOrID, options = {}) => {
-	const { combinators = defaultCombinators, combinatorPreceding, idGenerator = generateID } = options;
+	const { combinators = defaultCombinators, combinatorPreceding, idGenerator = generateID, onAbort } = options;
 	const parent = Array.isArray(parentPathOrID) ? findPath(parentPathOrID, query) : findID(parentPathOrID, query);
-	if (!parent || !isRuleGroup(parent)) return query;
+	if (!parent) {
+		onAbort?.({
+			reason: "parent-not-found",
+			operation: "add",
+			pathOrID: parentPathOrID
+		});
+		return query;
+	}
+	if (!isRuleGroup(parent)) {
+		onAbort?.({
+			reason: "parent-not-a-group",
+			operation: "add",
+			pathOrID: parentPathOrID
+		});
+		return query;
+	}
+	const parentPath = Array.isArray(parentPathOrID) ? parentPathOrID : getPathOfID(parentPathOrID, query);
+	const addGuardReason = getGuardAbortReason(query, parentPath, options, { asParent: true });
+	if (addGuardReason) {
+		onAbort?.({
+			reason: addGuardReason,
+			operation: "add",
+			pathOrID: parentPathOrID
+		});
+		return query;
+	}
+	if (isRuleGroup(ruleOrGroup) && exceedsMaxLevels(parentPath, options)) {
+		onAbort?.({
+			reason: "max-levels-exceeded",
+			operation: "add",
+			pathOrID: parentPathOrID
+		});
+		return query;
+	}
 	if (isRuleGroupTypeIC(parent) && parent.rules.length > 0) {
 		const prevCombinator = parent.rules.at(-2);
 		parent.rules.push(combinatorPreceding ?? (typeof prevCombinator === "string" ? prevCombinator : getFirstOption(combinators)));
@@ -5122,7 +5748,7 @@ const updatePropRank = {
 	value: 4
 };
 /** Stable-sorts `[prop, value]` entries by {@link updatePropRank}. */
-const orderUpdateEntries = (entries) => entries.sort((x, y) => (updatePropRank[x[0]] ?? 3) - (updatePropRank[y[0]] ?? 3));
+const orderUpdateEntries = (entries) => entries.toSorted((x, y) => (updatePropRank[x[0]] ?? 3) - (updatePropRank[y[0]] ?? 3));
 /**
 * Normalizes the variadic {@link update}/{@link updateInPlace} arguments (single
 * prop+value, parallel arrays, or property map) into a canonically-ordered list
@@ -5185,19 +5811,69 @@ const updateInPlace = ((query, a, b, c, d) => applyUpdatesInPlace(query, a, b, c
 * Updates a single property of a rule or group within a query in place.
 */
 const updateInPlaceSingle = (query, prop, value, pathOrID, options = {}) => {
-	const { resetOnFieldChange: _resetOnFieldChange = true, resetOnOperatorChange = false, getRuleDefaultOperator = () => "=", getValueSources = () => ["value"], getRuleDefaultValue = () => "", getMatchModes = () => [] } = options;
+	const { resetOnFieldChange: _resetOnFieldChange = true, resetOnOperatorChange = false, getRuleDefaultOperator = () => "=", getValueSources = () => ["value"], getRuleDefaultValue = () => "", getMatchModes = () => [], onAbort } = options;
 	let resetOnFieldChange = _resetOnFieldChange;
 	const path = Array.isArray(pathOrID) ? pathOrID : getPathOfID(pathOrID, query);
-	if (!path) return query;
+	if (!path) {
+		onAbort?.({
+			reason: "target-not-found",
+			operation: "update",
+			pathOrID
+		});
+		return query;
+	}
+	const updateGuards = prop === "disabled" ? { queryDisabled: options.queryDisabled } : options;
+	const updateGuardReason = getGuardAbortReason(query, path, updateGuards);
+	if (updateGuardReason) {
+		onAbort?.({
+			reason: updateGuardReason,
+			operation: "update",
+			pathOrID
+		});
+		return query;
+	}
 	if (prop === "combinator" && !isRuleGroupType(query)) {
-		const parentRules = findPath(getParentPath(path), query).rules;
-		if (path.at(-1) % 2 === 1) parentRules[path.at(-1)] = value;
+		const parent = findPath(getParentPath(path), query);
+		if (!parent || !isRuleGroup(parent)) {
+			onAbort?.({
+				reason: "target-not-found",
+				operation: "update",
+				pathOrID
+			});
+			return query;
+		}
+		const parentRules = parent.rules;
+		if (path.at(-1) % 2 === 1) if (parentRules[path.at(-1)] === value) onAbort?.({
+			reason: "no-change",
+			operation: "update",
+			pathOrID
+		});
+		else parentRules[path.at(-1)] = value;
+		else onAbort?.({
+			reason: "not-a-combinator-slot",
+			operation: "update",
+			pathOrID
+		});
 		return query;
 	}
 	const ruleOrGroup = findPath(path, query);
-	if (!ruleOrGroup) return query;
+	if (!ruleOrGroup) {
+		onAbort?.({
+			reason: "target-not-found",
+			operation: "update",
+			pathOrID
+		});
+		return query;
+	}
 	const isGroup = isRuleGroup(ruleOrGroup);
-	if (ruleOrGroup[prop] === value) return query;
+	if (ruleOrGroup[prop] === value) {
+		onAbort?.({
+			reason: "no-change",
+			operation: "update",
+			pathOrID
+		});
+		return query;
+	}
 	if (prop !== "valueSource") ruleOrGroup[prop] = value;
 	if (isGroup) return query;
 	let resetValueSource = false;
@@ -5243,7 +5919,7 @@ const updateInPlaceSingle = (query, prop, value, pathOrID, options = {}) => {
 *
 * @group Query Tools
 */
-const remove = (query, pathOrID) => produce(query, (q) => removeInPlace(q, pathOrID));
+const remove = (query, pathOrID, options = {}) => produce(query, (q) => removeInPlace(q, pathOrID, options));
 /**
 * Removes a rule or group from a query in place.
 *
@@ -5251,12 +5927,45 @@ const remove = (query, pathOrID) => produce(query, (q) => removeInPlace(q, pathO
 *
 * @group Query Tools
 */
-const removeInPlace = (query, pathOrID) => {
+const removeInPlace = (query, pathOrID, options = {}) => {
+	const { onAbort } = options;
 	const path = Array.isArray(pathOrID) ? pathOrID : getPathOfID(pathOrID, query);
-	if (!path || path.length === 0 || !isRuleGroupType(query) && !findPath(path, query)) return query;
+	if (!path) {
+		onAbort?.({
+			reason: "target-not-found",
+			operation: "remove",
+			pathOrID
+		});
+		return query;
+	}
+	if (path.length === 0) {
+		onAbort?.({
+			reason: "root-not-allowed",
+			operation: "remove",
+			pathOrID
+		});
+		return query;
+	}
+	const removeGuardReason = getGuardAbortReason(query, path, options);
+	if (removeGuardReason) {
+		onAbort?.({
+			reason: removeGuardReason,
+			operation: "remove",
+			pathOrID
+		});
+		return query;
+	}
+	if (!findPath(path, query)) {
+		onAbort?.({
+			reason: "target-not-found",
+			operation: "remove",
+			pathOrID
+		});
+		return query;
+	}
 	const index = path.at(-1);
 	const parent = findPath(getParentPath(path), query);
-	if (parent && isRuleGroup(parent)) if (!isRuleGroupType(parent) && parent.rules.length > 1) {
+	if (!isRuleGroupType(parent) && parent.rules.length > 1) {
 		const idxStartDelete = index === 0 ? 0 : index - 1;
 		parent.rules.splice(idxStartDelete, 2);
 	} else parent.rules.splice(index, 1);
@@ -5281,7 +5990,8 @@ const getNextPath = (query, currentPath, newPathOrShiftDirection) => {
 		return [...getParentPath(parentPath), parentPath.at(-1) + 1];
 	} else {
 		const evaluationPath = [...getParentPath(currentPath), currentPath.at(-1) + (ic ? 2 : 1)];
-		if (isRuleGroup(findPath(evaluationPath, query))) return [...evaluationPath, 0];
+		const entityToEvaluate = findPath(evaluationPath, query);
+		if (isRuleGroup(entityToEvaluate)) return [...evaluationPath, 0];
 		else return [...getParentPath(currentPath), currentPath.at(-1) + (ic ? 3 : 2)];
 	}
 	return currentPath;
@@ -5304,13 +6014,67 @@ const move = (query, oldPathOrID, newPath, options = {}) => produce(query, (q) =
 * @group Query Tools
 */
 const moveInPlace = (query, oldPathOrID, newPath, options = {}) => {
-	const { clone = false, combinators = defaultCombinators, idGenerator = generateID } = options;
+	const { clone = false, combinators = defaultCombinators, idGenerator = generateID, onAbort } = options;
 	const oldPath = Array.isArray(oldPathOrID) ? oldPathOrID : getPathOfID(oldPathOrID, query);
-	if (!oldPath) return query;
-	const nextPath = getNextPath(query, oldPath, newPath);
-	if (oldPath.length === 0 || pathsAreEqual(oldPath, nextPath) || !findPath(getParentPath(nextPath), query)) return query;
+	if (!oldPath) {
+		onAbort?.({
+			reason: "target-not-found",
+			operation: "move",
+			pathOrID: oldPathOrID
+		});
+		return query;
+	}
 	const ruleOrGroupOriginal = findPath(oldPath, query);
-	if (!ruleOrGroupOriginal) return query;
+	if (!ruleOrGroupOriginal) {
+		onAbort?.({
+			reason: "target-not-found",
+			operation: "move",
+			pathOrID: oldPathOrID
+		});
+		return query;
+	}
+	const nextPath = getNextPath(query, oldPath, newPath);
+	if (oldPath.length === 0) {
+		onAbort?.({
+			reason: "root-not-allowed",
+			operation: "move",
+			pathOrID: oldPathOrID
+		});
+		return query;
+	}
+	const moveGuardReason = getGuardAbortReason(query, oldPath, options);
+	if (moveGuardReason) {
+		onAbort?.({
+			reason: moveGuardReason,
+			operation: "move",
+			pathOrID: oldPathOrID
+		});
+		return query;
+	}
+	if (pathsAreEqual(oldPath, nextPath)) {
+		onAbort?.({
+			reason: "same-location",
+			operation: "move",
+			pathOrID: oldPathOrID
+		});
+		return query;
+	}
+	if (!findPath(getParentPath(nextPath), query)) {
+		onAbort?.({
+			reason: "destination-not-found",
+			operation: "move",
+			pathOrID: newPath
+		});
+		return query;
+	}
+	if (!clone && isAncestor(oldPath, nextPath)) {
+		onAbort?.({
+			reason: "destination-not-found",
+			operation: "move",
+			pathOrID: newPath
+		});
+		return query;
+	}
 	const ruleOrGroup = clone ? regenerateIDs(isDraft(ruleOrGroupOriginal) ? current(ruleOrGroupOriginal) : ruleOrGroupOriginal, { idGenerator }) : ruleOrGroupOriginal;
 	const independentCombinators = isRuleGroupTypeIC(query);
 	const parentOfRuleToRemove = findPath(getParentPath(oldPath), query);
@@ -5323,20 +6087,23 @@ const moveInPlace = (query, oldPathOrID, newPath, options = {}) => {
 		parentOfRuleToRemove.rules.splice(idxStartDelete, deleteLength);
 	}
 	const newNewPath = [...nextPath];
+	if (independentCombinators && newNewPath.at(-1) % 2 === 1) newNewPath[newNewPath.length - 1] += 1;
 	const commonAncestorPath = getCommonAncestorPath(oldPath, nextPath);
-	if (!clone && oldPath.length === commonAncestorPath.length + 1 && nextPath[commonAncestorPath.length] > oldPath[commonAncestorPath.length]) newNewPath[commonAncestorPath.length] -= independentCombinators ? 2 : 1;
-	const parentToInsertInto = findPath(getParentPath(newNewPath), query);
+	if (!clone && oldPath.length === commonAncestorPath.length + 1 && newNewPath[commonAncestorPath.length] > oldPath[commonAncestorPath.length]) newNewPath[commonAncestorPath.length] -= independentCombinators ? 2 : 1;
+	const newNewParentPath = getParentPath(newNewPath);
+	const parentToInsertInto = findPath(newNewParentPath, query);
 	const newIndex = newNewPath.at(-1);
+	const spliceIndex = independentCombinators && newIndex > 0 ? newIndex - 1 : newIndex;
 	/**
 	* This function 1) glosses over the need for type assertions to splice directly
 	* into `parentToInsertInto.rules`, and 2) shortens the actual insertion code.
 	*/
-	const insertRuleOrGroup = (...args) => parentToInsertInto.rules.splice(newIndex, 0, ...args);
+	const insertRuleOrGroup = (...args) => parentToInsertInto.rules.splice(spliceIndex, 0, ...args);
 	if (parentToInsertInto.rules.length === 0 || !independentCombinators) insertRuleOrGroup(ruleOrGroup);
 	else if (newIndex === 0) if (ruleToRemoveIndex === 0 && oldNextCombinator) insertRuleOrGroup(ruleOrGroup, oldNextCombinator);
 	else insertRuleOrGroup(ruleOrGroup, parentToInsertInto.rules[1] ?? oldPrevCombinator ?? getFirstOption(combinators));
 	else if (oldPrevCombinator) insertRuleOrGroup(oldPrevCombinator, ruleOrGroup);
-	else insertRuleOrGroup(parentToInsertInto.rules[newIndex - 2] ?? oldNextCombinator ?? getFirstOption(combinators), ruleOrGroup);
+	else insertRuleOrGroup(parentToInsertInto.rules[spliceIndex - 2] ?? oldNextCombinator ?? getFirstOption(combinators), ruleOrGroup);
 	return query;
 };
 /**
@@ -5355,9 +6122,42 @@ const insert = (query, ruleOrGroup, path, options = {}) => produce(query, (q) =>
 * @group Query Tools
 */
 const insertInPlace = (query, ruleOrGroup, path, options = {}) => {
-	const { combinators = defaultCombinators, combinatorPreceding, combinatorSucceeding, idGenerator = generateID, replace = false } = options;
+	const { combinators = defaultCombinators, combinatorPreceding, combinatorSucceeding, idGenerator = generateID, replace = false, onAbort } = options;
 	const parentToInsertInto = findPath(getParentPath(path), query);
-	if (!parentToInsertInto || !isRuleGroup(parentToInsertInto)) return query;
+	if (!parentToInsertInto) {
+		onAbort?.({
+			reason: "parent-not-found",
+			operation: "insert",
+			pathOrID: path
+		});
+		return query;
+	}
+	if (!isRuleGroup(parentToInsertInto)) {
+		onAbort?.({
+			reason: "parent-not-a-group",
+			operation: "insert",
+			pathOrID: path
+		});
+		return query;
+	}
+	const parentPath = getParentPath(path);
+	const insertGuardReason = getGuardAbortReason(query, parentPath, options, { asParent: true });
+	if (insertGuardReason) {
+		onAbort?.({
+			reason: insertGuardReason,
+			operation: "insert",
+			pathOrID: path
+		});
+		return query;
+	}
+	if (isRuleGroup(ruleOrGroup) && exceedsMaxLevels(parentPath, options)) {
+		onAbort?.({
+			reason: "max-levels-exceeded",
+			operation: "insert",
+			pathOrID: path
+		});
+		return query;
+	}
 	const rorg = regenerateIDs(ruleOrGroup, { idGenerator });
 	const independentCombinators = isRuleGroupTypeIC(query);
 	const newIndex = path.at(-1);
@@ -5397,15 +6197,85 @@ const group = (query, sourcePathOrID, targetPathOrID, options = {}) => produce(q
 * @group Query Tools
 */
 const groupInPlace = (query, sourcePathOrID, targetPathOrID, options = {}) => {
-	const { clone = false, combinators = defaultCombinators, idGenerator = generateID } = options;
+	const { clone = false, combinators = defaultCombinators, idGenerator = generateID, onAbort } = options;
 	const sourcePath = Array.isArray(sourcePathOrID) ? sourcePathOrID : getPathOfID(sourcePathOrID, query);
 	const targetPath = Array.isArray(targetPathOrID) ? targetPathOrID : getPathOfID(targetPathOrID, query);
-	if (!sourcePath || !targetPath) return query;
+	if (!sourcePath) {
+		onAbort?.({
+			reason: "target-not-found",
+			operation: "group",
+			pathOrID: sourcePathOrID
+		});
+		return query;
+	}
+	if (!targetPath) {
+		onAbort?.({
+			reason: "target-not-found",
+			operation: "group",
+			pathOrID: targetPathOrID
+		});
+		return query;
+	}
 	const nextPath = getNextPath(query, sourcePath, targetPath);
-	if (sourcePath.length === 0 || pathsAreEqual(sourcePath, nextPath) || !findPath(getParentPath(nextPath), query)) return query;
+	if (sourcePath.length === 0) {
+		onAbort?.({
+			reason: "root-not-allowed",
+			operation: "group",
+			pathOrID: sourcePathOrID
+		});
+		return query;
+	}
+	const groupGuardReason = getGuardAbortReason(query, sourcePath, options);
+	if (groupGuardReason) {
+		onAbort?.({
+			reason: groupGuardReason,
+			operation: "group",
+			pathOrID: sourcePathOrID
+		});
+		return query;
+	}
+	if (pathsAreEqual(sourcePath, nextPath)) {
+		onAbort?.({
+			reason: "same-location",
+			operation: "group",
+			pathOrID: sourcePathOrID
+		});
+		return query;
+	}
+	if (!findPath(getParentPath(nextPath), query)) {
+		onAbort?.({
+			reason: "destination-not-found",
+			operation: "group",
+			pathOrID: targetPathOrID
+		});
+		return query;
+	}
+	if (!clone && isAncestor(sourcePath, nextPath)) {
+		onAbort?.({
+			reason: "destination-not-found",
+			operation: "group",
+			pathOrID: targetPathOrID
+		});
+		return query;
+	}
 	const sourceRuleOrGroupOriginal = findPath(sourcePath, query);
 	const targetRuleOrGroup = findPath(targetPath, query);
-	if (!sourceRuleOrGroupOriginal || !targetRuleOrGroup) return query;
+	if (!sourceRuleOrGroupOriginal) {
+		onAbort?.({
+			reason: "target-not-found",
+			operation: "group",
+			pathOrID: sourcePathOrID
+		});
+		return query;
+	}
+	if (!targetRuleOrGroup) {
+		onAbort?.({
+			reason: "target-not-found",
+			operation: "group",
+			pathOrID: targetPathOrID
+		});
+		return query;
+	}
 	const sourceRuleOrGroup = clone ? regenerateIDs(isDraft(sourceRuleOrGroupOriginal) ? current(sourceRuleOrGroupOriginal) : sourceRuleOrGroupOriginal, { idGenerator }) : sourceRuleOrGroupOriginal;
 	const independentCombinators = isRuleGroupTypeIC(query);
 	const parentOfRuleToRemove = findPath(getParentPath(sourcePath), query);
@@ -5418,7 +6288,8 @@ const groupInPlace = (query, sourcePathOrID, targetPathOrID, options = {}) => {
 	const newNewPath = [...nextPath];
 	const commonAncestorPath = getCommonAncestorPath(sourcePath, nextPath);
 	if (!clone && sourcePath.length === commonAncestorPath.length + 1 && nextPath[commonAncestorPath.length] > sourcePath[commonAncestorPath.length]) newNewPath[commonAncestorPath.length] -= independentCombinators ? 2 : 1;
-	const parentOfTargetPath = findPath(getParentPath(newNewPath), query);
+	const newNewParentPath = getParentPath(newNewPath);
+	const parentOfTargetPath = findPath(newNewParentPath, query);
 	const targetPathIndex = newNewPath.at(-1);
 	parentOfTargetPath.rules.splice(targetPathIndex, 1, prepareRuleOrGroup(independentCombinators ? { rules: [
 		targetRuleOrGroup,
@@ -5431,6 +6302,1248 @@ const groupInPlace = (query, sourcePathOrID, targetPathOrID, options = {}) => {
 	return query;
 };
 //#endregion
-export { LogType, TestID, add, addInPlace, betweenOperators, bigIntJsonParseReviver, bigIntJsonStringifyReplacer, celCombinatorMap, clsx, convertFromIC, convertQuery, convertToIC, cypherCombinatorMap, defaultCELValueProcessor, defaultCombinatorLabelMap, defaultCombinators, defaultCombinatorsExtended, defaultControlClassnames, defaultExportOperatorMap, defaultJoinChar, defaultMatchModes, defaultMongoDBValueProcessor, defaultNLTranslations, defaultOperatorLabelMap, defaultOperatorNegationMap, defaultOperatorProcessorNL, defaultOperatorProcessorSQL, defaultOperators, defaultPlaceholderFieldGroupLabel, defaultPlaceholderFieldLabel, defaultPlaceholderFieldName, defaultPlaceholderLabel, defaultPlaceholderName, defaultPlaceholderOperatorGroupLabel, defaultPlaceholderOperatorLabel, defaultPlaceholderOperatorName, defaultPlaceholderValueGroupLabel, defaultPlaceholderValueLabel, defaultPlaceholderValueName, defaultRuleGroupProcessorCEL, defaultRuleGroupProcessorCypher, defaultRuleGroupProcessorDiagnostics, defaultRuleGroupProcessorDrizzle, defaultRuleGroupProcessorElasticSearch, defaultRuleGroupProcessorGremlin, defaultRuleGroupProcessorJSONata, defaultRuleGroupProcessorJsonLogic, defaultRuleGroupProcessorLDAP, defaultRuleGroupProcessorMongoDB, defaultRuleGroupProcessorMongoDBQuery, defaultRuleGroupProcessorNL, defaultRuleGroupProcessorParameterized, defaultRuleGroupProcessorPrisma, defaultRuleGroupProcessorSPARQL, defaultRuleGroupProcessorSQL, defaultRuleGroupProcessorSequelize, defaultRuleGroupProcessorSpEL, defaultRuleGroupProcessorTanStackDB, defaultRuleProcessorCEL, defaultRuleProcessorCypher, defaultRuleProcessorDrizzle, defaultRuleProcessorElasticSearch, defaultRuleProcessorGremlin, defaultRuleProcessorJSONata, defaultRuleProcessorJsonLogic, defaultRuleProcessorLDAP, defaultRuleProcessorMongoDB, defaultRuleProcessorMongoDBQuery, defaultRuleProcessorNL, defaultRuleProcessorParameterized, defaultRuleProcessorPrisma, defaultRuleProcessorSPARQL, defaultRuleProcessorSQL, defaultRuleProcessorSequelize, defaultRuleProcessorSpEL, defaultRuleProcessorTanStackDB, defaultSpELValueProcessor, defaultTranslations, defaultValidator, defaultValueProcessor, defaultValueProcessorByRule, defaultValueProcessorCELByRule, defaultValueProcessorMongoDBByRule, defaultValueProcessorNL, defaultValueProcessorSpELByRule, filterFieldsByComparator, findID, findPath, formatQuery, formatQueryOptionPresets, generateAccessibleDescription, generateID, getCommonAncestorPath, getFirstOption, getLikeWildcards, getMatchModesUtil, getNLTranslataion, getOption, getParentPath, getParseNumberMethod, getPathOfID, getQuoteFieldNamesWithArray, getQuotedFieldName, getRuleDefaultValue, getSQLConcat, getValidationClassNames, getValueSourcesUtil, group, groupInPlace, groupInvalidReasons, inOperators, insert, insertInPlace, isAncestor, isFlexibleOptionArray, isFlexibleOptionGroupArray, isFullOptionArray, isFullOptionGroupArray, isOptionGroupArray, isPojo, isRuleGroup, isRuleGroupType, isRuleGroupTypeIC, isRuleOrGroupValid, isRuleType, isUnsafeKey, isValidValue, isValidationResult, isValueProcessorLegacy, joinWith, jsonLogicAdditionalOperators, lc, mapSQLOperator, mergeAnyTranslation, mergeAnyTranslations, mergeClassnames, mongoDbFallback, mongoOperators, move, moveInPlace, normalizeConstituentWordOrder, nullFreeArray, nullOperators, nullOrUndefinedOrEmpty, numericRegex, numerifyValues, objectEntries, objectKeys, parseNumber, pathIsDisabled, pathsAreEqual, preferAnyProp, preferFlagProps, preferProp, prepareOptionList, prepareRule, prepareRuleGroup, prepareRuleOrGroup, prismaFallback, prismaOperators, processMatchMode, queryBuilderFlagDefaults, regenerateID, regenerateIDs, relationalOperators, remove, removeInPlace, rootPath, shouldRenderAsNumber, sparqlVar, splitBy, sqlDialectPresets, standardClassnames, stripParamPrefix, substringOperators, toArray, toFlatOptionArray, toFullOption, toFullOptionList, toFullOptionMap, transformQuery, trimIfString, uniqByIdentifier, uniqByName, uniqOptGroups, uniqOptList, update, updateInPlace, uuidV4regex, withParamPrefix, wrapLikeFragment };
+//#region src/utils/queryActions.ts
+/**
+* Builds the query builder's six mutation handlers as pure functions of the current query.
+*
+* This is the framework-agnostic core of the action handlers in `useQueryBuilderSchema`. It owns
+* the policy that surrounds the query tools—disabled gating, the confirmation callback protocol,
+* `maxLevels`, and debug logging—so an implementation only has to supply its own storage: read
+* the current query, call the action, and apply a non-`undefined` result.
+*
+* @group Query Tools
+*/
+const createQueryActions = (config = {}) => {
+	const { qbId, combinators, idGenerator, maxLevels = Infinity, queryDisabled, respectDisabled = true, disabledPaths, resetOnFieldChange, resetOnOperatorChange, getRuleDefaultOperator, getValueSources, getRuleDefaultValue, getMatchModes, onAddRule, onAddGroup, onRemove, onMoveRule, onMoveGroup, onGroupRule, onGroupGroup, onLog } = config;
+	const log = (payload) => onLog?.({
+		qbId,
+		...payload
+	});
+	const guards = {
+		respectDisabled,
+		queryDisabled,
+		disabledPaths
+	};
+	/** Whether the mutation is blocked, using the same rules the query tools apply internally. */
+	const blocked = (query, path, asParent = false) => !!getGuardAbortReason(query, path, guards, { asParent });
+	return {
+		addRule: (query, rule, parentPath, context) => {
+			if (blocked(query, parentPath, true)) {
+				log({
+					type: LogType.parentPathDisabled,
+					rule,
+					parentPath,
+					query
+				});
+				return;
+			}
+			const nextRule = onAddRule ? onAddRule(rule, parentPath, query, context) : true;
+			if (!nextRule) {
+				log({
+					type: LogType.onAddRuleFalse,
+					rule,
+					parentPath,
+					query
+				});
+				return;
+			}
+			const newRule = nextRule === true ? rule : nextRule;
+			const newQuery = add(query, newRule, parentPath, {
+				combinators,
+				combinatorPreceding: newRule.combinatorPreceding,
+				idGenerator
+			});
+			log({
+				type: LogType.add,
+				query,
+				newQuery,
+				newRule,
+				parentPath
+			});
+			return newQuery;
+		},
+		addGroup: (query, ruleGroup, parentPath, context) => {
+			if (parentPath.length >= maxLevels) return void 0;
+			if (blocked(query, parentPath, true)) {
+				log({
+					type: LogType.parentPathDisabled,
+					ruleGroup,
+					parentPath,
+					query
+				});
+				return;
+			}
+			const nextGroup = onAddGroup ? onAddGroup(ruleGroup, parentPath, query, context) : true;
+			if (!nextGroup) {
+				log({
+					type: LogType.onAddGroupFalse,
+					ruleGroup,
+					parentPath,
+					query
+				});
+				return;
+			}
+			const newGroup = nextGroup === true ? ruleGroup : nextGroup;
+			const newQuery = add(query, newGroup, parentPath, {
+				combinators,
+				combinatorPreceding: newGroup.combinatorPreceding ?? void 0,
+				idGenerator
+			});
+			log({
+				type: LogType.add,
+				query,
+				newQuery,
+				newGroup,
+				parentPath
+			});
+			return newQuery;
+		},
+		propChange: (query, prop, value, path) => {
+			if (getGuardAbortReason(query, path, prop === "disabled" ? { queryDisabled } : guards)) {
+				log({
+					type: LogType.pathDisabled,
+					path,
+					prop,
+					value,
+					query
+				});
+				return;
+			}
+			const newQuery = update(query, prop, value, path, {
+				resetOnFieldChange,
+				resetOnOperatorChange,
+				getRuleDefaultOperator,
+				getValueSources,
+				getRuleDefaultValue,
+				getMatchModes
+			});
+			log({
+				type: LogType.update,
+				query,
+				newQuery,
+				prop,
+				value,
+				path
+			});
+			return newQuery;
+		},
+		removeRuleOrGroup: (query, path, context) => {
+			if (blocked(query, path)) {
+				log({
+					type: LogType.pathDisabled,
+					path,
+					query
+				});
+				return;
+			}
+			const ruleOrGroup = findPath(path, query);
+			/* v8 ignore next -- @preserve */
+			if (!ruleOrGroup) return void 0;
+			if (onRemove && !onRemove(ruleOrGroup, path, query, context)) {
+				log({
+					type: LogType.onRemoveFalse,
+					ruleOrGroup,
+					path,
+					query
+				});
+				return;
+			}
+			const newQuery = remove(query, path);
+			log({
+				type: LogType.remove,
+				query,
+				newQuery,
+				path,
+				ruleOrGroup
+			});
+			return newQuery;
+		},
+		moveRule: (query, oldPath, newPath, clone, context) => {
+			if (blocked(query, oldPath)) {
+				log({
+					type: LogType.pathDisabled,
+					oldPath,
+					newPath,
+					query
+				});
+				return;
+			}
+			const ruleOrGroup = findPath(oldPath, query);
+			if (!ruleOrGroup) return void 0;
+			const nextQuery = move(query, oldPath, newPath, {
+				clone,
+				combinators,
+				idGenerator
+			});
+			const isGroup = isRuleGroup(ruleOrGroup);
+			const callback = isGroup ? onMoveGroup : onMoveRule;
+			const callbackResult = callback ? callback(ruleOrGroup, oldPath, newPath, query, nextQuery, {
+				clone,
+				combinators
+			}, context) : true;
+			if (!callbackResult) {
+				log({
+					type: isGroup ? LogType.onMoveGroupFalse : LogType.onMoveRuleFalse,
+					ruleOrGroup,
+					oldPath,
+					newPath,
+					clone,
+					query,
+					nextQuery
+				});
+				return;
+			}
+			const newQuery = isRuleGroup(callbackResult) ? callbackResult : nextQuery;
+			log({
+				type: LogType.move,
+				query,
+				newQuery,
+				oldPath,
+				newPath,
+				clone
+			});
+			return newQuery;
+		},
+		groupRule: (query, sourcePath, targetPath, clone, context) => {
+			if (blocked(query, sourcePath)) {
+				log({
+					type: LogType.pathDisabled,
+					sourcePath,
+					targetPath,
+					query
+				});
+				return;
+			}
+			const ruleOrGroup = findPath(sourcePath, query);
+			if (!ruleOrGroup) return void 0;
+			const nextQuery = group(query, sourcePath, targetPath, {
+				clone,
+				combinators,
+				idGenerator
+			});
+			const isGroup = isRuleGroup(ruleOrGroup);
+			const callback = isGroup ? onGroupGroup : onGroupRule;
+			const callbackResult = callback ? callback(ruleOrGroup, sourcePath, targetPath, query, nextQuery, {
+				clone,
+				combinators
+			}, context) : true;
+			if (!callbackResult) {
+				log({
+					type: isGroup ? LogType.onGroupGroupFalse : LogType.onGroupRuleFalse,
+					ruleOrGroup,
+					sourcePath,
+					targetPath,
+					clone,
+					query,
+					nextQuery
+				});
+				return;
+			}
+			const newQuery = isRuleGroup(callbackResult) ? callbackResult : nextQuery;
+			log({
+				type: LogType.group,
+				query,
+				newQuery,
+				sourcePath,
+				targetPath,
+				clone
+			});
+			return newQuery;
+		}
+	};
+};
+//#endregion
+//#region src/utils/ruleFactory.ts
+/**
+* Creates a rule from the given configuration, applying the same precedence as the
+* `QueryBuilder` component. The `value` is computed in a second pass, once `field`, `operator`,
+* and `valueSource` are known, since the default value depends on all three.
+*
+* @group Query Tools
+*/
+const createRule = ({ fields, getDefaultField, getRuleDefaultOperator, getValueSources, getMatchModes, getRuleDefaultValue, idGenerator = generateID }) => {
+	let field = getFirstOption(fields) ?? "";
+	if (getDefaultField) if (typeof getDefaultField === "function") {
+		const defaultField = getDefaultField(fields);
+		if (defaultField) field = defaultField;
+	} else field = getDefaultField;
+	const fieldData = getOption(fields, field);
+	const operator = getRuleDefaultOperator(field);
+	const valueSource = getFirstOption(getValueSources(field, operator, { fieldData })) ?? "value";
+	const matchMode = getFirstOption(getMatchModes(field, { fieldData }));
+	const newRule = {
+		id: idGenerator(),
+		field,
+		operator,
+		valueSource,
+		value: "",
+		...matchMode ? { match: {
+			mode: matchMode,
+			threshold: 1
+		} } : null
+	};
+	return {
+		...newRule,
+		value: getRuleDefaultValue(newRule)
+	};
+};
+/**
+* Creates a group from the given configuration. Pass `true` for `independentCombinators` to omit
+* the `combinator` property.
+*
+* The group's own `id` is generated _before_ any contained rule's, matching the order the
+* `QueryBuilder` component has always used. This is observable when `idGenerator` is
+* deterministic, as it often is in tests.
+*
+* @group Query Tools
+*/
+const createRuleGroup = ({ combinators, addRuleToNewGroups, createRule: createRuleMain, idGenerator = generateID }, independentCombinators) => {
+	const id = idGenerator();
+	const rules = addRuleToNewGroups ? [createRuleMain()] : [];
+	if (independentCombinators) return {
+		id,
+		rules,
+		not: false
+	};
+	return {
+		id,
+		rules,
+		combinator: getFirstOption(combinators) ?? "",
+		not: false
+	};
+};
+//#endregion
+//#region src/utils/signature.ts
+/**
+* Signature returned when a change alters the _shape_ of the query—rules or groups added,
+* removed, moved, or reordered—rather than the properties of a single node. Structural changes
+* never coalesce with each other, so each one produces its own history entry.
+*/
+const structuralSignature = "~structural";
+/**
+* Signature returned when two queries differ by reference only, with no observable difference
+* in their properties.
+*/
+const unchangedSignature = "";
+/**
+* Returns the list of property names that differ between two nodes, ignoring `rules` (which is
+* compared structurally by the caller).
+*/
+const changedProps = (prev, next) => {
+	const keys = /* @__PURE__ */ new Set([...Object.keys(prev), ...Object.keys(next)]);
+	keys.delete("rules");
+	const changed = [];
+	for (const key of keys) if (!Object.is(prev[key], next[key])) changed.push(key);
+	return changed.toSorted();
+};
+const signatureOfNode = (prev, next, parentId, index) => {
+	if (prev === next) return "";
+	if (typeof prev === "string" || typeof next === "string") return typeof prev === typeof next ? `${parentId}:combinator[${index}]` : structuralSignature;
+	const prevIsGroup = isRuleGroup(prev);
+	const nextIsGroup = isRuleGroup(next);
+	if (prevIsGroup !== nextIsGroup) return structuralSignature;
+	if (!prevIsGroup || !nextIsGroup) {
+		const props = changedProps(prev, next);
+		return props.length === 0 ? "" : `${next.id ?? ""}:${props.join(",")}`;
+	}
+	if (prev.rules.length !== next.rules.length) return structuralSignature;
+	const ownProps = changedProps(prev, next);
+	let changedIndex = -1;
+	for (const [i, prevRule] of prev.rules.entries()) if (prevRule !== next.rules[i]) {
+		if (changedIndex !== -1) return structuralSignature;
+		changedIndex = i;
+	}
+	if (changedIndex === -1) return ownProps.length === 0 ? "" : `${next.id ?? ""}:${ownProps.join(",")}`;
+	if (ownProps.length > 0) return structuralSignature;
+	return signatureOfNode(prev.rules[changedIndex], next.rules[changedIndex], next.id ?? "", changedIndex);
+};
+/**
+* Describes _what changed_ between two versions of a query as a short string, so that
+* consecutive edits to the same property of the same rule (e.g. typing in a value editor) can
+* be recognized and coalesced into a single history entry.
+*
+* Returns {@link structuralSignature} for changes to the shape of the query, {@link unchangedSignature} when the
+* two queries differ by reference only, and `"<id>:<props>"` otherwise.
+*
+* The walk prunes on reference equality, so it costs O(depth) rather than O(size) for the
+* single-node edits that make up the overwhelming majority of changes.
+*
+* Note that this relies on the structural sharing that Immer—and therefore every query
+* produced by RQB's own update functions—guarantees: nodes that did not change keep their
+* identity. A query that has been wholly rebuilt (deep-cloned, round-tripped through JSON,
+* re-parsed from a string) shares no identity with its predecessor, so it is reported as
+* {@link structuralSignature} and will not coalesce. That is a graceful degradation—every change simply
+* gets its own history entry—but controlled components that clone the query on every change
+* will not benefit from coalescing.
+*/
+const signatureOf = (prev, next) => signatureOfNode(prev, next, "", -1);
+//#endregion
+//#region src/utils/QueryManager.ts
+/**
+* Abort reasons that {@link QueryManager}'s `strict` mode treats as errors. The remaining
+* reasons—`"same-location"` and `"no-change"`—describe valid operations that had nothing to do,
+* so they are reported to `onInvalidTarget` but never throw.
+*
+* @group Query Tools
+*/
+const strictAbortReasons = [
+	"target-not-found",
+	"parent-not-found",
+	"parent-not-a-group",
+	"destination-not-found",
+	"root-not-allowed",
+	"not-a-combinator-slot",
+	"target-disabled",
+	"parent-disabled",
+	"max-levels-exceeded"
+];
+const strictAbortReasonSet = new Set(strictAbortReasons);
+/**
+* Thrown by {@link QueryManager} methods in `strict` mode when an operation cannot be carried
+* out because its target could not be used.
+*
+* @group Query Tools
+*/
+var QueryManagerError = class QueryManagerError extends Error {
+	/** Why the operation was aborted. */
+	code;
+	/** Full details about the aborted operation. */
+	info;
+	constructor(info) {
+		super(`QueryManager: "${info.operation}" aborted (${info.reason})${info.pathOrID === void 0 ? "" : ` for target ${JSON.stringify(info.pathOrID)}`}.`);
+		this.name = "QueryManagerError";
+		this.code = info.reason;
+		this.info = info;
+		Object.setPrototypeOf(this, QueryManagerError.prototype);
+	}
+};
+/**
+* Stateful wrapper around the {@link add}/{@link remove}/{@link update}/{@link move}/
+* {@link insert}/{@link group} query tools, plus rule/group factories, {@link defaultValidator
+* validation}, and {@link formatQuery formatting}.
+*
+* The query is held internally, so each method takes the same arguments as its `queryTools`
+* counterpart minus the leading `query` parameter, and returns the manager itself for chaining.
+* Mutations use the non-`InPlace` tools, so a query previously handed out by
+* {@link QueryManager.getQuery} is never modified.
+*
+* ```ts
+* const q = new QueryManager(undefined, { fields });
+* q.add(q.createRule()).add({ field: 'firstName', operator: '=', value: 'Steve' });
+* q.format('sql');
+* ```
+*
+* Like the underlying query tools, methods are a no-op when the target path or `id` can't be
+* resolved (including attempts to remove the root group). By default nothing is thrown; pass
+* `strict: true` to raise a {@link QueryManagerError} instead, or `onInvalidTarget` to observe
+* aborted operations without changing control flow.
+*
+* @group Query Tools
+*/
+var QueryManager = class QueryManager {
+	#query;
+	#options;
+	#fields;
+	#fieldMap;
+	#operators;
+	#combinators;
+	#idGenerator;
+	#validator;
+	#strict;
+	#respectDisabled;
+	#onInvalidTarget;
+	#listeners = /* @__PURE__ */ new Set();
+	#historyEnabled;
+	#maxHistory;
+	#coalesceMs;
+	#now;
+	#past = [];
+	#future = [];
+	#lastSig;
+	#lastAt = 0;
+	#batchDepth = 0;
+	#batchSnapshot;
+	/** Whether a history-stack method ran inside the batch currently in progress. */
+	#historyBypassed = false;
+	/**
+	* The query the cached fields below were derived from. Caches are keyed on query _identity_
+	* rather than invalidated from {@link QueryManager.#commit} because `undo`, `redo`, and
+	* `batch`'s rollback all assign `#query` directly.
+	*/
+	#cacheFor;
+	#idPathIndex;
+	#validation;
+	constructor(query, options = {}) {
+		this.#options = options;
+		this.#idGenerator = options.idGenerator ?? generateID;
+		this.#validator = options.validator ?? defaultValidator;
+		this.#strict = options.strict ?? false;
+		this.#respectDisabled = options.respectDisabled ?? true;
+		this.#onInvalidTarget = options.onInvalidTarget;
+		const history = options.history ?? false;
+		const historyOptions = typeof history === "object" ? history : {};
+		this.#historyEnabled = history !== false;
+		this.#maxHistory = historyOptions.maxHistory ?? 50;
+		this.#coalesceMs = historyOptions.coalesceMs ?? 500;
+		this.#now = options.now ?? Date.now;
+		const { optionList: fields, optionsMap: fieldMap } = prepareOptionList({
+			optionList: options.fields,
+			baseOption: options.baseField,
+			autoSelectOption: options.autoSelectField
+		});
+		this.#fields = freeze(fields, true);
+		this.#fieldMap = freeze(fieldMap, true);
+		this.#operators = prepareOptionList({
+			optionList: options.operators ?? defaultOperators,
+			baseOption: options.baseOperator,
+			labelMap: defaultOperatorLabelMap,
+			autoSelectOption: options.autoSelectOperator
+		}).optionList;
+		this.#combinators = freeze(prepareOptionList({
+			optionList: options.combinators ?? defaultCombinators,
+			baseOption: options.baseCombinator
+		}).optionList, true);
+		this.#query = freeze(query ? prepareRuleGroup(query, { idGenerator: this.#idGenerator }) : this.createRuleGroup(), true);
+	}
+	/** Resolves the field configuration for a field name. */
+	#fieldData(field) {
+		return this.#fieldMap[field] ?? {};
+	}
+	/** Resolves the operator list for a field, mirroring `QueryBuilder`'s precedence. */
+	#operatorsFor(field) {
+		return resolveOperatorList({
+			field,
+			fieldData: this.#fieldData(field),
+			getOperators: this.#options.getOperators,
+			operators: this.#operators,
+			baseOption: this.#options.baseOperator,
+			autoSelectOption: this.#options.autoSelectOperator
+		});
+	}
+	/** Resolves the default operator for a field, mirroring `QueryBuilder`'s precedence. */
+	#defaultOperator(field) {
+		return resolveDefaultOperator({
+			field,
+			fieldData: this.#fieldData(field),
+			getDefaultOperator: this.#options.getDefaultOperator,
+			getOperators: (f) => this.#operatorsFor(f)
+		});
+	}
+	#valueSourcesFor(field, operator) {
+		return getValueSourcesUtil(this.#fieldData(field), operator, this.#options.getValueSources);
+	}
+	#matchModesFor(field) {
+		return getMatchModesUtil(this.#fieldData(field), this.#options.getMatchModes);
+	}
+	#valuesFor(field, operator) {
+		return resolveValueList({
+			field,
+			operator,
+			fieldData: this.#fieldData(field),
+			getValues: this.#options.getValues,
+			autoSelectOption: this.#options.autoSelectValue
+		});
+	}
+	#valueEditorTypeFor(field, operator) {
+		return resolveValueEditorType({
+			field,
+			operator,
+			fieldData: this.#fieldData(field),
+			getValueEditorType: this.#options.getValueEditorType
+		});
+	}
+	/** Computes the default `value` for a rule, mirroring `QueryBuilder`'s precedence. */
+	#defaultValue(rule) {
+		const { getDefaultValue, getParameters, listsAsArrays } = this.#options;
+		return getRuleDefaultValue(rule, {
+			fieldData: this.#fieldData(rule.field),
+			fields: this.#fields,
+			listsAsArrays,
+			getValueEditorType: (f, o) => this.#valueEditorTypeFor(f, o),
+			getValues: (f, o) => this.#valuesFor(f, o),
+			getDefaultValue: getDefaultValue && ((r, misc) => getDefaultValue(r, misc)),
+			getParameters: getParameters && ((f, o, misc) => this.#parametersFor(f, o, misc))
+		});
+	}
+	/**
+	* Resolves the parameter list for a field/operator pair, normalized the same way as every
+	* other option list. Shared by {@link QueryManager.#defaultValue} and
+	* {@link QueryManager.getRuleContext} so both see the same shape.
+	*/
+	#parametersFor(field, operator, misc) {
+		return prepareOptionList({
+			optionList: this.#options.getParameters?.(field, operator, misc) ?? [],
+			autoSelectOption: this.#options.autoSelectValue
+		}).optionList;
+	}
+	/** Defaults shared by every mutating method, overridable per call. */
+	#guardOptions() {
+		const { maxLevels } = this.#options;
+		return {
+			maxLevels: (maxLevels ?? 0) > 0 ? Number(maxLevels) : Infinity,
+			respectDisabled: this.#respectDisabled,
+			disabledPaths: this.#options.disabledPaths,
+			queryDisabled: this.#options.queryDisabled
+		};
+	}
+	#toolOptions() {
+		return {
+			combinators: this.#combinators,
+			idGenerator: this.#idGenerator,
+			...this.#guardOptions()
+		};
+	}
+	/**
+	* Builds the `onAbort` handler passed to the query tools, applying the per-call overrides on
+	* top of the manager's own options.
+	*/
+	#onAbort({ strict, onInvalidTarget }) {
+		const strictMain = strict ?? this.#strict;
+		const handler = onInvalidTarget ?? this.#onInvalidTarget;
+		return (info) => {
+			handler?.(info);
+			if (strictMain && strictAbortReasonSet.has(info.reason)) throw new QueryManagerError(info);
+		};
+	}
+	/** Defaults for {@link update}, so resets mirror `QueryBuilder`'s behavior. */
+	#updateOptions() {
+		return {
+			getRuleDefaultOperator: (f) => this.#defaultOperator(f),
+			getRuleDefaultValue: (r) => this.#defaultValue(r),
+			getValueSources: (f, o) => this.#valueSourcesFor(f, o),
+			getMatchModes: (f) => this.#matchModesFor(f),
+			resetOnFieldChange: this.#options.resetOnFieldChange,
+			resetOnOperatorChange: this.#options.resetOnOperatorChange,
+			...this.#guardOptions()
+		};
+	}
+	/**
+	* Applies a new query, recording history and notifying subscribers as appropriate. Every
+	* mutation funnels through here. A tool that could not resolve its target returns the same
+	* query object, which is treated as a no-op.
+	*/
+	#commit(next) {
+		const prev = this.#query;
+		if (prev === next) return;
+		this.#query = next;
+		if (this.#batchDepth > 0) return;
+		this.#record(prev, next);
+		this.#notify();
+	}
+	/**
+	* Records a change, either as a new history entry or by absorbing it into the current one.
+	* Mirrors the recording semantics of the `react-querybuilder/history` entry point.
+	*/
+	#record(prev, next) {
+		if (!this.#historyEnabled) return;
+		const sig = signatureOf(prev, next);
+		if (sig === "") return;
+		const now = this.#now();
+		if (!(sig !== "~structural" && sig === this.#lastSig && now - this.#lastAt < this.#coalesceMs)) {
+			this.#past.push(prev);
+			if (this.#past.length > this.#maxHistory) this.#past.shift();
+			this.#future = [];
+		}
+		this.#lastSig = sig;
+		this.#lastAt = now;
+	}
+	#notify() {
+		for (const listener of this.#listeners) listener();
+	}
+	/**
+	* Records that a history-stack method ran inside the current batch. Those methods manage
+	* `#past`/`#future` themselves, so the batch must not also record an entry on completion —
+	* doing so would push a duplicate onto `#past` and clear the redo stack that `undo` just
+	* populated.
+	*/
+	#markHistoryBypassed() {
+		if (this.#batchDepth > 0) this.#historyBypassed = true;
+	}
+	/**
+	* Discards every cached derivation when the query has been replaced since they were computed.
+	* Called at the top of each cached reader.
+	*/
+	#ensureCache() {
+		if (this.#cacheFor === this.#query) return;
+		this.#cacheFor = this.#query;
+		this.#idPathIndex = void 0;
+		this.#validation = void 0;
+	}
+	/**
+	* The single traversal implementation. Combinator strings in independent-combinator groups
+	* are skipped.
+	*
+	* @yields The subtree rooted at `node`, depth-first in pre-order, starting with `node` itself.
+	*/
+	*#walkFrom(node, path, parent) {
+		yield {
+			node,
+			path,
+			parent
+		};
+		if (!isRuleGroup(node)) return;
+		const startGroup = node;
+		for (const [index, child] of startGroup.rules.entries()) {
+			if (typeof child === "string") continue;
+			yield* this.#walkFrom(child, [...path, index], startGroup);
+		}
+	}
+	/** Builds (once per query) the `id` to {@link Path} index backing `findID`/`getPathOfID`. */
+	#index() {
+		this.#ensureCache();
+		if (!this.#idPathIndex) {
+			const index = /* @__PURE__ */ new Map();
+			for (const { node, path } of this.#walkFrom(this.#query, [], null)) if (node.id !== void 0 && !index.has(node.id)) index.set(node.id, path);
+			this.#idPathIndex = index;
+		}
+		return this.#idPathIndex;
+	}
+	/** Resolves a path or `id` to a path, or `null` when the `id` isn't present. */
+	#toPath(pathOrID) {
+		return typeof pathOrID === "string" ? this.#index().get(pathOrID) ?? null : pathOrID;
+	}
+	/**
+	* The current query. The returned object is frozen and structurally shared, so it is safe to
+	* retain and compare by reference to detect changes.
+	*
+	* Like {@link QueryManager.subscribe}, this method is bound to the instance, so it can be
+	* passed as a bare reference (e.g. as the `getSnapshot` argument to `useSyncExternalStore`).
+	*/
+	getQuery = () => this.#query;
+	/** Replaces the current query, ensuring every rule and group has an `id`. */
+	setQuery(query) {
+		this.#commit(freeze(prepareRuleGroup(query, { idGenerator: this.#idGenerator }), true));
+		return this;
+	}
+	/**
+	* Creates a rule using the configured fields, operators, and defaults. The rule is not added
+	* to the query—pass it to {@link QueryManager.add} or {@link QueryManager.insert}.
+	*/
+	createRule() {
+		return createRule({
+			fields: this.#fields,
+			getDefaultField: this.#options.getDefaultField,
+			getRuleDefaultOperator: (f) => this.#defaultOperator(f),
+			getValueSources: (f, o) => this.#valueSourcesFor(f, o),
+			getMatchModes: (f) => this.#matchModesFor(f),
+			getRuleDefaultValue: (r) => this.#defaultValue(r),
+			idGenerator: this.#idGenerator
+		});
+	}
+	/**
+	* Creates a group. Pass `true` for a group with independent combinators. The group is not
+	* added to the query—pass it to {@link QueryManager.add} or {@link QueryManager.insert}.
+	*/
+	createRuleGroup(independentCombinators) {
+		return createRuleGroup({
+			combinators: this.#combinators,
+			addRuleToNewGroups: this.#options.addRuleToNewGroups,
+			createRule: () => this.createRule(),
+			idGenerator: this.#idGenerator
+		}, independentCombinators);
+	}
+	/**
+	* Adds a rule or group to the end of the group at `parentPathOrID`, which defaults to the
+	* root group.
+	*/
+	add(ruleOrGroup, parentPathOrID = [], options = {}) {
+		const { strict, onInvalidTarget, ...toolOptions } = options;
+		this.#commit(add(this.#query, ruleOrGroup, parentPathOrID, {
+			...this.#toolOptions(),
+			...toolOptions,
+			onAbort: this.#onAbort({
+				strict,
+				onInvalidTarget
+			})
+		}));
+		return this;
+	}
+	/** Removes the rule or group at the given path or `id`. The root group cannot be removed. */
+	remove(pathOrID, options = {}) {
+		const { strict, onInvalidTarget, ...toolOptions } = options;
+		this.#commit(remove(this.#query, pathOrID, {
+			...this.#guardOptions(),
+			...toolOptions,
+			onAbort: this.#onAbort({
+				strict,
+				onInvalidTarget
+			})
+		}));
+		return this;
+	}
+	update(a, b, c, d) {
+		const optionsIndex = typeof a === "string" || Array.isArray(a) ? 3 : 2;
+		const args = [
+			a,
+			b,
+			c,
+			d
+		];
+		const { strict, onInvalidTarget, ...toolOptions } = args[optionsIndex] ?? {};
+		args[optionsIndex] = {
+			...this.#updateOptions(),
+			...toolOptions,
+			onAbort: this.#onAbort({
+				strict,
+				onInvalidTarget
+			})
+		};
+		this.#commit(update(this.#query, ...args.slice(0, optionsIndex + 1)));
+		return this;
+	}
+	/** Moves the rule or group at `oldPathOrID` to `newPath`, or shifts it `'up'`/`'down'`. */
+	move(oldPathOrID, newPath, options = {}) {
+		const { strict, onInvalidTarget, ...toolOptions } = options;
+		this.#commit(move(this.#query, oldPathOrID, newPath, {
+			...this.#toolOptions(),
+			...toolOptions,
+			onAbort: this.#onAbort({
+				strict,
+				onInvalidTarget
+			})
+		}));
+		return this;
+	}
+	/**
+	* Inserts a rule or group at the given path. Unlike the other methods, this accepts a path
+	* only—inserting _at_ an `id` would be ambiguous.
+	*/
+	insert(ruleOrGroup, path, options = {}) {
+		const { strict, onInvalidTarget, ...toolOptions } = options;
+		this.#commit(insert(this.#query, ruleOrGroup, path, {
+			...this.#toolOptions(),
+			...toolOptions,
+			onAbort: this.#onAbort({
+				strict,
+				onInvalidTarget
+			})
+		}));
+		return this;
+	}
+	/**
+	* Creates a new group at `targetPathOrID` containing the rules/groups currently at
+	* `targetPathOrID` and `sourcePathOrID`.
+	*/
+	group(sourcePathOrID, targetPathOrID, options = {}) {
+		const { strict, onInvalidTarget, ...toolOptions } = options;
+		this.#commit(group(this.#query, sourcePathOrID, targetPathOrID, {
+			...this.#toolOptions(),
+			...toolOptions,
+			onAbort: this.#onAbort({
+				strict,
+				onInvalidTarget
+			})
+		}));
+		return this;
+	}
+	/**
+	* Creates an independent manager with the same configuration and the current query.
+	*
+	* Subscribers and history are _not_ carried over: the clone starts with no listeners and an
+	* empty undo stack. Because every mutation produces a new query object, the two managers
+	* share the initial query safely and diverge from the first change.
+	*
+	* Pass `{ regenerateIDs: true }` to give every rule and group in the clone a new `id`, which
+	* is useful when both queries will be used together (e.g. inserted into the same tree).
+	*/
+	clone(options) {
+		const query = options?.regenerateIDs ? regenerateIDs(this.#query, { idGenerator: this.#idGenerator }) : this.#query;
+		return new QueryManager(query, this.#options);
+	}
+	/**
+	* Registers a listener called after every change to the query, and returns a function that
+	* unregisters it. Mutations that resolve to a no-op do not notify, and a
+	* {@link QueryManager.batch batch} notifies once no matter how many changes it contains.
+	*
+	* Together with {@link QueryManager.getQuery}, this satisfies React's `useSyncExternalStore`
+	* contract. Both methods are bound to the instance, so they are stable references across
+	* renders and can be passed directly:
+	*
+	* ```ts
+	* const query = useSyncExternalStore(q.subscribe, q.getQuery);
+	* ```
+	*
+	* In React, prefer the `useQueryManager` hook from `react-querybuilder`, which wraps this.
+	*/
+	subscribe = (listener) => {
+		this.#listeners.add(listener);
+		return () => {
+			this.#listeners.delete(listener);
+		};
+	};
+	/**
+	* Runs `fn`, deferring history recording and subscriber notification until it returns. The
+	* whole batch becomes a single undo step and triggers a single notification, or neither if
+	* the query ends up unchanged.
+	*
+	* Batches may be nested; only the outermost one commits. If `fn` throws, the query and its
+	* history are restored to their pre-batch state and the error propagates, so a batch either
+	* applies completely or not at all.
+	*
+	* {@link QueryManager.undo}, {@link QueryManager.redo}, and {@link QueryManager.clearHistory}
+	* may be called inside a batch; their notifications are deferred like everything else. Because
+	* they manage the history stacks themselves, a batch containing one of them records no entry of
+	* its own, leaving the stacks exactly as those methods left them.
+	*/
+	batch(fn) {
+		this.#batchDepth++;
+		if (this.#batchDepth === 1) this.#batchSnapshot = {
+			query: this.#query,
+			past: [...this.#past],
+			future: [...this.#future],
+			lastSig: this.#lastSig,
+			lastAt: this.#lastAt
+		};
+		try {
+			fn();
+		} catch (error) {
+			if (this.#batchDepth === 1) {
+				const snapshot = this.#batchSnapshot;
+				this.#query = snapshot.query;
+				this.#past = snapshot.past;
+				this.#future = snapshot.future;
+				this.#lastSig = snapshot.lastSig;
+				this.#lastAt = snapshot.lastAt;
+			}
+			throw error;
+		} finally {
+			this.#batchDepth--;
+			if (this.#batchDepth === 0) {
+				const { query: base } = this.#batchSnapshot;
+				this.#batchSnapshot = void 0;
+				if (base !== this.#query) {
+					if (!this.#historyBypassed) this.#record(base, this.#query);
+					this.#notify();
+				}
+				this.#historyBypassed = false;
+			}
+		}
+		return this;
+	}
+	/** Whether there is a previous query to restore. Always `false` unless `history` is enabled. */
+	canUndo() {
+		return this.#past.length > 0;
+	}
+	/** Whether there is an undone query to restore. Always `false` unless `history` is enabled. */
+	canRedo() {
+		return this.#future.length > 0;
+	}
+	/** Restores the previous query. No-op when {@link QueryManager.canUndo} is `false`. */
+	undo() {
+		if (this.#past.length === 0) return this;
+		this.#future.unshift(this.#query);
+		this.#query = this.#past.pop();
+		this.#lastSig = void 0;
+		this.#markHistoryBypassed();
+		if (this.#batchDepth === 0) this.#notify();
+		return this;
+	}
+	/** Restores the most recently undone query. No-op when {@link QueryManager.canRedo} is `false`. */
+	redo() {
+		if (this.#future.length === 0) return this;
+		this.#past.push(this.#query);
+		this.#query = this.#future.shift();
+		this.#lastSig = void 0;
+		this.#markHistoryBypassed();
+		if (this.#batchDepth === 0) this.#notify();
+		return this;
+	}
+	/** Discards all undo/redo history without changing the current query. */
+	clearHistory() {
+		this.#markHistoryBypassed();
+		this.#past = [];
+		this.#future = [];
+		this.#lastSig = void 0;
+		return this;
+	}
+	/**
+	* The recorded history: `past` oldest first, `future` newest first. Both are copies, so
+	* mutating them does not affect the manager.
+	*/
+	getHistory() {
+		return {
+			past: [...this.#past],
+			future: [...this.#future]
+		};
+	}
+	/**
+	* Validates the current query with the configured validator.
+	*
+	* The result is cached until the query changes, so a custom `validator` with side effects (or
+	* one that depends on anything other than the query) may run fewer times than expected.
+	*/
+	validate() {
+		this.#ensureCache();
+		this.#validation ??= this.#validator(this.#query);
+		return this.#validation;
+	}
+	format(options) {
+		return formatQuery(this.#query, options);
+	}
+	/**
+	* Yields every rule and group in the query, depth-first in pre-order, starting with the root
+	* group itself. Combinator strings in independent-combinator groups are skipped.
+	*
+	* ```ts
+	* for (const { node, path, parent } of qm.walk({ rulesOnly: true })) {
+	*   console.log(path, node.field);
+	* }
+	* ```
+	*
+	* Traversal operates on the query as it was when iteration began, so mutating the manager
+	* mid-iteration does not affect a walk already in progress. Because generators are lazy, that
+	* happens on the first iteration step rather than when `walk` is called.
+	*
+	* @yields Every rule and group in the query, subject to `options`.
+	*/
+	*walk(options = {}) {
+		const { from, rulesOnly, groupsOnly } = options;
+		let start = this.#query;
+		let startPath = [];
+		let startParent = null;
+		if (from !== void 0) {
+			const path = this.#toPath(from);
+			const node = path && findPath(path, this.#query);
+			if (!path || !node) return;
+			start = node;
+			startPath = path;
+			startParent = path.length === 0 ? null : findPath(getParentPath(path), this.#query);
+		}
+		for (const entry of this.#walkFrom(start, startPath, startParent)) {
+			if (rulesOnly && isRuleGroup(entry.node)) continue;
+			if (groupsOnly && !isRuleGroup(entry.node)) continue;
+			yield entry;
+		}
+	}
+	/** Yields every rule in the query. Shorthand for `walk({ ...options, rulesOnly: true })`. */
+	rules(options = {}) {
+		return this.walk({
+			...options,
+			rulesOnly: true
+		});
+	}
+	/**
+	* Yields every group in the query, including the root group. Shorthand for
+	* `walk({ ...options, groupsOnly: true })`.
+	*/
+	groups(options = {}) {
+		return this.walk({
+			...options,
+			groupsOnly: true
+		});
+	}
+	/** Returns the first node matching `predicate`, or `null` if there is none. */
+	find(predicate, options = {}) {
+		for (const entry of this.walk(options)) if (predicate(entry)) return entry;
+		return null;
+	}
+	/** Returns every node matching `predicate`. */
+	filter(predicate, options = {}) {
+		const results = [];
+		for (const entry of this.walk(options)) if (predicate(entry)) results.push(entry);
+		return results;
+	}
+	/** Equivalent to {@link QueryManager.walk} with no options, enabling `for...of` and spread. */
+	[Symbol.iterator]() {
+		return this.walk();
+	}
+	/**
+	* Returns the rule or group at the given path, or `null` if the path can't be resolved.
+	*
+	* Unlike the standalone {@link findPath}, which can return `undefined` for an out-of-range
+	* index, unresolvable paths are always normalized to `null` here.
+	*/
+	findPath(path) {
+		return findPath(path, this.#query) ?? null;
+	}
+	/**
+	* Returns the rule or group with the given `id`, or `null` if there is none. Backed by an
+	* index built once per query, so repeated lookups are constant time.
+	*/
+	findID(id) {
+		const path = this.#index().get(id);
+		return path === void 0 ? null : findPath(path, this.#query);
+	}
+	/**
+	* Returns the {@link Path} of the rule or group with the given `id`, or `null` if there is
+	* none. Backed by an index built once per query, so repeated lookups are constant time.
+	*/
+	getPathOfID(id) {
+		return this.#index().get(id) ?? null;
+	}
+	/**
+	* Determines whether the rule or group at the given path is disabled, either itself or by an
+	* ancestor group.
+	*/
+	pathIsDisabled(path) {
+		return pathIsDisabled(path, this.#query);
+	}
+	/** Returns the rule or group at the given path or `id`, or `null` if it can't be resolved. */
+	getNode(pathOrID) {
+		const path = this.#toPath(pathOrID);
+		return path === null ? null : findPath(path, this.#query) ?? null;
+	}
+	/**
+	* Returns the rule at the given path or `id`, or `null` if it can't be resolved _or_ resolves
+	* to a group.
+	*/
+	getRule(pathOrID) {
+		const node = this.getNode(pathOrID);
+		return node && !isRuleGroup(node) ? node : null;
+	}
+	/**
+	* Returns the group at the given path or `id`, or `null` if it can't be resolved _or_
+	* resolves to a rule.
+	*/
+	getGroup(pathOrID) {
+		const node = this.getNode(pathOrID);
+		return node && isRuleGroup(node) ? node : null;
+	}
+	/**
+	* Returns the group containing the rule or group at the given path or `id`. Returns `null`
+	* for the root group, which has no parent, and when the target can't be resolved.
+	*/
+	getParent(pathOrID) {
+		const path = this.#toPath(pathOrID);
+		if (path === null || path.length === 0) return null;
+		if (!findPath(path, this.#query)) return null;
+		return findPath(getParentPath(path), this.#query);
+	}
+	/**
+	* The normalized field list, as the `QueryBuilder` component would render it. Needed to
+	* populate a field selector.
+	*/
+	getFields() {
+		return this.#fields;
+	}
+	/**
+	* The normalized combinator list, as the `QueryBuilder` component would render it. Needed to
+	* populate a combinator selector.
+	*/
+	getCombinators() {
+		return this.#combinators;
+	}
+	/**
+	* The field configuration for a field name. When the field isn't configured, returns the same
+	* minimal fallback (`{ name, value, label }`, all set to the field name) that
+	* {@link QueryManager.getRuleContext} reports as `fieldData`, so both access paths agree.
+	*/
+	getFieldData(field) {
+		return getFieldData(field, this.#fieldMap);
+	}
+	/** The operator list for a field, mirroring `QueryBuilder`'s precedence. */
+	getOperators(field) {
+		return this.#operatorsFor(field);
+	}
+	/** The value sources available for a field/operator pair. */
+	getValueSources(field, operator) {
+		return this.#valueSourcesFor(field, operator);
+	}
+	/** The match modes available for a field. */
+	getMatchModes(field) {
+		return this.#matchModesFor(field);
+	}
+	/** The value option list for a field/operator pair. */
+	getValues(field, operator) {
+		return this.#valuesFor(field, operator);
+	}
+	/** The value editor type for a field/operator pair. */
+	getValueEditorType(field, operator) {
+		return this.#valueEditorTypeFor(field, operator);
+	}
+	/**
+	* Resolves everything about a rule that depends on the field/operator configuration—field data,
+	* operators, value editor type, value list, value sources, match modes, and validation result.
+	* Returns `null` when the target can't be resolved or isn't a rule.
+	*
+	* This is the same derivation the `useRule` hook performs, so a non-React implementation can
+	* render a rule without reimplementing the configuration precedence rules.
+	*/
+	getRuleContext(pathOrID) {
+		const rule = this.getRule(pathOrID);
+		if (!rule) return null;
+		const validation = this.validate();
+		return deriveRuleContext(rule, {
+			fields: this.#fields,
+			fieldMap: this.#fieldMap,
+			getInputType: (f, o, misc) => this.#options.getInputType?.(f, o, misc) ?? null,
+			getMatchModes: (f) => this.#matchModesFor(f),
+			getOperators: (f) => this.#operatorsFor(f),
+			getParameters: (f, o, misc) => this.#parametersFor(f, o, misc),
+			getValueEditorType: (f, o) => this.#valueEditorTypeFor(f, o),
+			getValues: (f, o) => this.#valuesFor(f, o),
+			getValueSources: (f, o) => this.getValueSources(f, o),
+			getSubQueryBuilderProps: (f, misc) => this.#options.getSubQueryBuilderProps?.(f, misc) ?? {}
+		}, {
+			validationMap: typeof validation === "boolean" ? {} : validation,
+			id: rule.id
+		});
+	}
+	/**
+	* Resolves everything about a rule group that depends on the combinator configuration, plus its
+	* validation result. Returns `null` when the target can't be resolved or isn't a group.
+	*
+	* This is the same derivation the `useRuleGroup` hook performs.
+	*/
+	getRuleGroupContext(pathOrID = []) {
+		const ruleGroup = this.getGroup(pathOrID);
+		if (!ruleGroup) return null;
+		const validation = this.validate();
+		return deriveRuleGroupContext(ruleGroup, this.#combinators, {
+			validationMap: typeof validation === "boolean" ? {} : validation,
+			id: ruleGroup.id
+		});
+	}
+	/** Whether the current query uses independent combinators. */
+	isIC() {
+		return isRuleGroupTypeIC(this.#query);
+	}
+	/**
+	* Returns the signature describing how the current query differs from `other`, as used by
+	* this manager's history coalescing.
+	*/
+	signatureOf(other) {
+		return signatureOf(this.#query, other);
+	}
+	/** Generates a {@link DiagnosticsResult}. Shorthand for `format('diagnostics')`. */
+	diagnostics() {
+		return formatQuery(this.#query, "diagnostics");
+	}
+	/**
+	* Returns the current query, so `JSON.stringify(queryManager)` produces the same output as
+	* `JSON.stringify(queryManager.getQuery())`.
+	*/
+	toJSON() {
+		return this.#query;
+	}
+	/**
+	* Returns a new manager with the same configuration and the current query converted to use
+	* independent combinators. Idempotent, and never modifies this manager. As with
+	* {@link QueryManager.clone}, subscribers and history are not carried over.
+	*/
+	toIC() {
+		return new QueryManager(convertToIC(this.#query), this.#options);
+	}
+	/**
+	* Returns a new manager with the same configuration and the current query converted to use a
+	* single combinator per group. Idempotent, and never modifies this manager. As with
+	* {@link QueryManager.clone}, subscribers and history are not carried over.
+	*/
+	fromIC() {
+		return new QueryManager(convertFromIC(this.#query), this.#options);
+	}
+	/**
+	* Runs {@link transformQuery} against the current query and returns its result.
+	*
+	* Unlike {@link QueryManager.toIC}/{@link QueryManager.fromIC}, this returns the raw
+	* transformed value rather than a new manager, since `transformQuery` can produce arbitrary
+	* shapes that are no longer valid queries. This manager is never modified.
+	*/
+	transform(options) {
+		return transformQuery(this.#query, options);
+	}
+};
+//#endregion
+export { LogType, QueryManager, QueryManagerError, TestID, add, addInPlace, betweenOperators, bigIntJsonParseReviver, bigIntJsonStringifyReplacer, celCombinatorMap, clsx, coerceBigIntValue, coerceInputType, convertFromIC, convertQuery, convertToIC, createQueryActions, createRule, createRuleGroup, cypherCombinatorMap, defaultCELValueProcessor, defaultCoalesceMs, defaultCombinatorLabelMap, defaultCombinators, defaultCombinatorsExtended, defaultControlClassnames, defaultExportOperatorMap, defaultJoinChar, defaultMatchModes, defaultMaxHistory, defaultMongoDBValueProcessor, defaultNLTranslations, defaultOperatorLabelMap, defaultOperatorNegationMap, defaultOperatorProcessorNL, defaultOperatorProcessorSQL, defaultOperators, defaultPlaceholderFieldGroupLabel, defaultPlaceholderFieldLabel, defaultPlaceholderFieldName, defaultPlaceholderLabel, defaultPlaceholderName, defaultPlaceholderOperatorGroupLabel, defaultPlaceholderOperatorLabel, defaultPlaceholderOperatorName, defaultPlaceholderValueGroupLabel, defaultPlaceholderValueLabel, defaultPlaceholderValueName, defaultRuleGroupProcessorCEL, defaultRuleGroupProcessorCypher, defaultRuleGroupProcessorDiagnostics, defaultRuleGroupProcessorDrizzle, defaultRuleGroupProcessorElasticSearch, defaultRuleGroupProcessorGremlin, defaultRuleGroupProcessorJSONata, defaultRuleGroupProcessorJsonLogic, defaultRuleGroupProcessorLDAP, defaultRuleGroupProcessorMongoDB, defaultRuleGroupProcessorMongoDBQuery, defaultRuleGroupProcessorNL, defaultRuleGroupProcessorParameterized, defaultRuleGroupProcessorPrisma, defaultRuleGroupProcessorSPARQL, defaultRuleGroupProcessorSQL, defaultRuleGroupProcessorSequelize, defaultRuleGroupProcessorSpEL, defaultRuleGroupProcessorTanStackDB, defaultRuleProcessorCEL, defaultRuleProcessorCypher, defaultRuleProcessorDrizzle, defaultRuleProcessorElasticSearch, defaultRuleProcessorGremlin, defaultRuleProcessorJSONata, defaultRuleProcessorJsonLogic, defaultRuleProcessorLDAP, defaultRuleProcessorMongoDB, defaultRuleProcessorMongoDBQuery, defaultRuleProcessorNL, defaultRuleProcessorParameterized, defaultRuleProcessorPrisma, defaultRuleProcessorSPARQL, defaultRuleProcessorSQL, defaultRuleProcessorSequelize, defaultRuleProcessorSpEL, defaultRuleProcessorTanStackDB, defaultSpELValueProcessor, defaultTranslations, defaultValidator, defaultValueProcessor, defaultValueProcessorByRule, defaultValueProcessorCELByRule, defaultValueProcessorMongoDBByRule, defaultValueProcessorNL, defaultValueProcessorSpELByRule, derivePathInfo, deriveRuleClassName, deriveRuleClassNames, deriveRuleContext, deriveRuleGroupClassNames, deriveRuleGroupContext, deriveRuleGroupOuterClassName, deriveRuleOuterClassName, exceedsMaxLevels, filterFieldsByComparator, findID, findPath, formatQuery, formatQueryOptionPresets, generateAccessibleDescription, generateID, getCommonAncestorPath, getFieldData, getFirstOption, getGuardAbortReason, getLikeWildcards, getMatchModesUtil, getMultiValueUpdate, getNLTranslataion, getOption, getParametersAsList, getParentPath, getParseNumberMethod, getPathOfID, getQuoteFieldNamesWithArray, getQuotedFieldName, getRuleDefaultValue, getRuleGroupCombinator, getRuleInputType, getRuleValidationResult, getRuleValueEditorType, getRuleValueSourceOptions, getRuleValues, getSQLConcat, getSubqueryElementAlias, getValidationClassNames, getValueEditorReset, getValueSelectorUpdate, getValueSourcesUtil, group, groupInPlace, groupInvalidReasons, hideValueControlsForOperator, inOperators, insert, insertInPlace, isAncestor, isBetweenOperator, isFlexibleOptionArray, isFlexibleOptionGroupArray, isFullOptionArray, isFullOptionGroupArray, isOptionGroupArray, isPojo, isRuleGroup, isRuleGroupType, isRuleGroupTypeIC, isRuleOrGroupValid, isRuleType, isUnsafeKey, isValidValue, isValidationResult, isValueProcessorLegacy, joinWith, jsonLogicAdditionalOperators, lc, mapSQLOperator, mergeAnyTranslation, mergeAnyTranslations, mergeClassnames, mongoDbFallback, mongoOperators, move, moveInPlace, normalizeConstituentWordOrder, normalizeValueSelectorValue, nullFreeArray, nullOperators, nullOrUndefinedOrEmpty, numericRegex, numerifyValues, objectEntries, objectKeys, parseNumber, pathIsDisabled, pathIsDisabledByPaths, pathsAreEqual, preferAnyProp, preferFlagProps, preferProp, prepareOptionList, prepareRule, prepareRuleGroup, prepareRuleOrGroup, prismaFallback, prismaOperators, processMatchMode, queryBuilderFlagDefaults, regenerateID, regenerateIDs, relationalOperators, remove, removeInPlace, resolveCandidateQuery, resolveDefaultOperator, resolveOperatorList, resolveValueEditorType, resolveValueList, rootPath, shouldRenderAsNumber, signatureOf, sparqlVar, splitBy, sqlDialectPresets, standardClassnames, strictAbortReasons, stripParamPrefix, structuralSignature, subqueryElementAliasBase, substringOperators, toArray, toFlatOptionArray, toFullOption, toFullOptionList, toFullOptionMap, transformQuery, trimIfString, unchangedSignature, uniqByIdentifier, uniqByName, uniqOptGroups, uniqOptList, update, updateInPlace, uuidV4regex, withParamPrefix, wrapLikeFragment };
 
 //# sourceMappingURL=react-querybuilder_core.mjs.map