@interop/was-react 0.1.5 → 0.1.7

package/dist/mui/ProtectedRoute.js

@@ -3,17 +3,26 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * Copyright (c) 2026 Interop Alliance. All rights reserved.
  */
 /**
- * The auth + hydration gate (wallet mode). Attempts the zero-popup session
- * restore; an unauthenticated visitor is redirected to the login path, and the
- * routed pages render only once the restored session has hydrated the stores.
+ * The router gate: a thin switch over the app's `onboarding` mode. While the
+ * session is booting it shows a spinner; a `local-first` app then always renders
+ * the routed pages (over the anonymous replica), while a `login-gated` app
+ * renders them only once the wallet is connected and otherwise redirects to the
+ * login path. Uses react-router's `Navigate` / `Outlet`.
  *
- * Apps with a local dev mode wrap their own gate; this component is wallet-mode
- * only. Uses react-router's `Navigate` / `Outlet`.
+ * Boot is kicked off by {@link WasSessionProvider} on mount, not here, so a
+ * local-first app that never mounts this component still boots.
+ *
+ * The fatal-error alert (`data-testid="bootstrap-error"`) is scoped to
+ * boot/storage failures ONLY: it renders solely while `status === 'boot'` with
+ * an `error`, which the store only produces when even the anonymous local
+ * replica cannot be opened. A failed or cancelled wallet login (or a reconnect
+ * failure) sets the store's `error` too, but only after `status` has left `boot`
+ * (to `local` / `reconnect`), so it never blanks a local-first app with this
+ * alert -- the login page surfaces that error instead.
  */
-import { useEffect } from 'react';
 import { Navigate, Outlet } from 'react-router';
 import { Alert, Box, CircularProgress, Typography } from '@mui/material';
