@cosmoops/connect-sdk 0.2.0 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,125 @@
+# Changelog
+
+`@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
+versions may carry breaking changes** and patch versions never do.
+
+## 0.6.0
+
+### Added
+
+- **`ConnectAppShell`** - the application frame every service platform was
+  otherwise writing by hand: a collapsible sidebar, a top bar carrying the app
+  launcher and the account menu, a mobile drawer below `md`, and your pages in
+  the middle. Each platform passes `name`, `icon` and `nav`; the lockup, the
+  rail geometry, the active-route treatment and the chrome come from one
+  place, which is what keeps a family of platforms looking like one product.
+
+  It mounts `ConnectAccessGate` around `children` by default. That is a
+  deliberate default rather than a convenience: the shell is exactly the "wrap
+  your app content once" place that gate asks for, and a platform that ships a
+  shell and forgets the gate is a platform where a suspended workspace keeps
+  working. The chrome is never gated, and routes that *resolve* a block -
+  your pricing page - are flagged `gateExempt: true` on the nav item itself,
+  so the exemption lives next to the route rather than in a second list that
+  has to be kept in step.
+
+- **`ConnectSideNav`** - the sidebar's nav column on its own, for an app that
+  already has chrome it likes. Sections, one level of children, and the same
+  active-route resolution the shell uses.
+
+- **The nav model as data**: `ConnectNav` / `ConnectNavItem` /
+  `ConnectNavSection` types plus `normalizeNav`, `flattenNav`, `normalizePath`,
+  `resolveActivePath`, `isNavItemActive` and `gateExemptPaths`. Pure functions
+  over plain data, exported because a breadcrumb or a page title derived from
+  your own nav should not be able to disagree with what the rail highlights.
+
+- **`useActivePath`** - the current path, from your router when you pass one
+  and from the browser when you don't.
+
+  Routing is a prop throughout (`renderLink`), because this package ships into
+  any React app and cannot import `next/link`. The default is a plain `<a>`.
+  Uncontrolled, `useActivePath` patches `history.pushState`/`replaceState` to
+  dispatch an event - neither fires one, so a client-side router moves the
+  address bar and tells nothing outside itself, and a sidebar reading
+  `location.pathname` would highlight the route the page first loaded on
+  forever. Pass `activePath` (Next: `usePathname()`) and none of that runs.
+
+## 0.5.0
+
+### Breaking
+
+- **`react` and `react-dom` peers raised to `>=19`** (from `>=18`). Both stay
+  `optional` - a `/server`-only consumer still needs neither - but `/next`'s
+  `getConnectSession()` now imports `react`'s `cache()` unconditionally,
+  which React 18 doesn't export. Every current App Router project is already
+  on 19; this only bites a project still pinned to 18.
+
+### Added
+
+- **`getConnectSession()` is now memoized per request.** The plain,
+  zero-argument call - the one every page, layout and Server Action actually
+  uses - is wrapped in React's `cache()`, so calling it from a layout *and*
+  the page beneath it costs one round trip to Connect, not two. Passing an
+  explicit `request`, `client` or `session` still bypasses the cache and
+  always makes a live call, as before.
+- **`requireConnectSession()`** - `getConnectSession()` plus the
+  `if (!session) redirect(...)` every integration was writing by hand.
+  Redirects to `/api/connect/signin` (or `signInPath`) when signed out,
+  optionally appending `next`. See "Authentication & authorization" in the
+  docs for where role/entitlement checks still belong - this only covers the
+  "is anyone signed in" half.
+
+## 0.4.0
+
+### Breaking
+
+- **`ConnectUser.photoUrl` is a new required field.** Additive for anything
+  *reading* a `ConnectUser`, breaking for anything *constructing* one - a test
+  fixture or a hand-rolled mock will stop type-checking until it sets
+  `photoUrl: string | null`. Nothing else about the type changed.
+
+  Connect has always stored a profile picture; it was simply never carried on
+  the wire, so `<ConnectUserMenu>` showed initials for every account no matter
+  what the member had set. It now flows through `/sso/token` and `/sso/user`.
+
+### Added
+
+- **`<ConnectAccessGate>` and `useConnectAccessGate()`** - one gate composing
+  the four states a partner actually needs, in priority order: workspace
+  suspended, no subscription, onboarding approval pending, and a dismissible
+  payment-due banner during a dunning retry. Replaces hand-assembling
+  `ConnectReadinessGate` + `ConnectSubscriptionGate` and deciding the ordering
+  yourself.
+
+  Mount it once around your app's content, but **carve out your own plans and
+  pricing routes** - its "Choose a plan" state is where blocked customers are
+  sent, so gating that page too traps them. See the component's doc comment.
+
+- **`<ConnectProvider silentSignIn>`** - OIDC silent authentication. A visitor
+  already signed into Connect who has authorised your app before is signed in
+  with no click and no screen. Off by default: it costs one full-page redirect
+  on the first load of a signed-out visit, and is attempted at most once per
+  tab.
+
+  First contact still shows Connect's consent screen once - that grant is
+  exactly what makes every later visit silent.
+
+- `ReadinessBlockerCode` gains `organization_suspended` and
+  `payment_retry_pending`; `ReadinessBlocker` gains an optional `graceEndsAt`
+  carrying the dunning-suspension deadline, so a payment-due warning can show a
+  real countdown instead of a bare "something failed".
+
+- `identity.authorizeUrl({ prompt })` accepts `"none"` alongside `"create"`.
+
+### Fixed
+
+- `ConnectUserMenu` renders the member's actual profile picture, falling back
+  to initials while it loads or if they have none.
+- Panels inside the account modal shared one elevation and one icon-medallion
+  spec; the destination tiles and session list previously used a fill that is
+  the *same lightness* as the modal itself in both light and dark, so they read
+  as hairline outlines beside a solid identity card.
+- `theme.css` now defines `--default` and `--surface-tertiary`. Without them,
+  every `secondary`/`tertiary` Button and default Chip fell back to
+  `@heroui/styles`' stock cool-grey ramp while the rest of the palette sat on a
+  warm one - close enough to read as a mistake rather than a choice.

package/README.md

@@ -25,7 +25,7 @@ Browser  ──►  your backend  ──►  Connect
 
 ## Server setup
 
-One credential does three jobs — the API key plaintext from your service's Setup tab is also your OAuth2 `client_secret` and the key your `id_token` is signed with. Revoking it revokes all three.
+One credential does three jobs — the API key plaintext from your service's Integration tab is also your OAuth2 `client_secret` and the key your `id_token` is signed with. Revoking it revokes all three.
 
 ```ts
 import { ConnectClient } from "@cosmoops/connect-sdk/server";
