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

package/dist/index.d.cts

@@ -1,61 +1,180 @@
 import * as React from 'react';
-import React__default, { RefObject } from 'react';
-import { H as HAI3ProviderProps, U as UseTranslationReturn, a as UseScreenTranslationsReturn, b as UseFormattersReturn, c as UseThemeReturn, M as MfeContextValue } from './types-Cp8Zm5s0.cjs';
-export { d as MfeContext, e as UseAppDispatchReturn, f as UseAppSelector, g as UseHAI3Return, u as useMfeContext } from './types-Cp8Zm5s0.cjs';
-import { HAI3App, AppDispatch, RootState, TranslationMap, TranslationLoader, ChildMfeBridge, Extension, ContainerProvider, ScreensetsRegistry, ParentMfeBridge, EventPayloadMap as EventPayloadMap$1, EventBus } from '@gears-frontx/framework';
-export { ACCOUNTS_DOMAIN, Action, ActionsChain, ApiPlugin, ApiPluginBase, ApiPluginErrorContext, ApiProtocol, ApiRequestContext, ApiResponseContext, ApiServiceConfig, AppDispatch, BaseApiService, BasePluginHooks, ChangeThemePayload, ChildMfeBridge, ContainerProvider, EventHandler, EventSourceLike, Extension, ExtensionDomain, ExtensionPresentation, ExtensionRegistrationState, FRONTX_ACTION_LOAD_EXT, FRONTX_ACTION_MOUNT_EXT, FRONTX_ACTION_UNMOUNT_EXT, FRONTX_MFE_ENTRY_MF, FRONTX_OVERLAY_DOMAIN, FRONTX_POPUP_DOMAIN, FRONTX_SCREEN_DOMAIN, FRONTX_SCREEN_EXTENSION_TYPE, FRONTX_SHARED_PROPERTY_LANGUAGE, FRONTX_SHARED_PROPERTY_THEME, FRONTX_SIDEBAR_DOMAIN, FooterConfig, FooterState, HAI3App, HAI3AppBuilder, HAI3Config, HAI3Plugin, HAI3Store, HeaderConfig, HeaderState, HeaderUser, I18nConfig, I18nRegistry, I18nRegistryImpl, I18nRegistryType, JSONSchema, JsonCompatible, JsonObject, JsonPrimitive, JsonValue, LAYOUT_SLICE_NAME, Language, LanguageDisplayMode, LanguageMetadata, LayoutDomain, LayoutDomainReducers, LayoutDomainState, LayoutState, LifecycleHook, LifecycleStage, LoadExtPayload, MOCK_PLUGIN, MenuItem, MenuState, MfeBridgeFactory, MfeEntry, MfeEntryLifecycle, MfeEntryMF, MfeHandler, MfeHandlerMF, MfeState, MockEventSource, MockEvents, MockMap, MockState, MockTogglePayload, MountExtPayload, OverlayConfig, OverlayState, ParentMfeBridge, PluginClass, PluginFactory, PluginLifecycle, PluginProvides, PopupConfig, PopupSliceState, PopupState, Preset, Presets, ProtocolClass, ProtocolPluginType, ReducerPayload, RegisterExtensionPayload, RestMockConfig, RestMockPlugin, RestPlugin, RestPluginHooks, RestPluginWithConfig, RestProtocol, RestProtocolConfig, RestRequestContext, RestResponseContext, RestShortCircuitResponse, RootState, RootStateWithLayout, SUPPORTED_LANGUAGES, ScreenExtension, ScreenState, ScreensetsConfig, ScreensetsRegistry, ScreensetsRegistryConfig, ScreensetsRegistryFactory, SetLanguagePayload, SharedProperty, ShortCircuitResponse, ShowPopupPayload, SidebarPosition, SidebarState, SliceObject, SseConnectContext, SseMockConfig, SseMockEvent, SseMockPlugin, SsePlugin, SsePluginHooks, SsePluginWithConfig, SseProtocol, SseProtocolConfig, SseShortCircuitResponse, Subscription, TENANT_SLICE_NAME, Tenant, TenantChangedPayload, TenantClearedPayload, TenantEvents, TenantState, TextDirection, ThemeConfig, ThemeRegistry, TranslationDictionary, TranslationLoader, TranslationMap, TypeSystemPlugin, UnmountExtPayload, UnregisterExtensionPayload, ValidationError, ValidationResult, apiRegistry, changeTenant, clearActiveScreen, clearTenant, clearTenantAction, clearUser, closeAllPopups, closePopup, closeTopPopup, createHAI3, createHAI3App, createI18nRegistry, createShadowRoot, createSlice, createStore, createThemeRegistry, effects, extensionScreenSchema, extractGtsPackage, footerActions, footerSlice, getLanguageMetadata, getStore, gtsPlugin, hasSlice, headerActions, headerSlice, hideOverlay, i18n, i18nRegistry, initMockEffects, initTenantEffects, injectCssVariables, isMockPlugin, isRestShortCircuit, isShortCircuit, isSseShortCircuit, languageSchema, layout, layoutDomainReducers, layoutReducer, loadExtension, menuActions, menuSlice, microfrontends, mock, mockActions, mockSlice, mountExtension, navigateTo, openPopup, overlayActions, overlayDomain, overlaySlice, popupActions, popupDomain, popupSlice, presets, registerExtension, registerSlice, screenActions, screenDomain, screenSlice, screensets, screensetsRegistryFactory, selectExtensionError, selectExtensionState, selectRegisteredExtensions, setActiveScreen, setFooterConfig, setFooterVisible, setHeaderLoading, setMenuCollapsed, setMenuConfig, setMenuItems, setMenuVisible, setMockEnabled, setOverlayVisible, setScreenLoading, setSidebarCollapsed, setSidebarConfig, setSidebarContent, setSidebarPosition, setSidebarTitle, setSidebarVisible, setSidebarWidth, setTenant, setTenantLoading, setTenantLoadingState, setUser, showOverlay, sidebarActions, sidebarDomain, sidebarSlice, tenantActions, tenantReducer, tenantSlice, themeSchema, themes, toggleMenu, toggleMockMode, toggleSidebar, unmountExtension, unregisterExtension } from '@gears-frontx/framework';
+import React__default, { ReactElement } from 'react';
+import { F as FrontXProviderProps, A as ApiQueryResult, a as ApiInfiniteQueryResult, b as ApiMutationResult, C as CanAccessProps, U as UseTranslationReturn, c as UseScreenTranslationsReturn, d as UseFormattersReturn, e as UseThemeReturn, f as ApiSuspenseQueryResult, g as ApiSuspenseInfiniteQueryResult, h as UseCanAccessResult, M as MfeContextValue } from './types-Cjd20AT-.cjs';
+export { i as MfeContext, j as UseAppDispatchReturn, k as UseAppSelector, l as UseFrontXReturn, u as useMfeContext } from './types-Cjd20AT-.cjs';
+import { FrontXApp, EndpointDescriptor, MutationDescriptor, AccessRecord, AppDispatch, RootState, TranslationMap, TranslationLoader, StreamStatus, StreamDescriptor, AccessQuery, ChildMfeBridge, Extension, MfeEntryLifecycle, MfeMountContext, MfeRegistry, EventPayloadMap as EventPayloadMap$1, EventBus } from '@gears-frontx/framework';
+export { ACCOUNTS_DOMAIN, AccessDecision, AccessQuery, Action, ActionHandler, ActionPayload, ActionsChain, ApiPlugin, ApiPluginBase, ApiPluginErrorContext, ApiProtocol, ApiRequestContext, ApiResponseContext, ApiServiceConfig, AppDispatch, AuthCallbackInput, AuthCapabilities, AuthCheckResult, AuthContext, AuthLoginInput, AuthPermissions, AuthPluginConfig, AuthProvider, AuthRuntime, AuthSession, AuthState, AuthStateEvent, AuthStateListener, AuthTransition, AuthUnsubscribe, BaseApiService, BasePluginHooks, ChangeThemePayload, ChildMfeBridge, ConcurrentMountStrategy, ContainerHooks, DomainContext, EndpointDescriptor, EndpointOptions, EventHandler, EventSourceLike, ExclusiveMountStrategy, Extension, ExtensionDomain, ExtensionDomainImplementation, ExtensionDomainImplementationFactory, ExtensionMounter, ExtensionPresentation, ExtensionRegistrationState, FRONTX_ACTION_LOAD_EXT, FRONTX_ACTION_MOUNT_EXT, FRONTX_ACTION_UNMOUNT_EXT, FRONTX_MFE_ENTRY_MF, FRONTX_OVERLAY_DOMAIN, FRONTX_POPUP_DOMAIN, FRONTX_SCREEN_DOMAIN, FRONTX_SCREEN_EXTENSION_TYPE, FRONTX_SHARED_PROPERTY_LANGUAGE, FRONTX_SHARED_PROPERTY_THEME, FRONTX_SIDEBAR_DOMAIN, FooterConfig, FooterState, FrontXApp, FrontXAppBuilder, FrontXConfig, FrontXPlugin, FrontXStore, HeaderConfig, HeaderState, HeaderUser, I18nConfig, I18nRegistry, I18nRegistryImpl, I18nRegistryType, JSONSchema, JsonCompatible, JsonObject, JsonPrimitive, JsonValue, LAYOUT_SLICE_NAME, Language, LanguageDisplayMode, LanguageMetadata, LayoutDomain, LayoutDomainReducers, LayoutDomainState, LayoutState, LifecycleHook, LifecycleStage, LoadExtPayload, MOCK_PLUGIN, MenuItem, MenuState, MfManifest, MfManifestAssets, MfManifestBuildInfo, MfManifestMetaData, MfManifestRemoteEntry, MfManifestShared, MfeBridgeFactory, MfeEntry, MfeEntryLifecycle, MfeEntryMF, MfeHandler, MfeHandlerMF, MfeMountContext, MfeRegistry, MfeRegistryConfig, MfeRegistryFactory, MfeState, MockEventSource, MockEvents, MockMap, MockState, MockTogglePayload, MountExtPayload, MountStrategy, MutationDescriptor, OptionalMountStrategy, OverlayConfig, OverlayState, ParameterizedEndpointDescriptor, ParentMfeBridge, PluginClass, PluginFactory, PluginLifecycle, PluginProvides, PopupConfig, PopupSliceState, PopupState, Preset, Presets, ProtocolClass, ProtocolPluginType, ReducerPayload, RegisterExtensionPayload, RestEndpointProtocol, RestMockConfig, RestMockPlugin, RestPlugin, RestPluginHooks, RestPluginWithConfig, RestProtocol, RestProtocolConfig, RestRequestContext, RestResponseContext, RestShortCircuitResponse, RootState, RootStateWithLayout, SUPPORTED_LANGUAGES, ScreenExtension, SetLanguagePayload, SharedProperty, ShortCircuitResponse, ShowPopupPayload, SidebarPosition, SidebarState, SliceObject, SseConnectContext, SseMockConfig, SseMockEvent, SseMockPlugin, SsePlugin, SsePluginHooks, SsePluginWithConfig, SseProtocol, SseProtocolConfig, SseShortCircuitResponse, SseStreamProtocol, StreamDescriptor, StreamStatus, Subscription, TENANT_SLICE_NAME, Tenant, TenantChangedPayload, TenantClearedPayload, TenantEvents, TenantState, TextDirection, ThemeConfig, ThemeRegistry, TranslationDictionary, TranslationLoader, TranslationMap, TypeSystemPlugin, UnmountExtPayload, UnregisterExtensionPayload, apiRegistry, auth, changeTenant, clearTenant, clearTenantAction, clearUser, closeAllPopups, closePopup, closeTopPopup, createFrontX, createFrontXApp, createI18nRegistry, createShadowRoot, createSlice, createStore, createThemeRegistry, effects, extensionScreenSchema, extractGtsPackage, footerActions, footerSlice, frontxApiTransport, getLanguageMetadata, getStore, gtsPlugin, hasSlice, headerActions, headerSlice, hideOverlay, i18n, i18nRegistry, initMockEffects, initTenantEffects, injectCssVariables, isMockPlugin, isRestShortCircuit, isShortCircuit, isSseShortCircuit, languageSchema, layout, layoutDomainReducers, layoutReducer, loadExtension, menuActions, menuSlice, mfeRegistryFactory, microfrontends, mock, mockActions, mockSlice, mountExtension, openPopup, overlayActions, overlayDomain, overlaySlice, popupActions, popupDomain, popupSlice, presets, queryCache, queryCacheShared, registerExtension, registerSlice, screenDomain, selectExtensionError, selectExtensionState, selectMountedExtensions, selectRegisteredExtensions, setFooterConfig, setFooterVisible, setHeaderLoading, setMenuCollapsed, setMenuConfig, setMenuItems, setMenuVisible, setMockEnabled, setOverlayVisible, setSidebarCollapsed, setSidebarConfig, setSidebarContent, setSidebarPosition, setSidebarTitle, setSidebarVisible, setSidebarWidth, setTenant, setTenantLoading, setTenantLoadingState, setUser, showOverlay, sidebarActions, sidebarDomain, sidebarSlice, subscribeQueryCacheRuntimeChanged, tenantActions, tenantReducer, tenantSlice, themeSchema, themes, toggleMenu, toggleMockMode, toggleSidebar, unmountExtension, unregisterExtension } from '@gears-frontx/framework';
+import { M as MutationCallbackContext, Q as QueryCache } from './testing-Dlmfu6tE.cjs';
+export { a as QueryCacheInvalidateFilters, b as QueryCacheState, i as invalidateQueryCacheForApp } from './testing-Dlmfu6tE.cjs';
 import { TypedUseSelectorHook } from 'react-redux';
