@atscript/ui-table 0.1.138 → 0.1.139

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { FilterExpr, Uniquery } from "@uniqu/core";
 import { ColumnDef, PaginationControl, SortControl, TableDef } from "@atscript/ui";
+import { FilterExpr, Uniquery } from "@uniqu/core";
 import { Client } from "@atscript/db-client";
 
 //#region src/filters/filter-types.d.ts
@@ -44,6 +44,34 @@ type ColumnFilterType = "text" | "number" | "date" | "boolean" | "enum" | "ref";
 declare function conditionsForType(type: ColumnFilterType, nullable?: boolean): readonly FilterConditionType[];
 /** Map a ColumnDef display type string to a ColumnFilterType. */
 declare function columnFilterType(columnType: string): ColumnFilterType;
+/** The `ColumnDef` fields that decide which filter conditions a column offers. */
+type FilterableColumn = Pick<ColumnDef, "type" | "nullable" | "filterable" | "filterOps">;
+/**
+ * Filter conditions a column offers — the one answer every filter UI (column
+ * menu, filter dialog, filter bar, config dialog) reads.
+ *
+ * - Value-filterable (`filterable: true`) → {@link conditionsForType} for its
+ *   display type.
+ * - Existence-only (`filterable: false`, `filterOps` includes `$exists` — a
+ *   JSON-stored column) → `null` / `notNull`: whether a value is present,
+ *   never what it is.
+ * - Otherwise → `[]`: the column takes no filter.
+ *
+ * `null` / `notNull` are dropped for non-nullable columns, so an existence-only
+ * column that is never empty offers nothing.
+ *
+ * @since 0.1.139
+ */
+declare function columnFilterConditions(column: FilterableColumn): readonly FilterConditionType[];
+/**
+ * Whether a column takes any filter at all — value comparisons or the
+ * existence-only `null` / `notNull` pair. Use it (not
+ * `column.filterable`, which is value comparison only) to decide whether to
+ * show a column in a filter UI.
+ *
+ * @since 0.1.139
+ */
+declare function isColumnFilterable(column: FilterableColumn): boolean;
 //#endregion
 //#region src/filters/escape-regex.d.ts
 /** Escape special regex characters in user input for safe embedding in $regex. */
@@ -54,6 +82,14 @@ declare function unescapeRegex(input: string): string;
 //#region src/filters/filter-input-format.d.ts
 /** Default condition type when no symbol matches the input. */
 declare function defaultCondition(columnType: ColumnFilterType): FilterConditionType;
+/**
+ * The condition a column's filter input starts with: its type's
+ * {@link defaultCondition} when the column offers it, otherwise the first
+ * condition it does offer (`null` on an existence-only column).
+ *
+ * @since 0.1.139
+ */
+declare function columnDefaultCondition(column: FilterableColumn): FilterConditionType;
 /**
  * Parse a user-typed filter input string into a FilterCondition.
  *
@@ -77,9 +113,19 @@ declare function defaultCondition(columnType: ColumnFilterType): FilterCondition
  *   number/date/boolean → eq
  *
  * Returns undefined for empty/invalid input or if the parsed operator
- * is not available for the column type.
+ * is not available for the column type. To honour what a specific column
+ * offers (an existence-only column takes only `<empty>` / `!<empty>`), use
+ * {@link parseColumnFilterInput}.
  */
 declare function parseFilterInput(text: string, columnType: ColumnFilterType, nullable?: boolean): FilterCondition | undefined;
