@nominalso/vibe-auth 0.2.3 → 0.3.0

package/AGENTS.md

@@ -39,11 +39,33 @@ export const auth = createVibeAuth({
    render the app's provider tree there (see **Root wiring** below).
 2. **The app root.** Wrap everything in `<auth.AuthGate>`. The app renders nothing of itself
    until authenticated.
-3. **The host bridge**, if embedded via `@nominalso/vibe-bridge`. Call
-   `auth.wireHostAuth(bridge)` at module scope, then start `bridge.connect()`
-   immediately in that same module — do not defer it to a React effect. Seed
-   `auth.seedLastUserId(ctx.user.id, ctx.tenant)` once `connect()` resolves,
-   from a **parent** of `AuthGate`, not inside gated children.
+3. **The host bridge**, if embedded via `@nominalso/vibe-bridge`. One call, at
+   module scope, from a **parent** of `AuthGate` — never a React effect, and
+   never a module reachable only through a `lazy()` chunk:
+
+   ```ts
+   export const bridge = new VibeAppBridge()
+   export const { hostContext, getHostContext, subscribeHostContext } =
+     auth.wireVibeApp<ContextPayload>(bridge)
+   ```
+
+   `wireVibeApp` registers the context subscriber and host auth **before**
+   `connect()`, seeds the host principal `AuthGate` waits on **before**
+   publishing context, skips the handshake entirely in the callback document,
+   and resolves `null` rather than rejecting when there is no host. Pass
+   `onContextChange` / `onDataReset` / `onSubrouteRequest` as options in the
+   same call; each is a single subscriber, and routing them through here is what
+   guarantees exactly one of each.
+
+   `hostOutcome` (alongside `hostContext`) settles `{ kind: 'connected' }`,
+   `{ kind: 'standalone' }` or `{ kind: 'failed', error }`. `hostContext`
+   resolves `null` for the last two alike, so use `hostOutcome` when the app
+   needs an error state that does not fire on every standalone dev load.
+
+   `wireHostAuth` / `seedLastUserId` are the pre-0.2.3 hand-wiring. They are
+   still exported for compatibility, but new code should not call them — four of
+   seven migrated apps got that sequence wrong, each differently, which is why
+   `wireVibeApp` exists.
 
 ## Root wiring (SSR — React #418)
 

package/README.md

@@ -62,17 +62,35 @@ function Root() {
 
 ```ts
 // Start the Nominal host handshake at module scope, before React mounts.
+import { VibeAppBridge, type ContextPayload } from '@nominalso/vibe-bridge'
 import { auth } from '@/lib/auth'
-import { bridge } from './bridge'
 
-const unsub = auth.wireHostAuth(bridge)
-export const hostContext = bridge.connect().then((ctx) => {
-  auth.seedLastUserId(ctx.user.id, ctx.tenant)
-  return ctx
-})
+export const bridge = new VibeAppBridge()
+
+export const { hostContext, getHostContext, subscribeHostContext } =
+  auth.wireVibeApp<ContextPayload>(bridge)
+```
+
+One call does the whole handshake, in the one correct order: context subscriber
+and host auth registered before `connect()`, the host principal seeded before
+context is published, the handshake skipped in the callback document, and `null`
+rather than a rejection when there is no host. Pass `onContextChange`,
+`onDataReset` and `onSubrouteRequest` as options in the same call.
+
+**Telling "not embedded" from "the host broke".** `hostContext` resolves `null`
+for both, which is why apps either showed an error banner on every standalone
+dev load or showed none at all. `hostOutcome` carries the distinction:
+
+```ts
+const { hostContext, hostOutcome } = auth.wireVibeApp<ContextPayload>(bridge)
+
+const outcome = await hostOutcome // never rejects, settles with hostContext
+// { kind: 'connected' }
+// { kind: 'standalone' }          — nothing was ever going to answer; expected
+// { kind: 'failed', error }       — embedded, and the host stayed silent
 ```
 
-See [`AGENTS.md`](./AGENTS.md) for SSR root wiring and host `seedLastUserId` rules.
+See [`AGENTS.md`](./AGENTS.md) for SSR root wiring and the full ordering rules.
 Timeouts live on `VibeAuthTimeouts` in the package `.d.ts`.
 
 ## Why a client you own, not one this package creates
@@ -87,11 +105,13 @@ control**, not a preference (the `.d.ts` on `VibeAuthConfig` explains why).
 
 - `ensureSession()` / `rebindSession({ userId, tenant })` — the cross-document-safe core (Web Lock
   serialised, terminal-capped, sibling-adopting). Most apps never call these directly; the
-  gate and `wireHostAuth` do.
+  gate and `wireVibeApp` do.
 - `AuthGate` / `DefaultSignInScreen` / `SilentCallback` — the three React pieces. Override
   `signInScreen`/`loader` props on `AuthGate` for branding.
-- `wireHostAuth(bridge)` / `seedLastUserId(userId, tenant)` — the Nominal-host integration (logout,
-  identity/tenant switch). Seed from a parent of `AuthGate` after `connect()`.
+- `wireVibeApp(bridge, options?)` — the Nominal-host integration in one call (handshake,
+  host context store, logout and identity/tenant switch). Call it at module scope from a
+  parent of `AuthGate`. (`wireHostAuth` / `seedLastUserId` are the pre-0.2.3 hand-wiring,
+  still exported for compatibility; new code should not use them.)
 - Fully configurable timeouts (`VibeAuthTimeouts` in the `.d.ts`) — every value defaults to
   what shipped after this flow's production incidents.
 

package/dist/index.cjs

@@ -501,28 +501,108 @@ function createAuthGate(config, silentAuth, interactiveAuth, hostAuth) {
   const { supabase, callbackPath, timeouts } = config;
   const RETURNING_FROM_OAUTH = typeof window !== "undefined" && (new URLSearchParams(window.location.search).has("code") || window.location.hash.includes("access_token"));
   const IS_CALLBACK_PATH = typeof window !== "undefined" && window.location.pathname === callbackPath;
+  const SPIN_CLASS = "nominal-vibe-auth-spin";
+  function Spinner({ size = 18 }) {
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("style", { children: `
+          @keyframes ${SPIN_CLASS} { to { transform: rotate(360deg) } }
+          .${SPIN_CLASS} { animation: ${SPIN_CLASS} 700ms linear infinite; transform-origin: 50% 50% }
+          @media (prefers-reduced-motion: reduce) { .${SPIN_CLASS} { animation-duration: 2.4s } }
+        ` }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+        "svg",
+        {
+          className: SPIN_CLASS,
+          width: size,
+          height: size,
+          viewBox: "0 0 24 24",
+          fill: "none",
+          "aria-hidden": "true",
+          children: [
+            /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+              "circle",
+              {
+                cx: "12",
+                cy: "12",
+                r: "9",
+                stroke: "currentColor",
+                strokeOpacity: "0.18",
+                strokeWidth: "3"
+              }
+            ),
+            /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+              "path",
+              {
+                d: "M21 12a9 9 0 0 0-9-9",
+                stroke: "currentColor",
+                strokeWidth: "3",
+                strokeLinecap: "round"
+              }
+            )
+          ]
+        }
+      )
+    ] });
+  }
+  const SCREEN = {
+    display: "grid",
+    placeItems: "center",
+    height: "100vh",
+    fontFamily: 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+    color: "#3f3f46",
+    background: "#fafafa"
+  };
   function DefaultFullScreenLoader() {
-    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: SCREEN, children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
       "div",
       {
-        style: { display: "grid", placeItems: "center", height: "100vh", fontFamily: "sans-serif" },
-        children: "Fetching your data\u2026"
+        style: { display: "flex", alignItems: "center", gap: 10, fontSize: 14 },
+        role: "status",
+        "aria-live": "polite",
+        children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {}),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { children: "Fetching your data\u2026" })
+        ]
       }