+import '@tanstack/react-query';
+import '@gears-frontx/framework/testing';
 
 /**
- * HAI3 Provider - Main provider component for HAI3 applications
+ * FrontX Provider - Main provider component for FrontX applications
  *
  * React Layer: L3 (Depends on @gears-frontx/framework)
+ *
+ * Query cache lifecycle is owned by the queryCache() framework plugin (L2).
+ * FrontXProvider reads the plugin-owned QueryClient from the app and mounts the
+ * internal React provider around the tree when it is available.
  */
 
 /**
- * HAI3 Provider Component
+ * FrontX Provider Component
  *
- * Provides the HAI3 application context to all child components.
- * Creates the HAI3 app instance with the full preset by default.
+ * Provides the FrontX application context to all child components.
+ * Creates the FrontX app instance with the full preset by default.
  *
  * @example
  * ```tsx
  * // Default - creates app with full preset
- * <HAI3Provider>
+ * <FrontXProvider>
  *   <App />
- * </HAI3Provider>
+ * </FrontXProvider>
  *
  * // With configuration
- * <HAI3Provider config={{ devMode: true }}>
+ * <FrontXProvider config={{ devMode: true }}>
  *   <App />
- * </HAI3Provider>
+ * </FrontXProvider>
  *
  * // With pre-built app
- * const app = createHAI3().use(screensets()).use(microfrontends()).build();
- * <HAI3Provider app={app}>
+ * const app = createFrontX().use(queryCache()).build();
+ * <FrontXProvider app={app}>
  *   <App />
- * </HAI3Provider>
+ * </FrontXProvider>
  *
  * // With MFE bridge (for MFE components)
- * <HAI3Provider mfeBridge={{ bridge, extensionId, domainId }}>
+ * <FrontXProvider mfeBridge={{ bridge, extensionId, domainId }}>
+ *   <MyMfeApp />
+ * </FrontXProvider>
+ *
+ * // QueryCache is resolved from the app's plugin composition
+ * <FrontXProvider app={app}>
  *   <MyMfeApp />
- * </HAI3Provider>
+ * </FrontXProvider>
  * ```
  */
