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

package/dist/types-JtpziA_B.d.ts

@@ -0,0 +1,224 @@
+import * as React from 'react';
+import { ReactNode } from 'react';
+import { ChildMfeBridge, AccessRecord, AccessQuery, FrontXApp, RootState, Formatters, Language } from '@gears-frontx/framework';
+
+/**
+ * MFE Context Value
+ * Contains bridge and metadata about the MFE instance.
+ */
+interface MfeContextValue {
+    /** Child bridge for communication with host */
+    bridge: ChildMfeBridge;
+    /** Extension ID */
+    extensionId: string;
+    /** Domain ID where MFE is mounted */
+    domainId: string;
+}
+/**
+ * MFE Context
+ * Holds the MFE bridge and metadata for child components.
+ */
+declare const MfeContext: React.Context<MfeContextValue | null>;
+/**
+ * Use the MFE context.
+ * Throws if used outside of MFE context.
+ *
+ * @returns The MFE context value
+ */
+declare function useMfeContext(): MfeContextValue;
+
+/**
+ * @gears-frontx/react - Type Definitions
+ *
+ * Core types for FrontX React bindings.
+ * Provides type-safe hooks and components.
+ *
+ * Now using real imports from @gears-frontx/framework since packages are built together.
+ */
+
+/**
+ * Gears FrontX-owned query result type.
+ * Returned by useApiQuery — callers depend on this contract, not on TanStack internals.
+ */
+interface ApiQueryResult<TData, TError = Error> {
+    data: TData | undefined;
+    error: TError | null;
+    isLoading: boolean;
+    isFetching: boolean;
+    isError: boolean;
+    refetch: () => Promise<unknown>;
+}
+/**
+ * Gears FrontX-owned suspense query result type.
+ * Returned by useApiSuspenseQuery — callers depend on this contract, not on TanStack internals.
+ */
+interface ApiSuspenseQueryResult<TData, TError = Error> {
+    data: TData;
+    error: TError | null;
+    isFetching: boolean;
+    refetch: () => Promise<void>;
+}
+/**
+ * Gears FrontX-owned infinite query result type.
+ * Returned by useApiInfiniteQuery for descriptor-driven pagination.
+ */
+interface ApiInfiniteQueryResult<TPage, TError = Error> {
+    data: readonly TPage[] | undefined;
+    error: TError | null;
+    isLoading: boolean;
+    isFetching: boolean;
+    isError: boolean;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    isFetchingNextPage: boolean;
+    isFetchingPreviousPage: boolean;
+    fetchNextPage: () => Promise<void>;
+    fetchPreviousPage: () => Promise<void>;
+    refetch: () => Promise<void>;
+}
+/**
+ * Gears FrontX-owned suspense infinite query result type.
+ * Returned by useApiSuspenseInfiniteQuery for descriptor-driven pagination.
+ */
+interface ApiSuspenseInfiniteQueryResult<TPage, TError = Error> {
+    data: readonly TPage[];
+    error: TError | null;
+    isFetching: boolean;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    isFetchingNextPage: boolean;
+    isFetchingPreviousPage: boolean;
+    fetchNextPage: () => Promise<void>;
+    fetchPreviousPage: () => Promise<void>;
+    refetch: () => Promise<void>;
+}
+/**
+ * Gears FrontX-owned mutation result type.
+ * Returned by useApiMutation — callers depend on this contract, not on TanStack internals.
+ */
+interface ApiMutationResult<TData, TError = Error, TVariables = void> {
+    mutate: (variables: TVariables) => void;
+    mutateAsync: (variables: TVariables) => Promise<TData>;
+    isPending: boolean;
+    error: TError | null;
+    data: TData | undefined;
+    reset: () => void;
+}
+type Selector<TResult, TState = RootState> = (state: TState) => TResult;
+type TranslationParams = Record<string, string | number | boolean>;
+/**
+ * FrontX Provider Props
+ * Props for the main FrontXProvider component.
+ *
+ * @example
+ * ```tsx
+ * const app = createFrontX().use(microfrontends(config)).build();
+ * <FrontXProvider app={app}>
+ *   <App />
+ * </FrontXProvider>
+ *
+ * // With MFE bridge (for MFE components)
+ * <FrontXProvider app={app} mfeBridge={{ bridge, extensionId, domainId }}>
+ *   <MyMfeApp />
+ * </FrontXProvider>
+ *
+ * // QueryCache is resolved from the app's plugin composition
+ * <FrontXProvider app={app}>
+ *   <MyMfeApp />
+ * </FrontXProvider>
+ * ```
+ */
+interface FrontXProviderProps {
+    /** Child components */
+    children: ReactNode;
+    /** The runtime's FrontX app, built once by the caller */
+    app: FrontXApp;
+    /** MFE bridge context (for MFE components) */
+    mfeBridge?: MfeContextValue;
+}
+/**
+ * useFrontX Hook Return Type
+ * Returns the FrontX app instance from context.
+ */
+type UseFrontXReturn = FrontXApp;
+/**
+ * useAppSelector Hook
+ * Type-safe selector hook for Redux state.
+ *
+ * @template TResult - The result type of the selector
+ */
+type UseAppSelector = <TResult>(selector: Selector<TResult>) => TResult;
+/**
+ * useAppDispatch Hook Return Type
+ * Returns the typed dispatch function.
+ */
+type UseAppDispatchReturn = (action: unknown) => unknown;
+/**
+ * useTranslation Hook Return Type
+ * Translation utilities.
+ */
+interface UseTranslationReturn {
+    /** Translate a key */
+    t: (key: string, params?: TranslationParams) => string;
+    /** Current language */
+    language: Language | null;
+    /** Change language */
+    setLanguage: (language: Language) => void;
+    /** Check if current language is RTL */
+    isRTL: boolean;
+}
+/**
+ * useScreenTranslations Hook Return Type
+ * Screen-level translation loading state.
+ */
+interface UseScreenTranslationsReturn {
+    /** Whether translations are loaded */
+    isLoaded: boolean;
+    /** Loading error (if any) */
+    error: Error | null;
+}
+/**
+ * useTheme Hook Return Type
+ * Theme utilities.
+ */
+interface UseThemeReturn {
+    /** Current theme ID */
+    currentTheme: string | undefined;
+    /** All available themes */
+    themes: Array<{
+        id: string;
+        name: string;
+    }>;
+    /** Change theme */
+    setTheme: (themeId: string) => void;
+}
+/**
+ * useFormatters Hook Return Type
+ * Locale-aware formatters (locale from i18nRegistry.getLanguage()).
+ * References @gears-frontx/i18n Formatters so signatures stay in sync.
+ */
+type UseFormattersReturn = Formatters;
+/**
+ * useCanAccess Hook Return Type
+ * Result of an RBAC access check.
+ * allow is false until an explicit 'allow' decision arrives (pessimistic default).
+ */
+interface UseCanAccessResult {
+    allow: boolean;
+    isResolving: boolean;
+}
+/**
+ * CanAccess Component Props.
+ * Pessimistic: renders `denied` (or `loading`) until an authoritative 'allow' arrives.
+ */
+interface CanAccessProps<TRecord extends AccessRecord = AccessRecord> {
+    query: AccessQuery<TRecord>;
+    /** Content rendered when access is explicitly allowed. */
+    allowed: ReactNode;
+    /** Content rendered on deny or error. Defaults to null. */
+    denied?: ReactNode;
+    /** Optional slot shown while the decision is resolving. Falls back to `denied`. */
+    loading?: ReactNode;
+}
+
+export { type ApiQueryResult as A, type CanAccessProps as C, type FrontXProviderProps as F, type MfeContextValue as M, type UseTranslationReturn as U, type ApiInfiniteQueryResult as a, type ApiMutationResult as b, type UseScreenTranslationsReturn as c, type UseFormattersReturn as d, type UseThemeReturn as e, type ApiSuspenseQueryResult as f, type ApiSuspenseInfiniteQueryResult as g, type UseCanAccessResult as h, MfeContext as i, type UseAppDispatchReturn as j, type UseAppSelector as k, type UseFrontXReturn as l, useMfeContext as u };

