@powerhousedao/reactor-browser 6.2.2-dev.5 → 6.2.2-dev.50

package/README.md

@@ -9,6 +9,7 @@ This document contains all documentation comments for the hooks exported from `p
 - [Config: Editor](#config-editor)
 - [Config: Set Config by Object](#config-set-config-by-object)
 - [Config: Use Value by Key](#config-use-value-by-key)
+- [Renown in-page sign-in](#renown-in-page-sign-in)
 - [Document by ID](#document-by-id)
 - [Document Cache](#document-cache)
 - [Document of Type](#document-of-type)
@@ -507,3 +508,285 @@ Strongly typed, inferred from type definition for the key.
 Gets the value of an item in the global document config for a given key.
 
 Strongly typed, inferred from type definition for the key.
+
+---
+
+## Renown in-page sign-in
+
+Let users authenticate with Renown **inside your app** — no redirect to the
+Renown portal — using pluggable wallet adapters (RainbowKit for external
+wallets, Privy for social/email). This is the same integration Connect and the
+`test-fusion` app use. Import from `@powerhousedao/reactor-browser/renown` (or
+the package root).
+
+### Quick start — `RenownProvider`
+
+Mount one provider high in your tree. It initializes the SDK, seeds the first
+render (from a server session cookie for SSR, or `localStorage` for client-only
+apps), mounts the wallet adapters (lazy-loaded on the first login click), keeps a
+server-readable session cookie in sync when running under SSR, and revalidates
+the stored credential against the switchboard.
+
+```tsx
+import { RenownProvider } from "@powerhousedao/reactor-browser/renown";
+import { privyAdapter } from "@renown/sdk/wallet/privy";
+import { rainbowAdapter } from "@renown/sdk/wallet/rainbow";
+
+// Module scope: the provider snapshots this array on mount.
+const ADAPTERS = [
+  rainbowAdapter({ walletConnectProjectId: "..." }),
+  privyAdapter({ appId: "...", methods: ["google", "email"] }),
+];
+
+<RenownProvider
+  appName="my-app"
+  namespace="my-app"
+  switchboardUrl="https://switchboard.example/graphql"
+  adapters={ADAPTERS}
+  theme="light" // "light" | "dark" | { mode, accentColor?, accentColorForeground? }
+>
+  <App />
+</RenownProvider>;
+```
+
+**One chain per app.** `chainId` (default `1`) is the chain credentials are issued
+on, and it is part of the user's DID (`did:pkh:eip155:<chainId>:<address>`), so the
+same wallet on another chain is a different user. Sign-in from a wallet on a
+different chain is rejected, so if you set `chainId`, pass matching `chains` to the
+wallet adapters — that is what makes the wallet UI prompt a network switch rather
+than failing at the end of the flow.
+
+**Install only the peers of the adapters you import.** Importing
+`@renown/sdk/wallet/rainbow` is what makes RainbowKit a build requirement; an app
+that only imports `@renown/sdk/wallet/privy` needs no RainbowKit and no bundler
+aliases. See the `@renown/sdk` README for the per-adapter peer list.
+
+The provider is **SSR-safe** — it renders on the server without `ssr: false`;
+the wallet libraries only load client-side on the first login click.
+
+Then build the login UI with `useRenownLoginMethods` (the button list, read from
+the mounted provider) and `useRenownAuth` (login + user state). Neither takes the
+adapters, so the login UI need not sit inside the provider's subtree:
+
+```tsx
+import {
+  useRenownAuth,
+  useRenownLoginMethods,
+} from "@powerhousedao/reactor-browser/renown";
+
+function Login() {
+  const { user, login, pending, error, logout } = useRenownAuth();
+  const methods = useRenownLoginMethods();
+  if (user) return <button onClick={() => void logout()}>Log out</button>;
+  return (
+    <>
+      {methods.map((m) => (
+        <button key={m.id} disabled={pending} onClick={() => login(undefined, m.id)}>
+          {m.label}
+        </button>
+      ))}
+      {error ? <p>{error.message}</p> : null}
+    </>
+  );
+}
+```
+
+`login(session?, method?)` activates the adapters on click, routes `method` to
+the adapter that supports it, produces a `WalletSession`, and completes the
+Renown credential sign-in via the switchboard — falling back to the redirect
+flow when no switchboard/adapter is available.
+
+### À la carte
+
+`RenownProvider` composes pieces you can also mount yourself — use them directly
+only when you need a custom tree:
+
+- `<Renown appName namespace switchboardUrl revalidate? />` — SDK init (renders
+  `null`; place high in the tree).
+- `RenownWalletProvider` — wallet adapters (below).
+- `RenownInitialUserProvider` — seeds the first render, via `initialAuth`
+  (three-state, preferred) or `initialUser` (a bare `User`; cannot express
+  "known signed out"). See [Server-side rendering](#server-side-rendering-ssr).
+
+### Auth state — `useRenownAuth` / `useRenownAuthAsync`
+
+`useRenownAuth()` returns the live auth: `{ user, status, pending, error, login,
+logout, displayName, displayAddress, ... }`. Gate on it with a plain `if` — no
+wrapper component is needed:
+
+```tsx
+function EditButton() {
+  const { user } = useRenownAuth();
+  if (!user) return null;
+  return <button>Edit</button>;
+}
+```
+
+`useRenownAuthAsync()` adds a collapsed `state: "authenticated" | "resolving" |
+"unauthenticated"` (and `isResolving`) so you can show a skeleton during the
+resolving window **without a Suspense boundary** — handy for client-only apps:
+
+```tsx
+function EditButton() {
+  const { state } = useRenownAuthAsync();
+  if (state === "resolving") return <EditSkeleton />;
+  if (state === "unauthenticated") return null;
+  return <button>Edit</button>;
+}
+```
+
+`"resolving"` only appears when the answer is genuinely unknown. If the first
+render already knows the visitor is signed out — no session cookie on the server,
+no persisted user in `localStorage` — the state goes straight to
+`"unauthenticated"`, so a logged-out visitor never sees the skeleton while the
+SDK builds its keypair. A login you triggered (`pending`) still reports
+`"resolving"`. `useRenownInitialAuth()` exposes the underlying signal as
+`{ state: "authenticated" | "anonymous" | "unknown" }`.
+
+### Server-side rendering (SSR)
+
+The provider tree is SSR-safe, so the logged-out shell renders on the server with
+no `ssr: false`. To render **authenticated** content on the server (no flash),
+give `RenownProvider` a server-resolved `session`:
+
+```tsx
+// app/layout.tsx (server component)
+import { verifySession } from "@/lib/dal";
+
+const session = await verifySession(); // reads + verifies the session cookie
+<RenownProvider appName="my-app" session={session}>
+  {children}
+</RenownProvider>;
+```
+
+Passing `session` also enables the **session-cookie sync**: after each login the
+client mints a bearer token and POSTs it to `sessionEndpoint` (default
+`/api/renown/session`), and clears it on logout. Your app provides the route
+handler that sets an HttpOnly cookie, and a Data Access Layer that verifies it
+with `verifyRenownSession` from `@renown/sdk/node` (see that package's README).
+
+The POST body is a `RenownSessionCookie` — the bearer token plus a
+`RenownSessionProfile` display hint carrying `documentId`, `username` and
+`userImage`. Those let `verifyRenownSession` rebuild a `user.profile` matching
+the client's, so the server renders the same name, avatar and profile links the
+client will. Type your route handler with `RenownSessionCookie` rather than
+redeclaring the shape — three copies of it drift.
+
+### Seeding: which source wins
+
+The first render is seeded from whichever source can answer at that moment:
+
+| Render | Source | Why |
+| --- | --- | --- |
+| Server | `session` (the cookie) | The only thing readable server-side |
+| Hydration | `session` | Must match the server output |
+| After mount | `localStorage` | Holds the credential the SDK actually restores |
+
+`localStorage` becomes authoritative once mounted because that is what the SDK
+reads on build; the cookie is a display hint that can go stale independently (it
+expires on its own schedule). Omit `session` entirely for client-only apps —
+`localStorage` then seeds every render, so a returning user is authenticated on
+the first paint with no server involved.
+
+### Revalidation and profile refresh
+
+Two separate background passes run on mount, neither blocking the paint:
+
+- **Credential revalidation** re-checks the restored credential against the
+  switchboard and logs the user out if it was revoked or expired. Gated by the
+  `revalidate` prop (default `"always"`; `"never"` skips it). Fail-open — a
+  transient outage keeps the session.
+- **Profile refresh** re-reads `username`/`userImage` and updates the store if
+  they changed. This runs **regardless of `revalidate`**, because it can never
+  log anyone out; apps that disabled revalidation still get fresh attributes.
+
+Neither replaces server-side checks: the switchboard enforces the credential on
+every real operation.
+
+### `RenownWalletProvider`
+
+Registers the login activator, lazy-mounts the given adapters, and merges them
+into one controller for `useRenownAuth`. The wallet Provider tree wraps only the
+adapter bridges (each library's modal portals to `<body>`), never your
+`children`, so activating login never remounts your app. Props: `adapters`
+(`WalletAdapterDescriptor[]`), `theme?`, `children`.
+
+### `useRenownLoginMethods(labels?)`
+
+Returns `{ id, label }[]` — one per login method the mounted
+`RenownWalletProvider`'s adapters offer, deduped, in descriptor-array order —
+reading each descriptor's eager metadata only (no wallet libraries load).
+Reorder the array you pass the provider to reorder the buttons. Override labels
+via the argument. Wire each to `login(undefined, id)`.
+
+The descriptors come from the provider, not from a prop or context, so a login UI
+mounted **outside** the provider's subtree still gets the full list — Connect
+renders its login modal as a sibling of the app. Empty when no provider is
+mounted, which is the redirect-only case.
+
+### Next.js
+
+The integration is the same, with four things worth knowing:
+
+- Pass `ssr: true` to `rainbowAdapter` so wagmi defers its hydrate reconnect to
+  an effect instead of running it during render.
+- Keep the descriptor array at **module scope** (or in a `useMemo`).
+  `RenownWalletProvider` snapshots it on mount, so an array rebuilt inline in JSX
+  silently pins the first render's value.
+- Give the descriptor array **its own module**, separate from config your server
+  code reads. Turbopack follows the adapters' lazy imports when computing RSC
+  boundaries, so a server module that imports anything sitting next to the
+  descriptors pulls the client-only wallet factories into the server graph and
+  the build fails.
+- `RenownProvider` is SSR-safe: no `ssr: false`, no dynamic import needed. Only
+  the component that renders login buttons needs `"use client"`.
+- Nothing needs a `next.config.ts` alias. If you find yourself stubbing
+  `@renown/sdk/wallet/<id>`, you are importing an adapter you don't use.
+
+`test/test-fusion` in the monorepo is a runnable Next.js example (App Router,
+server session cookie, Playwright e2e against the mock adapter).
+
+### Writing your own adapter
+
+`RenownWalletProvider` takes descriptors, not a fixed set of adapter ids, so any
+package can supply one. The contract is:
+
+```ts
+import type { WalletAdapterDescriptor } from "@renown/sdk/wallet";
+
+export function myAdapter(config: MyConfig): WalletAdapterDescriptor {
+  return {
+    meta: {
+      id: "my-adapter", // stable + unique among the host's adapters
+      supportedMethods: ["wallet"], // must be known before load()
+      redirectReturnParams: [], // URL params your full-page OAuth return leaves
+    },
+    load: () => import("./factory.js").then((m) => m.createMyAdapter(config)),
+  };
+}
+```
+
+`load()` resolves a `WalletAdapterImpl`: a `Provider` component and a
+`useController()` hook returning `connect(method?)` / `disconnect()` /
+`getSession()` and, if your flow leaves the page, `subscribe()` so sign-in can
+complete on the redirect back. Keep the module holding `myAdapter` free of your
+wallet library — `meta` is read before anything loads. `supportedMethods` must
+come from `LoginMethod` (`wallet`, `google`, `email`, `apple`); a method the host
+has no label for falls back to showing its id.
+
+### Testing (mock adapter)
+
+For e2e/dev, enable the **mock adapter** (`@renown/sdk/wallet/mock`) via the
+`mock` key. It's a headless signer backed by a viem local account — real EIP-712
+signatures, **no wallet extension or OAuth** — so sign-in runs deterministically
+in CI. **TEST/DEV ONLY; never enable in production** (it signs with a known key).
+
+```tsx
+<RenownWalletProvider adapters={{ mock: { methods: ["wallet", "google", "email"] } }}>
+  <App />
+</RenownWalletProvider>
+```
+
+See `test/test-fusion/e2e` (Playwright + mock adapter) and `test/vetra-e2e`
+(Connect login surface) for runnable examples, and the Powerhouse Academy
+"Renown authentication flow" guide for the full walkthrough.