+/**
+ * {@link parseFilterInput} for a column: the type comes from the column and
+ * the accepted operators are {@link columnFilterConditions} — the ones the
+ * column's filter UI offers.
+ *
+ * @since 0.1.139
+ */
+declare function parseColumnFilterInput(text: string, column: FilterableColumn): FilterCondition | undefined;
 /**
  * Format a FilterCondition for chip/token display using operator symbols.
  *
@@ -101,17 +147,57 @@ declare function formatFilterCondition(condition: FilterCondition): string;
 declare function filtersToUniqueryFilter(fieldFilters: FieldFilters): FilterExpr | undefined;
 //#endregion
 //#region src/filters/uniquery-to-filters.d.ts
+/**
+ * Why part of a Uniquery filter has no `FieldFilters` equivalent.
+ *
+ * - `"cross-field"` — an `$or` / `$not` that spans several fields
+ *   (`a=1 OR b=2`). The model ANDs fields, so it cannot hold a correlation.
+ * - `"operator"` — an operator or operand no condition type expresses
+ *   (`$nor`, an unknown `$op`, an object value, an empty `$in`, …).
+ * - `"negation"` — a negative inside an `$or`, or a `$not` that is not a
+ *   plain inversion of equality / emptiness.
+ * - `"conjunction"` — a second positive group AND'd onto a field that already
+ *   has one (`a>1 AND a<5`). A field's positive conditions are OR'd.
+ *
+ * @since 0.1.139
+ */
+type UnsupportedFilterReason = "cross-field" | "operator" | "negation" | "conjunction";
+/**
+ * One AND-ed piece of a Uniquery filter that {@link uniqueryFilterToFieldFilters}
+ * left out of its result.
+ *
+ * @since 0.1.139
+ */
+interface UnsupportedFilter {
+  reason: UnsupportedFilterReason;
+  /** The left-out sub-expression, as it appeared in the input. */
+  expr: FilterExpr;
+  /** Field paths the sub-expression references, in order of appearance. */
+  fields: string[];
+}
 /**
  * Convert a Uniquery `FilterExpr` back into the UI's `FieldFilters` shape.
  *
- * Inverse of `filtersToUniqueryFilter`. Drops:
- * - conditions on fields not in `knownFields` (when provided)
- * - operators not in the supported `FilterConditionType` union
- * - `$not` branches (no native UI representation; lossy on hand-crafted URLs)
+ * Inverse of `filtersToUniqueryFilter`, and exact for everything that encoder
+ * produces. For any other input, each AND-ed piece is either converted exactly
+ * or left out whole and reported — never approximated:
+ *
+ * - `$in` becomes equality conditions on the field, `$nin` inequality ones.
+ * - A same-field `$or` becomes that field's OR'd conditions.
+ * - A `$not` that inverts equality / emptiness becomes the inverse conditions.
+ * - Fields next to `$and` / `$or` / `$not` in one object are all kept.
+ * - Anything else (see {@link UnsupportedFilterReason}) is left out. Leaving
+ *   an AND-ed piece out only ever widens the match, so the result selects a
+ *   superset of `expr`. Each left-out piece goes to `onUnsupportedFilter`, or
+ *   to a dev-mode `console.warn` when no handler is given.
+ *
+ * Conditions on fields outside `knownFields` (when provided) are ignored
+ * silently: they are not this table's (a host page flag, a stale column). A
+ * piece that mixes known and unknown fields is reported.
  *
  * Returns `{}` for an empty/missing expression. Never throws.
  */
-declare function uniqueryFilterToFieldFilters(expr: FilterExpr | undefined, knownFields?: Iterable<string> | Set<string>): FieldFilters;
+declare function uniqueryFilterToFieldFilters(expr: FilterExpr | undefined, knownFields?: Iterable<string> | Set<string>, onUnsupportedFilter?: (issue: UnsupportedFilter) => void): FieldFilters;
 //#endregion
 //#region src/filters/date-shortcuts.d.ts
 /** A date shortcut produces a label and a [start, end] ISO date range. */
@@ -678,10 +764,35 @@ interface UrlQueryStateLike {
    */
   ignoreSorters?: boolean;
 }
