@atscript/ui-table 0.1.140 → 0.1.142

package/dist/index.d.cts

@@ -31,6 +31,14 @@ declare function isSimpleEq(condition: FilterCondition): boolean;
 declare function conditionLabel(type: FilterConditionType): string;
 /** Count of fields that have at least one filled condition. */
 declare function filledFilterCount(filters: FieldFilters): number;
+/**
+ * `filters` without the fields that have no filled condition — the shape
+ * table state holds (a field with nothing filled has no entry). Returns
+ * `filters` itself when every field has one; never mutates it.
+ *
+ * @since 0.1.142
+ */
+declare function compactFieldFilters(filters: FieldFilters): FieldFilters;
 /** Summarize a field's conditions into a human-readable token label. */
 declare function filterTokenLabel(path: string, conditions: FilterCondition[], columnLabel?: string): string;
 //#endregion
@@ -175,6 +183,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 +205,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 +226,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 +282,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 +560,113 @@ 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;
+};
+/**
+ * Spell a snapshot the way table state holds it, so it compares equal to a
+ * capture of the state it produces:
+ *
+ * - `columns.columnWidths` — an entry equal to its column's default width, or
+ *   on a path with no default (not a column), goes; an emptied map is
+ *   omitted. Capture writes overrides only.
+ * - `filterOps` — a field with no filled condition goes
+ *   (`compactFieldFilters`). Table state never holds one.
+ *
+ * `defaultWidths` maps each column path to its default width — the `d` of
+ * its `ColumnWidthsMap` entry. Other aspects pass through. Returns `snapshot`
+ * itself when nothing changes; the input is never mutated.
+ *
+ * @since 0.1.142
+ */
+declare function canonicalPresetSnapshot(snapshot: PresetSnapshot, defaultWidths: Readonly<Record<string, string>>): PresetSnapshot;
+/**
+ * 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 +1025,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 +1165,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 +1722,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, canonicalPresetSnapshot, cellAsString, clampTopIndex, collectExportRows, columnDefaultCondition, columnFilterConditions, columnFilterType, compactFieldFilters, 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

@@ -31,6 +31,14 @@ declare function isSimpleEq(condition: FilterCondition): boolean;
 declare function conditionLabel(type: FilterConditionType): string;
 /** Count of fields that have at least one filled condition. */
 declare function filledFilterCount(filters: FieldFilters): number;
+/**
+ * `filters` without the fields that have no filled condition — the shape
+ * table state holds (a field with nothing filled has no entry). Returns
+ * `filters` itself when every field has one; never mutates it.
+ *
+ * @since 0.1.142
+ */
+declare function compactFieldFilters(filters: FieldFilters): FieldFilters;
 /** Summarize a field's conditions into a human-readable token label. */
 declare function filterTokenLabel(path: string, conditions: FilterCondition[], columnLabel?: string): string;
 //#endregion
@@ -175,6 +183,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 +205,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 +226,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 +282,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 +560,113 @@ 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;
+};
+/**
+ * Spell a snapshot the way table state holds it, so it compares equal to a
+ * capture of the state it produces:
+ *
+ * - `columns.columnWidths` — an entry equal to its column's default width, or
+ *   on a path with no default (not a column), goes; an emptied map is
+ *   omitted. Capture writes overrides only.
+ * - `filterOps` — a field with no filled condition goes
+ *   (`compactFieldFilters`). Table state never holds one.
+ *
+ * `defaultWidths` maps each column path to its default width — the `d` of
+ * its `ColumnWidthsMap` entry. Other aspects pass through. Returns `snapshot`
+ * itself when nothing changes; the input is never mutated.
+ *
+ * @since 0.1.142
+ */
+declare function canonicalPresetSnapshot(snapshot: PresetSnapshot, defaultWidths: Readonly<Record<string, string>>): PresetSnapshot;
+/**
+ * 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 +1025,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 +1165,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 +1722,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, canonicalPresetSnapshot, cellAsString, clampTopIndex, collectExportRows, columnDefaultCondition, columnFilterConditions, columnFilterType, compactFieldFilters, 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 };