@gusnips/react 0.9.24 → 0.9.26

package/dist/ui/tabs.d.ts

@@ -9,19 +9,18 @@ type TabListLabel = {
     "aria-labelledby": string;
 };
 export type TabListProps = Omit<Primitive.List.Props, "aria-labelledby"> & TabListLabel & {
-    /** Classes for the scroll wrapper — the element that owns the sideways scroll. */
+    /** Classes for the wrapper that owns the sideways scroll. */
     wrapperClassName?: string;
 };
 /**
  * The rail, and the reason this file exists.
  *
- * It scrolls sideways rather than wrapping, because a second row of tabs pushes the panel
- * below the fold on a phone. But the scroll cannot live on the rail itself: `overflow-x: auto`
- * makes the element a scroll container, a scroll container clips everything its children paint
- * outside the padding box, and a computed `overflow-x` of `auto` forces `overflow-y` from
- * `visible` to `auto` as well. A self-scrolling rail therefore crops the focus ring on all
- * FOUR sides of whichever tab the keyboard is on — top and bottom always, the left of the
- * first tab and the right of the last.
+ * It scrolls sideways rather than wrapping, because a second row of tabs pushes the panel below the
+ * fold on a phone. But the scroll cannot live on the rail itself: `overflow-x: auto` makes the
+ * element a scroll container, a scroll container clips everything its children paint outside the
+ * padding box, and a computed `overflow-x` of `auto` forces `overflow-y` from `visible` to `auto`
+ * as well. A self-scrolling rail therefore crops the focus ring on all FOUR sides of whichever tab
+ * the keyboard is on: top and bottom always, the left of the first tab and the right of the last.
  *
  * So the scroll goes on a wrapper, and the wrapper's padding is the room the ring needs. The
  * number is derived, not inherited: `@gusnips/tokens` draws `outline: 2px solid` at
@@ -35,17 +34,17 @@ export type TabListProps = Omit<Primitive.List.Props, "aria-labelledby"> & TabLi
 export declare function TabList({ label, className, wrapperClassName, children, ...rest }: TabListProps): import("react").JSX.Element;
 export declare function Tab({ className, ...rest }: Primitive.Tab.Props): import("react").JSX.Element;
 /**
- * The travelling marker under the active tab — a SEPARATE part, because the two donors
- * disagreed about whether to have one at all and both were right about their own app. Render
- * it or do not; the rail works either way.
+ * The travelling marker under the active tab. A SEPARATE part, because the two donors disagreed
+ * about whether to have one at all and both were right about their own app. Render it or do not;
+ * the rail works either way.
  *
  * It must be a child of `TabList`: Base UI measures the active tab against the enclosing
  * `[role="tablist"]` and writes `--active-tab-left` / `--active-tab-width` onto this element.
  *
- * `renderBeforeHydration` is on by default because this package's apps are prerendered — with
- * it off, every prerendered page shows the rail with no marker until React arrives. It writes
- * one inline script to do that; under a strict CSP without Base UI's `CspProvider` the script
- * is blocked and the behaviour falls back to exactly what `false` would have done.
+ * `renderBeforeHydration` is on by default because this package's apps are prerendered. With it
+ * off, every prerendered page shows the rail with no marker until React arrives. It writes one
+ * inline script to do that; under a strict CSP without Base UI's `CspProvider` the script is
+ * blocked and the behaviour falls back to exactly what `false` would have done.
  */
 export declare function TabIndicator({ className, ...rest }: Primitive.Indicator.Props): import("react").JSX.Element;
 export {};