+/**
+ * The URL control that marks a query string as a complete snapshot of the
+ * table's filters and sorters. Restoring a URL that carries it clears every
+ * filter and sorter the URL owns before applying its own, so nothing the URL
+ * omits survives (empty `$sort` included). A URL without it is an overlay:
+ * its filters and sorters are laid over the table's starting ones.
+ *
+ * The encoder writes it bare (`…&$snapshot`) on every URL; the decoder goes
+ * by presence alone, whatever the value. `UrlQuerySync.snapshot: false` turns
+ * both off.
+ *
+ * @since 0.1.139
+ */
+declare const URL_SNAPSHOT_KEY = "$snapshot";
 /** Snapshot recovered from a URL string — partial on purpose so callers can layer it onto state. */
 interface UrlQueryStateSnapshot {
   filters: FieldFilters;
   sorters: SortControl[];
+  /**
+   * `true` when the URL carried {@link URL_SNAPSHOT_KEY} (and `sync.snapshot`
+   * is not `false`). Omitted otherwise. Since 0.1.139.
+   */
+  snapshot?: true;
+  /**
+   * Pieces of the URL's filter that `filters` leaves out because field filters
+   * cannot express them — see `uniqueryFilterToFieldFilters`. Omitted when
+   * the filter converted exactly. Since 0.1.139.
+   */
+  unsupported?: UnsupportedFilter[];
   /**
    * Raw record offset from `$skip` (omitted when no `$skip` in URL). The
    * decoder does NOT compute a page index — that requires `itemsPerPage`,
@@ -719,6 +830,12 @@ interface UrlQuerySync {
   search?: boolean;
   /** Whether pagination (`$skip` + `$limit`) syncs. Page and limit are coupled — one knob. */
   pagination?: boolean;
+  /**
+   * Whether the encoder writes {@link URL_SNAPSHOT_KEY} and the decoder
+   * honours it. Default `true`; `false` makes every URL an overlay.
+   * Since 0.1.139.
+   */
+  snapshot?: boolean;
 }
 interface UrlQueryDefaults {
   /** Consumer's `:limit` prop. Used to omit `$limit` from the URL when state matches it. */
@@ -762,7 +879,9 @@ declare function gateOwns(gate: AspectGate, path: string): boolean;
  * `$actions`, `forceFilters`, `forceSorters` — those are not user state) and
  * appends `$skip` / `$limit` for pagination.
  *
- * Returns `""` (no leading `?`) for the default view.
+ * Stamps {@link URL_SNAPSHOT_KEY} unless `defaults.sync.snapshot` is `false`
+ * (or neither filters nor sorters sync), so the default view serializes to
+ * `"$snapshot"`; with the marker off it serializes to `""` (no leading `?`).
  */
 declare function stateToUrlQueryString(state: UrlQueryStateLike, defaults: UrlQueryDefaults): string;
 /**
@@ -796,7 +915,9 @@ interface UrlQueryParseOptions {
  * Robust by design — schema drift and copy-paste errors must not break the
  * recipient's view:
  * - unknown fields (not in `knownFields`) → silently dropped
- * - unsupported operators → silently dropped
+ * - filter pieces field filters cannot express (cross-field OR, unknown
+ *   operator, …) → left out of `filters` and listed in `unsupported`, never
+ *   approximated (the parser does not warn — the caller decides)
  * - unknown controls (e.g. `$weird=42`) → silently ignored
  * - malformed query → `{ filters: {}, sorters: [], searchTerm: "" }`
  *
@@ -1306,4 +1427,7 @@ declare function cellAsString(v: unknown): string;
  */
 declare function sortRowsLocally<T extends Record<string, unknown>>(rows: T[], sorters: readonly SortControl[], getValue?: (row: T, field: string) => unknown): T[];
 //#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, DRAFT_PERSISTED_ASPECTS, type DateShortcut, type DisplayColumnDef, type DraftPersistedAspect, ExportAbortError, type ExportPage, type ExportPageFetcher, type ExportScalar, type FetchPlan, type FetchPlanMode, type FieldFilters, type FilterCondition, type FilterConditionType, 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, USER_CONF_PREFIX, type UrlQueryDefaults, type UrlQueryParseOptions, type UrlQueryStateLike, type UrlQueryStateSnapshot, type UrlQuerySync, type UserConfData, appConfId, arraysEqual, blockStartFor, buildTableQuery, cellAsString, clampTopIndex, collectExportRows, columnFilterType, computeDefaultColumnWidth, conditionLabel, conditionsForType, csvCell, dateShortcuts, debounce, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, fromWireSnapshot, gateOwns, hasSecondValue, isAuthError, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeDisplayColumns, mergeFilters, mergeSorters, normaliseSystemPresetId, pageAlignedBlocksFor, parseFilterInput, planFetch, reconcileColumnWidthDefaults, reorderColumnNames, resolveAspectGate, resolveExportValue, resolveSystemPresets, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortRowsLocally, sortersEqual, stableStringify, stateToUrlQueryString, toCsv, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryConsumesKey, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb, withStableOrder };
