@rindle/optimistic 0.4.4 → 0.6.3

package/src/client-id.ts

@@ -1,3 +1,5 @@
+import type { TicketPersistence } from "@rindle/remote";
+
 // The connection's stable clientID — kept in its own (wasm-free) module so it can be unit-tested
 // without pulling the engine in. A per-ORIGIN base (localStorage) shared by every tab and kept
 // across reloads, a per-TAB suffix (sessionStorage) that survives a reload within a tab but is
@@ -10,6 +12,12 @@
 const CLIENT_ID_KEY = "rindle-client-id";
 /** The per-TAB suffix (sessionStorage): survives a reload within a tab but is distinct per tab. */
 const TAB_ID_KEY = "rindle-tab-id";
+/** The per-TAB follower-affinity ticket (sessionStorage): kept across a reload WITHIN a tab (so a
+ *  reload lands back on the same follower — monotone reads survive it, FOLLOWER-AFFINITY-DESIGN.md
+ *  §8), but DISTINCT per tab so two tabs can pin two regions (design §13; a shared localStorage
+ *  ticket would force both onto one follower). The ticket is opaque and short-lived — the follower
+ *  re-mints one on every connect — so losing it (no sessionStorage) merely re-anycasts. */
+const AFFINITY_TICKET_KEY = "rindle-affinity-ticket";
 
 /** Read-or-mint a value in a web Storage area, tolerating its absence (SSR, privacy mode). Returns
  *  `undefined` when the area is unavailable so the caller can pick a fallback. */
@@ -55,6 +63,42 @@ export function resetStableClientID(): void {
   tabInstance = 0;
 }
 
+/** A sessionStorage-backed {@link TicketPersistence} for the affinity ticket — per-tab, survives a
+ *  reload (see {@link AFFINITY_TICKET_KEY}). Every access tolerates web storage being absent (SSR,
+ *  private mode): the store then behaves as pure in-memory, re-anycasting on each fresh load. */
+export function sessionTicketPersistence(): TicketPersistence {
+  const area = () => {
+    try {
+      return (globalThis as unknown as Record<string, Storage | undefined>).sessionStorage;
+    } catch {
+      return undefined;
+    }
+  };
+  return {
+    load: () => {
+      try {
+        return area()?.getItem(AFFINITY_TICKET_KEY) ?? undefined;
+      } catch {
+        return undefined;
+      }
+    },
+    save: (ticket) => {
+      try {
+        area()?.setItem(AFFINITY_TICKET_KEY, ticket);
+      } catch {
+        // Best-effort persistence; a full/blocked store just means we re-anycast on the next load.
+      }
+    },
+    clear: () => {
+      try {
+        area()?.removeItem(AFFINITY_TICKET_KEY);
+      } catch {
+        // Best-effort.
+      }
+    },
+  };
+}
+
 /** The connection's stable clientID. A per-origin base (localStorage) keeps one logical identity
  *  across reloads; a per-tab suffix (sessionStorage) gives each tab its OWN mid/lmid stream; a
  *  per-load instance suffix keeps two clients constructed in ONE tab from sharing that stream. Falls