@atscript/ui-table 0.1.137 → 0.1.139

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { isLogicalKey } from "@uniqu/core";
 import { ClientError } from "@atscript/db-client";
 import { getDefaultClientFactory, str } from "@atscript/ui";
 import { buildUrl } from "@uniqu/url/builder";
@@ -134,6 +135,40 @@ function columnFilterType(columnType) {
 		default: return "text";
 	}
 }
+const EXISTENCE_CONDITIONS = ["null", "notNull"];
+const NO_CONDITIONS = [];
+/**
+* Filter conditions a column offers — the one answer every filter UI (column
+* menu, filter dialog, filter bar, config dialog) reads.
+*
+* - Value-filterable (`filterable: true`) → {@link conditionsForType} for its
+*   display type.
+* - Existence-only (`filterable: false`, `filterOps` includes `$exists` — a
+*   JSON-stored column) → `null` / `notNull`: whether a value is present,
+*   never what it is.
+* - Otherwise → `[]`: the column takes no filter.
+*
+* `null` / `notNull` are dropped for non-nullable columns, so an existence-only
+* column that is never empty offers nothing.
+*
+* @since 0.1.139
+*/
+function columnFilterConditions(column) {
+	if (column.filterable) return conditionsForType(columnFilterType(column.type), column.nullable);
+	if (column.nullable && column.filterOps?.includes("$exists")) return EXISTENCE_CONDITIONS;
+	return NO_CONDITIONS;
+}
+/**
+* Whether a column takes any filter at all — value comparisons or the
+* existence-only `null` / `notNull` pair. Use it (not
+* `column.filterable`, which is value comparison only) to decide whether to
+* show a column in a filter UI.
+*
+* @since 0.1.139
+*/
+function isColumnFilterable(column) {
+	return columnFilterConditions(column).length > 0;
+}
 //#endregion
 //#region src/filters/escape-regex.ts
 /** Escape special regex characters in user input for safe embedding in $regex. */
@@ -175,6 +210,18 @@ function defaultCondition(columnType) {
 		default: return "eq";
 	}
 }