+//#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 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, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, fromWireSnapshot, gateOwns, hasSecondValue, isAuthError, isColumnFilterable, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeDisplayColumns, mergeFilters, mergeSorters, normaliseSystemPresetId, pageAlignedBlocksFor, parseColumnFilterInput, parseFilterInput, planFetch, reconcileColumnWidthDefaults, reorderColumnNames, resolveAspectGate, resolveExportValue, resolveSystemPresets, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortRowsLocally, sortersEqual, stableStringify, stateToUrlQueryString, toCsv, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryConsumesKey, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb, withStableOrder };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
+import { FilterExpr, Uniquery } from "@uniqu/core";
 import { Client } from "@atscript/db-client";
 import { ColumnDef, PaginationControl, SortControl, TableDef } from "@atscript/ui";
-import { FilterExpr, Uniquery } from "@uniqu/core";
 
 //#region src/filters/filter-types.d.ts
 /** Filter condition type identifiers. */
@@ -44,6 +44,34 @@ type ColumnFilterType = "text" | "number" | "date" | "boolean" | "enum" | "ref";
 declare function conditionsForType(type: ColumnFilterType, nullable?: boolean): readonly FilterConditionType[];
 /** Map a ColumnDef display type string to a ColumnFilterType. */
 declare function columnFilterType(columnType: string): ColumnFilterType;
+/** The `ColumnDef` fields that decide which filter conditions a column offers. */
+type FilterableColumn = Pick<ColumnDef, "type" | "nullable" | "filterable" | "filterOps">;
+/**
+ * Filter conditions a column offers — the one answer every filter UI (column
+ * menu, filter dialog, filter bar, config dialog) reads.
+ *
+ * - Value-filterable (`filterable: true`) → {@link conditionsForType} for its
+ *   display type.
+ * - Existence-only (`filterable: false`, `filterOps` includes `$exists` — a
+ *   JSON-stored column) → `null` / `notNull`: whether a value is present,
+ *   never what it is.
+ * - Otherwise → `[]`: the column takes no filter.
+ *
+ * `null` / `notNull` are dropped for non-nullable columns, so an existence-only
+ * column that is never empty offers nothing.
+ *
+ * @since 0.1.139
+ */
+declare function columnFilterConditions(column: FilterableColumn): readonly FilterConditionType[];
+/**
+ * Whether a column takes any filter at all — value comparisons or the
+ * existence-only `null` / `notNull` pair. Use it (not
+ * `column.filterable`, which is value comparison only) to decide whether to
+ * show a column in a filter UI.
+ *
+ * @since 0.1.139
+ */
+declare function isColumnFilterable(column: FilterableColumn): boolean;
 //#endregion
 //#region src/filters/escape-regex.d.ts
 /** Escape special regex characters in user input for safe embedding in $regex. */
