@molecule/app-bonds-default-react 1.1.0 → 1.1.2

package/README.md

@@ -3,15 +3,11 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-16T08:11:11.584Z
+Generated: 2026-10-16T23:54:35.164Z
 -->
 
 # @molecule/app-bonds-default-react
 
-> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
-> It is written to be read by coding agents as much as by people, and is generated from this
-> package's source — edit `src/index.ts` JSDoc, not this file.
-
 `@molecule/app-bonds-default-react` — default app-side bond wirings for the
 React fleet stack, replacing the byte-identical per-app files:
 
@@ -39,6 +35,10 @@ React fleet stack, replacing the byte-identical per-app files:
   `...WithFetchClient` variants also keep the bonded http client's bearer
   token in sync with auth events.
 
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
 ## Quick Start
 
 ```tsx
@@ -105,7 +105,11 @@ stripping a leading `/api/` from request URLs.
 Replaces ~20 per-app `bonds/http-default.ts` files that hand-roll
 this same wiring. Pass `stripApiPrefix: true` when the app uses
 `baseURL: '/api'` to handle pages that pass `/api/`-prefixed paths
-(would otherwise resolve to `/api/api/...` and 404).
+(would otherwise resolve to `/api/api/...` and 404). Pass `authScheme`
+when the API reads another scheme than `Bearer`: it is an option of THIS
+constructor (`createDefaultHttpClientWithAuthBearer({ authScheme: 'Token', … })`,
+or `createFetchClient({ baseURL, authScheme: 'Token' })` directly), never a
+property of the client it returns.
 
 ```typescript
 function createDefaultHttpClientWithAuthBearer(opts: {
@@ -113,6 +117,7 @@ function createDefaultHttpClientWithAuthBearer(opts: {
   withCredentials?: boolean
   stripApiPrefix?: boolean
   getToken: () => string | null | undefined
+  authScheme?: string
 }): { httpClient: HttpClient; setupHttpDefault: () => void }
 ```
 
@@ -140,7 +145,9 @@ client must carry the JWT on every request — without this wiring,
 authed endpoints return 401 after page reloads or token refresh.
 
 Hydrates the HTTP client's token from the persisted auth state
-on setup, then listens for auth events to keep them aligned.
+on setup, then listens for auth events to keep them aligned, and holds
+requests until the session restore settles so a page effect that fetches
+viewer-dependent data on mount cannot race it (see {@link registerAuthGate}).
 
 ```typescript
 function createDefaultAuthClientWithHttpSync(authConfig: AuthClientConfig): {
@@ -159,6 +166,10 @@ its bearer token in sync with auth events.
 Used by apps where molecule packages render pricing / billing /
 other authed JSON-fetching screens that need both behaviors.
 
+Requests are also held until the session restore settles (see
+{@link registerAuthGate}), so a page that fetches viewer-dependent data on
+mount cannot race it and answer for an anonymous viewer.
+
 ```typescript
 function createDefaultAuthClientWithFetchClient(
   authConfig: AuthClientConfig,

package/dist/auth.d.ts

@@ -26,13 +26,25 @@ export declare function createDefaultHttpClient(baseURL: string): {
  * Replaces ~20 per-app `bonds/http-default.ts` files that hand-roll
  * this same wiring. Pass `stripApiPrefix: true` when the app uses
  * `baseURL: '/api'` to handle pages that pass `/api/`-prefixed paths
- * (would otherwise resolve to `/api/api/...` and 404).
+ * (would otherwise resolve to `/api/api/...` and 404). Pass `authScheme`
+ * when the API reads another scheme than `Bearer`: it is an option of THIS
+ * constructor (`createDefaultHttpClientWithAuthBearer({ authScheme: 'Token', … })`,
+ * or `createFetchClient({ baseURL, authScheme: 'Token' })` directly), never a
+ * property of the client it returns.
  */
 export declare function createDefaultHttpClientWithAuthBearer(opts: {
     baseURL: string;
     withCredentials?: boolean;
     stripApiPrefix?: boolean;
     getToken: () => string | null | undefined;
+    /**
+     * The scheme of the `Authorization` header the token from `getToken()` is sent
+     * with: `Bearer` (default), or what the API expects, e.g. `Token` for an API
+     * that reads `Authorization: Token <jwt>`. Pass it to this constructor — the
+     * same option `@molecule/app-http`'s client config calls `authScheme`, and not
+     * a property of the client that comes back.
+     */
+    authScheme?: string;
 }): {
     httpClient: HttpClient;
     setupHttpDefault: () => void;
@@ -66,7 +78,9 @@ export declare function createDefaultAuthClient<TUser extends UserProfile = User
  * authed endpoints return 401 after page reloads or token refresh.
  *
  * Hydrates the HTTP client's token from the persisted auth state
- * on setup, then listens for auth events to keep them aligned.
+ * on setup, then listens for auth events to keep them aligned, and holds
+ * requests until the session restore settles so a page effect that fetches
+ * viewer-dependent data on mount cannot race it (see {@link registerAuthGate}).
  */
 export declare function createDefaultAuthClientWithHttpSync<TUser extends UserProfile = UserProfile>(authConfig: AuthClientConfig): {
     authClient: AuthClient<TUser>;
@@ -80,6 +94,10 @@ export declare function createDefaultAuthClientWithHttpSync<TUser extends UserPr
  *
  * Used by apps where molecule packages render pricing / billing /
  * other authed JSON-fetching screens that need both behaviors.
+ *
+ * Requests are also held until the session restore settles (see
+ * {@link registerAuthGate}), so a page that fetches viewer-dependent data on
+ * mount cannot race it and answer for an anonymous viewer.
  */
 export declare function createDefaultAuthClientWithFetchClient<TUser extends UserProfile = UserProfile>(authConfig: AuthClientConfig, fetchClientOptions: {
     baseURL: string;

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAEnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAOpD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG;IACxD,UAAU,EAAE,UAAU,CAAA;IACtB,gBAAgB,EAAE,MAAM,IAAI,CAAA;CAC7B,CAMA;AAED;;;;;;;;;GASG;AACH,wBAAgB,qCAAqC,CAAC,IAAI,EAAE;IAC1D,OAAO,EAAE,MAAM,CAAA;IACf,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,QAAQ,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAC1C,GAAG;IACF,UAAU,EAAE,UAAU,CAAA;IACtB,gBAAgB,EAAE,MAAM,IAAI,CAAA;CAC7B,CAmBA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,SAAS,WAAW,GAAG,WAAW,EAC7E,UAAU,EAAE,gBAAgB,GAC3B;IACD,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,CAAA;IAC7B,gBAAgB,EAAE,MAAM,IAAI,CAAA;CAC7B,CAMA;AAED;;;;;;;;;GASG;AACH,wBAAgB,mCAAmC,CAAC,KAAK,SAAS,WAAW,GAAG,WAAW,EACzF,UAAU,EAAE,gBAAgB,GAC3B;IACD,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,CAAA;IAC7B,gBAAgB,EAAE,MAAM,IAAI,CAAA;CAC7B,CAwBA;AAED;;;;;;;;GAQG;AACH,wBAAgB,sCAAsC,CAAC,KAAK,SAAS,WAAW,GAAG,WAAW,EAC5F,UAAU,EAAE,gBAAgB,EAC5B,kBAAkB,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,GACjE;IACD,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,CAAA;IAC7B,gBAAgB,EAAE,MAAM,IAAI,CAAA;CAC7B,CA0BA"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAEnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAsCpD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG;IACxD,UAAU,EAAE,UAAU,CAAA;IACtB,gBAAgB,EAAE,MAAM,IAAI,CAAA;CAC7B,CAMA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qCAAqC,CAAC,IAAI,EAAE;IAC1D,OAAO,EAAE,MAAM,CAAA;IACf,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,QAAQ,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;IACzC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,GAAG;IACF,UAAU,EAAE,UAAU,CAAA;IACtB,gBAAgB,EAAE,MAAM,IAAI,CAAA;CAC7B,CAoBA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,SAAS,WAAW,GAAG,WAAW,EAC7E,UAAU,EAAE,gBAAgB,GAC3B;IACD,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,CAAA;IAC7B,gBAAgB,EAAE,MAAM,IAAI,CAAA;CAC7B,CAMA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mCAAmC,CAAC,KAAK,SAAS,WAAW,GAAG,WAAW,EACzF,UAAU,EAAE,gBAAgB,GAC3B;IACD,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,CAAA;IAC7B,gBAAgB,EAAE,MAAM,IAAI,CAAA;CAC7B,CA2BA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sCAAsC,CAAC,KAAK,SAAS,WAAW,GAAG,WAAW,EAC5F,UAAU,EAAE,gBAAgB,EAC5B,kBAAkB,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,GACjE;IACD,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,CAAA;IAC7B,gBAAgB,EAAE,MAAM,IAAI,CAAA;CAC7B,CA2BA"}

package/dist/auth.js

@@ -1,5 +1,34 @@
 import { createJWTAuthClient, setClient } from '@molecule/app-auth';
-import { createFetchClient, getClient as getHttpClient, setClient as setHttpClient, } from '@molecule/app-http';
+import { createFetchClient, getClient as getHttpClient, setAuthGate, setClient as setHttpClient, } from '@molecule/app-http';
+/**
+ * Holds every HTTP request until this auth client's session restore has settled.
+ *
+ * Without it a page effect that fires on mount (fetching a profile's `following`
+ * flag, a feed, a `favorited` state) sends its request before `initialize()` has
+ * restored the session, so it leaves with no `Authorization` header and the server
+ * answers for an anonymous viewer. Localhost usually hides it — the restore wins
+ * the race against the first effect there — and the deployed URL exposes it, which
+ * is how X1 xr-molecule-flash-m95 spent ~25 min treating a "Follow" button on a
+ * followed user as database leftovers.
+ *
+ * `whenRestored()` resolves immediately when no restore is in flight, so a request
+ * made after boot never waits at all; it holds only while the restore is actually
+ * running. A provider without `whenRestored` (a bond that restores nothing) leaves
+ * requests ungated.
+ *
+ * The restore this gate waits for does NOT go through the gated client — both default auth
+ * bonds' `createJWTAuthClient` restores with `fetch` — so the scaffold's own wiring cannot
+ * deadlock. An app that registers its own gate over a restore made through the bonded client
+ * must exempt that request with `skipAuthGate: true`
+ * (`setAuthGate(() => store.whenSettled())` + `http.get(currentUserEndpoint, { skipAuthGate: true })`
+ * in the store); otherwise the gate holds the request it is waiting for and every request it
+ * holds stalls until the gate times out. See `RequestConfig.skipAuthGate` in `@molecule/app-http`.
+ *
+ * @param authClient - The bonded auth client.
+ */
+function registerAuthGate(authClient) {
+    setAuthGate(() => authClient.whenRestored?.() ?? Promise.resolve());
+}
 /**
  * Builds the default fetch-based HTTP client + wires it into
  * `@molecule/app-http`. Replaces the per-app `bonds/http-default.ts`
@@ -29,9 +58,14 @@ export function createDefaultHttpClient(baseURL) {
  * Replaces ~20 per-app `bonds/http-default.ts` files that hand-roll
  * this same wiring. Pass `stripApiPrefix: true` when the app uses
  * `baseURL: '/api'` to handle pages that pass `/api/`-prefixed paths
- * (would otherwise resolve to `/api/api/...` and 404).
+ * (would otherwise resolve to `/api/api/...` and 404). Pass `authScheme`
+ * when the API reads another scheme than `Bearer`: it is an option of THIS
+ * constructor (`createDefaultHttpClientWithAuthBearer({ authScheme: 'Token', … })`,
+ * or `createFetchClient({ baseURL, authScheme: 'Token' })` directly), never a
+ * property of the client it returns.
  */
 export function createDefaultHttpClientWithAuthBearer(opts) {
+    const authScheme = opts.authScheme ?? 'Bearer';
     const httpClient = createFetchClient({
         baseURL: opts.baseURL,
         withCredentials: opts.withCredentials,
@@ -42,7 +76,7 @@ export function createDefaultHttpClientWithAuthBearer(opts) {
         }
         const token = opts.getToken();
         if (token) {
-            config.headers = { ...config.headers, Authorization: `Bearer ${token}` };
+            config.headers = { ...config.headers, Authorization: `${authScheme} ${token}` };
         }
         return config;
     });
@@ -83,7 +117,9 @@ export function createDefaultAuthClient(authConfig) {
  * authed endpoints return 401 after page reloads or token refresh.
  *
  * Hydrates the HTTP client's token from the persisted auth state
- * on setup, then listens for auth events to keep them aligned.
+ * on setup, then listens for auth events to keep them aligned, and holds
+ * requests until the session restore settles so a page effect that fetches
+ * viewer-dependent data on mount cannot race it (see {@link registerAuthGate}).
  */
 export function createDefaultAuthClientWithHttpSync(authConfig) {
     const authClient = createJWTAuthClient(authConfig);
@@ -91,6 +127,9 @@ export function createDefaultAuthClientWithHttpSync(authConfig) {
         authClient,
         setupAuthDefault: () => {
             setClient(authClient);
+            // Requests made while the session is still restoring wait for it, so a page
+            // effect that fetches viewer-dependent data on mount cannot race the restore.
+            registerAuthGate(authClient);
             const initialToken = authClient.getAccessToken();
             if (initialToken) {
                 getHttpClient().setAuthToken(initialToken);
@@ -119,6 +158,10 @@ export function createDefaultAuthClientWithHttpSync(authConfig) {
  *
  * Used by apps where molecule packages render pricing / billing /
  * other authed JSON-fetching screens that need both behaviors.
+ *
+ * Requests are also held until the session restore settles (see
+ * {@link registerAuthGate}), so a page that fetches viewer-dependent data on
+ * mount cannot race it and answer for an anonymous viewer.
  */
 export function createDefaultAuthClientWithFetchClient(authConfig, fetchClientOptions) {
     const authClient = createJWTAuthClient(authConfig);
@@ -131,6 +174,7 @@ export function createDefaultAuthClientWithFetchClient(authConfig, fetchClientOp
             });
             setHttpClient(httpClient);
             setClient(authClient);
+            registerAuthGate(authClient);
             const initialToken = authClient.getAccessToken();
             if (initialToken) {
                 httpClient.setAuthToken(initialToken);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-bonds-default-react",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Default app-side bond wirings for React+Tailwind+react-router+localStorage+Arimo font+molecule icons. 5 setup functions consolidating 665 byte-identical per-app bond wiring files across the fleet.",
   "homepage": "https://www.molecule.dev/packages/app-bonds-default-react",
   "type": "module",
@@ -38,7 +38,7 @@
     "directory": "packages/app/infrastructure/bonds-default-react"
   },
   "devDependencies": {
-    "@molecule/app-auth": "1.2.1",
+    "@molecule/app-auth": "1.3.0",
     "@molecule/app-charts-chartjs": "1.0.2",
     "@molecule/app-client-search": "1.0.2",
     "@molecule/app-client-search-minisearch": "1.0.3",
@@ -50,7 +50,7 @@
     "@molecule/app-drag-drop-dndkit": "1.0.2",
     "@molecule/app-fonts": "1.1.0",
     "@molecule/app-fonts-arimo": "1.0.2",
-    "@molecule/app-http": "1.1.1",
+    "@molecule/app-http": "1.1.3",
     "@molecule/app-icons": "1.0.2",
     "@molecule/app-icons-molecule": "1.0.2",
     "@molecule/app-keyboard-shortcuts": "1.0.2",