-import { useAppReady, useAuthStore, useSession } from '../react/hooks.js';
+import { useSession } from '../react/hooks.js';
 function CenteredSpinner({ label }) {
     return (_jsxs(Box, { sx: {
             display: 'flex',
@@ -26,29 +35,27 @@ function CenteredSpinner({ label }) {
 }
 /**
  * @param props {object}
- * @param [props.loginPath] {string}   where to send an unauthenticated visitor
- *   (defaults to `/login`)
+ * @param [props.loginPath] {string}   where to send a not-yet-connected visitor
+ *   in a login-gated app (defaults to `/login`)
  * @returns {ReactNode}
  */
 export function ProtectedRoute({ loginPath = '/login' } = {}) {
-    const store = useAuthStore();
-    const { status } = useSession();
-    const { ready, error } = useAppReady();
-    useEffect(() => {
-        void store.getState().restore();
-    }, [store]);
-    if (error) {
+    const { status, onboarding, error } = useSession();
+    // Only a boot/storage failure (error present while still in `boot`) replaces
+    // the app with the fatal alert; a login/reconnect error never reaches here.
+    if (status === 'boot' && error) {
         return (_jsx(Box, { sx: { p: 4 }, children: _jsxs(Alert, { severity: "error", "data-testid": "bootstrap-error", children: ["Failed to open local storage: ", error] }) }));
     }
-    if (status === 'idle' || status === 'restoring') {
-        return _jsx(CenteredSpinner, { label: "Restoring your session..." });
+    if (status === 'boot') {
+        return _jsx(CenteredSpinner, { label: "Loading..." });
     }
-    if (status !== 'authenticated') {
-        return _jsx(Navigate, { to: loginPath, replace: true });
+    if (onboarding === 'local-first') {
+        return _jsx(Outlet, {});
     }
-    if (!ready) {
-        return _jsx(CenteredSpinner, { label: "Opening your storage..." });
+    // login-gated: the app is reachable only once a wallet is connected.
+    if (status === 'connected' || status === 'reconnect') {
+        return _jsx(Outlet, {});
     }
-    return _jsx(Outlet, {});
+    return _jsx(Navigate, { to: loginPath, replace: true });
 }
 //# sourceMappingURL=ProtectedRoute.js.map

package/dist/mui/ProtectedRoute.js.map

@@ -1 +1 @@
-{"version":3,"file":"ProtectedRoute.js","sourceRoot":"","sources":["../../src/mui/ProtectedRoute.tsx"],"names":[],"mappings":";AAAA;;GAEG;AACH;;;;;;;GAOG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AACxE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEzE,SAAS,eAAe,CAAC,EAAE,KAAK,EAAqB;IACnD,OAAO,CACL,MAAC,GAAG,IACF,EAAE,EAAE;YACF,OAAO,EAAE,MAAM;YACf,aAAa,EAAE,QAAQ;YACvB,UAAU,EAAE,QAAQ;YACpB,cAAc,EAAE,QAAQ;YACxB,GAAG,EAAE,CAAC;YACN,SAAS,EAAE,MAAM;SAClB,iBACW,mBAAmB,aAE/B,KAAC,gBAAgB,KAAG,EACpB,KAAC,UAAU,IAAC,KAAK,EAAC,gBAAgB,YAAE,KAAK,GAAc,IACnD,CACP,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,EAC7B,SAAS,GAAG,QAAQ,KAGlB,EAAE;IACJ,MAAM,KAAK,GAAG,YAAY,EAAE,CAAA;IAC5B,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAAA;IAC/B,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,WAAW,EAAE,CAAA;IAEtC,SAAS,CAAC,GAAG,EAAE;QACb,KAAK,KAAK,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,CAAA;IACjC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;IAEX,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,CACL,KAAC,GAAG,IAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,YACf,MAAC,KAAK,IAAC,QAAQ,EAAC,OAAO,iBAAa,iBAAiB,+CACpB,KAAK,IAC9B,GACJ,CACP,CAAA;IACH,CAAC;IAED,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,WAAW,EAAE,CAAC;QAChD,OAAO,KAAC,eAAe,IAAC,KAAK,EAAC,2BAA2B,GAAG,CAAA;IAC9D,CAAC;IACD,IAAI,MAAM,KAAK,eAAe,EAAE,CAAC;QAC/B,OAAO,KAAC,QAAQ,IAAC,EAAE,EAAE,SAAS,EAAE,OAAO,SAAG,CAAA;IAC5C,CAAC;IAED,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,KAAC,eAAe,IAAC,KAAK,EAAC,yBAAyB,GAAG,CAAA;IAC5D,CAAC;IAED,OAAO,KAAC,MAAM,KAAG,CAAA;AACnB,CAAC"}
+{"version":3,"file":"ProtectedRoute.js","sourceRoot":"","sources":["../../src/mui/ProtectedRoute.tsx"],"names":[],"mappings":";AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAE9C,SAAS,eAAe,CAAC,EAAE,KAAK,EAAqB;IACnD,OAAO,CACL,MAAC,GAAG,IACF,EAAE,EAAE;YACF,OAAO,EAAE,MAAM;YACf,aAAa,EAAE,QAAQ;YACvB,UAAU,EAAE,QAAQ;YACpB,cAAc,EAAE,QAAQ;YACxB,GAAG,EAAE,CAAC;YACN,SAAS,EAAE,MAAM;SAClB,iBACW,mBAAmB,aAE/B,KAAC,gBAAgB,KAAG,EACpB,KAAC,UAAU,IAAC,KAAK,EAAC,gBAAgB,YAAE,KAAK,GAAc,IACnD,CACP,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,EAC7B,SAAS,GAAG,QAAQ,KAGlB,EAAE;IACJ,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,UAAU,EAAE,CAAA;IAElD,6EAA6E;IAC7E,4EAA4E;IAC5E,IAAI,MAAM,KAAK,MAAM,IAAI,KAAK,EAAE,CAAC;QAC/B,OAAO,CACL,KAAC,GAAG,IAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,YACf,MAAC,KAAK,IAAC,QAAQ,EAAC,OAAO,iBAAa,iBAAiB,+CACpB,KAAK,IAC9B,GACJ,CACP,CAAA;IACH,CAAC;IAED,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,KAAC,eAAe,IAAC,KAAK,EAAC,YAAY,GAAG,CAAA;IAC/C,CAAC;IACD,IAAI,UAAU,KAAK,aAAa,EAAE,CAAC;QACjC,OAAO,KAAC,MAAM,KAAG,CAAA;IACnB,CAAC;IACD,qEAAqE;IACrE,IAAI,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,WAAW,EAAE,CAAC;QACrD,OAAO,KAAC,MAAM,KAAG,CAAA;IACnB,CAAC;IACD,OAAO,KAAC,QAAQ,IAAC,EAAE,EAAE,SAAS,EAAE,OAAO,SAAG,CAAA;AAC5C,CAAC"}

package/dist/mui/index.d.ts

@@ -9,4 +9,7 @@
 export { ProtectedRoute } from './ProtectedRoute.js';
 export { ReconnectBanner } from './ReconnectBanner.js';
 export { SyncStatusChip } from './SyncStatusChip.js';
+export { LogoutDialog } from './LogoutDialog.js';
+export { ClearDataDialog } from './ClearDataDialog.js';
+export { AdoptDialog } from './AdoptDialog.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/mui/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mui/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;GAIG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mui/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;GAIG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/mui/index.js

@@ -9,4 +9,7 @@
 export { ProtectedRoute } from './ProtectedRoute.js';
 export { ReconnectBanner } from './ReconnectBanner.js';
 export { SyncStatusChip } from './SyncStatusChip.js';
+export { LogoutDialog } from './LogoutDialog.js';
+export { ClearDataDialog } from './ClearDataDialog.js';
+export { AdoptDialog } from './AdoptDialog.js';
 //# sourceMappingURL=index.js.map

package/dist/mui/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mui/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;GAIG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mui/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;GAIG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/react/WasSessionProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WasSessionProvider.d.ts","sourceRoot":"","sources":["../../src/react/WasSessionProvider.tsx"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;GAQG;AACH,OAAO,EAAsC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC/D,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE5E;;;GAGG;AACH,eAAO,MAAM,iBAAiB,8CAA2C,CAAA;AAEzE;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,QAAQ,EACR,QAAQ,EACT,EAAE;IACD,MAAM,EAAE,YAAY,CAAA;IACpB,QAAQ,EAAE,aAAa,CAAA;IACvB,QAAQ,EAAE,SAAS,CAAA;CACpB,GAAG,SAAS,CAkBZ"}
+{"version":3,"file":"WasSessionProvider.d.ts","sourceRoot":"","sources":["../../src/react/WasSessionProvider.tsx"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;GAQG;AACH,OAAO,EAAsC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC/D,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE5E;;;GAGG;AACH,eAAO,MAAM,iBAAiB,8CAA2C,CAAA;AAEzE;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,QAAQ,EACR,QAAQ,EACT,EAAE;IACD,MAAM,EAAE,YAAY,CAAA;IACpB,QAAQ,EAAE,aAAa,CAAA;IACvB,QAAQ,EAAE,SAAS,CAAA;CACpB,GAAG,SAAS,CAsBZ"}

package/dist/react/WasSessionProvider.js

@@ -30,11 +30,15 @@ export const WasSessionContext = createContext(null);
  */
 export function WasSessionProvider({ config, registry, children }) {
     const [store] = useState(() => createAuthStore({ config, registry }));
-    // Tear the live session down on unmount so an abandoned provider never leaves
-    // the expiry-watch interval and the replication loop firing against a store no
-    // one is reading (reliably hit by React StrictMode dev remounts and by tests).
-    // The persisted record survives, so a remount's `restore()` re-opens it.
+    // Kick off boot on mount (so a local-first app that never renders
+    // `ProtectedRoute` still boots), and tear the live session down on unmount so
+    // an abandoned provider never leaves the expiry-watch interval and the
+    // replication loop firing against a store no one is reading (reliably hit by
+    // React StrictMode dev remounts and by tests). `destroy()` returns the store
+    // to `boot` with both persisted seeds intact, so a StrictMode remount's
+    // `boot()` re-opens the same session (or fresh local).
     useEffect(() => {
+        void store.getState().boot();
         return () => {
             void store.getState().destroy();
         };

package/dist/react/WasSessionProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"WasSessionProvider.js","sourceRoot":"","sources":["../../src/react/WasSessionProvider.tsx"],"names":[],"mappings":";AAAA;;GAEG;AACH;;;;;;;;GAQG;AACH,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAkB,MAAM,OAAO,CAAA;AAE1E,OAAO,EAAE,eAAe,EAAqB,MAAM,yBAAyB,CAAA;AAE5E;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAsB,IAAI,CAAC,CAAA;AAEzE;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,EACjC,MAAM,EACN,QAAQ,EACR,QAAQ,EAKT;IACC,MAAM,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAe,GAAG,EAAE,CAC1C,eAAe,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CACtC,CAAA;IACD,8EAA8E;IAC9E,+EAA+E;IAC/E,+EAA+E;IAC/E,yEAAyE;IACzE,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,GAAG,EAAE;YACV,KAAK,KAAK,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,CAAA;QACjC,CAAC,CAAA;IACH,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;IACX,OAAO,CACL,KAAC,iBAAiB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YACrC,QAAQ,GACkB,CAC9B,CAAA;AACH,CAAC"}
+{"version":3,"file":"WasSessionProvider.js","sourceRoot":"","sources":["../../src/react/WasSessionProvider.tsx"],"names":[],"mappings":";AAAA;;GAEG;AACH;;;;;;;;GAQG;AACH,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAkB,MAAM,OAAO,CAAA;AAE1E,OAAO,EAAE,eAAe,EAAqB,MAAM,yBAAyB,CAAA;AAE5E;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAsB,IAAI,CAAC,CAAA;AAEzE;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,EACjC,MAAM,EACN,QAAQ,EACR,QAAQ,EAKT;IACC,MAAM,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAe,GAAG,EAAE,CAC1C,eAAe,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CACtC,CAAA;IACD,kEAAkE;IAClE,8EAA8E;IAC9E,uEAAuE;IACvE,6EAA6E;IAC7E,6EAA6E;IAC7E,wEAAwE;IACxE,uDAAuD;IACvD,SAAS,CAAC,GAAG,EAAE;QACb,KAAK,KAAK,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAA;QAC5B,OAAO,GAAG,EAAE;YACV,KAAK,KAAK,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,CAAA;QACjC,CAAC,CAAA;IACH,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;IACX,OAAO,CACL,KAAC,iBAAiB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YACrC,QAAQ,GACkB,CAC9B,CAAA;AACH,CAAC"}

package/dist/react/hooks.d.ts

@@ -1,6 +1,5 @@
 import type { WasAuthStore } from '../session/authStore.js';
 import { type SyncRollup } from '../storage/syncStatusStore.js';
-export { useAppReady } from '../session/appReadyStore.js';
 /**
  * The bound auth store from the nearest {@link WasSessionProvider}. Throws a
  * helpful error when used outside a provider.
@@ -16,6 +15,8 @@ export declare function useAuthStore(): WasAuthStore;
  */
 export declare function useSession(): {
     status: ReturnType<WasAuthStore['getState']>['status'];
+    onboarding: ReturnType<WasAuthStore['getState']>['onboarding'];
+    authenticating: boolean;
     phase: ReturnType<WasAuthStore['getState']>['phase'];
     error: string | null;
     controllerDid: string | null;
@@ -24,22 +25,49 @@ export declare function useSession(): {
     reconnecting: boolean;
 };
 /**
- * The login action plus the state the login page renders (status/phase/error).
+ * The login action plus the state the login page renders. `authenticating` is
+ * the in-flight flag (the `status` stays `local` during login); `status` is
+ * exposed so a login page can redirect once it reads `connected`. `login`
+ * accepts `{ adopt }` -- `'merge'` (default) migrates data created in `local`
+ * into the connected replica, `'leave'` sets it aside untouched.
  *
  * @returns {object}
  */
 export declare function useLogin(): {
-    login: () => Promise<void>;
+    login: (options?: {
+        adopt?: 'merge' | 'leave';
+    }) => Promise<void>;
+    authenticating: boolean;
     status: ReturnType<WasAuthStore['getState']>['status'];
     phase: ReturnType<WasAuthStore['getState']>['phase'];
     error: string | null;
 };
 /**
- * The logout action.
+ * The logout action; accepts `{ wipe }` to delete the connected replica rather
+ * than keep it on the device.
+ *
+ * @returns {(options?: { wipe?: boolean }) => Promise<void>}
+ */
+export declare function useLogout(): (options?: {
+    wipe?: boolean;
+}) => Promise<void>;
+/**
+ * The clear-data action: deletes the local replica, discards the anonymous
+ * seed, and mints a fresh anonymous seed/DID + replica (the `local`-mode
+ * "Clear data" affordance).
  *
  * @returns {() => Promise<void>}
  */
-export declare function useLogout(): () => Promise<void>;
+export declare function useClearData(): () => Promise<void>;
+/**
+ * Whether the anonymous `local` replica currently holds any documents -- the
+ * check a login affordance runs at decision time (e.g. on the login button
+ * click) to choose between opening the adoption dialog and calling `login()`
+ * directly. Returns the async check, not a subscription.
+ *
+ * @returns {() => Promise<boolean>}
+ */
+export declare function useHasLocalData(): () => Promise<boolean>;
 /**
  * The expired-access reconnect: the banner flags plus the reconnect action.
  *

package/dist/react/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/react/hooks.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAA;AAEzD;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,YAAY,CAS3C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI;IAC5B,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;IACtD,KAAK,EAAE,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAA;IACpD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,aAAa,EAAE,OAAO,CAAA;IACtB,YAAY,EAAE,OAAO,CAAA;CACtB,CAcA;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI;IAC1B,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;IACtD,KAAK,EAAE,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAA;IACpD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB,CAYA;AAED;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,MAAM,OAAO,CAAC,IAAI,CAAC,CAG/C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI;IAC9B,aAAa,EAAE,OAAO,CAAA;IACtB,YAAY,EAAE,OAAO,CAAA;IACrB,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/B,CAWA;AAED;;;GAGG;AACH,YAAY,EAAE,UAAU,EAAE,CAAA;AAE1B;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI;IAC/B,KAAK,EAAE,UAAU,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd,CAKA"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/react/hooks.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,+BAA+B,CAAA;AAEtC;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,YAAY,CAS3C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI;IAC5B,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;IACtD,UAAU,EAAE,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAA;IAC9D,cAAc,EAAE,OAAO,CAAA;IACvB,KAAK,EAAE,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAA;IACpD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,aAAa,EAAE,OAAO,CAAA;IACtB,YAAY,EAAE,OAAO,CAAA;CACtB,CAgBA;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,IAAI;IAC1B,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACjE,cAAc,EAAE,OAAO,CAAA;IACvB,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;IACtD,KAAK,EAAE,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAA;IACpD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB,CAaA;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,IAAI,CAAC,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAG3E;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,MAAM,OAAO,CAAC,IAAI,CAAC,CAGlD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,MAAM,OAAO,CAAC,OAAO,CAAC,CAGxD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI;IAC9B,aAAa,EAAE,OAAO,CAAA;IACtB,YAAY,EAAE,OAAO,CAAA;IACrB,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/B,CAWA;AAED;;;GAGG;AACH,YAAY,EAAE,UAAU,EAAE,CAAA;AAE1B;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI;IAC/B,KAAK,EAAE,UAAU,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd,CAKA"}

package/dist/react/hooks.js

@@ -11,7 +11,6 @@ import { useStore } from 'zustand';
 import { useShallow } from 'zustand/react/shallow';
 import { WasSessionContext } from './WasSessionProvider.js';
 import { useSyncStatusStore, deriveSyncRollup } from '../storage/syncStatusStore.js';
-export { useAppReady } from '../session/appReadyStore.js';
 /**
  * The bound auth store from the nearest {@link WasSessionProvider}. Throws a
  * helpful error when used outside a provider.
@@ -36,6 +35,8 @@ export function useSession() {
     const store = useAuthStore();
     return useStore(store, useShallow(state => ({
         status: state.status,
+        onboarding: state.onboarding,
+        authenticating: state.authenticating,
         phase: state.phase,
         error: state.error,
         controllerDid: state.controllerDid,
@@ -45,29 +46,58 @@ export function useSession() {
     })));
 }
 /**
- * The login action plus the state the login page renders (status/phase/error).
+ * The login action plus the state the login page renders. `authenticating` is
+ * the in-flight flag (the `status` stays `local` during login); `status` is
+ * exposed so a login page can redirect once it reads `connected`. `login`
+ * accepts `{ adopt }` -- `'merge'` (default) migrates data created in `local`
+ * into the connected replica, `'leave'` sets it aside untouched.
  *
  * @returns {object}
  */
 export function useLogin() {
     const store = useAuthStore();
     const login = useStore(store, state => state.login);
-    const { status, phase, error } = useStore(store, useShallow(state => ({
+    const { authenticating, status, phase, error } = useStore(store, useShallow(state => ({
+        authenticating: state.authenticating,
         status: state.status,
         phase: state.phase,
         error: state.error
     })));
-    return { login, status, phase, error };
+    return { login, authenticating, status, phase, error };
 }
 /**
- * The logout action.
+ * The logout action; accepts `{ wipe }` to delete the connected replica rather
+ * than keep it on the device.
  *
- * @returns {() => Promise<void>}
+ * @returns {(options?: { wipe?: boolean }) => Promise<void>}
  */
 export function useLogout() {
     const store = useAuthStore();
     return useStore(store, state => state.logout);
 }
+/**
+ * The clear-data action: deletes the local replica, discards the anonymous
+ * seed, and mints a fresh anonymous seed/DID + replica (the `local`-mode
+ * "Clear data" affordance).
+ *
+ * @returns {() => Promise<void>}
+ */
+export function useClearData() {
+    const store = useAuthStore();
+    return useStore(store, state => state.clearLocalData);
+}
+/**
+ * Whether the anonymous `local` replica currently holds any documents -- the
+ * check a login affordance runs at decision time (e.g. on the login button
+ * click) to choose between opening the adoption dialog and calling `login()`
+ * directly. Returns the async check, not a subscription.
+ *
+ * @returns {() => Promise<boolean>}
+ */
+export function useHasLocalData() {
+    const store = useAuthStore();
+    return useStore(store, state => state.hasLocalData);
+}
 /**
  * The expired-access reconnect: the banner flags plus the reconnect action.
  *

package/dist/react/hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/react/hooks.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/react/hooks.ts"],"names":[],"mappings":"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"}

package/dist/react/index.d.ts

@@ -7,5 +7,5 @@
  * `./mui` subpath.
  */
 export { WasSessionProvider, WasSessionContext } from './WasSessionProvider.js';
-export { useAuthStore, useSession, useLogin, useLogout, useReconnect, useSyncStatus, useAppReady, type SyncRollup } from './hooks.js';
+export { useAuthStore, useSession, useLogin, useLogout, useClearData, useHasLocalData, useReconnect, useSyncStatus, type SyncRollup } from './hooks.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;GAIG;AACH,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC/E,OAAO,EACL,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,aAAa,EACb,WAAW,EACX,KAAK,UAAU,EAChB,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;GAIG;AACH,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC/E,OAAO,EACL,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,aAAa,EACb,KAAK,UAAU,EAChB,MAAM,YAAY,CAAA"}

package/dist/react/index.js

@@ -7,5 +7,5 @@
  * `./mui` subpath.
  */
 export { WasSessionProvider, WasSessionContext } from './WasSessionProvider.js';
-export { useAuthStore, useSession, useLogin, useLogout, useReconnect, useSyncStatus, useAppReady } from './hooks.js';
+export { useAuthStore, useSession, useLogin, useLogout, useClearData, useHasLocalData, useReconnect, useSyncStatus } from './hooks.js';
 //# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;GAIG;AACH,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC/E,OAAO,EACL,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,aAAa,EACb,WAAW,EAEZ,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;GAIG;AACH,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC/E,OAAO,EACL,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,aAAa,EAEd,MAAM,YAAY,CAAA"}

package/dist/session/authStore.d.ts

@@ -2,17 +2,29 @@
  * Copyright (c) 2026 Interop Alliance. All rights reserved.
  */
 /**
- * The wallet-mode auth store (zustand): owns the session lifecycle -- hot
- * restore (zero popups), Login With Wallet, logout, and the expired-access
- * reconnect -- plus the open/hydrate/sync ordering.
+ * The session auth store (zustand): a four-state machine
+ * (`boot` | `local` | `connected` | `reconnect`) that owns the whole session
+ * lifecycle -- boot (hot restore or fall to an anonymous local replica), Login
+ * With Wallet, the non-CHAPI `connectWithGrants` path, logout, clear-data, and
+ * the expired-access reconnect -- plus the open/hydrate/sync ordering.
  *
- * On a successful login/restore it opens the encrypted {@link LocalStore} from
- * the session seed (a per-controller database name, so two wallet users on one
- * browser never collide), hydrates the entity stores, flips the shared
- * `useAppReady` gate, and starts WAS replication from the granted zcaps.
+ * `boot` attempts a zero-popup session restore. A restore hit opens the
+ * encrypted {@link LocalStore} under the session seed, hydrates the entity
+ * stores, starts WAS replication, and lands `connected`. A restore miss (or any
+ * error) opens the store under a persisted ANONYMOUS seed instead and lands
+ * `local`: a fully usable, encrypted, local-only replica with no remote. Both
+ * successors finish open+hydrate before leaving `boot`, so "app ready" is simply
+ * `status !== 'boot'`.
  *
- * `status` is the router gate: `ProtectedRoute` waits for the restore attempt to
- * settle before deciding between the app and the login page.
+ * Login (or `connectWithGrants`) tears the anonymous replica down and opens the
+ * connected replica under the wallet-derived seed. By default it ADOPTS the
+ * anonymous replica's data first (`adopt: 'merge'`): the decrypted payloads are
+ * collected before teardown, LWW-merged into the connected replica before its
+ * first hydrate/sync (so they reach the server as ordinary creates), and the
+ * anonymous seed + database are deleted once the activation lands. `adopt:
+ * 'leave'` sets the anonymous replica aside untouched instead (it returns after
+ * a logout). Logout returns to a fresh `local` (optionally wiping the connected
+ * replica); `clearLocalData` mints a brand-new anonymous seed and replica.
  *
  * The library cannot bind a module-level store to app config, so this is a
  * FACTORY: {@link createAuthStore} captures the app's {@link WasAppConfig} and
@@ -21,12 +33,34 @@
  */
 import { type StoreApi } from 'zustand/vanilla';
 import type { RxStorage } from 'rxdb/plugins/core';
+import type { IZcap } from '@interop/data-integrity-core';
 import { type StoreRegistry, type WasAppConfig } from '../config.js';
 import { type SeedStore } from '../identity/seedStore.js';
 import { type LoginPhase } from '../auth/loginFlow.js';
-export type AuthStatus = 'idle' | 'restoring' | 'unauthenticated' | 'authenticating' | 'authenticated';
+/**
+ * The four session states:
+ * - `boot`: attempting hot restore; both successors open + hydrate before this
+ *   status is left.
+ * - `local`: an encrypted anonymous-seed replica, no remote (the pre-connection
+ *   product state; tier-1 apps may stay here indefinitely).
+ * - `connected`: a wallet-derived identity, parsed grants, replication.
+ * - `reconnect`: connected but access expired/revoked; the replica stays usable,
+ *   remote invocations paused until re-login.
+ */
+export type SessionStatus = 'boot' | 'local' | 'connected' | 'reconnect';
 export interface AuthState {
-    status: AuthStatus;
+    status: SessionStatus;
+    /**
+     * The app's onboarding mode. Read by `ProtectedRoute` to decide whether to
+     * render the app or redirect to login while in `local`; never affects the
+     * store's own transitions.
+     */
+    onboarding: 'local-first' | 'login-gated';
+    /**
+     * A Login With Wallet flow is in flight (the transient the login page's busy
+     * state keys off; distinct from the `status`, which stays `local` throughout).
+     */
+    authenticating: boolean;
     /**
      * The current login phase, for the login page's progress line.
      */
@@ -34,32 +68,87 @@ export interface AuthState {
     error: string | null;
     controllerDid: string | null;
     /**
-     * ISO expiry of the current grant set (earliest zcap expiry).
+     * ISO expiry of the current grant set (earliest zcap expiry); `null` in
+     * `local` (no grants).
      */
     expires: string | null;
     /**
-     * A live 401/403 was seen mid-session: show the reconnect banner.
+     * A live 401/403 was seen mid-session (or a proactive near-expiry): show the
+     * reconnect banner. Always true iff `status === 'reconnect'`.
      */
     accessExpired: boolean;
     reconnecting: boolean;
     /**
-     * Hot restore from the persisted session; falls to `unauthenticated`.
+     * Attempt a zero-popup hot restore; a restore hit lands `connected`, any
+     * miss/error falls to `local` (a fresh anonymous replica), never a dead login
+     * screen. No-op once the status has left `boot`.
+     */
+    boot: () => Promise<void>;
+    /**
+     * Full Login With Wallet (first-run or returning). On success tears down the
+     * anonymous replica and opens the connected one. `adopt` decides what happens
+     * to data created in `local` before this login: `'merge'` (the default)
+     * LWW-merges it into the connected replica and then deletes the anonymous
+     * seed + database; `'leave'` sets the anonymous replica aside untouched (it
+     * returns after a logout). A cancel or failure leaves `local` intact either
+     * way.
+     *
+     * @param [options] {object}
+     * @param [options.adopt] {'merge' | 'leave'}
+     * @returns {Promise<void>}
      */
-    restore: () => Promise<void>;
+    login: (options?: {
+        adopt?: 'merge' | 'leave';
+    }) => Promise<void>;
     /**
-     * Full Login With Wallet (first-run or returning).
+     * Non-CHAPI connect from an explicit seed + grants (dev/test and provisioned
+     * grants). Tears down the current replica and opens the connected one, with
+     * the same `adopt` choice (and `'merge'` default) as `login`, so this path
+     * exercises adoption exactly as a wallet login does.
+     *
+     * @param options {object}
+     * @param options.seed {Uint8Array}
+     * @param options.grants {IZcap[]}
+     * @param [options.adopt] {'merge' | 'leave'}
+     * @returns {Promise<void>}
      */
-    login: () => Promise<void>;
+    connectWithGrants: (options: {
+        seed: Uint8Array;
+        grants: IZcap[];
+        adopt?: 'merge' | 'leave';
+    }) => Promise<void>;
     /**
      * Re-run the grants flow with the existing seed (expired access).
      */
     reconnect: () => Promise<void>;
-    logout: () => Promise<void>;
+    /**
+     * Detach the wallet and return to a fresh `local` replica. `wipe` deletes the
+     * connected replica's database; otherwise it is kept on the device.
+     *
+     * @param [options] {object}
+     * @param [options.wipe] {boolean}
+     * @returns {Promise<void>}
+     */
+    logout: (options?: {
+        wipe?: boolean;
+    }) => Promise<void>;
+    /**
+     * Delete the local replica, discard the anonymous seed, and mint a fresh
+     * anonymous seed/DID + replica. The shared reset primitive behind the
+     * `local`-mode "Clear data" button.
+     */
+    clearLocalData: () => Promise<void>;
+    /**
+     * Whether the anonymous `local` replica currently holds any documents -- the
+     * check a login screen runs to decide whether to offer the adoption choice
+     * before `login()`. Always false outside `local`.
+     */
+    hasLocalData: () => Promise<boolean>;
     notifyAccessExpired: () => void;
     /**
-     * Tears down the live session (expiry watch, controller, local store) WITHOUT
-     * wiping the persisted session record, and returns to `idle` so a fresh
-     * `restore()` can re-open it. Called from the provider's unmount cleanup so an
+     * Tears down the live replica (expiry watch, controller, local store) WITHOUT
+     * wiping the persisted session record, and returns to `boot` so a fresh
+     * `boot()` can re-open it. Called from the provider's unmount cleanup so an
      * unmount (or a React StrictMode dev remount) never orphans the replication
      * loop or the expiry-watch interval.
      */
@@ -70,7 +159,7 @@ export interface AuthState {
  */
 export type WasAuthStore = StoreApi<AuthState>;
 /**
- * Builds the wallet-mode auth store bound to an app's config and store registry.
+ * Builds the session auth store bound to an app's config and store registry.
  * Call once (the React provider does) and share the returned store through
  * context; the hooks read it via `useStore`.
  *

package/dist/session/authStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authStore.d.ts","sourceRoot":"","sources":["../../src/session/authStore.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAElD,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAA;AAIrB,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAO1E,OAAO,EAKL,KAAK,UAAU,EAChB,MAAM,sBAAsB,CAAA;AAwB7B,MAAM,MAAM,UAAU,GACpB,MAAM,GAAG,WAAW,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,eAAe,CAAA;AAU/E,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,UAAU,CAAA;IAClB;;OAEG;IACH,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;IACxB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;OAEG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB;;OAEG;IACH,aAAa,EAAE,OAAO,CAAA;IACtB,YAAY,EAAE,OAAO,CAAA;IACrB;;OAEG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B;;OAEG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B;;OAEG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9B,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3B,mBAAmB,EAAE,MAAM,IAAI,CAAA;IAC/B;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAA;AAE9C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,EAC9B,MAAM,EACN,QAAQ,EACR,SAAS,EACT,OAAO,EACR,EAAE;IACD,MAAM,EAAE,YAAY,CAAA;IACpB,QAAQ,EAAE,aAAa,CAAA;IACvB,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,OAAO,CAAC,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;CACtC,GAAG,YAAY,CA2Yf"}
+{"version":3,"file":"authStore.d.ts","sourceRoot":"","sources":["../../src/session/authStore.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,8BAA8B,CAAA;AACzD,OAAO,EAKL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAA;AAIrB,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAQ1E,OAAO,EAKL,KAAK,UAAU,EAChB,MAAM,sBAAsB,CAAA;AAwB7B;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,WAAW,GAAG,WAAW,CAAA;AAqBxE,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,aAAa,CAAA;IACrB;;;;OAIG;IACH,UAAU,EAAE,aAAa,GAAG,aAAa,CAAA;IACzC;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAA;IACvB;;OAEG;IACH,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;IACxB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;OAGG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAA;IACtB,YAAY,EAAE,OAAO,CAAA;IACrB;;;;OAIG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACzB;;;;;;;;;;;;OAYG;IACH,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACjE;;;;;;;;;;;OAWG;IACH,iBAAiB,EAAE,CAAC,OAAO,EAAE;QAC3B,IAAI,EAAE,UAAU,CAAA;QAChB,MAAM,EAAE,KAAK,EAAE,CAAA;QACf,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAA;KAC1B,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnB;;OAEG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9B;;;;;;;OAOG;IACH,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACvD;;;;OAIG;IACH,cAAc,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACnC;;;;OAIG;IACH,YAAY,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IACpC,mBAAmB,EAAE,MAAM,IAAI,CAAA;IAC/B;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAA;AAQ9C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,EAC9B,MAAM,EACN,QAAQ,EACR,SAAS,EACT,OAAO,EACR,EAAE;IACD,MAAM,EAAE,YAAY,CAAA;IACpB,QAAQ,EAAE,aAAa,CAAA;IACvB,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,OAAO,CAAC,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;CACtC,GAAG,YAAY,CAgpBf"}