@urbicon-ui/sveltekit-utils 7.0.1 → 8.1.0

package/dist/url.svelte.d.ts

@@ -1,4 +1,4 @@
-import { type TableQueryParams, type TableQueryUrlOptions, type TableQueryViewState } from './table-query.js';
+export { bindViewToUrl, type UrlViewBindingOptions } from './view-binding.svelte.js';
 /**
  * How {@link useUrlArrayParam} maps an array onto the URL:
  * - `repeat` — one entry per key: `?tag=a&tag=b`
@@ -134,103 +134,3 @@ export declare function useUrlArrayParam(key: string, opts: {
     strategy?: UrlArrayStrategy;
     delimiter?: string;
 }): readonly [() => string[], (next: string[]) => void];
-/** Options for {@link createTableQueryUrlSync}. */
-export interface TableQueryUrlSyncOptions extends TableQueryUrlOptions {
-    /**
-     * Replace the current history entry instead of pushing a new one. The
-     * default (`true`) keeps every sort/filter/page interaction from polluting
-     * the back button.
-     * @default true
-     */
-    replaceState?: boolean;
-}
-/**
- * Opt-in URL sync for a table: mirrors the `TableQuery` the table emits onto
- * `?q=…&sort=…&page=…` query params, so the view state survives reloads, can
- * be shared as a link, and — unlike `localStorage` — is visible to the server.
- * Works in client mode as well as server mode; the table emits its query in
- * both.
- *
- * Two directions, both explicit:
- * - **URL → query**: `viewState` carries the axes the URL actually names, and
- *   re-reads the URL on every navigation. Hand it to the table's `query` prop,
- *   which controls exactly those axes — per field, and ahead of both
- *   `persistenceConfig` and the `initial*` seeds. Because a controlled axis is
- *   a derived rather than a write, it resolves during server rendering too,
- *   which is the point: the server renders the view the link asked for instead
- *   of a default one the client swaps out on hydration.
- * - **query → URL**: pass `syncQuery` the query from `onQueryChange`, or call
- *   it inside `queryFn` (when `queryFn` is set, `onQueryChange` does not
- *   fire). It rewrites only its own — optionally prefixed — params via
- *   `goto` (`replaceState`, `noScroll`, `keepFocus`); unrelated params are
- *   preserved. Values equal to `options.defaults` are elided, so a table in
- *   its default state leaves the URL clean.
- *
- * Set `options.defaults` to the table's initial props (`itemsPerPage`,
- * `initialPage`, `initialGroupBy`) so the elision baseline matches the state
- * the table actually starts in.
- *
- * @example Client mode — the whole wiring is two props
- * ```svelte
- * <script lang="ts">
- *   import { Table } from '@urbicon-ui/table';
- *   import { createTableQueryUrlSync } from '@urbicon-ui/sveltekit-utils/url.svelte';
- *
- *   const sync = createTableQueryUrlSync({ defaults: { itemsPerPage: 25 } });
- * </script>
- *
- * <Table {items} {columns} query={sync.viewState} onQueryChange={sync.syncQuery} />
- * ```
- *
- * `query` is a *controlled* prop, which is what makes this work on the server:
- * the URL is parsed during SSR and the table renders the linked view rather
- * than an unfiltered one the client then replaces. It also outranks
- * `persistenceConfig` per axis, so there is no longer a caveat about a stored
- * value beating the link.
- *
- * Pass `viewState`, never `initialQuery`. `initialQuery` describes **every**
- * axis, so as a `query` value it claims every axis — including the ones the URL
- * says nothing about, whose values it filled in from the defaults. A table
- * wired that way ignores `persistenceConfig`, `initialSort`, `initialFilters`
- * and `initialGroupBy` entirely, on any URL, and says nothing about it.
- *
- * @example Server mode — the same two directions, with the fetch in between
- * ```svelte
- * <script lang="ts">
- *   const sync = createTableQueryUrlSync({ defaults: { itemsPerPage: 25 } });
- * </script>
- *
- * <Table
- *   mode="server"
- *   {columns}
- *   itemsPerPage={25}
- *   query={sync.viewState}
- *   queryFn={async (query, { signal }) => {
- *     sync.syncQuery(query);
- *     const res = await fetch(`/api/users?${new URLSearchParams(...)}`, { signal });
- *     const data = await res.json();
- *     return { items: data.results, totalItems: data.total };
- *   }}
- * />
- * ```
- *
- * @param options - Elision defaults, key prefix, history behaviour.
- * @returns `viewState` (the controlled axes, re-read on every navigation),
- *   `initialQuery` (a complete snapshot for a fetch) + `syncQuery` (write a
- *   query back to the URL).
- */
-export declare function createTableQueryUrlSync(options?: TableQueryUrlSyncOptions): {
-    /**
-     * The axes the URL names, re-read on every navigation.
-     *
-     * A getter, not a captured value: `createTableQueryUrlSync` runs once per
-     * page component, and SvelteKit does not remount that component when only
-     * the query string changes. A snapshot would therefore never see the back
-     * button — the table would stay sorted after the user navigated back to a
-     * URL with no sort param. Reading `page.url` here makes every consumer of
-     * this getter a reader of SvelteKit's own reactive page state.
-     */
-    readonly viewState: TableQueryViewState;
-    readonly initialQuery: TableQueryParams;
-    readonly syncQuery: (query: TableQueryParams) => void;
-};

