@gusnips/react 0.2.0 → 0.4.0

package/README.md

@@ -128,14 +128,22 @@ hurry cannot skip.
 
 ## Also here
 
-`hydrateOrMount` for prerendered pages, `ErrorBoundary`, an SSE reader split into a platform-free
-parser and a stream wrapper, `i18nInitOptions`, and `cn`.
+`ErrorBoundary`, an SSE reader split into a platform-free parser and a stream wrapper,
+`i18nInitOptions`, and `cn`.
 
 `createAuthStore` is at `@gusnips/react/store` — a zustand store whose `isLoading` starts `false`
 where there is no window. A session bootstrap can only be in flight in a browser, and `true`
 during a build is a wait that never ends: it once shipped a spinner as the indexable body of a
 page whose whole job was to be found.
 
+`hydrateOrMount` is at `@gusnips/react/hydrate`, and the guards are at `@gusnips/react/guards`.
+
+## On a phone
+
+The main entry works in React Native. It imports `react` and nothing else you would have to go
+find — no `react-dom`, no router, no store — so the fetch client, the retry rule and the SSE
+parser all come along, and the four things that need a browser stay behind the subpaths above.
+
 ## The Base UI wrappers
 
 ```ts

package/dist/describe-error.d.ts

@@ -23,8 +23,21 @@ export interface DescribedError {
     /** What to do about it. Its absence should be a decision, not an oversight. */
     hint?: string;
 }
-/** The subset of i18next's `t` this module needs — typed here so `i18next` stays optional. */
-export type Translate = (key: string, params?: Record<string, unknown>) => string;
+/**
+ * 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.
+ */
+export type Translate<Key extends string = string> = (key: Key, params?: Record<string, unknown>) => string;
+/** The three names {@link humanizeWait} looks up, under whatever prefix you pass it. */
+type WaitName = "waitSeconds" | "waitMinutes" | "waitHours";
+/** Every name {@link createErrorDescriber} looks up itself. Your catalog carries all of them. */
+type CopyName = WaitName | "network" | "networkHint" | "unexpected" | "retrySoon";
 /** Seconds until a refusal clears, when the envelope carries them. */
 export declare function retryAfterSecs(error: ApiError): number | null;
 /**
@@ -32,31 +45,10 @@ export declare function retryAfterSecs(error: ApiError): number | null;
  *
  * 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` in the catalog, each with a
+ * one rung up. Needs `waitSeconds` / `waitMinutes` / `waitHours` under `prefix`, each with a
  * `count` plural.
  */
