@trackunit/react-components 3.4.2 → 3.4.5

package/README.md

@@ -5,6 +5,8 @@ This library is exposed publicly for use in the  the Trackunit [Iris App SDK](ht
 
 To browse all available components visit the [Design System](https://design.iris.trackunit.com/).
 
+AI agents should use the machine-readable index at [`/llms.txt`](https://design.iris.trackunit.com/llms.txt) instead of the Storybook HTML; it links to per-component docs at `/ai?storyId=<id>`.
+
 For more info and a full guide on Iris App SDK Development, please visit our [Developer Hub](https://developers.trackunit.com/).
 
 ## Development

package/index.cjs.js

@@ -13696,6 +13696,76 @@ const readPrimitiveSearchParam = (search, key) => {
     return String(parsedValue.data);
 };
 
+/**
+ * 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 };
+};
+
 /**
  * One-shot migration: if the URL still carries a legacy `?<key>=...`
  * search param from before this hook moved table-style state to the
@@ -14008,6 +14078,41 @@ const rawLocalStorage = {
     read: (key) => localStorage.getItem(key),
     write: (key, value) => localStorage.setItem(key, value),
     remove: (key) => localStorage.removeItem(key),
+    keys: () => {
+        const keys = [];
+        for (let index = 0; index < localStorage.length; index++) {
+            const key = localStorage.key(index);
+            if (key !== null) {
+                keys.push(key);
+            }
+        }
+        return keys;
+    },
+};
+/* eslint-enable no-restricted-globals */
+/**
+ * Whether some *other* identity that has used this browser wrote the URL
+ * value: `owner` is the fingerprint of a user id that has state stored under
+ * `key` in this localStorage. Storage keys are `<key>-<clientSideUserId>`
+ * (see `useStorageKey`), so the ids can be recovered from the keys.
+ *
+ * A value with no owner, or one written on another device (no matching
+ * storage here), is not foreign: that is a link someone shared.
+ */
+const isUrlOwnedByOtherLocalIdentity = (key, owner, currentOwner) => {
+    if (owner === undefined || currentOwner === undefined || owner === currentOwner) {
+        return false;
+    }
+    const prefix = `${key}-`;
+    try {
+        return rawLocalStorage
+            .keys()
+            .filter(storageKey => storageKey.startsWith(prefix))
+            .some(storageKey => identityFingerprint(storageKey.slice(prefix.length)) === owner);
+    }
+    catch {
+        return false;
+    }
 };
 /**
  * Generic persistence hook that loads state from a URL slot (search param
@@ -14052,9 +14157,16 @@ const rawLocalStorage = {
  *   state on read (URL wins on shared keys). Use when `toUrlValue` deliberately
  *   omits fields so they still survive via localStorage. Default `false`.
  * @param options.urlLocation - Which URL slot backs the value (`"search"` or `"hash"`). Default `"search"`.
+ * @param options.scopeUrlToIdentity - Stamp URL writes with the current identity and ignore
+ *   URL values written by another identity that has state in this browser. Default `false`.
  */
-const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue, enabled = true, localStorageEnabled = true, onExternalChange, replace, clientSideUserId, mergeWithStorageOnRead = false, urlLocation = "search", }) => {
+const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue, enabled = true, localStorageEnabled = true, onExternalChange, replace, clientSideUserId, mergeWithStorageOnRead = false, urlLocation = "search", scopeUrlToIdentity = false, }) => {
     const { encode, decode } = useCustomEncoding();
+    // Fingerprint of the identity this hook writes URL values for. `undefined`
+    // while the identity is unresolved (or when scoping is off): writes are then
+    // unstamped and no URL value is treated as foreign. The read below re-runs
+    // once `storageKey` picks up the resolved identity.
+    const currentUrlOwner = react.useMemo(() => (scopeUrlToIdentity && clientSideUserId !== undefined ? identityFingerprint(clientSideUserId) : undefined), [scopeUrlToIdentity, clientSideUserId]);
     const searchActive = enabled && urlLocation === "search";
     const hashActive = enabled && urlLocation === "hash";
     // Both URL-sync hooks are mounted unconditionally to satisfy the Rules of
@@ -14112,9 +14224,24 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
     const readPersistedState = react.useCallback(({ valueFromUrl, legacyValueFromUrl, validateState, transformFromUrlValue, }) => {
         const tryDecode = (raw) => {
             try {
-                const decoded = decode(raw);
-                const transformed = transformFromUrlValue ? transformFromUrlValue(decoded) : decoded;
-                return validateState(transformed);
+                const { owner, value } = unwrapUrlOwner(decode(raw));
+                const transformed = transformFromUrlValue ? transformFromUrlValue(value) : value;
+                return { state: validateState(transformed), owner };
+            }
+            catch {
+                return { state: undefined, owner: undefined };
+            }
+        };
+        const readStoredState = () => {
+            if (!localStorageEnabled) {
+                return undefined;
+            }
+            try {
+                const raw = rawLocalStorage.read(storageKey);
+                if (!raw) {
+                    return undefined;
+                }
+                return validateState(sharedUtils.storageSerializer.deserialize(raw));
             }
             catch {
                 return undefined;
@@ -14123,14 +14250,30 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
         let urlState;
         let canonicalUrlValid = false;
         let usedLegacyUrl = false;
+        let rejectedAsForeign = false;
         if (enabled && valueFromUrl) {
-            urlState = tryDecode(valueFromUrl);
+            const decoded = tryDecode(valueFromUrl);
+            // Another account on this browser left its state in the URL, or an
+            // unstamped bookmark/history entry would override a layout this user
+            // already saved. Treat the slot as empty so this user's storage wins
+            // and the restore effect below overwrites the stale entry.
+            const unstampedOverSavedState = scopeUrlToIdentity &&
+                decoded.owner === undefined &&
+                decoded.state !== undefined &&
+                currentUrlOwner !== undefined &&
+                readStoredState() !== undefined;
+            rejectedAsForeign =
+                unstampedOverSavedState ||
+                    (scopeUrlToIdentity && isUrlOwnedByOtherLocalIdentity(key, decoded.owner, currentUrlOwner));
+            urlState = rejectedAsForeign ? undefined : decoded.state;
             if (urlState !== undefined) {
                 canonicalUrlValid = true;
             }
         }
-        if (urlState === undefined && enabled && legacyValueFromUrl) {
-            urlState = tryDecode(legacyValueFromUrl);
+        // A legacy `?<key>=...` param next to a foreign hash came from the same
+        // other-account session, so it must not stand in for the rejected hash.
+        if (urlState === undefined && !rejectedAsForeign && enabled && legacyValueFromUrl) {
+            urlState = tryDecode(legacyValueFromUrl).state;
             if (urlState !== undefined) {
                 usedLegacyUrl = true;
             }
@@ -14142,21 +14285,10 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
                 initialState: urlState,
                 canonicalUrlHasValidState: canonicalUrlValid,
                 needsUrlRestore: usedLegacyUrl,
+                urlRejectedAsForeign: rejectedAsForeign,
             };
         }
-        let storageState;
-        if (localStorageEnabled) {
-            try {
-                const raw = rawLocalStorage.read(storageKey);
-                if (raw) {
-                    const parsed = sharedUtils.storageSerializer.deserialize(raw);
-                    storageState = validateState(parsed);
-                }
-            }
-            catch {
-                // no valid stored state
-            }
-        }
+        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`).
@@ -14164,6 +14296,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
                 initialState: { ...storageState, ...urlState },
                 canonicalUrlHasValidState: canonicalUrlValid,
                 needsUrlRestore: usedLegacyUrl,
+                urlRejectedAsForeign: rejectedAsForeign,
             };
         }
         if (urlState !== undefined) {
@@ -14171,6 +14304,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
                 initialState: urlState,
                 canonicalUrlHasValidState: canonicalUrlValid,
                 needsUrlRestore: usedLegacyUrl,
+                urlRejectedAsForeign: rejectedAsForeign,
             };
         }
         if (storageState !== undefined) {
@@ -14178,14 +14312,22 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
                 initialState: storageState,
                 canonicalUrlHasValidState: false,
                 needsUrlRestore: true,
+                urlRejectedAsForeign: rejectedAsForeign,
             };
         }
         return {
             initialState: undefined,
             canonicalUrlHasValidState: false,
             needsUrlRestore: false,
+            urlRejectedAsForeign: rejectedAsForeign,
         };
-    }, [decode, enabled, localStorageEnabled, storageKey, mergeWithStorageOnRead]);
+    }, [decode, enabled, localStorageEnabled, storageKey, mergeWithStorageOnRead, scopeUrlToIdentity, key, currentUrlOwner]);
+    // Every URL write goes through here so the ownership stamp is applied
+    // uniformly (user edits, storage→URL restore, 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 [persistedStateSnapshot, setPersistedStateSnapshot] = react.useState(() => readPersistedState({
         valueFromUrl: searchValue,
         legacyValueFromUrl: legacySearchValue,
@@ -14206,7 +14348,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             transformFromUrlValue: fromUrlValueRef.current,
         }));
     }, [persistedStateReadKey, readPersistedState]);
-    const { initialState, canonicalUrlHasValidState, needsUrlRestore } = persistedStateSnapshot;
+    const { initialState, canonicalUrlHasValidState, needsUrlRestore, urlRejectedAsForeign } = 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
@@ -14217,11 +14359,13 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
     // `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.
+    //   - a legacy value has just appeared, and
+    //   - the canonical slot was not rejected (a legacy value next to a foreign
+    //     or unstamped-over-saved hash is ignored by the read anyway).
     // 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) {
+        if (initialState !== undefined || canonicalUrlHasValidState || urlRejectedAsForeign) {
             return;
         }
         if (legacySearchValue === undefined) {
@@ -14233,7 +14377,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             validateState: validateRef.current,
             transformFromUrlValue: fromUrlValueRef.current,
         }));
-    }, [legacySearchValue, initialState, canonicalUrlHasValidState, readPersistedState]);
+    }, [legacySearchValue, initialState, canonicalUrlHasValidState, urlRejectedAsForeign, readPersistedState]);
     const lastPersistedRef = react.useRef(initialState);
     react.useEffect(() => {
         lastPersistedRef.current = initialState;
@@ -14255,10 +14399,8 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             return;
         }
         hasRestoredUrlRef.current = true;
-        const urlValue = toUrlValueRef.current ? toUrlValueRef.current(initialState) : initialState;
-        const encoded = encode(urlValue);
-        updateSearchParam(encoded, { replace: true });
-    }, [enabled, needsUrlRestore, initialState, canonicalUrlHasValidState, updateSearchParam, encode]);
+        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
@@ -14266,13 +14408,16 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
     // 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).