@@ -54,6 +82,14 @@ declare function unescapeRegex(input: string): string;
 //#region src/filters/filter-input-format.d.ts
 /** Default condition type when no symbol matches the input. */
 declare function defaultCondition(columnType: ColumnFilterType): FilterConditionType;
+/**
+ * The condition a column's filter input starts with: its type's
+ * {@link defaultCondition} when the column offers it, otherwise the first
+ * condition it does offer (`null` on an existence-only column).
+ *
+ * @since 0.1.139
+ */
+declare function columnDefaultCondition(column: FilterableColumn): FilterConditionType;
 /**
  * Parse a user-typed filter input string into a FilterCondition.
  *
@@ -77,9 +113,19 @@ declare function defaultCondition(columnType: ColumnFilterType): FilterCondition
  *   number/date/boolean → eq
  *
  * Returns undefined for empty/invalid input or if the parsed operator
- * is not available for the column type.
+ * is not available for the column type. To honour what a specific column
+ * offers (an existence-only column takes only `<empty>` / `!<empty>`), use
+ * {@link parseColumnFilterInput}.
  */
 declare function parseFilterInput(text: string, columnType: ColumnFilterType, nullable?: boolean): FilterCondition | undefined;
+/**
+ * {@link parseFilterInput} for a column: the type comes from the column and
+ * the accepted operators are {@link columnFilterConditions} — the ones the
+ * column's filter UI offers.
+ *
+ * @since 0.1.139
+ */
+declare function parseColumnFilterInput(text: string, column: FilterableColumn): FilterCondition | undefined;
 /**
  * Format a FilterCondition for chip/token display using operator symbols.
  *
@@ -101,17 +147,57 @@ declare function formatFilterCondition(condition: FilterCondition): string;
 declare function filtersToUniqueryFilter(fieldFilters: FieldFilters): FilterExpr | undefined;
 //#endregion
 //#region src/filters/uniquery-to-filters.d.ts
+/**
+ * Why part of a Uniquery filter has no `FieldFilters` equivalent.
+ *
+ * - `"cross-field"` — an `$or` / `$not` that spans several fields
+ *   (`a=1 OR b=2`). The model ANDs fields, so it cannot hold a correlation.
+ * - `"operator"` — an operator or operand no condition type expresses
+ *   (`$nor`, an unknown `$op`, an object value, an empty `$in`, …).
+ * - `"negation"` — a negative inside an `$or`, or a `$not` that is not a
+ *   plain inversion of equality / emptiness.
+ * - `"conjunction"` — a second positive group AND'd onto a field that already
+ *   has one (`a>1 AND a<5`). A field's positive conditions are OR'd.
+ *
+ * @since 0.1.139
+ */
+type UnsupportedFilterReason = "cross-field" | "operator" | "negation" | "conjunction";
+/**
+ * One AND-ed piece of a Uniquery filter that {@link uniqueryFilterToFieldFilters}
+ * left out of its result.
+ *
+ * @since 0.1.139
+ */
+interface UnsupportedFilter {
+  reason: UnsupportedFilterReason;
+  /** The left-out sub-expression, as it appeared in the input. */
+  expr: FilterExpr;
+  /** Field paths the sub-expression references, in order of appearance. */
+  fields: string[];
+}
 /**
  * Convert a Uniquery `FilterExpr` back into the UI's `FieldFilters` shape.
  *
- * Inverse of `filtersToUniqueryFilter`. Drops:
- * - conditions on fields not in `knownFields` (when provided)
- * - operators not in the supported `FilterConditionType` union
- * - `$not` branches (no native UI representation; lossy on hand-crafted URLs)
+ * Inverse of `filtersToUniqueryFilter`, and exact for everything that encoder
+ * produces. For any other input, each AND-ed piece is either converted exactly
+ * or left out whole and reported — never approximated:
+ *
+ * - `$in` becomes equality conditions on the field, `$nin` inequality ones.
+ * - A same-field `$or` becomes that field's OR'd conditions.
+ * - A `$not` that inverts equality / emptiness becomes the inverse conditions.
+ * - Fields next to `$and` / `$or` / `$not` in one object are all kept.
+ * - Anything else (see {@link UnsupportedFilterReason}) is left out. Leaving
+ *   an AND-ed piece out only ever widens the match, so the result selects a
+ *   superset of `expr`. Each left-out piece goes to `onUnsupportedFilter`, or
+ *   to a dev-mode `console.warn` when no handler is given.
+ *
+ * Conditions on fields outside `knownFields` (when provided) are ignored
+ * silently: they are not this table's (a host page flag, a stale column). A
+ * piece that mixes known and unknown fields is reported.
  *
  * Returns `{}` for an empty/missing expression. Never throws.
  */