package/dist/url.svelte.js

@@ -1,7 +1,15 @@
 import { building } from '$app/environment';
 import { goto } from '$app/navigation';
 import { page } from '$app/state';
-import { applyTableQueryToSearchParams, searchParamsToTableQuery, searchParamsToTableViewState } from './table-query.js';
+// The v8 view-object binding lives in its own module; re-exported here so the
+// documented import path (`@urbicon-ui/sveltekit-utils/url.svelte`) carries it.
+// The mirror types (TableViewLike, TableViewSnapshot, …) are exported from the
+// package root via `table-view` — not re-exported here, which would make the
+// root's star exports ambiguous and silently drop them. The v7
+// `createTableQueryUrlSync` factory is gone with the table's `query` prop —
+// the URL home of a table view is `bindViewToUrl`; the load-path serializers
+// (`searchParamsToViewSnapshot` & friends) live in `table-view`.
+export { bindViewToUrl } from './view-binding.svelte.js';
 /**
  * Low-level escape hatch to update several params at once via `goto` (without a
  * full navigation). Starts from the current URL, applies `next`, and keeps
@@ -175,112 +183,3 @@ export function useUrlArrayParam(key, opts) {
     };
     return useUrlParam(key, { parse, serialize, initial: opts.initial });
 }
-/**
- * Opt-in URL sync for a table: mirrors the `TableQuery` the table emits onto
- * `?q=…&sort=…&page=…` query params, so the view state survives reloads, can
- * be shared as a link, and — unlike `localStorage` — is visible to the server.
- * Works in client mode as well as server mode; the table emits its query in
- * both.
- *
- * Two directions, both explicit:
- * - **URL → query**: `viewState` carries the axes the URL actually names, and
- *   re-reads the URL on every navigation. Hand it to the table's `query` prop,
- *   which controls exactly those axes — per field, and ahead of both
- *   `persistenceConfig` and the `initial*` seeds. Because a controlled axis is
- *   a derived rather than a write, it resolves during server rendering too,
- *   which is the point: the server renders the view the link asked for instead
- *   of a default one the client swaps out on hydration.
- * - **query → URL**: pass `syncQuery` the query from `onQueryChange`, or call
- *   it inside `queryFn` (when `queryFn` is set, `onQueryChange` does not
- *   fire). It rewrites only its own — optionally prefixed — params via
- *   `goto` (`replaceState`, `noScroll`, `keepFocus`); unrelated params are
- *   preserved. Values equal to `options.defaults` are elided, so a table in
- *   its default state leaves the URL clean.
- *
- * Set `options.defaults` to the table's initial props (`itemsPerPage`,
- * `initialPage`, `initialGroupBy`) so the elision baseline matches the state
- * the table actually starts in.
- *
- * @example Client mode — the whole wiring is two props
- * ```svelte
- * <script lang="ts">
- *   import { Table } from '@urbicon-ui/table';
- *   import { createTableQueryUrlSync } from '@urbicon-ui/sveltekit-utils/url.svelte';
- *
- *   const sync = createTableQueryUrlSync({ defaults: { itemsPerPage: 25 } });
- * </script>
- *
- * <Table {items} {columns} query={sync.viewState} onQueryChange={sync.syncQuery} />
- * ```
- *
- * `query` is a *controlled* prop, which is what makes this work on the server:
- * the URL is parsed during SSR and the table renders the linked view rather
- * than an unfiltered one the client then replaces. It also outranks
- * `persistenceConfig` per axis, so there is no longer a caveat about a stored
- * value beating the link.
- *
- * Pass `viewState`, never `initialQuery`. `initialQuery` describes **every**
- * axis, so as a `query` value it claims every axis — including the ones the URL
- * says nothing about, whose values it filled in from the defaults. A table
- * wired that way ignores `persistenceConfig`, `initialSort`, `initialFilters`
- * and `initialGroupBy` entirely, on any URL, and says nothing about it.
- *
- * @example Server mode — the same two directions, with the fetch in between
- * ```svelte
- * <script lang="ts">
- *   const sync = createTableQueryUrlSync({ defaults: { itemsPerPage: 25 } });
- * </script>
- *
- * <Table
- *   mode="server"
- *   {columns}
- *   itemsPerPage={25}
- *   query={sync.viewState}
- *   queryFn={async (query, { signal }) => {
- *     sync.syncQuery(query);
- *     const res = await fetch(`/api/users?${new URLSearchParams(...)}`, { signal });
- *     const data = await res.json();
- *     return { items: data.results, totalItems: data.total };
- *   }}
- * />
- * ```
- *
- * @param options - Elision defaults, key prefix, history behaviour.
- * @returns `viewState` (the controlled axes, re-read on every navigation),
- *   `initialQuery` (a complete snapshot for a fetch) + `syncQuery` (write a
- *   query back to the URL).
- */
-export function createTableQueryUrlSync(options = {}) {
-    // Same prerender rule as `useUrlParam`: no query string exists while
-    // building, so both readers parse from empty params instead of throwing.
-    const currentParams = () => (building ? new URLSearchParams() : page.url.searchParams);
-    // Parsed once, on purpose — a snapshot to seed a fetch with, not a source of
-    // truth. `viewState` below is the one the table binds to.
-    const initialQuery = searchParamsToTableQuery(currentParams(), options);
-    function syncQuery(query) {
-        const next = applyTableQueryToSearchParams(page.url.searchParams, query, options);
-        const qs = next.toString();
-        goto(`${page.url.pathname}${qs ? `?${qs}` : ''}${page.url.hash}`, {
-            replaceState: options.replaceState ?? true,
-            noScroll: true,
-            keepFocus: true
-        });
-    }
-    return {
-        /**
-         * The axes the URL names, re-read on every navigation.
-         *
-         * A getter, not a captured value: `createTableQueryUrlSync` runs once per
-         * page component, and SvelteKit does not remount that component when only
-         * the query string changes. A snapshot would therefore never see the back
-         * button — the table would stay sorted after the user navigated back to a
-         * URL with no sort param. Reading `page.url` here makes every consumer of
-         * this getter a reader of SvelteKit's own reactive page state.
-         */
-        get viewState() {
-            return searchParamsToTableViewState(currentParams(), options);
-        },
-        initialQuery,
-        syncQuery
-    };
-}

