@trackunit/react-components 3.8.4-alpha-7afddbbe4cc.0 → 3.8.4

package/index.cjs.js

@@ -2361,6 +2361,7 @@ const cvaTagText = cssClassVarianceUtilities.cva({
     },
 });
 const cvaTagIconContainer = cssClassVarianceUtilities.cva({ base: ["shrink-0", "inline-flex", "self-center"] });
+const cvaTagDismissButton = cssClassVarianceUtilities.cva({ base: ["inline-flex", "rounded-full", "focus-visible:outline-native"] });
 const cvaTagIcon = cssClassVarianceUtilities.cva({
     base: ["cursor-pointer", "transition-opacity", "hover:opacity-70", "text-neutral-500"],
 });
@@ -2414,9 +2415,11 @@ const TAG_TEXT_MIN_WIDTH_PX = sharedUtils.parseTailwindArbitraryValue(TAG_TEXT_M
  * @param {TagProps} props - The props for the Tag component.
  * @returns {ReactElement} The rendered Tag component.
  */
-const Tag = ({ className, "data-testid": dataTestId, children, size = "medium", onClickClose, color = "info", disabled = false, ref, icon, onMouseEnter, style, removeTagLabel, }) => {
+const Tag = ({ className, "data-testid": dataTestId, children, size = "medium", onClickClose, color = "info", disabled = false, ref, icon, onMouseEnter, style, removeTagLabel, removeButtonInTabOrder = true, }) => {
     const textRef = react.useRef(null);
     const [shouldTruncate, setShouldTruncate] = react.useState(false);
+    const textId = react.useId();
+    const removeButtonId = react.useId();
     react.useLayoutEffect(() => {
         // Using simple DOM measurements to avoid the complexity of the useMeasure hook.
         // Resize observers have some overhead and we don't need the full power of the useMeasure hook here.
@@ -2428,28 +2431,22 @@ const Tag = ({ className, "data-testid": dataTestId, children, size = "medium",
             setShouldTruncate(width >= TAG_TEXT_MIN_WIDTH_PX);
         }
     }, [children]);
-    const isSupportedDismissColor = react.useMemo(() => {
-        if (color === "neutral" || color === "primary" || color === "white" || color === "info") {
-            return true;
-        }
-        return false;
-    }, [color]);
     const layout = react.useMemo(() => {
-        if (onClickClose !== undefined && isSupportedDismissColor && !disabled) {
+        if (onClickClose !== undefined && !disabled) {
             return "containsDismiss";
         }
         if (icon !== null && icon !== undefined) {
             return "containsIcon";
         }
         return "default";
-    }, [onClickClose, isSupportedDismissColor, disabled, icon]);
+    }, [onClickClose, disabled, icon]);
     return (jsxRuntime.jsxs("div", { className: cvaTag({
             className,
             size,
             color,
             layout,
             border: color === "white" ? "default" : "none",
-        }), "data-testid": dataTestId, onMouseEnter: onMouseEnter, ref: ref, style: style, children: [icon !== null && icon !== undefined && size === "medium" ? (jsxRuntime.jsx("div", { className: cvaTagIconContainer(), "data-slot": "icon", children: icon })) : null, jsxRuntime.jsx("span", { className: cvaTagText({ truncate: shouldTruncate }), ref: textRef, children: children }), Boolean(onClickClose) && isSupportedDismissColor && size === "medium" && !disabled ? (jsxRuntime.jsx("div", { className: cvaTagIconContainer(), "data-slot": "dismiss", onClick: onClickClose, children: jsxRuntime.jsx(Tooltip, { disabled: disabled, label: removeTagLabel, placement: "bottom", children: jsxRuntime.jsx(Icon, { className: cvaTagIcon(), "data-testid": `${dataTestId}Icon`, name: "XCircle", size: "small", style: { WebkitTransition: "-webkit-transform 0.150s" }, type: "solid" }) }) })) : null] }));
+        }), "data-testid": dataTestId, onMouseEnter: onMouseEnter, ref: ref, style: style, children: [icon !== null && icon !== undefined && size === "medium" ? (jsxRuntime.jsx("div", { className: cvaTagIconContainer(), "data-slot": "icon", children: icon })) : null, jsxRuntime.jsx("span", { className: cvaTagText({ truncate: shouldTruncate }), id: textId, ref: textRef, children: children }), Boolean(onClickClose) && size === "medium" && !disabled ? (jsxRuntime.jsx("div", { className: cvaTagIconContainer(), "data-slot": "dismiss", onClick: onClickClose, children: jsxRuntime.jsx(Tooltip, { disabled: disabled, label: removeTagLabel, placement: "bottom", children: jsxRuntime.jsx("button", { "aria-label": removeTagLabel, "aria-labelledby": `${removeButtonId} ${textId}`, className: cvaTagDismissButton(), id: removeButtonId, tabIndex: removeButtonInTabOrder ? undefined : -1, type: "button", children: jsxRuntime.jsx(Icon, { ariaHidden: true, className: cvaTagIcon(), "data-testid": `${dataTestId}Icon`, name: "XCircle", size: "small", style: { WebkitTransition: "-webkit-transform 0.150s" }, type: "solid" }) }) }) })) : null] }));
 };
 
 // Mirrors the slug logic in @trackunit/storybook-docs-components SectionName so anchors line up