package/dist/types.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * @gears-frontx/react - Type Definitions\n *\n * Core types for HAI3 React bindings.\n * Provides type-safe hooks and components.\n *\n * Now using real imports from @gears-frontx/framework since packages are built together.\n */\n\nimport type { ReactNode } from 'react';\nimport type {\n  HAI3Config,\n  HAI3App,\n  RootState,\n  Language,\n  Formatters,\n} from '@gears-frontx/framework';\nimport type { MfeContextValue } from './mfe/MfeContext';\n\n// Re-export imported types for convenience\nexport type { HAI3Config, HAI3App };\n\n// ============================================================================\n// Type Aliases\n// ============================================================================\n\n// From @gears-frontx/store\ntype Selector<TResult, TState = RootState> = (state: TState) => TResult;\n\n// Language is imported from @gears-frontx/framework\ntype TranslationParams = Record<string, string | number | boolean>;\n\n// ============================================================================\n// HAI3 Provider Props\n// ============================================================================\n\n/**\n * HAI3 Provider Props\n * Props for the main HAI3Provider component.\n *\n * @example\n * ```tsx\n * <HAI3Provider config={{ devMode: true }}>\n *   <App />\n * </HAI3Provider>\n *\n * // With pre-built app\n * const app = createHAI3().use(screensets()).use(microfrontends()).build();\n * <HAI3Provider app={app}>\n *   <App />\n * </HAI3Provider>\n *\n * // With MFE bridge (for MFE components)\n * <HAI3Provider mfeBridge={{ bridge, extensionId, domainId }}>\n *   <MyMfeApp />\n * </HAI3Provider>\n * ```\n */\nexport interface HAI3ProviderProps {\n  /** Child components */\n  children: ReactNode;\n  /** HAI3 configuration */\n  config?: HAI3Config;\n  /** Pre-built HAI3 app instance (optional) */\n  app?: HAI3App;\n  /** MFE bridge context (for MFE components) */\n  mfeBridge?: MfeContextValue;\n}\n\n// ============================================================================\n// Hook Return Types\n// ============================================================================\n\n/**\n * useHAI3 Hook Return Type\n * Returns the HAI3 app instance from context.\n */\nexport type UseHAI3Return = HAI3App;\n\n/**\n * useAppSelector Hook\n * Type-safe selector hook for Redux state.\n *\n * @template TResult - The result type of the selector\n */\nexport type UseAppSelector = <TResult>(selector: Selector<TResult>) => TResult;\n\n/**\n * useAppDispatch Hook Return Type\n * Returns the typed dispatch function.\n */\nexport type UseAppDispatchReturn = (action: unknown) => unknown;\n\n/**\n * useTranslation Hook Return Type\n * Translation utilities.\n */\nexport interface UseTranslationReturn {\n  /** Translate a key */\n  t: (key: string, params?: TranslationParams) => string;\n  /** Current language */\n  language: Language | null;\n  /** Change language */\n  setLanguage: (language: Language) => void;\n  /** Check if current language is RTL */\n  isRTL: boolean;\n}\n\n/**\n * useScreenTranslations Hook Return Type\n * Screen-level translation loading state.\n */\nexport interface UseScreenTranslationsReturn {\n  /** Whether translations are loaded */\n  isLoaded: boolean;\n  /** Loading error (if any) */\n  error: Error | null;\n}\n\n/**\n * useTheme Hook Return Type\n * Theme utilities.\n */\nexport interface UseThemeReturn {\n  /** Current theme ID */\n  currentTheme: string | undefined;\n  /** All available themes */\n  themes: Array<{ id: string; name: string }>;\n  /** Change theme */\n  setTheme: (themeId: string) => void;\n}\n\n/**\n * useFormatters Hook Return Type\n * Locale-aware formatters (locale from i18nRegistry.getLanguage()).\n * References @gears-frontx/i18n Formatters so signatures stay in sync.\n */\nexport type UseFormattersReturn = Formatters;\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * @gears-frontx/react - Type Definitions\n *\n * Core types for FrontX React bindings.\n * Provides type-safe hooks and components.\n *\n * Now using real imports from @gears-frontx/framework since packages are built together.\n */\n\nimport type { ReactNode } from 'react';\nimport type {\n  FrontXConfig,\n  FrontXApp,\n  RootState,\n  Language,\n  Formatters,\n  AccessQuery,\n  AccessRecord,\n} from '@gears-frontx/framework';\nimport type { MfeContextValue } from './mfe/MfeContext';\n\n// Re-export imported types for convenience\nexport type { FrontXConfig, FrontXApp };\n\n// ============================================================================\n// API Hook Result Types\n// ============================================================================\n\n/**\n * Gears FrontX-owned query result type.\n * Returned by useApiQuery — callers depend on this contract, not on TanStack internals.\n */\n// @cpt-FEATURE:implement-endpoint-descriptors:p3\n// @cpt-begin:implement-endpoint-descriptors:p3:inst-api-query-result\nexport interface ApiQueryResult<TData, TError = Error> {\n  data: TData | undefined;\n  error: TError | null;\n  isLoading: boolean;\n  isFetching: boolean;\n  isError: boolean;\n  refetch: () => Promise<unknown>;\n}\n// @cpt-end:implement-endpoint-descriptors:p3:inst-api-query-result\n\n/**\n * Gears FrontX-owned suspense query result type.\n * Returned by useApiSuspenseQuery — callers depend on this contract, not on TanStack internals.\n */\n// @cpt-begin:cpt-frontx-dod-request-lifecycle-use-api-query:p2:inst-suspense-query-result\nexport interface ApiSuspenseQueryResult<TData, TError = Error> {\n  data: TData;\n  error: TError | null;\n  isFetching: boolean;\n  refetch: () => Promise<void>;\n}\n// @cpt-end:cpt-frontx-dod-request-lifecycle-use-api-query:p2:inst-suspense-query-result\n\n/**\n * Gears FrontX-owned infinite query result type.\n * Returned by useApiInfiniteQuery for descriptor-driven pagination.\n */\n// @cpt-begin:cpt-frontx-dod-request-lifecycle-use-api-query:p2:inst-infinite-query-result\nexport interface ApiInfiniteQueryResult<TPage, TError = Error> {\n  data: readonly TPage[] | undefined;\n  error: TError | null;\n  isLoading: boolean;\n  isFetching: boolean;\n  isError: boolean;\n  hasNextPage: boolean;\n  hasPreviousPage: boolean;\n  isFetchingNextPage: boolean;\n  isFetchingPreviousPage: boolean;\n  fetchNextPage: () => Promise<void>;\n  fetchPreviousPage: () => Promise<void>;\n  refetch: () => Promise<void>;\n}\n// @cpt-end:cpt-frontx-dod-request-lifecycle-use-api-query:p2:inst-infinite-query-result\n\n/**\n * Gears FrontX-owned suspense infinite query result type.\n * Returned by useApiSuspenseInfiniteQuery for descriptor-driven pagination.\n */\n// @cpt-begin:cpt-frontx-dod-request-lifecycle-use-api-query:p2:inst-suspense-infinite-query-result\nexport interface ApiSuspenseInfiniteQueryResult<TPage, TError = Error> {\n  data: readonly TPage[];\n  error: TError | null;\n  isFetching: boolean;\n  hasNextPage: boolean;\n  hasPreviousPage: boolean;\n  isFetchingNextPage: boolean;\n  isFetchingPreviousPage: boolean;\n  fetchNextPage: () => Promise<void>;\n  fetchPreviousPage: () => Promise<void>;\n  refetch: () => Promise<void>;\n}\n// @cpt-end:cpt-frontx-dod-request-lifecycle-use-api-query:p2:inst-suspense-infinite-query-result\n\n/**\n * Gears FrontX-owned mutation result type.\n * Returned by useApiMutation — callers depend on this contract, not on TanStack internals.\n */\n// @cpt-begin:implement-endpoint-descriptors:p3:inst-api-mutation-result\nexport interface ApiMutationResult<TData, TError = Error, TVariables = void> {\n  mutate: (variables: TVariables) => void;\n  mutateAsync: (variables: TVariables) => Promise<TData>;\n  isPending: boolean;\n  error: TError | null;\n  data: TData | undefined;\n  reset: () => void;\n}\n// @cpt-end:implement-endpoint-descriptors:p3:inst-api-mutation-result\n\n// ============================================================================\n// Type Aliases\n// ============================================================================\n\n// From @gears-frontx/store\ntype Selector<TResult, TState = RootState> = (state: TState) => TResult;\n\n// Language is imported from @gears-frontx/framework\ntype TranslationParams = Record<string, string | number | boolean>;\n\n// ============================================================================\n// FrontX Provider Props\n// ============================================================================\n\n/**\n * FrontX Provider Props\n * Props for the main FrontXProvider component.\n *\n * @example\n * ```tsx\n * const app = createFrontX().use(microfrontends(config)).build();\n * <FrontXProvider app={app}>\n *   <App />\n * </FrontXProvider>\n *\n * // With MFE bridge (for MFE components)\n * <FrontXProvider app={app} mfeBridge={{ bridge, extensionId, domainId }}>\n *   <MyMfeApp />\n * </FrontXProvider>\n *\n * // QueryCache is resolved from the app's plugin composition\n * <FrontXProvider app={app}>\n *   <MyMfeApp />\n * </FrontXProvider>\n * ```\n */\nexport interface FrontXProviderProps {\n  /** Child components */\n  children: ReactNode;\n  /** The runtime's FrontX app, built once by the caller */\n  app: FrontXApp;\n  /** MFE bridge context (for MFE components) */\n  mfeBridge?: MfeContextValue;\n}\n\n// ============================================================================\n// Hook Return Types\n// ============================================================================\n\n/**\n * useFrontX Hook Return Type\n * Returns the FrontX app instance from context.\n */\nexport type UseFrontXReturn = FrontXApp;\n\n/**\n * useAppSelector Hook\n * Type-safe selector hook for Redux state.\n *\n * @template TResult - The result type of the selector\n */\nexport type UseAppSelector = <TResult>(selector: Selector<TResult>) => TResult;\n\n/**\n * useAppDispatch Hook Return Type\n * Returns the typed dispatch function.\n */\nexport type UseAppDispatchReturn = (action: unknown) => unknown;\n\n/**\n * useTranslation Hook Return Type\n * Translation utilities.\n */\nexport interface UseTranslationReturn {\n  /** Translate a key */\n  t: (key: string, params?: TranslationParams) => string;\n  /** Current language */\n  language: Language | null;\n  /** Change language */\n  setLanguage: (language: Language) => void;\n  /** Check if current language is RTL */\n  isRTL: boolean;\n}\n\n/**\n * useScreenTranslations Hook Return Type\n * Screen-level translation loading state.\n */\nexport interface UseScreenTranslationsReturn {\n  /** Whether translations are loaded */\n  isLoaded: boolean;\n  /** Loading error (if any) */\n  error: Error | null;\n}\n\n/**\n * useTheme Hook Return Type\n * Theme utilities.\n */\nexport interface UseThemeReturn {\n  /** Current theme ID */\n  currentTheme: string | undefined;\n  /** All available themes */\n  themes: Array<{ id: string; name: string }>;\n  /** Change theme */\n  setTheme: (themeId: string) => void;\n}\n\n/**\n * useFormatters Hook Return Type\n * Locale-aware formatters (locale from i18nRegistry.getLanguage()).\n * References @gears-frontx/i18n Formatters so signatures stay in sync.\n */\nexport type UseFormattersReturn = Formatters;\n\n/**\n * useCanAccess Hook Return Type\n * Result of an RBAC access check.\n * allow is false until an explicit 'allow' decision arrives (pessimistic default).\n */\nexport interface UseCanAccessResult {\n  allow: boolean;\n  isResolving: boolean;\n}\n\n/**\n * CanAccess Component Props.\n * Pessimistic: renders `denied` (or `loading`) until an authoritative 'allow' arrives.\n */\nexport interface CanAccessProps<TRecord extends AccessRecord = AccessRecord> {\n  query: AccessQuery<TRecord>;\n  /** Content rendered when access is explicitly allowed. */\n  allowed: ReactNode;\n  /** Content rendered on deny or error. Defaults to null. */\n  denied?: ReactNode;\n  /** Optional slot shown while the decision is resolving. Falls back to `denied`. */\n  loading?: ReactNode;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/types.d.cts

