@atscript/ui-table 0.1.140 → 0.1.141

package/dist/index.cjs

@@ -528,6 +528,7 @@ function fieldsOf(expr, out) {
 	else if (!out.includes(key)) out.push(key);
 	return out;
 }
+/** @internal Module-shared with the URL parser; not a package export. */
 function unsupported(reason, expr) {
 	const fields = fieldsOf(expr, []);
 	return {
@@ -753,10 +754,10 @@ function warnUnsupported(issue) {
 /**
 * Split a Uniquery `FilterExpr` into what the table's field-filter model
 * holds exactly (`filters`), what it cannot hold but carries as residual
-* conditions (`residual`, with `carry`), and what it leaves out
-* (`unsupported`). Nothing is approximated: `filters AND residual` selects
-* `expr` minus the `unsupported` pieces and pieces on fields outside
-* `knownFields`.
+* conditions (`residual`, with `carry`), what it leaves out (`unsupported`)
+* and what names a field outside `knownFields` (`unknown`). Nothing is
+* approximated: `filters AND residual` selects `expr` minus the
+* `unsupported` and `unknown` pieces.
 *
 * Never throws, never warns — the caller decides how to report.
 *
@@ -767,7 +768,8 @@ function decomposeUniqueryFilter(expr, opts = {}) {
 	const result = {
 		filters,
 		residual: [],
-		unsupported: []
+		unsupported: [],
+		unknown: []
 	};
 	if (!expr) return result;
 	const knownFields = opts.knownFields;
@@ -788,8 +790,12 @@ function decomposeUniqueryFilter(expr, opts = {}) {
 		}];
 	}
 	const positives = /* @__PURE__ */ new Map();
+	const unknown = /* @__PURE__ */ new Map();
 	for (const term of out.terms) {
-		if (!isKnown(term.field)) continue;
+		if (!isKnown(term.field)) {
+			unknown.set(term.expr, [term.field]);
+			continue;
+		}
 		const list = filters[term.field] ??= [];
 		if (isNegative(term)) {
 			list.push(...term.conds);
@@ -819,11 +825,16 @@ function decomposeUniqueryFilter(expr, opts = {}) {
 	}
 	for (const issue of out.issues) {
 		const fields = issue.fields;
-		if (fields.length > 0 && !fields.some(isKnown)) continue;
-		if (opts.carry && fields.length > 0 && fields.every(isKnown)) carried.push(issue.expr);
+		const outside = fields.filter((f) => !isKnown(f));
+		if (outside.length > 0) unknown.set(issue.expr, outside);
+		else if (opts.carry && fields.length > 0) carried.push(issue.expr);
 		else result.unsupported.push(issue);
 	}
 	result.residual = normalizeResidualFilters(carried);
+	result.unknown = [...unknown].map(([expr, fields]) => ({
+		expr,
+		fields
+	}));
 	return result;
 }
 /**
@@ -874,9 +885,10 @@ function normalizeResidualFilters(exprs) {
 *   to a dev-mode `console.warn` when no handler is given. To keep those
 *   pieces instead, use {@link decomposeUniqueryFilter} with `carry`.
 *
-* 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.
+* Pieces that name a field outside `knownFields` (when provided) are ignored
+* silently: they are not this table's (a host page flag, a hidden or stale
+* column). Since 0.1.141 that includes a piece mixing known and unknown
+* fields — {@link decomposeUniqueryFilter} lists them as `unknown`.
 *
 * Returns `{}` for an empty/missing expression. Never throws.
 */
@@ -1146,6 +1158,137 @@ function resolveSystemPresets(input) {
 	}, ...named];
 }
 //#endregion
+//#region src/presets/prune-preset-snapshot.ts
+/** `[kept, dropped]` in one pass. */
+function partition(list, keep) {
+	const kept = [];
+	const dropped = [];
+	for (const x of list) (keep(x) ? kept : dropped).push(x);
+	return [kept, dropped];
+}
+/** The columns aspect, an empty width map spelled by omission — the way capture writes it. */
+function columnsAspect(columnNames, columnWidths) {
+	return columnWidths && Object.keys(columnWidths).length > 0 ? {
+		columnNames,
+		columnWidths
+	} : { columnNames };
+}
+/**
+* Remove every entry of `snapshot` that names a field outside `known`, per
+* aspect:
+*
+* - `columns.columnNames` — unknown names go, the rest keep their order. When
+*   none survives, it falls back to every column, never an empty grid.
+* - `columns.columnWidths` — unknown keys go.
+* - `filters` (displayed inputs) and `filterOps` — entries on a field outside
+*   `known.server` go. A field's conditions are one AND-ed conjunct, so
+*   dropping one only broadens the result.
+* - `sorters` — unknown entries go, the rest keep their priority.
+* - `itemsPerPage` — untouched.
+*
+* `dropped` is `null` when nothing user-visible went (a width-only drop is
+* hygiene). The input is never mutated.
+*
+* @since 0.1.141
+*/
+function prunePresetSnapshot(snapshot, known) {
+	const isColumn = (p) => known.columns.has(p);
+	const isServer = (p) => known.server.has(p);
+	const out = { ...snapshot };
+	const dropped = {
+		fields: [],
+		columns: [],
+		filterFields: [],
+		filters: {},
+		residual: [],
+		sorters: []
+	};
+	if (snapshot.columns) {
+		const [names, gone] = partition(snapshot.columns.columnNames, isColumn);
+		const [widths] = partition(Object.entries(snapshot.columns.columnWidths ?? {}), ([p]) => isColumn(p));
+		dropped.columns = gone;
+		out.columns = columnsAspect(names.length > 0 || gone.length === 0 ? names : [...known.columns], Object.fromEntries(widths));
+	}
+	if (snapshot.filters) [out.filters, dropped.filterFields] = partition(snapshot.filters, isServer);
+	if (snapshot.filterOps) {
+		const [kept, gone] = partition(Object.entries(snapshot.filterOps), ([p]) => isServer(p));
+		out.filterOps = Object.fromEntries(kept);
+		dropped.filters = Object.fromEntries(gone);
+	}
+	if (snapshot.sorters) [out.sorters, dropped.sorters] = partition(snapshot.sorters, (s) => isColumn(s.field));
+	dropped.fields = [...new Set([
+		...dropped.columns,
+		...dropped.filterFields,
+		...Object.keys(dropped.filters),
+		...dropped.sorters.map((s) => s.field)
+	])];
+	return {
+		snapshot: out,
+		dropped: dropped.fields.length > 0 ? dropped : null
+	};
+}
+/**
+* Split residual filter conditions, in one pass, into the ones that name
+* only `known` fields and the ones that do not. A condition naming any
+* unknown field is dropped WHOLE — never pruned inside an `$or` (that would
+* narrow the result) or a `$not` (that would invert it). Each condition is an
+* AND-ed conjunct, so dropping one only broadens the result.
+*
+* `dropped` holds the conditions in `residual` and the unknown paths in
+* `fields`; `null` when every condition is kept.
+*
+* @since 0.1.141
+*/
+function pruneResidualFilters(exprs, known) {
+	const kept = [];
+	const residual = [];
+	const fields = /* @__PURE__ */ new Set();
+	for (const expr of exprs) {
+		const unknown = filterExprFields(expr).filter((p) => !known.has(p));
+		if (unknown.length === 0) {
+			kept.push(expr);
+			continue;
+		}
+		residual.push(expr);
+		for (const p of unknown) fields.add(p);
+	}
+	if (residual.length === 0) return {
+		kept,
+		dropped: null
+	};
+	return {
+		kept,
+		dropped: {
+			fields: [...fields],
+			columns: [],
+			filterFields: [],
+			filters: {},
+			residual,
+			sorters: []
+		}
+	};
+}
+/**
+* Append what a prune dropped back onto a snapshot captured from (pruned)
+* table state, so overwriting a preset with a narrower view does not destroy
+* the parts the saver cannot see. Column names, filter inputs and sorters go
+* after the captured ones; field filters are added back. Only aspects
+* `captured` carries are touched; widths of hidden columns are not kept.
+*
+* @since 0.1.141
+*/
+function restoreDroppedEntries(captured, dropped) {
+	const out = { ...captured };
+	if (captured.columns) out.columns = columnsAspect([...captured.columns.columnNames, ...dropped.columns], captured.columns.columnWidths);
+	if (captured.filters) out.filters = [...captured.filters, ...dropped.filterFields];
+	if (captured.filterOps) out.filterOps = {
+		...captured.filterOps,
+		...dropped.filters
+	};
+	if (captured.sorters) out.sorters = [...captured.sorters, ...dropped.sorters];
+	return out;
+}
+//#endregion
 //#region src/presets/preset-dirty.ts
 /**
 * JSON-stringify with object keys sorted alphabetically at every depth so
@@ -1749,6 +1892,20 @@ const CONSUMED_CONTROLS = new Set([
 	"$skip",
 	URL_SNAPSHOT_KEY
 ]);
+function toSet(paths) {
+	if (!paths) return null;
+	return paths instanceof Set ? paths : new Set(paths);
+}
+/**
+* `field=value` (or `field=null`) — the one filter shape a host page flag
+* shares, so a bare one on an unknown field is not reported as dropped.
+*/
+function isBareEquality(expr) {
+	const keys = Object.keys(expr);
+	if (keys.length !== 1 || keys[0].startsWith("$")) return false;
+	const v = expr[keys[0]];
+	return v === null || typeof v !== "object";
+}
 /**
 * Characters that can only appear in a uniqu filter key, never in a page flag:
 * comparison operators, `^` (OR), `( )` (groups) and `{ }` (`$in` lists).
@@ -1775,9 +1932,10 @@ function urlQueryConsumesKey(key) {
 /**
 * Parse a URL query string back into the table state subset.
 *
-* Robust by design — schema drift and copy-paste errors must not break the
-* recipient's view:
-* - unknown fields (not in `knownFields`) → silently dropped
+* Robust by design — schema drift, fields hidden from the recipient and
+* copy-paste errors must not break the recipient's view:
+* - unknown fields (not in `knownFields`) → dropped, listed in `unknown` /
+*   `unknownSorters` (the parser does not warn — the caller decides)
 * - 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). Unless
@@ -1810,12 +1968,15 @@ function urlQueryStringToState(urlString, opts = {}) {
 	const sortersGate = resolveAspectGate(opts.sync?.sorters);
 	const searchOff = opts.sync?.search === false;
 	const paginationOff = opts.sync?.pagination === false;
-	const knownSet = opts.knownFields ? new Set(opts.knownFields) : null;
+	const knownSet = toSet(opts.knownFields);
+	const localSet = toSet(opts.localFields);
+	const isHidden = (f) => !!knownSet && !knownSet.has(f) && !localSet?.has(f);
 	let filterKnown;
 	if (filtersGate === "all") filterKnown = knownSet ?? void 0;
 	else if (filtersGate !== "none") if (knownSet) {
-		filterKnown = /* @__PURE__ */ new Set();
-		for (const path of filtersGate) if (knownSet.has(path)) filterKnown.add(path);
+		const owned = /* @__PURE__ */ new Set();
+		for (const path of filtersGate) if (knownSet.has(path)) owned.add(path);
+		filterKnown = owned;
 	} else filterKnown = filtersGate;
 	const decomposed = filtersGate === "none" ? null : decomposeUniqueryFilter(parsed.filter, {
 		knownFields: filterKnown,
@@ -1823,20 +1984,19 @@ function urlQueryStringToState(urlString, opts = {}) {
 	});
 	const filters = decomposed?.filters ?? {};
 	const sorters = [];
+	const unknownSorters = [];
 	if (sortersGate !== "none") {
 		const $sort = parsed.controls?.$sort;
 		if ($sort && typeof $sort === "object") for (const field in $sort) {
-			if (knownSet && !knownSet.has(field)) continue;
 			if (!gateOwns(sortersGate, field)) continue;
 			const dir = $sort[field];
-			if (dir === 1) sorters.push({
-				field,
-				direction: "asc"
-			});
-			else if (dir === -1) sorters.push({
+			if (dir !== 1 && dir !== -1) continue;
+			const sorter = {
 				field,
-				direction: "desc"
-			});
+				direction: dir === 1 ? "asc" : "desc"
+			};
+			if (!knownSet || knownSet.has(field)) sorters.push(sorter);
+			else if (isHidden(field)) unknownSorters.push(sorter);
 		}
 	}
 	const $search = parsed.controls?.$search;
@@ -1845,8 +2005,24 @@ function urlQueryStringToState(urlString, opts = {}) {
 		sorters,
 		searchTerm: !searchOff && typeof $search === "string" ? $search : ""
 	};
-	if (decomposed?.unsupported.length) out.unsupported = decomposed.unsupported;
+	const unsupported$1 = decomposed?.unsupported ?? [];
+	const unknown = [];
+	for (const piece of decomposed?.unknown ?? []) {
+		const hidden = piece.fields.filter(isHidden);
+		if (hidden.length > 0) {
+			if (!isBareEquality(piece.expr)) unknown.push({
+				expr: piece.expr,
+				fields: hidden
+			});
+			continue;
+		}
+		const issue = unsupported("cross-field", piece.expr);
+		if (issue.fields.some((f) => filterKnown?.has(f))) unsupported$1.push(issue);
+	}
+	if (unsupported$1.length) out.unsupported = unsupported$1;
 	if (decomposed?.residual.length) out.residual = decomposed.residual;
+	if (unknown.length) out.unknown = unknown;
+	if (unknownSorters.length) out.unknownSorters = unknownSorters;
 	if (opts.sync?.snapshot !== false && parsed.controls && "$snapshot" in parsed.controls) out.snapshot = true;
 	if (!searchOff) {
 		const $relevance = parsed.controls?.$relevance;
@@ -2464,12 +2640,15 @@ exports.pageAlignedBlocksFor = pageAlignedBlocksFor;
 exports.parseColumnFilterInput = parseColumnFilterInput;
 exports.parseFilterInput = parseFilterInput;
 exports.planFetch = planFetch;
+exports.prunePresetSnapshot = prunePresetSnapshot;
+exports.pruneResidualFilters = pruneResidualFilters;
 exports.reconcileColumnWidthDefaults = reconcileColumnWidthDefaults;
 exports.reorderColumnNames = reorderColumnNames;
 exports.residualGateOwns = residualGateOwns;
 exports.resolveAspectGate = resolveAspectGate;
 exports.resolveExportValue = resolveExportValue;
 exports.resolveSystemPresets = resolveSystemPresets;
+exports.restoreDroppedEntries = restoreDroppedEntries;
 exports.rowsToPks = rowsToPks;
 exports.sameColumnSet = sameColumnSet;
 exports.serializeDraft = serializeDraft;

package/dist/index.d.cts

@@ -175,6 +175,18 @@ interface UnsupportedFilter {
   /** Field paths the sub-expression references, in order of appearance. */
   fields: string[];
 }
+/**
+ * One AND-ed piece of a Uniquery filter left out because it names a field
+ * outside `knownFields` — alone or next to known ones.
+ *
+ * @since 0.1.141
+ */
+interface UnknownFilter {
+  /** The left-out sub-expression, as it appeared in the input. */
+  expr: FilterExpr;
+  /** The paths it names that are outside `knownFields`. */
+  fields: string[];
+}
 /**
  * Field paths a Uniquery filter expression references, deduped, in order of
  * appearance (logical operators are walked, operator keys skipped).
@@ -185,9 +197,10 @@ declare function filterExprFields(expr: unknown): string[];
 /** Options for {@link decomposeUniqueryFilter}. @since 0.1.140 */
 interface DecomposeUniqueryFilterOptions {
   /**
-   * Field paths the table knows. Pieces on fields outside it are ignored
-   * silently; a piece mixing known and unknown fields is reported, never
-   * carried. Omit to accept every field.
+   * Field paths the table knows. A piece that names a field outside it —
+   * alone or mixed with known ones — is left out whole and listed in
+   * `unknown`, never carried or reported as `unsupported`. Omit to accept
+   * every field.
    */
   knownFields?: Iterable<string>;
   /**
@@ -205,14 +218,22 @@ interface DecomposedUniqueryFilter {
   residual: FilterExpr[];
   /** Pieces left out and lost — the result is broader by exactly these. */
   unsupported: UnsupportedFilter[];
+  /**
+   * Pieces left out because they name a field outside `knownFields` (hidden
+   * from the caller, or not in the schema). Each is a whole AND-ed piece, so
+   * the result is broader by exactly these too. `[]` without `knownFields`.
+   * Since 0.1.141 — before, pieces on unknown fields only were dropped
+   * silently and mixed known/unknown pieces went to `unsupported`.
+   */
+  unknown: UnknownFilter[];
 }
 /**
  * Split a Uniquery `FilterExpr` into what the table's field-filter model
  * holds exactly (`filters`), what it cannot hold but carries as residual
- * conditions (`residual`, with `carry`), and what it leaves out
- * (`unsupported`). Nothing is approximated: `filters AND residual` selects
- * `expr` minus the `unsupported` pieces and pieces on fields outside
- * `knownFields`.
+ * conditions (`residual`, with `carry`), what it leaves out (`unsupported`)
+ * and what names a field outside `knownFields` (`unknown`). Nothing is
+ * approximated: `filters AND residual` selects `expr` minus the
+ * `unsupported` and `unknown` pieces.
  *
  * Never throws, never warns — the caller decides how to report.
  *
@@ -253,9 +274,10 @@ declare function normalizeResidualFilters(exprs: readonly FilterExpr[]): FilterE
  *   to a dev-mode `console.warn` when no handler is given. To keep those
  *   pieces instead, use {@link decomposeUniqueryFilter} with `carry`.
  *
- * 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.
+ * Pieces that name a field outside `knownFields` (when provided) are ignored
+ * silently: they are not this table's (a host page flag, a hidden or stale
+ * column). Since 0.1.141 that includes a piece mixing known and unknown
+ * fields — {@link decomposeUniqueryFilter} lists them as `unknown`.
  *
  * Returns `{}` for an empty/missing expression. Never throws.
  */
@@ -530,6 +552,96 @@ interface SystemPresetInput {
  */
 declare function resolveSystemPresets(input?: SystemPresetInput[]): SystemPreset[];
 //#endregion
+//#region src/presets/prune-preset-snapshot.d.ts
+/**
+ * The field paths a table can use, derived from its column list. A path
+ * outside these sets is one the server does not expose to the current caller
+ * (hidden by role, removed from the schema) — naming it in a query is rejected.
+ *
+ * @since 0.1.141
+ */
+interface KnownFields {
+  /**
+   * Every column path, client-owned (display) columns included, in column
+   * order. Gates `columnNames`, column widths and sorters (a sorter on a
+   * client-owned column is applied in memory).
+   */
+  columns: ReadonlySet<string>;
+  /**
+   * Server-backed column paths. Gates displayed filter inputs, field filters
+   * and residual filter conditions.
+   */
+  server: ReadonlySet<string>;
+}
+/**
+ * What pruning left out of a preset snapshot or of residual conditions
+ * because it names a field outside {@link KnownFields}.
+ *
+ * @since 0.1.141
+ */
+interface DroppedFields {
+  /** The unavailable field paths behind the drops, deduped, in order of appearance. */
+  fields: string[];
+  /** Dropped `columnNames` entries. */
+  columns: string[];
+  /** Dropped displayed filter inputs. */
+  filterFields: string[];
+  /** Dropped field filters — whole entries, one per field. */
+  filters: FieldFilters;
+  /** Dropped filter conditions — each a whole AND-ed conjunct. */
+  residual: FilterExpr[];
+  /** Dropped sorters. */
+  sorters: SortControl[];
+}
+/**
+ * Remove every entry of `snapshot` that names a field outside `known`, per
+ * aspect:
+ *
+ * - `columns.columnNames` — unknown names go, the rest keep their order. When
+ *   none survives, it falls back to every column, never an empty grid.
+ * - `columns.columnWidths` — unknown keys go.
+ * - `filters` (displayed inputs) and `filterOps` — entries on a field outside
+ *   `known.server` go. A field's conditions are one AND-ed conjunct, so
+ *   dropping one only broadens the result.
+ * - `sorters` — unknown entries go, the rest keep their priority.
+ * - `itemsPerPage` — untouched.
+ *
+ * `dropped` is `null` when nothing user-visible went (a width-only drop is
+ * hygiene). The input is never mutated.
+ *
+ * @since 0.1.141
+ */
+declare function prunePresetSnapshot(snapshot: PresetSnapshot, known: KnownFields): {
+  snapshot: PresetSnapshot;
+  dropped: DroppedFields | null;
+};
+/**
+ * Split residual filter conditions, in one pass, into the ones that name
+ * only `known` fields and the ones that do not. A condition naming any
+ * unknown field is dropped WHOLE — never pruned inside an `$or` (that would
+ * narrow the result) or a `$not` (that would invert it). Each condition is an
+ * AND-ed conjunct, so dropping one only broadens the result.
+ *
+ * `dropped` holds the conditions in `residual` and the unknown paths in
+ * `fields`; `null` when every condition is kept.
+ *
+ * @since 0.1.141
+ */
+declare function pruneResidualFilters(exprs: FilterExpr[], known: ReadonlySet<string>): {
+  kept: FilterExpr[];
+  dropped: DroppedFields | null;
+};
+/**
+ * Append what a prune dropped back onto a snapshot captured from (pruned)
+ * table state, so overwriting a preset with a narrower view does not destroy
+ * the parts the saver cannot see. Column names, filter inputs and sorters go
+ * after the captured ones; field filters are added back. Only aspects
+ * `captured` carries are touched; widths of hidden columns are not kept.
+ *
+ * @since 0.1.141
+ */
+declare function restoreDroppedEntries(captured: PresetSnapshot, dropped: DroppedFields): PresetSnapshot;
+//#endregion
 //#region src/presets/preset-dirty.d.ts
 /**
  * JSON-stringify with object keys sorted alphabetically at every depth so
@@ -888,6 +1000,21 @@ interface UrlQueryStateSnapshot {
    * or `sync.residual` is `false`. Since 0.1.140.
    */
   residual?: FilterExpr[];
+  /**
+   * Filter pieces left out because they name a field outside `knownFields`
+   * and `localFields` — a column hidden from this caller, or gone from the
+   * schema — with those paths in `fields`. Each is a whole AND-ed piece (a
+   * mixed known/unknown one included), so the result is broader by exactly
+   * these. A bare `field=value` piece is not listed: without the table
+   * definition it reads the same as a flag of the host page. Omitted when
+   * none. Since 0.1.141 — before, a mixed piece was listed in `unsupported`.
+   */
+  unknown?: UnknownFilter[];
+  /**
+   * `$sort` entries left out because their field is outside `knownFields`
+   * and `localFields`. Omitted when none. Since 0.1.141.
+   */
+  unknownSorters?: SortControl[];
   /**
    * Raw record offset from `$skip` (omitted when no `$skip` in URL). The
    * decoder does NOT compute a page index — that requires `itemsPerPage`,
@@ -1013,20 +1140,29 @@ declare function stateToUrlQueryString(state: UrlQueryStateLike, defaults: UrlQu
 declare function urlQueryConsumesKey(key: string): boolean;
 interface UrlQueryParseOptions {
   /**
-   * Field paths the table knows about. Conditions on fields outside this set
-   * are silently dropped. Omit to accept any field (useful when the table
-   * definition isn't loaded yet).
+   * Field paths the table knows about. Conditions and sorters on fields
+   * outside this set are dropped and listed in `unknown` / `unknownSorters`.
+   * Omit to accept any field (useful when the table definition isn't loaded
+   * yet).
    */
   knownFields?: Iterable<string>;
+  /**
+   * Client-owned column paths. The URL never restores them (no server query
+   * can use them), but they are not unknown either: a sorter on one is
+   * ignored, and a filter piece correlating one with a known field is
+   * reported as `unsupported` (`"cross-field"`). Since 0.1.141.
+   */
+  localFields?: Iterable<string>;
   /** Per-aspect sync gates — must match the encoder's config to keep the round-trip symmetric. */
   sync?: UrlQuerySync;
 }
 /**
  * Parse a URL query string back into the table state subset.
  *
- * Robust by design — schema drift and copy-paste errors must not break the
- * recipient's view:
- * - unknown fields (not in `knownFields`) → silently dropped
+ * Robust by design — schema drift, fields hidden from the recipient and
+ * copy-paste errors must not break the recipient's view:
+ * - unknown fields (not in `knownFields`) → dropped, listed in `unknown` /
+ *   `unknownSorters` (the parser does not warn — the caller decides)
  * - 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). Unless
@@ -1561,4 +1697,4 @@ declare function sortRowsLocally<T extends Record<string, unknown>>(rows: T[], s
 //#region src/utils/dev.d.ts
 declare const DEV: boolean;
 //#endregion
-export { APP_CONF_PREFIX, type AppConfData, AppPrefsClient, type AppPrefsClientConfig, type AppPrefsLoadResult, type AsPresetEntryData, type AsPresetEntryRow, type AsPresetsErrorCode, type AspectGate, type AspectMask, type BuildTableQueryOptions, type ColumnFilterType, type ColumnReorderPosition, type ColumnWidthEntry, type ColumnWidthsMap, type ConfigTab, type CsvOptions, DEFAULT_EXPORT_PAGE_SIZE, DEFAULT_ROW_HEIGHT_PX, DEV, DRAFT_PERSISTED_ASPECTS, type DateShortcut, type DecomposeUniqueryFilterOptions, type DecomposedUniqueryFilter, type DisplayColumnDef, type DraftPersistedAspect, ExportAbortError, type ExportPage, type ExportPageFetcher, type ExportScalar, type FetchPlan, type FetchPlanMode, type FieldFilters, type FilterCondition, type FilterConditionType, type FilterableColumn, MAX_DEFAULT_COLUMN_WIDTH_PX, type MergeResult, NULL_OPS, PRESET_ASPECTS, type PageAlignedBlock, type PlanFetchArgs, type PresetAspect, type PresetCapabilities, type PresetColumnWidthEntry, type PresetData, type PresetDraft, type PresetFilterOpEntry, type PresetLimitReachedBody, type PresetSnapshot, type PresetSnapshotWire, type PresetSorterEntry, PresetsClient, type PresetsClientConfig, PresetsHttpError, type PresetsListResult, type PresetsSaveAsOptions, type PresetsSaveResult, type QueryOptions, RESERVED_ID_PREFIXES, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, type SelectionMode, type SystemPreset, type SystemPresetInput, type TableStateData, type TableStateMethods, URL_SNAPSHOT_KEY, USER_CONF_PREFIX, type UnsupportedFilter, type UnsupportedFilterReason, type UrlQueryDefaults, type UrlQueryParseOptions, type UrlQueryStateLike, type UrlQueryStateSnapshot, type UrlQuerySync, type UserConfData, appConfId, arraysEqual, blockStartFor, buildTableQuery, cellAsString, clampTopIndex, collectExportRows, columnDefaultCondition, columnFilterConditions, columnFilterType, computeDefaultColumnWidth, conditionLabel, conditionsForType, csvCell, dateShortcuts, debounce, decomposeUniqueryFilter, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterExprFields, filterExprKey, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, formatFilterExpr, fromWireSnapshot, gateOwns, hasSecondValue, isAuthError, isColumnFilterable, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeDisplayColumns, mergeFilters, mergeSorters, normaliseSystemPresetId, normalizeResidualFilters, pageAlignedBlocksFor, parseColumnFilterInput, parseFilterInput, planFetch, reconcileColumnWidthDefaults, reorderColumnNames, residualGateOwns, 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, type AppConfData, AppPrefsClient, type AppPrefsClientConfig, type AppPrefsLoadResult, type AsPresetEntryData, type AsPresetEntryRow, type AsPresetsErrorCode, type AspectGate, type AspectMask, type BuildTableQueryOptions, type ColumnFilterType, type ColumnReorderPosition, type ColumnWidthEntry, type ColumnWidthsMap, type ConfigTab, type CsvOptions, DEFAULT_EXPORT_PAGE_SIZE, DEFAULT_ROW_HEIGHT_PX, DEV, DRAFT_PERSISTED_ASPECTS, type DateShortcut, type DecomposeUniqueryFilterOptions, type DecomposedUniqueryFilter, type DisplayColumnDef, type DraftPersistedAspect, type DroppedFields, ExportAbortError, type ExportPage, type ExportPageFetcher, type ExportScalar, type FetchPlan, type FetchPlanMode, type FieldFilters, type FilterCondition, type FilterConditionType, type FilterableColumn, type KnownFields, MAX_DEFAULT_COLUMN_WIDTH_PX, type MergeResult, NULL_OPS, PRESET_ASPECTS, type PageAlignedBlock, type PlanFetchArgs, type PresetAspect, type PresetCapabilities, type PresetColumnWidthEntry, type PresetData, type PresetDraft, type PresetFilterOpEntry, type PresetLimitReachedBody, type PresetSnapshot, type PresetSnapshotWire, type PresetSorterEntry, PresetsClient, type PresetsClientConfig, PresetsHttpError, type PresetsListResult, type PresetsSaveAsOptions, type PresetsSaveResult, type QueryOptions, RESERVED_ID_PREFIXES, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, type SelectionMode, type SystemPreset, type SystemPresetInput, type TableStateData, type TableStateMethods, URL_SNAPSHOT_KEY, USER_CONF_PREFIX, type UnknownFilter, type UnsupportedFilter, type UnsupportedFilterReason, type UrlQueryDefaults, type UrlQueryParseOptions, type UrlQueryStateLike, type UrlQueryStateSnapshot, type UrlQuerySync, type UserConfData, appConfId, arraysEqual, blockStartFor, buildTableQuery, cellAsString, clampTopIndex, collectExportRows, columnDefaultCondition, columnFilterConditions, columnFilterType, computeDefaultColumnWidth, conditionLabel, conditionsForType, csvCell, dateShortcuts, debounce, decomposeUniqueryFilter, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterExprFields, filterExprKey, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, formatFilterExpr, fromWireSnapshot, gateOwns, hasSecondValue, isAuthError, isColumnFilterable, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeDisplayColumns, mergeFilters, mergeSorters, normaliseSystemPresetId, normalizeResidualFilters, pageAlignedBlocksFor, parseColumnFilterInput, parseFilterInput, planFetch, prunePresetSnapshot, pruneResidualFilters, reconcileColumnWidthDefaults, reorderColumnNames, residualGateOwns, resolveAspectGate, resolveExportValue, resolveSystemPresets, restoreDroppedEntries, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortRowsLocally, sortersEqual, stableStringify, stateToUrlQueryString, toCsv, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryConsumesKey, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb, withStableOrder };

package/dist/index.d.mts

@@ -175,6 +175,18 @@ interface UnsupportedFilter {
   /** Field paths the sub-expression references, in order of appearance. */
   fields: string[];
 }
+/**
+ * One AND-ed piece of a Uniquery filter left out because it names a field
+ * outside `knownFields` — alone or next to known ones.
+ *
+ * @since 0.1.141
+ */
+interface UnknownFilter {
+  /** The left-out sub-expression, as it appeared in the input. */
+  expr: FilterExpr;
+  /** The paths it names that are outside `knownFields`. */
+  fields: string[];
+}
 /**
  * Field paths a Uniquery filter expression references, deduped, in order of
  * appearance (logical operators are walked, operator keys skipped).
@@ -185,9 +197,10 @@ declare function filterExprFields(expr: unknown): string[];
 /** Options for {@link decomposeUniqueryFilter}. @since 0.1.140 */
 interface DecomposeUniqueryFilterOptions {
   /**
-   * Field paths the table knows. Pieces on fields outside it are ignored
-   * silently; a piece mixing known and unknown fields is reported, never
-   * carried. Omit to accept every field.
+   * Field paths the table knows. A piece that names a field outside it —
+   * alone or mixed with known ones — is left out whole and listed in
+   * `unknown`, never carried or reported as `unsupported`. Omit to accept
+   * every field.
    */
   knownFields?: Iterable<string>;
   /**
@@ -205,14 +218,22 @@ interface DecomposedUniqueryFilter {
   residual: FilterExpr[];
   /** Pieces left out and lost — the result is broader by exactly these. */
   unsupported: UnsupportedFilter[];
+  /**
+   * Pieces left out because they name a field outside `knownFields` (hidden
+   * from the caller, or not in the schema). Each is a whole AND-ed piece, so
+   * the result is broader by exactly these too. `[]` without `knownFields`.
+   * Since 0.1.141 — before, pieces on unknown fields only were dropped
+   * silently and mixed known/unknown pieces went to `unsupported`.
+   */
+  unknown: UnknownFilter[];
 }
 /**
  * Split a Uniquery `FilterExpr` into what the table's field-filter model
  * holds exactly (`filters`), what it cannot hold but carries as residual
- * conditions (`residual`, with `carry`), and what it leaves out
- * (`unsupported`). Nothing is approximated: `filters AND residual` selects
- * `expr` minus the `unsupported` pieces and pieces on fields outside
- * `knownFields`.
+ * conditions (`residual`, with `carry`), what it leaves out (`unsupported`)
+ * and what names a field outside `knownFields` (`unknown`). Nothing is
+ * approximated: `filters AND residual` selects `expr` minus the
+ * `unsupported` and `unknown` pieces.
  *
  * Never throws, never warns — the caller decides how to report.
  *
@@ -253,9 +274,10 @@ declare function normalizeResidualFilters(exprs: readonly FilterExpr[]): FilterE
  *   to a dev-mode `console.warn` when no handler is given. To keep those
  *   pieces instead, use {@link decomposeUniqueryFilter} with `carry`.
  *
- * 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.
+ * Pieces that name a field outside `knownFields` (when provided) are ignored
+ * silently: they are not this table's (a host page flag, a hidden or stale
+ * column). Since 0.1.141 that includes a piece mixing known and unknown
+ * fields — {@link decomposeUniqueryFilter} lists them as `unknown`.
  *
  * Returns `{}` for an empty/missing expression. Never throws.
  */
@@ -530,6 +552,96 @@ interface SystemPresetInput {
  */
 declare function resolveSystemPresets(input?: SystemPresetInput[]): SystemPreset[];
 //#endregion
+//#region src/presets/prune-preset-snapshot.d.ts
+/**
+ * The field paths a table can use, derived from its column list. A path
+ * outside these sets is one the server does not expose to the current caller
+ * (hidden by role, removed from the schema) — naming it in a query is rejected.
+ *
+ * @since 0.1.141
+ */
+interface KnownFields {
+  /**
+   * Every column path, client-owned (display) columns included, in column
+   * order. Gates `columnNames`, column widths and sorters (a sorter on a
+   * client-owned column is applied in memory).
+   */
+  columns: ReadonlySet<string>;
+  /**
+   * Server-backed column paths. Gates displayed filter inputs, field filters
+   * and residual filter conditions.
+   */
+  server: ReadonlySet<string>;
+}
+/**
+ * What pruning left out of a preset snapshot or of residual conditions
+ * because it names a field outside {@link KnownFields}.
+ *
+ * @since 0.1.141
+ */
+interface DroppedFields {
+  /** The unavailable field paths behind the drops, deduped, in order of appearance. */
+  fields: string[];
+  /** Dropped `columnNames` entries. */
+  columns: string[];
+  /** Dropped displayed filter inputs. */
+  filterFields: string[];
+  /** Dropped field filters — whole entries, one per field. */
+  filters: FieldFilters;
+  /** Dropped filter conditions — each a whole AND-ed conjunct. */
+  residual: FilterExpr[];
+  /** Dropped sorters. */
+  sorters: SortControl[];
+}
+/**
+ * Remove every entry of `snapshot` that names a field outside `known`, per
+ * aspect:
+ *
+ * - `columns.columnNames` — unknown names go, the rest keep their order. When
+ *   none survives, it falls back to every column, never an empty grid.
+ * - `columns.columnWidths` — unknown keys go.
+ * - `filters` (displayed inputs) and `filterOps` — entries on a field outside
+ *   `known.server` go. A field's conditions are one AND-ed conjunct, so
+ *   dropping one only broadens the result.
+ * - `sorters` — unknown entries go, the rest keep their priority.
+ * - `itemsPerPage` — untouched.
+ *
+ * `dropped` is `null` when nothing user-visible went (a width-only drop is
+ * hygiene). The input is never mutated.
+ *
+ * @since 0.1.141
+ */
+declare function prunePresetSnapshot(snapshot: PresetSnapshot, known: KnownFields): {
+  snapshot: PresetSnapshot;
+  dropped: DroppedFields | null;
+};
+/**
+ * Split residual filter conditions, in one pass, into the ones that name
+ * only `known` fields and the ones that do not. A condition naming any
+ * unknown field is dropped WHOLE — never pruned inside an `$or` (that would
+ * narrow the result) or a `$not` (that would invert it). Each condition is an
+ * AND-ed conjunct, so dropping one only broadens the result.
+ *
+ * `dropped` holds the conditions in `residual` and the unknown paths in
+ * `fields`; `null` when every condition is kept.
+ *
+ * @since 0.1.141
+ */
+declare function pruneResidualFilters(exprs: FilterExpr[], known: ReadonlySet<string>): {
+  kept: FilterExpr[];
+  dropped: DroppedFields | null;
+};
+/**
+ * Append what a prune dropped back onto a snapshot captured from (pruned)
+ * table state, so overwriting a preset with a narrower view does not destroy
+ * the parts the saver cannot see. Column names, filter inputs and sorters go
+ * after the captured ones; field filters are added back. Only aspects
+ * `captured` carries are touched; widths of hidden columns are not kept.
+ *
+ * @since 0.1.141
+ */
+declare function restoreDroppedEntries(captured: PresetSnapshot, dropped: DroppedFields): PresetSnapshot;
+//#endregion
 //#region src/presets/preset-dirty.d.ts
 /**
  * JSON-stringify with object keys sorted alphabetically at every depth so
@@ -888,6 +1000,21 @@ interface UrlQueryStateSnapshot {
    * or `sync.residual` is `false`. Since 0.1.140.
    */
   residual?: FilterExpr[];
+  /**
+   * Filter pieces left out because they name a field outside `knownFields`
+   * and `localFields` — a column hidden from this caller, or gone from the
+   * schema — with those paths in `fields`. Each is a whole AND-ed piece (a
+   * mixed known/unknown one included), so the result is broader by exactly
+   * these. A bare `field=value` piece is not listed: without the table
+   * definition it reads the same as a flag of the host page. Omitted when
+   * none. Since 0.1.141 — before, a mixed piece was listed in `unsupported`.
+   */
+  unknown?: UnknownFilter[];
+  /**
+   * `$sort` entries left out because their field is outside `knownFields`
+   * and `localFields`. Omitted when none. Since 0.1.141.
+   */
+  unknownSorters?: SortControl[];
   /**
    * Raw record offset from `$skip` (omitted when no `$skip` in URL). The
    * decoder does NOT compute a page index — that requires `itemsPerPage`,
@@ -1013,20 +1140,29 @@ declare function stateToUrlQueryString(state: UrlQueryStateLike, defaults: UrlQu
 declare function urlQueryConsumesKey(key: string): boolean;
 interface UrlQueryParseOptions {
   /**
-   * Field paths the table knows about. Conditions on fields outside this set
-   * are silently dropped. Omit to accept any field (useful when the table
-   * definition isn't loaded yet).
+   * Field paths the table knows about. Conditions and sorters on fields
+   * outside this set are dropped and listed in `unknown` / `unknownSorters`.
+   * Omit to accept any field (useful when the table definition isn't loaded
+   * yet).
    */
   knownFields?: Iterable<string>;
+  /**
+   * Client-owned column paths. The URL never restores them (no server query
+   * can use them), but they are not unknown either: a sorter on one is
+   * ignored, and a filter piece correlating one with a known field is
+   * reported as `unsupported` (`"cross-field"`). Since 0.1.141.
+   */
+  localFields?: Iterable<string>;
   /** Per-aspect sync gates — must match the encoder's config to keep the round-trip symmetric. */
   sync?: UrlQuerySync;
 }
 /**
  * Parse a URL query string back into the table state subset.
  *
- * Robust by design — schema drift and copy-paste errors must not break the
- * recipient's view:
- * - unknown fields (not in `knownFields`) → silently dropped
+ * Robust by design — schema drift, fields hidden from the recipient and
+ * copy-paste errors must not break the recipient's view:
+ * - unknown fields (not in `knownFields`) → dropped, listed in `unknown` /
+ *   `unknownSorters` (the parser does not warn — the caller decides)
  * - 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). Unless
@@ -1561,4 +1697,4 @@ declare function sortRowsLocally<T extends Record<string, unknown>>(rows: T[], s
 //#region src/utils/dev.d.ts
 declare const DEV: boolean;
 //#endregion
-export { APP_CONF_PREFIX, type AppConfData, AppPrefsClient, type AppPrefsClientConfig, type AppPrefsLoadResult, type AsPresetEntryData, type AsPresetEntryRow, type AsPresetsErrorCode, type AspectGate, type AspectMask, type BuildTableQueryOptions, type ColumnFilterType, type ColumnReorderPosition, type ColumnWidthEntry, type ColumnWidthsMap, type ConfigTab, type CsvOptions, DEFAULT_EXPORT_PAGE_SIZE, DEFAULT_ROW_HEIGHT_PX, DEV, DRAFT_PERSISTED_ASPECTS, type DateShortcut, type DecomposeUniqueryFilterOptions, type DecomposedUniqueryFilter, type DisplayColumnDef, type DraftPersistedAspect, ExportAbortError, type ExportPage, type ExportPageFetcher, type ExportScalar, type FetchPlan, type FetchPlanMode, type FieldFilters, type FilterCondition, type FilterConditionType, type FilterableColumn, MAX_DEFAULT_COLUMN_WIDTH_PX, type MergeResult, NULL_OPS, PRESET_ASPECTS, type PageAlignedBlock, type PlanFetchArgs, type PresetAspect, type PresetCapabilities, type PresetColumnWidthEntry, type PresetData, type PresetDraft, type PresetFilterOpEntry, type PresetLimitReachedBody, type PresetSnapshot, type PresetSnapshotWire, type PresetSorterEntry, PresetsClient, type PresetsClientConfig, PresetsHttpError, type PresetsListResult, type PresetsSaveAsOptions, type PresetsSaveResult, type QueryOptions, RESERVED_ID_PREFIXES, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, type SelectionMode, type SystemPreset, type SystemPresetInput, type TableStateData, type TableStateMethods, URL_SNAPSHOT_KEY, USER_CONF_PREFIX, type UnsupportedFilter, type UnsupportedFilterReason, type UrlQueryDefaults, type UrlQueryParseOptions, type UrlQueryStateLike, type UrlQueryStateSnapshot, type UrlQuerySync, type UserConfData, appConfId, arraysEqual, blockStartFor, buildTableQuery, cellAsString, clampTopIndex, collectExportRows, columnDefaultCondition, columnFilterConditions, columnFilterType, computeDefaultColumnWidth, conditionLabel, conditionsForType, csvCell, dateShortcuts, debounce, decomposeUniqueryFilter, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterExprFields, filterExprKey, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, formatFilterExpr, fromWireSnapshot, gateOwns, hasSecondValue, isAuthError, isColumnFilterable, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeDisplayColumns, mergeFilters, mergeSorters, normaliseSystemPresetId, normalizeResidualFilters, pageAlignedBlocksFor, parseColumnFilterInput, parseFilterInput, planFetch, reconcileColumnWidthDefaults, reorderColumnNames, residualGateOwns, 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, type AppConfData, AppPrefsClient, type AppPrefsClientConfig, type AppPrefsLoadResult, type AsPresetEntryData, type AsPresetEntryRow, type AsPresetsErrorCode, type AspectGate, type AspectMask, type BuildTableQueryOptions, type ColumnFilterType, type ColumnReorderPosition, type ColumnWidthEntry, type ColumnWidthsMap, type ConfigTab, type CsvOptions, DEFAULT_EXPORT_PAGE_SIZE, DEFAULT_ROW_HEIGHT_PX, DEV, DRAFT_PERSISTED_ASPECTS, type DateShortcut, type DecomposeUniqueryFilterOptions, type DecomposedUniqueryFilter, type DisplayColumnDef, type DraftPersistedAspect, type DroppedFields, ExportAbortError, type ExportPage, type ExportPageFetcher, type ExportScalar, type FetchPlan, type FetchPlanMode, type FieldFilters, type FilterCondition, type FilterConditionType, type FilterableColumn, type KnownFields, MAX_DEFAULT_COLUMN_WIDTH_PX, type MergeResult, NULL_OPS, PRESET_ASPECTS, type PageAlignedBlock, type PlanFetchArgs, type PresetAspect, type PresetCapabilities, type PresetColumnWidthEntry, type PresetData, type PresetDraft, type PresetFilterOpEntry, type PresetLimitReachedBody, type PresetSnapshot, type PresetSnapshotWire, type PresetSorterEntry, PresetsClient, type PresetsClientConfig, PresetsHttpError, type PresetsListResult, type PresetsSaveAsOptions, type PresetsSaveResult, type QueryOptions, RESERVED_ID_PREFIXES, STANDARD_PRESET_ID, SYSTEM_PRESET_PREFIX, type SelectionMode, type SystemPreset, type SystemPresetInput, type TableStateData, type TableStateMethods, URL_SNAPSHOT_KEY, USER_CONF_PREFIX, type UnknownFilter, type UnsupportedFilter, type UnsupportedFilterReason, type UrlQueryDefaults, type UrlQueryParseOptions, type UrlQueryStateLike, type UrlQueryStateSnapshot, type UrlQuerySync, type UserConfData, appConfId, arraysEqual, blockStartFor, buildTableQuery, cellAsString, clampTopIndex, collectExportRows, columnDefaultCondition, columnFilterConditions, columnFilterType, computeDefaultColumnWidth, conditionLabel, conditionsForType, csvCell, dateShortcuts, debounce, decomposeUniqueryFilter, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterExprFields, filterExprKey, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, formatFilterExpr, fromWireSnapshot, gateOwns, hasSecondValue, isAuthError, isColumnFilterable, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeDisplayColumns, mergeFilters, mergeSorters, normaliseSystemPresetId, normalizeResidualFilters, pageAlignedBlocksFor, parseColumnFilterInput, parseFilterInput, planFetch, prunePresetSnapshot, pruneResidualFilters, reconcileColumnWidthDefaults, reorderColumnNames, residualGateOwns, resolveAspectGate, resolveExportValue, resolveSystemPresets, restoreDroppedEntries, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortRowsLocally, sortersEqual, stableStringify, stateToUrlQueryString, toCsv, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryConsumesKey, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb, withStableOrder };

package/dist/index.mjs

@@ -527,6 +527,7 @@ function fieldsOf(expr, out) {
 	else if (!out.includes(key)) out.push(key);
 	return out;
 }
+/** @internal Module-shared with the URL parser; not a package export. */
 function unsupported(reason, expr) {
 	const fields = fieldsOf(expr, []);
 	return {
@@ -752,10 +753,10 @@ function warnUnsupported(issue) {
 /**
 * Split a Uniquery `FilterExpr` into what the table's field-filter model
 * holds exactly (`filters`), what it cannot hold but carries as residual
-* conditions (`residual`, with `carry`), and what it leaves out
-* (`unsupported`). Nothing is approximated: `filters AND residual` selects
-* `expr` minus the `unsupported` pieces and pieces on fields outside
-* `knownFields`.
+* conditions (`residual`, with `carry`), what it leaves out (`unsupported`)
+* and what names a field outside `knownFields` (`unknown`). Nothing is
+* approximated: `filters AND residual` selects `expr` minus the
+* `unsupported` and `unknown` pieces.
 *
 * Never throws, never warns — the caller decides how to report.
 *
@@ -766,7 +767,8 @@ function decomposeUniqueryFilter(expr, opts = {}) {
 	const result = {
 		filters,
 		residual: [],
-		unsupported: []
+		unsupported: [],
+		unknown: []
 	};
 	if (!expr) return result;
 	const knownFields = opts.knownFields;
@@ -787,8 +789,12 @@ function decomposeUniqueryFilter(expr, opts = {}) {
 		}];
 	}
 	const positives = /* @__PURE__ */ new Map();
+	const unknown = /* @__PURE__ */ new Map();
 	for (const term of out.terms) {
-		if (!isKnown(term.field)) continue;
+		if (!isKnown(term.field)) {
+			unknown.set(term.expr, [term.field]);
+			continue;
+		}
 		const list = filters[term.field] ??= [];
 		if (isNegative(term)) {
 			list.push(...term.conds);
@@ -818,11 +824,16 @@ function decomposeUniqueryFilter(expr, opts = {}) {
 	}
 	for (const issue of out.issues) {
 		const fields = issue.fields;
-		if (fields.length > 0 && !fields.some(isKnown)) continue;
-		if (opts.carry && fields.length > 0 && fields.every(isKnown)) carried.push(issue.expr);
+		const outside = fields.filter((f) => !isKnown(f));
+		if (outside.length > 0) unknown.set(issue.expr, outside);
+		else if (opts.carry && fields.length > 0) carried.push(issue.expr);
 		else result.unsupported.push(issue);
 	}
 	result.residual = normalizeResidualFilters(carried);
+	result.unknown = [...unknown].map(([expr, fields]) => ({
+		expr,
+		fields
+	}));
 	return result;
 }
 /**
@@ -873,9 +884,10 @@ function normalizeResidualFilters(exprs) {
 *   to a dev-mode `console.warn` when no handler is given. To keep those
 *   pieces instead, use {@link decomposeUniqueryFilter} with `carry`.
 *
-* 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.
+* Pieces that name a field outside `knownFields` (when provided) are ignored
+* silently: they are not this table's (a host page flag, a hidden or stale
+* column). Since 0.1.141 that includes a piece mixing known and unknown
+* fields — {@link decomposeUniqueryFilter} lists them as `unknown`.
 *
 * Returns `{}` for an empty/missing expression. Never throws.
 */
@@ -1145,6 +1157,137 @@ function resolveSystemPresets(input) {
 	}, ...named];
 }
 //#endregion
+//#region src/presets/prune-preset-snapshot.ts
+/** `[kept, dropped]` in one pass. */
+function partition(list, keep) {
+	const kept = [];
+	const dropped = [];
+	for (const x of list) (keep(x) ? kept : dropped).push(x);
+	return [kept, dropped];
+}
+/** The columns aspect, an empty width map spelled by omission — the way capture writes it. */
+function columnsAspect(columnNames, columnWidths) {
+	return columnWidths && Object.keys(columnWidths).length > 0 ? {
+		columnNames,
+		columnWidths
+	} : { columnNames };
+}
+/**
+* Remove every entry of `snapshot` that names a field outside `known`, per
+* aspect:
+*
+* - `columns.columnNames` — unknown names go, the rest keep their order. When
+*   none survives, it falls back to every column, never an empty grid.
+* - `columns.columnWidths` — unknown keys go.
+* - `filters` (displayed inputs) and `filterOps` — entries on a field outside
+*   `known.server` go. A field's conditions are one AND-ed conjunct, so
+*   dropping one only broadens the result.
+* - `sorters` — unknown entries go, the rest keep their priority.
+* - `itemsPerPage` — untouched.
+*
+* `dropped` is `null` when nothing user-visible went (a width-only drop is
+* hygiene). The input is never mutated.
+*
+* @since 0.1.141
+*/
+function prunePresetSnapshot(snapshot, known) {
+	const isColumn = (p) => known.columns.has(p);
+	const isServer = (p) => known.server.has(p);
+	const out = { ...snapshot };
+	const dropped = {
+		fields: [],
+		columns: [],
+		filterFields: [],
+		filters: {},
+		residual: [],
+		sorters: []
+	};
+	if (snapshot.columns) {
+		const [names, gone] = partition(snapshot.columns.columnNames, isColumn);
+		const [widths] = partition(Object.entries(snapshot.columns.columnWidths ?? {}), ([p]) => isColumn(p));
+		dropped.columns = gone;
+		out.columns = columnsAspect(names.length > 0 || gone.length === 0 ? names : [...known.columns], Object.fromEntries(widths));
+	}
+	if (snapshot.filters) [out.filters, dropped.filterFields] = partition(snapshot.filters, isServer);
+	if (snapshot.filterOps) {
+		const [kept, gone] = partition(Object.entries(snapshot.filterOps), ([p]) => isServer(p));
+		out.filterOps = Object.fromEntries(kept);
+		dropped.filters = Object.fromEntries(gone);
+	}
+	if (snapshot.sorters) [out.sorters, dropped.sorters] = partition(snapshot.sorters, (s) => isColumn(s.field));
+	dropped.fields = [...new Set([
+		...dropped.columns,
+		...dropped.filterFields,
+		...Object.keys(dropped.filters),
+		...dropped.sorters.map((s) => s.field)
+	])];
+	return {
+		snapshot: out,
+		dropped: dropped.fields.length > 0 ? dropped : null
+	};
+}
+/**
+* Split residual filter conditions, in one pass, into the ones that name
+* only `known` fields and the ones that do not. A condition naming any
+* unknown field is dropped WHOLE — never pruned inside an `$or` (that would
+* narrow the result) or a `$not` (that would invert it). Each condition is an
+* AND-ed conjunct, so dropping one only broadens the result.
+*
+* `dropped` holds the conditions in `residual` and the unknown paths in
+* `fields`; `null` when every condition is kept.
+*
+* @since 0.1.141
+*/
+function pruneResidualFilters(exprs, known) {
+	const kept = [];
+	const residual = [];
+	const fields = /* @__PURE__ */ new Set();
+	for (const expr of exprs) {
+		const unknown = filterExprFields(expr).filter((p) => !known.has(p));
+		if (unknown.length === 0) {
+			kept.push(expr);
+			continue;
+		}
+		residual.push(expr);
+		for (const p of unknown) fields.add(p);
+	}
+	if (residual.length === 0) return {
+		kept,
+		dropped: null
+	};
+	return {
+		kept,
+		dropped: {
+			fields: [...fields],
+			columns: [],
+			filterFields: [],
+			filters: {},
+			residual,
+			sorters: []
+		}
+	};
+}
+/**
+* Append what a prune dropped back onto a snapshot captured from (pruned)
+* table state, so overwriting a preset with a narrower view does not destroy
+* the parts the saver cannot see. Column names, filter inputs and sorters go
+* after the captured ones; field filters are added back. Only aspects
+* `captured` carries are touched; widths of hidden columns are not kept.
+*
+* @since 0.1.141
+*/
+function restoreDroppedEntries(captured, dropped) {
+	const out = { ...captured };
+	if (captured.columns) out.columns = columnsAspect([...captured.columns.columnNames, ...dropped.columns], captured.columns.columnWidths);
+	if (captured.filters) out.filters = [...captured.filters, ...dropped.filterFields];
+	if (captured.filterOps) out.filterOps = {
+		...captured.filterOps,
+		...dropped.filters
+	};
+	if (captured.sorters) out.sorters = [...captured.sorters, ...dropped.sorters];
+	return out;
+}
+//#endregion
 //#region src/presets/preset-dirty.ts
 /**
 * JSON-stringify with object keys sorted alphabetically at every depth so
@@ -1748,6 +1891,20 @@ const CONSUMED_CONTROLS = new Set([
 	"$skip",
 	URL_SNAPSHOT_KEY
 ]);
+function toSet(paths) {
+	if (!paths) return null;
+	return paths instanceof Set ? paths : new Set(paths);
+}
+/**
+* `field=value` (or `field=null`) — the one filter shape a host page flag
+* shares, so a bare one on an unknown field is not reported as dropped.
+*/
+function isBareEquality(expr) {
+	const keys = Object.keys(expr);
+	if (keys.length !== 1 || keys[0].startsWith("$")) return false;
+	const v = expr[keys[0]];
+	return v === null || typeof v !== "object";
+}
 /**
 * Characters that can only appear in a uniqu filter key, never in a page flag:
 * comparison operators, `^` (OR), `( )` (groups) and `{ }` (`$in` lists).
@@ -1774,9 +1931,10 @@ function urlQueryConsumesKey(key) {
 /**
 * Parse a URL query string back into the table state subset.
 *
-* Robust by design — schema drift and copy-paste errors must not break the
-* recipient's view:
-* - unknown fields (not in `knownFields`) → silently dropped
+* Robust by design — schema drift, fields hidden from the recipient and
+* copy-paste errors must not break the recipient's view:
+* - unknown fields (not in `knownFields`) → dropped, listed in `unknown` /
+*   `unknownSorters` (the parser does not warn — the caller decides)
 * - 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). Unless
@@ -1809,12 +1967,15 @@ function urlQueryStringToState(urlString, opts = {}) {
 	const sortersGate = resolveAspectGate(opts.sync?.sorters);
 	const searchOff = opts.sync?.search === false;
 	const paginationOff = opts.sync?.pagination === false;
-	const knownSet = opts.knownFields ? new Set(opts.knownFields) : null;
+	const knownSet = toSet(opts.knownFields);
+	const localSet = toSet(opts.localFields);
+	const isHidden = (f) => !!knownSet && !knownSet.has(f) && !localSet?.has(f);
 	let filterKnown;
 	if (filtersGate === "all") filterKnown = knownSet ?? void 0;
 	else if (filtersGate !== "none") if (knownSet) {
-		filterKnown = /* @__PURE__ */ new Set();
-		for (const path of filtersGate) if (knownSet.has(path)) filterKnown.add(path);
+		const owned = /* @__PURE__ */ new Set();
+		for (const path of filtersGate) if (knownSet.has(path)) owned.add(path);
+		filterKnown = owned;
 	} else filterKnown = filtersGate;
 	const decomposed = filtersGate === "none" ? null : decomposeUniqueryFilter(parsed.filter, {
 		knownFields: filterKnown,
@@ -1822,20 +1983,19 @@ function urlQueryStringToState(urlString, opts = {}) {
 	});
 	const filters = decomposed?.filters ?? {};
 	const sorters = [];
+	const unknownSorters = [];
 	if (sortersGate !== "none") {
 		const $sort = parsed.controls?.$sort;
 		if ($sort && typeof $sort === "object") for (const field in $sort) {
-			if (knownSet && !knownSet.has(field)) continue;
 			if (!gateOwns(sortersGate, field)) continue;
 			const dir = $sort[field];
-			if (dir === 1) sorters.push({
-				field,
-				direction: "asc"
-			});
-			else if (dir === -1) sorters.push({
+			if (dir !== 1 && dir !== -1) continue;
+			const sorter = {
 				field,
-				direction: "desc"
-			});
+				direction: dir === 1 ? "asc" : "desc"
+			};
+			if (!knownSet || knownSet.has(field)) sorters.push(sorter);
+			else if (isHidden(field)) unknownSorters.push(sorter);
 		}
 	}
 	const $search = parsed.controls?.$search;
@@ -1844,8 +2004,24 @@ function urlQueryStringToState(urlString, opts = {}) {
 		sorters,
 		searchTerm: !searchOff && typeof $search === "string" ? $search : ""
 	};
-	if (decomposed?.unsupported.length) out.unsupported = decomposed.unsupported;
+	const unsupported$1 = decomposed?.unsupported ?? [];
+	const unknown = [];
+	for (const piece of decomposed?.unknown ?? []) {
+		const hidden = piece.fields.filter(isHidden);
+		if (hidden.length > 0) {
+			if (!isBareEquality(piece.expr)) unknown.push({
+				expr: piece.expr,
+				fields: hidden
+			});
+			continue;
+		}
+		const issue = unsupported("cross-field", piece.expr);
+		if (issue.fields.some((f) => filterKnown?.has(f))) unsupported$1.push(issue);
+	}
+	if (unsupported$1.length) out.unsupported = unsupported$1;
 	if (decomposed?.residual.length) out.residual = decomposed.residual;
+	if (unknown.length) out.unknown = unknown;
+	if (unknownSorters.length) out.unknownSorters = unknownSorters;
 	if (opts.sync?.snapshot !== false && parsed.controls && "$snapshot" in parsed.controls) out.snapshot = true;
 	if (!searchOff) {
 		const $relevance = parsed.controls?.$relevance;
@@ -2397,4 +2573,4 @@ function sortRowsLocally(rows, sorters, getValue = (row, field) => row[field]) {
 	});
 }
 //#endregion
-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, decomposeUniqueryFilter, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterExprFields, filterExprKey, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, formatFilterExpr, fromWireSnapshot, gateOwns, hasSecondValue, isAuthError, isColumnFilterable, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeDisplayColumns, mergeFilters, mergeSorters, normaliseSystemPresetId, normalizeResidualFilters, pageAlignedBlocksFor, parseColumnFilterInput, parseFilterInput, planFetch, reconcileColumnWidthDefaults, reorderColumnNames, residualGateOwns, 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, decomposeUniqueryFilter, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterExprFields, filterExprKey, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, formatFilterExpr, fromWireSnapshot, gateOwns, hasSecondValue, isAuthError, isColumnFilterable, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeDisplayColumns, mergeFilters, mergeSorters, normaliseSystemPresetId, normalizeResidualFilters, pageAlignedBlocksFor, parseColumnFilterInput, parseFilterInput, planFetch, prunePresetSnapshot, pruneResidualFilters, reconcileColumnWidthDefaults, reorderColumnNames, residualGateOwns, resolveAspectGate, resolveExportValue, resolveSystemPresets, restoreDroppedEntries, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortRowsLocally, sortersEqual, stableStringify, stateToUrlQueryString, toCsv, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryConsumesKey, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb, withStableOrder };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/ui-table",
-  "version": "0.1.140",
+  "version": "0.1.141",
   "description": "Framework-agnostic filter model, filter-to-Uniquery conversion, and preset serialization for atscript tables",
   "keywords": [
     "atscript",
@@ -42,7 +42,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@atscript/ui": "0.1.140"
+    "@atscript/ui": "0.1.141"
   },
   "devDependencies": {
     "@atscript/db-client": "^0.1.133",