@edgespark/web 0.0.1-beta.4 → 0.0.1-beta.6

package/README.md

@@ -47,12 +47,13 @@ es.authUI.mount(container, { redirectTo: "/dashboard" });
 
 ### `auth`
 
-`es.auth` is the better-auth client, with two small EdgeSpark additions:
+`es.auth` keeps better-auth's API shape and adds two EdgeSpark helpers:
 
 ```ts
 const session = await es.auth.requireSession();
-const unsubscribe = es.auth.onSessionChange((session) => {
-  console.log(session?.user.email ?? "signed out");
+
+const unsubscribe = es.auth.onSessionChange((nextSession) => {
+  console.log(nextSession?.user.email ?? "signed out");
 });
 ```
 
@@ -60,7 +61,12 @@ const unsubscribe = es.auth.onSessionChange((session) => {
 session lookup itself fails, it preserves the upstream auth error code/status
 so route guards can distinguish backend failures from a real sign-out.
 
-Use the upstream better-auth auth methods directly:
+`onSessionChange()` is hydration-safe: it waits for the first session lookup to
+complete before emitting, so apps do not mistake initial loading for a real
+signed-out state. Successful sign-in/sign-up/sign-out mutations also prompt
+other tabs to refetch their session state.
+
+Use the familiar auth methods directly:
 
 ```ts
 await es.auth.signIn.email({ email, password });
@@ -134,6 +140,10 @@ Password reset has one special rule:
 - in controlled mode, `onSuccess({ action: "password-reset" })` fires and the caller owns the next step
 - in redirect mode, the UI returns to sign-in with a success notice instead of redirecting to an authenticated page
 
+In controlled mode, `authUI` stops mutating the container after `onSuccess`
+runs. If the app wants to close, replace, or reuse that container, it owns that
+teardown explicitly.
+
 ## Flows covered by the managed UI
 
 - email/password sign-in

package/dist/auth/create-auth.d.ts

@@ -4,8 +4,9 @@ export declare function syncEdgeSparkAuthSession(authClient: BetterAuthClientIns
 /**
  * Creates the headless auth module.
  *
- * This intentionally mirrors better-auth so agents can rely on upstream API
- * knowledge instead of learning a second parallel auth surface.
+ * The exposed API intentionally keeps better-auth's shape so existing upstream
+ * knowledge transfers directly. EdgeSpark adds session helpers and sync
+ * semantics on top of that familiar surface.
  */
 export declare function createEdgeSparkAuth(): EdgeSparkAuth;
 /**

package/dist/auth/types.d.ts

@@ -17,11 +17,8 @@ export interface AuthEndpointResult<TData = unknown> {
     error?: AuthEndpointError | null;
 }
 /**
- * EdgeSpark keeps auth primitive usage aligned with better-auth.
- *
- * All better-auth client methods work directly.  EdgeSpark adds three
- * small conveniences on top: `requireSession`, `onSessionChange`, and
- * a wrapped `signOut` that best-effort invalidates the same-tab session.
+ * EdgeSpark keeps the auth API shape aligned with better-auth while adding a
+ * small set of session helpers on top.
  */
 export type EdgeSparkAuth = BetterAuthClientInstance & {
     /**
@@ -35,30 +32,28 @@ export type EdgeSparkAuth = BetterAuthClientInstance & {
      */
     requireSession(): Promise<AuthSession>;
     /**
-     * Subscribes to session changes for the current tab.
+     * Subscribes to session changes for the current browser context.
      *
      * The first emission is hydration-safe: it waits for the initial server
-     * session check to complete before firing, so subscribers never receive a
-     * premature `null` that looks like "not authenticated" while the cookie
-     * session is still being verified.
+     * session lookup to complete before firing, so subscribers never receive a
+     * premature `null` while a cookie session is still settling.
      *
-     * After the initial emission, successful session atom updates are forwarded
-     * immediately (sign-in from another tab, sign-out, token refresh, etc.).
-     * Transient refresh failures that temporarily clear the atom to `null` are
-     * ignored so subscribers do not mistake a lookup error for a real sign-out.
+     * After hydration, successful session atom updates are forwarded immediately.
+     * Successful auth mutations that create or clear a session in the current
+     * tab also prompt other tabs to refetch their session state, so logout and
+     * same-tab sign-in/sign-up converge quickly across tabs.
+     *
+     * Transient lookup failures that temporarily clear the atom to `null` are
+     * ignored so subscribers do not mistake a backend error for a real sign-out.
      *
      * Returns an unsubscribe function.
      */
     onSessionChange(callback: SessionChangeCallback): () => void;
     /**
-     * Signs out and invalidates the session for the current tab.
-     *
-     * This wraps better-auth's `signOut` and additionally forces the session
-     * atom to refetch after a successful sign-out so `onSessionChange`
-     * subscribers update in the same tab.
+     * Signs out and then best-effort synchronizes session state for the current
+     * tab and other open tabs.
      *
-     * The extra refetch is best-effort. If it fails, the original better-auth
-     * sign-out result is still returned unchanged.
+     * The underlying better-auth result is returned unchanged.
      */
     signOut(...args: Parameters<BetterAuthClientInstance["signOut"]>): ReturnType<BetterAuthClientInstance["signOut"]>;
 };

package/dist/auth-ui/ManagedAuthUI.d.ts

@@ -30,6 +30,7 @@ export declare class ManagedAuthUI implements MountedAuthUI {
     constructor(container: HTMLElement, auth: BetterAuthClientInstance, options: MountAuthUIOptions, loadConfig: () => Promise<NormalizedAuthUIConfig>, runtimeOptions?: ManagedAuthUIRuntimeOptions | undefined);
     destroy(): void;
     private initialize;
+    private redirectAfterManagedReturnLookupFailure;
     private readMountSession;
     private render;
     private renderLoading;

package/dist/client.d.ts

@@ -3,14 +3,15 @@ import { EdgeSparkAuth } from './auth/types';
 import { EdgeSparkAuthUI } from './auth-ui';
 export interface EdgeSparkClient {
     /**
-       * Headless auth primitives — the full better-auth client, plus:
+       * Headless auth client with a better-auth-aligned API shape, plus a small
+       * set of EdgeSpark session helpers:
        *
        * - `requireSession()` — resolves or throws, for route guards
-       * - `onSessionChange(cb)` — hydration-safe session subscription
-       * - `signOut()` — signs out and best-effort invalidates the same-tab session atom
+       * - `onSessionChange()` — hydration-safe session observer
        *
-       * All other better-auth methods (`signIn.email`, `signUp.email`,
-       * `getSession`, etc.) work directly.
+       * Standard auth methods such as `signIn.email`, `signIn.social`,
+       * `signUp.email`, `signOut`, and `getSession` remain available on the same
+       * familiar shape.
      */
     auth: EdgeSparkAuth;
     /**