@@ -1,3 +1,3 @@
 import 'react';
-export { HAI3App, HAI3Config } from '@gears-frontx/framework';
-export { H as HAI3ProviderProps, e as UseAppDispatchReturn, f as UseAppSelector, b as UseFormattersReturn, g as UseHAI3Return, a as UseScreenTranslationsReturn, c as UseThemeReturn, U as UseTranslationReturn } from './types-Cp8Zm5s0.cjs';
+export { FrontXApp, FrontXConfig } from '@gears-frontx/framework';
+export { a as ApiInfiniteQueryResult, b as ApiMutationResult, A as ApiQueryResult, g as ApiSuspenseInfiniteQueryResult, f as ApiSuspenseQueryResult, C as CanAccessProps, F as FrontXProviderProps, j as UseAppDispatchReturn, k as UseAppSelector, h as UseCanAccessResult, d as UseFormattersReturn, l as UseFrontXReturn, c as UseScreenTranslationsReturn, e as UseThemeReturn, U as UseTranslationReturn } from './types-JtpziA_B.cjs';

package/dist/types.d.ts

@@ -1,3 +1,3 @@
 import 'react';
-export { HAI3App, HAI3Config } from '@gears-frontx/framework';
-export { H as HAI3ProviderProps, e as UseAppDispatchReturn, f as UseAppSelector, b as UseFormattersReturn, g as UseHAI3Return, a as UseScreenTranslationsReturn, c as UseThemeReturn, U as UseTranslationReturn } from './types-Cp8Zm5s0.js';
+export { FrontXApp, FrontXConfig } from '@gears-frontx/framework';
+export { a as ApiInfiniteQueryResult, b as ApiMutationResult, A as ApiQueryResult, g as ApiSuspenseInfiniteQueryResult, f as ApiSuspenseQueryResult, C as CanAccessProps, F as FrontXProviderProps, j as UseAppDispatchReturn, k as UseAppSelector, h as UseCanAccessResult, d as UseFormattersReturn, l as UseFrontXReturn, c as UseScreenTranslationsReturn, e as UseThemeReturn, U as UseTranslationReturn } from './types-JtpziA_B.js';