+    // A rejected hash counts as "already has a value" too. The legacy param
+    // beside a foreign stamp or an unstamped hash that lost to saved state is
+    // stripped without being written into this user's storage or hash.
     useMigrateLegacySearchParam({
         key,
         enabled: hashActive,
         decode,
         fromUrlValue,
         validate,
-        hashAlreadyHasValue: canonicalUrlHasValidState,
+        hashAlreadyHasValue: canonicalUrlHasValidState || urlRejectedAsForeign,
         onMigrated: react.useCallback((migrated) => {
             if (dequal.dequal(lastPersistedRef.current, migrated)) {
                 return;
@@ -14284,10 +14429,8 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
                     : sharedUtils.storageSerializer.serialize(migrated);
                 rawLocalStorage.write(storageKey, serialized);
             }
-            const urlValue = toUrlValueRef.current ? toUrlValueRef.current(migrated) : migrated;
-            const encoded = encode(urlValue);
-            updateSearchParam(encoded, { replace: true });
-        }, [encode, localStorageEnabled, storageKey, updateSearchParam]),
+            updateSearchParam(encodeForUrl(migrated), { replace: true });
+        }, [encodeForUrl, localStorageEnabled, storageKey, updateSearchParam]),
     });
     const persistState = react.useCallback((state) => {
         if (dequal.dequal(lastPersistedRef.current, state)) {
@@ -14298,10 +14441,8 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             const serialized = serializeRef.current ? serializeRef.current(state) : sharedUtils.storageSerializer.serialize(state);
             rawLocalStorage.write(storageKey, serialized);
         }
-        const urlValue = toUrlValueRef.current ? toUrlValueRef.current(state) : state;
-        const encoded = encode(urlValue);
-        updateSearchParam(encoded);
-    }, [storageKey, encode, localStorageEnabled, updateSearchParam]);
+        updateSearchParam(encodeForUrl(state));
+    }, [storageKey, encodeForUrl, localStorageEnabled, updateSearchParam]);
     const clearState = react.useCallback(() => {
         lastPersistedRef.current = undefined;
         if (localStorageEnabled) {

package/index.esm.js

@@ -13695,6 +13695,76 @@ const readPrimitiveSearchParam = (search, key) => {
     return String(parsedValue.data);
 };
 
+/**
+ * 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
@@ -14007,6 +14077,41 @@ const rawLocalStorage = {
     read: (key) => localStorage.getItem(key),
     write: (key, value) => localStorage.setItem(key, value),
     remove: (key) => localStorage.removeItem(key),
+    keys: () => {
+        const keys = [];
+        for (let index = 0; index < localStorage.length; index++) {
+            const key = localStorage.key(index);
+            if (key !== null) {
+                keys.push(key);
+            }
+        }
+        return keys;
+    },
+};
+/* eslint-enable no-restricted-globals */
+/**
+ * Whether some *other* identity that has used this browser wrote the URL
+ * value: `owner` is the fingerprint of a user id that has state stored under
+ * `key` in this localStorage. Storage keys are `<key>-<clientSideUserId>`
+ * (see `useStorageKey`), so the ids can be recovered from the keys.
+ *
+ * A value with no owner, or one written on another device (no matching
+ * storage here), is not foreign: that is a link someone shared.
+ */
+const isUrlOwnedByOtherLocalIdentity = (key, owner, currentOwner) => {
+    if (owner === undefined || currentOwner === undefined || owner === currentOwner) {
+        return false;
+    }
+    const prefix = `${key}-`;
+    try {
+        return rawLocalStorage
+            .keys()
+            .filter(storageKey => storageKey.startsWith(prefix))
+            .some(storageKey => identityFingerprint(storageKey.slice(prefix.length)) === owner);
+    }
+    catch {
+        return false;
+    }
 };
 /**
  * Generic persistence hook that loads state from a URL slot (search param
@@ -14051,9 +14156,16 @@ const rawLocalStorage = {
  *   state on read (URL wins on shared keys). Use when `toUrlValue` deliberately
  *   omits fields so they still survive via localStorage. Default `false`.
  * @param options.urlLocation - Which URL slot backs the value (`"search"` or `"hash"`). Default `"search"`.
+ * @param options.scopeUrlToIdentity - Stamp URL writes with the current identity and ignore
+ *   URL values written by another identity that has state in this browser. Default `false`.
  */
-const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue, enabled = true, localStorageEnabled = true, onExternalChange, replace, clientSideUserId, mergeWithStorageOnRead = false, urlLocation = "search", }) => {
+const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue, enabled = true, localStorageEnabled = true, onExternalChange, replace, clientSideUserId, mergeWithStorageOnRead = false, urlLocation = "search", scopeUrlToIdentity = false, }) => {
     const { encode, decode } = useCustomEncoding();
+    // Fingerprint of the identity this hook writes URL values for. `undefined`
+    // while the identity is unresolved (or when scoping is off): writes are then
+    // unstamped and no URL value is treated as foreign. The read below re-runs
+    // once `storageKey` picks up the resolved identity.
+    const currentUrlOwner = useMemo(() => (scopeUrlToIdentity && clientSideUserId !== undefined ? identityFingerprint(clientSideUserId) : undefined), [scopeUrlToIdentity, clientSideUserId]);
     const searchActive = enabled && urlLocation === "search";
     const hashActive = enabled && urlLocation === "hash";
     // Both URL-sync hooks are mounted unconditionally to satisfy the Rules of
@@ -14111,9 +14223,24 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
     const readPersistedState = useCallback(({ valueFromUrl, legacyValueFromUrl, validateState, transformFromUrlValue, }) => {
         const tryDecode = (raw) => {
             try {
-                const decoded = decode(raw);
-                const transformed = transformFromUrlValue ? transformFromUrlValue(decoded) : decoded;
-                return validateState(transformed);
+                const { owner, value } = unwrapUrlOwner(decode(raw));
+                const transformed = transformFromUrlValue ? transformFromUrlValue(value) : value;
+                return { state: validateState(transformed), owner };
+            }
+            catch {
+                return { state: undefined, owner: undefined };
+            }
+        };
+        const readStoredState = () => {
+            if (!localStorageEnabled) {
+                return undefined;
+            }
+            try {
+                const raw = rawLocalStorage.read(storageKey);
+                if (!raw) {
+                    return undefined;
+                }
+                return validateState(storageSerializer.deserialize(raw));
             }
             catch {
                 return undefined;
@@ -14122,14 +14249,30 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
         let urlState;
         let canonicalUrlValid = false;
         let usedLegacyUrl = false;
+        let rejectedAsForeign = false;
         if (enabled && valueFromUrl) {
-            urlState = tryDecode(valueFromUrl);
+            const decoded = tryDecode(valueFromUrl);
+            // Another account on this browser left its state in the URL, or an
+            // unstamped bookmark/history entry would override a layout this user
+            // already saved. Treat the slot as empty so this user's storage wins
+            // and the restore effect below overwrites the stale entry.
+            const unstampedOverSavedState = scopeUrlToIdentity &&
+                decoded.owner === undefined &&
+                decoded.state !== undefined &&
+                currentUrlOwner !== undefined &&
+                readStoredState() !== undefined;
+            rejectedAsForeign =
+                unstampedOverSavedState ||
+                    (scopeUrlToIdentity && isUrlOwnedByOtherLocalIdentity(key, decoded.owner, currentUrlOwner));
+            urlState = rejectedAsForeign ? undefined : decoded.state;
             if (urlState !== undefined) {
                 canonicalUrlValid = true;
             }
         }
-        if (urlState === undefined && enabled && legacyValueFromUrl) {
-            urlState = tryDecode(legacyValueFromUrl);
+        // A legacy `?<key>=...` param next to a foreign hash came from the same
+        // other-account session, so it must not stand in for the rejected hash.
+        if (urlState === undefined && !rejectedAsForeign && enabled && legacyValueFromUrl) {
+            urlState = tryDecode(legacyValueFromUrl).state;
             if (urlState !== undefined) {
                 usedLegacyUrl = true;
             }
@@ -14141,21 +14284,10 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
                 initialState: urlState,
                 canonicalUrlHasValidState: canonicalUrlValid,
                 needsUrlRestore: usedLegacyUrl,
+                urlRejectedAsForeign: rejectedAsForeign,
             };
         }
-        let storageState;
-        if (localStorageEnabled) {
-            try {
-                const raw = rawLocalStorage.read(storageKey);
-                if (raw) {
-                    const parsed = storageSerializer.deserialize(raw);
-                    storageState = validateState(parsed);
-                }
-            }
-            catch {
-                // no valid stored state
-            }
-        }
+        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`).
@@ -14163,6 +14295,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
                 initialState: { ...storageState, ...urlState },
                 canonicalUrlHasValidState: canonicalUrlValid,
                 needsUrlRestore: usedLegacyUrl,
+                urlRejectedAsForeign: rejectedAsForeign,
             };
         }
         if (urlState !== undefined) {
@@ -14170,6 +14303,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
                 initialState: urlState,
                 canonicalUrlHasValidState: canonicalUrlValid,
                 needsUrlRestore: usedLegacyUrl,
+                urlRejectedAsForeign: rejectedAsForeign,
             };
         }
         if (storageState !== undefined) {
@@ -14177,14 +14311,22 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
                 initialState: storageState,
                 canonicalUrlHasValidState: false,
                 needsUrlRestore: true,
+                urlRejectedAsForeign: rejectedAsForeign,
             };
         }
         return {
             initialState: undefined,
             canonicalUrlHasValidState: false,
             needsUrlRestore: false,
+            urlRejectedAsForeign: rejectedAsForeign,
         };
-    }, [decode, enabled, localStorageEnabled, storageKey, mergeWithStorageOnRead]);
+    }, [decode, enabled, localStorageEnabled, storageKey, mergeWithStorageOnRead, scopeUrlToIdentity, key, currentUrlOwner]);
+    // Every URL write goes through here so the ownership stamp is applied
+    // uniformly (user edits, storage→URL restore, 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 [persistedStateSnapshot, setPersistedStateSnapshot] = useState(() => readPersistedState({
         valueFromUrl: searchValue,
         legacyValueFromUrl: legacySearchValue,
@@ -14205,7 +14347,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             transformFromUrlValue: fromUrlValueRef.current,
         }));
     }, [persistedStateReadKey, readPersistedState]);
-    const { initialState, canonicalUrlHasValidState, needsUrlRestore } = persistedStateSnapshot;
+    const { initialState, canonicalUrlHasValidState, needsUrlRestore, urlRejectedAsForeign } = 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
@@ -14216,11 +14358,13 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
     // `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.
+    //   - a legacy value has just appeared, and
+    //   - the canonical slot was not rejected (a legacy value next to a foreign
+    //     or unstamped-over-saved hash is ignored by the read anyway).
     // 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) {
+        if (initialState !== undefined || canonicalUrlHasValidState || urlRejectedAsForeign) {
             return;
         }
         if (legacySearchValue === undefined) {
@@ -14232,7 +14376,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             validateState: validateRef.current,
             transformFromUrlValue: fromUrlValueRef.current,
         }));
-    }, [legacySearchValue, initialState, canonicalUrlHasValidState, readPersistedState]);
+    }, [legacySearchValue, initialState, canonicalUrlHasValidState, urlRejectedAsForeign, readPersistedState]);
     const lastPersistedRef = useRef(initialState);
     useEffect(() => {
         lastPersistedRef.current = initialState;
@@ -14254,10 +14398,8 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             return;
         }
         hasRestoredUrlRef.current = true;
-        const urlValue = toUrlValueRef.current ? toUrlValueRef.current(initialState) : initialState;
-        const encoded = encode(urlValue);
-        updateSearchParam(encoded, { replace: true });
-    }, [enabled, needsUrlRestore, initialState, canonicalUrlHasValidState, updateSearchParam, encode]);
+        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
@@ -14265,13 +14407,16 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
     // 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).