@@ -13481,90 +13478,6 @@ 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 = zod.z.object({
-    o: zod.z.string(),
-    v: zod.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 react.useMemo(() => (userId ? `${key}-${userId}` : key), [key, userId]);
-};
-
 /**
  * Pure utilities for reading and writing single named entries inside a URL
  * fragment (the part after `#`).
@@ -13693,6 +13606,183 @@ 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 = reactRouter.useNavigate();
+    const location = reactRouter.useLocation();
+    const router = reactRouter.useRouter();
+    const lastWrittenRef = react.useRef(undefined);
+    const pendingWriteRef = react.useRef(null);
+    const onExternalChangeRef = react.useRef(onExternalChange);
+    react.useEffect(() => {
+        onExternalChangeRef.current = onExternalChange;
+    }, [onExternalChange]);
+    const currentHashValue = react.useMemo(() => {
+        if (!enabled) {
+            return undefined;
+        }
+        return readHashKey(location.hash, key);
+    }, [enabled, location.hash, key]);
+    react.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 = react.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]);
+    react.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.
+    react.useEffect(() => () => {
+        pendingWriteRef.current = null;
+    }, []);
+    const updateHashParam = react.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 react.useMemo(() => ({ searchValue: currentHashValue, updateSearchParam: updateHashParam }), [currentHashValue, updateHashParam]);
+};
+
 const searchRecordSchema = zod.z.record(zod.z.string(), zod.z.unknown());
 const primitiveSearchValueSchema = zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean()]);
 /**
@@ -13715,187 +13805,373 @@ const readPrimitiveSearchParam = (search, key) => {
 };
 
 /**
- * Maximum full URL length after adding one persisted search param before the
- * URL write is skipped (localStorage still persists the full state).
+ * Pure utilities for stamping a URL-persisted value with the identity that
+ * wrote it.
  *
- * Sized to stay safely below the AWS WAF managed-rule default
- * `SizeRestrictions_QUERYSTRING` cap of 5000 bytes for the entire
- * host + path + query + hash string.
+ * 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.
  */
-const MAX_URL_LENGTH = 5000;
 /**
- * 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.
+ * 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 = zod.z.object({
+    o: zod.z.string(),
+    v: zod.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.
  *
- * 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.
+ * @param identity - The client-side user id to fingerprint.
+ * @returns {string} A short stable fingerprint of `identity`.
  */
-const MAX_HASH_LENGTH = 64 * 1024;
+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 = reactRouter.useNavigate();
+    const location = reactRouter.useLocation();
+    const search = reactRouter.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 = react.useRef(false);
+    const hasMigratedRef = react.useRef(false);
+    const cachedRawValueRef = react.useRef(undefined);
+    const decodeRef = react.useRef(decode);
+    const fromUrlValueRef = react.useRef(fromUrlValue);
+    const validateRef = react.useRef(validate);
+    const onMigratedRef = react.useRef(onMigrated);
+    react.useEffect(() => {
+        decodeRef.current = decode;
+        fromUrlValueRef.current = fromUrlValue;
+        validateRef.current = validate;
+        onMigratedRef.current = onMigrated;
+    }, [decode, fromUrlValue, validate, onMigrated]);
+    react.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).
+ *
+ * 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
+ */
+const MAX_URL_LENGTH = 5000;
 /**
- * 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"`.
+ * Syncs an encoded string value with a URL search parameter via Tanstack Router.
+ *
+ * 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.
  * @param options.enabled - Set to `false` to disable all URL interaction (default `true`).
- * @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.
+ * @param options.onExternalChange - Called when the param changes externally.
+ * @param options.replace - `true` to always use `replaceState`.
  */