-    );
+    ) });
   }
   function DefaultSignInScreen() {
     const [pending, setPending] = (0, import_react2.useState)(false);
     const [failure, setFailure] = (0, import_react2.useState)(null);
-    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { style: SCREEN, children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
       "div",
       {
-        style: { display: "grid", placeItems: "center", height: "100vh", fontFamily: "sans-serif" },
-        children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: { textAlign: "center" }, children: [
-          /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+        style: {
+          textAlign: "center",
+          background: "#fff",
+          border: "1px solid #e4e4e7",
+          borderRadius: 12,
+          padding: "28px 32px",
+          boxShadow: "0 1px 2px rgba(0,0,0,0.04)",
+          maxWidth: 340
+        },
+        children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
             "button",
             {
               type: "button",
               disabled: pending,
+              style: {
+                display: "inline-flex",
+                alignItems: "center",
+                justifyContent: "center",
+                gap: 8,
+                minWidth: 168,
+                padding: "10px 20px",
+                fontFamily: "inherit",
+                fontSize: 14,
+                fontWeight: 500,
+                color: "#fff",
+                background: pending ? "#71717a" : "#18181b",
+                border: "none",
+                borderRadius: 8,
+                cursor: pending ? "default" : "pointer"
+              },
               onClick: () => {
                 setPending(true);
                 setFailure(null);
@@ -531,13 +611,16 @@ function createAuthGate(config, silentAuth, interactiveAuth, hostAuth) {
                   if (result.kind !== "redirecting" /* Redirecting */) setPending(false);
                 });
               },
-              children: pending ? "Opening sign-in\u2026" : "Sign in"
+              children: [
+                pending ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, { size: 15 }) : null,
+                pending ? "Opening sign-in\u2026" : "Sign in"
+              ]
             }
           ),
-          failure ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: { fontSize: 12, marginTop: 8 }, children: failure === "popup-blocked" /* PopupBlocked */ ? "Your browser blocked the sign-in popup. Allow popups for this site and try again." : "Sign-in didn't complete. Please try again." }) : null
-        ] })
+          failure ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: { fontSize: 12.5, lineHeight: 1.5, marginTop: 14, color: "#a1a1aa" }, children: failure === "popup-blocked" /* PopupBlocked */ ? "Your browser blocked the sign-in popup. Allow popups for this site and try again." : "Sign-in didn't complete. Please try again." }) : null
+        ]
       }