-declare const HAI3Provider: React__default.FC<HAI3ProviderProps>;
+declare const FrontXProvider: React__default.FC<FrontXProviderProps>;
+
+/**
+ * FrontX Context
+ * Holds the FrontX app instance for the application.
+ */
+declare const FrontXContext: React.Context<FrontXApp | null>;
+/**
+ * Use the FrontX context.
+ * Throws if used outside of FrontXProvider.
+ *
+ * @returns The FrontX app instance
+ */
+declare function useFrontX(): FrontXApp;
+
+/**
+ * useApiQuery - Declarative data fetching hook
+ *
+ * Accepts an EndpointDescriptor from @gears-frontx/api and returns a Gears FrontX-owned
+ * ApiQueryResult. AbortSignal for request cancellation is threaded automatically
+ * through the shared QueryClient integration.
+ *
+ * Cache config cascade: component overrides > descriptor defaults > plugin defaults.
+ * Omit overrides to rely on the descriptor's staleTime/gcTime, which in turn
+ * fall back to the plugin-level query-cache defaults.
+ */
+
+/** Per-call cache overrides. Cascade: these > descriptor > plugin defaults. */
+interface ApiQueryOverrides {
+    /** Override staleTime for this specific call site. */
+    staleTime?: number;
+    /** Override gcTime for this specific call site. */
+    gcTime?: number;
+}
+declare function useApiQuery<TData = unknown, TError = Error>(descriptor: EndpointDescriptor<TData>, overrides?: ApiQueryOverrides): ApiQueryResult<TData, TError>;
+
+/**
+ * useApiInfiniteQuery - Declarative paginated data fetching hook
+ *
+ * Accepts an initial EndpointDescriptor plus descriptor resolvers for adjacent
+ * pages. Each page remains a standard service descriptor so MFE code does not
+ * need raw TanStack query keys or query functions.
+ */
+
+interface ApiInfiniteQueryPageContext<TPage> {
+    page: TPage;
+    pages: readonly TPage[];
+    descriptor: EndpointDescriptor<TPage>;
+    descriptors: readonly EndpointDescriptor<TPage>[];
+}
+interface ApiInfiniteQueryOptions<TPage> extends ApiQueryOverrides {
+    /** Descriptor for the first page in the sequence. */
+    initialPage: EndpointDescriptor<TPage>;
+    /**
+     * Resolve the next page descriptor from the current page payload.
+     * Return undefined when there is no next page.
+     */
+    getNextPage: (context: ApiInfiniteQueryPageContext<TPage>) => EndpointDescriptor<TPage> | undefined;
+    /**
+     * Resolve the previous page descriptor from the current first page payload.
+     * Return undefined when backward pagination is not available.
+     */
+    getPreviousPage?: (context: ApiInfiniteQueryPageContext<TPage>) => EndpointDescriptor<TPage> | undefined;
+    /** Optional TanStack maxPages passthrough for bounded page windows. */
+    maxPages?: number;
+}
+declare function useApiInfiniteQuery<TPage = unknown, TError = Error>(options: ApiInfiniteQueryOptions<TPage>): ApiInfiniteQueryResult<TPage, TError>;
+
+/**
+ * useApiMutation - Declarative mutation hook with restricted QueryCache injection
+ *
+ * Accepts { endpoint: MutationDescriptor, callbacks } and returns a Gears FrontX-owned
+ * ApiMutationResult. Supports optimistic updates, rollback, and cache invalidation
+ * through the QueryCache interface injected into each callback.
+ *
+ * Optimistic update pattern:
+ *   onMutate  -> cancel outgoing refetches, snapshot via queryCache.get,
+ *                apply optimistic data via queryCache.set, return snapshot
+ *   onError   -> restore snapshot via queryCache.set(key, context.snapshot)
+ *   onSettled -> invalidate to refetch authoritative state
+ *
+ * TanStack Query is used internally only and is NOT re-exported.
+ * MFEs interact with the cache through QueryCache, not the raw QueryClient.
+ */
 
 /**
- * HAI3 Context
- * Holds the HAI3 app instance for the application.
+ * Options for useApiMutation.
+ *
+ * Each callback receives { queryCache } as an additional final parameter,
+ * providing controlled access to the shared cache without exposing the
+ * raw QueryClient. TContext is the return type of onMutate, passed as
+ * context to onSuccess, onError, and onSettled.
  */
