@gusnips/react 0.9.24 → 0.9.26

package/src/describe-error.ts

@@ -6,21 +6,21 @@ import { shouldRetry } from "./query.ts";
  * Turning anything thrown into copy a person can act on.
  *
  * The API already answers with a message written for a developer, a stable `messageKey` for the
- * domain refusals, and `details` carrying the parts that make a refusal actionable. This is the
- * one place that decides what the SCREEN says — which is not always the same sentence.
- * "Monthly quota spent, upgrade or buy a pack" is right in a JSON body and wrong under a button
- * that could just say what to do next.
+ * domain refusals, and `details` carrying the parts that make a refusal actionable. This is the one
+ * place that decides what the SCREEN says. It is not always the same sentence. "Monthly quota
+ * spent, upgrade or buy a pack" is right in a JSON body and wrong under a button that could just
+ * say what to do next.
  *
  * `cause` is what happened. `fix` is what to do about it. **A surface that shows only the first
- * half is the dead end this exists to prevent** — which is why the type has two fields and not
- * one, and why `fix` being absent should be a deliberate choice at each call site rather than
- * the default nobody noticed.
+ * half is the dead end this exists to prevent**. That is why the type has two fields and not one,
+ * and why `fix` being absent should be a deliberate choice at each call site rather than the
+ * default nobody noticed.
  *
- * `fix`, and not the `hint` this returned until 0.6.0. `ErrorStateProps` — the contract this same
- * package ships for the component that renders this — has always called it `fix`, so every
- * adopter wrote `fix={hint}` at every error surface: a rename adapter, which is the shape of an
- * API we got wrong. It also clears a collision, because in at least one adopter a form field's
- * `hint` is the requirement text under the input, which is a different thing entirely.
+ * `fix`, and not the `hint` this returned until 0.6.0. `ErrorStateProps`, the contract this same
+ * package ships for the component that renders this, has always called it `fix`, so every adopter
+ * wrote `fix={hint}` at every error surface: a rename adapter, which is the shape of an API we got
+ * wrong. It also clears a collision, because in at least one adopter a form field's `hint` is the
+ * requirement text under the input, which is a different thing entirely.
  *
  * The per-code switch stays in the product: two donors' switches shared their SHAPE and almost
  * no arms, because the arms are that API's vocabulary. What ships is the scaffolding around it,
@@ -30,11 +30,11 @@ import { shouldRetry } from "./query.ts";
 /**
  * Which control to offer beside the words.
  *
- * The fourth adopter had this and the package did not, which left every adopter re-deriving
- * "can a second attempt fix this" from its own switch — beside a `shouldRetry` already deciding
- * exactly that for react-query. Two answers to one question drift, and the drift is visible: a
- * screen offering "try again" for a refusal the query layer refuses to retry, so the button does
- * nothing and the reader presses it twice.
+ * The fourth adopter had this and the package did not, which left every adopter re-deriving "can a
+ * second attempt fix this" from its own switch, beside a `shouldRetry` already deciding exactly
+ * that for react-query. Two answers to one question drift, and the drift is visible: a screen
+ * offering "try again" for a refusal the query layer refuses to retry, so the button does nothing
+ * and the reader presses it twice.
  *
  * So this is DERIVED from `shouldRetry`, not switched on separately. One rule, two consumers.
  */