-declare function uniqueryFilterToFieldFilters(expr: FilterExpr | undefined, knownFields?: Iterable<string> | Set<string>): FieldFilters;
+declare function uniqueryFilterToFieldFilters(expr: FilterExpr | undefined, knownFields?: Iterable<string> | Set<string>, onUnsupportedFilter?: (issue: UnsupportedFilter) => void): FieldFilters;
 //#endregion
 //#region src/filters/date-shortcuts.d.ts
 /** A date shortcut produces a label and a [start, end] ISO date range. */
@@ -678,10 +764,35 @@ interface UrlQueryStateLike {
    */
   ignoreSorters?: boolean;
 }
+/**
+ * The URL control that marks a query string as a complete snapshot of the
+ * table's filters and sorters. Restoring a URL that carries it clears every
+ * filter and sorter the URL owns before applying its own, so nothing the URL
+ * omits survives (empty `$sort` included). A URL without it is an overlay:
+ * its filters and sorters are laid over the table's starting ones.
+ *
+ * The encoder writes it bare (`…&$snapshot`) on every URL; the decoder goes
+ * by presence alone, whatever the value. `UrlQuerySync.snapshot: false` turns
+ * both off.
+ *
+ * @since 0.1.139
+ */
+declare const URL_SNAPSHOT_KEY = "$snapshot";
 /** Snapshot recovered from a URL string — partial on purpose so callers can layer it onto state. */
 interface UrlQueryStateSnapshot {
   filters: FieldFilters;
   sorters: SortControl[];
+  /**
+   * `true` when the URL carried {@link URL_SNAPSHOT_KEY} (and `sync.snapshot`
+   * is not `false`). Omitted otherwise. Since 0.1.139.
+   */
+  snapshot?: true;
+  /**
+   * Pieces of the URL's filter that `filters` leaves out because field filters
+   * cannot express them — see `uniqueryFilterToFieldFilters`. Omitted when
+   * the filter converted exactly. Since 0.1.139.
+   */
+  unsupported?: UnsupportedFilter[];
   /**
    * Raw record offset from `$skip` (omitted when no `$skip` in URL). The
    * decoder does NOT compute a page index — that requires `itemsPerPage`,
@@ -719,6 +830,12 @@ interface UrlQuerySync {
   search?: boolean;
   /** Whether pagination (`$skip` + `$limit`) syncs. Page and limit are coupled — one knob. */
   pagination?: boolean;
+  /**
+   * Whether the encoder writes {@link URL_SNAPSHOT_KEY} and the decoder
+   * honours it. Default `true`; `false` makes every URL an overlay.
+   * Since 0.1.139.
+   */
+  snapshot?: boolean;
 }
 interface UrlQueryDefaults {
   /** Consumer's `:limit` prop. Used to omit `$limit` from the URL when state matches it. */
@@ -762,7 +879,9 @@ declare function gateOwns(gate: AspectGate, path: string): boolean;
  * `$actions`, `forceFilters`, `forceSorters` — those are not user state) and
  * appends `$skip` / `$limit` for pagination.
  *