-declare const HAI3Context: React.Context<HAI3App | null>;
+type UseApiMutationOptions<TData = unknown, TError = Error, TVariables = void, TContext = unknown> = {
+    endpoint: MutationDescriptor<TData, TVariables>;
+    cancelOnSupersede?: boolean;
+    abortOnUnmount?: boolean;
+    onMutate?: (variables: TVariables, ctx: MutationCallbackContext) => Promise<TContext> | TContext;
+    onSuccess?: (data: TData, variables: TVariables, context: TContext | undefined, ctx: MutationCallbackContext) => unknown;
+    onError?: (error: TError, variables: TVariables, context: TContext | undefined, ctx: MutationCallbackContext) => unknown;
+    onSettled?: (data: TData | undefined, error: TError | null, variables: TVariables, context: TContext | undefined, ctx: MutationCallbackContext) => unknown;
+};
+declare function useApiMutation<TData = unknown, TError = Error, TVariables = void, TContext = unknown>(options: UseApiMutationOptions<TData, TError, TVariables, TContext>): ApiMutationResult<TData, TError, TVariables>;
+
 /**
- * Use the HAI3 context.
- * Throws if used outside of HAI3Provider.
+ * Declarative RBAC guard component.
  *
- * @returns The HAI3 app instance
+ * Pessimistic: renders `denied` (or `loading` if provided) until an explicit
+ * 'allow' decision arrives from app.auth.canAccess. Only renders `allowed`
+ * after a confirmed allow.
+ *
+ * Example:
+ *   <CanAccess
+ *     query={{ action: AppAction.InvoicesRead, resource: ResourceKind.Invoice }}
+ *     allowed={<InvoiceList />}
+ *     denied={<AccessDenied />}
+ *     loading={<Spinner />}
+ *   />
  */
