@gusnips/react 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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/api-client.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { ApiError, isAbortError } from "./api-error.ts";
+import { ApiError, isAbortError, retryAfterSecs } from "./api-error.ts";
 import { createApiClient, type RefreshResult, type SessionAdapter } from "./api-client.ts";
 
 function stubFetch(handler: (url: string, init: RequestInit) => Response | Promise<Response>) {
@@ -65,6 +65,43 @@ describe("createApiClient", () => {
     });
   });
 
+  /**
+   * The second migration's API states the wait in the HEADER and puts nothing in the body — the
+   * standard place, and the one this package did not read. `retryAfterSecs` now answers for
+   * either convention, which is what lets one retry rule and one piece of copy serve both.
+   */
+  it("reads the wait off the Retry-After header", async () => {
+    stubFetch(
+      () =>
+        new Response(JSON.stringify({ error: { code: "RATE_LIMIT_EXCEEDED", message: "slow" } }), {
+          status: 429,
+          headers: { "Retry-After": "60" },
+        }),
+    );
+    const api = createApiClient({
+      baseUrl: "https://api.test",
+      session: session(),
+      onSessionDead: () => {},
+    });
+
+    const error = await api.get("/x").catch((e: unknown) => e);
+    expect(error).toMatchObject({ status: 429, retryAfterSecs: 60 });
+    expect(retryAfterSecs(error as ApiError)).toBe(60);
+  });
+
+  it("leaves the wait unset when the answer did not state one", async () => {
+    stubFetch(() => new Response("{}", { status: 500 }));
+    const api = createApiClient({
+      baseUrl: "https://api.test",
+      session: session(),
+      onSessionDead: () => {},
+    });
+
+    const error = await api.get("/x").catch((e: unknown) => e);
+    expect((error as ApiError).retryAfterSecs).toBeUndefined();
+    expect(retryAfterSecs(error as ApiError)).toBeNull();
+  });
+
   /**
    * The single-flight rule, and the reason all three donors found it the hard way: the auth
    * server rotates the refresh token on use, so six parallel 401s sending six refreshes means
@@ -150,15 +187,15 @@ describe("createApiClient", () => {
 
   /**
    * providerkit's invariant 2, on the web side: a caller's Stop and our deadline must stay
-   * distinguishable. `AbortSignal.timeout` rejects with a **TimeoutError**, not an AbortError,
-   * so `isAbortError` stays false for it — which is what lets a timeout be retried and reported
+   * distinguishable. The deadline aborts with a **TimeoutError**, not an AbortError, so
+   * `isAbortError` stays false for it — which is what lets a timeout be retried and reported
    * while a navigation-cancelled request is silently dropped.
    */
   it("distinguishes its own timeout from the caller's abort", async () => {
     // Note the `aborted` check before the listener. A signal that fired before fetch was ever
     // called never emits the event, so a listener alone hangs forever — real `fetch` checks the
-    // flag first, and so must anything standing in for it. That already-aborted race is exactly
-    // what `AbortSignal.any` in the client exists to cover.
+    // flag first, and so must anything standing in for it. That already-aborted race is one of
+    // the three things `withDeadline` exists to get right.
     stubFetch(
       (_url, init) =>
         new Promise<Response>((_resolve, reject) => {
@@ -175,13 +212,44 @@ describe("createApiClient", () => {
     });
 
     const timedOut = await api.get("/slow").catch((e: unknown) => e);
-    expect((timedOut as DOMException).name).toBe("TimeoutError");
+    expect((timedOut as Error).name).toBe("TimeoutError");
     expect(isAbortError(timedOut)).toBe(false);
 
     const controller = new AbortController();
     const cancelled = api.get("/slow", { signal: controller.signal }).catch((e: unknown) => e);
     controller.abort();
     expect(isAbortError(await cancelled)).toBe(true);
+
+    // The already-aborted race: a signal that fired BEFORE the call. A listener alone never
+    // hears it, so the request would go out and run to full term with nobody waiting.
+    const already = new AbortController();
+    already.abort();
+    const dead = await api.get("/slow", { signal: already.signal }).catch((e: unknown) => e);
+    expect(isAbortError(dead)).toBe(true);
+  });
+
+  /**
+   * React Native replaces the global `AbortSignal` with abort-controller@3, which has neither
+   * `timeout` nor `any`. The client used both, so `createApiClient` threw
+   * `AbortSignal.timeout is not a function` on the phone's first request — in the main entry,
+   * the one this package promises works there. Deleting the statics is the cheapest honest
+   * stand-in for that runtime.
+   */
+  it("works where AbortSignal has no static helpers, as on a phone", async () => {
+    const { timeout, any } = AbortSignal as unknown as Record<string, unknown>;
+    delete (AbortSignal as unknown as Record<string, unknown>).timeout;
+    delete (AbortSignal as unknown as Record<string, unknown>).any;
+    try {
+      stubFetch(() => ok({ id: "1" }));
+      const api = createApiClient({
+        baseUrl: "https://api.test",
+        session: session(),
+        onSessionDead: () => {},
+      });
+      await expect(api.get("/me")).resolves.toEqual({ id: "1" });
+    } finally {
+      Object.assign(AbortSignal, { timeout, any });
+    }
   });
 
   // A 204 has no body, so `res.json()` on one throws `Unexpected end of JSON input` — which

package/src/api-client.ts

@@ -1,5 +1,5 @@
 import { isApiError, type ApiSuccess } from "@gusnips/http";
-import { ApiError } from "./api-error.ts";
+import { ApiError, parseRetryAfter } from "./api-error.ts";
 
 /**
  * The app's one door to the API. Nothing else should call `fetch`.
@@ -144,6 +144,67 @@ export interface ApiClient {
 
 const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
 
+/**
+ * One signal that fires on the caller's abort or on the deadline, whichever comes first.
+ *
+ * `AbortSignal.timeout` plus `AbortSignal.any` is the obvious way to write this, and it is
+ * not portable: React Native replaces the global `AbortSignal` with abort-controller@3, which
+ * has neither static — so the phone got `AbortSignal.timeout is not a function` on its very
+ * first request. This is the same two rules with an `AbortController`, which every runtime
+ * this package targets does have, and it is the ONLY path rather than a fallback: one branch
+ * cannot drift from the other.
+ *
+ * Three details that are the whole reason this is not three lines:
+ *
+ * - **The already-aborted race.** A caller whose signal fired before we attached would never
+ *   fire the listener, so the request would go out and run to full term. Checked first.
+ * - **A timeout must not look like a cancellation.** `isAbortError` exists so a request nobody
+ *   is waiting for stays silent; a request that ran out of time is a real failure somebody
+ *   should see. A bare `controller.abort()` raises an `AbortError` and would be swallowed, so
+ *   the deadline aborts with a plain `Error` — not a `DOMException`, which `isAbortError` is
+ *   the one thing that checks for.
+ * - **The timer is cleared.** Otherwise every completed request leaves a pending timeout for
+ *   the rest of its budget, which on a phone is a wake-up nobody asked for.
+ */
+function withDeadline(
+  ms: number,
+  caller: AbortSignal | null | undefined,
+): { signal: AbortSignal; clear: () => void } {
+  const controller = new AbortController();
+  const timer = setTimeout(() => {
+    // Named, not typed: callers identify a deadline by `name === "TimeoutError"`, the same
+    // way `AbortSignal.timeout` reports it. A `DOMException` would be the faithful copy and is
+    // not constructible everywhere this runs.
+    const expired = new Error(`Request timed out after ${String(ms)}ms`);
+    expired.name = "TimeoutError";
+    controller.abort(expired);
+  }, ms);
+
+  let detach = (): void => {};
+  if (caller) {
+    if (caller.aborted) {
+      clearTimeout(timer);
+      controller.abort(caller.reason);
+    } else {
+      const onAbort = (): void => {
+        controller.abort(caller.reason);
+      };
+      caller.addEventListener("abort", onAbort, { once: true });
+      detach = () => {
+        caller.removeEventListener("abort", onAbort);
+      };
+    }
+  }
+
+  return {
+    signal: controller.signal,
+    clear: () => {
+      clearTimeout(timer);
+      detach();
+    },
+  };
+}
+
 export function createApiClient({
   baseUrl,
   session,
@@ -215,15 +276,16 @@ export function createApiClient({
     if (budget === null)
       return fetch(`${baseUrl}${path}`, { ...init, signal, headers: buildHeaders(token, headers) });
 
-    // `AbortSignal.any` rather than a listener: it also catches the already-aborted race, where
-    // a caller's signal fired before we ever attached. It keeps the caller's abort and our
-    // timeout distinguishable at the source, which is what lets `isAbortError` stay honest.
-    const timeout = AbortSignal.timeout(budget);
-    return fetch(`${baseUrl}${path}`, {
-      ...init,
-      signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
-      headers: buildHeaders(token, headers),
-    });
+    const deadline = withDeadline(budget, signal);
+    try {
+      return await fetch(`${baseUrl}${path}`, {
+        ...init,
+        signal: deadline.signal,
+        headers: buildHeaders(token, headers),
+      });
+    } finally {
+      deadline.clear();
+    }
   }
 
   async function request(path: string, options: RequestOptions = {}): Promise<Response> {
@@ -249,6 +311,7 @@ export function createApiClient({
       const body: unknown = await res.json().catch(() => null);
       const error = new ApiError(res.status, isApiError(body) ? body.error : null, {
         requestId: res.headers.get(requestIdHeader) ?? undefined,
+        retryAfterSecs: parseRetryAfter(res.headers.get("retry-after")),
       });
       // A listener that throws must not become the error the caller sees: the API failure is
       // the real news, and swallowing it for a bug in a side effect would send everyone

package/src/api-error.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { ApiError, parseRetryAfter, retryAfterSecs } from "./api-error.ts";
+
+/**
+ * Two APIs, two places for the same fact: one states the wait in the `Retry-After` header (the
+ * standard one), the other in `details.retryAfterSecs`. A caller asking "how long" should not
+ * have to know which server answered.
+ */
+describe("retryAfterSecs", () => {
+  it("reads the header the client captured", () => {
+    expect(retryAfterSecs(new ApiError(429, null, { retryAfterSecs: 60 }))).toBe(60);
+    // Zero is a real answer — "now" — and must not read as "did not say".
+    expect(retryAfterSecs(new ApiError(429, null, { retryAfterSecs: 0 }))).toBe(0);
+  });
+
+  it("prefers the header to the body", () => {
+    const both = new ApiError(
+      429,
+      { code: "X", message: "", details: { retryAfterSecs: 30 } },
+      {
+        retryAfterSecs: 60,
+      },
+    );
+    expect(retryAfterSecs(both)).toBe(60);
+  });
+
+  it("reads the number out of details, and refuses anything else", () => {
+    expect(
+      retryAfterSecs(
+        new ApiError(429, { code: "X", message: "", details: { retryAfterSecs: 30 } }),
+      ),
+    ).toBe(30);
+    expect(
+      retryAfterSecs(
+        new ApiError(429, { code: "X", message: "", details: { retryAfterSecs: "30" } }),
+      ),
+    ).toBeNull();
+    expect(retryAfterSecs(new ApiError(429, { code: "X", message: "", details: null }))).toBeNull();
+    expect(retryAfterSecs(new ApiError(429, null))).toBeNull();
+  });
+});
+
+/**
+ * Both spec forms are real — RFC 9110 allows delay-seconds or an HTTP-date, and servers pick
+ * differently. The date half is the one that gets skipped, which silently turns a stated wait
+ * into no wait at all.
+ */
+describe("parseRetryAfter", () => {
+  it("reads delay-seconds", () => {
+    expect(parseRetryAfter("60")).toBe(60);
+    expect(parseRetryAfter("  60  ")).toBe(60);
+    expect(parseRetryAfter("0")).toBe(0);
+  });
+
+  it("reads an HTTP-date", () => {
+    const at = new Date(Date.now() + 120_000).toUTCString();
+    expect(parseRetryAfter(at)).toBeGreaterThanOrEqual(119);
+    expect(parseRetryAfter(at)).toBeLessThanOrEqual(120);
+  });
+
+  // A date already gone means "now", not a negative delay that would run the backoff backwards.
+  it("clamps a date in the past to zero", () => {
+    expect(parseRetryAfter(new Date(Date.now() - 60_000).toUTCString())).toBe(0);
+  });
+
+  it("answers nothing for a header that is missing or not a wait", () => {
+    expect(parseRetryAfter(null)).toBeUndefined();
+    expect(parseRetryAfter("")).toBeUndefined();
+    expect(parseRetryAfter("   ")).toBeUndefined();
+    expect(parseRetryAfter("soon")).toBeUndefined();
+    expect(parseRetryAfter("-5")).toBeUndefined();
+    expect(parseRetryAfter("9007199254740993")).toBeUndefined();
+  });
+});

package/src/api-error.ts

@@ -18,6 +18,17 @@ export class ApiError extends Error {
   readonly params: Record<string, string | number> | undefined;
   readonly details: unknown;
   readonly requestId: string | undefined;
+  /**
+   * Seconds until this refusal clears, when the answer said so.
+   *
+   * 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; {@link retryAfterSecs} reads either.
+   */
+  readonly retryAfterSecs: number | undefined;
 
   /**
    * The client raised this itself to stop a caller while it was already handling the
@@ -33,7 +44,12 @@ export class ApiError extends Error {
   constructor(
     status: number,
     body: ApiErrorBody["error"] | null,
-    opts: { requestId?: string; expected?: boolean; message?: string } = {},
+    opts: {
+      requestId?: string;
+      expected?: boolean;
+      message?: string;
+      retryAfterSecs?: number;
+    } = {},
   ) {
     super(opts.message ?? body?.message ?? `Request failed (${status})`);
     this.name = "ApiError";
@@ -43,10 +59,50 @@ export class ApiError extends Error {
     this.params = body?.params;
     this.details = body?.details;
     this.requestId = opts.requestId;
+    this.retryAfterSecs = opts.retryAfterSecs;
     this.expected = opts.expected ?? false;
   }
 }
 
+/**
+ * Seconds until a refusal clears, from whichever place the API put them.
+ *
+ * The header first, because it is the standard one and it is what a limiter emits without being
+ * asked; then `details.retryAfterSecs`, which one donor's API sends in the body instead. A
+ * caller asking "how long" should not have to know which server it is talking to.
+ */
+export function retryAfterSecs(error: ApiError): number | null {
+  if (error.retryAfterSecs !== undefined) return error.retryAfterSecs;
+  const details = error.details;
+  if (typeof details !== "object" || details === null) return null;
+  const value = (details as { retryAfterSecs?: unknown }).retryAfterSecs;
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * `Retry-After` in either spec form: delay-seconds, or an HTTP-date.
+ *
+ * Both forms are real — RFC 9110 allows either and different servers pick differently — and the
+ * date one is the half that gets skipped, which turns a stated wait into no wait at all. Clamped
+ * at zero: a date already in the past means "now", not a negative delay.
+ */
+export function parseRetryAfter(value: string | null | undefined): number | undefined {
+  const raw = value?.trim();
+  if (!raw) return undefined;
+
+  // A bare integer is the delay-seconds form, malformed included: `Date.parse` accepts some of
+  // them as years, so falling through would read "-5" as a date long past and answer 0 — a
+  // wait invented out of a header that never stated one.
+  if (/^[+-]?\d+$/.test(raw)) {
+    const secs = Number(raw);
+    return Number.isSafeInteger(secs) && secs >= 0 ? secs : undefined;
+  }
+
+  const at = Date.parse(raw);
+  if (Number.isNaN(at)) return undefined;
+  return Math.max(0, Math.round((at - Date.now()) / 1000));
+}
+
 /**
  * An aborted request — the caller's own `AbortController`, or a navigation that unmounted the
  * component waiting on it.

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { ApiError } from "./api-error.ts";
-import { createErrorDescriber, humanizeWait, retryAfterSecs } from "./describe-error.ts";
+import { createErrorDescriber, humanizeWait } from "./describe-error.ts";
 
 /** A translator that echoes the key, so a test can see exactly which one was asked for. */
 const t = (key: string, params?: Record<string, unknown>) =>
@@ -22,23 +22,6 @@ describe("humanizeWait", () => {
   });
 });
 
-describe("retryAfterSecs", () => {
-  it("reads the number out of details, and refuses anything else", () => {
-    expect(
-      retryAfterSecs(
-        new ApiError(429, { code: "X", message: "", details: { retryAfterSecs: 30 } }),
-      ),
-    ).toBe(30);
-    expect(
-      retryAfterSecs(
-        new ApiError(429, { code: "X", message: "", details: { retryAfterSecs: "30" } }),
-      ),
-    ).toBeNull();
-    expect(retryAfterSecs(new ApiError(429, { code: "X", message: "", details: null }))).toBeNull();
-    expect(retryAfterSecs(new ApiError(429, null))).toBeNull();
-  });
-});
-
 describe("createErrorDescriber", () => {
   const describeError = createErrorDescriber({
     t,
@@ -102,3 +85,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

@@ -1,4 +1,4 @@
-import { ApiError } from "./api-error.ts";
+import { ApiError, retryAfterSecs } from "./api-error.ts";
 
 /**
  * Turning anything thrown into copy a person can act on.
@@ -75,14 +75,6 @@ type _TypedCatalogNeedsNoCast = Satisfied<
     : false
 >;
 
-/** Seconds until a refusal clears, when the envelope carries them. */
-export function retryAfterSecs(error: ApiError): number | null {
-  const details = error.details;
-  if (typeof details !== "object" || details === null) return null;
-  const value = (details as { retryAfterSecs?: unknown }).retryAfterSecs;
-  return typeof value === "number" && Number.isFinite(value) ? value : null;
-}
-
 /**
  * "in 4 minutes" / "in 2 hours" — a wait nobody has to convert from seconds.
  *
@@ -121,6 +113,12 @@ export interface ErrorDescriberOptions<
   /**
    * 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;
   /**
@@ -168,10 +166,18 @@ export function createErrorDescriber<
   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(`${messageKeyPrefix}${name}`, 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 {

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";