package/dist/view-binding.svelte.d.ts

@@ -0,0 +1,73 @@
+import { type TableViewAxis, type TableViewLike } from './table-view.js';
+/**
+ * Reset the module-scope writer between tests. The writer's pending-set and
+ * memo are keyed to a page's navigation stream; a test runner reusing the
+ * module across tests would otherwise leak one test's in-flight markers into
+ * the next.
+ * @internal test-only — not part of the public API.
+ */
+export declare function __resetUrlWriterForTests(): void;
+/**
+ * Size of the writer's live-key registry — lets the SSR suite assert that
+ * the module-global registry does not grow across simulated server requests.
+ * @internal test-only — not part of the public API.
+ */
+export declare function __urlWriterLiveKeyCountForTests(): number;
+/** Options for {@link bindViewToUrl}. */
+export interface UrlViewBindingOptions {
+    /** Axes to bind. @default all six */
+    axes?: readonly TableViewAxis[];
+    /** Debounce for view → URL writes in ms. @default 300 */
+    debounceMs?: number;
+    /**
+     * Replace the current history entry instead of pushing a new one, so rapid
+     * sort/filter/page edits do not flood the back button.
+     *
+     * Decided for v8: this default covers **all** binding writes — v7
+     * continuity, keeping interactions from polluting the back button — and
+     * there is deliberately no per-interaction-type history mapping (a page
+     * turn pushing while a keystroke replaces); this one global option is the
+     * whole knob. Mirror-only writes (`reflectExternal`) always replace,
+     * whatever this is set to.
+     * @default true
+     */
+    replaceState?: boolean;
+    /**
+     * Key prefix (`prefix: 't_'` → `?t_q=…&t_page=…`) — namespace for a second
+     * bound table on the same page.
+     * @default ''
+     */
+    prefix?: string;
+    /**
+     * Whether *external* changes (a storage seed) are mirrored into the URL.
+     *
+     * - `false` (default): the address bar does not change without a reader
+     *   interaction — a restored "yesterday's view" stays out of the URL until
+     *   the reader's first edit, which then serializes the full snapshot.
+     * - `true`: an external application reaches the URL immediately, always
+     *   via `replaceState` (a mirror is not a reader action, so it never
+     *   mints a history entry) — the restored state becomes shareable without
+     *   an interaction.
+     * @default false
+     */
+    reflectExternal?: boolean;
+}
+/**
+ * Bind a view to the page URL. Call during component initialisation: the
+ * init half runs synchronously (SSR-safe — a `?sort=…` link renders sorted
+ * server HTML), the runtime halves are effects.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { Table, createTableView } from '@urbicon-ui/table';
+ *   import { bindViewToUrl } from '@urbicon-ui/sveltekit-utils/url.svelte';
+ *
+ *   const view = createTableView({ defaults: { pageSize: 25 } });
+ *   bindViewToUrl(view);
+ * </script>
+ *
+ * <Table {items} {columns} {view} />
+ * ```
+ */
+export declare function bindViewToUrl(view: TableViewLike, options?: UrlViewBindingOptions): void;