-declare function useHAI3(): HAI3App;
+declare function CanAccess<TRecord extends AccessRecord = AccessRecord>({ query, allowed, denied, loading, }: CanAccessProps<TRecord>): ReactElement | null;
 
 /**
  * useAppDispatch Hook - Type-safe dispatch hook
@@ -225,12 +344,165 @@ declare function useFormatters(): UseFormattersReturn;
  */
 declare function useTheme(): UseThemeReturn;
 
+/**
+ * useApiSuspenseQuery - Suspense declarative data fetching hook
+ *
+ * Mirrors useApiQuery but integrates with React Suspense so the initial load is
+ * handled by a Suspense boundary.
+ */
+
+declare function useApiSuspenseQuery<TData = unknown, TError = Error>(descriptor: EndpointDescriptor<TData>, overrides?: ApiQueryOverrides): ApiSuspenseQueryResult<TData, TError>;
+
+/**
+ * useApiSuspenseInfiniteQuery - Suspense paginated data fetching hook
+ *
+ * Mirrors useApiInfiniteQuery but integrates with React Suspense so the initial
+ * page load is handled by a Suspense boundary while pagination stays
+ * descriptor-driven.
+ */
+
+declare function useApiSuspenseInfiniteQuery<TPage = unknown, TError = Error>(options: ApiInfiniteQueryOptions<TPage>): ApiSuspenseInfiniteQueryResult<TPage, TError>;
+
+/**
+ * useApiStream - Declarative SSE streaming hook
+ *
+ * Accepts a StreamDescriptor from @gears-frontx/api and returns the latest
+ * event, accumulated events, connection status, and a manual disconnect
+ * function.
+ *
+ * @example
+ * ```tsx
+ * const { data, events, status, error } = useApiStream(
+ *   service.messageStream,
+ *   { mode: 'latest' }   // default — data holds last event
+ * );
+ *
+ * // Accumulate all events
+ * const { events, status } = useApiStream(service.messageStream, { mode: 'accumulate' });
+ * ```
+ */
+
+/** Configuration options for useApiStream. */
+interface ApiStreamOptions {
+    /**
+     * `'latest'` (default) — `data` holds the most recent event.
+     * `'accumulate'` — `events` holds all received events in order.
+     */
+    mode?: 'latest' | 'accumulate';
+    /** When false the connection is deferred (no connect on mount). Default true. */
+    enabled?: boolean;
+}
+/** Return type of useApiStream. */
+interface ApiStreamResult<TEvent> {
+    /** Latest event payload, set in both modes — `undefined` until the first event and after each connect attempt resets it. */
+    data: TEvent | undefined;
+    /** All received events when `mode: 'accumulate'`; empty array in `'latest'` mode. */
+    events: TEvent[];
+    /** Connection lifecycle status. */
+    status: StreamStatus;
+    /** Last connect error — set when a connect attempt rejects, cleared when the next attempt starts. */
+    error: Error | null;
+    /** Manually close the connection. */
+    disconnect: () => void;
+}
+/**
+ * Manages the status lifecycle for a single SSE stream connection.
+ *
+ * **Status values**
+ * - `'idle'` — no connection is being attempted. This is the initial status
+ *   before the first connect effect runs, and it is ordinarily the status
+ *   while `enabled` is `false`. Consumers must not assume `'idle'` means "never
+ *   connected" — a stream that is disabled after having connected returns to
+ *   `'idle'` too, and `data`/`events` from the earlier connection are not
+ *   cleared by that transition alone (they are cleared by mode/key changes,
+ *   see below).
+ * - `'connecting'` — `descriptor.connect()` has been called and its promise
+ *   has not yet settled.
+ * - `'connected'` — set both when `connect()` resolves (unless a disconnect
+ *   was requested while it was pending) and, independently, whenever the
+ *   `onEvent` callback delivers a new event. Because every event re-asserts
+ *   `'connected'`, this status also serves as "still receiving events."
+ * - `'disconnected'` — reached via any of: the descriptor's `onComplete`
+ *   callback firing (the stream ended normally), `connect()` rejecting while
+ *   a disconnect was requested concurrently, or the manual `disconnect()`
+ *   function being called. `disconnect()` has no `enabled` guard: called
+ *   while the stream is disabled it still sets `'disconnected'`, which
+ *   persists until the next connect-effect run.
+ * - `'error'` — `connect()` rejected and no disconnect was requested while it
+ *   was pending. `error` holds the rejection, coerced to an `Error` if it
+ *   wasn't one already.
+ *
+ * **Transitions**
+ * - Mount / `enabled` becomes `true` / `descriptor.key` or `mode` changes:
+ *   `data`, `events`, and `error` are reset, then status goes to
+ *   `'connecting'` and `connect()` is called.
+ * - `enabled` becomes `false` (or starts `false`): status is forced to
+ *   `'idle'` and `connect()` is never called; no other field is reset by
+ *   this transition alone.
+ * - Unmount, `descriptor.key` change, `mode` change, or `enabled` flipping to
+ *   `false` while connected or connecting: the previous connection is torn
+ *   down via `descriptor.disconnect()` once its `connect()` promise settles
+ *   (or immediately skipped if it rejected). All four share the same cleanup
+ *   path: the effect's cleanup runs on every dependency change and on unmount.
+ * - Calling `disconnect()`: if a connection id is already resolved, it is
+ *   disconnected immediately and status becomes `'disconnected'`. If
+ *   `connect()` is still pending, the request is recorded and honored when
+ *   the promise settles — the newly resolved connection is torn down instead
+ *   of being adopted, and status is `'disconnected'`. One caveat:
+ *   `disconnect()` does not cancel the event callback, so a buffered or
+ *   in-flight event landing after the call re-asserts `'connected'` — and in
+ *   the pending-connect case the settle handler tears the connection down
+ *   without touching status, so that stray `'connected'` persists.
+ * - Stream completion while `connect()` is still pending: the current
+ *   implementation lets `onComplete` set `'disconnected'`, then the settle
+ *   handler adopts the connection id and re-asserts `'connected'` anyway.
+ *   This is known current behavior, not a durable guarantee: a pending
+ *   upstream derived-status rewrite is expected to remove this transition.
+ *
+ * `enabled` (default `true`) is the only way to defer connecting past mount;
+ * flipping it back to `true` re-runs the same connect sequence as a fresh
+ * mount would.
+ */
+declare function useApiStream<TEvent>(descriptor: StreamDescriptor<TEvent>, options?: ApiStreamOptions): ApiStreamResult<TEvent>;
+
+/**
+ * Exposes the sanctioned imperative cache API for app and MFE code without
+ * leaking the raw QueryClient.
+ *
+ * Preferred usage:
+ * - useApiQuery() for declarative reads
+ * - useApiMutation() for writes
+ * - useQueryCache() for controlled imperative cache inspection and invalidation
+ */
+declare function useQueryCache(): QueryCache;
+
+/**
+ * Declarative RBAC guard hook.
+ *
+ * Pessimistic: `allow` is false until an explicit 'allow' decision arrives.
+ * Aborts the in-flight canAccess call on unmount and on query change.
+ *
+ * State machine:
+ *   mount               -> Pending (allow=false, isResolving=true)
+ *   Pending -> 'allow'  -> Allowed (allow=true,  isResolving=false)
+ *   Pending -> 'deny'   -> Denied  (allow=false, isResolving=false)
+ *   Pending -> error    -> Denied  (allow=false, isResolving=false)
+ *   Allowed -> query-change -> Pending  (re-pessimize)
+ *   Denied  -> query-change -> Pending  (re-pessimize)
+ */
+declare function useCanAccess<TRecord extends AccessRecord = AccessRecord>(query: AccessQuery<TRecord>): UseCanAccessResult;
+
 /**
  * MFE Provider - Provides MFE context to child components
  *
  * Wraps MFE components with bridge and metadata.
  * Used by the MFE mounting system.
  *
+ * MfeProvider does not create or own the shared QueryClient. When the host uses
+ * queryCache() and the child app uses queryCacheShared(), overlapping queries
+ * (same query key) are deduplicated and cached once across MFE boundaries.
+ * Each MFE still uses its own apiRegistry and service instances in queryFn.
+ *
  * React Layer: L3 (Depends on @gears-frontx/framework)
  */
 
