@urbicon-ui/sveltekit-utils 7.0.1 → 8.1.0

package/README.md

@@ -5,7 +5,7 @@ Small, focused SvelteKit helpers that Urbicon apps share. Zero runtime dependenc
 Currently shipping:
 
 - **URL-state runes** — reactive `useUrlParam` / `useUrlArrayParam` that keep component state in sync with `?query=` parameters
-- **Table-query URL sync** — opt-in `?q=…&sort=…&page=…` mirroring for `@urbicon-ui/table` server mode, plus the pure serializers behind it
+- **Table view ↔ URL** — `bindViewToUrl`, the URL home for a `@urbicon-ui/table` view object (`?q=…&sort=…&page=…`), plus the pure serializers for the load path
 - **Cron runner** — interval-based background fetcher for scheduled server endpoints
 - **SSE stream reader** — `streamSse`, a spec-correct async-generator client for one-shot POST `text/event-stream` endpoints (LLM relays)
 
@@ -57,60 +57,60 @@ updateUrlSearchParams({ page: '1', tag: ['a', 'b'] }, { replaceState: true });
 - URL updates use `goto()` with `replaceState: true`, `noScroll: true`, `keepFocus: true` — suited for filter/pagination UIs, not full page transitions.
 - `useUrlParam` returns getters (not Svelte stores) so consumers can read the value lazily inside `$derived`/`$effect`.
 
-## Table Query ↔ URL (`table-query` + `url.svelte`)
+## Table View ↔ URL (`url.svelte` + `table-view`)
 
-Opt-in URL sync for `@urbicon-ui/table`, in client mode as well as `mode="server"`: the `TableQuery` the table emits (search, sort, page, page size, filters, grouping) is mirrored onto query parameters (`?q=…&sort=…&page=…`), so the view state survives reloads, can be shared as a link, and — unlike `localStorage` — is visible to the server.
+`bindViewToUrl` gives the view object of `@urbicon-ui/table` — search, sort, page, page size, filters, grouping — the URL as its home: the axes are mirrored onto query parameters (`?q=…&sort=…&page=…`), so the view survives a reload, can be shared as a link, and — unlike `localStorage` — is visible to the server.
 
 ```svelte
 <script lang="ts">
-  import { Table } from '@urbicon-ui/table';
-  import { tableQueryToSearchParams } from '@urbicon-ui/sveltekit-utils/table-query';
-  import { createTableQueryUrlSync } from '@urbicon-ui/sveltekit-utils/url.svelte';
+  import { Table, createTableView } from '@urbicon-ui/table';
+  import { bindViewToUrl } from '@urbicon-ui/sveltekit-utils/url.svelte';
 
-  const sync = createTableQueryUrlSync({ defaults: { itemsPerPage: 25 } });
+  const view = createTableView({ defaults: { pageSize: 25 } });
+  bindViewToUrl(view);
 </script>
 
-<Table
-  mode="server"
-  {columns}
-  itemsPerPage={25}
-  query={sync.viewState}
-  queryFn={async (query, { signal }) => {
-    sync.syncQuery(query); // mirror the query onto the URL (replaceState)
-    const res = await fetch(`/api/users?${tableQueryToSearchParams(query)}`, { signal });
-    const data = await res.json();
-    return { items: data.results, totalItems: data.total };
-  }}
-/>
+<Table {items} {columns} {view} />
 ```
 
-`viewState` carries **only the axes the URL actually names**, and the table's `query` prop reads it by field presence: a present field controls that axis, an absent one leaves persistence and the `initial*` seeds alone. That is why this is not `initialQuery` — that one describes every axis, including the ones it filled in from the defaults, so a table wired to it ignores `persistenceConfig`, `initialSort`, `initialFilters` and `initialGroupBy` on every URL. `initialQuery` stays what its name says: a complete snapshot, parsed once, to seed a fetch with.
+Both calls belong in the component's initialisation. The init half runs synchronously — a `?sort=…` link renders sorted server HTML — and the runtime halves are effects: URL navigations apply to the view, the reader's changes reach the URL debounced.
 
-Because `viewState` re-reads the URL rather than capturing it, the browser's back button works: navigating back to a URL without `?sort` returns the table to its unsorted view.
+The second argument is optional; every option has a default:
 
