@gears-frontx/react 0.2.0-alpha.0 → 0.2.0-alpha.15

package/CLAUDE.md

@@ -8,47 +8,44 @@ This package is part of the **React Layer (L3)** - it depends only on @gears-fro
 
 ## Core Concepts
 
-### Gears FrontXProvider
+### FrontXProvider
 
-Wrap your app with Gears FrontXProvider to enable all hooks:
+Wrap your app with FrontXProvider to enable all hooks. A runtime builds exactly one app, once at module level; the provider never creates one. The three compositions below are alternatives: choose one per runtime.
 
 ```tsx
-import { Gears FrontXProvider } from '@gears-frontx/react';
+import { createFrontX, FrontXProvider, presets } from '@gears-frontx/react';
+
+// Alternative 1: the full preset
+const app = createFrontX({ devMode: true }).useAll(presets.full()).build();
 
 function App() {
   return (
-    <Gears FrontXProvider>
+    <FrontXProvider app={app}>
       <YourApp />
-    </Gears FrontXProvider>
+    </FrontXProvider>
   );
 }
 
-// With configuration
-<Gears FrontXProvider config={{ devMode: true }}>
-  <YourApp />
-</Gears FrontXProvider>
-
-// With pre-built app (host-style shell; host typically also uses queryCache() — see REACT.md)
-const app = createGears FrontX().use(screensets()).build();
-<Gears FrontXProvider app={app}>
-  <YourApp />
-</Gears FrontXProvider>
-
-// Child MFE app — canonical bootstrap matches src/mfe_packages/*/init.ts and .ai/targets/SCREENSETS.md:
-// apiRegistry.register / initialize before .build; createGears FrontX().use(effects()).use(queryCacheShared()).use(mock()).build();
-// registerSlice after .build when slices exist.
-const mfeApp = createGears FrontX().use(effects()).use(queryCacheShared()).use(mock()).build();
-<Gears FrontXProvider app={mfeApp}>
-  <YourApp />
-</Gears FrontXProvider>
+```
+
+Alternative 2: a host shell with a custom plugin set (a host typically uses `queryCache()`):
+
+```tsx
+const app = createFrontX().use(effects()).use(queryCache()).build();
+```
+
+Alternative 3: a child MFE app. The canonical bootstrap matches `src/mfe_packages/*/init.ts`: `apiRegistry.register` / `initialize` before `.build()`, `registerSlice` after `.build()` when slices exist:
+
+```tsx
+const app = createFrontX().use(effects()).use(queryCacheShared()).use(mock()).build();
 ```
 
 The shared `QueryClient` is created and owned by the `queryCache()` framework plugin at L2.
-`Gears FrontXProvider` resolves that client from the app instance — it does not create its own `QueryClient`.
+`FrontXProvider` resolves that client from the app instance — it does not create its own `QueryClient`.
 
-When the host uses `queryCache()` and the child MFE app uses `queryCacheShared()` (with `effects()` and `mock()` on the same chain as in repo MFE inits), both roots join the same shared `QueryClient` while keeping separate React trees. `ThemeAwareReactLifecycle` relies on that shared plugin-owned client through the app instance. If the shared client is missing for a mounted MFE, the lifecycle now fails explicitly instead of silently falling back.
+When the host uses `queryCache()` and the child MFE app uses `queryCacheShared()` (with `effects()` and `mock()` on the same chain as in repo MFE inits), both roots join the same shared `QueryClient` while keeping separate React trees. `ThemeAwareReactLifecycle` relies on that shared plugin-owned client through the app instance. If the shared client is missing for a mounted MFE, the lifecycle fails explicitly instead of silently falling back.
 
-For separate roots, build each app with the appropriate query-cache plugin (`queryCache()` for the host, `queryCacheShared()` for child MFE shells) so every tree joins the same cache through plugin composition. MFE package ordering and forbidden bootstrap pieces are defined in SCREENSETS.md. Host apps should register domains/extensions during bootstrap; **`ExtensionDomainSlot`** is the preferred host-side renderer for screen slots while the framework wires `mount_ext`.
+For separate roots, build each app with the appropriate query-cache plugin (`queryCache()` for the host, `queryCacheShared()` for child MFE shells) so every tree joins the same cache through plugin composition. Host apps should register domains/extensions during bootstrap; **`ExtensionDomainSlot`** is the preferred host-side renderer for screen slots while the framework wires `mount_ext`.
 
 ### Data Fetching with Endpoint Descriptors
 