package/llms.txt

@@ -1,19 +1,20 @@
 # @gears-frontx/react
 
-> React bindings, hooks, and components for HAI3 SDK. Provides type-safe integration with React applications including MFE (Microfrontend) support.
+> React bindings, hooks, and components for FrontX SDK. Provides type-safe integration with React applications including MFE (Microfrontend) support.
 
-Part of the HAI3 React Layer (L3) - depends on @gears-frontx/framework. Peer dependency on react and react-dom.
+Part of the FrontX React Layer (L3) - depends on @gears-frontx/framework. Peer dependency on react and react-dom.
 
 ## Core API
 
-- [HAI3Provider](https://hai3.dev/docs/react/provider): Root context provider
-- [MFE Components](https://hai3.dev/docs/react/mfe): ExtensionDomainSlot, MfeProvider, RefContainerProvider
+- [FrontXProvider](https://frontx.dev/docs/react/provider): Root context provider
+- [MFE Components](https://frontx.dev/docs/react/mfe): ExtensionDomainSlot, MfeProvider
+- `FrontXProvider` resolves the shared `QueryClient` from `queryCache()` / `queryCacheShared()` through the app instance; mounted MFEs reuse the host cache by building their local app with `queryCacheShared()`, which joins the same shared `QueryClient` without mutating L1 contracts
 
 ## Hooks
 
 | Hook | Purpose |
 |------|---------|
-| `useHAI3()` | Access app instance |
+| `useFrontX()` | Access app instance |
 | `useAppDispatch()` | Type-safe dispatch |
 | `useAppSelector()` | Type-safe selector |
 | `useTranslation()` | Translation utilities (t, language, setLanguage, isRTL) |
@@ -25,30 +26,34 @@ Part of the HAI3 React Layer (L3) - depends on @gears-frontx/framework. Peer dep
 | Hook | Purpose |
 |------|---------|
 | `useMfeBridge()` | Access MFE bridge (child MFEs) |
-| `useSharedProperty()` | Subscribe to shared property changes |
+| `useSharedProperty()` | Subscribe to shared property changes, via `MfeContext` or an explicit `bridge` option |
 | `useHostAction()` | Invoke actions on host application |
 | `useDomainExtensions()` | Subscribe to extensions in a domain |
 
 ## Quick Start
 
 ```tsx
-import { HAI3Provider, ExtensionDomainSlot, useTranslation, useHAI3 } from '@gears-frontx/react';
+import { createFrontX, FrontXProvider, presets, useTranslation, useFrontX } from '@gears-frontx/react';
+
+// One app per runtime, built once at module level (the full preset here;
+// `presets.full({ microfrontends: config })` also adds microfrontends)
+const app = createFrontX().useAll(presets.full()).build();
 
 // Wrap app with provider
 function App() {
   return (
-    <HAI3Provider>
+    <FrontXProvider app={app}>
       <Layout>
-        <ExtensionDomainSlot domainId="screen" fallback={<Loading />} />
+        <MainScreen />
       </Layout>
-    </HAI3Provider>
+    </FrontXProvider>
   );
 }
 
 // Use hooks in components
 function MyComponent() {
   const { t, isRTL } = useTranslation();
-  const app = useHAI3();
+  const app = useFrontX();
 
   return (
     <div dir={isRTL ? 'rtl' : 'ltr'}>
@@ -66,13 +71,12 @@ function MyComponent() {
 import { ExtensionDomainSlot } from '@gears-frontx/react';
 
 function LayoutScreen() {
-  const screenContainerRef = useRef<HTMLDivElement>(null);
-
   return (
     <ExtensionDomainSlot
+      registry={registry}
       domainId="screen"
-      containerRef={screenContainerRef}
-      fallback={<Loading />}
+      extensionId="home"
+      loadingComponent={<Loading />}
     />
   );
 }
@@ -81,15 +85,17 @@ function LayoutScreen() {
 ### Using MFE Bridge
 
 ```tsx
-import { useMfeBridge, useSharedProperty, HAI3_ACTION_LOAD_EXT, HAI3_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
+import { useMfeBridge, useSharedProperty, FRONTX_ACTION_LOAD_EXT, FRONTX_SHARED_PROPERTY_THEME } from '@gears-frontx/react';
 
 function MyExtension() {
   const bridge = useMfeBridge();
-  const theme = useSharedProperty(HAI3_SHARED_PROPERTY_THEME);
+  const theme = useSharedProperty(FRONTX_SHARED_PROPERTY_THEME);
 
-  const handleAction = async () => {
-    await bridge.executeActionsChain({
-      action: { type: HAI3_ACTION_LOAD_EXT, target: 'screen', payload: { extensionId: 'other' } }
+  // executeActionsChain is acceptance-only: it returns void, never throws,
+  // and never yields anything to await for the chain's own execution.
+  const handleAction = () => {
+    bridge.executeActionsChain({
+      action: { type: FRONTX_ACTION_LOAD_EXT, target: 'screen', payload: { subject: 'other' } }
     });
   };
 
@@ -97,6 +103,26 @@ function MyExtension() {
 }
 ```
 
+### Shared Properties Without MfeProvider
+
+`useSharedProperty(propertyTypeId, options)` takes an explicit `bridge` for components that never mount `MfeProvider`, plus a `fallback` returned until the host publishes the property (only `undefined` is substituted; a published `null` is a value). With `fallback` set the result type is `T`. There is no consumer-side validation option: the host validates published values against the property's schema before delivery, so `T` is the caller's declaration of that schema.
+
+```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>;
+}
+```
+
+Omitting `bridge` falls back to `MfeContext`; the hook still throws when neither is available. Changing `bridge` or `propertyTypeId` moves the subscription and the value follows on the same render.
+
 ### Subscribing to Domain Extensions
 
 ```tsx
@@ -117,6 +143,6 @@ function ScreenList() {
 
 ## Optional
 
-- [Screen Translations](https://hai3.dev/docs/react/translations): Per-screen lazy loading
-- [Custom Hooks](https://hai3.dev/docs/react/hooks): Building on HAI3 hooks
-- [MFE Bridge Communication](https://hai3.dev/docs/react/mfe-bridge): Parent-child patterns
+- [Screen Translations](https://frontx.dev/docs/react/translations): Per-screen lazy loading
+- [Custom Hooks](https://frontx.dev/docs/react/hooks): Building on FrontX hooks
+- [MFE Bridge Communication](https://frontx.dev/docs/react/mfe-bridge): Parent-child patterns

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gears-frontx/react",
-  "version": "0.1.0",
-  "description": "React bindings and hooks for HAI3 framework",
+  "version": "0.2.0-alpha.15",
+  "description": "React bindings and hooks for FrontX framework",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -12,6 +12,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs"
+    },
     "./types": {
       "types": "./dist/types.d.ts",
       "import": "./dist/types.js",
@@ -21,33 +26,39 @@
   "files": [
     "dist",
     "CLAUDE.md",
-    "llms.txt",
-    "commands"
+    "llms.txt"
   ],
   "scripts": {
     "build": "tsup",
-    "type-check": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "type-check": "tsc --noEmit && npm run type-check:test",
+    "type-check:test": "tsc -p tsconfig.test.json",
+    "test": "npm run test:unit",
+    "test:unit": "vitest --run --passWithNoTests=false",
+    "test:unit:watch": "vitest --watch"
   },
-  "dependencies": {},
   "devDependencies": {
-    "tsup": "^8.0.0",
-    "typescript": "^5.4.2",
-    "react": "^19.2.4",
-    "@types/react": "^19.0.8",
-    "react-redux": "^9.1.0",
-    "@types/react-redux": "^7.1.33",
-    "vitest": "^4.0.18",
-    "@vitest/coverage-v8": "^4.0.18",
-    "@testing-library/react": "^16.1.0",
-    "@reduxjs/toolkit": "^2.5.0",
-    "jsdom": "^25.0.1"
+    "@reduxjs/toolkit": "2.12.0",
+    "@tanstack/react-query": "5.101.4",
+    "@testing-library/react": "16.3.2",
+    "@types/node": "^24.0.0",
+    "@types/react": "19.2.18",
+    "@types/react-redux": "7.1.34",
+    "@vitejs/plugin-react": "4.3.4",
+    "@vitest/coverage-v8": "4.1.4",
+    "jsdom": "26.1.0",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "react-redux": "9.3.0",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "4.1.4"
   },
   "peerDependencies": {
     "@gears-frontx/framework": "*",
-    "react": "^19.2.4",
-    "react-redux": ">=8.0.0"
+    "@tanstack/react-query": "5.101.4",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "react-redux": "9.3.0"
   },
   "peerDependenciesMeta": {
     "@gears-frontx/framework": {
@@ -56,20 +67,26 @@
     "react": {
       "optional": false
     },
+    "react-dom": {
+      "optional": false
+    },
     "react-redux": {
       "optional": false
+    },
+    "@tanstack/react-query": {
+      "optional": false
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "keywords": [
-    "hai3",
+    "frontx",
     "react",
     "hooks",
     "provider",
     "typescript"
   ],
-  "author": "HAI3",
+  "author": "Cyber Fabric",
   "license": "Apache-2.0"
 }

package/commands/hai3-duplicate-screenset.md

@@ -1,58 +0,0 @@
-<!-- @standalone -->
-# hai3:duplicate-screenset - Duplicate Screenset
-
-## AI WORKFLOW (REQUIRED)
-1) Read .ai/targets/SCREENSETS.md before starting.
-2) Gather requirements from user.
-3) Follow steps below.
-
-REQUIRED: Copy folder and update ids.ts only (2 steps, 96% reduction).
-REQUIRED: Pass arch:check with zero errors.
-REQUIRED: Test via Chrome DevTools MCP (never skip).
-
-## GATHER REQUIREMENTS
-Ask user for:
-- SOURCE screenset name (existing screenset to copy).
-- TARGET screenset name (camelCase, single word preferred).
-- TARGET category: Drafts | Mockups | Production.
-
-## STEP 1: Copy Screenset via CLI
-```bash
-hai3 screenset copy SOURCE TARGET --category={category}
-```
-The CLI automatically:
-- Copies all files (screens, slices, actions, events, effects, API, icons, i18n).
-- Updates ids.ts with TARGET_SCREENSET_ID and all SCREEN_IDs.
-- Everything auto-updates via template literals:
-  - Event enums: ${TARGET_SCREENSET_ID}/${DOMAIN_ID}/eventName.
-  - Icon IDs: ${TARGET_SCREENSET_ID}:iconName.
-  - API domain: ${TARGET_SCREENSET_ID}:serviceName.
-  - Redux state key.
-- Screenset auto-discovered (no manual registration).
-
-## STEP 2: Validate
-```bash
-npm run type-check
-npm run arch:check
-npm run lint
-grep -rn "OLD_SCREENSET_ID" src/screensets/TARGET/  # Must return 0 matches
-```
-
-## STEP 3: Test via Chrome DevTools MCP
-STOP: If MCP connection is broken, fix it first. NEVER skip testing.
-- npm run dev.
-- Verify TARGET in screenset selector.
-- Click TARGET screenset in dev panel.
-- Verify URL changes to target screenset.
-- Check 0 console errors.
-- Test all primary features.
-- Verify auto-discovery worked (screenset appears without manual registration).
-
-## CHECKLIST
-- [ ] Gather requirements (source, target name, category).
-- [ ] Run `hai3 screenset copy SOURCE TARGET --category={category}`.
-- [ ] Run type-check (MUST pass).
-- [ ] Run arch:check (MUST pass).
-- [ ] Run lint (MUST pass).
-- [ ] Verify zero occurrences of old screenset ID.
-- [ ] Test via Chrome DevTools MCP (NEVER skip).

package/commands/hai3-new-component.md

@@ -1,48 +0,0 @@
-<!-- @standalone -->
-# hai3:new-component - Add New UI Component
-
-## AI WORKFLOW (REQUIRED)
-1) Check for existing equivalent in project (e.g. components/ui/) and configured UI library first.
-2) Gather requirements from user.
-3) Implement.
-
-## CHECK EXISTING COMPONENTS FIRST
-- REQUIRED: Read `frontx.config.json` to find the `uikit` value.
-- If uikit is a third-party package (not `shadcn` or `none`): read its exports from `node_modules/<package>/` to check for existing components.
-- REQUIRED: Before creating a new component, scan the project AND the configured UI library for existing equivalents.
-- REQUIRED: Reuse existing components if equivalent exists.
-
-## GATHER REQUIREMENTS
-Ask user for:
-- Component name (e.g., "DataTable", "ColorPicker").
-- Component description and props.
-
-## IF SCREENSET COMPONENT
-
-### STEP 0: Determine Subfolder
-- components/ui/: Base UI primitives (shadcn components or custom).
-- screens/{screen}/components/: Screen-specific components.
-- components/: Shared composites used across screens.
-
-### STEP 1: Implementation
-
-#### 1.1 Create Component
-File: src/components/ui/{ComponentName}.tsx (base primitives)
-  or: src/screens/{screen}/components/{ComponentName}.tsx (screen-specific)
-  or: src/components/{ComponentName}.tsx (shared composites)
-- Must be reusable within the MFE.
-- NO Redux or state management.
-- Accept value/onChange pattern for state.
-
-#### 1.2 Export
-Export from local index if needed.
-
-#### 1.3 Validation
-Run: npm run arch:check && npm run dev
-Test component in UI.
-
-## RULES
-- REQUIRED: Check existing project UI components first; create new only if missing.
-- FORBIDDEN: Redux, business logic, side effects in components.
-- FORBIDDEN: Inline styles outside components/ui/.
-- REQUIRED: Accept value/onChange pattern for state.