@trackunit/react-components 3.8.2 → 3.8.3-alpha-e1e6a0f33ce.0

package/index.esm.js

@@ -13480,6 +13480,90 @@ const useSessionStorage = (options) => useWebStorage(globalThis.sessionStorage,
  */
 const useSessionStorageReducer = (options) => useWebStorageReducer(globalThis.sessionStorage, options);
 
+/**
+ * Pure utilities for stamping a URL-persisted value with the identity that
+ * wrote it.
+ *
+ * A URL (hash or search param) is shared by every account that uses the same
+ * browser: it survives login redirects, history and bookmarks, and it takes
+ * precedence over per-user localStorage when a page loads. Without a stamp
+ * there is no way to tell "a colleague shared this link" from "the previous
+ * account on this PC left its layout in the address bar" — and the second
+ * case silently replaces the current user's saved state (GLU-2396).
+ *
+ * The stamp is a short, non-reversible fingerprint of `clientSideUserId`.
+ * It is not a secret and not a security boundary; it only lets a reader
+ * recognise a value written by a *different* identity on the same device.
+ */
+/**
+ * Wire shape of a stamped URL value: `{ o: <fingerprint>, v: <payload> }`.
+ * Values written before stamping existed are bare payloads and decode as
+ * unowned (see {@link unwrapUrlOwner}).
+ */
+const stampedUrlValueSchema = z.object({
+    o: z.string(),
+    v: z.unknown(),
+});
+const FNV_OFFSET_BASIS = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+/**
+ * 32-bit FNV-1a of `identity`, rendered in base36 (≤ 7 chars).
+ *
+ * Synchronous and dependency-free so it can run inside a `useState`
+ * initializer. Collisions are possible in theory but irrelevant here: a
+ * collision can only make a foreign value look like the reader's own, which
+ * is today's behaviour for every value.
+ *
+ * @param identity - The client-side user id to fingerprint.
+ * @returns {string} A short stable fingerprint of `identity`.
+ */
+const identityFingerprint = (identity) => {
+    let hash = FNV_OFFSET_BASIS;
+    for (let index = 0; index < identity.length; index++) {
+        hash ^= identity.charCodeAt(index);
+        hash = Math.imul(hash, FNV_PRIME) >>> 0;
+    }
+    return hash.toString(36);
+};
+/**
+ * Wraps a URL payload with the fingerprint of the identity writing it.
+ *
+ * @param value - The payload that would otherwise be encoded into the URL.
+ * @param owner - Fingerprint of the writing identity (see {@link identityFingerprint}).
+ * @returns {StampedUrlValue} The payload wrapped in its ownership envelope.
+ */
+const wrapUrlOwner = (value, owner) => ({ o: owner, v: value });
+/**
+ * Splits a decoded URL value into its owner fingerprint and payload.
+ * Bare (pre-stamping) payloads come back with `owner: undefined`.
+ *
+ * @param decoded - The decoded URL value, stamped or bare.
+ * @returns {{ owner: string | undefined; value: unknown }} The owner fingerprint (if any) and the payload.
+ */
+const unwrapUrlOwner = (decoded) => {
+    const stamped = stampedUrlValueSchema.safeParse(decoded);
+    // `z.unknown()` accepts a missing key, so `{ o: "x" }` parses without `v`.
+    // Such an object is a payload of its own, not an envelope; the `in` check
+    // is what keeps it unowned. Do not remove it as redundant.
+    return stamped.success && "v" in stamped.data
+        ? { owner: stamped.data.o, value: stamped.data.v }
+        : { owner: undefined, value: decoded };
+};
+
+/**
+ * Generates a localStorage key, optionally scoped to a specific user.
+ *
+ * When `userId` is provided the key is `"key-userId"`.
+ * When omitted the key is returned as-is (unscoped).
+ *
+ * @param key - Unique persistence identifier.
+ * @param userId - Client-side user id to scope storage per user.
+ * @returns {string} The combined storage key.
+ */
+const useStorageKey = (key, userId) => {
+    return useMemo(() => (userId ? `${key}-${userId}` : key), [key, userId]);
+};
+
 /**
  * Pure utilities for reading and writing single named entries inside a URL
  * fragment (the part after `#`).
@@ -13608,183 +13692,6 @@ const writeHashKey = (hash, key, value) => {
     return formatHash(next.join(TOKEN_SEPARATOR));
 };
 
-/**
- * Default maximum length of the resulting URL fragment after adding one
- * persisted entry. Oversized new entries are skipped; oversized replacements
- * remove the stale entry so localStorage remains authoritative.
- *
- * The fragment is never sent to the server, so it is not subject to the
- * AWS WAF managed-rule `SizeRestrictions_QUERYSTRING` cap that applies to
- * search params (5000 bytes). 64 KB stays well below typical browser URL
- * limits (Chromium ≳ 100 KB, Firefox ≳ 64 KB on the address bar) while
- * still leaving generous headroom for any realistic table state.
- */
-const MAX_HASH_LENGTH = 64 * 1024;
-/**
- * Syncs an encoded string value with a single named entry inside the URL
- * fragment (`location.hash`) via Tanstack Router.
- *
- * Behaviour mirrors `useSearchParamSync`, with two differences:
- *  - Reads from and writes to `location.hash` instead of `location.search`.
- *  - Oversized replacements remove stale values using
- *    {@link MAX_HASH_LENGTH}, rather than the AWS-WAF-driven search-param cap.
- *
- * The fragment is treated as a sequence of `&`-separated tokens via the
- * pure utilities in `./hashFragment`. Foreign tokens (bare anchors, other
- * named entries) are preserved byte-for-byte on every write.
- *
- * @param options - Configuration for the hash entry sync.
- * @param options.key - The named entry inside the fragment.
- * @param options.enabled - Set to `false` to disable all URL interaction (default `true`).
- * @param options.onExternalChange - Called when the entry changes externally
- *   (e.g. browser back/forward, pasted link, foreign router push).
- * @param options.replace - `true` to always use `replaceState` instead of pushState.
- */
-const useHashParamSync = ({ key, enabled = true, onExternalChange, replace: replaceOption, }) => {
-    const navigate = useNavigate();
-    const location = useLocation();
-    const router = useRouter();
-    const lastWrittenRef = useRef(undefined);
-    const pendingWriteRef = useRef(null);
-    const onExternalChangeRef = useRef(onExternalChange);
-    useEffect(() => {
-        onExternalChangeRef.current = onExternalChange;
-    }, [onExternalChange]);
-    const currentHashValue = useMemo(() => {
-        if (!enabled) {
-            return undefined;
-        }
-        return readHashKey(location.hash, key);
-    }, [enabled, location.hash, key]);
-    useEffect(() => {
-        if (!enabled) {
-            return;
-        }
-        if (currentHashValue === undefined) {
-            return;
-        }
-        if (currentHashValue === lastWrittenRef.current) {
-            return;
-        }
-        if (lastWrittenRef.current === undefined) {
-            return;
-        }
-        // A caller may have primed `lastWrittenRef` via `updateHashParam` while the
-        // URL still carries the previous value (queued rAF / router pending). Treating
-        // that stale URL as an external change reloads filter state from persistence
-        // and can clear in-progress search input before the write lands.
-        if (pendingWriteRef.current !== null) {
-            return;
-        }
-        requestAnimationFrame(() => {
-            onExternalChangeRef.current?.();
-        });
-    }, [currentHashValue, enabled]);
-    // Writes are dispatched via a "pending write" queue rather than calling
-    // `navigate` directly from inside the rAF callback. Tanstack Router's
-    // `router.state.status === "pending"` is common during the first paint
-    // of a route (loaders, suspense), and an earlier implementation that
-    // simply returned in that case lost the write outright. A one-shot write
-    // (a legacy search-param migrated into the hash, or the first edit)
-    // would otherwise never land.
-    //
-    // The queue + retry pattern below makes writes reliable:
-    //  - `updateHashParam` stores the latest attempted write in
-    //    `pendingWriteRef` and schedules an rAF flush.
-    //  - `flushPendingWrite` only navigates when the router is idle; while
-    //    pending it leaves the write queued so it can fire later.
-    //  - A dedicated effect watches `router.state.status` and re-attempts
-    //    the flush whenever the router settles, draining the queue.
-    const flushPendingWrite = useCallback(() => {
-        const pending = pendingWriteRef.current;
-        if (pending === null) {
-            return;
-        }
-        if (router.state.status === "pending") {
-            // Keep the write queued; the status-watcher effect below will retry
-            // when the router transitions back to idle.
-            return;
-        }
-        pendingWriteRef.current = null;
-        const { encodedValue, options } = pending;
-        let nextHash = writeHashKey(location.hash, key, encodedValue);
-        let removedOversizedValue = false;
-        if (nextHash.length > MAX_HASH_LENGTH) {
-            if (currentHashValue === undefined) {
-                return;
-            }
-            nextHash = writeHashKey(location.hash, key, undefined);
-            removedOversizedValue = true;
-        }
-        const shouldReplace = removedOversizedValue
-            ? true
-            : (options?.replace ?? replaceOption ?? !Boolean(currentHashValue));
-        // Tanstack Router's `navigate({ hash })` expects the fragment body
-        // *without* the leading `#` — the router adds the delimiter itself
-        // when serialising the URL. Forwarding the `#`-prefixed value from
-        // `writeHashKey` produces a doubled `##` in the address bar
-        // (visually broken, even though browsers still parse the fragment
-        // correctly because URL fragments start at the *first* `#`).
-        const navigateHash = nextHash.startsWith("#") ? nextHash.slice(1) : nextHash;
-        void navigate({
-            to: ".",
-            // Returning the same `prev` reference leaves the search params
-            // unchanged. We must still pass `search` so router types are happy.
-            search: (prev) => prev,
-            hash: navigateHash,
-            replace: shouldReplace,
-        });
-    }, [router.state.status, location.hash, key, currentHashValue, navigate, replaceOption]);
-    useEffect(() => {
-        if (router.state.status === "pending") {
-            return;
-        }
-        if (pendingWriteRef.current === null) {
-            return;
-        }
-        flushPendingWrite();
-    }, [router.state.status, flushPendingWrite]);
-    // Drop any queued write when the consumer unmounts. The queue + retry
-    // pattern above keeps writes pending across a `router.state.status ===
-    // "pending"` phase, which means a write scheduled just before a route
-    // change could otherwise drain onto the *next* route once it settles.
-    // Cancelling here preserves the original "writes are scoped to the
-    // owning route" contract that the pre-queue implementation got for
-    // free by dropping the write outright.
-    useEffect(() => () => {
-        pendingWriteRef.current = null;
-    }, []);
-    const updateHashParam = useCallback((encodedValue, options) => {
-        if (!enabled) {
-            return;
-        }
-        // Dedupe against either the last *committed* write or the value
-        // currently queued for the next rAF. Both represent the caller's
-        // intent so we don't schedule redundant rAF callbacks for identical
-        // requests.
-        const inFlightOrLastWritten = pendingWriteRef.current?.encodedValue ?? lastWrittenRef.current;
-        if (encodedValue !== undefined && encodedValue === inFlightOrLastWritten) {
-            return;
-        }
-        // Prime `lastWrittenRef` here (not inside `flushPendingWrite`) so
-        // the external-change detector treats this value as the caller's
-        // authoritative state even when the flush is a no-op (URL already
-        // matches) or stays queued during a pending router phase. Without
-        // priming, the next "external" change would look identical to the
-        // initial render (`lastWrittenRef === undefined`) and the callback
-        // would be skipped.
-        lastWrittenRef.current = encodedValue;
-        if (currentHashValue === encodedValue) {
-            return;
-        }
-        pendingWriteRef.current = { encodedValue, options };
-        requestAnimationFrame(() => {
-            flushPendingWrite();
-        });
-    }, [enabled, currentHashValue, flushPendingWrite]);
-    return useMemo(() => ({ searchValue: currentHashValue, updateSearchParam: updateHashParam }), [currentHashValue, updateHashParam]);
-};
-
 const searchRecordSchema = z.record(z.string(), z.unknown());
 const primitiveSearchValueSchema = z.union([z.string(), z.number(), z.boolean()]);
 /**
@@ -13807,373 +13714,187 @@ const readPrimitiveSearchParam = (search, key) => {
 };
 
 /**
- * Pure utilities for stamping a URL-persisted value with the identity that
- * wrote it.
- *
- * A URL (hash or search param) is shared by every account that uses the same
- * browser: it survives login redirects, history and bookmarks, and it takes
- * precedence over per-user localStorage when a page loads. Without a stamp
- * there is no way to tell "a colleague shared this link" from "the previous
- * account on this PC left its layout in the address bar" — and the second
- * case silently replaces the current user's saved state (GLU-2396).
- *
- * The stamp is a short, non-reversible fingerprint of `clientSideUserId`.
- * It is not a secret and not a security boundary; it only lets a reader
- * recognise a value written by a *different* identity on the same device.
- */
-/**
- * Wire shape of a stamped URL value: `{ o: <fingerprint>, v: <payload> }`.
- * Values written before stamping existed are bare payloads and decode as
- * unowned (see {@link unwrapUrlOwner}).
- */
-const stampedUrlValueSchema = z.object({
-    o: z.string(),
-    v: z.unknown(),
-});
-const FNV_OFFSET_BASIS = 0x811c9dc5;
-const FNV_PRIME = 0x01000193;
-/**
- * 32-bit FNV-1a of `identity`, rendered in base36 (≤ 7 chars).
- *
- * Synchronous and dependency-free so it can run inside a `useState`
- * initializer. Collisions are possible in theory but irrelevant here: a
- * collision can only make a foreign value look like the reader's own, which
- * is today's behaviour for every value.
- *
- * @param identity - The client-side user id to fingerprint.
- * @returns {string} A short stable fingerprint of `identity`.
- */
-const identityFingerprint = (identity) => {
-    let hash = FNV_OFFSET_BASIS;
-    for (let index = 0; index < identity.length; index++) {
-        hash ^= identity.charCodeAt(index);
-        hash = Math.imul(hash, FNV_PRIME) >>> 0;
-    }
-    return hash.toString(36);
-};
-/**
- * Wraps a URL payload with the fingerprint of the identity writing it.
- *
- * @param value - The payload that would otherwise be encoded into the URL.
- * @param owner - Fingerprint of the writing identity (see {@link identityFingerprint}).
- * @returns {StampedUrlValue} The payload wrapped in its ownership envelope.
- */
-const wrapUrlOwner = (value, owner) => ({ o: owner, v: value });
-/**
- * Splits a decoded URL value into its owner fingerprint and payload.
- * Bare (pre-stamping) payloads come back with `owner: undefined`.
- *
- * @param decoded - The decoded URL value, stamped or bare.
- * @returns {{ owner: string | undefined; value: unknown }} The owner fingerprint (if any) and the payload.
- */
-const unwrapUrlOwner = (decoded) => {
-    const stamped = stampedUrlValueSchema.safeParse(decoded);
-    // `z.unknown()` accepts a missing key, so `{ o: "x" }` parses without `v`.
-    // Such an object is a payload of its own, not an envelope; the `in` check
-    // is what keeps it unowned. Do not remove it as redundant.
-    return stamped.success && "v" in stamped.data
-        ? { owner: stamped.data.o, value: stamped.data.v }
-        : { owner: undefined, value: decoded };
-};
-
-/**
- * One-shot migration: if the URL still carries a legacy `?<key>=...`
- * search param from before this hook moved table-style state to the
- * fragment, decode it, hand it to the caller via `onMigrated`, then strip
- * the search param via a `replace` navigation so back/forward history
- * isn't polluted.
- *
- * Invariants:
- *  - The strip navigation fires at most once per mount (guarded by
- *    `hasStrippedRef`) so we don't loop on the navigation we ourselves
- *    triggered.
- *  - `onMigrated` is also fired at most once per mount (guarded by
- *    `hasMigratedRef`), but its gating is independent of the strip:
- *    if `hashAlreadyHasValue` flips `true → false` after the strip
- *    (e.g. an external actor clears the canonical hash mid-mount), the
- *    next render still gets a chance to migrate the legacy value into
- *    the hash. Conflating the two flags would have permanently lost
- *    the legacy state in that race.
- *  - Never throws — a decode/validate failure silently drops the value
- *    and still strips the search param. The legacy key is owned by this
- *    codebase's persistence convention (camelCase + `Tp` suffix), so
- *    stripping unparseable values cannot destroy third-party data.
- *  - When `hashAlreadyHasValue` is `true` the hash wins: the search
- *    param is stripped but `onMigrated` is not fired.
- *  - The `location.hash` is preserved verbatim across the strip
- *    navigation so any concurrent hash content (including a freshly
- *    written value) survives the cleanup.
- */
-const useMigrateLegacySearchParam = ({ key, enabled, decode, fromUrlValue, validate, hashAlreadyHasValue, onMigrated, }) => {
-    const navigate = useNavigate();
-    const location = useLocation();
-    const search = useSearch({ strict: false, shouldThrow: false });
-    // The three flags are tracked independently because they describe
-    // distinct side effects with distinct lifetimes:
-    //
-    //  - `hasStrippedRef` guards the cleanup navigation against looping
-    //    on the navigation we ourselves triggered.
-    //  - `hasMigratedRef` guards `onMigrated` against being called twice
-    //    with the same legacy value.
-    //  - `cachedRawValueRef` snapshots the legacy raw string the first
-    //    time we observe it. The strip navigation below removes the
-    //    value from `search` on the next render, so without a cache we
-    //    can never migrate it later. This matters in one specific edge
-    //    case: `hashAlreadyHasValue` is `true` on the first render (so
-    //    we skip `onMigrated` and just strip), then later flips to
-    //    `false` because another actor cleared the canonical hash. With
-    //    the cache the next render can still surface the legacy value.
-    //
-    // The previous implementation conflated all of this into a single
-    // `hasRunRef`, which permanently lost the legacy state in that race.
-    const hasStrippedRef = useRef(false);
-    const hasMigratedRef = useRef(false);
-    const cachedRawValueRef = useRef(undefined);
-    const decodeRef = useRef(decode);
-    const fromUrlValueRef = useRef(fromUrlValue);
-    const validateRef = useRef(validate);
-    const onMigratedRef = useRef(onMigrated);
-    useEffect(() => {
-        decodeRef.current = decode;
-        fromUrlValueRef.current = fromUrlValue;
-        validateRef.current = validate;
-        onMigratedRef.current = onMigrated;
-    }, [decode, fromUrlValue, validate, onMigrated]);
-    useEffect(() => {
-        if (!enabled) {
-            return;
-        }
-        if (hasStrippedRef.current && hasMigratedRef.current) {
-            return;
-        }
-        // Snapshot the raw value the first time we see it. After the strip
-        // navigation below, `search?.[key]` is undefined, but a later
-        // render that flips `hashAlreadyHasValue` back to `false` still
-        // needs the original value to migrate.
-        if (cachedRawValueRef.current === undefined) {
-            cachedRawValueRef.current = readPrimitiveSearchParam(search, key);
-        }
-        const rawString = cachedRawValueRef.current;
-        if (rawString === undefined) {
-            // Nothing legacy to migrate yet. Don't flip either flag — the
-            // param may appear on a later render (e.g. router still hydrating).
-            return;
-        }
-        if (!hasMigratedRef.current && !hashAlreadyHasValue) {
-            let migratedState;
-            try {
-                const decoded = decodeRef.current(rawString);
-                const transformed = fromUrlValueRef.current ? fromUrlValueRef.current(decoded) : decoded;
-                migratedState = validateRef.current(transformed);
-            }
-            catch {
-                migratedState = undefined;
-            }
-            // Invalid legacy data is silently dropped: the search param is
-            // still stripped below, so the URL stays clean. Surfacing a
-            // console warning here would require disabling a lint rule, and
-            // the data loss is bounded — localStorage holds the working state
-            // for the current session, and the user's next interaction
-            // repopulates the hash. We still flip the flag in the invalid
-            // case so we don't burn cycles re-decoding the same bad string
-            // on every render.
-            hasMigratedRef.current = true;
-            if (migratedState !== undefined) {
-                onMigratedRef.current(migratedState);
-            }
-        }
-        if (!hasStrippedRef.current) {
-            hasStrippedRef.current = true;
-            void navigate({
-                to: ".",
-                search: (prev) => ({ ...prev, [key]: undefined }),
-                hash: location.hash,
-                replace: true,
-            });
-        }
-    }, [enabled, key, hashAlreadyHasValue, search, navigate, location.hash]);
-};
-
-/**
- * Default maximum full URL length after adding one persisted search param
- * before the URL write is skipped (localStorage still persists the full state).
+ * Maximum full URL length after adding one persisted search param before the
+ * URL write is skipped (localStorage still persists the full state).
  *
  * Sized to stay safely below the AWS WAF managed-rule default
- * `SizeRestrictions_QUERYSTRING` cap of 5000 bytes for the entire url host + path + query + hash string
+ * `SizeRestrictions_QUERYSTRING` cap of 5000 bytes for the entire
+ * host + path + query + hash string.
  */
 const MAX_URL_LENGTH = 5000;
 /**
- * Syncs an encoded string value with a URL search parameter via Tanstack Router.
+ * Maximum length of the URL fragment after adding one persisted entry.
+ * Oversized new entries are skipped; oversized replacements remove the stale
+ * entry so localStorage remains authoritative.
  *
- * Provides a write function that updates the URL through the application
- * router (preserving other search params), guards against exceeding
- * {@link MAX_URL_LENGTH}, and detects external URL changes (browser
- * back/forward, shared links) via an optional callback.
- *
- * @param options - Configuration for the search param sync.
- * @param options.key - The URL search parameter name.
+ * The fragment is never sent to the server, so the WAF cap above does not
+ * apply. 64 KB stays well below typical browser URL limits (Chromium ≳ 100 KB,
+ * Firefox ≳ 64 KB on the address bar) while leaving generous headroom for any
+ * realistic table state.
+ */
+const MAX_HASH_LENGTH = 64 * 1024;
+/**
+ * Syncs an encoded string value with a single named entry in the URL — either
+ * a search param or an entry inside the hash fragment — via Tanstack Router.
+ *
+ * Writes go through the application router so other search params and
+ * foreign fragment content are preserved. Each slot has a size guard
+ * ({@link MAX_URL_LENGTH} for search, {@link MAX_HASH_LENGTH} for hash); an
+ * oversized value is dropped from the URL and localStorage stays
+ * authoritative. External changes to the entry (browser back/forward, a
+ * pasted link, a foreign router push) fire `onExternalChange`.
+ *
+ * Writes are dispatched via a pending-write queue rather than calling
+ * `navigate` directly. Tanstack Router's `router.state.status === "pending"`
+ * is common during the first paint of a route (loaders, suspense), and an
+ * implementation that simply returned in that case lost the write outright.
+ * `updateSearchParam` stores the latest attempted write and schedules an rAF
+ * flush; the flush only navigates when the router is idle, and an effect
+ * retries whenever the router settles. A queued write is dropped on unmount so
+ * it cannot drain onto the next route.
+ *
+ * @param options - Configuration for the URL entry sync.
+ * @param options.key - The search param name or fragment entry name.
+ * @param options.location - `"search"` or `"hash"`.
  * @param options.enabled - Set to `false` to disable all URL interaction (default `true`).
- * @param options.onExternalChange - Called when the param changes externally.
- * @param options.replace - `true` to always use `replaceState`.
+ * @param options.onExternalChange - Called when the entry changes externally.
+ * @param options.replace - `true` to always use `replaceState`; `false` to always push.
+ *   Default: replace when the entry is being added, push when it already has a value.
  */
-const useSearchParamSync = ({ key, enabled = true, onExternalChange, replace: replaceOption, }) => {
+const useUrlParamSync = ({ key, location: urlLocation, enabled = true, onExternalChange, replace: replaceOption, }) => {
     const navigate = useNavigate();
     const location = useLocation();
     const router = useRouter();
     const search = useSearch({ strict: false, shouldThrow: false });
+    const isHash = urlLocation === "hash";
     const lastWrittenRef = useRef(undefined);
     const pendingWriteRef = useRef(null);
     const onExternalChangeRef = useRef(onExternalChange);
     useEffect(() => {
         onExternalChangeRef.current = onExternalChange;
     }, [onExternalChange]);
-    const currentSearchValue = useMemo(() => {
+    const currentValue = useMemo(() => {
         if (!enabled) {
             return undefined;
         }
-        return readPrimitiveSearchParam(search, key);
-    }, [enabled, search, key]);
+        return isHash ? readHashKey(location.hash, key) : readPrimitiveSearchParam(search, key);
+    }, [enabled, isHash, location.hash, search, key]);
     useEffect(() => {
-        if (!enabled) {
+        if (!enabled || currentValue === undefined) {
             return;
         }
-        if (currentSearchValue === undefined) {
+        if (currentValue === lastWrittenRef.current || lastWrittenRef.current === undefined) {
             return;
         }
-        if (currentSearchValue === lastWrittenRef.current) {
-            return;
-        }
-        if (lastWrittenRef.current === undefined) {
-            return;
-        }
-        // A caller may have primed `lastWrittenRef` via `updateSearchParam` while the
-        // URL still carries the previous value (queued rAF / router pending). Treating
-        // that stale URL as an external change reloads filter state from persistence
-        // and can clear in-progress search input before the write lands.
+        // A caller may have primed `lastWrittenRef` via `updateSearchParam` while
+        // the URL still carries the previous value (queued rAF / router pending).
+        // Treating that stale URL as an external change would reload state from
+        // persistence before the write lands.
         if (pendingWriteRef.current !== null) {
             return;
         }
         requestAnimationFrame(() => {
             onExternalChangeRef.current?.();
         });
-    }, [currentSearchValue, enabled]);
-    const getUrlLengthWithSearchParam = useCallback((paramKey, paramValue, params) => {
+    }, [currentValue, enabled]);
+    // Read through refs so the write path does not change identity on every
+    // navigation; it only needs the location and current value at the moment it
+    // flushes, which may be an animation frame after it was queued.
+    const locationRef = useRef(location);
+    const currentValueRef = useRef(currentValue);
+    useEffect(() => {
+        locationRef.current = location;
+        currentValueRef.current = currentValue;
+    }, [location, currentValue]);
+    const getUrlLengthWithSearchParam = useCallback((paramValue, params) => {
+        const { href, searchStr, hash } = locationRef.current;
         const otherParamsLength = objectKeys(params)
-            .filter(k => k !== paramKey)
+            .filter(k => k !== key)
             .reduce((totalLength, k) => {
             const kLen = encodeURIComponent(String(k)).length;
             const v = params[k];
             const vLen = v !== null && v !== undefined ? encodeURIComponent(String(v)).length : 0;
             return totalLength + kLen + vLen + (totalLength > 0 ? 2 : 1);
         }, 0);
-        const urlBase = location.href.length - (location.searchStr.length || 0) + (location.hash.length || 0);
-        return urlBase + otherParamsLength + 1 + paramKey.length + 1 + paramValue.length;
-    }, [location]);
-    // Writes are dispatched via a "pending write" queue rather than calling
-    // `navigate` directly from inside the rAF callback. See the matching
-    // comment block in `useHashParamSync` for the full rationale — in short,
-    // navigating while `router.state.status === "pending"` was previously
-    // dropped silently, which lost a one-shot write (a legacy search param
-    // migrated into the URL, or the first edit) on routes that mount during
-    // a loader-driven pending phase.
+        const urlBase = href.length - (searchStr.length || 0) + (hash.length || 0);
+        return urlBase + otherParamsLength + 1 + key.length + 1 + paramValue.length;
+    }, [key]);
     const flushPendingWrite = useCallback(() => {
         const pending = pendingWriteRef.current;
         if (pending === null) {
             return;
         }
         if (router.state.status === "pending") {
-            // Keep the write queued; the status-watcher effect below retries on
-            // the next idle transition.
+            // Keep the write queued; the status-watcher effect retries once idle.
             return;
         }
         pendingWriteRef.current = null;
-        const { encodedValue, options } = pending;
-        const shouldReplace = options?.replace ?? replaceOption ?? !Boolean(currentSearchValue);
+        const { encodedValue } = pending;
+        const { hash } = locationRef.current;
+        const valueInUrl = currentValueRef.current;
+        const shouldReplace = replaceOption ?? !Boolean(valueInUrl);
+        if (!isHash) {
+            void navigate({
+                to: ".",
+                search: (prev) => getUrlLengthWithSearchParam(encodedValue ?? "", prev) <= MAX_URL_LENGTH
+                    ? { ...prev, [key]: encodedValue }
+                    : { ...prev, [key]: undefined },
+                hash,
+                replace: shouldReplace,
+            });
+            return;
+        }
+        let nextHash = writeHashKey(hash, key, encodedValue);
+        let removedOversizedValue = false;
+        if (nextHash.length > MAX_HASH_LENGTH) {
+            if (valueInUrl === undefined) {
+                return;
+            }
+            nextHash = writeHashKey(hash, key, undefined);
+            removedOversizedValue = true;
+        }
         void navigate({
             to: ".",
-            search: (prev) => {
-                if (getUrlLengthWithSearchParam(key, encodedValue || "", prev) <= MAX_URL_LENGTH) {
-                    return { ...prev, [key]: encodedValue };
-                }
-                else {
-                    return { ...prev, [key]: undefined };
-                }
-            },
-            hash: location.hash,
-            replace: shouldReplace,
+            // Returning the same `prev` reference leaves the search params
+            // unchanged; `search` must still be passed for the router types.
+            search: (prev) => prev,
+            // The router adds the `#` itself; forwarding it would double it.
+            hash: nextHash.startsWith("#") ? nextHash.slice(1) : nextHash,
+            replace: removedOversizedValue ? true : shouldReplace,
         });
-    }, [
-        router.state.status,
-        location.hash,
-        key,
-        currentSearchValue,
-        navigate,
-        replaceOption,
-        getUrlLengthWithSearchParam,
-    ]);
+    }, [router.state.status, replaceOption, isHash, navigate, getUrlLengthWithSearchParam, key]);
     useEffect(() => {
-        if (router.state.status === "pending") {
-            return;
-        }
-        if (pendingWriteRef.current === null) {
+        if (router.state.status === "pending" || pendingWriteRef.current === null) {
             return;
         }
         flushPendingWrite();
     }, [router.state.status, flushPendingWrite]);
-    // Drop any queued write when the consumer unmounts. The queue + retry
-    // pattern above keeps writes pending across a `router.state.status ===
-    // "pending"` phase, which means a write scheduled just before a route
-    // change could otherwise drain onto the *next* route once it settles
-    // (e.g. a debounced filter write leaking into the destination route).
-    // Cancelling here preserves the original "writes are scoped to the
-    // owning route" contract that the pre-queue implementation got for
-    // free by dropping the write outright.
     useEffect(() => () => {
         pendingWriteRef.current = null;
     }, []);
-    const updateSearchParam = useCallback((encodedValue, options) => {
+    const updateSearchParam = useCallback((encodedValue) => {
         if (!enabled) {
             return;
         }
-        // Dedupe against either the last committed write or the value
-        // currently queued for the next rAF — both represent the caller's
-        // intent so we don't schedule redundant rAF callbacks for identical
-        // requests.
+        // Dedupe against the last committed write or the value already queued;
+        // both represent the caller's intent.
         const inFlightOrLastWritten = pendingWriteRef.current?.encodedValue ?? lastWrittenRef.current;
         if (encodedValue !== undefined && encodedValue === inFlightOrLastWritten) {
             return;
         }
-        // Prime `lastWrittenRef` here (not inside `flushPendingWrite`) so
-        // the external-change detector treats this value as the caller's
-        // authoritative state even when the flush is a no-op (URL already
-        // matches) or stays queued during a pending router phase. Without
-        // priming, the next "external" change would look identical to the
-        // initial render (`lastWrittenRef === undefined`) and the callback
-        // would be skipped.
+        // Prime here (not in the flush) so the external-change detector treats
+        // this value as the caller's state even when the flush is a no-op or
+        // stays queued during a pending router phase.
         lastWrittenRef.current = encodedValue;
-        if (currentSearchValue === encodedValue) {
+        if (currentValueRef.current === encodedValue) {
             return;
         }
-        pendingWriteRef.current = { encodedValue, options };
+        pendingWriteRef.current = { encodedValue };
         requestAnimationFrame(() => {
             flushPendingWrite();
         });
-    }, [enabled, currentSearchValue, flushPendingWrite]);
-    return useMemo(() => ({ searchValue: currentSearchValue, updateSearchParam }), [currentSearchValue, updateSearchParam]);
-};
-
-/**
- * Generates a localStorage key, optionally scoped to a specific user.
- *
- * When `userId` is provided the key is `"key-userId"`.
- * When omitted the key is returned as-is (unscoped).
- *
- * @param key - Unique persistence identifier.
- * @param userId - Client-side user id to scope storage per user.
- * @returns {string} The combined storage key.
- */
-const useStorageKey = (key, userId) => {
-    return useMemo(() => (userId ? `${key}-${userId}` : key), [key, userId]);
+    }, [enabled, flushPendingWrite]);
+    return useMemo(() => ({ searchValue: currentValue, updateSearchParam }), [currentValue, updateSearchParam]);
 };
 
 /**
@@ -14195,47 +13916,43 @@ const rawLocalStorage = {
  * and writes changes to both.
  *
  * On mount the hook resolves the initial state as follows:
- *  - If the canonical URL slot (search OR hash, per `urlLocation`) holds a
- *    value, decode it and pass through `validate`.
- *  - In `urlLocation: "hash"` mode, if the canonical hash slot has no valid
- *    value but a **legacy** `?<key>=...` search param is present, decode and
- *    validate that as a one-shot fallback. The value is copied into the hash
- *    and the search param is stripped via a `replace` navigation.
- *  - A value that comes only from localStorage is not written to the URL.
- *    Copying it on load left a layout in history, bookmarks, and login
- *    redirects, which then replayed an older layout over the saved one
- *    (GLU-2396). The URL is written when the user changes the state.
+ *  - If the URL slot holds a value, decode it and pass through `validate`.
  *  - If localStorage is enabled, read and validate its value.
  *  - When `mergeWithStorageOnRead` is `false` (default): URL state wins
  *    entirely when present, otherwise fall back to localStorage.
  *  - When `mergeWithStorageOnRead` is `true`: shallow-merge URL fields over
  *    localStorage so fields stripped by `toUrlValue` survive via storage.
  *
- * `persistState` writes the state to localStorage (via `serialize`, default
- * `storageSerializer.serialize`) and syncs to the canonical URL slot (via
- * `toUrlValue` + encoding). Duplicate writes where the state has not
- * changed (deep equality) are skipped.
- *
- * `commitHydratedState` writes the hydrated value to localStorage only,
- * when it came from the URL and differs from what this identity has stored.
- * It does not update the URL. It returns `false` while the snapshot is
- * still for a previous read, so the caller can retry after identity
- * resolution. The caller decides which identity is allowed to commit.
- *
- * `clearState` removes the entry from localStorage and from the URL slot,
- * rather than writing an empty value. Use it when the state a consumer
- * derives has become empty, so no leftover entry is stored for a value the
- * user has reset. It is idempotent — clearing an absent entry is a no-op.
+ * A value that comes only from localStorage is never written to the URL on
+ * load. Copying it left a layout in history, bookmarks, and login redirects,
+ * which then replayed an older layout over the saved one (GLU-2396). The URL
+ * is written when the consumer persists a change.
+ *
+ * `persistState` writes to localStorage (`storageSerializer`) and to the URL
+ * (via `toUrlValue` + encoding).
+ * Each slot skips a value equal to its last write. The URL side compares what
+ * would land in the URL (the `toUrlValue` projection and the identity stamp),
+ * starting from the projection of the hydrated state and the stamp the URL
+ * carries: echoing `initialState`, or changing only a field the projection
+ * strips, writes no URL entry, while an equal state persisted after the
+ * identity resolves rewrites the URL with its stamp. The storage side starts
+ * from what localStorage held, so a consumer that persists `initialState`
+ * after opening a link saves that link's state for the account that opened
+ * it, and a reload of the account's own link writes nothing.
+ * `persistToStorage` and `persistToUrl` are the same two halves exposed
+ * separately for consumers that schedule them differently; passing `undefined`
+ * removes the entry rather than writing an empty value.
+ *
+ * The snapshot is re-read when the storage key or the storage/merge options
+ * change, in the same render, so a write in that commit already sees the
+ * state for the new key.
  *
  * @param options - Configuration for the persisted state.
  * @param options.key - Unique identifier used for both the URL slot and the localStorage key.
  * @param options.validate - Called with the decoded/parsed value; must return `TState` or `undefined`.
- * @param options.serialize - Custom localStorage serialiser (default `storageSerializer.serialize`).
  * @param options.toUrlValue - Transform applied before URL encoding (default: encode state as-is).
  * @param options.fromUrlValue - Transform applied after URL decoding, before validation (default: identity).
- * @param options.enabled - When `false` the URL is neither read nor written (default `true`).
  * @param options.localStorageEnabled - When `false` localStorage is neither read nor written (default `true`).
- * @param options.onExternalChange - Fired when the URL value changes externally (e.g. browser back).
  * @param options.replace - Forwarded to the underlying URL sync hook.
  * @param options.clientSideUserId - The user ID to use for the localStorage key.
  * @param options.mergeWithStorageOnRead - Merge URL state on top of localStorage
@@ -14245,344 +13962,182 @@ const rawLocalStorage = {
  * @param options.stampUrlWithIdentity - Stamp URL writes with the current identity so the login
  *   redirect can drop entries left by another account on this browser. Default `false`.
  */
-const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue, enabled = true, localStorageEnabled = true, onExternalChange, replace, clientSideUserId, mergeWithStorageOnRead = false, urlLocation = "search", stampUrlWithIdentity = false, }) => {
+const usePersistedState = ({ key, validate, toUrlValue, fromUrlValue, localStorageEnabled = true, replace, clientSideUserId, mergeWithStorageOnRead = false, urlLocation = "search", stampUrlWithIdentity = false, }) => {
     const { encode, decode } = useCustomEncoding();
     // Fingerprint of the identity this hook writes URL values for. `undefined`
     // while the identity is unresolved (or when stamping is off): writes are
     // then unstamped.
     const currentUrlOwner = useMemo(() => (stampUrlWithIdentity && clientSideUserId !== undefined ? identityFingerprint(clientSideUserId) : undefined), [stampUrlWithIdentity, clientSideUserId]);
-    const searchActive = enabled && urlLocation === "search";
-    const hashActive = enabled && urlLocation === "hash";
-    // Both URL-sync hooks are mounted unconditionally to satisfy the Rules of
-    // Hooks; the inactive one is gated off via `enabled: false` and is a
-    // no-op at runtime.
-    const searchSync = useSearchParamSync({
-        key,
-        enabled: searchActive,
-        onExternalChange,
-        replace,
-    });
-    const hashSync = useHashParamSync({
+    const { searchValue: urlValue, updateSearchParam: updateUrlValue } = useUrlParamSync({
         key,
-        enabled: hashActive,
-        onExternalChange,
+        location: urlLocation,
         replace,
     });
-    const { searchValue, updateSearchParam } = hashActive ? hashSync : searchSync;
-    // In hash mode, also read the raw search params so a legacy `?<key>=...`
-    // value can hydrate the initial state once, before the migration effect
-    // strips it. In search mode this stays `undefined` so the legacy fallback
-    // is inert.
-    const rawSearch = useSearch({ strict: false, shouldThrow: false });
-    const legacySearchValue = useMemo(() => {
-        if (!hashActive) {
-            return undefined;
-        }
-        return readPrimitiveSearchParam(rawSearch, key);
-    }, [hashActive, rawSearch, key]);
     const storageKey = useStorageKey(key, clientSideUserId);
+    // `toUrlValue` is read through a ref so the write callbacks stay stable
+    // when a consumer passes an inline function.
     const toUrlValueRef = useRef(toUrlValue);
     useEffect(() => {
         toUrlValueRef.current = toUrlValue;
     }, [toUrlValue]);
-    const serializeRef = useRef(serialize);
-    useEffect(() => {
-        serializeRef.current = serialize;
-    }, [serialize]);
-    const validateRef = useRef(validate);
-    useEffect(() => {
-        validateRef.current = validate;
-    }, [validate]);
-    const fromUrlValueRef = useRef(fromUrlValue);
-    useEffect(() => {
-        fromUrlValueRef.current = fromUrlValue;
-    }, [fromUrlValue]);
-    const searchValueRef = useRef(searchValue);
-    useEffect(() => {
-        searchValueRef.current = searchValue;
-    }, [searchValue]);
-    const legacySearchValueRef = useRef(legacySearchValue);
-    useEffect(() => {
-        legacySearchValueRef.current = legacySearchValue;
-    }, [legacySearchValue]);
-    const readPersistedState = useCallback(({ valueFromUrl, legacyValueFromUrl, validateState, transformFromUrlValue, }) => {
-        // The ownership stamp is only read at the login redirect (see
-        // `useStripForeignIdentityHash`); here it is unwrapped and discarded.
-        const tryDecode = (raw) => {
-            try {
-                const { value } = unwrapUrlOwner(decode(raw));
-                const transformed = transformFromUrlValue ? transformFromUrlValue(value) : value;
-                const state = validateState(transformed);
-                if (state === undefined) {
-                    return undefined;
-                }
-                return { state, payload: value };
-            }
-            catch {
-                return undefined;
-            }
-        };
-        const readStoredState = () => {
-            if (!localStorageEnabled) {
+    const readStoredState = useCallback((validateState) => {
+        if (!localStorageEnabled) {
+            return undefined;
+        }
+        try {
+            const raw = rawLocalStorage.read(storageKey);
+            if (!raw) {
                 return undefined;
             }
+            return validateState(storageSerializer.deserialize(raw));
+        }
+        catch {
+            return undefined;
+        }
+    }, [localStorageEnabled, storageKey]);
+    const readPersistedState = useCallback(({ valueFromUrl, validateState, transformFromUrlValue, }) => {
+        let urlState;
+        let urlStamp;
+        if (valueFromUrl) {
             try {
-                const raw = rawLocalStorage.read(storageKey);
-                if (!raw) {
-                    return undefined;
-                }
-                return validateState(storageSerializer.deserialize(raw));
+                // The ownership stamp decides nothing on read (the login redirect
+                // does that, see `useStripForeignIdentityHash`); it is kept only to
+                // seed the URL dedupe with what the URL is currently stamped with.
+                const { value, owner } = unwrapUrlOwner(decode(valueFromUrl));
+                urlState = validateState(transformFromUrlValue ? transformFromUrlValue(value) : value);
+                urlStamp = urlState === undefined ? undefined : { owner };
             }
             catch {
-                return undefined;
+                urlState = undefined;
             }
-        };
-        let urlState;
-        let decodedPayload;
-        let canonicalUrlValid = false;
-        let usedLegacyUrl = false;
-        if (enabled && valueFromUrl) {
-            const decoded = tryDecode(valueFromUrl);
-            if (decoded !== undefined) {
-                urlState = decoded.state;
-                decodedPayload = decoded.payload;
-                canonicalUrlValid = true;
-            }
-        }
-        if (urlState === undefined && enabled && legacyValueFromUrl) {
-            const decoded = tryDecode(legacyValueFromUrl);
-            if (decoded !== undefined) {
-                urlState = decoded.state;
-                usedLegacyUrl = true;
-            }
-        }
-        // Without the merge option, URL state wins entirely when present —
-        // this preserves the original "URL > localStorage" priority.
-        if (urlState !== undefined && !mergeWithStorageOnRead) {
-            return {
-                initialState: urlState,
-                canonicalUrlHasValidState: canonicalUrlValid,
-                canonicalUrlPayload: decodedPayload,
-                needsUrlRestore: usedLegacyUrl,
-            };
         }
-        const storageState = readStoredState();
-        if (urlState !== undefined && storageState !== undefined) {
-            // Shallow merge — URL fields take precedence; storage fills in
-            // whatever the URL omits (e.g. fields stripped by `toUrlValue`).
-            return {
-                initialState: { ...storageState, ...urlState },
-                canonicalUrlHasValidState: canonicalUrlValid,
-                canonicalUrlPayload: decodedPayload,
-                needsUrlRestore: usedLegacyUrl,
-            };
+        // Storage is read even when the URL wins outright: it seeds the storage
+        // dedupe, so persisting the hydrated state writes only when the URL
+        // changed something.
+        const stored = readStoredState(validateState);
+        let hydrated;
+        if (urlState === undefined) {
+            hydrated = stored;
         }
-        if (urlState !== undefined) {
-            return {
-                initialState: urlState,
-                canonicalUrlHasValidState: canonicalUrlValid,
-                canonicalUrlPayload: decodedPayload,
-                needsUrlRestore: usedLegacyUrl,
-            };
+        else if (mergeWithStorageOnRead && stored !== undefined) {
+            // URL fields take precedence; storage fills in whatever the URL
+            // omits (e.g. fields stripped by `toUrlValue`).
+            hydrated = { ...stored, ...urlState };
         }
-        if (storageState !== undefined) {
-            return {
-                initialState: storageState,
-                canonicalUrlHasValidState: false,
-                canonicalUrlPayload: undefined,
-                // Leave the URL alone. A storage-only load must not grow a hash,
-                // or the next history/bookmark/login of this page replays it.
-                needsUrlRestore: false,
-            };
-        }
-        return {
-            initialState: undefined,
-            canonicalUrlHasValidState: false,
-            canonicalUrlPayload: undefined,
-            needsUrlRestore: false,
-        };
-    }, [decode, enabled, localStorageEnabled, storageKey, mergeWithStorageOnRead]);
-    // Every URL write goes through here so the ownership stamp is applied
-    // uniformly (user edits and legacy search-param migration).
-    const encodeForUrl = useCallback((state) => {
-        const urlValue = toUrlValueRef.current ? toUrlValueRef.current(state) : state;
-        return encode(currentUrlOwner === undefined ? urlValue : wrapUrlOwner(urlValue, currentUrlOwner));
-    }, [encode, currentUrlOwner]);
-    const persistedStateReadKey = `${enabled}:${localStorageEnabled}:${mergeWithStorageOnRead}:${urlLocation}:${storageKey}`;
-    const [persistedStateSnapshot, setPersistedStateSnapshot] = useState(() => ({
-        ...readPersistedState({
-            valueFromUrl: searchValue,
-            legacyValueFromUrl: legacySearchValue,
-            validateState: validate,
-            transformFromUrlValue: fromUrlValue,
-        }),
-        readKey: persistedStateReadKey,
-    }));
-    const persistedStateReadKeyRef = useRef(persistedStateReadKey);
-    useEffect(() => {
-        if (persistedStateReadKeyRef.current === persistedStateReadKey) {
-            return;
-        }
-        persistedStateReadKeyRef.current = persistedStateReadKey;
-        setPersistedStateSnapshot({
-            ...readPersistedState({
-                valueFromUrl: searchValueRef.current,
-                legacyValueFromUrl: legacySearchValueRef.current,
-                validateState: validateRef.current,
-                transformFromUrlValue: fromUrlValueRef.current,
-            }),
-            readKey: persistedStateReadKey,
-        });
-    }, [persistedStateReadKey, readPersistedState]);
-    const { initialState, canonicalUrlHasValidState, canonicalUrlPayload, needsUrlRestore } = persistedStateSnapshot;
-    // Late-hydration recovery: TanStack Router's `useSearch` can return an
-    // empty object on the very first render of a route that's still in a
-    // loader-driven pending phase. The `useState` initializer above runs
-    // exactly once, so a legacy `?<key>=...` value that only becomes
-    // visible on a later render would otherwise be missed entirely —
-    // `initialState` would resolve to `undefined`, and the migration
-    // effect would strip the legacy param without ever piping it through
-    // `onMigrated`. We re-read here when:
-    //   - the snapshot has nothing usable yet (`initialState === undefined`
-    //     AND the canonical URL slot has no valid value), and
-    //   - a legacy value has just appeared.
-    // Once `initialState` is populated, this effect's guard short-circuits
-    // and the rest of the lifecycle (restore + migration) takes over.
-    useEffect(() => {
-        if (initialState !== undefined || canonicalUrlHasValidState) {
-            return;
-        }
-        if (legacySearchValue === undefined) {
-            return;
-        }
-        setPersistedStateSnapshot({
-            ...readPersistedState({
-                valueFromUrl: searchValueRef.current,
-                legacyValueFromUrl: legacySearchValue,
-                validateState: validateRef.current,
-                transformFromUrlValue: fromUrlValueRef.current,
-            }),
-            readKey: persistedStateReadKey,
-        });
-    }, [legacySearchValue, initialState, canonicalUrlHasValidState, persistedStateReadKey, readPersistedState]);
-    const lastPersistedRef = useRef(initialState);
-    useEffect(() => {
-        lastPersistedRef.current = initialState;
-    }, [initialState, localStorageEnabled, storageKey]);
-    const hasRestoredUrlRef = useRef(false);
-    useEffect(() => {
-        hasRestoredUrlRef.current = false;
-    }, [enabled, localStorageEnabled, storageKey, urlLocation]);
+        else {
+            hydrated = urlState;
+        }
+        return { initialState: hydrated, storedState: stored, urlValue: urlStamp };
+    }, [decode, mergeWithStorageOnRead, readStoredState]);
+    // The shareable projection of `state`: what a URL write carries before
+    // encoding. The URL dedupe compares this, not the whole state, so a change
+    // confined to a field `toUrlValue` strips is not a URL change.
+    const projectForUrl = useCallback((state) => (toUrlValueRef.current ? toUrlValueRef.current(state) : state), []);
+    // Every URL write goes through here so the ownership stamp is applied uniformly.
+    const encodeUrlWrite = useCallback(({ projected, owner }) => encode(owner === undefined ? projected : wrapUrlOwner(projected, owner)), [encode]);
+    // `readPersistedState` changes identity exactly when an input that changes
+    // what a read returns does (storage key, storage/merge options), so the
+    // snapshot is re-read then and only then — synchronously, in the render
+    // where the input changed, by deriving state from the changed input. A URL
+    // change after mount or an inline `validate` deliberately does not
+    // re-hydrate `initialState`: `useUrlParamSync` owns URL changes.
+    const readSnapshot = () => ({
+        readWith: readPersistedState,
+        ...readPersistedState({ valueFromUrl: urlValue, validateState: validate, transformFromUrlValue: fromUrlValue }),
+    });
+    const [snapshot, setSnapshot] = useState(readSnapshot);
+    if (snapshot.readWith !== readPersistedState) {
+        setSnapshot(readSnapshot());
+    }
+    const { initialState, storedState } = snapshot;
+    // Last value written to each slot, for deduping. Two refs, not one, because
+    // a consumer may schedule the two writes differently (storage at once, URL
+    // debounced). Both are re-seeded whenever the snapshot is re-read so the
+    // first write to a newly scoped key is never skipped.
+    //
+    // The storage side starts as what storage held, so persisting the hydrated
+    // state after opening a link writes only when the URL changed something.
+    //
+    // The URL side holds what a write would put in the URL: the shareable
+    // projection plus the owner stamp. It starts as the projection of the
+    // hydrated value, so a consumer that echoes `initialState` on mount, or
+    // changes only a field the projection strips, writes nothing: a layout read
+    // from storage must not grow a URL entry (GLU-2396). Its owner starts as the
+    // stamp the URL carries (or the current owner when the URL is empty), so an
+    // equal state persisted after the identity resolves still rewrites the URL
+    // with its stamp.
+    const urlOwnerSeed = snapshot.urlValue ? snapshot.urlValue.owner : currentUrlOwner;
+    const seedUrlWrite = useCallback((project) => initialState === undefined ? undefined : { projected: project(initialState), owner: urlOwnerSeed }, [initialState, urlOwnerSeed]);
+    const lastStoredRef = useRef(storedState);
+    // The first seed is computed during render, so it projects with the
+    // `toUrlValue` prop rather than reading `toUrlValueRef` (refs are not read
+    // in render); the projection is cheap, and later seeds come from the effect.
+    const lastUrlRef = useRef(seedUrlWrite(state => (toUrlValue ? toUrlValue(state) : state)));
     useEffect(() => {
-        if (hasRestoredUrlRef.current) {
+        lastStoredRef.current = storedState;
+        lastUrlRef.current = seedUrlWrite(projectForUrl);
+    }, [seedUrlWrite, projectForUrl, storedState]);
+    const persistToStorage = useCallback((state) => {
+        if (!localStorageEnabled) {
             return;
         }
-        // Only a legacy search param is copied into the hash. Storage is not:
-        // mirroring it on load is what put a layout into every history entry
-        // (GLU-2396). Gate on `canonicalUrlHasValidState`, not on the raw
-        // `searchValue`: an undecodable string in the hash slot must not block
-        // the legacy copy, or the migration strips the search param and the
-        // bad string is the only state left on the next reload.
-        if (!enabled || !needsUrlRestore || initialState === undefined || canonicalUrlHasValidState) {
+        if (state === undefined) {
+            lastStoredRef.current = undefined;
+            rawLocalStorage.remove(storageKey);
             return;
         }
-        hasRestoredUrlRef.current = true;
-        updateSearchParam(encodeForUrl(initialState), { replace: true });
-    }, [enabled, needsUrlRestore, initialState, canonicalUrlHasValidState, updateSearchParam, encodeForUrl]);
-    // Strip the legacy search param so reloads come from the canonical hash
-    // slot and the URL stays tidy. The hook is a no-op outside hash mode.
-    // `hashAlreadyHasValue` is `true` only when the canonical hash slot
-    // already holds *valid* state — a raw but undecodable string must not
-    // suppress `onMigrated`, otherwise a valid legacy value would be lost
-    // on the next reload (see `canonicalUrlHasValidState` for the same
-    // reasoning in the restore effect above).
-    useMigrateLegacySearchParam({
-        key,
-        enabled: hashActive,
-        decode,
-        fromUrlValue,
-        validate,
-        hashAlreadyHasValue: canonicalUrlHasValidState,
-        onMigrated: useCallback((migrated) => {
-            if (dequal(lastPersistedRef.current, migrated)) {
-                return;
-            }
-            lastPersistedRef.current = migrated;
-            if (localStorageEnabled) {
-                const serialized = serializeRef.current
-                    ? serializeRef.current(migrated)
-                    : storageSerializer.serialize(migrated);
-                rawLocalStorage.write(storageKey, serialized);
-            }
-            updateSearchParam(encodeForUrl(migrated), { replace: true });
-        }, [encodeForUrl, localStorageEnabled, storageKey, updateSearchParam]),
-    });
-    const persistState = useCallback((state) => {
-        if (dequal(lastPersistedRef.current, state)) {
+        if (dequal(lastStoredRef.current, state)) {
             return;
         }
-        lastPersistedRef.current = state;
-        if (localStorageEnabled) {
-            const serialized = serializeRef.current ? serializeRef.current(state) : storageSerializer.serialize(state);
-            rawLocalStorage.write(storageKey, serialized);
-        }
-        updateSearchParam(encodeForUrl(state));
-    }, [storageKey, encodeForUrl, localStorageEnabled, updateSearchParam]);
-    const clearState = useCallback(() => {
-        lastPersistedRef.current = undefined;
-        if (localStorageEnabled) {
-            rawLocalStorage.remove(storageKey);
-        }
-        updateSearchParam(undefined);
-    }, [localStorageEnabled, storageKey, updateSearchParam]);
-    const snapshotIsCurrent = persistedStateSnapshot.readKey === persistedStateReadKey;
-    // Opening a shared URL should become this identity's saved layout. The
-    // caller decides which identity is allowed to commit: this only writes
-    // when the snapshot was read for the current storage key, so a late
-    // identity resolution cannot persist the pre-merge value and drop fields
-    // that live only in localStorage. A hash that is only the shareable
-    // projection of what is already stored is left alone, so reloading this
-    // account's own link does not replace hidden columns with the shorter URL form.
-    const commitHydratedState = useCallback(() => {
-        if (!snapshotIsCurrent || !localStorageEnabled) {
-            return false;
-        }
-        if (!canonicalUrlHasValidState || initialState === undefined) {
-            return true;
-        }
-        let stored;
         try {
-            const raw = rawLocalStorage.read(storageKey);
-            if (raw) {
-                stored = validateRef.current(storageSerializer.deserialize(raw));
-            }
+            rawLocalStorage.write(storageKey, storageSerializer.serialize(state));
+            lastStoredRef.current = state;
         }
         catch {
-            stored = undefined;
+            // Quota or a disabled store: the next write retries; the URL is unaffected.
         }
-        if (stored !== undefined) {
-            const projected = toUrlValueRef.current ? toUrlValueRef.current(stored) : stored;
-            if (dequal(projected, canonicalUrlPayload)) {
-                return true;
-            }
+    }, [localStorageEnabled, storageKey]);
+    const persistToUrl = useCallback((state) => {
+        if (state === undefined) {
+            lastUrlRef.current = undefined;
+            updateUrlValue(undefined);
+            return;
         }
-        const serialized = serializeRef.current
-            ? serializeRef.current(initialState)
-            : storageSerializer.serialize(initialState);
-        rawLocalStorage.write(storageKey, serialized);
-        lastPersistedRef.current = initialState;
-        return true;
-    }, [
-        canonicalUrlHasValidState,
-        canonicalUrlPayload,
-        initialState,
-        localStorageEnabled,
-        snapshotIsCurrent,
-        storageKey,
-    ]);
-    return useMemo(() => ({ initialState, persistState, clearState, commitHydratedState }), [initialState, persistState, clearState, commitHydratedState]);
+        const write = { projected: projectForUrl(state), owner: currentUrlOwner };
+        const last = lastUrlRef.current;
+        // Same projection: write only to add or change a stamp. An unresolved
+        // identity never rewrites a stamped URL just to strip the stamp; it is
+        // re-stamped once the identity resolves.
+        if (last !== undefined &&
+            dequal(last.projected, write.projected) &&
+            (last.owner === write.owner || write.owner === undefined)) {
+            return;
+        }
+        lastUrlRef.current = write;
+        updateUrlValue(encodeUrlWrite(write));
+    }, [currentUrlOwner, encodeUrlWrite, projectForUrl, updateUrlValue]);
+    const persistState = useCallback((state) => {
+        persistToStorage(state);
+        persistToUrl(state);
+    }, [persistToStorage, persistToUrl]);
+    return useMemo(() => ({ initialState, persistState, persistToStorage, persistToUrl }), [initialState, persistState, persistToStorage, persistToUrl]);
 };
 
+/**
+ * Syncs an encoded string value with a URL search parameter via Tanstack Router.
+ *
+ * Thin wrapper over {@link useUrlParamSync} with `location: "search"`; see it
+ * for the write queue, the size guard (`MAX_URL_LENGTH`), and external-change
+ * detection.
+ *
+ * @param options - Configuration for the search param sync.
+ * @param options.key - The URL search parameter name.
+ * @param options.enabled - Set to `false` to disable all URL interaction (default `true`).
+ * @param options.onExternalChange - Called when the param changes externally.
+ * @param options.replace - `true` to always use `replaceState`.
+ */
+const useSearchParamSync = (options) => useUrlParamSync({ ...options, location: "search" });
+
 /**
  * Enumerates localStorage keys. Kept local so this file's exemption from the
  * no-direct-storage-access rule is centralised, as in `usePersistedState`.
@@ -15908,4 +15463,4 @@ const useWindowActivity = ({ onFocus, onBlur, skip = false } = { onBlur: undefin
  */
 setupLibraryTranslations();
 
-export { Alert, Badge, Breadcrumb, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyButton, CopyableValue, DEFAULT_SKELETON_PREFERENCE_CARD_PROPS, DetailsList, EmptyState, EmptyValue, ExternalLink, GridAreas, Heading, Highlight, HorizontalOverflowScroller, Icon, IconButton, IdentityCard, IdentityCardSkeleton, Indicator, KPI, KPICard, KPICardSkeleton, KPISkeleton, LabeledValue, LabeledValueList, List, ListItem, MAX_HASH_LENGTH, MAX_URL_LENGTH, MenuContent, MenuDivider, MenuItem, MenuTree, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, PreferenceCard, PreferenceCardSkeleton, Prompt, ROLE_CARD, SHEET_TRANSITION_DURATION, SHEET_TRANSITION_DURATION_MS, SHEET_TRANSITION_EASING, SectionHeader, SegmentedValueBar, Sheet, Sidebar, SidebarContentLayout, SkeletonBlock, SkeletonLabel, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, Tooltip, TrendIndicator, TrendIndicators, ValueBar, ZStack, createGrid, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaContentContainer, cvaContentWrapper, cvaDescriptionCard, cvaIconBackground, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInputContainer, cvaInteractableItem, cvaList, cvaListContainer, cvaListItem$1 as cvaListItem, cvaMenu, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaMenuList, cvaMenuListDivider, cvaMenuListItem, cvaMenuListMultiSelect, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaPreferenceCard, cvaTitleCard, cvaToggleGroup, cvaToggleGroupWithSlidingBackground, cvaToggleItem, cvaToggleItemContent, cvaToggleItemText, cvaZStackContainer, cvaZStackItem, defaultPageSize, docs, getDevicePixelRatio, getValueBarColorByValue, iconColorNames, iconPalette, noPagination, preferenceCardGrid, useBidirectionalScroll, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useCopyToClipboard, useCursorUrlSync, useCustomEncoding, useDebounce, useDevicePixelRatio, useElevatedReducer, useElevatedState, useGridAreas, useHashParamSync, useHold, useHover, useInfiniteScroll, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useKeyboardShortcut, useList, useListItemHeight, useLocalStorage, useLocalStorageReducer, useMeasure, useMenuSearchField, useMenuTree, useMergeRefs, useModifierKey, useOptionalPopoverContext, useOverflowBorder, useOverflowItems, usePersistedState, usePopoverContext, usePrevious, usePrompt, useRandomCSSLengths, useRelayPagination, useResize, useScrollBlock, useScrollDetection, useSearchParamSync, useSelfUpdatingRef, useSessionStorage, useSessionStorageReducer, useSheet, useSheetSnap, useStorageKey, useStripForeignIdentityHash, useTextSearch, useTimeout, useViewportBreakpoints, useWatch, useWindowActivity };
+export { Alert, Badge, Breadcrumb, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyButton, CopyableValue, DEFAULT_SKELETON_PREFERENCE_CARD_PROPS, DetailsList, EmptyState, EmptyValue, ExternalLink, GridAreas, Heading, Highlight, HorizontalOverflowScroller, Icon, IconButton, IdentityCard, IdentityCardSkeleton, Indicator, KPI, KPICard, KPICardSkeleton, KPISkeleton, LabeledValue, LabeledValueList, List, ListItem, MAX_URL_LENGTH, MenuContent, MenuDivider, MenuItem, MenuTree, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, PreferenceCard, PreferenceCardSkeleton, Prompt, ROLE_CARD, SHEET_TRANSITION_DURATION, SHEET_TRANSITION_DURATION_MS, SHEET_TRANSITION_EASING, SectionHeader, SegmentedValueBar, Sheet, Sidebar, SidebarContentLayout, SkeletonBlock, SkeletonLabel, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, Tooltip, TrendIndicator, TrendIndicators, ValueBar, ZStack, createGrid, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaContentContainer, cvaContentWrapper, cvaDescriptionCard, cvaIconBackground, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInputContainer, cvaInteractableItem, cvaList, cvaListContainer, cvaListItem$1 as cvaListItem, cvaMenu, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaMenuList, cvaMenuListDivider, cvaMenuListItem, cvaMenuListMultiSelect, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaPreferenceCard, cvaTitleCard, cvaToggleGroup, cvaToggleGroupWithSlidingBackground, cvaToggleItem, cvaToggleItemContent, cvaToggleItemText, cvaZStackContainer, cvaZStackItem, defaultPageSize, docs, getDevicePixelRatio, getValueBarColorByValue, iconColorNames, iconPalette, noPagination, preferenceCardGrid, useBidirectionalScroll, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useCopyToClipboard, useCursorUrlSync, useCustomEncoding, useDebounce, useDevicePixelRatio, useElevatedReducer, useElevatedState, useGridAreas, useHold, useHover, useInfiniteScroll, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useKeyboardShortcut, useList, useListItemHeight, useLocalStorage, useLocalStorageReducer, useMeasure, useMenuSearchField, useMenuTree, useMergeRefs, useModifierKey, useOptionalPopoverContext, useOverflowBorder, useOverflowItems, usePersistedState, usePopoverContext, usePrevious, usePrompt, useRandomCSSLengths, useRelayPagination, useResize, useScrollBlock, useScrollDetection, useSearchParamSync, useSelfUpdatingRef, useSessionStorage, useSessionStorageReducer, useSheet, useSheetSnap, useStorageKey, useStripForeignIdentityHash, useTextSearch, useTimeout, useViewportBreakpoints, useWatch, useWindowActivity };