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

package/dist/index.d.cts

@@ -1,9 +1,9 @@
 import * as React from 'react';
 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 { 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-JtpziA_B.cjs';
+export { i as MfeContext, j as UseAppDispatchReturn, k as UseAppSelector, l as UseFrontXReturn, u as useMfeContext } from './types-JtpziA_B.cjs';
+import { FrontXApp, EndpointDescriptor, MutationDescriptor, AccessRecord, AppDispatch, RootState, TranslationMap, TranslationLoader, StreamStatus, StreamDescriptor, AccessQuery, ChildMfeBridge, MfeRegistry, Extension, MfeEntryLifecycle, MfeMountContext, 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, AuthEvents, AuthLoggedInPayload, AuthLoggedOutPayload, 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, 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, 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, RestPlugin, RestPluginHooks, RestPluginWithConfig, RestProtocol, RestProtocolConfig, RestRequestContext, RestResponseContext, RestShortCircuitResponse, RootState, RootStateWithLayout, SUPPORTED_LANGUAGES, ScreenExtension, SetLanguagePayload, SharedProperty, ShortCircuitResponse, ShowPopupPayload, SidebarPosition, SidebarState, SliceObject, SseConnectContext, 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, createI18nRegistry, createShadowRoot, createSlice, createStore, createThemeRegistry, effects, extractGtsPackage, footerActions, footerSlice, frontxApiTransport, getLanguageMetadata, getStore, gtsPlugin, hasSlice, headerActions, headerSlice, hideOverlay, i18n, i18nRegistry, initMockEffects, initTenantEffects, injectCssVariables, isMockPlugin, isRestShortCircuit, isShortCircuit, isSseShortCircuit, 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, 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, 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';
@@ -23,29 +23,19 @@ import '@gears-frontx/framework/testing';
 /**
  * FrontX Provider Component
  *
- * Provides the FrontX application context to all child components.
- * Creates the FrontX app instance with the full preset by default.
+ * Provides the FrontX application context to all child components. The app
+ * is built once per runtime by the caller (`createFrontX(...).build()`); the
+ * provider never creates or destroys one.
  *
  * @example
  * ```tsx
- * // Default - creates app with full preset
- * <FrontXProvider>
- *   <App />
- * </FrontXProvider>
- *
- * // With configuration
- * <FrontXProvider config={{ devMode: true }}>
- *   <App />
- * </FrontXProvider>
- *
- * // With pre-built app
  * const app = createFrontX().use(queryCache()).build();
  * <FrontXProvider app={app}>
  *   <App />
  * </FrontXProvider>
  *
  * // With MFE bridge (for MFE components)
- * <FrontXProvider mfeBridge={{ bridge, extensionId, domainId }}>
+ * <FrontXProvider app={app} mfeBridge={{ bridge, extensionId, domainId }}>
  *   <MyMfeApp />
  * </FrontXProvider>
  *
@@ -79,16 +69,36 @@ declare function useFrontX(): FrontXApp;
  *
  * 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.
+ * fall back to the plugin-level query-cache defaults, so a screen that remounts
+ * within staleTime paints from cache without refetching.
+ *
+ * Pass `enabled: false` to hold a query whose input is not known yet.
  */
 
-/** Per-call cache overrides. Cascade: these > descriptor > plugin defaults. */
-interface ApiQueryOverrides {
+/**
+ * Per-call cache overrides shared by every read hook.
+ * Cascade: these > descriptor > plugin defaults.
+ */
+interface ApiQueryCacheOverrides {
     /** Override staleTime for this specific call site. */
     staleTime?: number;
     /** Override gcTime for this specific call site. */
     gcTime?: number;
 }
+/** Per-call overrides for useApiSuspenseQuery. */
+interface ApiSuspenseQueryOverrides extends ApiQueryCacheOverrides {
+    /** A suspense query always runs; use useApiQuery to hold one back. */
+    enabled?: never;
+}
+/** Per-call overrides for useApiQuery. */
+interface ApiQueryOverrides extends ApiQueryCacheOverrides {
+    /**
+     * `false` keeps the query idle: it is not fetched automatically and
+     * `isLoading` stays false until it turns `true`. An explicit `refetch`
+     * still fetches. Defaults to `true`.
+     */
+    enabled?: boolean;
+}
 declare function useApiQuery<TData = unknown, TError = Error>(descriptor: EndpointDescriptor<TData>, overrides?: ApiQueryOverrides): ApiQueryResult<TData, TError>;
 
 /**
@@ -105,7 +115,8 @@ interface ApiInfiniteQueryPageContext<TPage> {
     descriptor: EndpointDescriptor<TPage>;
     descriptors: readonly EndpointDescriptor<TPage>[];
 }
-interface ApiInfiniteQueryOptions<TPage> extends ApiQueryOverrides {
+/** Options shared by useApiInfiniteQuery and useApiSuspenseInfiniteQuery. */
+interface ApiInfiniteQueryBaseOptions<TPage> extends ApiQueryCacheOverrides {
     /** Descriptor for the first page in the sequence. */
     initialPage: EndpointDescriptor<TPage>;
     /**
@@ -121,6 +132,18 @@ interface ApiInfiniteQueryOptions<TPage> extends ApiQueryOverrides {
     /** Optional TanStack maxPages passthrough for bounded page windows. */
     maxPages?: number;
 }
+/** Options for useApiSuspenseInfiniteQuery. */
+interface ApiSuspenseInfiniteQueryOptions<TPage> extends ApiInfiniteQueryBaseOptions<TPage> {
+    /** A suspense query always runs; use useApiInfiniteQuery to hold one back. */
+    enabled?: never;
+}
+interface ApiInfiniteQueryOptions<TPage> extends ApiInfiniteQueryBaseOptions<TPage> {
+    /**
+     * `false` keeps the query idle: no page is fetched until it turns `true`.
+     * Defaults to `true`.
+     */
+    enabled?: boolean;
+}
 declare function useApiInfiniteQuery<TPage = unknown, TError = Error>(options: ApiInfiniteQueryOptions<TPage>): ApiInfiniteQueryResult<TPage, TError>;
 
 /**
@@ -348,10 +371,11 @@ 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.
+ * handled by a Suspense boundary. A suspense query always runs, so there is no
+ * `enabled` override.
  */
 
-declare function useApiSuspenseQuery<TData = unknown, TError = Error>(descriptor: EndpointDescriptor<TData>, overrides?: ApiQueryOverrides): ApiSuspenseQueryResult<TData, TError>;
+declare function useApiSuspenseQuery<TData = unknown, TError = Error>(descriptor: EndpointDescriptor<TData>, overrides?: ApiSuspenseQueryOverrides): ApiSuspenseQueryResult<TData, TError>;
 
 /**
  * useApiSuspenseInfiniteQuery - Suspense paginated data fetching hook
@@ -361,15 +385,14 @@ declare function useApiSuspenseQuery<TData = unknown, TError = Error>(descriptor
  * descriptor-driven.
  */
 
-declare function useApiSuspenseInfiniteQuery<TPage = unknown, TError = Error>(options: ApiInfiniteQueryOptions<TPage>): ApiSuspenseInfiniteQueryResult<TPage, TError>;
+declare function useApiSuspenseInfiniteQuery<TPage = unknown, TError = Error>(options: ApiSuspenseInfiniteQueryOptions<TPage>): ApiSuspenseInfiniteQueryResult<TPage, TError>;
 
 /**
  * useApiStream - Declarative SSE streaming hook
  *
- * Accepts a StreamDescriptor from @gears-frontx/api and manages the EventSource
- * lifecycle: connects on mount, disconnects on unmount/descriptor change.
- * Returns the latest event, accumulated events, connection status, and
- * a manual disconnect function.
+ * Accepts a StreamDescriptor from @gears-frontx/api and returns the latest
+ * event, accumulated events, connection status, and a manual disconnect
+ * function.
  *
  * @example
  * ```tsx
@@ -395,17 +418,96 @@ interface ApiStreamOptions {
 }
 /** Return type of useApiStream. */
 interface ApiStreamResult<TEvent> {
-    /** Latest event payload (always set in both modes). */
+    /** 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;
-    /** Error if the connection failed. */
+    /** 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 status whenever
+ *   `enabled` is `false`, including on mount: a hook that mounts disabled
+ *   never reports anything but `'idle'` until `enabled` flips to `true`. A
+ *   hook that mounts enabled skips `'idle'` entirely — the status is set
+ *   during render, so its very first render already reports `'connecting'`.
+ *   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'` — a connection attempt is committed to but has not settled.
+ *   It is published during the render that turns the stream on, which is
+ *   before `descriptor.connect()` runs: the call is made from an effect after
+ *   that render commits. So `'connecting'` means "this stream is being
+ *   opened", not "the connect promise is pending" — for one render the two
+ *   differ, and a consumer that reads the status as proof a request is already
+ *   in flight is reading it too strongly.
+ * - `'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, but calling
+ *   it while the stream is disabled is not observable: the stored status moves
+ *   to `'disconnected'` while the published one stays `'idle'`, and flipping
+ *   `enabled` back to `true` sets `'connecting'` during that render, so the
+ *   stored `'disconnected'` is overwritten before it is ever returned.
+ * - `'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**
+ * - Mounting enabled, `enabled` becoming `true`, or `descriptor.key` / `mode`
+ *   changing while `enabled` is `true`: `data`, `events`, and `error` are reset
+ *   and status is set to `'connecting'` synchronously during render (not from
+ *   an effect); `connect()` is then called from an effect that runs after that
+ *   render commits.
+ * - `descriptor.key` or `mode` changing while `enabled` is `false`: `data`,
+ *   `events`, and `error` are reset all the same, since that reset is not gated
+ *   on `enabled`, but the status write is - so no `'connecting'` is written and
+ *   the published status stays `'idle'`; `connect()` is not called. The skipped
+ *   `'connecting'` is not owed later either: the change counts as handled when
+ *   it happens, so what publishes `'connecting'` is the subsequent flip of
+ *   `enabled` to `true`, once, for whichever key and mode are in force by then.
+ * - `enabled` becomes `false` (or starts `false`): the published status is
+ *   `'idle'` for as long as `enabled` stays `false` — it is derived from
+ *   `enabled` rather than written, so nothing a prior connection stored can
+ *   surface through it — 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>;
 
 /**
@@ -416,6 +518,11 @@ declare function useApiStream<TEvent>(descriptor: StreamDescriptor<TEvent>, opti
  * - useApiQuery() for declarative reads
  * - useApiMutation() for writes
  * - useQueryCache() for controlled imperative cache inspection and invalidation
+ *
+ * The returned handle is not bound to the cache scope (mock mode, tenant,
+ * session): it writes to whatever scope is current. A write after an await or
+ * inside a mutation callback must use the `queryCache` that callback receives,
+ * which drops writes once the scope changed since the mutation started.
  */
 declare function useQueryCache(): QueryCache;
 
@@ -498,7 +605,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>;
  * }
  * ```
  */
@@ -507,32 +614,94 @@ declare function useMfeBridge(): ChildMfeBridge;
 /**
  * useSharedProperty Hook - Shared property subscription
  *
- * Subscribes to shared property updates from the host.
+ * Subscribes to shared property updates from the host, either through the
+ * ambient MfeProvider context or through an explicitly supplied bridge.
  *
  * React Layer: L3
  */
+
 /**
- * Hook for subscribing to a shared property.
- *
- * Subscribes to property updates from the host and returns the current value.
- * Must be used within a MfeProvider (i.e., inside an MFE component).
- *
- * NOTE: This hook provides the interface and uses useSyncExternalStore with a stub subscription.
- * Full bridge subscription should be implemented when bridge methods are available.
- *
- * @param _propertyTypeId - Type ID of the shared property to subscribe to (currently unused)
- * @returns Current property value
- *
- * @example
+ * Options for {@link useSharedProperty}.
+ */
+interface UseSharedPropertyOptions<T> {
+    /**
+     * Bridge to read the property from, bypassing `MfeContext`.
+     *
+     * Pass this when the calling component never mounts `MfeProvider` (for
+     * example, a component that receives its bridge directly 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,
+     * matching the zero-argument form.
+     *
+     * `bridge` and `propertyTypeId` identify the subscription: changing either
+     * one unsubscribes from the old source and subscribes to the new one, and
+     * the returned value reflects the new source on the same render.
+     */
+    bridge?: ChildMfeBridge;
+    /**
+     * Value returned while the host has not published the property yet
+     * (`bridge.getProperty()` returns `undefined`).
+     *
+     * Only the `undefined` sentinel is substituted: a published `null` is a
+     * real value and is returned as-is. The host validates every published
+     * value against the property's schema before it reaches any MFE
+     * (`TypeSystemPlugin.register()` throws on a schema mismatch and the
+     * update is never stored or delivered), so no consumer-side filtering is
+     * needed -- `T` is simply the caller's declaration of that schema.
+     *
+     * `fallback` may be passed inline on every render; it does not affect the
+     * host subscription.
+     */
+    fallback?: T;
+}
+/**
+ * Subscribe to a shared property from the host.
+ *
+ * Two forms:
+ *
+ * 1. **Context form** -- `useSharedProperty(propertyTypeId)`. Reads the
+ *    bridge from `MfeContext` and throws if no `MfeProvider` is mounted.
+ * 2. **Options form** -- `useSharedProperty(propertyTypeId, options)`. Pass
+ *    `options.bridge` for components that never mount `MfeProvider`, and/or
+ *    `options.fallback` for a value to show until the host publishes one.
+ *    `options.bridge` may be omitted, in which case the hook still falls
+ *    back to `MfeContext`.
+ *
+ * Both forms read through `useSyncExternalStore`: the bridge is the store,
+ * `bridge.getProperty()` is the snapshot, so the first render already shows
+ * the host's current value, a publish between render and commit is picked
+ * up when React re-reads the snapshot after subscribing, and the value is
+ * tearing-protected under concurrent rendering.
+ *
+ * @param propertyTypeId - GTS type ID of the shared property to subscribe to
+ * @param options - Optional bridge override and fallback
+ * @returns The current property value; `T` when `options.fallback` is set,
+ *   otherwise `T | undefined`
+ *
+ * @example Context form (inside MfeProvider)
  * ```tsx
- * function MyMfeComponent() {
- *   const userData = useSharedProperty('gts.frontx.mfes.comm.shared_property.v1~myapp.user_data.v1');
+ * function ThemedComponent() {
+ *   const theme = useSharedProperty<{ primaryColor: string }>(THEME_PROPERTY_ID);
+ *   return <div style={{ color: theme?.primaryColor }} />;
+ * }
+ * ```
  *
- *   return <div>User: {userData?.name}</div>;
+ * @example Explicit bridge with fallback (no MfeProvider)
+ * ```tsx
+ * function StandaloneComponent({ bridge }: { bridge: ChildMfeBridge }) {
+ *   const label = useSharedProperty<string>(LABEL_PROPERTY_ID, {
+ *     bridge,
+ *     fallback: 'Untitled',
+ *   });
+ *   return <span>{label}</span>;
  * }
  * ```
  */
 declare function useSharedProperty<T = unknown>(propertyTypeId: string): T | undefined;
+declare function useSharedProperty<T>(propertyTypeId: string, options: UseSharedPropertyOptions<T> & {
+    fallback: T;
+}): T;
+declare function useSharedProperty<T = unknown>(propertyTypeId: string, options?: UseSharedPropertyOptions<T>): T | undefined;
 
 /**
  * useHostAction Hook - Host action requests
@@ -568,84 +737,64 @@ declare function useSharedProperty<T = unknown>(propertyTypeId: string): T | und
 declare function useHostAction<TPayload extends Record<string, unknown> = Record<string, unknown>>(actionTypeId: string): (payload?: TPayload) => void;
 
 /**
- * useDomainExtensions Hook - Domain extension list subscription
+ * useMfeRegistry Hook - Shared MfeRegistry access guard
  *
- * Subscribes to store changes to detect when extensions are registered or unregistered,
- * and returns the current list of extensions for a domain.
+ * Resolves the MFE-enabled registry off the FrontX app instance and throws a
+ * descriptive error when the `microfrontends()` plugin was not installed.
+ * Extracted so every registry-consuming hook shares one guard implementation
+ * instead of hand-rolling the same `if (!app.mfeRegistry)` check.
  *
  * React Layer: L3
  */
 
 /**
- * Hook for observing extensions registered for a domain.
+ * Hook for accessing the MFE-enabled registry off the current FrontX app.
  *
- * Subscribes to the FrontX store to detect registration state changes,
- * and returns the current list of extensions for the specified domain.
+ * Throws if the app was built without the `microfrontends()` plugin.
  *
- * @param domainId - Domain ID to query extensions for
- * @returns Array of extensions currently registered for the domain
+ * @returns The MFE-enabled registry
  *
  * @example
- * ```tsx
- * function SidebarExtensions() {
- *   const extensions = useDomainExtensions('gts.frontx.mfes.ext.domain.v1~frontx.screensets.layout.sidebar.v1');
- *
- *   return (
- *     <div>
- *       {extensions.map(ext => (
- *         <div key={ext.id}>{ext.id}</div>
- *       ))}
- *     </div>
- *   );
- * }
+ * ```ts
+ * const registry = useMfeRegistry();
  * ```
  */
-declare function useDomainExtensions(domainId: string): Extension[];
+declare function useMfeRegistry(): MfeRegistry;
 
 /**
- * useMountedExtensions Hook - Mounted extension observation for any domain
+ * useDomainExtensions Hook - Domain extension list subscription
  *
- * Domain-agnostic hook that returns the currently-mounted Extension instances
- * for any registered domain, including multi-mount domains backed by
- * ConcurrentMountStrategy.
+ * Subscribes to store changes to detect when extensions are registered or unregistered,
+ * and returns the current list of extensions for a domain.
  *
  * 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.
+ * Hook for observing extensions registered for a domain.
  *
- * For multi-mount domains (ConcurrentMountStrategy), may return more than one entry.
- * For single-mount domains (ExclusiveMountStrategy), the returned array has at most one entry.
+ * 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 mounted extensions for
- * @returns Array of Extension instances currently mounted in the domain
+ * @param domainId - Domain ID to query extensions for
+ * @returns Array of extensions currently registered for the domain
  *
  * @example
  * ```tsx
- * function MountedWidgets() {
- *   const mounted = useMountedExtensions('gts.frontx.mfes.ext.domain.v1~frontx.screensets.layout.sidebar.v1');
+ * function SidebarExtensions() {
+ *   const extensions = useDomainExtensions('gts.frontx.mfes.ext.domain.v1~frontx.screensets.layout.sidebar.v1');
  *
  *   return (
- *     <ul>
- *       {mounted.map(ext => (
- *         <li key={ext.id}>{ext.id}</li>
+ *     <div>
+ *       {extensions.map(ext => (
+ *         <div key={ext.id}>{ext.id}</div>
  *       ))}
- *     </ul>
+ *     </div>
  *   );
  * }
  * ```
  */
-declare function useMountedExtensions(domainId: string): Extension[];
+declare function useDomainExtensions(domainId: string): Array<Omit<Extension, 'route'>>;
 
 /**
  * useRegisteredPackages Hook - Registered GTS packages subscription
@@ -698,13 +847,32 @@ declare function useRegisteredPackages(): string[];
  *
  * 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/**).
+ *    front of the shadow root, bringing the full compiled Tailwind CSS (including
+ *    MFE utilities, since the host's content paths cover src-app/mfe_packages/**) and
+ *    the ui-kit component CSS (the host entry side-effect-imports
+ *    @gears-frontx/ui-kit so that CSS exists in the host document; the kit's
+ *    CSS-module class names are stable per kit version, so they match the
+ *    classes MFE bundles reference only while host and MFE install the same
+ *    kit version - the template-pin-drift policy check is what guarantees
+ *    that; a drifted MFE renders its kit components unstyled with no error).
+ *    Front, not back, so the MFE's own stylesheets
+ *    outrank them - see the method. Design tokens must therefore be full CSS
+ *    colors - both Tailwind utilities (var(--x)) and ui-kit component CSS
+ *    consume them directly.
  * 2. injectBaseResets() adds box-model resets and :host defaults that aren't part
- *    of Tailwind's compiled output but are needed for consistent rendering.
+ *    of Tailwind's compiled output but are needed for consistent rendering, and
+ *    positions them at the end of the shell-owned head - after the adopted block
+ *    and the isolation style, ahead of the MFE's own CSS.
  * 3. Subclasses may override initializeStyles() to inject additional CSS that is
  *    not covered by the host stylesheet (e.g., MFE-specific @font-face rules).
  *
+ * Every mount therefore leaves the same sequence - adopted host block, shadow
+ * isolation, base resets, then the MFE's stylesheets - so the shell's CSS is
+ * context and the MFE wins every specificity tie against all three shell blocks.
+ * Steps 1 and 2 both position what they own rather than appending beside it,
+ * because a remounted container arrives with its shadow root intact and the MFE's
+ * own stylesheet removed and re-appended around the remount - see each method.
+ *
  * 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.
@@ -717,16 +885,113 @@ declare abstract class ThemeAwareReactLifecycle implements MfeEntryLifecycle<Chi
     private root;
     constructor(app: FrontXApp);
     mount(container: Element | ShadowRoot, bridge: ChildMfeBridge, mountContext?: MfeMountContext): void;
-    unmount(_container: Element | ShadowRoot): void;
+    /**
+     * `Root.unmount()` itself is synchronous, but a nested `ExtensionDomainSlot`
+     * mounted anywhere in this root's own tree cannot make ITS cleanup
+     * synchronous too — its mounter's own `detach()` awaits per-extension
+     * unmounts. Collecting whatever that cleanup fire-and-forgets (through
+     * `domainTeardownCollector`, scoped to this one `Root.unmount()` call) and
+     * awaiting it here is what makes this method's own returned promise settle
+     * only once every nested domain this root owns has actually finished
+     * tearing down — never before. A root with no routed nested domain
+     * collects nothing, and this resolves exactly as before (a microtask after
+     * the synchronous unmount, same observable timing `void | Promise<void>`
+     * already allows).
+     */
+    unmount(_container: Element | ShadowRoot): Promise<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.
+     *
+     * The clones are inserted ahead of everything already in the shadow root, never
+     * appended, because adopted host styles are context rather than authority: where
+     * they and the MFE's own CSS declare the same property at equal specificity, the
+     * MFE has to win. Appending inverted that. `MfeHandlerMF` injects the MFE's
+     * compiled stylesheet into the shadow root before it calls mount, so an appended
+     * clone of the shell's Tailwind preflight - whose
+     * `button, [type='button'], [type='reset'], [type='submit']` rule sets
+     * `background-color: transparent` at specificity (0,1,0) - tied with
+     * `@gears-frontx/ui-kit`'s single-class button rule and won on document order,
+     * leaving every kit Button transparent until it was hovered.
+     *
+     * Inserting at the front rather than pushing MFE styles to the back is what makes
+     * the invariant hold for stylesheets that appear after mount too - a lazily
+     * imported component's CSS module, or whatever initializeStyles() adds - since
+     * those land behind the adopted block by construction.
+     *
+     * A cascade layer around the adopted CSS was the alternative and is rejected:
+     * layered rules lose to unlayered ones at *any* specificity, so a host utility
+     * class would stop overriding an MFE element selector. Document order keeps
+     * specificity in charge and only settles the ties.
+     *
+     * The block replaces its predecessor instead of stacking on it, the same
+     * upsert shape `injectStylesheet` and `injectCssVariables` use in
+     * `@gears-frontx/mfes`' shadow utilities, widened from one id-keyed node to a
+     * marked block. Replacement is required rather than tidy: `createShadowRoot`
+     * hands back an existing `element.shadowRoot` instead of attaching a new one,
+     * so remounting the same container runs this method again on a shadow root
+     * that already holds a full adopted block, and appending would grow it once
+     * per mount with no bound. It does not save re-resolving the cloned `<link>`s -
+     * every mount clones them afresh and the browser resolves each clone; what
+     * replacement buys is that the count stays at one block instead of one per
+     * mount.
+     *
+     * The block is rebuilt from the host head rather than left in place, because
+     * the head is not fixed: a lazily imported chunk adds stylesheets to it after
+     * the first mount, and the second mount has to pick those up.
+     *
+     * A `<style>` is copied into a new element that holds the host's CSS - see
+     * `cssToCopy` - and takes three things from the host element: `media`,
+     * without which a print-only host style applies on screen inside the MFE;
+     * `type`, which keeps the copy of a non-CSS element as inert as the original;
+     * and the nonce, without which a nonce-based CSP blocks the copy. The nonce is read from the `nonce` property, because
+     * browsers blank the attribute in a document served with a CSP header.
+     * Nothing else is carried over, because libraries look for their own
+     * attributes inside the shadow root: styled-components, rendering into it,
+     * puts its tag right after the last `style[data-styled]` there, so a copy of
+     * the host's tag would pull the MFE's rules ahead of the base resets and the
+     * MFE's own CSS. A `<link>` is a deep clone and is loaded from its `href`
+     * again.
+     *
+     * The fresh block goes in before the previous one comes out. Removing first
+     * leaves the shadow root with no host CSS at all, and everything between that
+     * removal and the insertion is synchronous work in this same task - so the gap
+     * never reaches a paint, but any code that reads computed styles from the tree
+     * in between sees an unstyled one. Inserting first costs one moment with two
+     * blocks present, which changes nothing: the old block is a clone of the same
+     * host head and loses every tie to the new one on document order anyway.
      */
     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.
+     *
+     * Reuses the node a previous mount left behind, exactly as `injectStylesheet`
+     * does in `@gears-frontx/mfes`' shadow utilities: a remount runs against a
+     * shadow root that `createShadowRoot` handed back intact, and appending a
+     * second copy would add one node per mount forever.
+     *
+     * Reuse alone is not enough, which is why the node is also positioned on every
+     * mount rather than left where the previous one sat. These resets are context
+     * like the adopted block is - `border-color: currentColor` on `*` is a 0-0-0
+     * declaration that beats an MFE preflight's own 0-0-0 reset purely on document
+     * order - so they have to stay ahead of the MFE's CSS, and where they land is
+     * not stable on its own. `MfeHandlerMF.wrapLifecycleWithStylesheets` removes the
+     * MFE's stylesheet on unmount and appends a fresh one before the next mount, so
+     * a node merely left in place ends up ahead of that stylesheet on a remount and
+     * behind it on the first mount: two different cascades for one component.
+     * Anchoring it to the end of the shell-owned head gives every mount the same
+     * order - adopted block, isolation, resets, MFE - which is also the order the
+     * adoption method's invariant is written against.
+     *
+     * With no shell-owned node to anchor to, the resets go to the front. That is the
+     * plain-`Element` container: no adopted block, no isolation style, and the MFE
+     * stylesheet already appended by the handler, so the front is again the only
+     * position that leaves the MFE winning ties.
+     *
+     * Looked up by attribute-selector form rather than `getElementById`, which
+     * `ShadowRoot` has but `Element` does not, and this hook takes either.
      */
     private injectBaseResets;
     /**
@@ -763,7 +1028,7 @@ declare abstract class ThemeAwareReactLifecycle implements MfeEntryLifecycle<Chi
  */
 interface ExtensionDomainSlotProps {
     /**
-     * The screensets registry instance.
+     * The MFE registry instance.
      */
     registry: MfeRegistry;
     /**
@@ -829,4 +1094,4 @@ interface EventPayloadMap extends EventPayloadMap$1 {
  */
 declare const eventBus: EventBus<EventPayloadMap>;
 
-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 };
+export { type ApiInfiniteQueryOptions, type ApiInfiniteQueryPageContext, ApiInfiniteQueryResult, ApiMutationResult, type ApiQueryOverrides, ApiQueryResult, type ApiStreamOptions, type ApiStreamResult, type ApiSuspenseInfiniteQueryOptions, ApiSuspenseInfiniteQueryResult, type ApiSuspenseQueryOverrides, ApiSuspenseQueryResult, CanAccess, CanAccessProps, type EventPayloadMap, ExtensionDomainSlot, type ExtensionDomainSlotProps, FrontXContext, FrontXProvider, FrontXProviderProps, MfeContextValue, MfeProvider, type MfeProviderProps, MutationCallbackContext, QueryCache, ThemeAwareReactLifecycle, type UseApiMutationOptions, UseCanAccessResult, UseFormattersReturn, UseScreenTranslationsReturn, type UseSharedPropertyOptions, UseThemeReturn, UseTranslationReturn, eventBus, useApiInfiniteQuery, useApiMutation, useApiQuery, useApiStream, useApiSuspenseInfiniteQuery, useApiSuspenseQuery, useAppDispatch, useAppSelector, useCanAccess, useDomainExtensions, useFormatters, useFrontX, useHostAction, useMfeBridge, useMfeRegistry, useQueryCache, useRegisteredPackages, useScreenTranslations, useSharedProperty, useTheme, useTranslation };