+    // A rejected hash counts as "already has a value" too. The legacy param
+    // beside a foreign stamp or an unstamped hash that lost to saved state is
+    // stripped without being written into this user's storage or hash.
     useMigrateLegacySearchParam({
         key,
         enabled: hashActive,
         decode,
         fromUrlValue,
         validate,
-        hashAlreadyHasValue: canonicalUrlHasValidState,
+        hashAlreadyHasValue: canonicalUrlHasValidState || urlRejectedAsForeign,
         onMigrated: useCallback((migrated) => {
             if (dequal(lastPersistedRef.current, migrated)) {
                 return;
@@ -14283,10 +14428,8 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
                     : storageSerializer.serialize(migrated);
                 rawLocalStorage.write(storageKey, serialized);
             }
-            const urlValue = toUrlValueRef.current ? toUrlValueRef.current(migrated) : migrated;
-            const encoded = encode(urlValue);
-            updateSearchParam(encoded, { replace: true });
-        }, [encode, localStorageEnabled, storageKey, updateSearchParam]),
+            updateSearchParam(encodeForUrl(migrated), { replace: true });
+        }, [encodeForUrl, localStorageEnabled, storageKey, updateSearchParam]),
     });
     const persistState = useCallback((state) => {
         if (dequal(lastPersistedRef.current, state)) {
@@ -14297,10 +14440,8 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             const serialized = serializeRef.current ? serializeRef.current(state) : storageSerializer.serialize(state);
             rawLocalStorage.write(storageKey, serialized);
         }
-        const urlValue = toUrlValueRef.current ? toUrlValueRef.current(state) : state;
-        const encoded = encode(urlValue);
-        updateSearchParam(encoded);
-    }, [storageKey, encode, localStorageEnabled, updateSearchParam]);
+        updateSearchParam(encodeForUrl(state));
+    }, [storageKey, encodeForUrl, localStorageEnabled, updateSearchParam]);
     const clearState = useCallback(() => {
         lastPersistedRef.current = undefined;
         if (localStorageEnabled) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "3.4.2",
+  "version": "3.4.5",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "migrations": "./migrations.json",
@@ -14,16 +14,16 @@
     "@floating-ui/react": "^0.26.25",
     "string-ts": "^2.0.0",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/ui-design-tokens": "1.16.2",
-    "@trackunit/css-class-variance-utilities": "2.1.2",
-    "@trackunit/shared-utils": "1.17.2",
-    "@trackunit/ui-icons": "1.15.2",
+    "@trackunit/ui-design-tokens": "1.16.4",
+    "@trackunit/css-class-variance-utilities": "2.1.4",
+    "@trackunit/shared-utils": "1.17.4",
+    "@trackunit/ui-icons": "1.15.4",
     "es-toolkit": "^1.39.10",
     "@tanstack/react-virtual": "^3.14.3",
     "dequal": "^2.0.3",
     "fflate": "^0.8.2",
     "zod": "^3.25.76",
-    "@trackunit/i18n-library-translation": "2.6.2"
+    "@trackunit/i18n-library-translation": "2.6.4"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/hooks/persistence/urlIdentity.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ */
+import { z } from "zod";
+/**
+ * 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}).
+ */
+declare const stampedUrlValueSchema: z.ZodObject<{
+    o: z.ZodString;
+    v: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    o: string;
+    v?: unknown;
+}, {
+    o: string;
+    v?: unknown;
+}>;
+type StampedUrlValue = z.infer<typeof stampedUrlValueSchema>;
+/**
+ * 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`.
+ */
+export declare const identityFingerprint: (identity: string) => string;
+/**
+ * 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.
+ */
+export declare const wrapUrlOwner: (value: unknown, owner: string) => StampedUrlValue;
+/**
+ * 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.
+ */
+export declare const unwrapUrlOwner: (decoded: unknown) => {
+    readonly owner: string | undefined;
+    readonly value: unknown;
+};
+export {};

package/src/hooks/persistence/usePersistedState.d.ts

@@ -39,6 +39,25 @@ type UsePersistedStateOptions<TState> = {
      * See {@link UrlPersistenceLocation} for the trade-offs.
      */
     readonly urlLocation?: UrlPersistenceLocation;
+    /**
+     * When `true`, every URL write is stamped with a fingerprint of
+     * `clientSideUserId`, and a URL value stamped by a *different* identity
+     * that also has state stored in this browser (under the same `key`) is
+     * ignored on read — the current user's localStorage wins and is written
+     * back over the stale URL entry.
+     *
+     * The URL is shared by every account that signs in from the same browser
+     * (history, bookmarks, login redirects carry it along) and it takes
+     * precedence over per-user storage, so without this the previous account's
+     * state replaces the next account's saved state (GLU-2396).
+     *
+     * Values stamped by an identity with no storage here (a link shared from
+     * another device) still render. An unstamped value written before this
+     * option existed renders only when the current user has nothing saved;
+     * otherwise their localStorage wins and the hash is restamped, because a
+     * bookmark or history entry is never rewritten on its own. Default `false`.
+     */
+    readonly scopeUrlToIdentity?: boolean;
 };
 type UsePersistedStateReturn<TState> = {
     readonly initialState: TState | undefined;
@@ -88,6 +107,8 @@ type UsePersistedStateReturn<TState> = {
  *   state on read (URL wins on shared keys). Use when `toUrlValue` deliberately
  *   omits fields so they still survive via localStorage. Default `false`.
  * @param options.urlLocation - Which URL slot backs the value (`"search"` or `"hash"`). Default `"search"`.
+ * @param options.scopeUrlToIdentity - Stamp URL writes with the current identity and ignore
+ *   URL values written by another identity that has state in this browser. Default `false`.
  */
-export declare const usePersistedState: <TState extends object>({ key, validate, serialize, toUrlValue, fromUrlValue, enabled, localStorageEnabled, onExternalChange, replace, clientSideUserId, mergeWithStorageOnRead, urlLocation, }: UsePersistedStateOptions<TState>) => UsePersistedStateReturn<TState>;
+export declare const usePersistedState: <TState extends object>({ key, validate, serialize, toUrlValue, fromUrlValue, enabled, localStorageEnabled, onExternalChange, replace, clientSideUserId, mergeWithStorageOnRead, urlLocation, scopeUrlToIdentity, }: UsePersistedStateOptions<TState>) => UsePersistedStateReturn<TState>;
 export {};