-A controlled axis is not written to `localStorage` by default, so a visit that arrives without query params starts clean. For a business table where "my filters are still there tomorrow" is expected, pair the sync with `persistenceConfig={{ tableId: '…', persistControlled: true }}` — the table then stores what the reader themselves changed (never what a shared link brought), and hands it back on a bare visit. Reading order is unaffected: the URL still wins.
+| Option            | Default | Effect                                                                                                                                                                                                            |
+| ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `axes`            | all six | Which axes this binding manages. An unbound axis never reaches the URL, whatever the view holds.                                                                                                                  |
+| `debounceMs`      | `300`   | Delay before a view change is written to the URL.                                                                                                                                                                 |
+| `replaceState`    | `true`  | Replace the current history entry instead of pushing one, so rapid sort/filter/page edits do not flood the back button.                                                                                           |
+| `prefix`          | `''`    | Key namespace (`prefix: 't_'` → `?t_q=…&t_page=…`) for a second bound table on the same page.                                                                                                                     |
+| `reflectExternal` | `false` | Mirror an externally applied value (a storage seed) into the URL immediately. Off by default: the address bar does not change without reader interaction, and the seed reaches the URL with the first one anyway. |
 
-With manual control (`onQueryChange` instead of `queryFn`), pass `sync.syncQuery` directly — note that `onQueryChange` does not fire when `queryFn` is set, which is why the managed variant calls it inside `queryFn`.
+Because the binding re-reads the URL rather than capturing it, the browser's back button works: navigating back to a URL that no longer names `?sort` returns the table to its default sort.
 
-The pure serializers live under `@urbicon-ui/sveltekit-utils/table-query` and work without SvelteKit — e.g. to parse the initial query in a server `load` and fetch the first page during SSR:
+The pure serializers work without SvelteKit — e.g. to parse the incoming query in a server `load` and fetch the first page during SSR. Use `searchParamsToViewSnapshot` from `./table-view`: it takes the *same* defaults object the component hands `createTableView`, so the server cannot resolve an absent param differently from the client, and it hands back the very shape a managed `source.query` receives.
 
 ```typescript
+// view-defaults.ts — imported by both the component and the load function
+export const userView = { pageSize: 25, sort: { column: 'joined', direction: 'desc' } };
+
 // +page.server.ts
-import { searchParamsToTableQuery } from '@urbicon-ui/sveltekit-utils/table-query';
+import { searchParamsToViewSnapshot } from '@urbicon-ui/sveltekit-utils/table-view';
+import { userView } from './view-defaults';
 
-export const load = async ({ url }) => {
-  const query = searchParamsToTableQuery(url.searchParams, { defaults: { itemsPerPage: 25 } });
-  return { initialResult: await fetchUsers(query) };
-};
+export const load = async ({ url }) => ({
+  initialResult: await fetchUsers(searchParamsToViewSnapshot(url.searchParams, userView))
+});
 ```
 
+The `./table-query` subpath that used to hold a second copy of this codec — same URL scheme, wire-vocabulary spellings, no field for a default filter set — retired with the vocabulary split it served (#162).
+
 **Design notes**
 
-- **Default elision** — values equal to `defaults` are not written; a table in its default state leaves the URL clean. Set `defaults` to the table's initial props (`itemsPerPage`, `initialPage`, `initialGroupBy`, and `sortColumn`/`sortDirection` when the table ships a baked-in `initialSort`) so the elision baseline matches the state the table starts in.
-- **Read tolerant, write strict** — unparsable params fall back to the defaults and malformed `filter` entries are skipped; serializing a structurally invalid query (non-positive page, unknown operator) throws instead of writing corrupt state.
-- **Namespacing** — `prefix: 't_'` scopes all keys (`?t_q=…`) for multiple synced tables on one page; unrelated params are always preserved.
-- **Types** — `TableQueryParams` is a structural mirror of the table's `TableQuery` (no dependency on `@urbicon-ui/table`; a parity test in the table package guards against drift).
-- **Seeding, the variant without `query`** — every axis the URL carries can also be handed to the table as a seed: `initialPage`, `initialGroupBy`, `initialSort`, `initialFilters` (plus a controlled `searchTerm` with an `onSearchTermChange` write-back). The seeds land before the table's first query emission, so a shared URL's sort/filter params survive it — the header indicator and filter chips show the URL state instead of the first emission wiping it. Its precedence is the **inverse** of `query`'s, and that is the reason to prefer `query`: an `initial*` prop seeds only an axis `persistenceConfig` has nothing stored for, so with both active a persisted sort/filter/group beats the link — including a persisted _empty_ value (the user cleared that axis once, so it stays cleared). The seeds do reach the server-rendered HTML — they are applied during construction, which runs under SSR too (measured: `initialSort`, `initialFilters`, `initialGroupBy` and `initialPage` all land in the server markup; only a controlled `searchTerm`, applied in an effect, does not). What they lack is the per-axis precedence above and any reaction to the back button, since a seed is read once. Use them only where the axis must not be controlled; otherwise `query={sync.viewState}` (+ `persistControlled` when the reader's own state should outlive the link).
+- **Default elision** — an axis whose value equals its default is not written; a table in its default state leaves the URL clean. The baseline *is* `view.defaults`, read off the object the binding decorates, so there is no second copy of the defaults to keep in step with the table's own.
+- **Read tolerant, write strict** — an unparsable value on a param the URL actually carries falls back to that axis' default, and malformed `filter` entries are skipped individually. `assertValidViewSnapshot` is the strict half: it throws on a structurally invalid view (non-positive page, unknown operator) instead of writing corrupt state, and `applyViewToSearchParams` calls it. `viewSnapshotToSearchParams` deliberately does not — it runs inside the binding on every view change, where a throw would cost the page rather than the URL.
+- **Namespacing** — `prefix: 't_'` scopes all keys (`?t_q=…`) for multiple bound tables on one page; unrelated params are always preserved. Two prefixless bindings would manage the same keys, so that throws at registration instead of producing a link that loads the wrong table.
+- **One writer per page** — every binding submits into one coalescing URL writer, so two tables land in a single navigation, each replacing only its own keys. A landing URL the writer itself sent is not applied back onto the view: an edit made while that navigation was in flight survives instead of being overwritten by the URL it raced.
+- **Types** — `TableViewLike`, `TableViewSnapshot` and `TableViewFilter` mirror the table's view object structurally, so this package carries no dependency on `@urbicon-ui/table`. A parity test in the table package (`viewMirror.parity.test.ts`) pins the mirror: the shapes must stay mutually assignable, and the real `TableView` must satisfy `TableViewLike`, which is the entire mechanism by which this binding decorates a view it never imports.
 
 ## Cron Runner (`cron`)
 
