feat: add backup recovery, setup wizard and user-view guards

frontend/app/lib/viewMode.ts

@@ -1,13 +1,19 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { useEffect, useSyncExternalStore } from "react";
+import { getEffectiveRole } from "./user-view-policy";
 
 const USER_VIEW_STORAGE_KEY = "magent_user_view_preview";
 const USER_VIEW_EVENT = "magent:user-view-change";
+let fallbackPreview = false;
 
 const readUserViewPreview = () => {
   if (typeof window === "undefined") return false;
-  return window.sessionStorage.getItem(USER_VIEW_STORAGE_KEY) === "1";
+  try {
+    return window.sessionStorage.getItem(USER_VIEW_STORAGE_KEY) === "1";
+  } catch {
+    return fallbackPreview;
+  }
 };
 
 const applyDocumentMode = (enabled: boolean) => {
@@ -17,32 +23,46 @@ const applyDocumentMode = (enabled: boolean) => {
 
 export const setUserViewPreview = (enabled: boolean) => {
   if (typeof window === "undefined") return;
-  if (enabled) {
-    window.sessionStorage.setItem(USER_VIEW_STORAGE_KEY, "1");
-  } else {
-    window.sessionStorage.removeItem(USER_VIEW_STORAGE_KEY);
+  fallbackPreview = enabled;
+  try {
+    if (enabled) {
+      window.sessionStorage.setItem(USER_VIEW_STORAGE_KEY, "1");
+    } else {
+      window.sessionStorage.removeItem(USER_VIEW_STORAGE_KEY);
+    }
+  } catch {
+    // Preview still works for this document when browser storage is unavailable.
   }
   applyDocumentMode(enabled);
   window.dispatchEvent(new CustomEvent(USER_VIEW_EVENT, { detail: { enabled } }));
 };
 
-export const useUserViewPreview = () => {
-  const [enabled, setEnabled] = useState(false);
+const subscribe = (notify: () => void) => {
+  window.addEventListener(USER_VIEW_EVENT, notify);
+  window.addEventListener("storage", notify);
+  return () => {
+    window.removeEventListener(USER_VIEW_EVENT, notify);
+    window.removeEventListener("storage", notify);
+  };
+};
+
+// Unknown during server rendering/initial hydration: admin pages must not mount
+// and fetch privileged data before the saved per-tab preview mode is known.
+const serverSnapshot = (): boolean | null => null;
+
+export const useUserViewState = () => {
+  const value = useSyncExternalStore(subscribe, readUserViewPreview, serverSnapshot);
 
   useEffect(() => {
-    const sync = () => {
-      const nextValue = readUserViewPreview();
-      applyDocumentMode(nextValue);
-      setEnabled(nextValue);
-    };
-    sync();
-    window.addEventListener(USER_VIEW_EVENT, sync);
-    window.addEventListener("storage", sync);
-    return () => {
-      window.removeEventListener(USER_VIEW_EVENT, sync);
-      window.removeEventListener("storage", sync);
-    };
-  }, []);
+    if (value !== null) applyDocumentMode(value);
+  }, [value]);
 
-  return enabled;
+  return { enabled: value === true, ready: value !== null };
+};
+
+export const useUserViewPreview = () => useUserViewState().enabled;
+
+export const useEffectiveRole = (role?: string | null) => {
+  const { enabled, ready } = useUserViewState();
+  return getEffectiveRole(role, !ready || enabled);
 };