@@ -87,6 +87,49 @@ if (!serviceRole.granted.includes("invoice:write")) return forbidden();
 await connect.identity.logout(sessionToken);
 ```
 
+## Sign returning visitors in with no click
+
+A visitor already signed into Connect should not have to press "Sign in"
+again. OIDC calls this silent authentication, and on `./next` it is one prop:
+
+```tsx
+<ConnectProvider silentSignIn>
+```
+
+On the first load of a signed-out visit the browser makes one round trip to
+Connect with `prompt=none`. If they have a Connect session **and** have
+authorised your app before, they come back signed in having seen nothing. If
+not, they come back signed out — no error, no screen, your normal signed-out
+UI a beat later.
+
+Rolling it yourself is the same flow with `prompt: "none"`:
+
+```ts
+redirect(connect.identity.authorizeUrl({ redirectUri, state, prompt: "none" }));
+```
+
+Three things to get right, all handled for you by `./next`:
+
+- **`prompt=none` never shows a login screen — that is its contract.** Use it
+  to *resume* a session, never to start one. Sending a genuinely signed-out
+  visitor through it in a loop is the classic way to build a redirect loop.
+- **`login_required` from a silent attempt is not the `login_required` above.**
+  The retry in step 2 is right for an interactive sign-in and wrong here: it
+  escalates a quiet "nobody home" into a forced login. Track which kind of
+  attempt is in flight.
+- **Attempt it at most once per tab.** A visitor with no Connect session will
+  answer the same way on every page load; without a marker, every navigation
+  pays a full redirect.
+
+**First contact still shows Connect's consent screen once.** That grant is
+exactly what makes every later visit silent, and it is per user, per client —
+so `consent_required` means "they have never authorised you", not "something
+broke". Treat all three of `login_required`, `consent_required` and
+`interaction_required` as "carry on signed out".
+
+It costs a full-page redirect on that first load, which is why it is off by
+default: worth it for an app shell, less so for a marketing page.
+
 ## Gate on entitlements
 
 ```ts
