@atscript/vue-table 0.1.139 → 0.1.141

package/dist/{types-CgdpcJdd.d.mts → types-Ev-A5h_D.d.mts}

@@ -1,8 +1,8 @@
 import { ColumnDef, PaginationControl, SortControl, TableDef } from "@atscript/ui";
 import { Component, ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
-import { AsPresetEntryRow, AspectMask, ColumnWidthsMap, ConfigTab, FieldFilters, PresetAspect, PresetCapabilities, PresetSnapshot, SelectionMode, SystemPreset, SystemPresetInput, TableStateMethods } from "@atscript/ui-table";
+import { AsPresetEntryRow, AspectMask, ColumnWidthsMap, ConfigTab, DroppedFields, FieldFilters, PresetAspect, PresetCapabilities, PresetSnapshot, SelectionMode, SystemPreset, SystemPresetInput, TableStateMethods } from "@atscript/ui-table";
 import { ClientError, PageResult, TDbActionInfo, TDbActionProcessor, TDbDeleteResult } from "@atscript/db-client";
-import { Uniquery } from "@uniqu/core";
+import { FilterExpr, Uniquery } from "@uniqu/core";
 
 //#region src/composables/state/intent-scope.d.ts
 interface ActionBuckets {
@@ -369,6 +369,11 @@ interface TAsTableControls {
   filterDialog?: Component;
   filterField?: Component;
   filterValueHelp?: Component;
+  /**
+   * One residual filter condition's chip in `<AsFilters>` — receives
+   * `expr` and `index`. Default `AsResidualFilter`. Since 0.1.140.
+   */
+  residualFilter?: Component;
   configDialog?: Component;
   fieldsSelector?: Component;
   sortersConfig?: Component;
@@ -408,6 +413,28 @@ type TAsCellTypeComponents = {
   ref: Component; /** Synthesised row-actions pseudo-column (`:rowActionsColumn` opt-in). */
   __actions?: Component;
 } & Record<string, Component>;
+/**
+ * What the table left out because it names a field outside the columns this
+ * caller can use — a field hidden from their role, or gone from the schema.
+ * Sent to `onFieldsDropped` / `@fields-dropped` once per apply, only when
+ * something was dropped. `fields` lists the unavailable paths; the other
+ * lists hold the dropped entries themselves.
+ *
+ * - `"preset"` — a preset applied (picker switch, reset, raw snapshot, and
+ *   the bootstrap default with the local draft laid over it).
+ * - `"url"` — a restored URL (deep link, shared link, Back/Forward). Its
+ *   dropped filter pieces are listed in `residual`, as whole expressions.
+ *
+ * State written straight to the model is not reported: the query leaves such
+ * fields out (a dev-mode warning names them once).
+ *
+ * @since 0.1.141
+ */
+interface DroppedFieldsReport extends DroppedFields {
+  source: "preset" | "url";
+  /** The preset whose apply dropped the entries (`"preset"`). */
+  presetId?: string;
+}
 /**
  * How `applyUrlQuery` treats filters and sorters the URL does not mention.
  * @since 0.1.137
@@ -442,6 +469,15 @@ interface ReactiveTableState extends TableStateMethods {
   columnWidths: Ref<ColumnWidthsMap>;
   filterFields: ShallowRef<string[]>;
   filters: ShallowRef<FieldFilters>;
+  /**
+   * Residual filter conditions — AND-ed Uniquery conjuncts the field-filter
+   * model cannot hold (a cross-field `$or`, a second range on one field, …).
+   * AND'd after `filters` into every query, carried through the URL, shown
+   * as "custom filter" chips by `<AsFilters>`. Replace wholesale (or use
+   * `setResidualFilters` / `removeResidualFilter`); `resetFilters()`
+   * clears them. Not saved in presets. Since 0.1.140.
+   */
+  residualFilters: ShallowRef<FilterExpr[]>;
   sorters: ShallowRef<SortControl[]>;
   results: ShallowRef<Record<string, unknown>[]>;
   /** Absolute index where `results[0]` sits. */
@@ -686,6 +722,11 @@ interface ReactiveTableState extends TableStateMethods {
    *   the baseline.
    *
    * `opts.mode` overrides the marker either way. Since 0.1.139.
+   *
+   * Filter pieces the field-filter model cannot hold are restored as
+   * `residualFilters` (since 0.1.140). A URL owns every path it mentions —
+   * in a field filter or inside such a condition — so on merge the
+   * baseline's filters and residual conditions on those paths give way.
    */
   applyUrlQuery: (urlString: string, opts?: ApplyUrlQueryOptions) => void;
   /**
@@ -784,8 +825,19 @@ interface PresetSurface {
   available: ComputedRef<boolean>;
   /** Currently active preset id (system `'sys:*'` or stored). null = no active. */
   activeId: Ref<string | null>;
-  /** Active preset's snapshot (system presets are aspect-expanded). */
+  /**
+   * Active preset's snapshot (system presets are aspect-expanded), pruned of
+   * fields this caller cannot use — what applying it wrote. The stored row
+   * is never rewritten.
+   */
   activeSnapshot: ComputedRef<PresetSnapshot>;
+  /**
+   * What the active preset names that this caller cannot use — left out
+   * when it was applied — or `null`. Derived from the stored preset, so it
+   * follows the active id. `<AsPresetPicker>` shows a quiet note while set.
+   * Since 0.1.141.
+   */
+  droppedFields: ComputedRef<DroppedFieldsReport | null>;
   /** True when the current snapshot ≠ active preset's claimed aspects. */
   isDirty: ComputedRef<boolean>;
   /** True iff the active preset is owned by the current user (gates Save). */
@@ -811,7 +863,11 @@ interface PresetSurface {
    * if it still references a known preset, else `STANDARD_PRESET_ID`.
    */
   resolveDefaultId: () => string;
-  /** Re-capture the active preset's existing aspect mask. Never widens. */
+  /**
+   * Re-capture the active preset's existing aspect mask. Never widens.
+   * Entries on fields this caller cannot use (`droppedFields`) are appended
+   * back after the visible ones, so they survive the overwrite.
+   */
   saveActive: () => Promise<void>;
   /** Create a new preset and switch the active id to it. */
   saveAs: (label: string, opts?: {
@@ -849,4 +905,4 @@ interface PresetSurface {
   lastError: Ref<Error | null>;
 }
 //#endregion
-export { TAsTableControls as C, extractIdentifier as D, TableNavBridge as E, TAsCellTypeComponents as S, TableActionsState as T, RowClassHook as _, ConfirmOptions as a, RowSelectableHook as b, LocalRowAction as c, PresetConfig as d, QueryErrorKind as f, RowAttrsHook as g, RowActionsConfig as h, ConfigTab as i, MainActionRequest as l, RowActionsColumnPlacement as m, ApplyUrlQueryOptions as n, EnterAction as o, ReactiveTableState as p, ColumnMenuConfig as r, InvokeOpts as s, ActionResult as t, NavKeyOptions as u, RowDeleteOpt as v, TVueTableActionInfo as w, RowSelectableVerdict as x, RowHookContext as y };
+export { TAsCellTypeComponents as C, TableNavBridge as D, TableActionsState as E, extractIdentifier as O, RowSelectableVerdict as S, TVueTableActionInfo as T, RowAttrsHook as _, ConfirmOptions as a, RowHookContext as b, InvokeOpts as c, NavKeyOptions as d, PresetConfig as f, RowActionsConfig as g, RowActionsColumnPlacement as h, ConfigTab as i, LocalRowAction as l, ReactiveTableState as m, ApplyUrlQueryOptions as n, DroppedFieldsReport as o, QueryErrorKind as p, ColumnMenuConfig as r, EnterAction as s, ActionResult as t, MainActionRequest as u, RowClassHook as v, TAsTableControls as w, RowSelectableHook as x, RowDeleteOpt as y };

package/dist/{use-table-DUwUfjSZ.mjs → use-table-BG3IZyCO.mjs}

@@ -1,4 +1,4 @@
-import { c as DEFAULT_AVAILABLE_ASPECTS, n as createTableState, r as provideTableContext } from "./use-table-state-BEwXQayO.mjs";
+import { l as DEFAULT_AVAILABLE_ASPECTS, n as createTableState, r as provideTableContext } from "./use-table-state-BgLIOO31.mjs";
 import { n as useTableSelection } from "./use-table-selection-ULbKT2xW.mjs";
 import { createTableDef, getMetaEntry, resetMetaCache } from "@atscript/ui";
 import { computed, inject, isRef, ref, shallowRef, toValue, watch } from "vue";
@@ -435,7 +435,8 @@ function useTable(url, opts) {
 			urlQueryReady: opts?.urlQueryReady,
 			onUrlQueryChange: opts?.onUrlQueryChange,
 			urlQuerySync: opts?.urlQuerySync,
-			onUnsupportedFilter: opts?.onUnsupportedFilter
+			onUnsupportedFilter: opts?.onUnsupportedFilter,
+			onFieldsDropped: opts?.onFieldsDropped
 		},
 		window: {
 			blockSize: opts?.blockSize,

package/dist/{use-table-column-handlers-Do0Z-R9D.cjs → use-table-column-handlers-CWHRcQbE.cjs}

@@ -1,4 +1,4 @@
-const require_use_table_state = require("./use-table-state-Cnxv0w_E.cjs");
+const require_use_table_state = require("./use-table-state-CgXY-ruN.cjs");
 let vue = require("vue");
 let _atscript_ui_table = require("@atscript/ui-table");
 //#region src/composables/use-row-actions-column.ts

package/dist/{use-table-column-handlers-eKHCfUm_.mjs → use-table-column-handlers-CaT7dYnI.mjs}

@@ -1,4 +1,4 @@
-import { D as ROW_ACTIONS_PATH, O as ROW_ACTIONS_TYPE } from "./use-table-state-BEwXQayO.mjs";
+import { O as ROW_ACTIONS_PATH, k as ROW_ACTIONS_TYPE } from "./use-table-state-BgLIOO31.mjs";
 import { computed, watch } from "vue";
 import { reorderColumnNames } from "@atscript/ui-table";
 //#region src/composables/use-row-actions-column.ts

package/dist/{use-table-component-wfU13P3L.mjs → use-table-component-OTdgA202.mjs}

@@ -1,4 +1,4 @@
-import { o as useTableContextOptional } from "./use-table-state-BEwXQayO.mjs";
+import { o as useTableContextOptional } from "./use-table-state-BgLIOO31.mjs";
 //#region src/composables/use-table-component.ts
 /**
 * Resolve a single skin-slot component from the injected `controls` map,

package/dist/{use-table-component-DbQDINoa.cjs → use-table-component-Tc_ZvZua.cjs}

@@ -1,4 +1,4 @@
-const require_use_table_state = require("./use-table-state-Cnxv0w_E.cjs");
+const require_use_table_state = require("./use-table-state-CgXY-ruN.cjs");
 //#region src/composables/use-table-component.ts
 /**
 * Resolve a single skin-slot component from the injected `controls` map,

package/dist/{use-table-nav-bridge-DRrvQxXq.mjs → use-table-nav-bridge-BNjwR3qy.mjs}

@@ -1,4 +1,4 @@
-import { o as useTableContextOptional } from "./use-table-state-BEwXQayO.mjs";
+import { o as useTableContextOptional } from "./use-table-state-BgLIOO31.mjs";
 //#region src/composables/use-table-nav-bridge.ts
 function isPassthroughKey(event) {
 	const key = event.key;

package/dist/{use-table-nav-bridge-BLLVGR1r.cjs → use-table-nav-bridge-ByQo00IH.cjs}

@@ -1,4 +1,4 @@
-const require_use_table_state = require("./use-table-state-Cnxv0w_E.cjs");
+const require_use_table_state = require("./use-table-state-CgXY-ruN.cjs");
 //#region src/composables/use-table-nav-bridge.ts
 function isPassthroughKey(event) {
 	const key = event.key;

package/dist/{use-table-c4ku22Mx.cjs → use-table-rc6_sYU6.cjs}

@@ -1,4 +1,4 @@
-const require_use_table_state = require("./use-table-state-Cnxv0w_E.cjs");
+const require_use_table_state = require("./use-table-state-CgXY-ruN.cjs");
 const require_use_table_selection = require("./use-table-selection-DtCV3rhu.cjs");
 let _atscript_ui = require("@atscript/ui");
 let vue = require("vue");
@@ -435,7 +435,8 @@ function useTable(url, opts) {
 			urlQueryReady: opts?.urlQueryReady,
 			onUrlQueryChange: opts?.onUrlQueryChange,
 			urlQuerySync: opts?.urlQuerySync,
-			onUnsupportedFilter: opts?.onUnsupportedFilter
+			onUnsupportedFilter: opts?.onUnsupportedFilter,
+			onFieldsDropped: opts?.onFieldsDropped
 		},
 		window: {
 			blockSize: opts?.blockSize,

package/dist/{use-table-state-BEwXQayO.mjs → use-table-state-BgLIOO31.mjs}

@@ -1,7 +1,7 @@
 import { t as getCellValue } from "./get-cell-value-Cb3X8nUn.mjs";
 import { navigateHrefFor } from "@atscript/ui";
 import { computed, inject, nextTick, onBeforeUnmount, onScopeDispose, provide, ref, shallowRef, toValue, watch } from "vue";
-import { DEV, STANDARD_PRESET_ID, blockStartFor, buildTableQuery, cellAsString, debounce, derivePresetAspects, fromWireSnapshot, gateOwns, isDirtyAgainst, isFilled, isSystemPresetId, mergeDisplayColumns, mergeSorters, pageAlignedBlocksFor, planFetch, reconcileColumnWidthDefaults, resolveAspectGate, resolveSystemPresets, rowsToPks, sameColumnSet, sortRowsLocally, sortersEqual, stateToUrlQueryString, togglePk, urlQueryStringToState, walkBackwardAbsorb, walkForwardAbsorb } from "@atscript/ui-table";
+import { DEV, STANDARD_PRESET_ID, arraysEqual, blockStartFor, buildTableQuery, cellAsString, debounce, derivePresetAspects, filterExprFields, filterExprKey, fromWireSnapshot, gateOwns, isDirtyAgainst, isFilled, isSystemPresetId, mergeDisplayColumns, mergeSorters, normalizeResidualFilters, pageAlignedBlocksFor, planFetch, prunePresetSnapshot, pruneResidualFilters, reconcileColumnWidthDefaults, residualGateOwns, resolveAspectGate, resolveSystemPresets, restoreDroppedEntries, rowsToPks, sameColumnSet, sortRowsLocally, sortersEqual, stateToUrlQueryString, togglePk, urlQueryStringToState, walkBackwardAbsorb, walkForwardAbsorb } from "@atscript/ui-table";
 import { formatIdentifier } from "@atscript/db-client";
 //#region src/types.ts
 /** UI-side sentinel for the synthesised row-delete processor. */
@@ -1023,6 +1023,7 @@ function createPresetState(opts) {
 			apply(o, value, isSystem) {
 				if (!value && !isSystem) return;
 				o.filters.value = value ? { ...value } : {};
+				if (o.residualFilters?.value.length) o.residualFilters.value = [];
 			},
 			expandDefault: () => ({})
 		},
@@ -1100,8 +1101,25 @@ function createPresetState(opts) {
 			nextActiveId: id
 		};
 	}
+	/**
+	* The one write-side prune: drop what names a field this table cannot use,
+	* and report it. A no-op before the table definition loads — bootstrap
+	* waits for it, and the query gate covers any other early writer.
+	*/
+	function pruneForApply(snapshot, presetId) {
+		const known = opts.knownFields?.value;
+		if (!known) return snapshot;
+		const { snapshot: pruned, dropped } = prunePresetSnapshot(snapshot, known);
+		if (dropped) opts.onFieldsDropped?.({
+			...dropped,
+			source: "preset",
+			presetId: presetId ?? void 0
+		});
+		return pruned;
+	}
 	function apply(idOrSnapshot) {
-		const { snapshot, nextActiveId } = resolveSnapshot(idOrSnapshot);
+		const { snapshot: resolved, nextActiveId } = resolveSnapshot(idOrSnapshot);
+		const snapshot = pruneForApply(resolved, nextActiveId);
 		const isSystem = typeof idOrSnapshot === "string" && nextActiveId !== null && isSystemPresetId(nextActiveId);
 		for (const aspect of ownedAspects(nextActiveId)) {
 			const value = snapshot[aspect];
@@ -1142,7 +1160,8 @@ function createPresetState(opts) {
 		}
 		return out;
 	}
-	const activeSnapshot = computed(() => {
+	/** The active preset's snapshot as stored — the base `saveActive` merges back into. */
+	const storedActiveSnapshot = computed(() => {
 		const id = activeId.value;
 		if (!id) return {};
 		if (isSystemPresetId(id)) return expandSystemSnapshot(systemPresetsById.value.get(id)?.content ?? {}, id);
@@ -1151,7 +1170,25 @@ function createPresetState(opts) {
 		const wire = row.data?.content;
 		return wire ? fromWireSnapshot(wire) : {};
 	});
-	const isDirty = computed(() => isDirtyAgainst(activeSnapshot.value, captureSnapshot()));
+	const prunedActive = computed(() => {
+		const known = opts.knownFields?.value;
+		const stored = storedActiveSnapshot.value;
+		return known ? prunePresetSnapshot(stored, known) : {
+			snapshot: stored,
+			dropped: null
+		};
+	});
+	const activeSnapshot = computed(() => prunedActive.value.snapshot);
+	const droppedFields = computed(() => {
+		const dropped = prunedActive.value.dropped;
+		const presetId = activeId.value;
+		return dropped && presetId ? {
+			...dropped,
+			source: "preset",
+			presetId
+		} : null;
+	});
+	const isDirty = computed(() => isDirtyAgainst(activeSnapshot.value, captureSnapshot()) || activeSnapshot.value.filterOps !== void 0 && !!opts.residualFilters?.value.length);
 	function requirePresets() {
 		if (!opts.presetsHandle) throw new Error("[vue-table] presets feature not configured (preset.url missing)");
 		return opts.presetsHandle;
@@ -1162,10 +1199,12 @@ function createPresetState(opts) {
 			const id = activeId.value;
 			if (!id) throw new Error("[vue-table] saveActive: no active preset");
 			if (isSystemPresetId(id)) throw new Error("[vue-table] saveActive: system presets cannot be overwritten");
-			const existing = activeSnapshot.value;
+			const existing = storedActiveSnapshot.value;
 			const mask = {};
 			for (const aspect of availableAspects) if (existing[aspect] !== void 0) mask[aspect] = true;
-			await handle.savePreset(captureSnapshot(mask));
+			const captured = captureSnapshot(mask);
+			const dropped = prunedActive.value.dropped;
+			await handle.savePreset(dropped ? restoreDroppedEntries(captured, dropped) : captured);
 			clearLocalDraft();
 		});
 	}
@@ -1224,20 +1263,25 @@ function createPresetState(opts) {
 	function bootstrap() {
 		if (!opts.presetsHandle) return;
 		const handle = opts.presetsHandle;
-		const stop = watch(() => handle.loading.value, (loading) => {
-			if (loading) return;
-			stop();
+		const knownReady = () => !opts.knownFields || opts.knownFields.value !== null;
+		let done = false;
+		let stop;
+		stop = watch(() => !handle.loading.value && knownReady(), (ready) => {
+			if (!ready || done) return;
+			done = true;
+			stop?.();
 			const id = resolveDefaultId();
 			const { snapshot, nextActiveId } = resolveSnapshot(id);
 			const base = isSystemPresetId(id) ? expandSystemSnapshot(snapshot, id) : snapshot;
 			const draftEnabled = !!(opts.draftHandle && opts.persistDrafts);
-			apply(draftEnabled ? opts.draftHandle.hydrate(base) : base);
+			apply(pruneForApply(draftEnabled ? opts.draftHandle.hydrate(base) : base, nextActiveId));
 			activeId.value = nextActiveId;
 			if (draftEnabled) opts.draftHandle.watchAndPersist(() => captureSnapshot(), () => activeSnapshot.value);
 			nextTick(() => {
 				gate.value = true;
 			});
 		}, { immediate: true });
+		if (done) stop();
 	}
 	return {
 		slice: {
@@ -1253,6 +1297,7 @@ function createPresetState(opts) {
 			available,
 			activeId,
 			activeSnapshot,
+			droppedFields,
 			isDirty,
 			canSaveActive,
 			currentUser,
@@ -1594,6 +1639,10 @@ const cloneSorter = (s) => ({
 	field: s.field,
 	direction: s.direction
 });
+/** Same residual conditions, in the same (canonical) order. */
+function sameResidualFilters(a, b) {
+	return arraysEqual(a.map(filterExprKey), b.map(filterExprKey));
+}
 /**
 * The report for a restored URL's filter piece when nobody handles it
 * (`onUnsupportedFilter` / `@unsupported-filter`): a dev-mode warning.
@@ -1602,6 +1651,15 @@ function warnUnsupportedFilter(issue) {
 	if (!DEV) return;
 	console.warn(`[vue-table] URL filter left out (${issue.reason}): ${JSON.stringify(issue.expr)}. Field filters cannot express it, so the table shows more rows than the URL described.`);
 }
+/**
+* The report for fields the table left out when nobody handles it
+* (`onFieldsDropped` / `@fields-dropped`): a dev-mode warning.
+*/
+function warnFieldsDropped(report) {
+	if (!DEV) return;
+	const from = report.presetId ? `${report.source} "${report.presetId}"` : report.source;
+	console.warn(`[vue-table] Left out fields this table cannot use (${from}): ${report.fields.join(", ")}.`);
+}
 function createTableState(opts) {
 	const client = opts.client;
 	const modelOpts = opts.model;
@@ -1638,6 +1696,7 @@ function createTableState(opts) {
 	*/
 	const rowActionsPolicy = computed(() => compileRowActionsConfig(rowActions.value));
 	const filters = shallowRef({});
+	const residualFilters = shallowRef([]);
 	const results = shallowRef([]);
 	const resultsStart = ref(0);
 	const querying = ref(false);
@@ -1675,11 +1734,34 @@ function createTableState(opts) {
 	const configDialogOpen = ref(false);
 	const configTab = ref("columns");
 	const filterDialogColumn = ref(null);
+	/**
+	* The paths the table can use, from its column list: every column, and the
+	* server-backed ones. `null` until the table definition loads. Presets,
+	* drafts, URLs and the query itself are all pruned against it.
+	*/
+	const knownFields = computed(() => {
+		const all = allColumns.value;
+		if (all.length === 0) return null;
+		const columns = /* @__PURE__ */ new Set();
+		const server = /* @__PURE__ */ new Set();
+		for (const c of all) {
+			columns.add(c.path);
+			if (!c.local) server.add(c.path);
+		}
+		return {
+			columns,
+			server
+		};
+	});
+	function reportFieldsDropped(report) {
+		(queryOpts?.onFieldsDropped ?? warnFieldsDropped)(report);
+	}
 	const { slice: presetSlice, internals: presetInternals } = createPresetState({
 		columnNames,
 		columnWidths,
 		filterFields,
 		filters,
+		residualFilters,
 		sorters,
 		pagination,
 		allColumns,
@@ -1688,7 +1770,9 @@ function createTableState(opts) {
 		availableAspects: opts.preset?.availableAspects,
 		systemAspects: opts.preset?.systemAspects,
 		persistDrafts: opts.preset?.persistDrafts,
-		fallbackSystemPresets: opts.preset?.fallbackSystemPresets
+		fallbackSystemPresets: opts.preset?.fallbackSystemPresets,
+		knownFields,
+		onFieldsDropped: reportFieldsDropped
 	});
 	presetInternals.bootstrap();
 	const promptSlot = createRequestSlot(false);
@@ -1730,7 +1814,10 @@ function createTableState(opts) {
 	*/
 	const localColumnPaths = computed(() => {
 		const out = /* @__PURE__ */ new Set();
-		for (const c of allColumns.value) if (c.local) out.add(c.path);
+		const known = knownFields.value;
+		if (known) {
+			for (const p of known.columns) if (!known.server.has(p)) out.add(p);
+		}
 		return out;
 	});
 	/**
@@ -1763,21 +1850,67 @@ function createTableState(opts) {
 		if (splitSorters.value.local.length === 0 || sortersIgnored()) return rows;
 		return sortRowsLocally(rows, queryOpts?.forceSorters?.length ? mergeSorters(queryOpts.forceSorters, sorters.value) : sorters.value, sortValueOf);
 	}
+	/**
+	* The query's view of the model, gated to the fields this caller can use.
+	* This is the guarantee that no table state sends a field the server does
+	* not expose: presets and URLs are pruned on apply, but `setFieldFilter`,
+	* `addFilterField`, `v-model` writes, `setResidualFilters` and the like
+	* write straight to the model. `$select` is gated by the column list
+	* (`knownFields.columns`, then client-owned columns are stripped); filters
+	* and residual conditions by the server-backed columns. `forceFilters` /
+	* `forceSorters` are app-authored and never gated. Memoized: pages,
+	* window blocks and exports reuse it.
+	*/
+	const queryModel = computed(() => {
+		const model = {
+			columnNames: columnNames.value,
+			filters: filters.value,
+			sorters: splitSorters.value.server,
+			residual: residualFilters.value,
+			stripped: []
+		};
+		const known = knownFields.value;
+		if (!known) return model;
+		const { snapshot, dropped } = prunePresetSnapshot({
+			columns: { columnNames: model.columnNames },
+			filterOps: model.filters,
+			sorters: model.sorters
+		}, known);
+		const residual = pruneResidualFilters(model.residual, known.server);
+		return {
+			columnNames: model.columnNames,
+			filters: snapshot.filterOps,
+			sorters: snapshot.sorters,
+			residual: residual.kept,
+			stripped: [...new Set([...dropped?.fields ?? [], ...residual.dropped?.fields ?? []])]
+		};
+	});
+	/** Stripped path sets already warned about — one dev warning per set. */
+	const warnedStripped = /* @__PURE__ */ new Set();
 	function buildCurrentQuery(buildOpts) {
-		const available = tableDef.value?.fetchableFields ?? new Set(allColumns.value.map((c) => c.path));
+		const available = tableDef.value?.fetchableFields ?? knownFields.value?.columns ?? /* @__PURE__ */ new Set();
 		const extra = /* @__PURE__ */ new Set();
 		for (const c of columns.value) for (const p of c.selectWith ?? []) if (available.has(p)) extra.add(p);
 		if (queryOpts?.alwaysSelected) {
 			for (const p of queryOpts.alwaysSelected) if (available.has(p)) extra.add(p);
 		}
+		const model = queryModel.value;
+		if (DEV && model.stripped.length > 0) {
+			const key = model.stripped.join(",");
+			if (!warnedStripped.has(key)) {
+				warnedStripped.add(key);
+				console.warn(`[vue-table] Query leaves out fields this table cannot use: ${model.stripped.join(", ")}.`);
+			}
+		}
+		const known = knownFields.value;
 		const localPaths = localColumnPaths.value;
-		const requested = buildOpts?.columnPaths ?? columnNames.value;
 		return buildTableQuery({
-			visibleColumnPaths: localPaths.size ? requested.filter((p) => !localPaths.has(p)) : requested,
+			visibleColumnPaths: (buildOpts?.columnPaths ?? model.columnNames).filter((p) => !localPaths.has(p) && (!known || known.columns.has(p))),
 			extraSelect: extra.size ? [...extra] : void 0,
-			sorters: splitSorters.value.server,
+			sorters: model.sorters,
 			forceSorters: queryOpts?.forceSorters,
-			filters: filters.value,
+			filters: model.filters,
+			residualFilters: model.residual,
 			forceFilters: queryOpts?.forceFilters,
 			search: searchTerm.value || void 0,
 			ignoreSorters: sortersIgnored(),
@@ -1964,6 +2097,10 @@ function createTableState(opts) {
 			}
 		};
 	}
+	function setResidualFilters(exprs) {
+		const next = normalizeResidualFilters(exprs);
+		if (!sameResidualFilters(next, residualFilters.value)) residualFilters.value = next;
+	}
 	const state = {
 		tableDef,
 		loadingMetadata,
@@ -1973,6 +2110,7 @@ function createTableState(opts) {
 		columnWidths,
 		filterFields,
 		filters,
+		residualFilters,
 		sorters,
 		results,
 		resultsStart,
@@ -2047,8 +2185,14 @@ function createTableState(opts) {
 		loadingAt,
 		errorAt,
 		resetFilters() {
-			if (Object.keys(filters.value).length === 0) return;
-			filters.value = {};
+			if (Object.keys(filters.value).length > 0) filters.value = {};
+			if (residualFilters.value.length > 0) residualFilters.value = [];
+		},
+		setResidualFilters,
+		removeResidualFilter(index) {
+			const list = residualFilters.value;
+			if (index < 0 || index >= list.length) return;
+			residualFilters.value = list.filter((_, i) => i !== index);
 		},
 		showConfigDialog(tab) {
 			configTab.value = tab ?? "columns";
@@ -2099,6 +2243,7 @@ function createTableState(opts) {
 	function serializeStateForUrl() {
 		return stateToUrlQueryString({
 			filters: filters.value,
+			residualFilters: residualFilters.value,
 			sorters: sorters.value,
 			page: pagination.value.page,
 			itemsPerPage: pagination.value.itemsPerPage,
@@ -2129,6 +2274,8 @@ function createTableState(opts) {
 	}
 	const filtersGate = resolveAspectGate(urlQuerySync?.filters);
 	const sortersGate = resolveAspectGate(urlQuerySync?.sorters);
+	const residualSync = urlQuerySync?.residual !== false;
+	const urlOwnsResidual = (expr) => residualSync && residualGateOwns(filtersGate, expr);
 	let urlBaseline = null;
 	function captureUrlBaseline() {
 		if (urlBaseline) return;
@@ -2139,6 +2286,7 @@ function createTableState(opts) {
 		}
 		urlBaseline = {
 			filters: owned,
+			residual: residualFilters.value.filter(urlOwnsResidual),
 			sorters: sorters.value.filter((s) => gateOwns(sortersGate, s.field)).map(cloneSorter)
 		};
 	}
@@ -2156,12 +2304,30 @@ function createTableState(opts) {
 	function applyUrlQuery(urlString, opts) {
 		captureUrlBaseline();
 		if (urlsEquivalent(urlString, lastEmittedUrl)) return;
-		const cols = allColumns.value;
+		const known = knownFields.value;
 		const parsed = urlQueryStringToState(urlString, {
-			knownFields: cols.length > 0 ? cols.map((c) => c.path) : void 0,
+			knownFields: known?.server,
+			localFields: known ? localColumnPaths.value : void 0,
 			sync: urlQuerySync
 		});
 		for (const issue of parsed.unsupported ?? []) (queryOpts?.onUnsupportedFilter ?? warnUnsupportedFilter)(issue);
+		if (parsed.unknown || parsed.unknownSorters) {
+			const residual = parsed.unknown?.map((u) => u.expr) ?? [];
+			const sorters = parsed.unknownSorters ?? [];
+			const fields = new Set(parsed.unknown?.flatMap((u) => u.fields));
+			for (const s of sorters) fields.add(s.field);
+			reportFieldsDropped({
+				source: "url",
+				fields: [...fields],
+				columns: [],
+				filterFields: [],
+				filters: {},
+				residual,
+				sorters
+			});
+		}
+		const urlResidual = parsed.residual ?? [];
+		const residualPaths = new Set(urlResidual.flatMap((expr) => filterExprFields(expr)));
 		const base = (opts?.mode ? opts.mode === "replace" : parsed.snapshot === true) ? null : urlBaseline;
 		const currentItemsPerPage = pagination.value.itemsPerPage;
 		const skip = parsed.skip ?? 0;
@@ -2170,12 +2336,24 @@ function createTableState(opts) {
 		hydratingFromUrl = true;
 		if (filtersGate !== "none") {
 			const next = {};
+			const fromBase = (path) => !!base?.filters[path] && !residualPaths.has(path);
 			for (const path in filters.value) if (!gateOwns(filtersGate, path)) next[path] = filters.value[path];
-			else if (base?.filters[path]) next[path] = cloneConditions(base.filters[path]);
-			if (base) for (const path in base.filters) next[path] ??= cloneConditions(base.filters[path]);
+			else if (fromBase(path)) next[path] = cloneConditions(base.filters[path]);
+			if (base) {
+				for (const path in base.filters) if (fromBase(path)) next[path] ??= cloneConditions(base.filters[path]);
+			}
 			for (const path in parsed.filters) next[path] = parsed.filters[path];
 			filters.value = next;
 		}
+		if (residualSync) {
+			const mentioned = new Set([...Object.keys(parsed.filters), ...residualPaths]);
+			const next = residualFilters.value.filter((expr) => !urlOwnsResidual(expr));
+			if (base) {
+				for (const expr of base.residual) if (!filterExprFields(expr).some((f) => mentioned.has(f))) next.push(expr);
+			}
+			next.push(...urlResidual);
+			setResidualFilters(next);
+		}
 		let urlSortersChanged = false;
 		if (sortersGate !== "none") {
 			const urlSortFields = new Set(parsed.sorters.map((s) => s.field));
@@ -2220,7 +2398,11 @@ function createTableState(opts) {
 	const debouncedFilterQuery = debounce(() => {
 		if (queryDetected) scheduleQuery();
 	}, FILTER_DEBOUNCE_MS);
-	watch([() => filters.value, () => searchTerm.value], () => {
+	watch([
+		() => filters.value,
+		() => residualFilters.value,
+		() => searchTerm.value
+	], () => {
 		if (hydratingFromUrl) return;
 		if (!queryDetected) return;
 		mustRefresh.value = true;
@@ -2267,6 +2449,7 @@ function createTableState(opts) {
 	});
 	watch([
 		() => filters.value,
+		() => residualFilters.value,
 		() => sorters.value,
 		() => searchTerm.value,
 		() => pagination.value,
@@ -2451,4 +2634,4 @@ function useRegisterMainActionListener(state, listener, enabled) {
 	});
 }
 //#endregion
-export { intentToScope as C, ROW_ACTIONS_PATH as D, triggerAction as E, ROW_ACTIONS_TYPE as O, intentClass as S, isPlainLeftClick as T, applyRowsGate as _, useTableContext as a, createNavigateGestures as b, DEFAULT_AVAILABLE_ASPECTS as c, ownerNameOf as d, readPresetLabel as f, applyRowGate as g, rowActionHref as h, useRegisterMainActionListener as i, ASPECT_ICONS as l, onSelectControlKeydown as m, createTableState as n, useTableContextOptional as o, INTERACTIVE_SELECTOR as p, provideTableContext as r, warnUnsupportedFilter as s, createStaticTableState as t, ASPECT_LABELS as u, ariaLabelFor as v, isModClick as w, extractIdentifier as x, collectIdentifiers as y };
+export { intentClass as C, triggerAction as D, isPlainLeftClick as E, ROW_ACTIONS_PATH as O, extractIdentifier as S, isModClick as T, applyRowGate as _, useTableContext as a, collectIdentifiers as b, warnUnsupportedFilter as c, ASPECT_LABELS as d, ownerNameOf as f, rowActionHref as g, onSelectControlKeydown as h, useRegisterMainActionListener as i, ROW_ACTIONS_TYPE as k, DEFAULT_AVAILABLE_ASPECTS as l, INTERACTIVE_SELECTOR as m, createTableState as n, useTableContextOptional as o, readPresetLabel as p, provideTableContext as r, warnFieldsDropped as s, createStaticTableState as t, ASPECT_ICONS as u, applyRowsGate as v, intentToScope as w, createNavigateGestures as x, ariaLabelFor as y };