@nominalso/vibe-auth 0.2.3 → 0.2.4

package/AGENTS.md

@@ -39,11 +39,28 @@ 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.
+
+   `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,22 @@ 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)
 ```
 
-See [`AGENTS.md`](./AGENTS.md) for SSR root wiring and host `seedLastUserId` rules.
+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.
+
+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 +92,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/llms.txt

@@ -2,7 +2,7 @@
 
 > Silent Supabase OIDC login for Nominal Vibe Apps that authenticate through Supabase federated with the Nominal host's IdP (Descope). A configurable, cross-document-safe replacement for a hand-copied `silentAuth.ts`/`AuthGate.tsx` pair generated from the `silent-supabase-oidc-login` skill: Web-Lock-serialised silent SSO (`prompt=none`), identity-switch rebinding, a popup/top-level-redirect interactive fallback, and a React `AuthGate` that never renders the app until authenticated.
 
-The integration is always the same: call `createVibeAuth({ supabase, provider })` once, synchronously, at the top of its own eagerly-imported module (your own PKCE-configured Supabase client — this package never creates one); mount the returned `SilentCallback` at the callback path (default `/silent-callback`), ungated, outside the gate; wrap the app root in `<AuthGate>`; and, if embedded via `@nominalso/vibe-bridge`, call `wireHostAuth(bridge)` before `connect()` then `seedLastUserId(ctx.user.id, ctx.tenant)` after from a parent of `AuthGate`. `provider` is the app's Supabase Auth → Providers value — never guess it.
+The integration is always the same: call `createVibeAuth({ supabase, provider })` once, synchronously, at the top of its own eagerly-imported module (your own PKCE-configured Supabase client — this package never creates one); mount the returned `SilentCallback` at the callback path (default `/silent-callback`), ungated, outside the gate; wrap the app root in `<AuthGate>`; and, if embedded via `@nominalso/vibe-bridge`, call `wireVibeApp(bridge)` once at module scope from a parent of `AuthGate` — it performs the whole host handshake in the one correct order and returns `{ bridge, hostContext, getHostContext, subscribeHostContext }`. (`wireHostAuth` / `seedLastUserId` are the pre-0.2.3 hand-wiring; they still exist but new code should not use them.) `provider` is the app's Supabase Auth → Providers value — never guess it.
 
 Timing constraint: the factory call must happen synchronously at module scope, before any React effect or async work lets supabase-js's `detectSessionInUrl` strip the callback URL. In an SSR framework (Next.js, TanStack Start, Remix), the root layout must learn the current route from the router's own location state (identical on server and client), not from a render-time `typeof window` check — see `AGENTS.md` (Root wiring).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nominalso/vibe-auth",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Silent Supabase OIDC login for Nominal Vibe Apps — a configurable, cross-document-safe auth gate (Web-Lock-serialised silent SSO, identity-switch rebinding, popup fallback) that replaces a hand-copied per-app implementation.",
   "license": "UNLICENSED",
   "homepage": "https://github.com/nominalso/vibe-apps-sdk#readme",