@@ -149,6 +192,7 @@ try {
 | `logs` | `write` |
 | `apps` | `list` |
 | `sessions` | `list` · `revoke` · `revokeOthers` |
+| `integrations` | `list` · `initiateConnect` · `disconnect` · `execute` |
 
 ### Attributing a log to a user
 
@@ -215,7 +259,7 @@ cookie, `/session`, `/entitlements`, `/plans`, `/addons`, `/apps`, `/sessions`,
 | `CONNECT_SESSION_COOKIE` | no | session cookie name |
 
 Register `{your origin}/api/connect/callback` as a redirect URI in the service's
-Setup tab — the one step this cannot do for you.
+Integration tab — the one step this cannot do for you.
 
 No `next.config.ts` changes needed, including `transpilePackages`: `dist/` is
 already ES2022 with `"use client"` hoisted, so Turbopack and webpack both
@@ -235,9 +279,26 @@ export default async function DashboardPage() {
 }
 ```
 
+Or skip the check-and-redirect entirely — `requireConnectSession()` does both:
+
+```tsx
+import { requireConnectSession } from "@cosmoops/connect-sdk/next";
+
+export default async function DashboardPage() {
+  const session = await requireConnectSession(); // UserResponse — redirects if signed out
+  return <h1>{session.user.organizationName}</h1>;
+}
+```
+
 Pass a `Request` — `getConnectSession(request)` — anywhere `next/headers` does
 not exist: a framework-agnostic handler, a custom server, a test.
 
+Both are memoized per request when called with no arguments (React's
+`cache()`), so a layout reading the session for a nav avatar and the page
+beneath it reading it again for a role check share one round trip to Connect,
+not two. An explicit `request`, `client` or `session` argument bypasses the
+cache and always makes a live call.
+
 It reads `cookies()` transitively, so under `cacheComponents` it belongs inside
 a `<Suspense>` boundary like any other request-scoped read. A page that awaits
 it above every boundary gives up its static shell.
@@ -245,6 +306,68 @@ it above every boundary gives up its static shell.
 You do **not** need `transpilePackages`. `dist/` is ES2022 with `"use client"`
 already hoisted, so Turbopack and webpack consume it as-is.
 
+## Route protection and `proxy.ts`
+
+Nothing here is auto-wired, and nothing needs to be: this SDK ships no proxy and
+never writes one. Next 16 renamed Middleware to **Proxy** — a single `proxy.ts`
+at the project root (or in `src/`, beside `app/`).
+
+You only need one if you want unauthenticated visitors bounced *before* a page
+renders. If you are happy redirecting inside the page, `getConnectSession()`
+above already does the job and there is nothing to add.
+
+If you do add one, keep it to a cookie **presence** check:
+
+```ts
+// proxy.ts
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+
+const COOKIE = process.env.CONNECT_SESSION_COOKIE ?? "connect_session";
+
+export function proxy(request: NextRequest) {
+  if (request.cookies.has(COOKIE)) return NextResponse.next();
+
+  const signin = new URL("/api/connect/signin", request.url);
+  signin.searchParams.set("next", request.nextUrl.pathname);
+  return NextResponse.redirect(signin);
+}
+
+// Must not match /api/connect/* — the sign-in route has no session cookie yet,
+// so matching it would redirect the sign-in to itself.
+export const config = { matcher: ["/dashboard/:path*", "/settings/:path*"] };
+```
+
+**A cookie is not a session, and this check is not authorization.** The cookie
+holds an opaque Connect `sessionToken`; deciding whether it is still valid means
+asking Connect, and proxy runs on every matched request — so a real check here
+would put a network round trip in front of each one. Next's own guidance says
+the same thing: proxy is for [optimistic
+checks](https://nextjs.org/docs/app/guides/authentication#optimistic-checks-with-proxy-optional),
+"not ... a full session management or authorization solution."
+
+An expired or revoked token still arrives as a cookie and still passes the
+snippet above. The authoritative check is `getConnectSession()` in the Server
+Component, or `client.entitlements.*` on your server — treat the proxy purely as
+a way to skip rendering a page the visitor cannot use.
+
+### The server/client boundary
+
+`@cosmoops/connect-sdk/server` and `/next` build a client around
+`CONNECT_API_KEY`; `/client` holds no credential and calls your own origin. That
+split is enforced, not just documented — both credential-holding entries resolve
+to a stub in a browser bundle, so importing one from a client component fails the
+build:
+
+```
+No matching export in ".../dist/esm/this-entry-is-server-only.js" for import "ConnectClient"
+```
+
+Import from `/client` instead, or use `import type`, which erases before any
+bundler sees it. Server Components, Route Handlers, Server Actions and non-Next
+backends are unaffected — the stub is wired to the `browser` export condition,
+which only a client bundle resolves.
+
 ## Other frameworks
 
 Mount the bridge once in your backend:
@@ -282,11 +405,16 @@ that URL yourself instead.
 
 ```tsx
 import {
+  ConnectAppShell,
   ConnectLoginButton, ConnectRegisterButton,
   ConnectUserMenu, ConnectAppsGrid, ConnectPlans,
 } from "@cosmoops/connect-sdk/client";
 
-// Top bar — the pair swaps automatically on sign-in state
+// The whole frame — sidebar, top bar, access gate. See "App shell" below.
+<ConnectAppShell name="Dispatch" nav={nav}>{children}</ConnectAppShell>
+
+// Or the pieces, if you already have a layout. The pair swaps automatically
+// on sign-in state.
 <ConnectAppsGrid />
 <ConnectLoginButton />
 <ConnectUserMenu />
@@ -297,12 +425,15 @@ import {
 
 | Component | What it does |
 | --- | --- |
+| `ConnectAppShell` | **The whole application frame** — collapsible sidebar, top bar with the launcher and account menu, and your pages in the middle. Mounts `ConnectAccessGate` for you. |
+| `ConnectSideNav` | The sidebar's nav column on its own — sections, one level of children, active-route highlight — for an app that already has its own chrome. |
 | `ConnectLoginButton` · `ConnectRegisterButton` | "Continue with Connect", in the shape people know from Google. Render nothing when signed in. |
 | `ConnectUserMenu` | Avatar, name, workspace. Profile, Manage subscription and Open Connect each open Connect in a new tab; Sign out acts in place. Renders nothing when signed out. |
 | `ConnectAppsGrid` | Google-style launcher — grid icon opening a modal of every app this workspace can open. |
 | `ConnectPlans` | Monthly/annual toggle, features, add-ons, live discount, coupon field, and the subscribe / upgrade / downgrade / cancel flow. |
 | `ConnectPlansPage` | A whole `/plans` page — readiness banner, current subscription, and the grid. What `connect-sdk init` scaffolds. |
 | `ConnectSubscribeDialog` | The review step `ConnectPlans` opens — plan, GST, what happens to the current cycle. Exported so you can drive the flow from your own pricing page. |
+| `ConnectAccessGate` | **The one gate to mount if you mount one.** Composes suspended / no-plan / onboarding-pending / payment-due into a single priority-ordered decision. Wrap your app content once. |
 | `ConnectSubscriptionGate` | Renders your module for a subscribed workspace, and `ConnectNoSubscriptionCard` for everyone else. Never flashes the upsell while loading. |
 | `ConnectNoSubscriptionCard` · `ConnectSubscriptionCard` | The same slot, unsubscribed and subscribed. Plan, status, renewal date, seats, and one way into Connect. |
 | `ConnectReadinessBanner` · `ConnectReadinessGate` | Every gate between this workspace and your service — KYC, payment method, seat headroom — each with the Connect screen that fixes it. |
@@ -315,7 +446,7 @@ import {
 
 ### Hooks
 
-`useConnect` · `useConnectUser` · `useConnectEntitlements` · `useConnectPlans` · `useConnectApps` · `useConnectAddonUsage` · `useConnectSessions` · `useConnectResource` · `useConnectFeature` · `useConnectCheckout`
+`useConnect` · `useConnectUser` · `useActivePath` · `useConnectAccessGate` · `useConnectEntitlements` · `useConnectPlans` · `useConnectApps` · `useConnectAddonUsage` · `useConnectSessions` · `useConnectResource` · `useConnectFeature` · `useConnectCheckout`
 
 ### Metering
 
@@ -334,13 +465,59 @@ The catalogue read (`useConnectPlans`, `<ConnectPlans />`) reports `features` as
 
 ### Gates
 
+Most apps want **one** gate around everything, and finer ones inside it.
+
+```tsx
+// Mount once, around your app's content — not around your header.
+<ConnectAccessGate>
+  <YourApp />
+</ConnectAccessGate>
+```
+
+`ConnectAccessGate` answers "can this workspace use my app right now" in one
+priority-ordered pass, so you are not left assembling the pieces and choosing
+the order yourself:
+
+| State | What renders |
+| --- | --- |
+| `suspended` | A hard stop. Nothing the customer does clears it — only a Connect admin reactivating the workspace. |
+| `no_subscription` | "Choose a plan", linking to Connect's subscribe page for your service. |
+| `onboarding_pending` | Waiting on a reviewer. No action offered, because there is none. |
+| `blocked` | Any other blocking readiness code — verification, audience, seats — each with its own fix. |
+| `payment_retry` | **Your app still renders.** A dismissible banner counts down to the dunning deadline. |
+| `clear` | Your app, nothing else. |
+
+**Carve out your own plans/pricing routes.** The `no_subscription` card sends
+people to choose a plan; if the gate also covers the page they land on, they
+are trapped. The SDK cannot do this for you — it imports nothing from `next`
+and so cannot know your router:
+
+```tsx
+const EXEMPT = new Set(["/plans", "/pricing"]);
+const gated = !EXEMPT.has(usePathname());
+
+<main>{gated ? <ConnectAccessGate>{children}</ConnectAccessGate> : children}</main>
+```
+
+For per-state UI, call the hook instead of overriding `fallback`:
+
+```tsx
+const { state, blocker, paymentRetry } = useConnectAccessGate();
+```
+
+Signed-out renders `children`, deliberately — unlike the gates below. None of
+those states describes a signed-out visitor, and a gate around your whole app
+must not hide a public landing page.
+
+The narrower gates still exist for gating *within* a cleared workspace:
+
 ```tsx
 <ConnectReadinessBanner />                       {/* KYC, payment method, seats — each with a fix */}
 <ConnectSubscriptionGate><Dashboard /></ConnectSubscriptionGate>
 <ConnectFeatureGate feature="advanced_reports"><Reports /></ConnectFeatureGate>
 ```
 
-All three render `loading` — never the fallback — while the answer is unknown, so a paying customer is never flashed an upsell for something they already have.
+All of them render `loading` — never the fallback — while the answer is unknown, so a paying customer is never flashed an upsell for something they already have.
 
 **They are UX gates, not security boundaries.** Everything they read reaches your own origin and a browser can ignore it. The authoritative check is on your server: `client.entitlements.getReadiness(orgId)` and `client.entitlements.hasFeature(orgId, feature)`.
 
@@ -350,7 +527,13 @@ All three render `loading` — never the fallback — while the answer is unknow
 npx @cosmoops/connect-sdk init
 ```
 
-Writes `app/api/connect/[...connect]/route.ts`, `app/plans/page.tsx` and an `.env.local` template, then prints the two steps it will not do for you (wrapping your layout in `<ConnectProvider>`, and registering the redirect URI in Connect). It never overwrites, so re-running is safe.
+Writes `app/api/connect/[...connect]/route.ts`, `app/plans/page.tsx` and an `.env.local` template, then prints the steps it will not do for you (wrapping your layout in `<ConnectProvider>`, importing the theme, and registering the redirect URI in Connect). It never overwrites, so re-running is safe.
+
+```bash
+npx @cosmoops/connect-sdk doctor
+```
+
+Checks a wired-up project and names what is missing: the bridge route (wherever you mounted it) exporting both verbs, exactly one `<ConnectProvider>`, the theme imported *after* `@heroui/styles`, and both credentials actually set rather than declared empty. Exits non-zero on a real problem, so it works as a CI step. It is entirely offline — no credentials, no network — which is also its one limit: Connect exposes no endpoint listing a client's registered redirect URIs, so that step is reported as something only you can confirm.
 
 Next has no plugin API that adds routes — `next.config` can rewrite and redirect, but both need a route to point at, and the App Router only discovers routes in your own `app/` directory. So this is a scaffolder rather than a plugin: `ConnectPlansPage` makes the file that must exist one line, and `init` writes that line.
 
@@ -390,6 +573,100 @@ const checkout = useConnectCheckout();
 
 Cancelling uses the same machinery via `buildCancelUrl`. There is no *resume*: Connect has no uncancel path, so a subscription already set to cancel gets a statement of when access ends, not a button that cannot work.
 
+### App shell
+
+```tsx
+"use client";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { ConnectAppShell } from "@cosmoops/connect-sdk/client";
+import { LayoutDashboard, Receipt, Settings, Truck } from "lucide-react";
+
+export function Shell({ children }: { children: React.ReactNode }) {
+  return (
+    <ConnectAppShell
+      name="Dispatch"
+      icon={<Truck />}
+      activePath={usePathname()}
+      renderLink={(props) => <Link {...props} />}
+      nav={[
+        { label: "Overview", href: "/", icon: <LayoutDashboard className="size-5" /> },
+        { label: "Shipments", href: "/shipments", icon: <Truck className="size-5" /> },
+        {
+          title: "Workspace",
+          items: [
+            {
+              label: "Settings",
+              href: "/settings",
+              icon: <Settings className="size-5" />,
+              items: [
+                { label: "Members", href: "/settings/members" },
+                { label: "Billing", href: "/settings/billing" },
+              ],
+            },
+            { label: "Plans", href: "/plans", icon: <Receipt className="size-5" />, gateExempt: true },
+          ],
+        },
+      ]}
+    >
+      {children}
+    </ConnectAppShell>
+  );
+}
+```
+
+That is the entire layout of a service platform. Everything that should look
+identical across the family — the lockup, the rail geometry, the active-route
+treatment, the app launcher, the account menu, the mobile drawer — comes from
+here; only `name`, `icon` and `nav` differ per platform.
+
+**Routing is a prop.** The SDK ships into any React app and cannot import
+`next/link`, so `renderLink` is how your router gets involved; the default is a
+plain `<a>`, which works everywhere and costs a full page load. Pass
+`activePath` from your router too (`usePathname()`) — without it the nav reads
+`window.location` and patches `history.pushState` to hear about client-side
+navigations, which is guesswork your router never has to do.
+
+**The access gate is on by default.** `ConnectAppShell` is exactly the "wrap
+your app content once" place `ConnectAccessGate` asks for, so it mounts one
+around `children` — an app that ships a shell and forgets the gate is an app
+that lets a suspended workspace keep working. The chrome is never gated: the
+sidebar, the lockup, the account menu and sign-out stay reachable in every
+blocked state. Routes that resolve a block rather than needing one — your
+pricing page — are flagged where they are declared:
+
+```tsx
+{ label: "Plans", href: "/plans", gateExempt: true }
+```
+
+Gate a route any other way and a customer with no subscription reaches the
+page that sells them one, and is told to choose a plan. Pass `gate={false}` to
+opt out entirely, or `gateExemptRoutes` for a path that is not in the sidebar
+at all.
+
+Other things worth knowing:
+
+- **The rail collapses to icons** and remembers the choice per browser
+  (`localStorage`). Drive it yourself with `collapsed` + `onCollapsedChange`,
+  or pin it open with `collapsible={false}`.
+- **Below `md` there is no rail**, only a drawer behind the top bar's menu
+  button — a 64px icon strip on a phone is a worse drawer, not a smaller one.
+- **Children unfold only on the branch you are on.** A sidebar that opens
+  every branch at once is a sitemap.
+- **No `isSignedIn` branch, in here or in yours.** The auth buttons render
+  nothing once a session exists, the account menu renders nothing without one,
+  and the launcher renders nothing when signed out.
+- `title`, `headerActions`, `sidebarFooter` and `footer` are slots;
+  `contentClassName` replaces the content pane's default max-width and
+  padding.
+- `theme` / `onThemeChange` pass straight through to `ConnectUserMenu` — the
+  SDK has no theme provider of its own, deliberately.
+
+`ConnectSideNav` is the nav column alone, for an app with chrome it already
+likes. `resolveActivePath` and `isNavItemActive` are the same pure functions
+the rail highlights with, exported so a breadcrumb or a document title derived
+from your nav cannot disagree with it.
+
 ### Logo
 
 ```tsx
@@ -411,7 +688,7 @@ Each platform passes only what differs — `name` and `icon`. Mark geometry, wor
 
 One shared **HeroUI v3** theme for every service platform. The components paint with semantic tokens only — `accent`, `muted`, `surface`, `separator`, `danger` — never a hardcoded colour, so one edit to the theme restyles all of them everywhere at once. To diverge on brand, redefine individual tokens *after* the import rather than forking the file.
 
-Requires `@heroui/react` and `lucide-react` as peers (optional — server-only consumers need neither).
+Requires `@heroui/react`, `lucide-react` and `motion` as peers (optional — server-only consumers need none of them). `motion` drives the components' entrance and state transitions, and respects `prefers-reduced-motion`.
 
 ### Why payment happens on Connect