@molecule/app-react 1.6.4 → 1.6.5

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:00:14.834Z
+Generated: 2026-10-17T00:35:27.553Z
 -->
 
 # @molecule/app-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.
-
 React framework bindings for the Molecule app stack.
 
 Provides React hooks, contexts, and provider components for all molecule
@@ -19,6 +15,10 @@ core interfaces (auth, i18n, theme, routing, state, http, storage, logger,
 chat, workspace, editor, preview), so framework-agnostic providers plug
 into React idioms.
 
+> **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
@@ -188,6 +188,27 @@ interface AuthClient<T = UserProfile> {
    * Initializes auth state (e.g., from stored tokens).
    */
   initialize(): Promise<void>
+  /**
+   * Resolves when the session restore started by `initialize()` has settled — the point
+   * after which the client knows whether this visitor is signed in.
+   *
+   * Resolves IMMEDIATELY when no restore is in flight: before `initialize()` is ever
+   * called, and after it has finished. A restore that failed resolves too (it settled the
+   * question), so an HTTP client can await this before every request without risking one
+   * held forever. That is what makes the fetch-before-restore race impossible: a page that
+   * fetches viewer-dependent data on mount waits here instead of going out anonymously
+   * (see `setAuthGate` in `@molecule/app-http`).
+   *
+   * Optional: a provider that restores no session has nothing to wait for. Without it, an
+   * HTTP client bonded to that provider sends first-paint requests unauthenticated.
+   *
+   * A provider whose restore sends a request THROUGH the gated HTTP client must send that
+   * request with `skipAuthGate: true` (`RequestConfig` in `@molecule/app-http`): the gate
+   * waits on this promise, so holding the restore's own request makes the gate wait on
+   * itself and stalls every request it holds until it times out. `createJWTAuthClient`'s
+   * restore does not need it — it uses `fetch`, not the bonded client.
+   */
+  whenRestored?(): Promise<void>
   /**
    * Subscribes to auth state changes.
    */
@@ -2225,6 +2246,9 @@ The context comes from `<StateProvider provider={…}>` or from
 `<MoleculeProvider>` — which supplies the provider bonded under
 `@molecule/app-state` by default, so a scaffolded app needs no `state` prop.
 
+Only hooks that read the context call this; `useStore(store)` takes its store
+as an argument and works with no provider at all.
+
 ```typescript
 function useStateProvider(): StateProvider
 ```
@@ -2235,6 +2259,12 @@ function useStateProvider(): StateProvider
 
 Hook to subscribe to a store with optional selector and equality function.
 
+The store is the argument, so this hook needs NO `StateProvider`: it reads
+`store.getState()` and subscribes with `store.subscribe()`, and never touches
+the state context. A store minted outside the `state` bond — the direct
+`createStoreWithActions()` / `createStore()` a provider package exports — is
+therefore as valid here as one `@molecule/app-state`'s `createStore()` made.
+
 ```typescript
 function useStore(store: Store<T>, options?: UseStoreOptions<T, S>): S
 ```

package/dist/hooks/useStore.d.ts

@@ -12,13 +12,23 @@ import type { UseStoreOptions } from '../types.js';
  * `<MoleculeProvider>` — which supplies the provider bonded under
  * `@molecule/app-state` by default, so a scaffolded app needs no `state` prop.
  *
+ * Only hooks that read the context call this; `useStore(store)` takes its store
+ * as an argument and works with no provider at all.
+ *
  * @returns The state provider from context
- * @throws {Error} Error if used outside of StateProvider
+ * @throws {Error} when no `StateProvider` is above the component — the message
+ * names the fix (which provider to render, and the import for it).
  */
 export declare function useStateProvider(): StateProvider;
 /**
  * Hook to subscribe to a store with optional selector and equality function.
  *
+ * The store is the argument, so this hook needs NO `StateProvider`: it reads
+ * `store.getState()` and subscribes with `store.subscribe()`, and never touches
+ * the state context. A store minted outside the `state` bond — the direct
+ * `createStoreWithActions()` / `createStore()` a provider package exports — is
+ * therefore as valid here as one `@molecule/app-state`'s `createStore()` made.
+ *
  * @param store - The store to subscribe to
  * @param options - Hook options (selector, equalityFn)
  * @returns The selected state

package/dist/hooks/useStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useStore.d.ts","sourceRoot":"","sources":["../../src/hooks/useStore.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAG/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAUhD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAgCtF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAEpE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,SAAS,OAAO,EAAE,EAAE,CAAC,EACzD,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,MAAM,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,GAC/F,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,CAKtB"}
+{"version":3,"file":"useStore.d.ts","sourceRoot":"","sources":["../../src/hooks/useStore.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAG/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAkBlD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAUhD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CA6BtF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAEpE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,SAAS,OAAO,EAAE,EAAE,CAAC,EACzD,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,MAAM,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,GAC/F,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,CAKtB"}

package/dist/hooks/useStore.js

@@ -6,6 +6,20 @@
 import { useCallback, useContext, useRef, useSyncExternalStore } from 'react';
 import { t } from '@molecule/app-i18n';
 import { StateContext } from '../contexts.js';
+/**
+ * The fix, appended to the error below — this hook is the one place that READS
+ * the context, so it is the one place that has to say where the context comes
+ * from. The sentences are code (an import, a component, a bond call), so they
+ * are appended in English rather than translated.
+ */
+const STATE_CONTEXT_FIX = ' To fix: render a state provider above this component — ' +
+    "`import { MoleculeProvider, StateProvider } from '@molecule/app-react'`; " +
+    '<MoleculeProvider> passes the provider bonded under `@molecule/app-state` ' +
+    '(bond one with `setupAllDefaultBonds()` from `@molecule/app-bonds-default-react`, ' +
+    'or `setProvider(provider)` from `@molecule/app-state`), and ' +
+    '<StateProvider provider={provider}> passes one you hold. ' +
+    'To read a store you already have, call useStore(store) instead — it subscribes to the ' +
+    'store it is given and needs no provider.';
 /**
  * Hook to access the state provider from context.
  *
@@ -13,21 +27,31 @@ import { StateContext } from '../contexts.js';
  * `<MoleculeProvider>` — which supplies the provider bonded under
  * `@molecule/app-state` by default, so a scaffolded app needs no `state` prop.
  *
+ * Only hooks that read the context call this; `useStore(store)` takes its store
+ * as an argument and works with no provider at all.
+ *
  * @returns The state provider from context
- * @throws {Error} Error if used outside of StateProvider
+ * @throws {Error} when no `StateProvider` is above the component — the message
+ * names the fix (which provider to render, and the import for it).
  */
 export function useStateProvider() {
     const provider = useContext(StateContext);
     if (!provider) {
         throw new Error(t('react.error.useStoreOutsideProvider', undefined, {
             defaultValue: 'useStateProvider must be used within a StateProvider',
-        }));
+        }) + STATE_CONTEXT_FIX);
     }
     return provider;
 }
 /**
  * Hook to subscribe to a store with optional selector and equality function.
  *
+ * The store is the argument, so this hook needs NO `StateProvider`: it reads
+ * `store.getState()` and subscribes with `store.subscribe()`, and never touches
+ * the state context. A store minted outside the `state` bond — the direct
+ * `createStoreWithActions()` / `createStore()` a provider package exports — is
+ * therefore as valid here as one `@molecule/app-state`'s `createStore()` made.
+ *
  * @param store - The store to subscribe to
  * @param options - Hook options (selector, equalityFn)
  * @returns The selected state
@@ -39,8 +63,6 @@ export function useStateProvider() {
  * ```
  */
 export function useStore(store, options) {
-    // Validate that we're within a StateProvider
-    useStateProvider();
     const { selector, equalityFn } = options ?? {};
     // Use a ref to track the previous selected value for equality comparison
     const prevSelectedRef = useRef(undefined);

package/dist/hooks/useStore.js.map

@@ -1 +1 @@
-{"version":3,"file":"useStore.js","sourceRoot":"","sources":["../../src/hooks/useStore.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAA;AAE7E,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAGtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAG7C;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,QAAQ,GAAG,UAAU,CAAC,YAAY,CAAC,CAAA;IACzC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,CAAC,CAAC,qCAAqC,EAAE,SAAS,EAAE;YAClD,YAAY,EAAE,sDAAsD;SACrE,CAAC,CACH,CAAA;IACH,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,QAAQ,CAAW,KAAe,EAAE,OAA+B;IACjF,6CAA6C;IAC7C,gBAAgB,EAAE,CAAA;IAElB,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,OAAO,IAAI,EAAE,CAAA;IAE9C,yEAAyE;IACzE,MAAM,eAAe,GAAG,MAAM,CAAgB,SAAS,CAAC,CAAA;IAExD,MAAM,WAAW,GAAG,WAAW,CAAC,GAAG,EAAE;QACnC,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAA;QAC9B,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAsB,CAAA;QAErE,uEAAuE;QACvE,IAAI,UAAU,IAAI,eAAe,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YACxD,IAAI,UAAU,CAAC,eAAe,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,CAAC;gBAClD,OAAO,eAAe,CAAC,OAAO,CAAA;YAChC,CAAC;QACH,CAAC;QAED,eAAe,CAAC,OAAO,GAAG,QAAQ,CAAA;QAClC,OAAO,QAAQ,CAAA;IACjB,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAA;IAEjC,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,aAAyB,EAAE,EAAE;QAC5B,OAAO,KAAK,CAAC,SAAS,CAAC,aAAa,CAAC,CAAA;IACvC,CAAC,EACD,CAAC,KAAK,CAAC,CACR,CAAA;IAED,OAAO,oBAAoB,CAAC,SAAS,EAAE,WAAW,EAAE,WAAW,CAAC,CAAA;AAClE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAI,KAAe;IAC5C,OAAO,KAAK,CAAC,QAAQ,CAAA;AACvB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAe,EACf,MAAgG;IAEhG,OAAO,WAAW,CAChB,CAAC,GAAG,IAAU,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,CAAC,EAClE,CAAC,KAAK,EAAE,MAAM,CAAC,CAChB,CAAA;AACH,CAAC"}
+{"version":3,"file":"useStore.js","sourceRoot":"","sources":["../../src/hooks/useStore.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAA;AAE7E,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAGtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAG7C;;;;;GAKG;AACH,MAAM,iBAAiB,GACrB,0DAA0D;IAC1D,2EAA2E;IAC3E,4EAA4E;IAC5E,oFAAoF;IACpF,8DAA8D;IAC9D,2DAA2D;IAC3D,wFAAwF;IACxF,0CAA0C,CAAA;AAE5C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,QAAQ,GAAG,UAAU,CAAC,YAAY,CAAC,CAAA;IACzC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,CAAC,CAAC,qCAAqC,EAAE,SAAS,EAAE;YAClD,YAAY,EAAE,sDAAsD;SACrE,CAAC,GAAG,iBAAiB,CACvB,CAAA;IACH,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,QAAQ,CAAW,KAAe,EAAE,OAA+B;IACjF,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,OAAO,IAAI,EAAE,CAAA;IAE9C,yEAAyE;IACzE,MAAM,eAAe,GAAG,MAAM,CAAgB,SAAS,CAAC,CAAA;IAExD,MAAM,WAAW,GAAG,WAAW,CAAC,GAAG,EAAE;QACnC,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAA;QAC9B,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAsB,CAAA;QAErE,uEAAuE;QACvE,IAAI,UAAU,IAAI,eAAe,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YACxD,IAAI,UAAU,CAAC,eAAe,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,CAAC;gBAClD,OAAO,eAAe,CAAC,OAAO,CAAA;YAChC,CAAC;QACH,CAAC;QAED,eAAe,CAAC,OAAO,GAAG,QAAQ,CAAA;QAClC,OAAO,QAAQ,CAAA;IACjB,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAA;IAEjC,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,aAAyB,EAAE,EAAE;QAC5B,OAAO,KAAK,CAAC,SAAS,CAAC,aAAa,CAAC,CAAA;IACvC,CAAC,EACD,CAAC,KAAK,CAAC,CACR,CAAA;IAED,OAAO,oBAAoB,CAAC,SAAS,EAAE,WAAW,EAAE,WAAW,CAAC,CAAA;AAClE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAI,KAAe;IAC5C,OAAO,KAAK,CAAC,QAAQ,CAAA;AACvB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAe,EACf,MAAgG;IAEhG,OAAO,WAAW,CAChB,CAAC,GAAG,IAAU,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI,CAAC,EAClE,CAAC,KAAK,EAAE,MAAM,CAAC,CAChB,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-react",
-  "version": "1.6.4",
+  "version": "1.6.5",
   "description": "React framework bindings for molecule.dev",
   "type": "module",
   "main": "dist/index.js",
@@ -59,7 +59,7 @@
   },
   "devDependencies": {
     "@molecule/app-ai-models": "1.4.0",
-    "@molecule/app-bonds-default-react": "1.1.0",
+    "@molecule/app-bonds-default-react": "1.1.2",
     "@molecule/app-i18n": "1.0.3",
     "@testing-library/dom": "10.4.1",
     "@testing-library/react": "16.3.2",