@@ -54,7 +54,7 @@ export interface ErrorCopy {
   cause: string;
   /** What to do about it. Its absence should be a decision, not an oversight. */
   fix?: string;
-  /** Override the derived kind — a 429 whose code means a spent quota is `"none"`, not `"wait"`. */
+  /** Override the derived kind. A 429 whose code means a spent quota is `"none"`, not `"wait"`. */
   recover?: RecoveryKind;
   /** Override the request id. Rarely wanted; the envelope's is used by default. */
   reference?: string;
@@ -66,14 +66,14 @@ export interface DescribedError extends ErrorCopy {
 }
 
 /**
- * The subset of i18next's `t` this module needs — typed here so `i18next` stays optional.
+ * The subset of i18next's `t` this module needs, typed here so `i18next` stays optional.
  *
- * `Key` is a parameter and not plain `string` for a reason the first migration found. Every app
- * on this stack declares `CustomTypeOptions.resources`, which types `t` to accept ONLY the keys
- * its catalog has — so a `t` is not assignable to anything asking for `(key: string) => string`,
- * and the adopter is left with a cast. Naming the keys instead turns that around: each function
- * below asks for exactly the keys it looks up, a typed `t` accepts a superset of them and goes
- * in directly, and a catalog missing one is a compile error rather than a raw key on screen.
+ * `Key` is a parameter and not plain `string` for a reason the first migration found. Every app on
+ * this stack declares `CustomTypeOptions.resources`, which types `t` to accept ONLY the keys its
+ * catalog has, so a `t` is not assignable to anything asking for `(key: string) => string`, and the
+ * adopter is left with a cast. Naming the keys instead turns that around: each function below asks
+ * for exactly the keys it looks up, a typed `t` accepts a superset of them and goes in directly,
+ * and a catalog missing one is a compile error rather than a raw key on screen.
  */
 export type Translate<Key extends string = string> = (
   key: Key,
@@ -87,8 +87,8 @@ type WaitName = "waitSeconds" | "waitMinutes" | "waitHours";
  * Every name {@link createErrorDescriber} looks up itself. Your catalog carries all of them.
  *
  * The three wait names are deliberately NOT here, which is the other half of 0.6.0. This module
- * used to humanize a stated wait itself, so `waitSeconds`/`waitMinutes`/`waitHours` — each with
- * an ICU plural — landed in the key union of every adopter's `t` whether or not a wait was ever
+ * used to humanize a stated wait itself, so `waitSeconds`/`waitMinutes`/`waitHours`, each with an
+ * ICU plural, landed in the key union of every adopter's `t` whether or not a wait was ever
  * rendered. An app that formats waits with `Intl.RelativeTimeFormat` needs none of them and was
  * left adding six entries per language to satisfy a compiler. `formatWait` owns that now.
  */
@@ -99,11 +99,11 @@ type CopyName = "network" | "networkHint" | "unexpected" | "retrySoon";
  *
  * i18next keeps `seatLimitReached_one` and `seatLimitReached_other`; the server sends
  * `serverErrors.seatLimitReached`, because that is the key a person resolves with a `count`. So
- * `Object.keys` on a catalog does NOT contain the name the server actually sends, and a gate
- * built from it alone rejects a sentence the app is carrying — falling back to the server's
- * English for the one refusal that had a written answer. Measured in the seventh migration: two
- * of that API's 112 keys, both of them plan limits, both of them the exact screen where a
- * specific sentence earns its keep.
+ * `Object.keys` on a catalog does NOT contain the name the server actually sends, and a gate built
+ * from it alone rejects a sentence the app is carrying, falling back to the server's English for
+ * the one refusal that had a written answer. Measured in the seventh migration: two of that API's
+ * 112 keys, both of them plan limits, both of them the exact screen where a specific sentence earns
+ * its keep.
  */
 type PluralSuffix = "zero" | "one" | "two" | "few" | "many" | "other";
 type PluralBase<N extends string> = N extends `${infer Base}_${PluralSuffix}` ? Base : N;
@@ -135,17 +135,17 @@ type _TypedCatalogNeedsNoCast = Satisfied<
 >;
 
 /**
- * "in 4 minutes" / "in 2 hours" — a wait nobody has to convert from seconds.
+ * Format a wait as "in 4 minutes" or "in 2 hours", without making the reader convert seconds.
  *
  * The thresholds are deliberately not round: 90 seconds rather than 60, so "in 75 seconds" does
  * not become the less precise "in 1 minute", and 90 minutes rather than 60 for the same reason
  * one rung up. Needs `waitSeconds` / `waitMinutes` / `waitHours` under `prefix`, each with a
  * `count` plural.
  *
- * This is what you pass as `formatWait` when your catalog carries those three:
- * `formatWait: (secs) => humanizeWait(t, secs, "errors.")`. An app that formats a wait with
- * `Intl.RelativeTimeFormat` passes its own one-liner instead and needs no wait keys at all —
- * which also gets it correct plurals in languages with more than two forms, for free.
+ * This is what you pass as `formatWait` when your catalog carries those three: `formatWait: (secs)
+ * => humanizeWait(t, secs, "errors.")`. An app that formats a wait with `Intl.RelativeTimeFormat`
+ * passes its own one-liner instead and needs no wait keys at all. It also gets correct plurals in
+ * languages with more than two forms, for free.
  */
 export function humanizeWait<Prefix extends string>(
   t: Translate<`${Prefix}${WaitName}`>,
@@ -181,17 +181,17 @@ interface DescriberRules {
    * How a stated wait becomes words, for the `wait` an arm reads off its context.
    *
    * Required rather than defaulted, because there is no answer that is right for everyone and a
-   * default hid the cost: {@link humanizeWait} reads three ICU plural keys out of your catalog,
-   * and an app that already formats relative time with `Intl` would have had to add them to
-   * compile. Say which you want — `(secs) => humanizeWait(t, secs, "errors.")`, or your own
-   * `(secs) => formatIn(secs, locale)` — and the catalog you need is the one you can see.
+   * default hid the cost: {@link humanizeWait} reads three ICU plural keys out of your catalog, and
+   * an app that already formats relative time with `Intl` would have had to add them to compile.
+   * Pass `(secs) => humanizeWait(t, secs, "errors.")` or your own `(secs) => formatIn(secs,
+   * locale)`. The choice makes the catalog you need visible.
    */
   formatWait: (secs: number) => string;
   /**
    * Per-code copy. Everything not listed falls through to the default arm.
    *
-   * The arms look up the app's own keys, so they close over the app's `t` rather than being
-   * handed one — this module has no names for that copy and no business typing it.
+   * The arms look up the app's own keys, so they close over the app's `t` rather than being handed
+   * one. This module has no names for that copy and no business typing it.
    *
    * Annotate your object `Partial<Record<YourErrorCode, ErrorArm>>` where you write it, and a
    * code that does not exist is a compile error at the arm rather than a branch that never runs.
@@ -201,21 +201,21 @@ interface DescriberRules {
    * What to say when nothing in `codes` matches: a code this build has no arm for, or an answer
    * with no envelope at all.
    *
-   * The built-in arm hands the reader the server's own `message`, and for one API in the fleet
-   * that is right — its message IS the sentence a person should read. For another it is exactly
+   * The built-in arm hands the reader the server's own `message`, and for one API in the fleet that
+   * is right, because its message IS the sentence a person should read. For another it is exactly
    * wrong: that repo's own i18n rules say `message` is "the English fallback for logs", and it
    * ships three languages, so the built-in would put developer English in front of a reader who
-   * does not speak it. One default cannot be right for both, and the one baked in here was
-   * simply the first adopter's convention, mistaken for a fact.
+   * does not speak it. One default cannot be right for both, and the one baked in here was simply
+   * the first adopter's convention, mistaken for a fact.
    *
    * An arm here is also handed the stated wait, which the built-in spends on nothing: a refusal
    * with no arm of its own could state its expiry and have that go unsaid.
    */
   fallback?: ErrorArm;
   /**
-   * The codes that mean "this limit does not clear by waiting" — **the same list you hand
-   * `queryDefaults`**, because it answers the same question and a second copy is a second
-   * chance to disagree with the retry rule. Declare it once in the app and pass it twice.
+   * The codes that mean "this limit does not clear by waiting". Pass **the same list to
+   * `queryDefaults`**, because it answers the same question and a second copy is a second chance to
+   * disagree with the retry rule. Declare it once in the app and pass it twice.
    */
   durableLimitCodes?: readonly string[];
   /** Longest stated wait still worth a retry rather than a countdown. Matches `queryDefaults`. */
@@ -230,10 +230,10 @@ export interface ErrorDescriberOptions<
   /**
    * Checked against the keys, never used to find them: the three type parameters come from
    * `copyPrefix`, `messageKeyPrefix` and `knownMessageKeys`. With `t` as a source too, the call
-   * every adopter writes — an inline `(key, params) => i18n.t(key, params)` beside an inline arm —
+   * every adopter writes, an inline `(key, params) => i18n.t(key, params)` beside an inline arm,
    * failed overload resolution (TS2769, measured on TypeScript 5.9.3) once the one-language
-   * overload existed, although this signature alone accepted it. A typed `t` missing a key is
-   * still refused.
+   * overload existed, although this signature alone accepted it. A typed `t` missing a key is still
+   * refused.
    */
   t: Translate<
     NoInfer<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName | PluralBase<ServerName>}`>
@@ -242,13 +242,13 @@ export interface ErrorDescriberOptions<
   copyPrefix: Prefix;
   /**
    * The server's own catalog namespace, e.g. `"serverErrors."`. A `messageKey` outside it is
-   * ignored — the server names a sentence, it does not get to name any key in the app.
+   * ignored. The server names a sentence, it does not get to name any key in the app.
    *
-   * The `code` is read under this prefix too, for an API that has no `messageKey` field and
-   * lets the code name the sentence — one repo in the fleet has 98 of those, `errors.NOT_FOUND`
-   * and its siblings, against another repo's `messageKey`. Both are the same claim ("the server
-   * named a sentence this app carries"), both pass the same gate below, and an app that uses
-   * neither is unaffected because nothing matches.
+   * The `code` is read under this prefix too, for an API that has no `messageKey` field and lets
+   * the code name the sentence. One repo in the fleet has 98 of those, `errors.NOT_FOUND` and its
+   * siblings, against another repo's `messageKey`. Both are the same claim ("the server named a
+   * sentence this app carries"), both pass the same gate below, and an app that uses neither is
+   * unaffected because nothing matches.
    */
   messageKeyPrefix: ServerPrefix;
   /**
@@ -256,13 +256,13 @@ export interface ErrorDescriberOptions<
    * catalog. Passing the catalog itself is both the membership test and the proof the compiler
    * wants: a name that is in it IS a key, so the lookup below needs no cast.
    *
-   * It is required because leaving it out is not a smaller version of this — it is the bug the
-   * option exists to prevent. i18next answers a key it does not have with the key itself, so a
+   * It is required because leaving it out reintroduces the bug the option exists to prevent rather
+   * than making this smaller. i18next answers a key it does not have with the key itself, so a
    * deploy landing ahead of the bundle a tab is still running would render `serverErrors.foo` at
    * somebody. A name that is absent falls back to the server's English `message` instead.
    *
-   * Hand it over as it is. A plural sits in the catalog under suffixed names while the server
-   * names the base, so the base is admitted too — see {@link PluralBase}.
+   * Hand it over as it is. A plural sits in the catalog under suffixed names while the server names
+   * the base, so the base is admitted too. See {@link PluralBase}.
    */
   knownMessageKeys: Record<ServerName, unknown>;
   /**
@@ -270,13 +270,13 @@ export interface ErrorDescriberOptions<
    *
    * The envelope carries what the SERVER knows, which is not always a word anyone should read: a
    * role id (`admin`), an action verb (`approve_content`). The sentence needs whatever the app's
-   * own screens call those things, and the substitution happens here — inside the one lookup that
-   * reads `params` — so there is nowhere else an adopter could intervene. Without this seam the
-   * choice is to ship the raw id into `{{role}}`, or to stop using the server's sentence at all
-   * and re-resolve every key by hand, which is how i18n ended up inside a transport once already.
+   * own screens call those things, and the substitution happens here, inside the one lookup that
+   * reads `params`. There is nowhere else an adopter could intervene. Without this seam the choice
+   * is to ship the raw id into `{{role}}`, or to stop using the server's sentence at all and
+   * re-resolve every key by hand, which is how i18n ended up inside a transport once already.
    *
    * Optional, and identity by default: an API whose params are already words passes nothing. It
-   * deliberately takes only the params — an arm that needs the error has `ctx` for that.
+   * deliberately takes only the params. An arm that needs the error has `ctx` for that.
    */
   localizeParams?: (
     params: Record<string, string | number> | undefined,

package/src/error-boundary.tsx

@@ -3,18 +3,18 @@ import { Component, type ErrorInfo, type ReactNode } from "react";
 /**
  * The last stop before a white screen.
  *
- * React unmounts the whole tree when a render throws, and an app with no boundary anywhere
- * answers that with a blank page: no words, no navigation, no reload — the most complete dead
- * end a product can produce, and the one the never-dead-end rule cannot reach, because by then
- * there is no component left to render a state from.
+ * React unmounts the whole tree when a render throws, and an app with no boundary anywhere answers
+ * that with a blank page: no words, no navigation, no reload. That is the most complete dead end a
+ * product can produce, and the one the never-dead-end rule cannot reach, because by then there is
+ * no component left to render a state from.
  *
  * It is deliberately dumb. No retry loop, no error reporting, no reset on a timer: it catches,
  * it hands the error to a `fallback` the app draws in its own words, and it offers `reset`.
  * Every donor that baked its own UI in here had to keep a second copy for its second surface;
  * a render prop has no such problem, and the brand stays in the product where it belongs.
  *
- * A class, because `getDerivedStateFromError` has no hook equivalent — this is the one thing in
- * the kit React still has no other way to express.
+ * A class, because `getDerivedStateFromError` has no hook equivalent. This is the one thing in the
+ * kit React still has no other way to express.
  */
 
 export interface ErrorBoundaryFallbackProps {
@@ -22,9 +22,9 @@ export interface ErrorBoundaryFallbackProps {
   /** Put the children back. */
   reset: () => void;
   /**
-   * True when the throw was a failed lazy-chunk import — a deploy landed while this tab was
-   * open, so the fix is a reload and NOT a retry (a rejected dynamic import rethrows on
-   * re-render forever). Draw the "updating" screen, not the crash screen.
+   * True when the throw was a failed lazy-chunk import because a deploy landed while this tab was
+   * open, so the fix is a reload and NOT a retry (a rejected dynamic import rethrows on re-render
+   * forever). Draw the "updating" screen, not the crash screen.
    */
   isChunkError: boolean;
 }
@@ -33,9 +33,9 @@ export interface ErrorBoundaryProps {
   /** Drawn instead of the children once something has thrown. */
   fallback: (props: ErrorBoundaryFallbackProps) => ReactNode;
   /**
-   * Changing this value clears the error and remounts the children — pass the route, so
-   * navigating away from a screen that broke actually leaves it rather than carrying its
-   * wreckage to every page after it.
+   * Changing this value clears the error and remounts the children. Pass the route, so navigating
+   * away from a screen that broke actually leaves it rather than carrying its wreckage to every
+   * page after it.
    */
   resetKey?: string;
   /** Called once per catch. Report to whatever the app reports to. */

package/src/guards.tsx

@@ -6,9 +6,9 @@ import { returnPathFromLocation, safeInternalPath } from "./internal-path.ts";
 /**
  * Route guards.
  *
- * Two donors wrote these four, gave two of them the same names, and explained them in nearly
- * the same words. What differed was one line — and that line is invariant 4, so it is the
- * reason this file exists rather than being copied a ninth time.
+ * Two donors wrote these four, gave two of them the same names, and explained them in nearly the
+ * same words. What differed was one line. That line is invariant 4, so it is the reason this file
+ * exists rather than being copied a ninth time.
  *
  * These are factories because the destinations are the app's: `paths.signIn` is not something a
  * package can know, and one donor hardcoded `/login` in four places for exactly that reason.
@@ -27,18 +27,18 @@ export interface SessionState {
 /**
  * The answer to a "who is this?" query, in the three states it actually has.
  *
- * This shape is invariant 4. A guard reading `!me?.isStaff` collapses "pending", "failed" and
- * "no" into one branch — so an operator arriving while `/auth/me` is 500ing is told the page
- * does not exist. Wrong cause, no retry, and no request id to quote to support. One donor hit
- * that and fixed it; the other still has the collapsed version.
+ * This shape is invariant 4. A guard reading `!me?.isStaff` collapses "pending", "failed" and "no"
+ * into one branch, so an operator arriving while `/auth/me` is 500ing is told the page does not
+ * exist. Wrong cause, no retry, and no request id to quote to support. One donor hit that and fixed
+ * it; the other still has the collapsed version.
  *
  * `"pending"` and not `"loading"` for one measured reason: it is react-query's own word for this
  * state since v5, and with the words matching a `UseQueryResult<TMe>` satisfies this type
- * STRUCTURALLY — `createRequireProfile(useMe, …)` takes the hook directly, no adapter. With
- * `"loading"` it does not typecheck and every adopter hand-writes the same six-line mapping;
- * eight of the twelve repos this serves are on react-query, and the first migration wrote that
- * mapping before anyone noticed. Nothing here imports react-query at runtime — the type stays
- * structural, so an app on SWR or a plain `useState` still answers it in three lines.
+ * STRUCTURALLY: `createRequireProfile(useMe, …)` takes the hook directly, no adapter. With
+ * `"loading"` it does not typecheck and every adopter hand-writes the same six-line mapping; eight
+ * of the twelve repos this serves are on react-query, and the first migration wrote that mapping
+ * before anyone noticed. Nothing here imports react-query at runtime. The type stays structural, so
+ * an app on SWR or a plain `useState` still answers it in three lines.
  */
 export type MeQuery<TMe> =
   { status: "pending" } | { status: "error"; error: unknown } | { status: "success"; data: TMe };
@@ -68,8 +68,8 @@ function signInUrl(signInPath: string, returnTo: string): string {
 }
 
 /**
- * Signed in, or off to sign in — remembering where they were headed, so the redirect afterwards
- * lands on the page they actually wanted rather than the home screen.
+ * Require sign-in and remember where they were headed, so the redirect afterwards lands on the page
+ * they actually wanted rather than the home screen.
  */
 export function createRequireAuth(
   useSession: () => SessionState,
@@ -114,7 +114,7 @@ export function createRequireAnonymous(
 }
 
 /**
- * A gate on something the profile says — suspended, staff, on a given plan.
+ * A gate on a profile field, such as whether the person is suspended, staff or on a given plan.
  *
  * `allow` gets the profile and answers yes or no. `onDenied` draws the refusal; `onError` draws
  * the failure, and they are SEPARATE arguments on purpose. That separation is the whole point

package/src/hydrate.ts

@@ -1,18 +1,17 @@
 /**
  * The browser half of prerendering: deciding whether to hydrate or to mount fresh.
  *
- * Three separate repos invented all of this independently — same constant name, same string
- * value, same decision, and near-identical explaining comments. That is not a coincidence worth
- * deduping; it is one lesson learned three times, and it belongs somewhere it can be learned
- * once.
+ * Three separate repos invented all of this independently, with the same constant name, string
+ * value and decision, and near-identical explaining comments. That is not a coincidence worth
+ * deduping; it is one lesson learned three times, and it belongs somewhere it can be learned once.
  *
  * The constants themselves live in `prerender-contract.ts`, which imports nothing, because the
  * BUILD needs them too and must not pull `react-dom/client` into a Node process to get a string.
  *
  * This module sits behind `@gusnips/react/hydrate` rather than in the barrel for the same reason
- * one rung further out: it is the package's ONLY `react-dom` import, and a React Native app has
- * no react-dom to give. Leaving it in the barrel made `react-dom` a required peer and shut the
- * whole package out of every phone — for one function a phone would never call.
+ * one rung further out: it is the package's ONLY `react-dom` import, and a React Native app has no
+ * react-dom to give. Leaving it in the barrel made `react-dom` a required peer and shut the whole
+ * package out of every phone for one function a phone would never call.
  */
 import type { ReactNode } from "react";
 import { createRoot, hydrateRoot } from "react-dom/client";
@@ -24,16 +23,16 @@ export { PRERENDERED_ROUTE_ATTR, SHELL_ROUTE } from "./prerender-contract.ts";
  * Hydrate the render this file IS, and mount fresh over anything else.
  *
  * "Does the root have children" is the wrong question, and getting it wrong is silent. A static
- * host answers every address it does not publish with the nearest `404.html` — and that file has
- * the not-found page rendered INTO it — so an address served from a shell arrives at a full root
- * holding somebody else's markup. Hydrating that is React reconciling two different pages: it
- * recovers by throwing the whole tree away and says so in the console, which is a page that
- * works and a bug nobody sees. The file names the route it is a render of, so we can simply ask.
+ * host answers every address it does not publish with the nearest `404.html`, which has the
+ * not-found page rendered INTO it. An address served from a shell arrives at a full root holding
+ * somebody else's markup. Hydrating that is React reconciling two different pages: it recovers by
+ * throwing the whole tree away and says so in the console, which is a page that works and a bug
+ * nobody sees. The file names the route it is a render of, so we can simply ask.
  *
- * `route` is passed in rather than read from `window.location` on purpose. A localized app
- * serves `/pt/pricing` from a file rendered for `/pricing`, with the locale carried in the
- * router's `basename` — so the address and the route are different strings, and only the caller
- * knows which one the build wrote.
+ * `route` is passed in rather than read from `window.location` on purpose. A localized app serves
+ * `/pt/pricing` from a file rendered for `/pricing`, with the locale carried in the router's
+ * `basename`, so the address and the route are different strings, and only the caller knows which
+ * one the build wrote.
  *
  * **A trailing slash is not a different page.** The router renders `/precos/` and `/precos` alike,
  * and which one is in the address bar is the host's call: a host serving `precos/index.html`

package/src/i18n.ts

@@ -8,8 +8,7 @@
  * ```
  *
  * Keeping the options here is what stops a console, a storefront and a docs site in the same
- * product from drifting apart on the details below — each of which is a bug somebody already
- * shipped.
+ * product from drifting apart on the details below. Each is a bug somebody already shipped.
  */
 
 export interface I18nInitOptions {
@@ -28,10 +27,10 @@ export interface I18nInitOptions {
   /**
    * The query parameter that hands a language ACROSS an origin, e.g. `"lang"`.
    *
-   * When set it is detected FIRST, ahead of storage and the browser — it is the only one of the
+   * When set it is detected FIRST, ahead of storage and the browser. It is the only one of the
    * three that somebody chose on purpose and just now. A reader who picked Português on the
-   * storefront and followed a link into the app means it more than their laptop's locale does.
-   * It is cached on arrival, so it decides once and no URL inside the app has to carry it.
+   * storefront and followed a link into the app means it more than their laptop's locale does. It
+   * is cached on arrival, so it decides once and no URL inside the app has to carry it.
    *
    * Only one donor had this. The other has the same split-origin layout and the same problem.
    */
@@ -39,15 +38,15 @@ export interface I18nInitOptions {
   /**
    * Who WRITES {@link storageKey}. The detector, by default.
    *
-   * Pass `"app"` when your own language control writes it. That is not a preference — it is what
-   * a "follow the browser" option costs. Going back to following the browser means clearing the
-   * key and calling `changeLanguage(undefined)`, which re-runs detection; a detector that caches
-   * then writes the language it just detected straight back into the key it was told to clear.
-   * The choice re-pins itself and nothing can reach that state again.
+   * Pass `"app"` when your own language control writes it. A "follow the browser" option needs
+   * this. Going back to following the browser means clearing the key and calling
+   * `changeLanguage(undefined)`, which re-runs detection; a detector that caches then writes the
+   * language it just detected straight back into the key it was told to clear. The choice re-pins
+   * itself and nothing can reach that state again.
    *
    * Three repos on this stack, three answers: one lets the detector write, one writes it from its
-   * own control, and one does both — harmless there only because it offers no "follow the
-   * browser" state. So the rule, rather than the default: one writer per key.
+   * own control, and one does both. Doing both is harmless there only because it offers no "follow
+   * the browser" state. So the rule, rather than the default: one writer per key.
    */
   storageWriter?: "detector" | "app";
 }
@@ -106,13 +105,13 @@ export function i18nInitOptions({
  * i18next ever sees it.
  *
  * Done here rather than through interpolation because i18next v26 has no global interpolation
- * defaults, and these strings are often resolved by dynamic key — so a wrapping `t()` would not
+ * defaults, and these strings are often resolved by dynamic key, so a wrapping `t()` would not
  * reach them. The point is that a rename or a domain move is ONE edit in the brand constants
  * instead of a sweep across every locale file.
  *
- * Returns a fresh tree; the input is untouched. The placeholder names come from `vars`, so
- * adding one needs no change here — two donors hardcoded their own list in the regex and both
- * had to remember to update it.
+ * Returns a fresh tree; the input is untouched. The placeholder names come from `vars`, so adding
+ * one needs no change here. Two donors hardcoded their own list in the regex and both had to
+ * remember to update it.
  */
 export function applyBrandVars<T>(resources: T, vars: Record<string, string>): T {
   const names = Object.keys(vars);

package/src/index.ts

@@ -34,6 +34,8 @@ export { cn } from "./cn.ts";
 export { copyText, useCopy, type CopyOptions, type CopyState } from "./copy.ts";
 export { returnPathFromLocation, safeInternalPath, type PathParts } from "./internal-path.ts";
 
+export { forgetAuthEmail, recallAuthEmail, rememberAuthEmail } from "./auth-email.ts";
+
 export { ApiError, isAbortError } from "./api-error.ts";
 export { retryAfterSecs } from "@gusnips/http/retry";
 export {

package/src/internal-path.ts

@@ -12,9 +12,9 @@ function containsControl(value: string): boolean {
  * A route the browser can follow without leaving the current origin.
  *
  * Return targets cross a trust boundary: query strings, history state and storage are all writable
- * by somebody outside the app. `startsWith("/")` is not enough — URL parsers read both `//host`
- * and `/\\host` as another origin, and strip tabs or newlines before making the same decision.
- * Parsing against a fixed origin applies the browser's own rules rather than trying to copy them.
+ * by somebody outside the app. `startsWith("/")` is not enough: URL parsers read both `//host` and
+ * `/\\host` as another origin, and strip tabs or newlines before making the same decision. Parsing
+ * against a fixed origin applies the browser's own rules rather than trying to copy them.
  */
 export function safeInternalPath(value: unknown): string | null {
   if (typeof value !== "string" || !value.startsWith("/") || containsControl(value)) return null;
@@ -55,14 +55,15 @@ export interface PathParts {
  *
  * The fragment is the half that is easy to get wrong, and getting it wrong leaks a credential. A
  * Supabase client with no `flowType` uses the IMPLICIT flow, which returns the session in the
- * fragment — `#access_token=…&refresh_token=…`. A return target is recorded in a query string, and
- * a query string is not a fragment: it rides in `Referer`, it is written to every access log on the
+ * fragment, `#access_token=…&refresh_token=…`. A return target is recorded in a query string, and a
+ * query string is not a fragment: it rides in `Referer`, it is written to every access log on the
  * way, and it stays in history. So a fragment carrying a credential is dropped and the page is
  * kept, because the page is the part worth returning to and the anchor is the part that is
  * dangerous.
  *
- * Total on purpose — the caller is handing over its OWN address, which is on this origin by
- * construction. Use `safeInternalPath` for the other direction, where someone else wrote the value.
+ * Accepts every caller address on purpose. The caller is handing over its OWN address, which is on
+ * this origin by construction. Use `safeInternalPath` for the other direction, where someone else
+ * wrote the value.
  */
 export function returnPathFromLocation({ pathname, search, hash }: PathParts): string {
   const fragment = hash.startsWith("#") ? hash.slice(1) : hash;

package/src/prerender-contract.ts

@@ -1,5 +1,5 @@
 /**
- * The two constants the build and the browser both need — and **nothing else in this file**.
+ * The two constants the build and the browser both need. Keep **nothing else in this file**.
  *
  * It is separate from `hydrate.ts` for one reason: that module imports `react-dom/client`, and
  * `@gusnips/vite` needs these constants to WRITE the attribute at build time. If the constants
@@ -12,8 +12,8 @@
  */
 
 /**
- * The attribute a prerendered file names its own route in — written by the build, read by the
- * browser entry.
+ * The attribute where a prerendered file names its own route. The build writes it and the browser
+ * entry reads it.
  *
  * One constant because the writer and the reader are in different builds, and a typo between
  * them would show up only as a silent full re-render: a page that works, and a bug nobody sees.
@@ -23,9 +23,9 @@ export const PRERENDERED_ROUTE_ATTR = "data-prerendered-route";
 /**
  * What a 404 shell writes instead of a route.
  *
- * It is the pattern that actually matched — the catch-all — and it can never equal an address,
- * which is the property that matters: every route a static host answers from the shell mounts
- * fresh rather than hydrating the not-found page over itself. A real 404 pays one redundant
- * client render for that, and keeps the markup a crawler reads.
+ * It is the catch-all pattern that actually matched, and it can never equal an address, which is
+ * the property that matters: every route a static host answers from the shell mounts fresh rather
+ * than hydrating the not-found page over itself. A real 404 pays one redundant client render for
+ * that, and keeps the markup a crawler reads.
  */
 export const SHELL_ROUTE = "*";