@@ -58,7 +55,7 @@ Services define endpoints as descriptors. Components consume them via `useApiQue
 import { useApiQuery, useApiMutation, apiRegistry } from '@gears-frontx/react';
 import { AccountsApiService } from '../api/AccountsApiService';
 
-function ProfileScreen() {
+function ProfileScreen({ teamId }: { teamId?: string }) {
   const service = apiRegistry.getService(AccountsApiService);
 
   // Read — pass descriptor directly
@@ -90,15 +87,23 @@ function ProfileScreen() {
 
   // Per-endpoint cache override (rare)
   const { data: config } = useApiQuery(service.getConfig, { staleTime: 0 });
+
+  // Conditional query: stays idle until enabled (not on the suspense hooks).
+  // The hook still needs a descriptor on every render, so one is built with a
+  // stand-in id; while enabled is false it is not fetched automatically, and
+  // refetch would still fetch it, so do not call refetch before teamId is set.
+  const { data: team } = useApiQuery(service.getTeam({ id: teamId ?? '' }), { enabled: Boolean(teamId) });
 }
 ```
 
 Cache keys are derived automatically by the service — `QueryCache` methods accept
 endpoint descriptors directly (e.g., `queryCache.get(service.getCurrentUser)`).
 
+The `queryCache` a mutation callback receives is bound to the cache scope (mock mode, tenant, session) the mutation started under: once that scope changes, its writes (`set`, `remove`, `invalidate`, `invalidateMany`, `cancel`) do nothing and reads still work, so a response or snapshot from the old scope never lands in the new cache. Nothing else is scope-bound: a `useQueryCache()` handle, the raw `QueryClient`, `cache/*` eventBus emits and per-call `mutate(vars, { onSuccess })` options write to whatever scope is current, so a write after an `await` or inside a mutation callback must go through the callback's `queryCache`.
+
 ### SSE Streaming with Stream Descriptors
 
-Services declare SSE endpoints as stream descriptors. Components consume them via `useApiStream`, which manages the EventSource lifecycle automatically (connect on mount, disconnect on unmount).
+Services declare SSE endpoints as stream descriptors. Components consume them via `useApiStream`, which manages the connection lifecycle automatically (connect on mount, disconnect on unmount).
 
 ```tsx
 import { useApiStream, apiRegistry } from '@gears-frontx/react';
@@ -124,18 +129,38 @@ function ChatStream() {
   );
 
   if (status === 'connecting') return <Loading />;
-  if (error) return <Error error={error} />;
+  if (status === 'error') return <Error error={error} />;
 
   return <div>{data?.text}</div>;
 }
 ```
 
 `useApiStream` returns `{ data, events, status, error, disconnect }`:
-- `data` — latest event payload (always set in both modes)
+- `data` — latest event payload (set in both modes)
 - `events` — all received events when `mode: 'accumulate'`; empty array in `'latest'` mode
-- `status` — `'idle' | 'connecting' | 'connected' | 'disconnected' | 'error'`
-- `error` — connection error if any
-- `disconnect()` — manually close the connection
+- `status` — connection lifecycle state, `StreamStatus` (see below)
+- `error` — the last connect attempt's error; retained until the next connect attempt resets it, so check `status` rather than `error` truthiness
+- `disconnect()` — close the connection manually
+
+#### Status lifecycle
+
+`status` is a `StreamStatus`: `'idle' | 'connecting' | 'connected' | 'disconnected' | 'error'`.
+
+The TSDoc block on `useApiStream` in `src/hooks/useApiStream.ts` is the detailed and authoritative state-machine reference, including teardown edge cases. This guide summarizes consumer-facing usage and gating.
+
+`disconnect()` closes the connection and does not reconnect. There is no reconnect function: to open a new connection, change the descriptor key, change `mode`, or toggle `enabled` back to true.
+
+#### The `enabled` option
+
+`enabled` (default `true`) gates whether the hook connects at all. While it is false the hook never calls the descriptor's `connect()` and ordinarily holds `status: 'idle'` (calling `disconnect()` while disabled is the one exception — see the TSDoc). Flipping it to true re-runs the connect effect and starts a fresh connection; flipping it back to false tears the connection down and returns `status` to `'idle'`.
+
+Tearing down via `enabled` does not clear `data` or `events` — a descriptor-key or `mode` change, or re-enabling, does. A component reading `data` while the stream is disabled still sees the last event from the previous connection.
+
+Gating advice, since `'idle'` covers both "not started yet" and "deferred by `enabled`":
+
+- Gate the loading state on `'connecting'` alone. Treating `'idle'` as loading renders a permanent spinner for a stream deliberately held at `enabled: false`.
+- Handle `'idle'` as "not started / deferred". A component that both defers and shows loading should key its spinner off its own active flag, not off `'idle'`.
+- Check `status === 'error'` rather than the truthiness of `error` to render failures.
 
 ### Available Hooks
 