-export declare function humanizeWait(t: Translate, secs: number, prefix?: string): string;
-export interface ErrorDescriberOptions<Code extends string> {
-    t: Translate;
-    /**
-     * 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.
-     */
-    messageKeyPrefix?: string;
-    /**
-     * The keys this build actually carries, usually `Object.keys(en.serverErrors)`.
-     *
-     * Membership is checked with `hasOwnProperty` and not `in`, which would accept `"toString"`.
-     * A key that is absent falls back to the server's English `message`, because a deploy can land
-     * ahead of the bundle a tab is still running and a missing translation must degrade to
-     * readable rather than render the key itself at somebody.
-     */
-    knownMessageKeys?: readonly string[] | Record<string, unknown>;
-    /** Catalog namespace for this module's own copy. Defaults to `"errors."`. */
-    copyPrefix?: string;
-    /** Per-code copy. Everything not listed falls through to the default arm below. */
-    codes?: Partial<Record<Code, (ctx: ErrorContext) => DescribedError>>;
-}
+export declare function humanizeWait<Prefix extends string>(t: Translate<`${Prefix}${WaitName}`>, secs: number, prefix: Prefix): string;
 export interface ErrorContext {
     error: ApiError;
     /** The server's own localized sentence, when `messageKey` named one this build carries. */
@@ -64,11 +56,46 @@ export interface ErrorContext {
     /** Seconds until it clears, already humanized. Null when the envelope did not say. */
     wait: string | null;
     waitSecs: number | null;
-    t: Translate;
 }
-/**
- * Build the describer. Needs `network`, `networkHint`, `unexpected`, `retrySoon`,
- * `waitSeconds`, `waitMinutes` and `waitHours` under `copyPrefix` in every locale.
- */
-export declare function createErrorDescriber<Code extends string>({ t, messageKeyPrefix, knownMessageKeys, copyPrefix, codes, }: ErrorDescriberOptions<Code>): (error: unknown) => DescribedError;
+export interface ErrorDescriberOptions<Prefix extends string, ServerPrefix extends string, ServerName extends string> {
+    t: Translate<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName}`>;
+    /** Catalog namespace for this module's own copy, e.g. `"errors."`. */
+    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.
+     *
+     * 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;
+    /**
+     * The keys this build actually carries, usually the `serverErrors` object out of the English
+     * 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
+     * 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.
+     */
+    knownMessageKeys: Record<ServerName, unknown>;
+    /**
+     * 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.
+     *
+     * 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.
+     */
+    codes?: Partial<Record<string, ErrorArm>>;
+}
+export type ErrorArm = (ctx: ErrorContext) => DescribedError;
+/** Build the describer. */
+export declare function createErrorDescriber<Prefix extends string, ServerPrefix extends string, ServerName extends string>({ t, copyPrefix, messageKeyPrefix, knownMessageKeys, codes, }: ErrorDescriberOptions<Prefix, ServerPrefix, ServerName>): (error: unknown) => DescribedError;
+export {};
 //# sourceMappingURL=describe-error.d.ts.map

package/dist/describe-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe-error.d.ts","sourceRoot":"","sources":["../src/describe-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,8FAA8F;AAC9F,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;AAElF,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAK7D;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,SAAK,GAAG,MAAM,CAK5E;AAED,MAAM,WAAW,qBAAqB,CAAC,IAAI,SAAS,MAAM;IACxD,CAAC,EAAE,SAAS,CAAC;IACb;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/D,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,cAAc,CAAC,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,QAAQ,CAAC;IAChB,2FAA2F;IAC3F,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,sFAAsF;IACtF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,CAAC,EAAE,SAAS,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,SAAS,MAAM,EAAE,EACxD,CAAC,EACD,gBAAkC,EAClC,gBAAgB,EAChB,UAAsB,EACtB,KAAU,GACX,EAAE,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,cAAc,CA2ClE"}
+{"version":3,"file":"describe-error.d.ts","sourceRoot":"","sources":["../src/describe-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,IAAI,CACnD,GAAG,EAAE,GAAG,EACR,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,MAAM,CAAC;AAEZ,wFAAwF;AACxF,KAAK,QAAQ,GAAG,aAAa,GAAG,aAAa,GAAG,WAAW,CAAC;AAE5D,iGAAiG;AACjG,KAAK,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,GAAG,YAAY,GAAG,WAAW,CAAC;AA8BlF,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAK7D;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,SAAS,MAAM,EAChD,CAAC,EAAE,SAAS,CAAC,GAAG,MAAM,GAAG,QAAQ,EAAE,CAAC,EACpC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,MAAM,CAIR;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,QAAQ,CAAC;IAChB,2FAA2F;IAC3F,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,sFAAsF;IACtF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB,CACpC,MAAM,SAAS,MAAM,EACrB,YAAY,SAAS,MAAM,EAC3B,UAAU,SAAS,MAAM;IAEzB,CAAC,EAAE,SAAS,CAAC,GAAG,MAAM,GAAG,QAAQ,EAAE,GAAG,GAAG,YAAY,GAAG,UAAU,EAAE,CAAC,CAAC;IACtE,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;OASG;IACH,gBAAgB,EAAE,YAAY,CAAC;IAC/B;;;;;;;;;OASG;IACH,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC9C;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;CAC3C;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,cAAc,CAAC;AAE7D,2BAA2B;AAC3B,wBAAgB,oBAAoB,CAClC,MAAM,SAAS,MAAM,EACrB,YAAY,SAAS,MAAM,EAC3B,UAAU,SAAS,MAAM,EACzB,EACA,CAAC,EACD,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,KAAU,GACX,EAAE,qBAAqB,CAAC,MAAM,EAAE,YAAY,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,cAAc,CAkD9F"}

package/dist/describe-error.js

@@ -12,39 +12,41 @@ export function retryAfterSecs(error) {
  *
  * 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` in the catalog, each with a
+ * one rung up. Needs `waitSeconds` / `waitMinutes` / `waitHours` under `prefix`, each with a
  * `count` plural.
  */
-export function humanizeWait(t, secs, prefix = "") {
-    const key = (name) => `${prefix}${name}`;
+export function humanizeWait(t, secs, prefix) {
     if (secs < 90)
-        return t(key("waitSeconds"), { count: Math.max(1, Math.round(secs)) });
+        return t(`${prefix}waitSeconds`, { count: Math.max(1, Math.round(secs)) });
     if (secs < 90 * 60)
-        return t(key("waitMinutes"), { count: Math.round(secs / 60) });
-    return t(key("waitHours"), { count: Math.round(secs / 3600) });
+        return t(`${prefix}waitMinutes`, { count: Math.round(secs / 60) });
+    return t(`${prefix}waitHours`, { count: Math.round(secs / 3600) });
 }
-/**
- * Build the describer. Needs `network`, `networkHint`, `unexpected`, `retrySoon`,
- * `waitSeconds`, `waitMinutes` and `waitHours` under `copyPrefix` in every locale.
- */
-export function createErrorDescriber({ t, messageKeyPrefix = "serverErrors.", knownMessageKeys, copyPrefix = "errors.", codes = {}, }) {
-    const known = Array.isArray(knownMessageKeys)
-        ? new Set(knownMessageKeys)
-        : new Set(Object.keys(knownMessageKeys ?? {}));
-    const has = (name) => known.size === 0 || known.has(name);
-    const key = (name) => `${copyPrefix}${name}`;
+/** Build the describer. */
+export function createErrorDescriber({ t, copyPrefix, messageKeyPrefix, knownMessageKeys, codes = {}, }) {
+    const known = new Set(Object.keys(knownMessageKeys));
+    // Sound, and the reason nothing here needs a cast: the set was built from the keys of
+    // `knownMessageKeys`, so membership really does establish the claim. `Object.keys` and not
+    // `in`, which would have accepted "toString".
+    const has = (name) => known.has(name);
     function serverSentence(error) {
-        const messageKey = error.messageKey;
-        if (messageKey === undefined || !messageKey.startsWith(messageKeyPrefix))
-            return null;
-        const name = messageKey.slice(messageKeyPrefix.length);
-        return has(name) ? t(messageKey, error.params) : null;
+        const lookup = (named) => {
+            if (named === undefined || !named.startsWith(messageKeyPrefix))
+                return null;
+            const name = named.slice(messageKeyPrefix.length);
+            return has(name) ? t(`${messageKeyPrefix}${name}`, error.params) : null;
+        };
+        // `messageKey` first: an API that sends both means the key, and the code is what the UI
+        // switches on. The code is only consulted when there is no key to prefer, and it is spelled
+        // under the same prefix so the gate is identical.
+        return (lookup(error.messageKey) ??
+            (error.code === undefined ? null : lookup(`${messageKeyPrefix}${error.code}`)));
     }
     return function describeError(error) {
         if (!(error instanceof ApiError)) {
             // Not a response at all — the request never landed. Almost always the network, and almost
             // never worth showing a stack trace for.
-            return { cause: t(key("network")), hint: t(key("networkHint")) };
+            return { cause: t(`${copyPrefix}network`), hint: t(`${copyPrefix}networkHint`) };
         }
         const waitSecs = retryAfterSecs(error);
         const ctx = {
@@ -52,7 +54,6 @@ export function createErrorDescriber({ t, messageKeyPrefix = "serverErrors.", kn
             says: serverSentence(error),
             wait: waitSecs === null ? null : humanizeWait(t, waitSecs, copyPrefix),
             waitSecs,
-            t,
         };
         const arm = error.code === undefined ? undefined : codes[error.code];
         if (arm)
@@ -62,8 +63,8 @@ export function createErrorDescriber({ t, messageKeyPrefix = "serverErrors.", kn
         // genuinely does clear on its own — a 4xx does not, and saying so would be a lie that costs
         // the reader another attempt.
         return {
-            cause: ctx.says ?? (error.message || t(key("unexpected"))),
-            hint: error.status >= 500 ? t(key("retrySoon")) : undefined,
+            cause: ctx.says ?? (error.message || t(`${copyPrefix}unexpected`)),
+            hint: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
         };
     };
 }

package/dist/describe-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"describe-error.js","sourceRoot":"","sources":["../src/describe-error.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"describe-error.js","sourceRoot":"","sources":["../src/describe-error.ts"],"names":[],"mappings":"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"}

package/dist/hydrate.d.ts

@@ -8,6 +8,11 @@
  *
  * 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.
  */
 import type { ReactNode } from "react";
 export { PRERENDERED_ROUTE_ATTR, SHELL_ROUTE } from "./prerender-contract.ts";

package/dist/hydrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../src/hydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAGpF"}
+{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../src/hydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAGpF"}

package/dist/hydrate.js.map

@@ -1 +1 @@
-{"version":3,"file":"hydrate.js","sourceRoot":"","sources":["../src/hydrate.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAC,MAAe,EAAE,IAAe,EAAE,KAAa;IAC5E,IAAI,MAAM,CAAC,YAAY,CAAC,sBAAsB,CAAC,KAAK,KAAK;QAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;;QAChF,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACvC,CAAC"}
+{"version":3,"file":"hydrate.js","sourceRoot":"","sources":["../src/hydrate.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAC,MAAe,EAAE,IAAe,EAAE,KAAa;IAC5E,IAAI,MAAM,CAAC,YAAY,CAAC,sBAAsB,CAAC,KAAK,KAAK;QAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;;QAChF,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACvC,CAAC"}

package/dist/index.d.ts

@@ -4,9 +4,9 @@ export { createApiClient, type ApiClient, type ApiClientOptions, type RefreshRes
 export { createSseParser, readSseStream, type SseFrame } from "./sse.ts";
 export { queryDefaults, shouldRetry, type QueryDefaultsOptions } from "./query.ts";
 export { ErrorBoundary, type ErrorBoundaryFallbackProps, type ErrorBoundaryProps, } from "./error-boundary.tsx";
-export { createErrorDescriber, humanizeWait, retryAfterSecs, type DescribedError, type ErrorContext, type ErrorDescriberOptions, type Translate, } from "./describe-error.ts";
+export { createErrorDescriber, humanizeWait, retryAfterSecs, type DescribedError, type ErrorArm, type ErrorContext, type ErrorDescriberOptions, type Translate, } from "./describe-error.ts";
 export { installPreloadErrorHandler, isChunkLoadError, isPreloadHintFailure, reloadOnceForChunkError, } from "./chunk-reload.ts";
-export { hydrateOrMount, PRERENDERED_ROUTE_ATTR, SHELL_ROUTE } from "./hydrate.ts";
+export { PRERENDERED_ROUTE_ATTR, SHELL_ROUTE } from "./prerender-contract.ts";
 export { applyBrandVars, i18nInitOptions, type I18nInitOptions } from "./i18n.ts";
 export type { EmptyStateProps, ErrorStateProps } from "./states.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEnF,OAAO,EACL,aAAa,EACb,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEnF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAElF,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA6BA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEnF,OAAO,EACL,aAAa,EACb,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAElF,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -11,13 +11,21 @@
 //   @gusnips/react/ui       the Base UI wrappers   → @base-ui/react
 //   @gusnips/react/store    createAuthStore        → zustand
 //   @gusnips/react/guards   the route guards       → react-router-dom
+//   @gusnips/react/hydrate  hydrateOrMount         → react-dom
 //
-// So what is left here imports `react`, `react-dom` and `@gusnips/http` and nothing else, and an
-// app on TanStack Router or on Redux takes the fetch client without installing a router or a
-// store it will never call. `@tanstack/react-query`, `i18next` and `react-i18next` stay optional
-// AND stay here, because `query.ts`, `i18n.ts` and `states.ts` import only their TYPES — which
-// erase, so the built barrel does not reference them at runtime. Check that claim against
-// `dist/`, never against this file: a type-only re-export looks identical in source.
+// `react-dom` is the one the second migration added, and it is the sharpest case yet: olhary
+// ships a REACT NATIVE app beside its two web apps, and React Native has no react-dom to give.
+// A required peer nobody can satisfy is not a strict contract, it is a closed door — the whole
+// package was unusable there, for one function no phone would ever call. The rule did not need
+// changing to catch it; `react-dom` simply had to stop being required.
+//
+// So what is left here imports `react` and `@gusnips/http` and nothing else, and an app on
+// TanStack Router, on Redux, or on a phone takes the fetch client without installing a router, a
+// store or a DOM renderer it will never call. `@tanstack/react-query`, `i18next` and
+// `react-i18next` stay optional AND stay here, because `query.ts`, `i18n.ts` and `states.ts`
+// import only their TYPES — which erase, so the built barrel does not reference them at runtime.
+// Check that claim against `dist/`, never against this file: a type-only re-export looks
+// identical in source.
 export { cn } from "./cn.js";
 export { ApiError, isAbortError } from "./api-error.js";
 export { createApiClient, } from "./api-client.js";
@@ -26,6 +34,9 @@ export { queryDefaults, shouldRetry } from "./query.js";
 export { ErrorBoundary, } from "./error-boundary.js";
 export { createErrorDescriber, humanizeWait, retryAfterSecs, } from "./describe-error.js";
 export { installPreloadErrorHandler, isChunkLoadError, isPreloadHintFailure, reloadOnceForChunkError, } from "./chunk-reload.js";
-export { hydrateOrMount, PRERENDERED_ROUTE_ATTR, SHELL_ROUTE } from "./hydrate.js";
+// The two constants, but NOT `hydrateOrMount` — that one is at `@gusnips/react/hydrate`, because
+// it is the package's only `react-dom` import. These come from the contract module, which imports
+// nothing at all, so they are free to everyone: a build script, a browser entry, or a phone.
+export { PRERENDERED_ROUTE_ATTR, SHELL_ROUTE } from "./prerender-contract.js";
 export { applyBrandVars, i18nInitOptions } from "./i18n.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,+FAA+F;AAC/F,iGAAiG;AACjG,0BAA0B;AAC1B,EAAE;AACF,oEAAoE;AACpE,6DAA6D;AAC7D,sEAAsE;AACtE,EAAE;AACF,iGAAiG;AACjG,6FAA6F;AAC7F,iGAAiG;AACjG,+FAA+F;AAC/F,0FAA0F;AAC1F,qFAAqF;AAErF,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,eAAe,GAMhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,WAAW,EAA6B,MAAM,YAAY,CAAC;AAEnF,OAAO,EACL,aAAa,GAGd,MAAM,qBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,cAAc,GAKf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEnF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAwB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,+FAA+F;AAC/F,iGAAiG;AACjG,0BAA0B;AAC1B,EAAE;AACF,oEAAoE;AACpE,6DAA6D;AAC7D,sEAAsE;AACtE,+DAA+D;AAC/D,EAAE;AACF,6FAA6F;AAC7F,+FAA+F;AAC/F,+FAA+F;AAC/F,+FAA+F;AAC/F,uEAAuE;AACvE,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,qFAAqF;AACrF,6FAA6F;AAC7F,iGAAiG;AACjG,yFAAyF;AACzF,uBAAuB;AAEvB,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,eAAe,GAMhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,WAAW,EAA6B,MAAM,YAAY,CAAC;AAEnF,OAAO,EACL,aAAa,GAGd,MAAM,qBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,cAAc,GAMf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,iGAAiG;AACjG,kGAAkG;AAClG,6FAA6F;AAC7F,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAwB,MAAM,WAAW,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "The headless runtime under a Vite + React SPA: typed fetch client with single-flight refresh, auth store, query defaults, route guards, error boundary, chunk-reload recovery, i18n bootstrap.",
   "type": "module",
   "license": "MIT",
@@ -26,6 +26,10 @@
       "types": "./dist/guards.d.ts",
       "default": "./dist/guards.js"
     },
+    "./hydrate": {
+      "types": "./dist/hydrate.d.ts",
+      "default": "./dist/hydrate.js"
+    },
     "./contract": {
       "types": "./dist/prerender-contract.d.ts",
       "default": "./dist/prerender-contract.js"
@@ -92,6 +96,9 @@
     "i18next": {
       "optional": true
     },
+    "react-dom": {
+      "optional": true
+    },
     "react-i18next": {
       "optional": true
     },

package/src/chunk-reload.test.ts

@@ -1,5 +1,5 @@
-import { describe, expect, it } from "vitest";
-import { isChunkLoadError, isPreloadHintFailure } from "./chunk-reload.ts";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { isChunkLoadError, isPreloadHintFailure, reloadOnceForChunkError } from "./chunk-reload.ts";
 
 // No browser gives a failed dynamic import a shared type, so this is matched by message and
 // every phrasing has to be here. A miss is a white screen after a deploy — the exact failure
@@ -30,6 +30,9 @@ describe("isChunkLoadError", () => {
   it("does not match an ordinary render error", () => {
     expect(isChunkLoadError(new TypeError("Cannot read properties of undefined"))).toBe(false);
     expect(isChunkLoadError(null)).toBe(false);
+    // A thrown string reaches the `String(error)` branch, which is the one a non-Error throw
+    // takes — and the one that would blow up if it were written `error.message`.
+    expect(isChunkLoadError("something failed")).toBe(false);
   });
 });
 
@@ -44,3 +47,67 @@ describe("isPreloadHintFailure", () => {
     );
   });
 });
+
+/**
+ * The guard, which is the whole reason this function exists rather than a bare
+ * `location.reload()` at the call site. Reloading on a chunk error the reload does not fix is
+ * an infinite loop with a person inside it, and it only reproduces on a real broken deploy —
+ * so this is the only place the rule gets checked.
+ *
+ * Two globals, stubbed rather than run under a DOM: `window` and `sessionStorage` are the only
+ * ones this module touches, and adding jsdom to a package whose whole point is a small
+ * dependency list would cost more than it explains.
+ */
+describe("reloadOnceForChunkError", () => {
+  const reload = vi.fn();
+  let store: Record<string, string> = {};
+  /** Throws from both methods, the way a browser does when site data is blocked. */
+  let blocked = false;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    reload.mockClear();
+    store = {};
+    blocked = false;
+    vi.stubGlobal("window", { location: { reload } });
+    vi.stubGlobal("sessionStorage", {
+      getItem: (key: string): string | null => {
+        if (blocked) throw new Error("site data blocked");
+        return store[key] ?? null;
+      },
+      setItem: (key: string, value: string): void => {
+        if (blocked) throw new Error("site data blocked");
+        store[key] = value;
+      },
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  it("reloads on the first chunk failure", () => {
+    expect(reloadOnceForChunkError()).toBe(true);
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it("refuses a second reload inside the window, so a dead chunk cannot loop", () => {
+    expect(reloadOnceForChunkError()).toBe(true);
+    expect(reloadOnceForChunkError()).toBe(false);
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it("allows another one after the window, because the next deploy is a new problem", () => {
+    expect(reloadOnceForChunkError()).toBe(true);
+    vi.setSystemTime(Date.now() + 61_000);
+    expect(reloadOnceForChunkError()).toBe(true);
+    expect(reload).toHaveBeenCalledTimes(2);
+  });
+
+  it("still reloads when storage is blocked — a privacy setting is not a reason to strand", () => {
+    blocked = true;
+    expect(reloadOnceForChunkError()).toBe(true);
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+});

package/src/describe-error.test.ts

@@ -42,7 +42,9 @@ describe("retryAfterSecs", () => {
 describe("createErrorDescriber", () => {
   const describeError = createErrorDescriber({
     t,
-    knownMessageKeys: ["quotaDay", "suspended"],
+    copyPrefix: "errors.",
+    messageKeyPrefix: "serverErrors.",
+    knownMessageKeys: { quotaDay: "", suspended: "" },
     codes: {
       QUOTA_EXCEEDED: ({ says, wait }) => ({
         cause: says ?? "errors.quota",
@@ -100,3 +102,39 @@ describe("createErrorDescriber", () => {
     expect(describeError(new ApiError(403, null)).hint).toBeUndefined();
   });
 });
+
+/**
+ * The second convention in the fleet: an API with no `messageKey` field at all, whose CODE
+ * names the sentence. One repo has 98 of them — `errors.FORECAST_NOT_FOUND` and its siblings —
+ * and its client used to resolve them itself, which is how the translation ended up inside the
+ * transport.
+ */
+describe("createErrorDescriber, when the code names the sentence", () => {
+  const describeError = createErrorDescriber({
+    t,
+    copyPrefix: "errors.",
+    messageKeyPrefix: "errors.",
+    knownMessageKeys: { FORECAST_NOT_FOUND: "", network: "" },
+  });
+
+  it("resolves a code this build has copy for", () => {
+    const error = new ApiError(404, { code: "FORECAST_NOT_FOUND", message: "Forecast not found" });
+    expect(describeError(error).cause).toBe("errors.FORECAST_NOT_FOUND");
+  });
+
+  it("falls back to the server's own message for a code with no copy", () => {
+    // The server writes for a developer, so this is the worse of the two — but it is still the
+    // most specific thing anyone has, and support can act on it.
+    const error = new ApiError(429, { code: "RESEARCH_LIMIT", message: "Concurrent limit hit" });
+    expect(describeError(error).cause).toBe("Concurrent limit hit");
+  });
+
+  it("prefers messageKey when the server sends both", () => {
+    const error = new ApiError(404, {
+      code: "FORECAST_NOT_FOUND",
+      message: "Forecast not found",
+      messageKey: "errors.network",
+    });
+    expect(describeError(error).cause).toBe("errors.network");
+  });
+});

package/src/describe-error.ts

@@ -26,8 +26,54 @@ export interface DescribedError {
   hint?: string;
 }
 
-/** The subset of i18next's `t` this module needs — typed here so `i18next` stays optional. */
-export type Translate = (key: string, params?: Record<string, unknown>) => string;
+/**
+ * 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.
+ */
+export type Translate<Key extends string = string> = (
+  key: Key,
+  params?: Record<string, unknown>,
+) => string;
+
+/** The three names {@link humanizeWait} looks up, under whatever prefix you pass it. */
+type WaitName = "waitSeconds" | "waitMinutes" | "waitHours";
+
+/** Every name {@link createErrorDescriber} looks up itself. Your catalog carries all of them. */
+type CopyName = WaitName | "network" | "networkHint" | "unexpected" | "retrySoon";
+
+/**
+ * The paragraph above, pinned so it cannot quietly stop being true.
+ *
+ * `ClosedCatalog` is what an app's `t` looks like once it declares `CustomTypeOptions.resources`:
+ * a closed union, nothing else accepted. It must go straight into the options below. Widen `Key`
+ * back to `string` and this stops compiling HERE, rather than at the eleventh adopter reaching
+ * for the cast the house rules forbid.
+ */
+type Satisfied<T extends true> = T;
+type ClosedCatalog = (
+  key:
+    | "errors.network"
+    | "errors.networkHint"
+    | "errors.unexpected"
+    | "errors.retrySoon"
+    | "errors.waitSeconds"
+    | "errors.waitMinutes"
+    | "errors.waitHours"
+    | "serverErrors.quotaDay"
+    | "billing.plan",
+  params?: Record<string, unknown>,
+) => string;
+type _TypedCatalogNeedsNoCast = Satisfied<
+  ClosedCatalog extends ErrorDescriberOptions<"errors.", "serverErrors.", "quotaDay">["t"]
+    ? true
+    : false
+>;
 
 /** Seconds until a refusal clears, when the envelope carries them. */
 export function retryAfterSecs(error: ApiError): number | null {
@@ -42,78 +88,111 @@ export function retryAfterSecs(error: ApiError): number | null {
  *
  * 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` in the catalog, each with a
+ * one rung up. Needs `waitSeconds` / `waitMinutes` / `waitHours` under `prefix`, each with a
  * `count` plural.
  */
-export function humanizeWait(t: Translate, secs: number, prefix = ""): string {
-  const key = (name: string): string => `${prefix}${name}`;
-  if (secs < 90) return t(key("waitSeconds"), { count: Math.max(1, Math.round(secs)) });
-  if (secs < 90 * 60) return t(key("waitMinutes"), { count: Math.round(secs / 60) });
-  return t(key("waitHours"), { count: Math.round(secs / 3600) });
+export function humanizeWait<Prefix extends string>(
+  t: Translate<`${Prefix}${WaitName}`>,
+  secs: number,
+  prefix: Prefix,
+): string {
+  if (secs < 90) return t(`${prefix}waitSeconds`, { count: Math.max(1, Math.round(secs)) });
+  if (secs < 90 * 60) return t(`${prefix}waitMinutes`, { count: Math.round(secs / 60) });
+  return t(`${prefix}waitHours`, { count: Math.round(secs / 3600) });
+}
+
+export interface ErrorContext {
+  error: ApiError;
+  /** The server's own localized sentence, when `messageKey` named one this build carries. */
+  says: string | null;
+  /** Seconds until it clears, already humanized. Null when the envelope did not say. */
+  wait: string | null;
+  waitSecs: number | null;
 }
 
-export interface ErrorDescriberOptions<Code extends string> {
-  t: Translate;
+export interface ErrorDescriberOptions<
+  Prefix extends string,
+  ServerPrefix extends string,
+  ServerName extends string,
+> {
+  t: Translate<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName}`>;
+  /** Catalog namespace for this module's own copy, e.g. `"errors."`. */
+  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.
+   *
+   * 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?: string;
+  messageKeyPrefix: ServerPrefix;
   /**
-   * The keys this build actually carries, usually `Object.keys(en.serverErrors)`.
+   * The keys this build actually carries, usually the `serverErrors` object out of the English
+   * 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.
    *
-   * Membership is checked with `hasOwnProperty` and not `in`, which would accept `"toString"`.
-   * A key that is absent falls back to the server's English `message`, because a deploy can land
-   * ahead of the bundle a tab is still running and a missing translation must degrade to
-   * readable rather than render the key itself at somebody.
+   * 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
+   * 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.
    */
-  knownMessageKeys?: readonly string[] | Record<string, unknown>;
-  /** Catalog namespace for this module's own copy. Defaults to `"errors."`. */
-  copyPrefix?: string;
-  /** Per-code copy. Everything not listed falls through to the default arm below. */
-  codes?: Partial<Record<Code, (ctx: ErrorContext) => DescribedError>>;
+  knownMessageKeys: Record<ServerName, unknown>;
+  /**
+   * 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.
+   *
+   * 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.
+   */
+  codes?: Partial<Record<string, ErrorArm>>;
 }
 
-export interface ErrorContext {
-  error: ApiError;
-  /** The server's own localized sentence, when `messageKey` named one this build carries. */
-  says: string | null;
-  /** Seconds until it clears, already humanized. Null when the envelope did not say. */
-  wait: string | null;
-  waitSecs: number | null;
-  t: Translate;
-}
+export type ErrorArm = (ctx: ErrorContext) => DescribedError;
 
-/**
- * Build the describer. Needs `network`, `networkHint`, `unexpected`, `retrySoon`,
- * `waitSeconds`, `waitMinutes` and `waitHours` under `copyPrefix` in every locale.
- */
-export function createErrorDescriber<Code extends string>({
+/** Build the describer. */
+export function createErrorDescriber<
+  Prefix extends string,
+  ServerPrefix extends string,
+  ServerName extends string,
+>({
   t,
-  messageKeyPrefix = "serverErrors.",
+  copyPrefix,
+  messageKeyPrefix,
   knownMessageKeys,
-  copyPrefix = "errors.",
   codes = {},
-}: ErrorDescriberOptions<Code>): (error: unknown) => DescribedError {
-  const known = Array.isArray(knownMessageKeys)
-    ? new Set<string>(knownMessageKeys)
-    : new Set(Object.keys(knownMessageKeys ?? {}));
+}: ErrorDescriberOptions<Prefix, ServerPrefix, ServerName>): (error: unknown) => DescribedError {
+  const known = new Set<string>(Object.keys(knownMessageKeys));
 
-  const has = (name: string): boolean => known.size === 0 || known.has(name);
-  const key = (name: string): string => `${copyPrefix}${name}`;
+  // Sound, and the reason nothing here needs a cast: the set was built from the keys of
+  // `knownMessageKeys`, so membership really does establish the claim. `Object.keys` and not
+  // `in`, which would have accepted "toString".
+  const has = (name: string): name is ServerName => known.has(name);
 
   function serverSentence(error: ApiError): string | null {
-    const messageKey = error.messageKey;
-    if (messageKey === undefined || !messageKey.startsWith(messageKeyPrefix)) return null;
-    const name = messageKey.slice(messageKeyPrefix.length);
-    return has(name) ? t(messageKey, error.params) : null;
+    const lookup = (named: string | undefined): string | null => {
+      if (named === undefined || !named.startsWith(messageKeyPrefix)) return null;
+      const name = named.slice(messageKeyPrefix.length);
+      return has(name) ? t(`${messageKeyPrefix}${name}`, error.params) : null;
+    };
+    // `messageKey` first: an API that sends both means the key, and the code is what the UI
+    // switches on. The code is only consulted when there is no key to prefer, and it is spelled
+    // under the same prefix so the gate is identical.
+    return (
+      lookup(error.messageKey) ??
+      (error.code === undefined ? null : lookup(`${messageKeyPrefix}${error.code}`))
+    );
   }
 
   return function describeError(error: unknown): DescribedError {
     if (!(error instanceof ApiError)) {
       // Not a response at all — the request never landed. Almost always the network, and almost
       // never worth showing a stack trace for.
-      return { cause: t(key("network")), hint: t(key("networkHint")) };
+      return { cause: t(`${copyPrefix}network`), hint: t(`${copyPrefix}networkHint`) };
     }
 
     const waitSecs = retryAfterSecs(error);
@@ -122,10 +201,9 @@ export function createErrorDescriber<Code extends string>({
       says: serverSentence(error),
       wait: waitSecs === null ? null : humanizeWait(t, waitSecs, copyPrefix),
       waitSecs,
-      t,
     };
 
-    const arm = error.code === undefined ? undefined : codes[error.code as Code];
+    const arm = error.code === undefined ? undefined : codes[error.code];
     if (arm) return arm(ctx);
 
     // Anything unmapped: the server's own sentence is still the most specific thing we have,
@@ -133,8 +211,8 @@ export function createErrorDescriber<Code extends string>({
     // genuinely does clear on its own — a 4xx does not, and saying so would be a lie that costs
     // the reader another attempt.
     return {
-      cause: ctx.says ?? (error.message || t(key("unexpected"))),
-      hint: error.status >= 500 ? t(key("retrySoon")) : undefined,
+      cause: ctx.says ?? (error.message || t(`${copyPrefix}unexpected`)),
+      hint: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
     };
   };
 }

package/src/hydrate.ts

@@ -8,6 +8,11 @@
  *
  * 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.
  */
 import type { ReactNode } from "react";
 import { createRoot, hydrateRoot } from "react-dom/client";

package/src/index.ts

@@ -11,13 +11,21 @@
 //   @gusnips/react/ui       the Base UI wrappers   → @base-ui/react
 //   @gusnips/react/store    createAuthStore        → zustand
 //   @gusnips/react/guards   the route guards       → react-router-dom
+//   @gusnips/react/hydrate  hydrateOrMount         → react-dom
 //
-// So what is left here imports `react`, `react-dom` and `@gusnips/http` and nothing else, and an
-// app on TanStack Router or on Redux takes the fetch client without installing a router or a
-// store it will never call. `@tanstack/react-query`, `i18next` and `react-i18next` stay optional
-// AND stay here, because `query.ts`, `i18n.ts` and `states.ts` import only their TYPES — which
-// erase, so the built barrel does not reference them at runtime. Check that claim against
-// `dist/`, never against this file: a type-only re-export looks identical in source.
+// `react-dom` is the one the second migration added, and it is the sharpest case yet: olhary
+// ships a REACT NATIVE app beside its two web apps, and React Native has no react-dom to give.
+// A required peer nobody can satisfy is not a strict contract, it is a closed door — the whole
+// package was unusable there, for one function no phone would ever call. The rule did not need
+// changing to catch it; `react-dom` simply had to stop being required.
+//
+// So what is left here imports `react` and `@gusnips/http` and nothing else, and an app on
+// TanStack Router, on Redux, or on a phone takes the fetch client without installing a router, a
+// store or a DOM renderer it will never call. `@tanstack/react-query`, `i18next` and
+// `react-i18next` stay optional AND stay here, because `query.ts`, `i18n.ts` and `states.ts`
+// import only their TYPES — which erase, so the built barrel does not reference them at runtime.
+// Check that claim against `dist/`, never against this file: a type-only re-export looks
+// identical in source.
 
 export { cn } from "./cn.ts";
 
@@ -44,6 +52,7 @@ export {
   humanizeWait,
   retryAfterSecs,
   type DescribedError,
+  type ErrorArm,
   type ErrorContext,
   type ErrorDescriberOptions,
   type Translate,
@@ -56,7 +65,10 @@ export {
   reloadOnceForChunkError,
 } from "./chunk-reload.ts";
 
-export { hydrateOrMount, PRERENDERED_ROUTE_ATTR, SHELL_ROUTE } from "./hydrate.ts";
+// The two constants, but NOT `hydrateOrMount` — that one is at `@gusnips/react/hydrate`, because
+// it is the package's only `react-dom` import. These come from the contract module, which imports
+// nothing at all, so they are free to everyone: a build script, a browser entry, or a phone.
+export { PRERENDERED_ROUTE_ATTR, SHELL_ROUTE } from "./prerender-contract.ts";
 
 export { applyBrandVars, i18nInitOptions, type I18nInitOptions } from "./i18n.ts";