-    );
+    ) });
   }
   function AuthGate({ children, signInScreen, loader }) {
     const [isCallback, setIsCallback] = (0, import_react2.useState)(false);
@@ -703,6 +786,11 @@ function createHostAuth(config, silentAuth) {
     for (const listener of [...seedListeners]) listener(principal);
   }
   function wireHostAuth(bridge) {
+    if (typeof bridge?.onAuthChange !== "function") {
+      throw new TypeError(
+        "[vibe-auth] wireHostAuth(bridge) requires a VibeAppBridge \u2014 the object passed has no onAuthChange. Prefer wireVibeApp(bridge), which performs the whole handshake."
+      );
+    }
     hostWired = true;
     return bridge.onAuthChange((auth) => {
       if (!auth.authenticated) {
@@ -733,6 +821,15 @@ function createHostAuth(config, silentAuth) {
 }
 
 // src/wireVibeApp.ts
+function classifyConnectFailure(error) {
+  const code = error?.code;
+  if (code === "PARENT_ORIGIN_UNRESOLVED") return { kind: "standalone" };
+  if (code === "TIMEOUT") {
+    const framed = typeof window !== "undefined" && window.parent !== window;
+    return framed ? { kind: "failed", error } : { kind: "standalone" };
+  }
+  return { kind: "failed", error };
+}
 function createWireVibeApp(config, hostAuth) {
   return function wireVibeApp(bridge, options = {}) {
     const listeners = /* @__PURE__ */ new Set();
@@ -748,21 +845,31 @@ function createWireVibeApp(config, hostAuth) {
     if (options.onSubrouteRequest) bridge.onSubrouteRequest?.(options.onSubrouteRequest);
     hostAuth.wireHostAuth(bridge);
     const noHost = typeof window === "undefined" || window.location.pathname === config.callbackPath;
-    const hostContext = noHost ? Promise.resolve(null) : bridge.connect().then((ctx) => {
+    let settleOutcome;
+    const hostOutcome = new Promise((resolve) => {
+      settleOutcome = resolve;
+    });
+    const hostContext = noHost ? (settleOutcome({ kind: "standalone" }), Promise.resolve(null)) : bridge.connect().then((ctx) => {
       const next = ctx;
       hostAuth.seedLastUserId(next.user.id, next.tenant);
       if (next.enableDataReset && options.onDataReset) {
         bridge.onDataReset?.(options.onDataReset);
       }
       publish(next);
+      settleOutcome({ kind: "connected" });
       return next;
     }).catch((error) => {
-      console.warn("[vibe-auth] host connect failed", error);
+      const outcome = classifyConnectFailure(error);
+      if (outcome.kind === "failed") {
+        console.warn("[vibe-auth] host connect failed", error);
+      }
+      settleOutcome(outcome);
       return null;
     });
     return {
       bridge,
       hostContext,
+      hostOutcome,
       getHostContext: () => current,
       subscribeHostContext: (listener) => {
         listeners.add(listener);