@poly-x/react 0.2.0 → 0.3.0

package/README.md

@@ -72,11 +72,107 @@ and it lives in the PolyX console with the permission model and audit trail.
 Email, username and password are likewise excluded: each has its own verification
 path that a profile form must not route around.
 
+## Signing in silently, and switching workspace
+
+Someone already signed into another application on the same domain should not be asked for a
+password again. `useWarmHop()` tries that once when your sign-in screen mounts:
+
+```tsx
+import { useWarmHop, SignIn } from "@poly-x/react";
+
+export default function SignInPage() {
+  const hop = useWarmHop();
+  if (hop.status !== "settled") return null;                 // never a half-drawn form
+  if (hop.result.status === "signed_in") router.replace("/");
+  return <SignIn />;                                          // the ordinary path
+}
+```
+
+A failed attempt is invisible on purpose. Someone who is genuinely signed out pays the whole
+cost of this and gains nothing from it, so there is a hard timeout, nothing in the flow
+navigates, and every failure — offline, slow platform, unexpected response — ends at "show the
+form" rather than at an exception or a spinner.
+
+The attempt runs **once per tab**. The marker lives in `sessionStorage` rather than component
+state because the fall-back renders the sign-in page, which is a route change in most apps — a
+guard in state would reset at exactly the moment it needs to hold. Call `resetWarmHop()` after
+signing out so the next sign-in may try again.
+
+### Switching workspace
+
+Someone with access to several workspaces can move between them without a password:
+
+```tsx
+import { switchWorkspace } from "@poly-x/react";
+
+const result = await switchWorkspace(tenantId);
+if (result.status === "signed_in") router.refresh();          // now scoped to that workspace
+if (result.status === "no_access") showNoAccess();
+```
+
+When someone has more than one workspace and none was named, the settled result is
+`{ status: "select_workspace", workspaces }` — the SDK never picks for you, because putting
+someone to work in the wrong tenant without their noticing is worse than asking:
+
+```tsx
+const hop = useWarmHop();
+if (hop.status === "settled" && hop.result.status === "select_workspace") {
+  return <WorkspacePicker options={hop.result.workspaces} onPick={switchWorkspace} />;
+}
+```
+
+Entitlement is decided **by the platform at the moment of the switch**, not from the list you are
+holding, so a workspace revoked since you drew the picker never lets them in. What you get back
+depends on what is left: still hold other workspaces and you get `select_workspace` listing them;
+lost them all and you get `no_access`. Either way, not entry — so do not cache the decision in
+front of it.
+
+### When the workspace you asked for is quietly ignored
+
+Worth knowing, because success is not always what it looks like. PolyX only honours a workspace
+hint when the person has **more than one** workspace for that application. With exactly one, it
+ignores the hint and seats them there anyway — answering an ordinary success. Nobody gains access
+they are not entitled to, but they can end up **working in the wrong tenant without noticing**,
+which is the failure the picker exists to prevent.
+
+The SDK will not relay that as plain success. Pass a **tenant id** and land somewhere else, and you
+get `workspace_mismatch` carrying both:
+
+```tsx
+const result = await switchWorkspace(tenantId);
+if (result.status === "workspace_mismatch") {
+  // result.requested — what you asked for
+  // result.workspace — where they actually are now
+}
+```
+
+The session is left in place: it is valid, and you may be perfectly happy with it. What to do about
+it is your call, not the SDK's.
+
+An **organization code or slug** cannot be compared against what a session carries, so no mismatch
+is claimed for those — guessing would invent failures. Instead **every** successful result names
+the workspace actually entered, so you can check for yourself:
+
+```tsx
+if (result.status === "signed_in" && result.workspace !== expected) { /* … */ }
+```
+
+Switching does not navigate or reload — the SDK cannot know what is unsaved on your screen, so
+what happens next is yours to decide.
+
+### The boundary
+
+Silent sign-on works between applications that **share the ecosystem cookie's domain**.
+Browsers block third-party cookies by default, so an application on an unrelated domain falls
+back to ordinary sign-in. That is browser policy, not something to configure around.
+*Switching workspace is unaffected* — it happens inside one application.
+
 ## API
 
 `PolyXProvider` · `useAuth` (`isLoaded`, `isSignedIn`, `signIn`, `signOut`,
 `getToken`) · `useUser` · `useSession` · `<SignIn>` · `<Protected>` ·
-`<UserButton>` · `<UserProfile>` · `<AuthCallback>`. Sign-in defaults to a popup;
-pass `mode="redirect"` for a full-page flow.
+`<UserButton>` · `<UserProfile>` · `<AuthCallback>` · `useWarmHop` ·
+`attemptWarmHop` · `switchWorkspace` · `resetWarmHop`. Sign-in defaults to a
+popup; pass `mode="redirect"` for a full-page flow.
 
 MIT licensed.

package/dist/index.cjs