@@ -150,11 +175,13 @@ function MyComponent() {
   const app = useFrontX();
 
   // Access MFE-enabled registry
-  const extensions = app.screensetsRegistry.getRegisteredExtensions();
+  const extensions = app.mfeRegistry.getExtensionsForDomain('screen');
 
-  // Access MFE actions
-  await app.actions.loadExtension({ extensionId: 'home' });
-  await app.actions.mountExtension({ extensionId: 'home', domainId: 'screen', container });
+  // Access MFE actions — fire-and-forget: each dispatches an actions chain
+  // through the acceptance-only registry surface and returns nothing to
+  // await.
+  app.actions.loadExtension('home');
+  app.actions.mountExtension('home');
 }
 ```
 
@@ -240,47 +267,78 @@ Access the MFE bridge for child MFEs:
 
 ```tsx
 import { useMfeBridge } from '@gears-frontx/react';
-import { Gears FrontX_ACTION_LOAD_EXT, Gears FrontX_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
+import { FRONTX_ACTION_LOAD_EXT, FRONTX_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
 
 function MyExtension() {
   const bridge = useMfeBridge();
 
-  // Execute actions chain on parent
-  await bridge.executeActionsChain({
-    action: { type: Gears FrontX_ACTION_LOAD_EXT, target: 'screen', payload: { extensionId: 'other' } }
-  });
+  const handleLoad = () => {
+    // executeActionsChain is acceptance-only: it returns void, never
+    // throws, and never yields anything to await for the chain's own
+    // execution.
+    bridge.executeActionsChain({
+      action: { type: FRONTX_ACTION_LOAD_EXT, target: 'screen', payload: { subject: 'other' } }
+    });
+  };
 
   // Get shared property
-  const theme = bridge.getProperty(Gears FrontX_SHARED_PROPERTY_THEME);
+  const theme = bridge.getProperty(FRONTX_SHARED_PROPERTY_THEME);
 }
 ```
 
 #### useSharedProperty
 
-Subscribe to shared property changes:
+Subscribe to shared property changes. Two forms: the context form reads the bridge from `MfeContext`, and the options form accepts an explicit bridge and a fallback.
+
+**Context form** — `useSharedProperty(propertyTypeId)`. Reads the bridge from `MfeContext` and throws if no `MfeProvider` is mounted. Returns the value (or `undefined` if the host has not published it), updating on every host publish.
 
 ```tsx
-import { useSharedProperty, Gears FrontX_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
+import { useSharedProperty, FRONTX_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
 
 function ThemedComponent() {
-  const theme = useSharedProperty(Gears FrontX_SHARED_PROPERTY_THEME);
+  const theme = useSharedProperty(FRONTX_SHARED_PROPERTY_THEME);
 
   return <div style={{ backgroundColor: theme?.primaryColor }}>...</div>;
 }
 ```
 
+**Options form** — `useSharedProperty(propertyTypeId, { bridge, fallback })`. Use it for components that never mount `MfeProvider`, or to show a value until the host publishes one.
+
+```tsx
+import { useSharedProperty } from '@gears-frontx/react';
+import type { ChildMfeBridge } from '@gears-frontx/framework';
+
+function StandaloneComponent({ bridge }: { bridge: ChildMfeBridge }) {
+  const label = useSharedProperty<string>(LABEL_PROPERTY_ID, {
+    bridge,
+    fallback: 'Untitled',
+  });
+
+  return <span>{label}</span>;
+}
+```
+
+`UseSharedPropertyOptions<T>` fields:
+
+- `bridge` — bridge to read the property from, bypassing `MfeContext`. Pass it when the calling component never mounts `MfeProvider` (for example, a component that receives its bridge as a prop or from a non-React entry point). When omitted, the hook falls back to the bridge from `MfeContext` and throws if no `MfeProvider` is mounted. Changing `bridge` or `propertyTypeId` moves the subscription to the new source and the returned value follows on the same render.
+- `fallback` — value returned while the host has not published the property yet. Only `undefined` is substituted; a published `null` is a real value and comes through as-is. With `fallback` set the hook returns `T` rather than `T | undefined`. It may be passed inline on every render without affecting the subscription.
+
+There is no consumer-side validation option on purpose: the host validates every published value against the property's schema before it reaches any MFE (`TypeSystemPlugin.register()` throws on a mismatch and the update is never stored or delivered). `T` is the caller's declaration of that schema, as with `useState<T>`.
+
+Both forms read through `useSyncExternalStore`, so the first render shows the host's current value and the result is tearing-protected under concurrent rendering. The TSDoc block on `useSharedProperty` in `src/mfe/hooks/useSharedProperty.ts` is the authoritative reference; this guide summarizes consumer-facing usage.
+
 #### useHostAction
 
 Invoke actions on the host application:
 
 ```tsx
-import { useHostAction, Gears FrontX_ACTION_LOAD_EXT } from '@gears-frontx/react';
+import { useHostAction, FRONTX_ACTION_LOAD_EXT } from '@gears-frontx/react';
 
 function MyExtension() {
-  const loadExtension = useHostAction(Gears FrontX_ACTION_LOAD_EXT);
+  const loadExtension = useHostAction(FRONTX_ACTION_LOAD_EXT);
 
   const handleClick = () => {
-    loadExtension({ extensionId: 'other' });
+    loadExtension({ subject: 'other' });
   };
 
   return <button onClick={handleClick}>Load Extension</button>;
@@ -414,7 +472,7 @@ function Layout() {
 
 ## Key Rules
 
-1. **Wrap with Gears FrontXProvider** - Required for all hooks to work
+1. **Wrap with FrontXProvider** - Required for all hooks to work
 2. **Use hooks for state access** - Don't import selectors directly from @gears-frontx/framework
 3. **Use endpoint descriptors for data** - `useApiQuery(service.endpoint)` for REST, `useApiStream(service.stream)` for SSE — not `queryOptions()` or manual key factories
 4. **Service is the cache contract** - The service IS the data layer; cache keys are derived automatically
@@ -438,7 +496,7 @@ This allows users to import everything from `@gears-frontx/react` without needin
 ## Exports
 
 ### Components
-- `Gears FrontXProvider` - Main context provider
+- `FrontXProvider` - Main context provider
 - `MfeProvider` - MFE context provider
 - `ExtensionDomainSlot` - Domain slot renderer
 - `RefContainerProvider` - Container reference provider
@@ -455,18 +513,18 @@ This allows users to import everything from `@gears-frontx/react` without needin
 - `useScreenTranslations` - Screen translation loading
 - `useTheme` - Theme utilities
 - `useMfeBridge` - Access MFE bridge
-- `useSharedProperty` - Subscribe to shared property
+- `useSharedProperty` - Subscribe to shared property, via `MfeContext` or an explicit bridge
 - `useHostAction` - Invoke host action
 - `useDomainExtensions` - Subscribe to domain extensions
 - `useRegisteredPackages` - Subscribe to registered GTS packages
 - `useActivePackage` - Subscribe to active GTS package
 
 ### Context
-- `Gears FrontXContext` - React context (for advanced use)
+- `FrontXContext` - React context (for advanced use)
 - `MfeContext` - MFE context (for advanced use)
 
 ### Types
-- `Gears FrontXProviderProps`
+- `FrontXProviderProps`
 - `ApiQueryResult<TData>` - Gears FrontX-owned query result type (data, error, isLoading, refetch, etc.)
 - `ApiMutationResult<TData>` - Gears FrontX-owned mutation result type (mutateAsync, isPending, error, reset, etc.)
 - `ApiStreamResult<TEvent>` - Gears FrontX-owned stream result type (data, events, status, error, disconnect)
@@ -474,6 +532,7 @@ This allows users to import everything from `@gears-frontx/react` without needin
 - `QueryCache` - Restricted cache interface (accepts descriptors or raw keys)
 - `MutationCallbackContext` - Context with queryCache injected into mutation callbacks
 - `MfeProviderProps`, `ExtensionDomainSlotProps`
+- `UseSharedPropertyOptions<T>` - Options for `useSharedProperty` (bridge, fallback)
 - `UseTranslationReturn`, `UseThemeReturn`
 - All types from @gears-frontx/framework (including `EndpointDescriptor`, `MutationDescriptor`, `StreamDescriptor`, `StreamStatus`)
 
@@ -509,13 +568,11 @@ function MyComponent() {
   const app = useFrontX();
   const containerRef = useRef<HTMLDivElement>(null);
 
-  const handleNavigate = async () => {
+  const handleNavigate = () => {
     if (containerRef.current) {
-      await app.actions.mountExtension({
-        extensionId: 'home',
-        domainId: 'screen',
-        container: containerRef.current,
-      });
+      // Fire-and-forget: dispatches an actions chain through the
+      // acceptance-only registry surface and returns nothing to await.
+      app.actions.mountExtension('home');
     }
   };
 
@@ -535,7 +592,7 @@ import { ExtensionDomainSlot } from '@gears-frontx/react';
 function MyComponent() {
   return (
     <ExtensionDomainSlot
-      registry={app.screensetsRegistry}
+      registry={app.mfeRegistry}
       domainId="screen"
       extensionId="home"
       loadingComponent={<Loading />}