- * Returns `""` (no leading `?`) for the default view.
+ * Stamps {@link URL_SNAPSHOT_KEY} unless `defaults.sync.snapshot` is `false`
+ * (or neither filters nor sorters sync), so the default view serializes to
+ * `"$snapshot"`; with the marker off it serializes to `""` (no leading `?`).
  */
 declare function stateToUrlQueryString(state: UrlQueryStateLike, defaults: UrlQueryDefaults): string;
 /**
@@ -796,7 +915,9 @@ interface UrlQueryParseOptions {
  * Robust by design — schema drift and copy-paste errors must not break the
  * recipient's view:
  * - unknown fields (not in `knownFields`) → silently dropped
- * - unsupported operators → silently dropped
+ * - filter pieces field filters cannot express (cross-field OR, unknown
+ *   operator, …) → left out of `filters` and listed in `unsupported`, never
+ *   approximated (the parser does not warn — the caller decides)
  * - unknown controls (e.g. `$weird=42`) → silently ignored
  * - malformed query → `{ filters: {}, sorters: [], searchTerm: "" }`
  *
@@ -1306,4 +1427,7 @@ declare function cellAsString(v: unknown): string;
  */
 declare function sortRowsLocally<T extends Record<string, unknown>>(rows: T[], sorters: readonly SortControl[], getValue?: (row: T, field: string) => unknown): T[];
 //#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, DRAFT_PERSISTED_ASPECTS, type DateShortcut, type DisplayColumnDef, type DraftPersistedAspect, ExportAbortError, type ExportPage, type ExportPageFetcher, type ExportScalar, type FetchPlan, type FetchPlanMode, type FieldFilters, type FilterCondition, type FilterConditionType, 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, USER_CONF_PREFIX, type UrlQueryDefaults, type UrlQueryParseOptions, type UrlQueryStateLike, type UrlQueryStateSnapshot, type UrlQuerySync, type UserConfData, appConfId, arraysEqual, blockStartFor, buildTableQuery, cellAsString, clampTopIndex, collectExportRows, columnFilterType, computeDefaultColumnWidth, conditionLabel, conditionsForType, csvCell, dateShortcuts, debounce, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, fromWireSnapshot, gateOwns, hasSecondValue, isAuthError, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeDisplayColumns, mergeFilters, mergeSorters, normaliseSystemPresetId, pageAlignedBlocksFor, parseFilterInput, planFetch, reconcileColumnWidthDefaults, reorderColumnNames, resolveAspectGate, resolveExportValue, resolveSystemPresets, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortRowsLocally, sortersEqual, stableStringify, stateToUrlQueryString, toCsv, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryConsumesKey, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb, withStableOrder };
+//#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 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, defaultCondition, derivePresetAspects, deserializeDraft, draftMatchesPreset, escapeRegex, filledFilterCount, filterTokenLabel, filtersToUniqueryFilter, formatFilterCondition, fromWireSnapshot, gateOwns, hasSecondValue, isAuthError, isColumnFilterable, isDirtyAgainst, isEmptyDraft, isFilled, isSimpleEq, isSystemPresetId, isUnavailableError, mergeDisplayColumns, mergeFilters, mergeSorters, normaliseSystemPresetId, pageAlignedBlocksFor, parseColumnFilterInput, parseFilterInput, planFetch, reconcileColumnWidthDefaults, reorderColumnNames, resolveAspectGate, resolveExportValue, resolveSystemPresets, rowsToPks, sameColumnSet, serializeDraft, setsEqual, sortRowsLocally, sortersEqual, stableStringify, stateToUrlQueryString, toCsv, toWireSnapshot, togglePk, trimSelection, unescapeRegex, uniqueryFilterToFieldFilters, urlQueryConsumesKey, urlQueryStringToState, userConfId, walkBackwardAbsorb, walkForwardAbsorb, withStableOrder };