-const useUrlParamSync = ({ key, location: urlLocation, enabled = true, onExternalChange, replace: replaceOption, }) => {
+const useSearchParamSync = ({ key, enabled = true, onExternalChange, replace: replaceOption, }) => {
     const navigate = reactRouter.useNavigate();
     const location = reactRouter.useLocation();
     const router = reactRouter.useRouter();
     const search = reactRouter.useSearch({ strict: false, shouldThrow: false });
-    const isHash = urlLocation === "hash";
     const lastWrittenRef = react.useRef(undefined);
     const pendingWriteRef = react.useRef(null);
     const onExternalChangeRef = react.useRef(onExternalChange);
     react.useEffect(() => {
         onExternalChangeRef.current = onExternalChange;
     }, [onExternalChange]);
-    const currentValue = react.useMemo(() => {
+    const currentSearchValue = react.useMemo(() => {
         if (!enabled) {
             return undefined;
         }
-        return isHash ? readHashKey(location.hash, key) : readPrimitiveSearchParam(search, key);
-    }, [enabled, isHash, location.hash, search, key]);
+        return readPrimitiveSearchParam(search, key);
+    }, [enabled, search, key]);
     react.useEffect(() => {
-        if (!enabled || currentValue === undefined) {
+        if (!enabled) {
+            return;
+        }
+        if (currentSearchValue === undefined) {
             return;
         }
-        if (currentValue === lastWrittenRef.current || lastWrittenRef.current === undefined) {
+        if (currentSearchValue === lastWrittenRef.current) {
             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 would reload state from
-        // persistence before the write lands.
+        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.
         if (pendingWriteRef.current !== null) {
             return;
         }
         requestAnimationFrame(() => {
             onExternalChangeRef.current?.();
         });
-    }, [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 = react.useRef(location);
-    const currentValueRef = react.useRef(currentValue);
-    react.useEffect(() => {
-        locationRef.current = location;
-        currentValueRef.current = currentValue;
-    }, [location, currentValue]);
-    const getUrlLengthWithSearchParam = react.useCallback((paramValue, params) => {
-        const { href, searchStr, hash } = locationRef.current;
+    }, [currentSearchValue, enabled]);
+    const getUrlLengthWithSearchParam = react.useCallback((paramKey, paramValue, params) => {
         const otherParamsLength = sharedUtils.objectKeys(params)
-            .filter(k => k !== key)
+            .filter(k => k !== paramKey)
             .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 = href.length - (searchStr.length || 0) + (hash.length || 0);
-        return urlBase + otherParamsLength + 1 + key.length + 1 + paramValue.length;
-    }, [key]);
+        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 flushPendingWrite = react.useCallback(() => {
         const pending = pendingWriteRef.current;
         if (pending === null) {
             return;
         }
         if (router.state.status === "pending") {
-            // Keep the write queued; the status-watcher effect retries once idle.
+            // Keep the write queued; the status-watcher effect below retries on
+            // the next idle transition.
             return;
         }
         pendingWriteRef.current = null;
-        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;
-        }
+        const { encodedValue, options } = pending;
+        const shouldReplace = options?.replace ?? replaceOption ?? !Boolean(currentSearchValue);
         void navigate({
             to: ".",
-            // 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,
+            search: (prev) => {
+                if (getUrlLengthWithSearchParam(key, encodedValue || "", prev) <= MAX_URL_LENGTH) {
+                    return { ...prev, [key]: encodedValue };
+                }
+                else {
+                    return { ...prev, [key]: undefined };
+                }
+            },
+            hash: location.hash,
+            replace: shouldReplace,
         });
-    }, [router.state.status, replaceOption, isHash, navigate, getUrlLengthWithSearchParam, key]);
+    }, [
+        router.state.status,
+        location.hash,
+        key,
+        currentSearchValue,
+        navigate,
+        replaceOption,
+        getUrlLengthWithSearchParam,
+    ]);
     react.useEffect(() => {
-        if (router.state.status === "pending" || pendingWriteRef.current === null) {
+        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
+    // (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.
     react.useEffect(() => () => {
         pendingWriteRef.current = null;
     }, []);
-    const updateSearchParam = react.useCallback((encodedValue) => {
+    const updateSearchParam = react.useCallback((encodedValue, options) => {
         if (!enabled) {
             return;
         }
-        // Dedupe against the last committed write or the value already queued;
-        // both represent the caller's intent.
+        // 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 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.
+        // 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 (currentValueRef.current === encodedValue) {
+        if (currentSearchValue === encodedValue) {
             return;
         }
-        pendingWriteRef.current = { encodedValue };
+        pendingWriteRef.current = { encodedValue, options };
         requestAnimationFrame(() => {
             flushPendingWrite();
         });
-    }, [enabled, flushPendingWrite]);
-    return react.useMemo(() => ({ searchValue: currentValue, updateSearchParam }), [currentValue, updateSearchParam]);
+    }, [enabled, currentSearchValue, flushPendingWrite]);
+    return react.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 react.useMemo(() => (userId ? `${key}-${userId}` : key), [key, userId]);
 };
 
 /**
@@ -13917,43 +14193,47 @@ const rawLocalStorage = {
  * and writes changes to both.
  *
  * On mount the hook resolves the initial state as follows:
- *  - If the URL slot holds a value, decode it and pass through `validate`.
+ *  - 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 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.
  *
- * 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.
+ * `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.
  *
  * @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
@@ -13963,182 +14243,344 @@ 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, toUrlValue, fromUrlValue, localStorageEnabled = true, replace, clientSideUserId, mergeWithStorageOnRead = false, urlLocation = "search", stampUrlWithIdentity = false, }) => {
+const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue, enabled = true, localStorageEnabled = true, onExternalChange, 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 = react.useMemo(() => (stampUrlWithIdentity && clientSideUserId !== undefined ? identityFingerprint(clientSideUserId) : undefined), [stampUrlWithIdentity, clientSideUserId]);
-    const { searchValue: urlValue, updateSearchParam: updateUrlValue } = useUrlParamSync({
+    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({
         key,
-        location: urlLocation,
+        enabled: hashActive,
+        onExternalChange,
         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 = reactRouter.useSearch({ strict: false, shouldThrow: false });
+    const legacySearchValue = react.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 = react.useRef(toUrlValue);
     react.useEffect(() => {
         toUrlValueRef.current = toUrlValue;
     }, [toUrlValue]);
-    const readStoredState = react.useCallback((validateState) => {
-        if (!localStorageEnabled) {
-            return undefined;
-        }
-        try {
-            const raw = rawLocalStorage.read(storageKey);
-            if (!raw) {
+    const serializeRef = react.useRef(serialize);
+    react.useEffect(() => {
+        serializeRef.current = serialize;
+    }, [serialize]);
+    const validateRef = react.useRef(validate);
+    react.useEffect(() => {
+        validateRef.current = validate;
+    }, [validate]);
+    const fromUrlValueRef = react.useRef(fromUrlValue);
+    react.useEffect(() => {
+        fromUrlValueRef.current = fromUrlValue;
+    }, [fromUrlValue]);
+    const searchValueRef = react.useRef(searchValue);
+    react.useEffect(() => {
+        searchValueRef.current = searchValue;
+    }, [searchValue]);
+    const legacySearchValueRef = react.useRef(legacySearchValue);
+    react.useEffect(() => {
+        legacySearchValueRef.current = legacySearchValue;
+    }, [legacySearchValue]);
+    const readPersistedState = react.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) {
                 return undefined;
             }
-            return validateState(sharedUtils.storageSerializer.deserialize(raw));
-        }
-        catch {
-            return undefined;
-        }
-    }, [localStorageEnabled, storageKey]);
-    const readPersistedState = react.useCallback(({ valueFromUrl, validateState, transformFromUrlValue, }) => {
-        let urlState;
-        let urlStamp;
-        if (valueFromUrl) {
             try {
-                // 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 };
+                const raw = rawLocalStorage.read(storageKey);
+                if (!raw) {
+                    return undefined;
+                }
+                return validateState(sharedUtils.storageSerializer.deserialize(raw));
             }
             catch {
-                urlState = undefined;
+                return 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,
+            };
         }
-        // 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;
+        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,
+            };
         }
-        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 (urlState !== undefined) {
+            return {
+                initialState: urlState,
+                canonicalUrlHasValidState: canonicalUrlValid,
+                canonicalUrlPayload: decodedPayload,
+                needsUrlRestore: usedLegacyUrl,
+            };
         }
-        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 = react.useCallback((state) => (toUrlValueRef.current ? toUrlValueRef.current(state) : state), []);
-    // Every URL write goes through here so the ownership stamp is applied uniformly.
-    const encodeUrlWrite = react.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] = react.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 = react.useCallback((project) => initialState === undefined ? undefined : { projected: project(initialState), owner: urlOwnerSeed }, [initialState, urlOwnerSeed]);
-    const lastStoredRef = react.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 = react.useRef(seedUrlWrite(state => (toUrlValue ? toUrlValue(state) : state)));
+        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 = react.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] = react.useState(() => ({
+        ...readPersistedState({
+            valueFromUrl: searchValue,
+            legacyValueFromUrl: legacySearchValue,
+            validateState: validate,
+            transformFromUrlValue: fromUrlValue,
+        }),
+        readKey: persistedStateReadKey,
+    }));
+    const persistedStateReadKeyRef = react.useRef(persistedStateReadKey);
     react.useEffect(() => {
-        lastStoredRef.current = storedState;
-        lastUrlRef.current = seedUrlWrite(projectForUrl);
-    }, [seedUrlWrite, projectForUrl, storedState]);
-    const persistToStorage = react.useCallback((state) => {
-        if (!localStorageEnabled) {
+        if (persistedStateReadKeyRef.current === persistedStateReadKey) {
             return;
         }
-        if (state === undefined) {
-            lastStoredRef.current = undefined;
-            rawLocalStorage.remove(storageKey);
+        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.
+    react.useEffect(() => {
+        if (initialState !== undefined || canonicalUrlHasValidState) {
             return;
         }
-        if (dequal.dequal(lastStoredRef.current, state)) {
+        if (legacySearchValue === undefined) {
             return;
         }
-        try {
-            rawLocalStorage.write(storageKey, sharedUtils.storageSerializer.serialize(state));
-            lastStoredRef.current = state;
-        }
-        catch {
-            // Quota or a disabled store: the next write retries; the URL is unaffected.
-        }
-    }, [localStorageEnabled, storageKey]);
-    const persistToUrl = react.useCallback((state) => {
-        if (state === undefined) {
-            lastUrlRef.current = undefined;
-            updateUrlValue(undefined);
+        setPersistedStateSnapshot({
+            ...readPersistedState({
+                valueFromUrl: searchValueRef.current,
+                legacyValueFromUrl: legacySearchValue,
+                validateState: validateRef.current,
+                transformFromUrlValue: fromUrlValueRef.current,
+            }),
+            readKey: persistedStateReadKey,
+        });
+    }, [legacySearchValue, initialState, canonicalUrlHasValidState, persistedStateReadKey, readPersistedState]);
+    const lastPersistedRef = react.useRef(initialState);
+    react.useEffect(() => {
+        lastPersistedRef.current = initialState;
+    }, [initialState, localStorageEnabled, storageKey]);
+    const hasRestoredUrlRef = react.useRef(false);
+    react.useEffect(() => {
+        hasRestoredUrlRef.current = false;
+    }, [enabled, localStorageEnabled, storageKey, urlLocation]);
+    react.useEffect(() => {
+        if (hasRestoredUrlRef.current) {
             return;
         }
-        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.dequal(last.projected, write.projected) &&
-            (last.owner === write.owner || write.owner === undefined)) {
+        // 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) {
             return;
         }
-        lastUrlRef.current = write;
-        updateUrlValue(encodeUrlWrite(write));
-    }, [currentUrlOwner, encodeUrlWrite, projectForUrl, updateUrlValue]);
+        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: react.useCallback((migrated) => {
+            if (dequal.dequal(lastPersistedRef.current, migrated)) {
+                return;
+            }
+            lastPersistedRef.current = migrated;
+            if (localStorageEnabled) {
+                const serialized = serializeRef.current
+                    ? serializeRef.current(migrated)
+                    : sharedUtils.storageSerializer.serialize(migrated);
+                rawLocalStorage.write(storageKey, serialized);
+            }
+            updateSearchParam(encodeForUrl(migrated), { replace: true });
+        }, [encodeForUrl, localStorageEnabled, storageKey, updateSearchParam]),
+    });
     const persistState = react.useCallback((state) => {
-        persistToStorage(state);
-        persistToUrl(state);
-    }, [persistToStorage, persistToUrl]);
-    return react.useMemo(() => ({ initialState, persistState, persistToStorage, persistToUrl }), [initialState, persistState, persistToStorage, persistToUrl]);
+        if (dequal.dequal(lastPersistedRef.current, state)) {
+            return;
+        }
+        lastPersistedRef.current = state;
+        if (localStorageEnabled) {
+            const serialized = serializeRef.current ? serializeRef.current(state) : sharedUtils.storageSerializer.serialize(state);
+            rawLocalStorage.write(storageKey, serialized);
+        }
+        updateSearchParam(encodeForUrl(state));
+    }, [storageKey, encodeForUrl, localStorageEnabled, updateSearchParam]);
+    const clearState = react.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 = react.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(sharedUtils.storageSerializer.deserialize(raw));
+            }
+        }
+        catch {
+            stored = undefined;
+        }
+        if (stored !== undefined) {
+            const projected = toUrlValueRef.current ? toUrlValueRef.current(stored) : stored;
+            if (dequal.dequal(projected, canonicalUrlPayload)) {
+                return true;
+            }
+        }
+        const serialized = serializeRef.current
+            ? serializeRef.current(initialState)
+            : sharedUtils.storageSerializer.serialize(initialState);
+        rawLocalStorage.write(storageKey, serialized);
+        lastPersistedRef.current = initialState;
+        return true;
+    }, [
+        canonicalUrlHasValidState,
+        canonicalUrlPayload,
+        initialState,
+        localStorageEnabled,
+        snapshotIsCurrent,
+        storageKey,
+    ]);
+    return react.useMemo(() => ({ initialState, persistState, clearState, commitHydratedState }), [initialState, persistState, clearState, commitHydratedState]);
 };
 
-/**
- * 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`.
@@ -15502,6 +15944,7 @@ exports.LabeledValue = LabeledValue;
 exports.LabeledValueList = LabeledValueList;
 exports.List = List;
 exports.ListItem = ListItem;
+exports.MAX_HASH_LENGTH = MAX_HASH_LENGTH;
 exports.MAX_URL_LENGTH = MAX_URL_LENGTH;
 exports.MenuContent = MenuContent;
 exports.MenuDivider = MenuDivider;
@@ -15618,6 +16061,7 @@ exports.useDevicePixelRatio = useDevicePixelRatio;
 exports.useElevatedReducer = useElevatedReducer;
 exports.useElevatedState = useElevatedState;
 exports.useGridAreas = useGridAreas;
+exports.useHashParamSync = useHashParamSync;
 exports.useHold = useHold;
 exports.useHover = useHover;
 exports.useInfiniteScroll = useInfiniteScroll;