@@ -283,7 +555,7 @@ declare const MfeProvider: React__default.FC<MfeProviderProps>;
  *   // bridge.executeActionsChain(chain);
  *   // bridge.subscribeToProperty(propertyTypeId, callback);
  *
- *   return <div>Domain: {bridge.domainId}</div>;
+ *   return <div>Domain: {bridge.extDomainId}</div>;
  * }
  * ```
  */
@@ -364,7 +636,7 @@ declare function useHostAction<TPayload extends Record<string, unknown> = Record
 /**
  * Hook for observing extensions registered for a domain.
  *
- * Subscribes to the HAI3 store to detect registration state changes,
+ * Subscribes to the FrontX store to detect registration state changes,
  * and returns the current list of extensions for the specified domain.
  *
  * @param domainId - Domain ID to query extensions for
@@ -387,6 +659,51 @@ declare function useHostAction<TPayload extends Record<string, unknown> = Record
  */
 declare function useDomainExtensions(domainId: string): Extension[];
 
+/**
+ * useMountedExtensions Hook - Mounted extension observation for any domain
+ *
+ * Domain-agnostic hook that returns the currently-mounted Extension instances
+ * for any registered domain, including multi-mount domains backed by
+ * ConcurrentMountStrategy.
+ *
+ * React Layer: L3
+ */
+
+/**
+ * Hook for observing the currently-mounted extensions in any domain.
+ *
+ * Subscribes to the FrontX store to detect mount state changes, and returns
+ * the array of Extension instances currently mounted in the specified domain.
+ *
+ * Pairs with getMountedExtensions(domainId) on the registry and resolves each
+ * mounted extension ID to its Extension instance. IDs that have been unregistered
+ * concurrently (race against unregister) are filtered out.
+ *
+ * Returns a referentially stable array when the underlying ID list is unchanged.
+ *
+ * For multi-mount domains (ConcurrentMountStrategy), may return more than one entry.
+ * For single-mount domains (ExclusiveMountStrategy), the returned array has at most one entry.
+ *
+ * @param domainId - Domain ID to query mounted extensions for
+ * @returns Array of Extension instances currently mounted in the domain
+ *
+ * @example
+ * ```tsx
+ * function MountedWidgets() {
+ *   const mounted = useMountedExtensions('gts.frontx.mfes.ext.domain.v1~frontx.screensets.layout.sidebar.v1');
+ *
+ *   return (
+ *     <ul>
+ *       {mounted.map(ext => (
+ *         <li key={ext.id}>{ext.id}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+declare function useMountedExtensions(domainId: string): Extension[];
+
 /**
  * useRegisteredPackages Hook - Registered GTS packages subscription
  *
@@ -398,7 +715,7 @@ declare function useDomainExtensions(domainId: string): Extension[];
 /**
  * Hook for observing registered GTS packages.
  *
- * Subscribes to the HAI3 store to detect registration state changes,
+ * Subscribes to the FrontX store to detect registration state changes,
  * and returns the current list of GTS packages extracted from registered
  * extensions.
  *
@@ -406,7 +723,7 @@ declare function useDomainExtensions(domainId: string): Extension[];
  * This hook uses `useSyncExternalStore` with `app.store.subscribe`, which
  * fires on any Redux dispatch. Since `registerExtension()` dispatches to
  * the mfe store slice, the subscription WILL trigger when packages change.
- * The `getSnapshot` function calls `screensetsRegistry.getRegisteredPackages()`
+ * The `getSnapshot` function calls `mfeRegistry.getRegisteredPackages()`
  * which reads the private `packages` Map. This works because every package
  * map mutation (in registerExtension/unregisterExtension) is always
  * accompanied by a store dispatch in the same serializer callback.
@@ -434,74 +751,66 @@ declare function useDomainExtensions(domainId: string): Extension[];
 declare function useRegisteredPackages(): string[];
 
 /**
- * useActivePackage Hook - Active GTS package subscription
- *
- * Subscribes to store changes and returns the GTS package of the currently
- * mounted screen extension.
- *
- * React Layer: L3
- */
-/**
- * Hook for observing the active GTS package (the package of the currently
- * mounted screen extension).
- *
- * Subscribes to the HAI3 store to detect mount state changes, and returns
- * the GTS package extracted from the currently mounted screen extension's ID.
- *
- * Returns `undefined` if no screen extension is currently mounted.
- *
- * @returns GTS package string of the active screen extension, or undefined
- *
- * @example
- * ```tsx
- * function ActivePackageIndicator() {
- *   const activePackage = useActivePackage();
- *
- *   if (!activePackage) {
- *     return <div>No active screen</div>;
- *   }
- *
- *   return <div>Active package: {activePackage}</div>;
- * }
- * ```
- */
-declare function useActivePackage(): string | undefined;
-
-/**
- * Ref Container Provider
- *
- * Concrete ContainerProvider that wraps a React ref.
- * Created by React components (like ExtensionDomainSlot) for use
- * by framework-level domain registration code.
+ * Abstract base class for React-based MFE lifecycle implementations.
  *
- * @packageDocumentation
- */
-
-/**
- * Concrete ContainerProvider that wraps a React ref.
+ * Styling strategy:
+ * 1. adoptHostStylesIntoShadowRoot() clones all host <style> and <link> into the
+ *    shadow root, bringing the full compiled Tailwind CSS (including MFE utilities,
+ *    since the host's content paths cover src/mfe_packages/**).
+ * 2. injectBaseResets() adds box-model resets and :host defaults that aren't part
+ *    of Tailwind's compiled output but are needed for consistent rendering.
+ * 3. Subclasses may override initializeStyles() to inject additional CSS that is
+ *    not covered by the host stylesheet (e.g., MFE-specific @font-face rules).
  *
- * This provider reads the container element from a React ref at mount time.
- * It is designed to be created by React components but passed to domain
- * registration code (framework-level).
+ * Theme CSS variables are delivered via CSS inheritance from :root (Shadow DOM)
+ * or via MountManager injection (iframe). MFE lifecycles do NOT need to subscribe
+ * to theme changes or call applyThemeToShadowRoot.
  *
- * Usage pattern:
- * 1. React component creates a ref via `useRef<HTMLDivElement>(null)`
- * 2. Framework-level code creates `RefContainerProvider` wrapping the ref
- * 3. Framework-level code passes the provider to `registerDomain(domain, provider)`
- * 4. When mount_ext is dispatched, the provider returns `ref.current`
+ * Concrete subclasses must provide:
+ * - `renderContent(bridge)` - screen component rendering
  */
-declare class RefContainerProvider extends ContainerProvider {
-    private readonly containerRef;
-    constructor(containerRef: RefObject<HTMLDivElement>);
-    getContainer(_extensionId: string): Element;
-    releaseContainer(_extensionId: string): void;
+declare abstract class ThemeAwareReactLifecycle implements MfeEntryLifecycle<ChildMfeBridge> {
+    private readonly app;
+    private root;
+    constructor(app: FrontXApp);
+    mount(container: Element | ShadowRoot, bridge: ChildMfeBridge, mountContext?: MfeMountContext): void;
+    unmount(_container: Element | ShadowRoot): void;
+    /**
+     * Copy all inline <style> and <link rel="stylesheet"> from the host document
+     * into the shadow root so that Tailwind and component styles apply inside the MFE.
+     */
+    protected adoptHostStylesIntoShadowRoot(shadowRoot: ShadowRoot): void;
+    /**
+     * Box-model resets and :host defaults needed inside every shadow root.
+     * These aren't part of Tailwind's compiled output but are required for
+     * consistent rendering across browsers.
+     */
+    private injectBaseResets;
+    /**
+     * Hook for subclasses to inject additional CSS not covered by the adopted host
+     * stylesheet (e.g., MFE-specific @font-face rules or custom animations).
+     * No-op by default: host styles adopted in adoptHostStylesIntoShadowRoot()
+     * already include all Tailwind utilities compiled from MFE source files.
+     */
+    protected initializeStyles(_container: Element | ShadowRoot): void;
+    /**
+     * Return the screen-specific React component tree.
+     */
+    protected abstract renderContent(bridge: ChildMfeBridge): React__default.ReactNode;
 }
 
 /**
  * Extension Domain Slot Component
  *
- * React component that renders extensions within a domain slot.
- * Manages extension lifecycle (mount/unmount) and provides rendering context.
+ * Per-domain React component that provides the DOM root for a registered domain.
+ * Delegates root attachment to the per-domain ExtensionMounter obtained from the
+ * registry. What extensions live inside the root is a domain-policy concern (the
+ * active MountStrategy plus the domain implementation's ContainerHooks), not a
+ * slot-API concern.
+ *
+ * The slot is uniform across all cardinalities (Exclusive / Optional / Concurrent).
+ * Mount and unmount actions are dispatched by the host application via
+ * registry.executeActionsChain — NOT by this component.
  *
  * @packageDocumentation
  */
@@ -511,57 +820,47 @@ declare class RefContainerProvider extends ContainerProvider {
  */
 interface ExtensionDomainSlotProps {
     /**
-     * The screensets registry instance
+     * The screensets registry instance.
      */
-    registry: ScreensetsRegistry;
+    registry: MfeRegistry;
     /**
-     * The domain ID for this slot
+     * The domain ID for this slot.
      */
     domainId: string;
     /**
-     * The extension ID to render in this slot
-     */
-    extensionId: string;
-    /**
-     * Optional CSS class name for the container
+     * Optional CSS class name for the root container div.
      */
     className?: string;
     /**
-     * Optional callback when extension is mounted
+     * Optional callback invoked after mounter.attach(element) returns.
+     * Receives the root element that was attached.
      */
-    onMounted?: (bridge: ParentMfeBridge) => void;
+    onAttached?: (root: Element) => void;
     /**
-     * Optional callback when extension is unmounted
+     * Optional callback invoked after mounter.detach() returns on cleanup.
      */
-    onUnmounted?: () => void;
+    onDetached?: () => void;
     /**
-     * Optional error callback
-     */
-    onError?: (error: Error) => void;
-    /**
-     * Optional loading component
+     * Optional loading placeholder rendered before the mounter has been attached.
+     * Defaults to null (no visual placeholder).
      */
     loadingComponent?: React__default.ReactNode;
-    /**
-     * Optional error component renderer
-     */
-    errorComponent?: (error: Error) => React__default.ReactNode;
 }
 /**
  * Extension Domain Slot Component
  *
- * Renders an extension within a domain slot. Manages the extension lifecycle:
- * - Mounts the extension on component mount
- * - Unmounts the extension on component unmount
- * - Handles loading and error states
+ * Renders a single root `<div>` per domain instance. On ref-attach, resolves the
+ * per-domain mounter via registry.getMounter(domainId) and calls mounter.attach(element).
+ * On cleanup, calls mounter.detach() which mass-unmounts every currently-mounted
+ * extension in the domain so no orphan DOM trees or slice/registry desync remain.
  *
  * @example
  * ```tsx
  * <ExtensionDomainSlot
  *   registry={registry}
- *   domainId="gts.frontx.mfes.ext.domain.v1~frontx.screensets.layout.sidebar.v1"
- *   extensionId="gts.frontx.mfes.ext.extension.v1~myapp.sidebar.widget.v1"
- *   className="sidebar-slot"
+ *   domainId={FRONTX_SCREEN_DOMAIN}
+ *   loadingComponent={<Loading />}
+ *   onAttached={(root) => console.log('Root attached:', root)}
  * />
  * ```
  */
@@ -571,7 +870,7 @@ declare function ExtensionDomainSlot(props: ExtensionDomainSlotProps): React__de
  * @gears-frontx/react - React Bindings
  *
  * This package provides:
- * - HAI3Provider context provider
+ * - FrontXProvider context provider
  * - Type-safe hooks for state and actions
  * - MFE context, hooks, and components
  *
@@ -587,4 +886,4 @@ interface EventPayloadMap extends EventPayloadMap$1 {
  */
 declare const eventBus: EventBus<EventPayloadMap>;
 
-export { type EventPayloadMap, ExtensionDomainSlot, type ExtensionDomainSlotProps, HAI3Context, HAI3Provider, HAI3ProviderProps, MfeContextValue, MfeProvider, type MfeProviderProps, RefContainerProvider, UseFormattersReturn, UseScreenTranslationsReturn, UseThemeReturn, UseTranslationReturn, eventBus, useActivePackage, useAppDispatch, useAppSelector, useDomainExtensions, useFormatters, useHAI3, useHostAction, useMfeBridge, useRegisteredPackages, useScreenTranslations, useSharedProperty, useTheme, useTranslation };
+export { type ApiInfiniteQueryOptions, type ApiInfiniteQueryPageContext, ApiInfiniteQueryResult, ApiMutationResult, type ApiQueryOverrides, ApiQueryResult, type ApiStreamOptions, type ApiStreamResult, ApiSuspenseInfiniteQueryResult, ApiSuspenseQueryResult, CanAccess, CanAccessProps, type EventPayloadMap, ExtensionDomainSlot, type ExtensionDomainSlotProps, FrontXContext, FrontXProvider, FrontXProviderProps, MfeContextValue, MfeProvider, type MfeProviderProps, MutationCallbackContext, QueryCache, ThemeAwareReactLifecycle, type UseApiMutationOptions, UseCanAccessResult, UseFormattersReturn, UseScreenTranslationsReturn, UseThemeReturn, UseTranslationReturn, eventBus, useApiInfiniteQuery, useApiMutation, useApiQuery, useApiStream, useApiSuspenseInfiniteQuery, useApiSuspenseQuery, useAppDispatch, useAppSelector, useCanAccess, useDomainExtensions, useFormatters, useFrontX, useHostAction, useMfeBridge, useMountedExtensions, useQueryCache, useRegisteredPackages, useScreenTranslations, useSharedProperty, useTheme, useTranslation };