@@ -200,7 +200,7 @@ var BroadcastChannelSessionChannel = class {
 //#endregion
 //#region src/seams/session-storage-pkce.ts
 const KEY_PREFIX = "poly-x.pkce.";
-function hasSessionStorage() {
+function hasSessionStorage$1() {
 	try {
 		return typeof sessionStorage !== "undefined";
 	} catch {
@@ -216,7 +216,7 @@ function hasSessionStorage() {
 var SessionStoragePkceStore = class {
 	fallback;
 	constructor() {
-		if (!hasSessionStorage()) this.fallback = new _poly_x_core.InMemoryPkceStore();
+		if (!hasSessionStorage$1()) this.fallback = new _poly_x_core.InMemoryPkceStore();
 	}
 	save(entry) {
 		if (this.fallback) return this.fallback.save(entry);
@@ -481,6 +481,198 @@ function getBffSessionStore() {
 	return store;
 }
 //#endregion
+//#region src/warm-hop.ts
+/**
+* Warm hop — the browser half (F027/F028 · FR-HOP-1…6, FR-FALL-1…3, FR-SWITCH-1…7).
+*
+* The probe is made **from here, by the browser**, and that is not a style choice. The
+* platform resolves the ecosystem session from a cookie on its own domain; a server-side
+* request carries no browser cookie, so it would be told "sign-in required" every time and
+* the whole feature would look built while never working. `@poly-x/core` refuses the
+* server-side call outright for that reason.
+*
+* The three steps, and why the credential stays safe throughout:
+*
+*   1. Ask our own BFF to prepare (`/api/polyx/hop`). It mints PKCE and keeps the verifier
+*      in an httpOnly cookie; we receive only a URL.
+*   2. Call that URL with `credentials:"include"` so the browser attaches the ecosystem
+*      cookie. This is the one request that must not come from a server.
+*   3. Hand the resulting `code` back to our BFF (`/api/polyx/hop-complete`), which does the
+*      exchange. The code is worthless to anyone who intercepts it — the PKCE verifier that
+*      redeems it never left the server — so a page holding it briefly is not a custody leak.
+*
+* Nothing here navigates. That matters beyond tidiness: this exact flow produced a redirect
+* loop in a hand-rolled implementation once already, and a fetch cannot loop.
+*/
+const HOP_ENDPOINT = "/api/polyx/hop";
+const HOP_COMPLETE_ENDPOINT = "/api/polyx/hop-complete";
+/**
+* How long to wait for the silent attempt before giving up and showing the form.
+*
+* A guess, and labelled as one. The requirement it serves (FR-FALL-2) is that a slow or
+* dead platform must never leave someone watching a spinner — and for that, *any* bound
+* beats none. The person this protects is already signed out and gains nothing from
+* waiting, so the bound is deliberately short. Override it if you have measured yours.
+*/
+const WARM_HOP_TIMEOUT_MS = 5e3;
+/**
+* Survives navigation on purpose (FR-FALL-3).
+*
+* The fall-back from a failed attempt renders the sign-in page, which in most apps is a
+* route change — so a guard held in React state or a module variable is reset exactly when
+* it is needed. `sessionStorage` is scoped to the tab and cleared when it closes, which is
+* the same lifetime as "this entry".
+*/
+const ATTEMPTED_KEY = "polyx.warmHop.attempted";
+function hasSessionStorage() {
+	try {
+		return typeof sessionStorage !== "undefined";
+	} catch {
+		return false;
+	}
+}
+/** Has an automatic attempt already run in this tab? */
+function warmHopAttempted() {
+	if (!hasSessionStorage()) return false;
+	try {
+		return sessionStorage.getItem(ATTEMPTED_KEY) === "1";
+	} catch {
+		return false;
+	}
+}
+function markWarmHopAttempted() {
+	if (!hasSessionStorage()) return;
+	try {
+		sessionStorage.setItem(ATTEMPTED_KEY, "1");
+	} catch {}
+}
+/** Clear the once-per-entry marker. Exported for sign-out, so the next sign-in may try again. */
+function resetWarmHop() {
+	if (!hasSessionStorage()) return;
+	try {
+		sessionStorage.removeItem(ATTEMPTED_KEY);
+	} catch {}
+}
+async function postJson(url, body, signal) {
+	return fetch(url, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify(body ?? {}),
+		signal,
+		credentials: "same-origin"
+	});
+}
+/**
+* Run one silent attempt and report what the platform said.
+*
+* Never throws: every failure resolves to `failed`, because a caller in the middle of
+* rendering a sign-in page has no better answer than "show the form" and an exception
+* there is how a blank screen happens.
+*/
+async function attemptWarmHop(options = {}) {
+	if (typeof window === "undefined") return {
+		status: "failed",
+		reason: "warm hop attempted outside a browser"
+	};
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 5e3);
+	try {
+		const prepared = await postJson(HOP_ENDPOINT, options.workspace ? { tenantId: options.workspace } : {}, controller.signal);
+		if (!prepared.ok) return {
+			status: "failed",
+			reason: `hop preparation failed (${prepared.status})`
+		};
+		const { authorizeUrl } = await prepared.json();
+		if (!authorizeUrl) return {
+			status: "failed",
+			reason: "hop preparation returned no authorize URL"
+		};
+		const probe = await fetch(authorizeUrl, {
+			method: "GET",
+			credentials: "include",
+			headers: { accept: "application/json" },
+			signal: controller.signal
+		});
+		const body = await probe.json().catch(() => ({}));
+		const outcome = (0, _poly_x_core.parseAuthorizeOutcome)(probe.status, body);
+		switch (outcome.type) {
+			case "login_required": return { status: "sign_in_required" };
+			case "no_access": return { status: "no_access" };
+			case "select_tenant": return {
+				status: "select_workspace",
+				workspaces: outcome.tenants
+			};
+			case "authorized": {
+				const completed = await postJson(HOP_COMPLETE_ENDPOINT, {
+					code: outcome.code,
+					state: outcome.state
+				}, controller.signal);
+				const settled = await completed.json().catch(() => ({}));
+				if (completed.ok) {
+					if (settled.status === "workspace_mismatch" && settled.requested && settled.workspace) return {
+						status: "workspace_mismatch",
+						requested: settled.requested,
+						workspace: settled.workspace
+					};
+					return {
+						status: "signed_in",
+						...settled.workspace ? { workspace: settled.workspace } : {}
+					};
+				}
+				return {
+					status: "failed",
+					reason: settled.status ?? `exchange failed (${completed.status})`
+				};
+			}
+		}
+	} catch (error) {
+		return {
+			status: "failed",
+			reason: error instanceof Error ? error.message : "warm hop failed"
+		};
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+/**
+* Move to another workspace (F028 / FR-SWITCH-1…6).
+*
+* The same mechanism as the entry attempt, aimed deliberately rather than on arrival — and
+* deliberately **not** subject to the once-per-entry guard, because this one is a thing the
+* person asked for.
+*
+* Eligibility is decided by the platform at this moment, not from any list held here, so a
+* workspace revoked since the picker was drawn can never be entered (FR-SWITCH-4). Which
+* refusal you get depends on what is left, verified against a live platform: still holding
+* other workspaces gives `select_workspace` listing them; having lost them all gives
+* `no_access`. Do not treat `no_access` as the only refusal.
+*
+* On `signed_in` the session cookie now names the new workspace. The caller decides what to
+* do next — the SDK does not reload the page or discard anything on their behalf, because it
+* cannot know what is unsaved on the screen (FR-SWITCH-7).
+*/
+async function switchWorkspace(workspace, options = {}) {
+	if (!workspace) return {
+		status: "failed",
+		reason: "no workspace given"
+	};
+	return attemptWarmHop({
+		...options,
+		workspace
+	});
+}
+/**
+* The automatic entry attempt: at most once per tab, whatever the caller does (FR-HOP-2).
+*
+* Returns `null` when it declines to attempt — already tried this entry — so a caller can
+* tell "we tried and they must sign in" from "we did not try".
+*/
+async function attemptWarmHopOnce(options = {}) {
+	if (warmHopAttempted()) return null;
+	markWarmHopAttempted();
+	return attemptWarmHop(options);
+}
+//#endregion
 //#region src/hooks.ts
 function useSessionSource() {
 	const ctx = (0, react.useContext)(PolyXContext);
@@ -550,6 +742,52 @@ function useUser() {
 	const state = useSession();
 	return state.status === "authenticated" || state.status === "refreshing" ? state.session.claims : null;
 }
+/**
+* Try a silent sign-in once when this component mounts (F027 / FR-HOP-2, FR-FALL-1…3).
+*
+* The contract that matters is D11's: **an attempt that fails must be invisible.** Someone who
+* is genuinely signed out pays the whole cost of this feature and gets nothing from it, so they
+* must not see a flicker, a spinner that outlives their patience, or — worst — a redirect loop.
+* Hence: no navigation anywhere in the flow, a hard timeout, and a guard that survives the route
+* change to the sign-in page (a guard in React state would reset exactly when it is needed).
+*
+* ```tsx
+* const hop = useWarmHop();
+* if (hop.status !== "settled" ) return null;              // no half-drawn form
+* if (hop.result.status === "signed_in") return <Redirect/>;
+* return <SignIn />;                                       // the ordinary path
+* ```
+*
+* Strict Mode's double-mount does not produce two attempts: the marker is written before the
+* first request goes out.
+*/
+function useWarmHop(options = {}) {
+	const { enabled = true, workspace, timeoutMs } = options;
+	const [state, setState] = (0, react.useState)({ status: "idle" });
+	(0, react.useEffect)(() => {
+		if (!enabled) return;
+		let live = true;
+		setState({ status: "attempting" });
+		attemptWarmHopOnce({
+			workspace,
+			timeoutMs
+		}).then((result) => {
+			if (!live) return;
+			setState({
+				status: "settled",
+				result: result ?? { status: "sign_in_required" }
+			});
+		});
+		return () => {
+			live = false;
+		};
+	}, [
+		enabled,
+		workspace,
+		timeoutMs
+	]);
+	return state;
+}
 //#endregion
 //#region src/components/protected.tsx
 /** Gate content on authentication state without flashing the wrong branch. */
@@ -2681,7 +2919,7 @@ function useAuthzChanged(callback) {
 */
 const PACKAGE_NAME = "@poly-x/react";
 /** The published version of this package, injected at build time. */
-const version = "0.2.0";
+const version = "0.3.0";
 //#endregion
 exports.AuthCallback = AuthCallback;
 exports.BroadcastAuthChannel = BroadcastAuthChannel;
@@ -2698,18 +2936,25 @@ exports.SignIn = SignIn;
 exports.UserAvatar = UserAvatar;
 exports.UserButton = UserButton;
 exports.UserProfile = UserProfile;
+exports.WARM_HOP_TIMEOUT_MS = WARM_HOP_TIMEOUT_MS;
 exports.WebLocksLock = WebLocksLock;
 exports.WindowBrowserBridge = WindowBrowserBridge;
+exports.attemptWarmHop = attemptWarmHop;
+exports.attemptWarmHopOnce = attemptWarmHopOnce;
 exports.capturePreciseLocation = capturePreciseLocation;
 exports.consumeAuthEvent = consumeAuthEvent;
 exports.createLoginController = createLoginController;
 exports.initialsFrom = initialsFrom;
+exports.resetWarmHop = resetWarmHop;
 exports.resolveSide = resolveSide;
 exports.startLiveAuthz = startLiveAuthz;
+exports.switchWorkspace = switchWorkspace;
 exports.useAuth = useAuth;
 exports.useAuthCallback = useAuthCallback;
 exports.useAuthzChanged = useAuthzChanged;
 exports.useLiveAuthz = useLiveAuthz;
 exports.useSession = useSession;
 exports.useUser = useUser;
+exports.useWarmHop = useWarmHop;
 exports.version = version;
+exports.warmHopAttempted = warmHopAttempted;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { ReactNode } from "react";
-import { AuthClient, Lock, PkceEntry, PkceStore, SessionChannel, SessionChannelEvent, SessionClaims, SessionEngine, SessionState } from "@poly-x/core";
+import { AuthClient, Lock, PkceEntry, PkceStore, SessionChannel, SessionChannelEvent, SessionClaims, SessionEngine, SessionState, TenantOption } from "@poly-x/core";
 
 //#region src/provider.d.ts
 interface PolyXProviderProps {
@@ -122,6 +122,95 @@ declare class PopupCancelledError extends Error {
 }
 declare function createLoginController(deps: LoginControllerDeps): LoginController;
 //#endregion
+//#region src/warm-hop.d.ts
+/**
+ * How long to wait for the silent attempt before giving up and showing the form.
+ *
+ * A guess, and labelled as one. The requirement it serves (FR-FALL-2) is that a slow or
+ * dead platform must never leave someone watching a spinner — and for that, *any* bound
+ * beats none. The person this protects is already signed out and gains nothing from
+ * waiting, so the bound is deliberately short. Override it if you have measured yours.
+ */
+declare const WARM_HOP_TIMEOUT_MS = 5000;
+type WarmHopResult = /** Signed in. The session cookie is set; `workspace` names the tenant actually entered. */{
+  status: "signed_in";
+  workspace?: string;
+}
+/**
+ * Signed in — but **not** where you asked.
+ *
+ * The platform only honours a workspace hint when the person has more than one candidate for
+ * that application; with exactly one it seats them there regardless and still answers
+ * "authorized". The session is valid and the person is somewhere they are entitled to be, so
+ * this is not a failure — but it is not what was requested, and being silently put to work in
+ * the wrong tenant is worse than being asked. Decide deliberately: accept it, or send them to
+ * a picker.
+ */
+| {
+  status: "workspace_mismatch";
+  requested: string;
+  workspace: string;
+} /** Several workspaces are available and none was requested — ask, never guess (D14). */ | {
+  status: "select_workspace";
+  workspaces: readonly TenantOption[];
+} /** Recognised, but not entitled to this application or workspace (D15). */ | {
+  status: "no_access";
+} /** Not recognised. The ordinary signed-out path — not an error. */ | {
+  status: "sign_in_required";
+} /** The attempt could not be completed. Treated as signed-out by callers; surfaced for logs. */ | {
+  status: "failed";
+  reason: string;
+};
+/** Has an automatic attempt already run in this tab? */
+declare function warmHopAttempted(): boolean;
+/** Clear the once-per-entry marker. Exported for sign-out, so the next sign-in may try again. */
+declare function resetWarmHop(): void;
+interface WarmHopOptions {
+  /**
+   * Pin a workspace by tenant id, organization code or slug.
+   *
+   * The platform matches this **only within the person's own memberships**, so it can
+   * narrow a choice but never widen access — which is why passing it is safe even when the
+   * value came from something the page was holding.
+   */
+  workspace?: string;
+  /** Override the fall-back bound. See `WARM_HOP_TIMEOUT_MS`. */
+  timeoutMs?: number;
+}
+/**
+ * Run one silent attempt and report what the platform said.
+ *
+ * Never throws: every failure resolves to `failed`, because a caller in the middle of
+ * rendering a sign-in page has no better answer than "show the form" and an exception
+ * there is how a blank screen happens.
+ */
+declare function attemptWarmHop(options?: WarmHopOptions): Promise<WarmHopResult>;
+/**
+ * Move to another workspace (F028 / FR-SWITCH-1…6).
+ *
+ * The same mechanism as the entry attempt, aimed deliberately rather than on arrival — and
+ * deliberately **not** subject to the once-per-entry guard, because this one is a thing the
+ * person asked for.
+ *
+ * Eligibility is decided by the platform at this moment, not from any list held here, so a
+ * workspace revoked since the picker was drawn can never be entered (FR-SWITCH-4). Which
+ * refusal you get depends on what is left, verified against a live platform: still holding
+ * other workspaces gives `select_workspace` listing them; having lost them all gives
+ * `no_access`. Do not treat `no_access` as the only refusal.
+ *
+ * On `signed_in` the session cookie now names the new workspace. The caller decides what to
+ * do next — the SDK does not reload the page or discard anything on their behalf, because it
+ * cannot know what is unsaved on the screen (FR-SWITCH-7).
+ */
+declare function switchWorkspace(workspace: string, options?: WarmHopOptions): Promise<WarmHopResult>;
+/**
+ * The automatic entry attempt: at most once per tab, whatever the caller does (FR-HOP-2).
+ *
+ * Returns `null` when it declines to attempt — already tried this entry — so a caller can
+ * tell "we tried and they must sign in" from "we did not try".
+ */
+declare function attemptWarmHopOnce(options?: WarmHopOptions): Promise<WarmHopResult | null>;
+//#endregion
 //#region src/hooks.d.ts
 /** The raw session state machine value — tearing-free under concurrent React. */
 declare function useSession(): SessionState;
@@ -151,6 +240,37 @@ declare function useAuth(): UseAuth;
 /** Run this on your callback route to complete a sign-in (see `<AuthCallback>`). */
 declare function useAuthCallback(): () => Promise<void>;
 declare function useUser(): SessionClaims | null;
+/** What `useWarmHop` reports while and after it tries. */
+type WarmHopState = {
+  status: "idle";
+} | {
+  status: "attempting";
+} | {
+  status: "settled";
+  result: WarmHopResult;
+};
+/**
+ * Try a silent sign-in once when this component mounts (F027 / FR-HOP-2, FR-FALL-1…3).
+ *
+ * The contract that matters is D11's: **an attempt that fails must be invisible.** Someone who
+ * is genuinely signed out pays the whole cost of this feature and gets nothing from it, so they
+ * must not see a flicker, a spinner that outlives their patience, or — worst — a redirect loop.
+ * Hence: no navigation anywhere in the flow, a hard timeout, and a guard that survives the route
+ * change to the sign-in page (a guard in React state would reset exactly when it is needed).
+ *
+ * ```tsx
+ * const hop = useWarmHop();
+ * if (hop.status !== "settled" ) return null;              // no half-drawn form
+ * if (hop.result.status === "signed_in") return <Redirect/>;
+ * return <SignIn />;                                       // the ordinary path
+ * ```
+ *
+ * Strict Mode's double-mount does not produce two attempts: the marker is written before the
+ * first request goes out.
+ */
+declare function useWarmHop(options?: WarmHopOptions & {
+  enabled?: boolean;
+}): WarmHopState;
 //#endregion
 //#region src/context.d.ts
 interface PolyXContextValue {
@@ -806,4 +926,4 @@ declare const PACKAGE_NAME = "@poly-x/react";
 /** The published version of this package, injected at build time. */
 declare const version: string;
 //#endregion
-export { type Align, AuthCallback, type AuthCallbackMessage, type AuthCallbackProps, type AuthChannel, type AuthEventKind, BroadcastAuthChannel, BroadcastChannelSessionChannel, type BrowserBridge, type CallbackParams, type CaptureOptions, type CapturedGeo, ForgotPassword, type ForgotPasswordLabels, type ForgotPasswordProps, type GeolocationLike, type LiveAuthzHandle, type LiveAuthzOptions, type LoginController, type LoginControllerDeps, PACKAGE_NAME, PolyXContext, type PolyXContextValue, PolyXProvider, type PolyXProviderProps, PopupCancelledError, type PopupHandle, Protected, type ProtectedProps, ResetPassword, type ResetPasswordLabels, type ResetPasswordProps, SessionStoragePkceStore, type Side, type SideOption, SignIn, type SignInLabels, type SignInOptions, type SignInProps, type SignInVariant, type UseAuth, type UseLiveAuthzOptions, UserAvatar, type UserAvatarProps, UserButton, type UserButtonActionProps, type UserButtonLabels, type UserButtonLinkProps, type UserButtonProps, type UserButtonSlotProps, UserProfile, type UserProfileLabels, type UserProfileProps, WebLocksLock, WindowBrowserBridge, capturePreciseLocation, consumeAuthEvent, createLoginController, initialsFrom, resolveSide, startLiveAuthz, useAuth, useAuthCallback, useAuthzChanged, useLiveAuthz, useSession, useUser, version };
+export { type Align, AuthCallback, type AuthCallbackMessage, type AuthCallbackProps, type AuthChannel, type AuthEventKind, BroadcastAuthChannel, BroadcastChannelSessionChannel, type BrowserBridge, type CallbackParams, type CaptureOptions, type CapturedGeo, ForgotPassword, type ForgotPasswordLabels, type ForgotPasswordProps, type GeolocationLike, type LiveAuthzHandle, type LiveAuthzOptions, type LoginController, type LoginControllerDeps, PACKAGE_NAME, PolyXContext, type PolyXContextValue, PolyXProvider, type PolyXProviderProps, PopupCancelledError, type PopupHandle, Protected, type ProtectedProps, ResetPassword, type ResetPasswordLabels, type ResetPasswordProps, SessionStoragePkceStore, type Side, type SideOption, SignIn, type SignInLabels, type SignInOptions, type SignInProps, type SignInVariant, type UseAuth, type UseLiveAuthzOptions, UserAvatar, type UserAvatarProps, UserButton, type UserButtonActionProps, type UserButtonLabels, type UserButtonLinkProps, type UserButtonProps, type UserButtonSlotProps, UserProfile, type UserProfileLabels, type UserProfileProps, WARM_HOP_TIMEOUT_MS, type WarmHopOptions, type WarmHopResult, type WarmHopState, WebLocksLock, WindowBrowserBridge, attemptWarmHop, attemptWarmHopOnce, capturePreciseLocation, consumeAuthEvent, createLoginController, initialsFrom, resetWarmHop, resolveSide, startLiveAuthz, switchWorkspace, useAuth, useAuthCallback, useAuthzChanged, useLiveAuthz, useSession, useUser, useWarmHop, version, warmHopAttempted };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AuthClient, Lock, PkceEntry, PkceStore, SessionChannel, SessionChannelEvent, SessionClaims, SessionEngine, SessionState } from "@poly-x/core";
+import { AuthClient, Lock, PkceEntry, PkceStore, SessionChannel, SessionChannelEvent, SessionClaims, SessionEngine, SessionState, TenantOption } from "@poly-x/core";
 import { ReactNode } from "react";
 
 //#region src/provider.d.ts
@@ -122,6 +122,95 @@ declare class PopupCancelledError extends Error {
 }
 declare function createLoginController(deps: LoginControllerDeps): LoginController;
 //#endregion
+//#region src/warm-hop.d.ts
+/**
+ * How long to wait for the silent attempt before giving up and showing the form.
+ *
+ * A guess, and labelled as one. The requirement it serves (FR-FALL-2) is that a slow or
+ * dead platform must never leave someone watching a spinner — and for that, *any* bound
+ * beats none. The person this protects is already signed out and gains nothing from
+ * waiting, so the bound is deliberately short. Override it if you have measured yours.
+ */
+declare const WARM_HOP_TIMEOUT_MS = 5000;
+type WarmHopResult = /** Signed in. The session cookie is set; `workspace` names the tenant actually entered. */{
+  status: "signed_in";
+  workspace?: string;
+}
+/**
+ * Signed in — but **not** where you asked.
+ *
+ * The platform only honours a workspace hint when the person has more than one candidate for
+ * that application; with exactly one it seats them there regardless and still answers
+ * "authorized". The session is valid and the person is somewhere they are entitled to be, so
+ * this is not a failure — but it is not what was requested, and being silently put to work in
+ * the wrong tenant is worse than being asked. Decide deliberately: accept it, or send them to
+ * a picker.
+ */
+| {
+  status: "workspace_mismatch";
+  requested: string;
+  workspace: string;
+} /** Several workspaces are available and none was requested — ask, never guess (D14). */ | {
+  status: "select_workspace";
+  workspaces: readonly TenantOption[];
+} /** Recognised, but not entitled to this application or workspace (D15). */ | {
+  status: "no_access";
+} /** Not recognised. The ordinary signed-out path — not an error. */ | {
+  status: "sign_in_required";
+} /** The attempt could not be completed. Treated as signed-out by callers; surfaced for logs. */ | {
+  status: "failed";
+  reason: string;
+};
+/** Has an automatic attempt already run in this tab? */
+declare function warmHopAttempted(): boolean;
+/** Clear the once-per-entry marker. Exported for sign-out, so the next sign-in may try again. */
+declare function resetWarmHop(): void;
+interface WarmHopOptions {
+  /**
+   * Pin a workspace by tenant id, organization code or slug.
+   *
+   * The platform matches this **only within the person's own memberships**, so it can
+   * narrow a choice but never widen access — which is why passing it is safe even when the
+   * value came from something the page was holding.
+   */
+  workspace?: string;
+  /** Override the fall-back bound. See `WARM_HOP_TIMEOUT_MS`. */
+  timeoutMs?: number;
+}
+/**
+ * Run one silent attempt and report what the platform said.
+ *
+ * Never throws: every failure resolves to `failed`, because a caller in the middle of
+ * rendering a sign-in page has no better answer than "show the form" and an exception
+ * there is how a blank screen happens.
+ */
+declare function attemptWarmHop(options?: WarmHopOptions): Promise<WarmHopResult>;
+/**
+ * Move to another workspace (F028 / FR-SWITCH-1…6).
+ *
+ * The same mechanism as the entry attempt, aimed deliberately rather than on arrival — and
+ * deliberately **not** subject to the once-per-entry guard, because this one is a thing the
+ * person asked for.
+ *
+ * Eligibility is decided by the platform at this moment, not from any list held here, so a
+ * workspace revoked since the picker was drawn can never be entered (FR-SWITCH-4). Which
+ * refusal you get depends on what is left, verified against a live platform: still holding
+ * other workspaces gives `select_workspace` listing them; having lost them all gives
+ * `no_access`. Do not treat `no_access` as the only refusal.
+ *
+ * On `signed_in` the session cookie now names the new workspace. The caller decides what to
+ * do next — the SDK does not reload the page or discard anything on their behalf, because it
+ * cannot know what is unsaved on the screen (FR-SWITCH-7).
+ */
+declare function switchWorkspace(workspace: string, options?: WarmHopOptions): Promise<WarmHopResult>;
+/**
+ * The automatic entry attempt: at most once per tab, whatever the caller does (FR-HOP-2).
+ *
+ * Returns `null` when it declines to attempt — already tried this entry — so a caller can
+ * tell "we tried and they must sign in" from "we did not try".
+ */
+declare function attemptWarmHopOnce(options?: WarmHopOptions): Promise<WarmHopResult | null>;
+//#endregion
 //#region src/hooks.d.ts
 /** The raw session state machine value — tearing-free under concurrent React. */
 declare function useSession(): SessionState;
@@ -151,6 +240,37 @@ declare function useAuth(): UseAuth;
 /** Run this on your callback route to complete a sign-in (see `<AuthCallback>`). */
 declare function useAuthCallback(): () => Promise<void>;
 declare function useUser(): SessionClaims | null;
+/** What `useWarmHop` reports while and after it tries. */
+type WarmHopState = {
+  status: "idle";
+} | {
+  status: "attempting";
+} | {
+  status: "settled";
+  result: WarmHopResult;
+};
+/**
+ * Try a silent sign-in once when this component mounts (F027 / FR-HOP-2, FR-FALL-1…3).
+ *
+ * The contract that matters is D11's: **an attempt that fails must be invisible.** Someone who
+ * is genuinely signed out pays the whole cost of this feature and gets nothing from it, so they
+ * must not see a flicker, a spinner that outlives their patience, or — worst — a redirect loop.
+ * Hence: no navigation anywhere in the flow, a hard timeout, and a guard that survives the route
+ * change to the sign-in page (a guard in React state would reset exactly when it is needed).
+ *
+ * ```tsx
+ * const hop = useWarmHop();
+ * if (hop.status !== "settled" ) return null;              // no half-drawn form
+ * if (hop.result.status === "signed_in") return <Redirect/>;
+ * return <SignIn />;                                       // the ordinary path
+ * ```
+ *
+ * Strict Mode's double-mount does not produce two attempts: the marker is written before the
+ * first request goes out.
+ */
+declare function useWarmHop(options?: WarmHopOptions & {
+  enabled?: boolean;
+}): WarmHopState;
 //#endregion
 //#region src/context.d.ts
 interface PolyXContextValue {
@@ -806,4 +926,4 @@ declare const PACKAGE_NAME = "@poly-x/react";
 /** The published version of this package, injected at build time. */
 declare const version: string;
 //#endregion
-export { type Align, AuthCallback, type AuthCallbackMessage, type AuthCallbackProps, type AuthChannel, type AuthEventKind, BroadcastAuthChannel, BroadcastChannelSessionChannel, type BrowserBridge, type CallbackParams, type CaptureOptions, type CapturedGeo, ForgotPassword, type ForgotPasswordLabels, type ForgotPasswordProps, type GeolocationLike, type LiveAuthzHandle, type LiveAuthzOptions, type LoginController, type LoginControllerDeps, PACKAGE_NAME, PolyXContext, type PolyXContextValue, PolyXProvider, type PolyXProviderProps, PopupCancelledError, type PopupHandle, Protected, type ProtectedProps, ResetPassword, type ResetPasswordLabels, type ResetPasswordProps, SessionStoragePkceStore, type Side, type SideOption, SignIn, type SignInLabels, type SignInOptions, type SignInProps, type SignInVariant, type UseAuth, type UseLiveAuthzOptions, UserAvatar, type UserAvatarProps, UserButton, type UserButtonActionProps, type UserButtonLabels, type UserButtonLinkProps, type UserButtonProps, type UserButtonSlotProps, UserProfile, type UserProfileLabels, type UserProfileProps, WebLocksLock, WindowBrowserBridge, capturePreciseLocation, consumeAuthEvent, createLoginController, initialsFrom, resolveSide, startLiveAuthz, useAuth, useAuthCallback, useAuthzChanged, useLiveAuthz, useSession, useUser, version };
+export { type Align, AuthCallback, type AuthCallbackMessage, type AuthCallbackProps, type AuthChannel, type AuthEventKind, BroadcastAuthChannel, BroadcastChannelSessionChannel, type BrowserBridge, type CallbackParams, type CaptureOptions, type CapturedGeo, ForgotPassword, type ForgotPasswordLabels, type ForgotPasswordProps, type GeolocationLike, type LiveAuthzHandle, type LiveAuthzOptions, type LoginController, type LoginControllerDeps, PACKAGE_NAME, PolyXContext, type PolyXContextValue, PolyXProvider, type PolyXProviderProps, PopupCancelledError, type PopupHandle, Protected, type ProtectedProps, ResetPassword, type ResetPasswordLabels, type ResetPasswordProps, SessionStoragePkceStore, type Side, type SideOption, SignIn, type SignInLabels, type SignInOptions, type SignInProps, type SignInVariant, type UseAuth, type UseLiveAuthzOptions, UserAvatar, type UserAvatarProps, UserButton, type UserButtonActionProps, type UserButtonLabels, type UserButtonLinkProps, type UserButtonProps, type UserButtonSlotProps, UserProfile, type UserProfileLabels, type UserProfileProps, WARM_HOP_TIMEOUT_MS, type WarmHopOptions, type WarmHopResult, type WarmHopState, WebLocksLock, WindowBrowserBridge, attemptWarmHop, attemptWarmHopOnce, capturePreciseLocation, consumeAuthEvent, createLoginController, initialsFrom, resetWarmHop, resolveSide, startLiveAuthz, switchWorkspace, useAuth, useAuthCallback, useAuthzChanged, useLiveAuthz, useSession, useUser, useWarmHop, version, warmHopAttempted };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 "use client";
-import { AuthClient, FetchTransport, InMemoryLock, InMemoryPkceStore, InMemorySessionChannel, InMemorySessionStore, PROFILE_FIELDS, buildProfileUpdate, conflictField, createSessionEngine, generatePkce, randomState, resolveConfig, validateProfileDraft, validateProfileImage } from "@poly-x/core";
+import { AuthClient, FetchTransport, InMemoryLock, InMemoryPkceStore, InMemorySessionChannel, InMemorySessionStore, PROFILE_FIELDS, buildProfileUpdate, conflictField, createSessionEngine, generatePkce, parseAuthorizeOutcome, randomState, resolveConfig, validateProfileDraft, validateProfileImage } from "@poly-x/core";
 import { Children, Fragment, createContext, isValidElement, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { createPortal } from "react-dom";
@@ -199,7 +199,7 @@ var BroadcastChannelSessionChannel = class {
 //#endregion
 //#region src/seams/session-storage-pkce.ts
 const KEY_PREFIX = "poly-x.pkce.";
-function hasSessionStorage() {
+function hasSessionStorage$1() {
 	try {
 		return typeof sessionStorage !== "undefined";
 	} catch {
@@ -215,7 +215,7 @@ function hasSessionStorage() {
 var SessionStoragePkceStore = class {
 	fallback;
 	constructor() {
-		if (!hasSessionStorage()) this.fallback = new InMemoryPkceStore();
+		if (!hasSessionStorage$1()) this.fallback = new InMemoryPkceStore();
 	}
 	save(entry) {
 		if (this.fallback) return this.fallback.save(entry);
@@ -480,6 +480,198 @@ function getBffSessionStore() {
 	return store;
 }
 //#endregion
+//#region src/warm-hop.ts
+/**
+* Warm hop — the browser half (F027/F028 · FR-HOP-1…6, FR-FALL-1…3, FR-SWITCH-1…7).
+*
+* The probe is made **from here, by the browser**, and that is not a style choice. The
+* platform resolves the ecosystem session from a cookie on its own domain; a server-side
+* request carries no browser cookie, so it would be told "sign-in required" every time and
+* the whole feature would look built while never working. `@poly-x/core` refuses the
+* server-side call outright for that reason.
+*
+* The three steps, and why the credential stays safe throughout:
+*
+*   1. Ask our own BFF to prepare (`/api/polyx/hop`). It mints PKCE and keeps the verifier
+*      in an httpOnly cookie; we receive only a URL.
+*   2. Call that URL with `credentials:"include"` so the browser attaches the ecosystem
+*      cookie. This is the one request that must not come from a server.
+*   3. Hand the resulting `code` back to our BFF (`/api/polyx/hop-complete`), which does the
+*      exchange. The code is worthless to anyone who intercepts it — the PKCE verifier that
+*      redeems it never left the server — so a page holding it briefly is not a custody leak.
+*
+* Nothing here navigates. That matters beyond tidiness: this exact flow produced a redirect
+* loop in a hand-rolled implementation once already, and a fetch cannot loop.
+*/
+const HOP_ENDPOINT = "/api/polyx/hop";
+const HOP_COMPLETE_ENDPOINT = "/api/polyx/hop-complete";
+/**
+* How long to wait for the silent attempt before giving up and showing the form.
+*
+* A guess, and labelled as one. The requirement it serves (FR-FALL-2) is that a slow or
+* dead platform must never leave someone watching a spinner — and for that, *any* bound
+* beats none. The person this protects is already signed out and gains nothing from
+* waiting, so the bound is deliberately short. Override it if you have measured yours.
+*/
+const WARM_HOP_TIMEOUT_MS = 5e3;
+/**
+* Survives navigation on purpose (FR-FALL-3).
+*
+* The fall-back from a failed attempt renders the sign-in page, which in most apps is a
+* route change — so a guard held in React state or a module variable is reset exactly when
+* it is needed. `sessionStorage` is scoped to the tab and cleared when it closes, which is
+* the same lifetime as "this entry".
+*/
+const ATTEMPTED_KEY = "polyx.warmHop.attempted";
+function hasSessionStorage() {
+	try {
+		return typeof sessionStorage !== "undefined";
+	} catch {
+		return false;
+	}
+}
+/** Has an automatic attempt already run in this tab? */
+function warmHopAttempted() {
+	if (!hasSessionStorage()) return false;
+	try {
+		return sessionStorage.getItem(ATTEMPTED_KEY) === "1";
+	} catch {
+		return false;
+	}
+}
+function markWarmHopAttempted() {
+	if (!hasSessionStorage()) return;
+	try {
+		sessionStorage.setItem(ATTEMPTED_KEY, "1");
+	} catch {}
+}
+/** Clear the once-per-entry marker. Exported for sign-out, so the next sign-in may try again. */
+function resetWarmHop() {
+	if (!hasSessionStorage()) return;
+	try {
+		sessionStorage.removeItem(ATTEMPTED_KEY);
+	} catch {}
+}
+async function postJson(url, body, signal) {
+	return fetch(url, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify(body ?? {}),
+		signal,
+		credentials: "same-origin"
+	});
+}
+/**
+* Run one silent attempt and report what the platform said.
+*
+* Never throws: every failure resolves to `failed`, because a caller in the middle of
+* rendering a sign-in page has no better answer than "show the form" and an exception
+* there is how a blank screen happens.
+*/
+async function attemptWarmHop(options = {}) {
+	if (typeof window === "undefined") return {
+		status: "failed",
+		reason: "warm hop attempted outside a browser"
+	};
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 5e3);
+	try {
+		const prepared = await postJson(HOP_ENDPOINT, options.workspace ? { tenantId: options.workspace } : {}, controller.signal);
+		if (!prepared.ok) return {
+			status: "failed",
+			reason: `hop preparation failed (${prepared.status})`
+		};
+		const { authorizeUrl } = await prepared.json();
+		if (!authorizeUrl) return {
+			status: "failed",
+			reason: "hop preparation returned no authorize URL"
+		};
+		const probe = await fetch(authorizeUrl, {
+			method: "GET",
+			credentials: "include",
+			headers: { accept: "application/json" },
+			signal: controller.signal
+		});
+		const body = await probe.json().catch(() => ({}));
+		const outcome = parseAuthorizeOutcome(probe.status, body);
+		switch (outcome.type) {
+			case "login_required": return { status: "sign_in_required" };
+			case "no_access": return { status: "no_access" };
+			case "select_tenant": return {
+				status: "select_workspace",
+				workspaces: outcome.tenants
+			};
+			case "authorized": {
+				const completed = await postJson(HOP_COMPLETE_ENDPOINT, {
+					code: outcome.code,
+					state: outcome.state
+				}, controller.signal);
+				const settled = await completed.json().catch(() => ({}));
+				if (completed.ok) {
+					if (settled.status === "workspace_mismatch" && settled.requested && settled.workspace) return {
+						status: "workspace_mismatch",
+						requested: settled.requested,
+						workspace: settled.workspace
+					};
+					return {
+						status: "signed_in",
+						...settled.workspace ? { workspace: settled.workspace } : {}
+					};
+				}
+				return {
+					status: "failed",
+					reason: settled.status ?? `exchange failed (${completed.status})`
+				};
+			}
+		}
+	} catch (error) {
+		return {
+			status: "failed",
+			reason: error instanceof Error ? error.message : "warm hop failed"
+		};
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+/**
+* Move to another workspace (F028 / FR-SWITCH-1…6).
+*
+* The same mechanism as the entry attempt, aimed deliberately rather than on arrival — and
+* deliberately **not** subject to the once-per-entry guard, because this one is a thing the
+* person asked for.
+*
+* Eligibility is decided by the platform at this moment, not from any list held here, so a
+* workspace revoked since the picker was drawn can never be entered (FR-SWITCH-4). Which
+* refusal you get depends on what is left, verified against a live platform: still holding
+* other workspaces gives `select_workspace` listing them; having lost them all gives
+* `no_access`. Do not treat `no_access` as the only refusal.
+*
+* On `signed_in` the session cookie now names the new workspace. The caller decides what to
+* do next — the SDK does not reload the page or discard anything on their behalf, because it
+* cannot know what is unsaved on the screen (FR-SWITCH-7).
+*/
+async function switchWorkspace(workspace, options = {}) {
+	if (!workspace) return {
+		status: "failed",
+		reason: "no workspace given"
+	};
+	return attemptWarmHop({
+		...options,
+		workspace
+	});
+}
+/**
+* The automatic entry attempt: at most once per tab, whatever the caller does (FR-HOP-2).
+*
+* Returns `null` when it declines to attempt — already tried this entry — so a caller can
+* tell "we tried and they must sign in" from "we did not try".
+*/
+async function attemptWarmHopOnce(options = {}) {
+	if (warmHopAttempted()) return null;
+	markWarmHopAttempted();
+	return attemptWarmHop(options);
+}
+//#endregion
 //#region src/hooks.ts
 function useSessionSource() {
 	const ctx = useContext(PolyXContext);
@@ -549,6 +741,52 @@ function useUser() {
 	const state = useSession();
 	return state.status === "authenticated" || state.status === "refreshing" ? state.session.claims : null;
 }
+/**
+* Try a silent sign-in once when this component mounts (F027 / FR-HOP-2, FR-FALL-1…3).
+*
+* The contract that matters is D11's: **an attempt that fails must be invisible.** Someone who
+* is genuinely signed out pays the whole cost of this feature and gets nothing from it, so they
+* must not see a flicker, a spinner that outlives their patience, or — worst — a redirect loop.
+* Hence: no navigation anywhere in the flow, a hard timeout, and a guard that survives the route
+* change to the sign-in page (a guard in React state would reset exactly when it is needed).
+*
+* ```tsx
+* const hop = useWarmHop();
+* if (hop.status !== "settled" ) return null;              // no half-drawn form
+* if (hop.result.status === "signed_in") return <Redirect/>;
+* return <SignIn />;                                       // the ordinary path
+* ```
+*
+* Strict Mode's double-mount does not produce two attempts: the marker is written before the
+* first request goes out.
+*/
+function useWarmHop(options = {}) {
+	const { enabled = true, workspace, timeoutMs } = options;
+	const [state, setState] = useState({ status: "idle" });
+	useEffect(() => {
+		if (!enabled) return;
+		let live = true;
+		setState({ status: "attempting" });
+		attemptWarmHopOnce({
+			workspace,
+			timeoutMs
+		}).then((result) => {
+			if (!live) return;
+			setState({
+				status: "settled",
+				result: result ?? { status: "sign_in_required" }
+			});
+		});
+		return () => {
+			live = false;
+		};
+	}, [
+		enabled,
+		workspace,
+		timeoutMs
+	]);
+	return state;
+}
 //#endregion
 //#region src/components/protected.tsx
 /** Gate content on authentication state without flashing the wrong branch. */
@@ -2680,6 +2918,6 @@ function useAuthzChanged(callback) {
 */
 const PACKAGE_NAME = "@poly-x/react";
 /** The published version of this package, injected at build time. */
-const version = "0.2.0";
+const version = "0.3.0";
 //#endregion
-export { AuthCallback, BroadcastAuthChannel, BroadcastChannelSessionChannel, ForgotPassword, PACKAGE_NAME, PolyXContext, PolyXProvider, PopupCancelledError, Protected, ResetPassword, SessionStoragePkceStore, SignIn, UserAvatar, UserButton, UserProfile, WebLocksLock, WindowBrowserBridge, capturePreciseLocation, consumeAuthEvent, createLoginController, initialsFrom, resolveSide, startLiveAuthz, useAuth, useAuthCallback, useAuthzChanged, useLiveAuthz, useSession, useUser, version };
+export { AuthCallback, BroadcastAuthChannel, BroadcastChannelSessionChannel, ForgotPassword, PACKAGE_NAME, PolyXContext, PolyXProvider, PopupCancelledError, Protected, ResetPassword, SessionStoragePkceStore, SignIn, UserAvatar, UserButton, UserProfile, WARM_HOP_TIMEOUT_MS, WebLocksLock, WindowBrowserBridge, attemptWarmHop, attemptWarmHopOnce, capturePreciseLocation, consumeAuthEvent, createLoginController, initialsFrom, resetWarmHop, resolveSide, startLiveAuthz, switchWorkspace, useAuth, useAuthCallback, useAuthzChanged, useLiveAuthz, useSession, useUser, useWarmHop, version, warmHopAttempted };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poly-x/react",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "PolyX SDK for React SPAs - provider, hooks, drop-in auth UI",
   "license": "MIT",
   "type": "module",
@@ -27,7 +27,7 @@
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.cts",
   "dependencies": {
-    "@poly-x/core": "0.2.0"
+    "@poly-x/core": "0.3.0"
   },
   "peerDependencies": {
     "react": ">=18",
@@ -56,6 +56,6 @@
   "scripts": {
     "build": "tsdown && node scripts/copy-styles.mjs",
     "test": "vitest run",
-    "lint": "eslint src"
+    "lint": "eslint src && tsc --noEmit -p tsconfig.docs.json"
   }
 }