@@ -207,13 +207,15 @@ export const POST = async ({ request }) => {
 
 ## Exports
 
-| Subpath         | Contents                                                                                                           |
-| --------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `.`             | Barrel of all modules                                                                                              |
-| `./url.svelte`  | `useUrlParam`, `useUrlArrayParam`, `createUrlParam`, `updateUrlSearchParams`, `createTableQueryUrlSync`, types     |
-| `./table-query` | `tableQueryToSearchParams`, `searchParamsToTableQuery`, `applyTableQueryToSearchParams`, `TableQueryParams`, types |
-| `./cron`        | `createCronRunner`, `CronJob`, `CronRunnerConfig`, `CronRunner`                                                    |
-| `./sse`         | `streamSse`, `SseEvent`, `StreamSseOptions`, `SseRequestError`                                                     |
+| Subpath         | Contents                                                                                                                                           |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.`             | Barrel of all modules                                                                                                                              |
+| `./url.svelte`  | `useUrlParam`, `useUrlArrayParam`, `createUrlParam`, `updateUrlSearchParams`, `bindViewToUrl`, types                                               |
+| `./table-view`  | `searchParamsToViewSnapshot`, `searchParamsToViewPartial`, `viewSnapshotToSearchParams`, `applyViewToSearchParams`, `assertValidViewSnapshot`, `viewAxesNamedBy`, `viewAxisKeys`, `TABLE_VIEW_AXES`, `TABLE_VIEW_FILTER_OPERATORS`, `TableViewLike`, types |
+| `./cron`        | `createCronRunner`, `CronJob`, `CronRunnerConfig`, `CronRunner`                                                                                    |
+| `./sse`         | `streamSse`, `SseEvent`, `StreamSseOptions`, `SseRequestError`                                                                                     |
+
+`bindViewToUrl` lives in its own module (`view-binding.svelte.ts`) and is re-exported from `./url.svelte`, which is its documented import path — it has no subpath of its own. `./table-view` is SvelteKit-free (it touches no `$app/*`), which is what lets a `load` function and a plain test use it; `./url.svelte` is the half that needs the router.
 
 ## Development
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export * from './cron.js';
 export * from './sse.js';
-export * from './table-query.js';
+export * from './table-view.js';
 export * from './url.svelte.js';

package/dist/index.js

@@ -1,4 +1,4 @@
 export * from './cron.js';
 export * from './sse.js';
-export * from './table-query.js';
+export * from './table-view.js';
 export * from './url.svelte.js';

package/dist/table-view.d.ts

@@ -0,0 +1,163 @@
+/**
+ * URL (de)serialization for the v8 table view vocabulary (`TableView` from
+ * `@urbicon-ui/table`: search, sort, page, pageSize, filters, groupBy).
+ *
+ * The types in this module are a **structural mirror** of the table package's
+ * view types — deliberately not imported, so this package carries no
+ * dependency on `@urbicon-ui/table`. A type-parity test over there guards the
+ * shapes against drift; `bindViewToUrl` accepts any object shaped like
+ * {@link TableViewLike}, which the real `TableView` is.
+ *
+ * The key scheme is the shipped one (`q`, `page`, `size`, `sort`, `dir`,
+ * `group`, `filter`) — deep links written for v7 keep parsing. The write
+ * side adds one compatible extension: an empty `filter=` marker, analogous
+ * to `sort=`, so a cleared filter set elides like every other axis (the
+ * shipped read side already tolerated it).
+ */
+/**
+ * Filter operators supported by the table. Mirrors `FilterOperator` from
+ * `@urbicon-ui/table`. Used as the runtime whitelist when parsing `filter`
+ * params from the URL.
+ */
+export declare const TABLE_VIEW_FILTER_OPERATORS: readonly ["contains", "equals", "startsWith", "endsWith", "greaterThan", "lessThan"];
+/** Filter operator of a view filter. Mirrors `@urbicon-ui/table`. */
+export type TableViewFilterOperator = (typeof TABLE_VIEW_FILTER_OPERATORS)[number];
+/** Single column filter on the `filters` axis. Mirrors `Filter` from `@urbicon-ui/table`. */
+export interface TableViewFilter {
+    /** Column ID the filter applies to. */
+    column: string;
+    /** Filter operator. */
+    operator: TableViewFilterOperator;
+    /** Filter value (always a string, numeric operators convert internally). */
+    value: string;
+}
+/** One of the six view axes. Mirrors `ViewAxis` from `@urbicon-ui/table`. */
+export type TableViewAxis = 'search' | 'sort' | 'page' | 'pageSize' | 'filters' | 'groupBy';
+/** All six view axes, in vocabulary order. */
+export declare const TABLE_VIEW_AXES: readonly TableViewAxis[];
+/** Sort state of a view. Mirrors `ViewSort` from `@urbicon-ui/table`. */
+export interface TableViewSort {
+    /** Column ID to sort by. */
+    column: string;
+    /** Sort direction. */
+    direction: 'asc' | 'desc';
+}
+/**
+ * A fully resolved view state — never `undefined` anywhere. Mirrors
+ * `TableViewSnapshot` from `@urbicon-ui/table`.
+ */
+export interface TableViewSnapshot {
+    search: string;
+    sort: TableViewSort | null;
+    page: number;
+    pageSize: number;
+    filters: TableViewFilter[];
+    groupBy: string | null;
+}
+/**
+ * The surface {@link bindViewToUrl} needs from a view object — a structural
+ * mirror of the table package's `TableView` class. Field reads are reactive,
+ * field writes count as the reader's own change; `applyExternal` is the
+ * binding write surface, `claimAxes`/`releaseAxes` the fail-loud composition
+ * registry, and `originOf` the per-axis (revision, origin) bookkeeping the
+ * bindings decide by.
+ */
+export interface TableViewLike {
+    readonly defaults: TableViewSnapshot;
+    search: string;
+    sort: TableViewSort | null;
+    page: number;
+    pageSize: number;
+    filters: TableViewFilter[];
+    groupBy: string | null;
+    applyExternal(partial: Partial<TableViewSnapshot>, origin: 'external' | 'system'): void;
+    claimAxes(kind: 'url' | 'storage', axes: readonly TableViewAxis[]): void;
+    releaseAxes(kind: 'url' | 'storage', axes: readonly TableViewAxis[]): void;
+    markInitApplied(axes: readonly TableViewAxis[]): void;
+    wasInitApplied(axis: TableViewAxis): boolean;
+    originOf(axis: TableViewAxis): {
+        revision: number;
+        origin: 'user' | 'external' | 'system' | 'init';
+    };
+    snapshot(): TableViewSnapshot;
+}
+/** The URL keys a set of axes owns, with the configured prefix applied. */
+export declare function viewAxisKeys(axes: readonly TableViewAxis[], prefix?: string): string[];
+/** The axes a URL names — presence only for params it actually carries. */
+export declare function viewAxesNamedBy(sp: URLSearchParams, prefix?: string): TableViewAxis[];
+/**
+ * Parse search params into a **partial** view snapshot — a key per axis the
+ * URL actually carries, and nothing else. Read tolerant per key: an
+ * unparsable value on a *present* key falls back to the configured default
+ * for that axis (the key was present, so the axis stays claimed), and
+ * malformed filter entries are skipped individually.
+ */
+export declare function searchParamsToViewPartial(sp: URLSearchParams, defaults: Pick<TableViewSnapshot, 'page' | 'pageSize'>, prefix?: string): Partial<TableViewSnapshot>;
+/**
+ * Resolve a full view snapshot from search params: every axis the URL names
+ * comes from the URL, every other one from `defaults` — the same resolution
+ * the URL binding performs at init, for code that has no view (a server
+ * `load`).
+ *
+ * This is also what a server `load` hands its fetch. Since v9 the view and
+ * the query speak one vocabulary (#162), so there is nothing to project on
+ * the way out: the object below is the same shape a managed `source.query`
+ * receives. The `searchParamsToViewQuery` / `viewSnapshotToTableQuery` pair
+ * that used to do the projecting were identity functions once the names
+ * agreed, and are gone.
+ *
+ * The `defaults` argument is the point: it takes the very object
+ * `createTableView({ defaults })` takes, so the server cannot resolve an
+ * absent param differently from the client — and a default filter set is
+ * expressible, which the old wire-vocabulary baseline could not manage no
+ * matter how it was written (#157 finding 2).
+ *
+ * @example
+ * ```ts
+ * // shared with the component that calls createTableView({ defaults })
+ * export const invoiceView = { pageSize: 25, sort: { column: 'date', direction: 'desc' } };
+ *
+ * export const load = async ({ url }) => ({
+ *   initialResult: await fetchInvoices(searchParamsToViewSnapshot(url.searchParams, invoiceView))
+ * });
+ * ```
+ */
+export declare function searchParamsToViewSnapshot(sp: URLSearchParams, defaults?: Partial<TableViewSnapshot>, prefix?: string): TableViewSnapshot;
+/**
+ * Serialize a snapshot, eliding every axis that equals the defaults — the
+ * elision baseline *is* the view's defaults, structurally. `axes` restricts
+ * the output to a binding's own axes: an unbound axis never reaches the URL,
+ * no matter what the view holds.
+ */
+export declare function viewSnapshotToSearchParams(snapshot: TableViewSnapshot, defaults: TableViewSnapshot, axes?: readonly TableViewAxis[], prefix?: string): URLSearchParams;
+/**
+ * Write-side validation: never serialize structurally invalid state.
+ *
+ * The strict half of the module's read-tolerant / write-strict contract, and
+ * deliberately NOT called by {@link viewSnapshotToSearchParams}: that one runs
+ * inside the URL binding on every view change, where a throw would take the
+ * whole table down over a `view.page = 0` a consumer wrote. Serializing a bad
+ * page there costs a wrong URL; throwing there costs the page.
+ *
+ * @throws TypeError when an axis holds a value the URL scheme cannot mean.
+ */
+export declare function assertValidViewSnapshot(snapshot: TableViewSnapshot): void;
+/**
+ * Merge a view into existing search params: every key the given axes own is
+ * replaced by the serialized snapshot, and every other param is preserved
+ * untouched. Keys whose axis returned to its default are removed (the same
+ * elision {@link viewSnapshotToSearchParams} applies).
+ *
+ * This is the one thing the axis-scoped serializer cannot do on its own —
+ * everything else the retired `./table-query` module offered was the same
+ * codec under wire-vocabulary names (#162).
+ *
+ * @param existing - Current search params (not mutated — a copy is returned).
+ * @param snapshot - The view state to write.
+ * @param defaults - Elision baseline, structurally the view's own defaults.
+ * @param axes - Axes to write; every other axis is left alone in `existing`.
+ * @param prefix - Key prefix, to namespace multiple synced tables on a page.
+ * @returns New `URLSearchParams` with the view applied.
+ * @throws TypeError when the snapshot is structurally invalid (write strict).
+ */
+export declare function applyViewToSearchParams(existing: URLSearchParams, snapshot: TableViewSnapshot, defaults: TableViewSnapshot, axes?: readonly TableViewAxis[], prefix?: string): URLSearchParams;

package/dist/table-view.js

@@ -0,0 +1,312 @@
+/**
+ * URL (de)serialization for the v8 table view vocabulary (`TableView` from
+ * `@urbicon-ui/table`: search, sort, page, pageSize, filters, groupBy).
+ *
+ * The types in this module are a **structural mirror** of the table package's
+ * view types — deliberately not imported, so this package carries no
+ * dependency on `@urbicon-ui/table`. A type-parity test over there guards the
+ * shapes against drift; `bindViewToUrl` accepts any object shaped like
+ * {@link TableViewLike}, which the real `TableView` is.
+ *
+ * The key scheme is the shipped one (`q`, `page`, `size`, `sort`, `dir`,
+ * `group`, `filter`) — deep links written for v7 keep parsing. The write
+ * side adds one compatible extension: an empty `filter=` marker, analogous
+ * to `sort=`, so a cleared filter set elides like every other axis (the
+ * shipped read side already tolerated it).
+ */
+/**
+ * Filter operators supported by the table. Mirrors `FilterOperator` from
+ * `@urbicon-ui/table`. Used as the runtime whitelist when parsing `filter`
+ * params from the URL.
+ */
+export const TABLE_VIEW_FILTER_OPERATORS = [
+    'contains',
+    'equals',
+    'startsWith',
+    'endsWith',
+    'greaterThan',
+    'lessThan'
+];
+/** All six view axes, in vocabulary order. */
+export const TABLE_VIEW_AXES = [
+    'search',
+    'sort',
+    'page',
+    'pageSize',
+    'filters',
+    'groupBy'
+];
+/** URL keys per axis, unprefixed — the §3.2 key scheme, grouped by owning axis. */
+const AXIS_KEYS = {
+    search: ['q'],
+    sort: ['sort', 'dir'],
+    page: ['page'],
+    pageSize: ['size'],
+    filters: ['filter'],
+    groupBy: ['group']
+};
+/** The URL keys a set of axes owns, with the configured prefix applied. */
+export function viewAxisKeys(axes, prefix = '') {
+    return axes.flatMap((axis) => AXIS_KEYS[axis].map((key) => `${prefix}${key}`));
+}
+function isFilterOperator(value) {
+    return TABLE_VIEW_FILTER_OPERATORS.includes(value);
+}
+/** Per-entry tolerance: a malformed entry becomes null and the caller skips it. */
+function parseFilterParam(raw) {
+    const parts = raw.split(':');
+    if (parts.length !== 3)
+        return null;
+    const [encodedColumn, operator, encodedValue] = parts;
+    if (!isFilterOperator(operator))
+        return null;
+    try {
+        const column = decodeURIComponent(encodedColumn);
+        if (!column)
+            return null;
+        return { column, operator, value: decodeURIComponent(encodedValue) };
+    }
+    catch {
+        return null;
+    }
+}
+/** The axes a URL names — presence only for params it actually carries. */
+export function viewAxesNamedBy(sp, prefix = '') {
+    const axes = [];
+    if (sp.get(`${prefix}q`) !== null)
+        axes.push('search');
+    if (sp.get(`${prefix}sort`) !== null)
+        axes.push('sort');
+    if (sp.get(`${prefix}page`) !== null)
+        axes.push('page');
+    if (sp.get(`${prefix}size`) !== null)
+        axes.push('pageSize');
+    if (sp.getAll(`${prefix}filter`).length > 0)
+        axes.push('filters');
+    if (sp.get(`${prefix}group`) !== null)
+        axes.push('groupBy');
+    return axes;
+}
+/**
+ * Parse search params into a **partial** view snapshot — a key per axis the
+ * URL actually carries, and nothing else. Read tolerant per key: an
+ * unparsable value on a *present* key falls back to the configured default
+ * for that axis (the key was present, so the axis stays claimed), and
+ * malformed filter entries are skipped individually.
+ */
+export function searchParamsToViewPartial(sp, defaults, prefix = '') {
+    const partial = {};
+    const rawSearch = sp.get(`${prefix}q`);
+    if (rawSearch !== null)
+        partial.search = rawSearch;
+    const rawSort = sp.get(`${prefix}sort`);
+    if (rawSort !== null) {
+        partial.sort =
+            rawSort === ''
+                ? null // `sort: null` — "unsorted" is a value, not a sentinel
+                : { column: rawSort, direction: sp.get(`${prefix}dir`) === 'desc' ? 'desc' : 'asc' };
+    }
+    const rawPage = sp.get(`${prefix}page`);
+    if (rawPage !== null && /^\d+$/.test(rawPage) && Number(rawPage) >= 1) {
+        partial.page = Number(rawPage);
+    }
+    else if (rawPage !== null) {
+        partial.page = defaults.page;
+    }
+    const rawSize = sp.get(`${prefix}size`);
+    if (rawSize !== null && /^\d+$/.test(rawSize) && Number(rawSize) >= 1) {
+        partial.pageSize = Number(rawSize);
+    }
+    else if (rawSize !== null) {
+        partial.pageSize = defaults.pageSize;
+    }
+    // `filter=` (empty marker) and `filter=a:contains:b` both claim the axis;
+    // the empty marker claims it as *empty* — the compatible format extension.
+    const rawFilters = sp.getAll(`${prefix}filter`);
+    if (rawFilters.length > 0) {
+        partial.filters = rawFilters
+            .map(parseFilterParam)
+            .filter((f) => f !== null);
+    }
+    const rawGroup = sp.get(`${prefix}group`);
+    if (rawGroup !== null)
+        partial.groupBy = rawGroup === '' ? null : rawGroup;
+    return partial;
+}
+/**
+ * Resolve a full view snapshot from search params: every axis the URL names
+ * comes from the URL, every other one from `defaults` — the same resolution
+ * the URL binding performs at init, for code that has no view (a server
+ * `load`).
+ *
+ * This is also what a server `load` hands its fetch. Since v9 the view and
+ * the query speak one vocabulary (#162), so there is nothing to project on
+ * the way out: the object below is the same shape a managed `source.query`
+ * receives. The `searchParamsToViewQuery` / `viewSnapshotToTableQuery` pair
+ * that used to do the projecting were identity functions once the names
+ * agreed, and are gone.
+ *
+ * The `defaults` argument is the point: it takes the very object
+ * `createTableView({ defaults })` takes, so the server cannot resolve an
+ * absent param differently from the client — and a default filter set is
+ * expressible, which the old wire-vocabulary baseline could not manage no
+ * matter how it was written (#157 finding 2).
+ *
+ * @example
+ * ```ts
+ * // shared with the component that calls createTableView({ defaults })
+ * export const invoiceView = { pageSize: 25, sort: { column: 'date', direction: 'desc' } };
+ *
+ * export const load = async ({ url }) => ({
+ *   initialResult: await fetchInvoices(searchParamsToViewSnapshot(url.searchParams, invoiceView))
+ * });
+ * ```
+ */
+export function searchParamsToViewSnapshot(sp, defaults = {}, prefix = '') {
+    const resolved = resolveViewDefaults(defaults);
+    return { ...resolved, ...searchParamsToViewPartial(sp, resolved, prefix) };
+}
+/**
+ * Fill an unset axis with the table's own default — never `undefined`
+ * anywhere.
+ *
+ * The two composite axes are copied for the same reason `TableView`'s
+ * constructor copies them: the documented `load` pattern shares ONE defaults
+ * object between the server and the component (a module-scope
+ * `export const invoiceView = …`). Handing a caller's array straight back out
+ * means a `load` that sorts or normalises the snapshot in place poisons that
+ * shared constant for every later request on the same server process.
+ */
+function resolveViewDefaults(defaults) {
+    return {
+        search: defaults.search ?? '',
+        sort: defaults.sort ? { ...defaults.sort } : null,
+        page: defaults.page ?? 1,
+        pageSize: defaults.pageSize ?? 10,
+        filters: defaults.filters ? [...defaults.filters] : [],
+        groupBy: defaults.groupBy || null
+    };
+}
+/**
+ * Serialize a snapshot, eliding every axis that equals the defaults — the
+ * elision baseline *is* the view's defaults, structurally. `axes` restricts
+ * the output to a binding's own axes: an unbound axis never reaches the URL,
+ * no matter what the view holds.
+ */
+export function viewSnapshotToSearchParams(snapshot, defaults, axes = TABLE_VIEW_AXES, prefix = '') {
+    const sp = new URLSearchParams();
+    const bound = (axis) => axes.includes(axis);
+    if (bound('search') && snapshot.search !== defaults.search)
+        sp.set(`${prefix}q`, snapshot.search);
+    if (bound('page') && snapshot.page !== defaults.page)
+        sp.set(`${prefix}page`, String(snapshot.page));
+    if (bound('pageSize') && snapshot.pageSize !== defaults.pageSize)
+        sp.set(`${prefix}size`, String(snapshot.pageSize));
+    // `bound('sort')` gates BOTH branches — gating only the null-mismatch one
+    // let an unbound sort leak into the URL (an operator-precedence slip the
+    // spike caught; pinned by the axis-subset test).
+    const sortDiffers = bound('sort') &&
+        ((snapshot.sort === null) !== (defaults.sort === null) ||
+            (snapshot.sort !== null &&
+                defaults.sort !== null &&
+                (snapshot.sort.column !== defaults.sort.column ||
+                    snapshot.sort.direction !== defaults.sort.direction)));
+    if (sortDiffers) {
+        if (snapshot.sort === null) {
+            sp.set(`${prefix}sort`, ''); // explicitly unsorted — only reachable when defaults sort
+        }
+        else {
+            sp.set(`${prefix}sort`, snapshot.sort.column);
+            if (snapshot.sort.direction === 'desc')
+                sp.set(`${prefix}dir`, 'desc');
+        }
+    }
+    if (bound('groupBy') && snapshot.groupBy !== defaults.groupBy)
+        sp.set(`${prefix}group`, snapshot.groupBy ?? '');
+    const filtersDiffer = bound('filters') &&
+        (snapshot.filters.length !== defaults.filters.length ||
+            snapshot.filters.some((f, i) => f.column !== defaults.filters[i].column ||
+                f.operator !== defaults.filters[i].operator ||
+                f.value !== defaults.filters[i].value));
+    if (filtersDiffer) {
+        if (snapshot.filters.length === 0) {
+            // The format extension: an empty marker, analogous to `sort=`, so a
+            // cleared filter set elides like every other axis.
+            sp.set(`${prefix}filter`, '');
+        }
+        else {
+            for (const filter of snapshot.filters) {
+                sp.append(`${prefix}filter`, `${encodeURIComponent(filter.column)}:${filter.operator}:${encodeURIComponent(filter.value)}`);
+            }
+        }
+    }
+    return sp;
+}
+/**
+ * Write-side validation: never serialize structurally invalid state.
+ *
+ * The strict half of the module's read-tolerant / write-strict contract, and
+ * deliberately NOT called by {@link viewSnapshotToSearchParams}: that one runs
+ * inside the URL binding on every view change, where a throw would take the
+ * whole table down over a `view.page = 0` a consumer wrote. Serializing a bad
+ * page there costs a wrong URL; throwing there costs the page.
+ *
+ * @throws TypeError when an axis holds a value the URL scheme cannot mean.
+ */
+export function assertValidViewSnapshot(snapshot) {
+    if (!Number.isSafeInteger(snapshot.page) || snapshot.page < 1) {
+        throw new TypeError(`[table-view] page must be a positive integer, got ${snapshot.page}`);
+    }
+    if (!Number.isSafeInteger(snapshot.pageSize) || snapshot.pageSize < 1) {
+        throw new TypeError(`[table-view] pageSize must be a positive integer, got ${snapshot.pageSize}`);
+    }
+    if (snapshot.sort !== null) {
+        if (!snapshot.sort.column) {
+            throw new TypeError('[table-view] sort.column must be a non-empty string, or sort must be null');
+        }
+        if (snapshot.sort.direction !== 'asc' && snapshot.sort.direction !== 'desc') {
+            throw new TypeError(`[table-view] sort.direction must be 'asc' or 'desc', got ${String(snapshot.sort.direction)}`);
+        }
+    }
+    if (snapshot.groupBy === '') {
+        throw new TypeError("[table-view] groupBy must be a non-empty string or null, got ''");
+    }
+    for (const filter of snapshot.filters) {
+        if (!filter.column) {
+            throw new TypeError('[table-view] filter.column must be a non-empty string');
+        }
+        if (!isFilterOperator(filter.operator)) {
+            throw new TypeError(`[table-view] unknown filter operator '${String(filter.operator)}' on column '${filter.column}'`);
+        }
+    }
+}
+/**
+ * Merge a view into existing search params: every key the given axes own is
+ * replaced by the serialized snapshot, and every other param is preserved
+ * untouched. Keys whose axis returned to its default are removed (the same
+ * elision {@link viewSnapshotToSearchParams} applies).
+ *
+ * This is the one thing the axis-scoped serializer cannot do on its own —
+ * everything else the retired `./table-query` module offered was the same
+ * codec under wire-vocabulary names (#162).
+ *
+ * @param existing - Current search params (not mutated — a copy is returned).
+ * @param snapshot - The view state to write.
+ * @param defaults - Elision baseline, structurally the view's own defaults.
+ * @param axes - Axes to write; every other axis is left alone in `existing`.
+ * @param prefix - Key prefix, to namespace multiple synced tables on a page.
+ * @returns New `URLSearchParams` with the view applied.
+ * @throws TypeError when the snapshot is structurally invalid (write strict).
+ */
+export function applyViewToSearchParams(existing, snapshot, defaults, axes = TABLE_VIEW_AXES, prefix = '') {
+    assertValidViewSnapshot(snapshot);
+    const serialized = viewSnapshotToSearchParams(snapshot, defaults, axes, prefix);
+    const next = new URLSearchParams(existing);
+    for (const key of viewAxisKeys(axes, prefix)) {
+        next.delete(key);
+    }
+    for (const [key, value] of serialized) {
+        next.append(key, value);
+    }
+    return next;
+}