package/dist/view-binding.svelte.js

@@ -0,0 +1,365 @@
+/**
+ * The URL binding for the v8 table view object — the SvelteKit-bound half of
+ * the binding pair (`bindViewToStorage` lives in `@urbicon-ui/table`,
+ * kit-free). Decorates a view with the URL as its home: deep links apply at
+ * init (synchronously, during SSR too), navigations apply at runtime, and
+ * the reader's changes reach the URL debounced, with every axis that equals
+ * the view's defaults elided.
+ *
+ * Phase contract: defaults (constructor) → URL (init, synchronous) →
+ * storage (after hydration) → runtime (URL navigations apply; storage never
+ * applies again). At **init**, a missing param means *not claimed* — storage
+ * may seed the axis (the deep-link precedence URL > storage, the one moment
+ * presence matters). At **runtime**, a missing param on a bound axis means
+ * *apply the default* (the back-button contract).
+ *
+ * ## One URL writer per page
+ *
+ * All bindings share a module-scope, coalescing URL writer: jobs submitted
+ * in the same tick land in ONE `goto`, each job replacing only its own keys
+ * and preserving everything else. That is what makes two bindings (two
+ * tables with distinct `prefix`es) composable — every navigation carries
+ * both bindings' slices current, so neither ever sees a "foreign" URL from
+ * its sibling — and it is where the **self-navigation marker** lives: a
+ * landing URL the writer itself sent is not applied back onto the view, so
+ * a user edit made while the navigation was in flight survives instead of
+ * being overwritten by the landing (stale) URL — the measured lost-update
+ * window of the spike review.
+ */
+import { untrack } from 'svelte';
+import { browser, building } from '$app/environment';
+import { goto } from '$app/navigation';
+import { page } from '$app/state';
+import { searchParamsToViewPartial, TABLE_VIEW_AXES, viewAxesNamedBy, viewAxisKeys, viewSnapshotToSearchParams } from './table-view.js';
+/** Order-insensitive canonical form, for echo comparison only. */
+function canonical(sp) {
+    return [...sp.entries()]
+        .map(([k, v]) => `${k}=${v}`)
+        .sort()
+        .join('&');
+}
+/** The binding's own slice of a search string — foreign params excluded. */
+function ownSlice(search, keys) {
+    const all = new URLSearchParams(search);
+    const own = new URLSearchParams();
+    for (const key of keys) {
+        for (const value of all.getAll(key))
+            own.append(key, value);
+    }
+    return own;
+}
+/**
+ * The app-global coalescing URL writer (module scope — it outlives route
+ * changes). Safe on the server because every touch is browser-gated: flushes
+ * and teardowns live in effects and timer callbacks, which never run there,
+ * and registration is explicitly `browser`-gated in `bindViewToUrl` — an
+ * unconditional register leaked across requests (the map outlives the
+ * request, and only an effect teardown releases an entry), so request 2 of
+ * the same route threw the claims error below.
+ *
+ * While a navigation is in flight, `page.url` is stale — so the writer keeps
+ * `intendedSearch`, the last search string it sent, and uses it as BOTH the
+ * merge basis and the cancels-out comparison. Without it, a flush issued
+ * inside the in-flight window merged onto the stale URL: a revert during a
+ * slow navigation was swallowed as "cancels out" (permanent view↔URL
+ * divergence), and a sibling binding's slice was erased from the URL — the
+ * two red counter-examples of the adversarial review.
+ */
+const writer = {
+    jobs: [],
+    flushQueued: false,
+    /** Search strings sent via `goto` and not yet acknowledged by a landing. */
+    sentPending: new Set(),
+    /** The last sent search string — the true URL basis while anything is pending. */
+    intendedSearch: null,
+    /** Memoized verdict for the most recent landing, so every binding on the
+     *  page classifies one landing identically (the first query consumes the
+     *  `sentPending` entry, the rest read the memo). */
+    lastClassified: null,
+    /**
+     * The URL keys of every live url binding, by owner. Two prefixless
+     * bindings on two views would silently manage the same keys (last flush
+     * wins, a shared link loads the wrong table) — a key intersection at
+     * registration is a programming error, caught here because the writer is
+     * the one place that sees every binding on the page.
+     */
+    liveKeys: new Map(),
+    register(owner, keys) {
+        for (const [other, otherKeys] of this.liveKeys) {
+            if (other === owner)
+                continue;
+            const clash = keys.find((key) => otherKeys.includes(key));
+            if (clash) {
+                throw new Error(`[bindViewToUrl] two url bindings on this page manage the URL key "${clash}" — give one of them a \`prefix\`.`);
+            }
+        }
+        this.liveKeys.set(owner, keys);
+    },
+    unregister(owner) {
+        this.liveKeys.delete(owner);
+        // Withdraw unflushed jobs: a debounce that fired in the same task as the
+        // unmount must not navigate with the dead binding's params.
+        this.jobs = this.jobs.filter((job) => job.owner !== owner);
+    },
+    submit(job) {
+        this.jobs.push(job);
+        if (this.flushQueued)
+            return;
+        this.flushQueued = true;
+        queueMicrotask(() => this.flush());
+    },
+    flush() {
+        this.flushQueued = false;
+        if (this.jobs.length === 0)
+            return;
+        const jobs = this.jobs;
+        this.jobs = [];
+        const baseline = this.intendedSearch ?? page.url.search;
+        const next = new URLSearchParams(baseline);
+        let replaceState = true;
+        for (const job of jobs) {
+            for (const key of job.keys)
+                next.delete(key);
+            for (const [key, value] of job.params)
+                next.append(key, value);
+            replaceState &&= job.replaceState;
+        }
+        const qs = next.toString();
+        const search = qs ? `?${qs}` : '';
+        if (search === baseline)
+            return; // coalesced jobs cancelled out
+        this.sentPending.add(search);
+        this.intendedSearch = search;
+        void goto(`${page.url.pathname}${search}${page.url.hash}`, {
+            replaceState,
+            noScroll: true,
+            keepFocus: true
+        });
+    },
+    /**
+     * Classify a landing URL: did this writer send it? Consumes the pending
+     * entry on first query (so a later back-navigation to the same string is
+     * foreign, as it should be) and memoizes the verdict for the flush so
+     * every binding agrees. A foreign landing invalidates everything pending —
+     * SvelteKit has cancelled those navigations. When the *intended* (last
+     * sent) navigation lands, every older pending entry is cleared too: those
+     * navigations were superseded and will never land, and a stale entry
+     * would misclassify a later back-landing on the same string as self.
+     */
+    classify(search) {
+        if (this.lastClassified?.search === search) {
+            return this.lastClassified.self ? 'self' : 'foreign';
+        }
+        const self = this.sentPending.delete(search);
+        if (!self) {
+            this.sentPending.clear();
+            this.intendedSearch = null;
+        }
+        else if (search === this.intendedSearch) {
+            this.sentPending.clear();
+            this.intendedSearch = null;
+        }
+        this.lastClassified = { search, self };
+        return self ? 'self' : 'foreign';
+    }
+};
+/**
+ * Reset the module-scope writer between tests. The writer's pending-set and
+ * memo are keyed to a page's navigation stream; a test runner reusing the
+ * module across tests would otherwise leak one test's in-flight markers into
+ * the next.
+ * @internal test-only — not part of the public API.
+ */
+export function __resetUrlWriterForTests() {
+    writer.jobs = [];
+    writer.flushQueued = false;
+    writer.sentPending.clear();
+    writer.intendedSearch = null;
+    writer.lastClassified = null;
+    writer.liveKeys.clear();
+}
+/**
+ * Size of the writer's live-key registry — lets the SSR suite assert that
+ * the module-global registry does not grow across simulated server requests.
+ * @internal test-only — not part of the public API.
+ */
+export function __urlWriterLiveKeyCountForTests() {
+    return writer.liveKeys.size;
+}
+const zeroRevisions = () => ({
+    search: 0,
+    sort: 0,
+    page: 0,
+    pageSize: 0,
+    filters: 0,
+    groupBy: 0
+});
+/** Read exactly the bound axes through the view's getters — tracked. */
+function readAxes(view, axes) {
+    for (const axis of axes)
+        void view[axis];
+}
+/**
+ * Bind a view to the page URL. Call during component initialisation: the
+ * init half runs synchronously (SSR-safe — a `?sort=…` link renders sorted
+ * server HTML), the runtime halves are effects.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { Table, createTableView } from '@urbicon-ui/table';
+ *   import { bindViewToUrl } from '@urbicon-ui/sveltekit-utils/url.svelte';
+ *
+ *   const view = createTableView({ defaults: { pageSize: 25 } });
+ *   bindViewToUrl(view);
+ * </script>
+ *
+ * <Table {items} {columns} {view} />
+ * ```
+ */
+export function bindViewToUrl(view, options = {}) {
+    const axes = options.axes ?? TABLE_VIEW_AXES;
+    const debounceMs = options.debounceMs ?? 300;
+    const replaceState = options.replaceState ?? true;
+    const reflectExternal = options.reflectExternal ?? false;
+    const prefix = options.prefix ?? '';
+    const managedKeys = viewAxisKeys(axes, prefix);
+    /** Identity handle for the writer's job/key bookkeeping. */
+    const owner = {};
+    view.claimAxes('url', axes);
+    // The writer registry serves the CLIENT writer only. Registering during
+    // SSR would leak the request: the module-global map outlives the request
+    // and only the effect teardown below — which never runs on the server —
+    // releases an entry, so request 2 of the same route would throw the claims
+    // error (and disjoint routes would grow the map without bound). The
+    // fail-loud purpose — two prefixless bindings are a programming error —
+    // is fully preserved client-side, where the same page renders again.
+    if (browser)
+        writer.register(owner, managedKeys);
+    // ── Init phase: URL → view, synchronous. Absence means "not claimed" here
+    // (storage may seed the axis later) — the only moment presence matters.
+    // While prerendering there is no query string to read (SvelteKit forbids
+    // touching `url.searchParams`), so the defaults are the truth for that
+    // render; the client applies the real URL through the runtime effect.
+    const initialSearch = building ? '' : untrack(() => page.url.search);
+    if (!building) {
+        const initialParams = new URLSearchParams(initialSearch);
+        const named = viewAxesNamedBy(initialParams, prefix).filter((axis) => axes.includes(axis));
+        const initialPartial = searchParamsToViewPartial(initialParams, view.defaults, prefix);
+        const initApply = {};
+        for (const axis of named) {
+            initApply[axis] = initialPartial[axis];
+        }
+        view.applyExternal(initApply, 'external');
+        view.markInitApplied(named);
+    }
+    // ── Runtime: URL → view. From here on, absence on a *bound* axis means
+    // "apply the default" (the back-button contract). Guarded against the
+    // initial run so a storage seed applied between init and the first
+    // navigation is not flattened back to the defaults — the precise line
+    // where "init absence = unclaimed" turns into "runtime absence = default".
+    let lastSeenSearch = initialSearch;
+    $effect(() => {
+        const search = page.url.search;
+        if (search === lastSeenSearch)
+            return;
+        lastSeenSearch = search;
+        untrack(() => {
+            // The self-navigation marker: a landing the writer itself sent is not
+            // applied back. The view already holds this state — or a NEWER one,
+            // when the reader kept editing while the navigation was in flight, and
+            // applying the stale landing would overwrite their edit.
+            if (writer.classify(search) === 'self')
+                return;
+            lastSubmitted = null; // the URL basis changed under the binding
+            const params = new URLSearchParams(search);
+            const partial = searchParamsToViewPartial(params, view.defaults, prefix);
+            const full = {};
+            for (const axis of axes) {
+                full[axis] =
+                    partial[axis] !== undefined ? partial[axis] : view.defaults[axis];
+            }
+            view.applyExternal(full, 'external');
+        });
+    });
+    // ── Runtime: view → URL, debounced. Echo suppression compares only the
+    // binding's OWN key slice (canonicalised — key order in the URL is not the
+    // binding's to dictate), against the slice it last *submitted* while a
+    // navigation is in flight — comparing against the live URL there would
+    // re-send (and re-race) states the writer is already carrying.
+    const lastSeenRevision = zeroRevisions();
+    for (const axis of axes)
+        lastSeenRevision[axis] = untrack(() => view.originOf(axis).revision);
+    let lastSubmitted = null;
+    let timer = null;
+    const currentBaseline = () => lastSubmitted ?? canonical(ownSlice(page.url.search, managedKeys));
+    // Whether the pending debounce window saw a reader (or system) change, as
+    // opposed to a pure external mirror (`reflectExternal`): a storage seed
+    // reaching the URL must never mint a history entry the reader did not
+    // cause, so a mirror-only submission always replaces.
+    let pendingHasUserChange = false;
+    $effect(() => {
+        readAxes(view, axes); // track exactly the bound axes
+        untrack(() => {
+            let shouldMirror = reflectExternal;
+            let sawUserChange = false;
+            for (const axis of axes) {
+                const { revision, origin } = view.originOf(axis);
+                if (revision > lastSeenRevision[axis]) {
+                    lastSeenRevision[axis] = revision;
+                    // `system` mirrors too: the table cleaning a value may clean the
+                    // URL (virtualized × grouping). Only `external` (a binding
+                    // applying) stays silent.
+                    if (origin === 'user' || origin === 'system') {
+                        shouldMirror = true;
+                        sawUserChange = true;
+                    }
+                }
+            }
+            if (!shouldMirror)
+                return;
+            if (sawUserChange)
+                pendingHasUserChange = true;
+            const serialized = viewSnapshotToSearchParams(view.snapshot(), view.defaults, axes, prefix);
+            if (canonical(serialized) === currentBaseline())
+                return;
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(() => {
+                timer = null;
+                // Serialize from the *live* view — the debounce window may have seen
+                // further changes; the last state is the one worth navigating to.
+                const latest = viewSnapshotToSearchParams(view.snapshot(), view.defaults, axes, prefix);
+                const latestCanonical = canonical(latest);
+                const mirrorOnly = !pendingHasUserChange;
+                pendingHasUserChange = false;
+                if (latestCanonical === currentBaseline())
+                    return;
+                lastSubmitted = latestCanonical;
+                writer.submit({
+                    owner,
+                    keys: managedKeys,
+                    params: latest,
+                    replaceState: mirrorOnly ? true : replaceState
+                });
+            }, debounceMs);
+        });
+        // No per-run teardown — the timer must survive unrelated re-runs, or
+        // every keystroke would cancel the pending write.
+    });
+    // Destroy-only teardown: a dependency-free effect runs once; its teardown
+    // fires when the owning scope is destroyed. Without it, a pending debounce
+    // outlives the component and navigates with the dead table's params onto
+    // whatever page comes next — and the claims would block a remounting child
+    // (`{#if}`) on a longer-lived view from binding again.
+    $effect(() => {
+        return () => {
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            view.releaseAxes('url', axes);
+            writer.unregister(owner);
+        };
+    });
+}