+/**
+* The condition a column's filter input starts with: its type's
+* {@link defaultCondition} when the column offers it, otherwise the first
+* condition it does offer (`null` on an existence-only column).
+*
+* @since 0.1.139
+*/
+function columnDefaultCondition(column) {
+	const type = defaultCondition(columnFilterType(column.type));
+	const offered = columnFilterConditions(column);
+	return offered.length === 0 || offered.includes(type) ? type : offered[0];
+}
 /** Prefix operators in match order (longest first). */
 const PREFIX_OPS = [
 	["!=", "ne"],
@@ -207,12 +254,26 @@ const PREFIX_OPS = [
 *   number/date/boolean → eq
 *
 * Returns undefined for empty/invalid input or if the parsed operator
-* is not available for the column type.
+* is not available for the column type. To honour what a specific column
+* offers (an existence-only column takes only `<empty>` / `!<empty>`), use
+* {@link parseColumnFilterInput}.
 */
 function parseFilterInput(text, columnType, nullable = true) {
+	return parseInput(text, columnType, conditionsForType(columnType, nullable));
+}
+/**
+* {@link parseFilterInput} for a column: the type comes from the column and
+* the accepted operators are {@link columnFilterConditions} — the ones the
+* column's filter UI offers.
+*
+* @since 0.1.139
+*/
+function parseColumnFilterInput(text, column) {
+	return parseInput(text, columnFilterType(column.type), columnFilterConditions(column));
+}
+function parseInput(text, columnType, available) {
 	const trimmed = text.trim();
 	if (trimmed === "") return void 0;
-	const available = conditionsForType(columnType, nullable);
 	const isNumber = columnType === "number";
 	const build = (type, value) => {
 		if (!available.includes(type)) return void 0;
@@ -288,6 +349,10 @@ function formatFilterCondition(condition) {
 //#region src/filters/filters-to-uniquery.ts
 /** Exclusion condition types — AND'd together per field. */
 const EXCLUSION_TYPES = new Set(["ne", "notNull"]);
+/** Whether conditions of `type` are exclusions (AND'd per field) rather than inclusions (OR'd). */
+function isExclusionType(type) {
+	return EXCLUSION_TYPES.has(type);
+}
 /**
 * Convert a single condition to a Uniquery filter expression.
 * Returns a ComparisonNode with the field as key.
@@ -336,7 +401,7 @@ function filtersToUniqueryFilter(fieldFilters) {
 		for (const condition of conditions) {
 			if (!isFilled(condition)) continue;
 			const expr = conditionToExpr(field, condition);
-			if (EXCLUSION_TYPES.has(condition.type)) (exclusions ??= []).push(expr);
+			if (isExclusionType(condition.type)) (exclusions ??= []).push(expr);
 			else (inclusions ??= []).push(expr);
 		}
 		if (inclusions) pushGroup(topGroups, inclusions, "$or");
@@ -347,25 +412,33 @@ function filtersToUniqueryFilter(fieldFilters) {
 	return { $and: topGroups };
 }
 //#endregion
+//#region src/utils/dev.ts
+/**
+* `true` outside a production build — the gate for authoring-time warnings, so
+* their strings and checks cost a shipped app nothing.
+*
+* Read from `process.env.NODE_ENV` rather than `import.meta.env`: bundlers
+* replace this expression with a literal in both the ESM and the CJS output,
+* while `import.meta` only exists in the former. Where neither a bundler nor a
+* `process` shim is present the read throws — warnings stay on, which is the
+* safe side of the trade.
+*/
+function detectDev() {
+	try {
+		return process.env.NODE_ENV !== "production";
+	} catch {
+		return true;
+	}
+}
+const DEV = detectDev();
+//#endregion
 //#region src/filters/uniquery-to-filters.ts
-const SUPPORTED_TYPES = new Set([
-	"eq",
-	"ne",
-	"gt",
-	"gte",
-	"lt",
-	"lte",
-	"contains",
-	"starts",
-	"ends",
-	"bw",
-	"null",
-	"notNull",
-	"regex"
-]);
 function isPrimitive(v) {
 	return typeof v === "string" || typeof v === "number" || typeof v === "boolean";
 }
+function isPlainObject(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v) && !(v instanceof RegExp) && !(v instanceof Date);
+}
 const REGEX_LITERAL = /^\/(.*)\/([a-z]*)$/s;
 const STARTS_ANCHOR = /^\^(.+)$/s;
 const ENDS_ANCHOR = /^(.+)\$$/s;
@@ -376,6 +449,7 @@ const ENDS_ANCHOR = /^(.+)\$$/s;
 * `regex` condition.
 */
 function regexToCondition(raw) {
+	if (raw instanceof RegExp) raw = raw.toString();
 	if (typeof raw !== "string") return null;
 	const m = REGEX_LITERAL.exec(raw);
 	if (!m) return {
@@ -404,108 +478,324 @@ function regexToCondition(raw) {
 		value: [raw]
 	};
 }
-function pushIfPrimitive(out, type, v) {
-	if (!isPrimitive(v)) return;
-	out.push({
-		type,
+const nullCond = () => ({
+	type: "null",
+	value: []
+});
+const notNullCond = () => ({
+	type: "notNull",
+	value: []
+});
+/** Positive condition for one `$eq` / `$in` value — `null` means "is empty". */
+function memberCondition(v) {
+	if (v === null) return nullCond();
+	return isPrimitive(v) ? {
+		type: "eq",
 		value: [v]
-	});
+	} : null;
+}
+/** Negative condition for one `$ne` / `$nin` value — `null` means "is not empty". */
+function nonMemberCondition(v) {
+	if (v === null) return notNullCond();
+	return isPrimitive(v) ? {
+		type: "ne",
+		value: [v]
+	} : null;
+}
+const RANGE_OPS = {
+	$gt: "gt",
+	$gte: "gte",
+	$lt: "lt",
+	$lte: "lte"
+};
+/** Field paths an expression references, deduped, in order of appearance. */
+function fieldsOf(expr, out = []) {
+	if (Array.isArray(expr)) {
+		for (const child of expr) fieldsOf(child, out);
+		return out;
+	}
+	if (!isPlainObject(expr)) return out;
+	for (const key in expr) if (key.startsWith("$")) fieldsOf(expr[key], out);
+	else if (!out.includes(key)) out.push(key);
+	return out;
 }
+function unsupported(reason, expr) {
+	const fields = fieldsOf(expr);
+	return {
+		reason: fields.length > 1 ? "cross-field" : reason,
+		expr,
+		fields
+	};
+}
+const isNegative = (term) => isExclusionType(term.conds[0].type);
 /**
-* Decode a per-field operator object (e.g. `{ $gt: 5, $lte: 10 }`) into one or
-* more `FilterCondition`s. Unknown operators are silently dropped.
-*
-* `$gte` + `$lte` on the same field collapse into a single `bw` condition,
-* matching the encoder's behaviour.
+* Add decoded conditions as terms: negatives one term each (they AND), a
+* positive list as one group (it ORs). Conditions share their polarity.
 */
-function decodeFieldOps(ops) {
-	const out = [];
-	const hasGte = "$gte" in ops && isPrimitive(ops.$gte);
-	const hasLte = "$lte" in ops && isPrimitive(ops.$lte);
-	if (hasGte && hasLte) out.push({
-		type: "bw",
-		value: [ops.$gte, ops.$lte]
+function addTerms(out, field, conds, expr) {
+	if (conds.length === 0) return;
+	if (isExclusionType(conds[0].type)) for (const cond of conds) out.terms.push({
+		field,
+		conds: [cond],
+		expr
 	});
-	else {
-		if (hasGte) pushIfPrimitive(out, "gte", ops.$gte);
-		if (hasLte) pushIfPrimitive(out, "lte", ops.$lte);
-	}
-	if ("$eq" in ops) pushIfPrimitive(out, "eq", ops.$eq);
-	if ("$ne" in ops) pushIfPrimitive(out, "ne", ops.$ne);
-	if ("$gt" in ops) pushIfPrimitive(out, "gt", ops.$gt);
-	if ("$lt" in ops) pushIfPrimitive(out, "lt", ops.$lt);
-	if ("$exists" in ops) {
-		if (ops.$exists === false) out.push({
-			type: "null",
-			value: []
-		});
-		else if (ops.$exists === true) out.push({
-			type: "notNull",
-			value: []
-		});
+	else out.terms.push({
+		field,
+		conds,
+		expr
+	});
+}
+/**
+* `a>=x` AND `a<=y` is the model's `bw`, whether both halves sit in one
+* operator object (the encoder's shape) or in two AND-ed pieces. Folds `cond`
+* into an earlier lone opposite half on `field`; `false` when there is none.
+*/
+function pairRange(out, field, cond) {
+	const opposite = cond.type === "gte" ? "lte" : cond.type === "lte" ? "gte" : null;
+	if (!opposite) return false;
+	const i = out.terms.findIndex((t) => t.field === field && t.conds.length === 1 && t.conds[0].type === opposite);
+	if (i < 0) return false;
+	const other = out.terms[i].conds[0];
+	const [lo, hi] = cond.type === "gte" ? [cond.value[0], other.value[0]] : [other.value[0], cond.value[0]];
+	out.terms[i] = {
+		field,
+		conds: [{
+			type: "bw",
+			value: [lo, hi]
+		}],
+		expr: { [field]: {
+			$gte: lo,
+			$lte: hi
+		} }
+	};
+	return true;
+}
+/**
+* Decode one field entry (`field: value`) into terms. An operator object is an
+* implicit AND of its operators — each becomes its own term.
+*/
+function collectField(field, value, out) {
+	const whole = { [field]: value };
+	if (value === null || value === void 0) return addTerms(out, field, [nullCond()], whole);
+	if (isPrimitive(value)) return addTerms(out, field, [{
+		type: "eq",
+		value: [value]
+	}], whole);
+	if (value instanceof RegExp) return addTerms(out, field, [regexToCondition(value)], whole);
+	if (!isPlainObject(value)) {
+		out.issues.push(unsupported("operator", whole));
+		return;
 	}
-	if ("$regex" in ops) {
-		const cond = regexToCondition(ops.$regex);
-		if (cond) out.push(cond);
+	for (const op in value) {
+		const v = value[op];
+		if (v === void 0) continue;
+		const expr = { [field]: { [op]: v } };
+		const conds = decodeOperator(op, v);
+		if (!conds) out.issues.push(unsupported("operator", expr));
+		else if (conds.length !== 1 || !pairRange(out, field, conds[0])) addTerms(out, field, conds, expr);
 	}
-	return out;
 }
+const one = (cond) => cond ? [cond] : null;
 /**
-* Walk a leaf `ComparisonNode` (one or more field=value entries) into the
-* shared `FieldFilters` accumulator. Drops unknown fields and operators.
+* One operator of a field's operator object, as conditions of one polarity
+* (see {@link addTerms}). `null` means no condition type expresses the
+* operator / operand.
 */
-function walkLeaf(node, acc, knownFields) {
-	for (const field in node) {
-		if (field.startsWith("$")) continue;
-		if (knownFields && !knownFields.has(field)) continue;
-		const value = node[field];
-		let conditions;
-		if (value === null || value === void 0) conditions = [{
-			type: "null",
-			value: []
-		}];
-		else if (isPrimitive(value)) conditions = [{
-			type: "eq",
-			value: [value]
-		}];
-		else if (typeof value === "object" && !Array.isArray(value)) conditions = decodeFieldOps(value);
-		else continue;
-		if (conditions.length === 0) continue;
-		const filtered = conditions.filter((c) => SUPPORTED_TYPES.has(c.type));
-		if (filtered.length === 0) continue;
-		if (acc[field]) acc[field] = [...acc[field], ...filtered];
-		else acc[field] = filtered;
-	}
-}
-function walkExpr(expr, acc, knownFields) {
-	if ("$and" in expr && expr.$and) {
-		for (const child of expr.$and) walkExpr(child, acc, knownFields);
+function decodeOperator(op, v) {
+	if (op in RANGE_OPS) return one(isPrimitive(v) ? {
+		type: RANGE_OPS[op],
+		value: [v]
+	} : null);
+	switch (op) {
+		case "$eq": return one(memberCondition(v));
+		case "$ne": return one(nonMemberCondition(v));
+		case "$regex": return one(regexToCondition(v));
+		case "$exists":
+			if (v === false) return one(nullCond());
+			return v === true ? one(notNullCond()) : null;
+		case "$in": {
+			const conds = Array.isArray(v) ? v.map(memberCondition) : [];
+			return conds.length > 0 && conds.every(Boolean) ? conds : null;
+		}
+		case "$nin": {
+			if (!Array.isArray(v)) return null;
+			const conds = v.map(nonMemberCondition);
+			return conds.every(Boolean) ? conds : null;
+		}
+		default: return null;
+	}
+}
+/**
+* Decode an `$or` branch / `$not` operand on its own. Usable only when it
+* converts fully and stays on one field; `null` when it constrains nothing.
+* A branch that spans fields comes back with a placeholder reason —
+* {@link unsupported} names it `"cross-field"` from the fields it sees.
+*/
+function classifyBranch(expr) {
+	const sub = {
+		terms: [],
+		issues: []
+	};
+	collect(expr, sub);
+	if (sub.issues.length > 0) return { reason: sub.issues[0].reason };
+	if (sub.terms.length === 0) return null;
+	const field = sub.terms[0].field;
+	if (sub.terms.some((t) => t.field !== field)) return { reason: "operator" };
+	return {
+		field,
+		terms: sub.terms
+	};
+}
+/**
+* `$or` fits the model only as a same-field OR of positive branches. Each
+* branch must decode to exactly one positive group; the groups merge.
+*/
+function collectOr(branches, out) {
+	const expr = { $or: branches };
+	if (!Array.isArray(branches) || branches.length === 0) {
+		out.issues.push(unsupported("operator", expr));
+		return;
+	}
+	if (branches.length === 1) return collect(branches[0], out);
+	const groups = [];
+	let reason;
+	for (const branch of branches) {
+		const b = classifyBranch(branch);
+		if (b === null) return;
+		if ("reason" in b) reason ??= b.reason;
+		else if (b.terms.length > 1) reason ??= "conjunction";
+		else if (isNegative(b.terms[0])) reason ??= "negation";
+		else groups.push(b.terms[0]);
+	}
+	const field = groups[0]?.field;
+	if (reason !== void 0 || groups.some((t) => t.field !== field)) {
+		out.issues.push(unsupported(reason ?? "operator", expr));
 		return;
 	}
-	if ("$or" in expr && expr.$or) {
-		for (const child of expr.$or) walkExpr(child, acc, knownFields);
+	out.terms.push({
+		field,
+		conds: groups.flatMap((t) => t.conds),
+		expr
+	});
+}
+const INVERSE = {
+	eq: "ne",
+	ne: "eq",
+	null: "notNull",
+	notNull: "null"
+};
+function invert(cond) {
+	const type = INVERSE[cond.type];
+	return type ? {
+		type,
+		value: [...cond.value]
+	} : null;
+}
+/**
+* `$not` fits when it inverts equality / emptiness on one field — De Morgan
+* turns NOT(a=1 OR a=2) into a≠1 AND a≠2 (negatives), and NOT(a≠1 AND a≠2)
+* back into a=1 OR a=2 (one positive group). A positive group AND'd with
+* anything else would invert into an OR of ANDs, which the model cannot hold.
+*/
+function collectNot(child, out) {
+	const expr = { $not: child };
+	const b = classifyBranch(child);
+	if (b && !("reason" in b) && (b.terms.length === 1 || b.terms.every(isNegative))) {
+		const inverted = b.terms.flatMap((t) => t.conds).map(invert);
+		if (inverted.every(Boolean)) return addTerms(out, b.field, inverted, expr);
+	}
+	out.issues.push(unsupported("negation", expr));
+}
+function collectAnd(children, out) {
+	if (Array.isArray(children)) for (const child of children) collect(child, out);
+	else out.issues.push(unsupported("operator", { $and: children }));
+}
+const LOGICAL = {
+	$and: collectAnd,
+	$or: collectOr,
+	$not: collectNot
+};
+/**
+* Split an expression into AND-ed terms. Every member of a node is an implicit
+* AND, in key order — comparison fields may sit next to `$and` / `$or` /
+* `$not` (Mongo semantics), and none of them is skipped.
+*/
+function collect(expr, out) {
+	if (!isPlainObject(expr)) {
+		out.issues.push(unsupported("operator", expr));
 		return;
 	}
-	if ("$not" in expr && expr.$not) return;
-	walkLeaf(expr, acc, knownFields);
+	for (const key in expr) {
+		const value = expr[key];
+		if (!key.startsWith("$")) collectField(key, value, out);
+		else if (value === void 0) continue;
+		else if (isLogicalKey(key)) LOGICAL[key](value, out);
+		else out.issues.push(unsupported("operator", { [key]: value }));
+	}
+}
+function sameConds(a, b) {
+	return a.length === b.length && a.every((c, i) => c.type === b[i].type && c.value.length === b[i].value.length && c.value.every((v, j) => v === b[i].value[j]));
+}
+function warnUnsupported(issue) {
+	if (!DEV) return;
+	console.warn(`[ui-table] Filter left out (${issue.reason}): ${JSON.stringify(issue.expr)}. Field filters cannot express it, so the result is broader than the source filter.`);
 }
 /**
 * Convert a Uniquery `FilterExpr` back into the UI's `FieldFilters` shape.
 *
-* Inverse of `filtersToUniqueryFilter`. Drops:
-* - conditions on fields not in `knownFields` (when provided)
-* - operators not in the supported `FilterConditionType` union
-* - `$not` branches (no native UI representation; lossy on hand-crafted URLs)
+* Inverse of `filtersToUniqueryFilter`, and exact for everything that encoder
+* produces. For any other input, each AND-ed piece is either converted exactly
+* or left out whole and reported — never approximated:
+*
+* - `$in` becomes equality conditions on the field, `$nin` inequality ones.
+* - A same-field `$or` becomes that field's OR'd conditions.
+* - A `$not` that inverts equality / emptiness becomes the inverse conditions.
+* - Fields next to `$and` / `$or` / `$not` in one object are all kept.
+* - Anything else (see {@link UnsupportedFilterReason}) is left out. Leaving
+*   an AND-ed piece out only ever widens the match, so the result selects a
+*   superset of `expr`. Each left-out piece goes to `onUnsupportedFilter`, or
+*   to a dev-mode `console.warn` when no handler is given.
+*
+* Conditions on fields outside `knownFields` (when provided) are ignored
+* silently: they are not this table's (a host page flag, a stale column). A
+* piece that mixes known and unknown fields is reported.
 *
 * Returns `{}` for an empty/missing expression. Never throws.
 */
-function uniqueryFilterToFieldFilters(expr, knownFields) {
+function uniqueryFilterToFieldFilters(expr, knownFields, onUnsupportedFilter = warnUnsupported) {
 	const acc = {};
 	if (!expr) return acc;
 	const known = knownFields == null ? null : knownFields instanceof Set ? knownFields : new Set(knownFields);
+	const isKnown = (field) => known === null || known.has(field);
+	const out = {
+		terms: [],
+		issues: []
+	};
 	try {
-		walkExpr(expr, acc, known);
-	} catch {}
+		collect(expr, out);
+	} catch {
+		out.terms = [];
+		out.issues = [{
+			reason: "operator",
+			expr,
+			fields: []
+		}];
+	}
+	const positives = /* @__PURE__ */ new Map();
+	for (const term of out.terms) {
+		if (!isKnown(term.field)) continue;
+		const list = acc[term.field] ??= [];
+		const kept = positives.get(term.field);
+		if (isNegative(term) || !kept) {
+			if (!isNegative(term)) positives.set(term.field, term.conds);
+			list.push(...term.conds);
+		} else if (!sameConds(kept, term.conds)) out.issues.push({
+			reason: "conjunction",
+			expr: term.expr,
+			fields: [term.field]
+		});
+	}
+	for (const issue of out.issues) if (issue.fields.length === 0 || issue.fields.some(isKnown)) onUnsupportedFilter(issue);
 	return acc;
 }
 //#endregion
@@ -1213,6 +1503,20 @@ function buildTableQuery(opts) {
 }
 //#endregion
 //#region src/query/url-query.ts
+/**
+* The URL control that marks a query string as a complete snapshot of the
+* table's filters and sorters. Restoring a URL that carries it clears every
+* filter and sorter the URL owns before applying its own, so nothing the URL
+* omits survives (empty `$sort` included). A URL without it is an overlay:
+* its filters and sorters are laid over the table's starting ones.
+*
+* The encoder writes it bare (`…&$snapshot`) on every URL; the decoder goes
+* by presence alone, whatever the value. `UrlQuerySync.snapshot: false` turns
+* both off.
+*
+* @since 0.1.139
+*/
+const URL_SNAPSHOT_KEY = "$snapshot";
 function resolveAspectGate(value) {
 	if (value === void 0 || value === true) return "all";
 	if (value === false) return "none";
@@ -1251,7 +1555,9 @@ function pickFilterPaths(filters, gate) {
 * `$actions`, `forceFilters`, `forceSorters` — those are not user state) and
 * appends `$skip` / `$limit` for pagination.
 *
-* Returns `""` (no leading `?`) for the default view.
+* Stamps {@link URL_SNAPSHOT_KEY} unless `defaults.sync.snapshot` is `false`
+* (or neither filters nor sorters sync), so the default view serializes to
+* `"$snapshot"`; with the marker off it serializes to `""` (no leading `?`).
 */
 function stateToUrlQueryString(state, defaults) {
 	const filtersGate = resolveAspectGate(defaults.sync?.filters);
@@ -1271,6 +1577,7 @@ function stateToUrlQueryString(state, defaults) {
 		const page = state.page ?? 1;
 		if (page > 1) query.controls.$skip = (page - 1) * itemsPerPage;
 	}
+	if (defaults.sync?.snapshot !== false && (filtersGate !== "none" || sortersGate !== "none")) query.controls[URL_SNAPSHOT_KEY] = "";
 	return buildUrl(query);
 }
 /**
@@ -1281,7 +1588,8 @@ const CONSUMED_CONTROLS = new Set([
 	"$sort",
 	"$search",
 	"$relevance",
-	"$skip"
+	"$skip",
+	URL_SNAPSHOT_KEY
 ]);
 /** Characters that can only appear in a uniqu filter key, never in a page flag. */
 const FILTER_OPERATOR_CHAR = /[<>!~]/;
@@ -1309,7 +1617,9 @@ function urlQueryConsumesKey(key) {
 * Robust by design — schema drift and copy-paste errors must not break the
 * recipient's view:
 * - unknown fields (not in `knownFields`) → silently dropped
-* - unsupported operators → silently dropped
+* - filter pieces field filters cannot express (cross-field OR, unknown
+*   operator, …) → left out of `filters` and listed in `unsupported`, never
+*   approximated (the parser does not warn — the caller decides)
 * - unknown controls (e.g. `$weird=42`) → silently ignored
 * - malformed query → `{ filters: {}, sorters: [], searchTerm: "" }`
 *
@@ -1344,7 +1654,8 @@ function urlQueryStringToState(urlString, opts = {}) {
 		filterKnown = /* @__PURE__ */ new Set();
 		for (const path of filtersGate) if (knownSet.has(path)) filterKnown.add(path);
 	} else filterKnown = filtersGate;
-	const filters = filtersGate === "none" ? {} : uniqueryFilterToFieldFilters(parsed.filter, filterKnown);
+	const unsupported = [];
+	const filters = filtersGate === "none" ? {} : uniqueryFilterToFieldFilters(parsed.filter, filterKnown, (issue) => unsupported.push(issue));
 	const sorters = [];
 	if (sortersGate !== "none") {
 		const $sort = parsed.controls?.$sort;
@@ -1368,6 +1679,8 @@ function urlQueryStringToState(urlString, opts = {}) {
 		sorters,
 		searchTerm: !searchOff && typeof $search === "string" ? $search : ""
 	};
+	if (unsupported.length > 0) out.unsupported = unsupported;
+	if (opts.sync?.snapshot !== false && parsed.controls && "$snapshot" in parsed.controls) out.snapshot = true;
 	if (!searchOff) {
 		const $relevance = parsed.controls?.$relevance;
 		if ($relevance === "1" || $relevance === 1) out.ignoreSorters = true;
@@ -1918,4 +2231,4 @@ function sortRowsLocally(rows, sorters, getValue = (row, field) => row[field]) {
 	});
 }
 //#endregion
-export { APP_CONF_PREFIX, AppPrefsClient, DEFAULT_EXPORT_PAGE_SIZE, DEFAULT_ROW_HEIGHT_PX, DRAFT_PERSISTED_ASPECTS, ExportAbortError, MAX_DEFAULT_COLUMN_WIDTH_PX, NULL_OPS, PRESET_ASPECTS, PresetsClient, PresetsHttpError, RESERVED_ID_PREFIXES, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, USER_CONF_PREFIX, appConfId, arraysEqual, blockStartFor, buildTableQuery, cellAsString, clampTopIndex, collectExportRows, columnFilterType, computeDefaultColumnWidth, conditionLabel, conditionsForType, csvCell, dateShortcuts, debounce, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, fromWireSnapshot, gateOwns, hasSecondValue, isAuthError, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeDisplayColumns, mergeFilters, mergeSorters, normaliseSystemPresetId, pageAlignedBlocksFor, parseFilterInput, planFetch, reconcileColumnWidthDefaults, reorderColumnNames, resolveAspectGate, resolveExportValue, resolveSystemPresets, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortRowsLocally, sortersEqual, stableStringify, stateToUrlQueryString, toCsv, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryConsumesKey, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb, withStableOrder };
+export { APP_CONF_PREFIX, AppPrefsClient, DEFAULT_EXPORT_PAGE_SIZE, DEFAULT_ROW_HEIGHT_PX, DEV, DRAFT_PERSISTED_ASPECTS, ExportAbortError, MAX_DEFAULT_COLUMN_WIDTH_PX, NULL_OPS, PRESET_ASPECTS, PresetsClient, PresetsHttpError, RESERVED_ID_PREFIXES, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, URL_SNAPSHOT_KEY, USER_CONF_PREFIX, appConfId, arraysEqual, blockStartFor, buildTableQuery, cellAsString, clampTopIndex, collectExportRows, columnDefaultCondition, columnFilterConditions, columnFilterType, computeDefaultColumnWidth, conditionLabel, conditionsForType, csvCell, dateShortcuts, debounce, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, fromWireSnapshot, gateOwns, hasSecondValue, isAuthError, isColumnFilterable, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeDisplayColumns, mergeFilters, mergeSorters, normaliseSystemPresetId, pageAlignedBlocksFor, parseColumnFilterInput, parseFilterInput, planFetch, reconcileColumnWidthDefaults, reorderColumnNames, resolveAspectGate, resolveExportValue, resolveSystemPresets, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortRowsLocally, sortersEqual, stableStringify, stateToUrlQueryString, toCsv, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryConsumesKey, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb, withStableOrder };