@gusnips/react 0.3.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

@@ -64,6 +64,12 @@ export interface ErrorDescriberOptions<Prefix extends string, ServerPrefix exten
     /**
      * 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;
     /**

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;;;;;;;;;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;;;OAGG;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,CA0C9F"}
+{"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

@@ -30,11 +30,17 @@ export function createErrorDescriber({ t, copyPrefix, messageKeyPrefix, knownMes
     // `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(`${messageKeyPrefix}${name}`, 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)) {

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

@@ -6,7 +6,7 @@ export { queryDefaults, shouldRetry, type QueryDefaultsOptions } from "./query.t
 export { ErrorBoundary, type ErrorBoundaryFallbackProps, type ErrorBoundaryProps, } from "./error-boundary.tsx";
 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,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;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,GAMf,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.3.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

@@ -102,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

@@ -121,6 +121,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 +174,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";

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";
 
@@ -57,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";