package/dist/ui/tabs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tabs.d.ts","sourceRoot":"","sources":["../../src/ui/tabs.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAOxD,eAAO,MAAM,IAAI,gJAAiB,CAAC;AACnC,eAAO,MAAM,QAAQ,iJAAkB,CAAC;AAExC,KAAK,YAAY,GACb;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,SAAS,CAAA;CAAE,GAChD;IAAE,KAAK,CAAC,EAAE,SAAS,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,iBAAiB,CAAC,GACtE,YAAY,GAAG;IACb,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,EAAE,YAAY,+BAa9F;AAYD,wBAAgB,GAAG,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,SAAS,CAAC,GAAG,CAAC,KAAK,+BAE9D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,SAAS,CAAC,SAAS,CAAC,KAAK,+BAY7E"}
+{"version":3,"file":"tabs.d.ts","sourceRoot":"","sources":["../../src/ui/tabs.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAOxD,eAAO,MAAM,IAAI,gJAAiB,CAAC;AACnC,eAAO,MAAM,QAAQ,iJAAkB,CAAC;AAExC,KAAK,YAAY,GACb;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,SAAS,CAAA;CAAE,GAChD;IAAE,KAAK,CAAC,EAAE,SAAS,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,iBAAiB,CAAC,GACtE,YAAY,GAAG;IACb,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEJ;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,EAAE,YAAY,+BAa9F;AAYD,wBAAgB,GAAG,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,SAAS,CAAC,GAAG,CAAC,KAAK,+BAE9D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,SAAS,CAAC,SAAS,CAAC,KAAK,+BAY7E"}

package/dist/ui/tabs.js

@@ -10,13 +10,12 @@ export const TabPanel = Primitive.Panel;
 /**
  * The rail, and the reason this file exists.
  *
- * It scrolls sideways rather than wrapping, because a second row of tabs pushes the panel
- * below the fold on a phone. But the scroll cannot live on the rail itself: `overflow-x: auto`
- * makes the element a scroll container, a scroll container clips everything its children paint
- * outside the padding box, and a computed `overflow-x` of `auto` forces `overflow-y` from
- * `visible` to `auto` as well. A self-scrolling rail therefore crops the focus ring on all
- * FOUR sides of whichever tab the keyboard is on — top and bottom always, the left of the
- * first tab and the right of the last.
+ * It scrolls sideways rather than wrapping, because a second row of tabs pushes the panel below the
+ * fold on a phone. But the scroll cannot live on the rail itself: `overflow-x: auto` makes the
+ * element a scroll container, a scroll container clips everything its children paint outside the
+ * padding box, and a computed `overflow-x` of `auto` forces `overflow-y` from `visible` to `auto`
+ * as well. A self-scrolling rail therefore crops the focus ring on all FOUR sides of whichever tab
+ * the keyboard is on: top and bottom always, the left of the first tab and the right of the last.
  *
  * So the scroll goes on a wrapper, and the wrapper's padding is the room the ring needs. The
  * number is derived, not inherited: `@gusnips/tokens` draws `outline: 2px solid` at
@@ -44,17 +43,17 @@ export function Tab({ className, ...rest }) {
     return _jsx(Primitive.Tab, { ...rest, className: mergeClassName(tabClasses, className) });
 }
 /**
- * The travelling marker under the active tab — a SEPARATE part, because the two donors
- * disagreed about whether to have one at all and both were right about their own app. Render
- * it or do not; the rail works either way.
+ * The travelling marker under the active tab. A SEPARATE part, because the two donors disagreed
+ * about whether to have one at all and both were right about their own app. Render it or do not;
+ * the rail works either way.
  *
  * It must be a child of `TabList`: Base UI measures the active tab against the enclosing
  * `[role="tablist"]` and writes `--active-tab-left` / `--active-tab-width` onto this element.
  *
- * `renderBeforeHydration` is on by default because this package's apps are prerendered — with
- * it off, every prerendered page shows the rail with no marker until React arrives. It writes
- * one inline script to do that; under a strict CSP without Base UI's `CspProvider` the script
- * is blocked and the behaviour falls back to exactly what `false` would have done.
+ * `renderBeforeHydration` is on by default because this package's apps are prerendered. With it
+ * off, every prerendered page shows the rail with no marker until React arrives. It writes one
+ * inline script to do that; under a strict CSP without Base UI's `CspProvider` the script is
+ * blocked and the behaviour falls back to exactly what `false` would have done.
  */
 export function TabIndicator({ className, ...rest }) {
     return (_jsx(Primitive.Indicator, { "aria-hidden": "true", renderBeforeHydration: true, ...rest, className: mergeClassName("absolute bottom-0 left-0 h-0.5 w-[var(--active-tab-width)] translate-x-[var(--active-tab-left)] bg-foreground transition-[translate,width]", className) }));

package/dist/ui/tabs.js.map

@@ -1 +1 @@
-{"version":3,"file":"tabs.js","sourceRoot":"","sources":["../../src/ui/tabs.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,6FAA6F;AAC7F,uFAAuF;AACvF,oCAAoC;AACpC,MAAM,CAAC,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC;AACnC,MAAM,CAAC,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC;AAYxC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAgB;IAC7F,OAAO,CACL,cAAK,SAAS,EAAE,EAAE,CAAC,sCAAsC,EAAE,gBAAgB,CAAC,YAC1E,KAAC,SAAS,CAAC,IAAI,kBACD,KAAK,KACb,IAAI;YACR,sEAAsE;YACtE,SAAS,EAAE,cAAc,CAAC,qBAAqB,EAAE,SAAS,CAAC,YAE1D,QAAQ,GACM,GACb,CACP,CAAC;AACJ,CAAC;AAED,6FAA6F;AAC7F,uFAAuF;AACvF,2DAA2D;AAC3D,EAAE;AACF,4FAA4F;AAC5F,6FAA6F;AAC7F,uBAAuB;AACvB,MAAM,UAAU,GACd,yJAAyJ,CAAC;AAE5J,MAAM,UAAU,GAAG,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAAuB;IAC7D,OAAO,KAAC,SAAS,CAAC,GAAG,OAAK,IAAI,EAAE,SAAS,EAAE,cAAc,CAAC,UAAU,EAAE,SAAS,CAAC,GAAI,CAAC;AACvF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAA6B;IAC5E,OAAO,CACL,KAAC,SAAS,CAAC,SAAS,mBACN,MAAM,EAClB,qBAAqB,WACjB,IAAI,EACR,SAAS,EAAE,cAAc,CACvB,4IAA4I,EAC5I,SAAS,CACV,GACD,CACH,CAAC;AACJ,CAAC"}
+{"version":3,"file":"tabs.js","sourceRoot":"","sources":["../../src/ui/tabs.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,6FAA6F;AAC7F,uFAAuF;AACvF,oCAAoC;AACpC,MAAM,CAAC,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC;AACnC,MAAM,CAAC,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC;AAYxC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAgB;IAC7F,OAAO,CACL,cAAK,SAAS,EAAE,EAAE,CAAC,sCAAsC,EAAE,gBAAgB,CAAC,YAC1E,KAAC,SAAS,CAAC,IAAI,kBACD,KAAK,KACb,IAAI;YACR,sEAAsE;YACtE,SAAS,EAAE,cAAc,CAAC,qBAAqB,EAAE,SAAS,CAAC,YAE1D,QAAQ,GACM,GACb,CACP,CAAC;AACJ,CAAC;AAED,6FAA6F;AAC7F,uFAAuF;AACvF,2DAA2D;AAC3D,EAAE;AACF,4FAA4F;AAC5F,6FAA6F;AAC7F,uBAAuB;AACvB,MAAM,UAAU,GACd,yJAAyJ,CAAC;AAE5J,MAAM,UAAU,GAAG,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAAuB;IAC7D,OAAO,KAAC,SAAS,CAAC,GAAG,OAAK,IAAI,EAAE,SAAS,EAAE,cAAc,CAAC,UAAU,EAAE,SAAS,CAAC,GAAI,CAAC;AACvF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAA6B;IAC5E,OAAO,CACL,KAAC,SAAS,CAAC,SAAS,mBACN,MAAM,EAClB,qBAAqB,WACjB,IAAI,EACR,SAAS,EAAE,cAAc,CACvB,4IAA4I,EAC5I,SAAS,CACV,GACD,CACH,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.9.24",
+  "version": "0.9.26",
   "description": "The headless runtime under a Vite + React SPA: typed fetch client with single-flight refresh, auth store, query defaults, route guards, error boundary, stale-tab recovery, i18n bootstrap.",
   "type": "module",
   "license": "MIT",
@@ -41,6 +41,10 @@
     "./theme": {
       "types": "./dist/theme.d.ts",
       "default": "./dist/theme.js"
+    },
+    "./commands": {
+      "types": "./dist/commands.d.ts",
+      "default": "./dist/commands.js"
     }
   },
   "types": "./dist/index.d.ts",

package/src/api-client.ts

@@ -5,10 +5,10 @@ import { ApiError } from "./api-error.ts";
 /**
  * The app's one door to the API. Nothing else should call `fetch`.
  *
- * Every route answers the same envelope, so unwrapping and error-shaping belong here once
- * rather than in every hook. Three donors built this independently and all three arrived at
- * single-flight token refresh — see {@link SessionAdapter.refresh} for the reason, which is
- * the sharpest thing in this file.
+ * Every route answers the same envelope, so unwrapping and error-shaping belong here once rather
+ * than in every hook. Three donors built this independently and all three arrived at single-flight
+ * token refresh. See {@link SessionAdapter.refresh} for the reason, which is the sharpest thing in
+ * this file.
  *
  * Four things deliberately did NOT come across from the donors, because they belong to a
  * product and not to a client:
@@ -16,7 +16,7 @@ import { ApiError } from "./api-error.ts";
  * - **Toasts.** Whether a failure is spoken aloud is a design decision that differs per surface.
  *   Throw, and let the caller decide.
  * - **In-flight GET deduplication.** react-query already dedups by key, so the client's copy is
- *   redundant — and one donor's version returned a `clone()` of a body already being consumed,
+ *   redundant. One donor's version also returned a `clone()` of a body already being consumed,
  *   which is a race with no symptom until it has one.
  * - **Service-status tracking and impersonation.** One donor's, and firmly its own.
  * - **Analytics correlation headers.** Injected through {@link ApiClientOptions.headers}.
@@ -26,8 +26,8 @@ import { ApiError } from "./api-error.ts";
 export interface RefreshResult {
   token: string | null;
   /**
-   * False when the refresh never got an ANSWER out of the auth server — a dropped connection,
-   * a 5xx, a captive portal.
+   * False when the refresh never got an ANSWER out of the auth server because of a dropped
+   * connection, a 5xx or a captive portal.
    *
    * This flag is invariant 3, and only one of three donors had it. Losing a packet says nothing
    * about whether a session is still good, so a client that collapses "auth said no" into
@@ -39,8 +39,8 @@ export interface RefreshResult {
 }
 
 /**
- * The seam onto whatever holds the session. Supabase in every donor so far, but nothing here
- * knows that — an adapter is four lines and keeps the auth vendor out of this package.
+ * The seam onto whatever holds the session. Supabase in every donor so far, but nothing here knows
+ * that. An adapter is four lines and keeps the auth vendor out of this package.
  */
 export interface SessionAdapter {
   getToken(): Promise<string | null>;
@@ -49,9 +49,9 @@ export interface SessionAdapter {
 }
 
 /**
- * How long anything here waits on a sign-out: the default for
- * {@link ApiClientOptions.signOutTimeoutMs}, and the deadline of `signOutEvenOffline` in
- * `@gusnips/react/supabase`. Shared so the two give up together — a redirect that gave up sooner
+ * How long anything here waits on a sign-out: the default for {@link
+ * ApiClientOptions.signOutTimeoutMs}, and the deadline of `signOutEvenOffline` in
+ * `@gusnips/react/supabase`. Shared so the two give up together. A redirect that gave up sooner
  * would navigate away while the session was still in storage.
  */
 export const SIGN_OUT_TIMEOUT_MS = 3_000;
@@ -70,54 +70,54 @@ export interface ApiClientOptions {
    */
   headers?: () => Record<string, string>;
   /**
-   * The session is gone and cannot be renewed — send them to sign in.
+   * The session is gone and cannot be renewed. Send them to sign in.
    *
    * The client does not know the route, and it deliberately still THROWS after calling this:
    * `location.replace()` does not stop the current frame, so a caller's own `onError` must
    * still run or a half-finished screen keeps rendering against data that will never arrive.
    * The error it throws carries `expected: true`.
    *
-   * Ending the session IN PLACE is equally supported — routing to the sign-in screen without a
-   * reload — and it is the case that keeps this client alive across the next sign-in. The
-   * sign-out latch is keyed on the refused token for exactly that reason; see `refusedToken`.
+   * Routing to the sign-in screen without a reload is equally supported. It is the case that keeps
+   * this client alive across the next sign-in. The sign-out latch is keyed on the refused token for
+   * exactly that reason; see `refusedToken`.
    */
   onSessionDead: () => void;
   /**
    * Every failed response, seen once, just before it is thrown.
    *
-   * For a reaction that belongs to the whole app rather than to one call site. The donor's case
-   * is the sharp one: a mid-session account suspension 403s every authed route except
-   * `GET /auth/me`, so the moment one arrives the app has to refresh `me` and route to the
-   * screen that explains it — otherwise every query on the page fails at once and the shell
-   * half-renders behind an error storm until `me` goes stale on its own.
+   * For a reaction that belongs to the whole app rather than to one call site. The donor's case is
+   * the sharp one: a mid-session account suspension 403s every authed route except `GET /auth/me`,
+   * so the moment one arrives the app has to refresh `me` and route to the screen that explains it.
+   * Otherwise every query on the page fails at once and the shell half-renders behind an error
+   * storm until `me` goes stale on its own.
    *
-   * It cannot live at a call site, because the point is that it fires from whichever call
-   * happened to be first. It went in the donor's client directly, which made the client import
-   * its query cache and its query keys — a cycle that this hook removes.
+   * It cannot live at a call site, because the point is that it fires from whichever call happened
+   * to be first. It went in the donor's client directly, which made the client import its query
+   * cache and its query keys, creating a cycle that this hook removes.
    *
    * Observation only: the error is thrown either way, and throwing from here would replace a
    * real API failure with whatever the listener hit.
    *
    * **The response comes with it, because a refusal's headers are otherwise unreachable.**
-   * `request` throws before the `Response` escapes, so an adopter whose API states something on
-   * the error path had no way to read it at all — one reports what every call cost, refusals
-   * included, which is how "a blocked page costs nothing" becomes a thing a customer can check
-   * rather than a thing we assert. That is the distinction worth keeping: field-error flattening
-   * and a per-call meter callback both stayed in their products, because a product can write
-   * those itself. This one it cannot, at any price, and a capability the kit makes unreachable
-   * is a regression the kit has to undo.
+   * `request` throws before the `Response` escapes, so an adopter whose API states something on the
+   * error path had no way to read it at all. One reports what every call cost, refusals included,
+   * which is how "a blocked page costs nothing" becomes a thing a customer can check rather than a
+   * thing we assert. That is the distinction worth keeping: field-error flattening and a per-call
+   * meter callback both stayed in their products, because a product can write those itself. This
+   * one it cannot, at any price, and a capability the kit makes unreachable is a regression the kit
+   * has to undo.
    *
-   * The BODY has already been read by the time this runs — the envelope was needed to build the
-   * error — so `response.json()` here throws. The headers are what is left, and what this is for.
+   * The BODY has already been read by the time this runs to build the error from the envelope, so
+   * `response.json()` here throws. The headers are what is left, and what this is for.
    */
   onError?: (error: ApiError, response: Response) => void;
   /**
    * Abort a request that has not answered. Default 30s.
    *
-   * Neither donor bounded its authenticated requests at all — both bounded only their keyless
-   * clients — so a stalled connection was a spinner with no end. providerkit learned the same
-   * lesson about streams: a request with no deadline is a bug that only shows up on a bad
-   * network, which is exactly when nobody can reproduce it.
+   * Neither donor bounded its authenticated requests. Both bounded only their keyless clients, so a
+   * stalled connection was a spinner with no end. providerkit learned the same lesson about
+   * streams: a request with no deadline is a bug that only shows up on a bad network, which is
+   * exactly when nobody can reproduce it.
    */
   timeoutMs?: number;
   /** How many times to refresh-and-retry a 401. Default 2. */
@@ -127,9 +127,9 @@ export interface ApiClientOptions {
   /**
    * How long to wait for `signOut()` before redirecting anyway. Default 3s.
    *
-   * A fail-safe, and one donor added it after the failure it prevents: awaiting `signOut()`
-   * covers a rejection but not a HANG, and a hang leaves the tab signed out in name only —
-   * still on the page, every request 401ing, nothing left that could redirect it.
+   * A fail-safe, and one donor added it after the failure it prevents: awaiting `signOut()` covers
+   * a rejection but not a HANG, and a hang leaves the tab signed out in name only: still on the
+   * page, every request 401ing, nothing left that could redirect it.
    */
   signOutTimeoutMs?: number;
   /** Header carrying the server's request id, echoed onto {@link ApiError.requestId}. */
@@ -151,9 +151,9 @@ export interface ApiClient {
   put<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
   patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
   /**
-   * DELETE, discarding whatever comes back. Returns `void` because 204 is the usual answer and
-   * a 204 has NO BODY — `res.json()` on one throws `Unexpected end of JSON input`, which reads
-   * like a malformed response and is really just a success nobody was allowed to parse.
+   * DELETE, discarding whatever comes back. Returns `void` because 204 is the usual answer and a
+   * 204 has NO BODY. `res.json()` on one throws `Unexpected end of JSON input`, which reads like a
+   * malformed response and is really just a success nobody was allowed to parse.
    *
    * Split from {@link ApiClient.delJson} rather than guessing per response, because the guess is
    * the part that hides a bug: a route that was supposed to answer with data and returned
@@ -161,21 +161,21 @@ export interface ApiClient {
    * layers away. The donor that hit this had written exactly these two functions.
    */
   del(path: string, options?: RequestOptions): Promise<void>;
-  /** The DELETE that answers with something worth reading — a queue entry it handed back. */
+  /** The DELETE that answers with something worth reading, such as a queue entry it handed back. */
   delJson<T>(path: string, options?: RequestOptions): Promise<T>;
   /**
-   * The whole envelope rather than just `data`, for a route whose `meta` is half the answer —
-   * a list's `total`, or a metered call's receipt.
+   * The whole envelope rather than just `data`, for a route whose `meta` is half the answer, such
+   * as a list's `total` or a metered call's receipt.
    */
   page<T, M>(path: string, options?: RequestOptions): Promise<ApiSuccess<T, M>>;
   /**
    * The same, off a POST.
    *
-   * Two adopters needed this and both wrote the same workaround: `client.request(…)` followed by
-   * a hand-rolled `res.json()`, stepping around the client's own envelope reader and its one
-   * assertion about the success shape. One of them left the reason sitting in a comment — "the
-   * whole envelope is reachable off a GET and not off a POST, so this one reads the body itself"
-   * — which is this package describing its own gap in somebody else's file.
+   * Two adopters needed this and both wrote the same workaround: `client.request(…)` followed by a
+   * hand-rolled `res.json()`, stepping around the client's own envelope reader and its one
+   * assertion about the success shape. One of them left the reason sitting in a comment: "the whole
+   * envelope is reachable off a GET and not off a POST, so this one reads the body itself". This
+   * package's gap was described in somebody else's file.
    *
    * A metered route takes a body whenever its input is too long or too punctuated to be a path
    * segment (a URL, a search query), and then the receipt has to survive the POST too. When the

package/src/api-error.ts

@@ -3,9 +3,9 @@ import type { ApiErrorBody } from "@gusnips/http";
 /**
  * A refusal, with the whole envelope intact.
  *
- * `code` is what the UI switches on, `messageKey` is what gets localized, and `details` carries
- * the parts that make a refusal actionable — the `resetAt` on a 429, the plan that lifts a 402.
- * Keeping all of it means a caller never has to re-parse a response body that has already been
+ * `code` is what the UI switches on, `messageKey` is what gets localized, and `details` carries the
+ * parts that make a refusal actionable, such as the `resetAt` on a 429 or the plan that lifts a
+ * 402. Keeping all of it means a caller never has to re-parse a response body that has already been
  * read once.
  *
  * A real `class` and not an interface with a factory: one donor used the interface shape, which
@@ -23,17 +23,17 @@ export class ApiError extends Error {
    *
    * Read from the `Retry-After` HEADER, which is where HTTP puts it and where a rate limiter
    * written by anyone puts it. The second migration is why this exists: that API sends
-   * `Retry-After: 60` on every 429 and nothing in its body, so the package's only reader —
-   * which looked in `details.retryAfterSecs`, the first donor's convention — found nothing, and
-   * both the copy and the retry rule were flying blind on the one refusal that states its own
-   * expiry. Two conventions, same fact; `retryAfterSecs` from `@gusnips/http/retry` reads either.
+   * `Retry-After: 60` on every 429 and nothing in its body, so the package's only reader looked in
+   * `details.retryAfterSecs`, the first donor's convention, and found nothing, and both the copy
+   * and the retry rule were flying blind on the one refusal that states its own expiry. Two
+   * conventions, same fact; `retryAfterSecs` from `@gusnips/http/retry` reads either.
    */
   readonly retryAfterSecs: number | undefined;
 
   /**
-   * The client raised this itself to stop a caller while it was already handling the
-   * situation — today, the 401 thrown after a dead session, where the person is already on
-   * their way to the sign-in page.
+   * The client raised this itself to stop a caller while it was already handling the situation.
+   * Today this is the 401 thrown after a dead session, where the person is already on their way to
+   * the sign-in page.
    *
    * It is control flow, not a fault. Exception reporting should skip it, and an error surface
    * should not ask somebody to retry something that is not broken. One donor had this and it is
@@ -65,7 +65,7 @@ export class ApiError extends Error {
 }
 
 /**
- * An aborted request — the caller's own `AbortController`, or a navigation that unmounted the
+ * A request aborted by the caller's own `AbortController` or a navigation that unmounted the
  * component waiting on it.
  *
  * Worth its own predicate because it is the one failure that must NOT be reported, retried or

package/src/auth-email.test.ts

@@ -0,0 +1,145 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { forgetAuthEmail, recallAuthEmail, rememberAuthEmail } from "./auth-email.ts";
+
+const KEY = "frontkit.auth-email";
+const MINUTE = 60 * 1000;
+
+/**
+ * `localStorage` stubbed rather than run under a DOM, the same call as `theme.test.ts`. What
+ * matters is what a browser does at the edges: site data blocked (every method throws), a quota
+ * that refuses new writes while old ones stay readable, and a page with no storage at all.
+ */
+function storage({ blocked = false }: { blocked?: boolean } = {}) {
+  const store = new Map<string, string>();
+  const state = { blocked, full: false };
+  vi.stubGlobal("localStorage", {
+    getItem: (key: string) => {
+      if (state.blocked) throw new Error("site data blocked");
+      return store.get(key) ?? null;
+    },
+    setItem: (key: string, value: string) => {
+      if (state.blocked || state.full) throw new Error("site data blocked");
+      store.set(key, value);
+    },
+    removeItem: (key: string) => {
+      if (state.blocked) throw new Error("site data blocked");
+      store.delete(key);
+    },
+  });
+  return { store, state };
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(new Date("2026-10-08T10:00:00Z"));
+});
+
+afterEach(() => {
+  forgetAuthEmail();
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+describe("remember and recall", () => {
+  it("starts empty", () => {
+    storage();
+    expect(recallAuthEmail()).toBe("");
+  });
+
+  it("hands back what was typed, as typed", () => {
+    storage();
+    rememberAuthEmail(" Ana@Example.com ");
+    expect(recallAuthEmail()).toBe(" Ana@Example.com ");
+  });
+
+  it("writes to localStorage, so a new tab opened from a mail finds it", () => {
+    const { store } = storage();
+    rememberAuthEmail("ana@example.com");
+    expect(JSON.parse(store.get(KEY) ?? "null")).toMatchObject({ email: "ana@example.com" });
+  });
+
+  it("empties when the field is cleared", () => {
+    const { store } = storage();
+    rememberAuthEmail("ana@example.com");
+    rememberAuthEmail("");
+    expect(recallAuthEmail()).toBe("");
+    expect(store.has(KEY)).toBe(false);
+  });
+
+  it("keeps the last good value when handed something longer than an address can be", () => {
+    storage();
+    rememberAuthEmail("ana@example.com");
+    rememberAuthEmail("a".repeat(255));
+    expect(recallAuthEmail()).toBe("ana@example.com");
+  });
+
+  it("forgets on request", () => {
+    const { store } = storage();
+    rememberAuthEmail("ana@example.com");
+    forgetAuthEmail();
+    expect(recallAuthEmail()).toBe("");
+    expect(store.has(KEY)).toBe(false);
+  });
+});
+
+describe("the thirty minutes", () => {
+  it("lets go after thirty minutes of nothing, and deletes what it found", () => {
+    const { store } = storage();
+    rememberAuthEmail("ana@example.com");
+    vi.advanceTimersByTime(30 * MINUTE);
+    expect(recallAuthEmail()).toBe("ana@example.com");
+    vi.advanceTimersByTime(1);
+    expect(recallAuthEmail()).toBe("");
+    expect(store.has(KEY)).toBe(false);
+  });
+
+  it("renews on every keystroke", () => {
+    storage();
+    rememberAuthEmail("ana@example.com");
+    vi.advanceTimersByTime(25 * MINUTE);
+    rememberAuthEmail("ana@example.com.br");
+    vi.advanceTimersByTime(25 * MINUTE);
+    expect(recallAuthEmail()).toBe("ana@example.com.br");
+  });
+});
+
+describe("when the browser will not store it", () => {
+  it("falls back to memory when site data is blocked", () => {
+    storage({ blocked: true });
+    rememberAuthEmail("ana@example.com");
+    expect(recallAuthEmail()).toBe("ana@example.com");
+    forgetAuthEmail();
+    expect(recallAuthEmail()).toBe("");
+  });
+
+  it("falls back to memory when there is no localStorage at all", () => {
+    vi.stubGlobal("localStorage", undefined);
+    rememberAuthEmail("ana@example.com");
+    expect(recallAuthEmail()).toBe("ana@example.com");
+  });
+
+  it("prefers the newer address when a full quota left an older one in storage", () => {
+    const { state } = storage();
+    rememberAuthEmail("old@example.com");
+    state.full = true;
+    vi.advanceTimersByTime(MINUTE);
+    rememberAuthEmail("new@example.com");
+    expect(recallAuthEmail()).toBe("new@example.com");
+  });
+
+  it("prefers what another tab wrote after this tab's memory went stale", () => {
+    const { store } = storage();
+    rememberAuthEmail("old@example.com");
+    vi.advanceTimersByTime(MINUTE);
+    store.set(KEY, JSON.stringify({ email: "new@example.com", at: Date.now() }));
+    expect(recallAuthEmail()).toBe("new@example.com");
+  });
+
+  it("ignores a stored value that is not ours", () => {
+    const { store } = storage();
+    store.set(KEY, "{not json");
+    expect(recallAuthEmail()).toBe("");
+    store.set(KEY, JSON.stringify({ email: 42, at: "now" }));
+    expect(recallAuthEmail()).toBe("");
+  });
+});

package/src/auth-email.ts

@@ -0,0 +1,112 @@
+/**
+ * The email a person has typed during sign-in, kept so the next auth screen opens with it filled.
+ *
+ * Sign-in, "use a code instead", "forgot password" and "create account" are separate screens, and
+ * each one used to start with an empty email field. Someone who typed their address, then chose
+ * another way in, typed it again. The fix is the same everywhere, so it lives here once.
+ *
+ * ```tsx
+ * <input name="email" type="email" defaultValue={recallAuthEmail()}
+ *   onChange={(event) => rememberAuthEmail(event.currentTarget.value)} />
+ * ```
+ *
+ * - **Not in the URL.** A query string rides in `Referer`, in access logs, in history and in every
+ *   analytics tool that records page addresses. An email is personal data and has no business there.
+ * - **`localStorage`, not `sessionStorage`.** An emailed link opens in a new tab, and a new tab
+ *   does not inherit `sessionStorage`. The person who confirms their account from the mail lands
+ *   on sign-in in that new tab, which is the screen that most needs the address.
+ * - **Thirty minutes, sliding.** Long enough to read a code in a mail client and come back; short
+ *   enough that a shared computer forgets. Every keystroke renews it, and a value found expired is
+ *   deleted when it is read, so it does not sit on disk afterwards.
+ * - **Memory behind it.** A browser that blocks site data throws on `localStorage` itself, and
+ *   React Native has none. The value then lasts until the page (or the app) is left, which still
+ *   covers moving between screens.
+ *
+ * Read it once when a screen opens, as a default value. It is not a live store: nothing re-renders
+ * when it changes, and a prerendered page must read it after hydration, never while rendering.
+ * Never put a password, a code or a token here. Call `forgetAuthEmail()` once a session exists, so
+ * the next person at this browser starts empty.
+ */
+
+const KEY = "frontkit.auth-email";
+const TTL_MS = 30 * 60 * 1000;
+/** The longest an address can be (RFC 5321). A longer value is not one, and is not kept. */
+const MAX_LENGTH = 254;
+
+interface Saved {
+  email: string;
+  at: number;
+}
+
+let memory: Saved | null = null;
+
+function isSaved(value: unknown): value is Saved {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "email" in value &&
+    typeof value.email === "string" &&
+    "at" in value &&
+    typeof value.at === "number"
+  );
+}
+
+function readStored(): Saved | null {
+  try {
+    const raw = globalThis.localStorage?.getItem(KEY);
+    if (!raw) return null;
+    const parsed: unknown = JSON.parse(raw);
+    return isSaved(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Storage and memory are written together, so they only differ when one of them missed a write:
+ * storage that is full keeps an older address while memory holds the new one, and a second tab
+ * writes storage while this tab's memory goes stale. The newer of the two is the one the person
+ * typed last.
+ */
+function newest(): Saved | null {
+  const stored = readStored();
+  if (!stored || !memory) return stored ?? memory;
+  return stored.at >= memory.at ? stored : memory;
+}
+
+/** The address typed earlier in this sign-in, or an empty string when there is none. */
+export function recallAuthEmail(): string {
+  const saved = newest();
+  if (!saved) return "";
+  if (Date.now() - saved.at > TTL_MS) {
+    forgetAuthEmail();
+    return "";
+  }
+  return saved.email;
+}
+
+/**
+ * Keep what the person has typed. Call it from the email field's change handler, so every screen
+ * they reach next can open with it. The value is stored as typed: trim it where you submit it.
+ * An empty value forgets.
+ */
+export function rememberAuthEmail(value: string): void {
+  if (value === "") return forgetAuthEmail();
+  if (value.length > MAX_LENGTH) return;
+  memory = { email: value, at: Date.now() };
+  try {
+    globalThis.localStorage?.setItem(KEY, JSON.stringify(memory));
+  } catch {
+    // Blocked or full: the memory copy above carries it until the page is left.
+  }
+}
+
+/** Drop it. Call this once a session exists, so the next person at this browser starts empty. */
+export function forgetAuthEmail(): void {
+  memory = null;
+  try {
+    globalThis.localStorage?.removeItem(KEY);
+  } catch {
+    // Blocked: nothing was stored, so there is nothing to drop.
+  }
+}