@ikonai/sdk-react-ui 1.0.56 → 1.0.58

package/app/connection-state-renderer.d.ts

@@ -14,25 +14,33 @@ export interface ConnectedRenderProps {
 }
 /**
  * Props for the ConnectionStateRenderer component.
+ *
+ * @deprecated Prefer {@link IkonApp} which renders the surface continuously and layers
+ * overlays on top of it. `ConnectionStateRenderer` remains as a back-compat shim for apps
+ * pinned to the old callback-per-state API.
  */
 export interface ConnectionStateRendererProps {
     connectionState: ConnectionState;
     error: string | null;
     isReady: boolean;
+    isConnectingSlow?: boolean;
     stores: ReadonlyMap<string, IkonUiStoreEntry> | undefined;
     registry: IkonUiRegistry | null;
     client: IkonClient | null;
     onAction: (actionId: string, payload: unknown) => void;
     /**
-     * Render when idle (not yet started connecting).
+     * @deprecated The runtime no longer emits `'idle'`; this callback never fires. The
+     * prop stays for source-compatibility with apps that already pass it.
      */
     renderIdle: () => ReactNode;
     /**
-     * Render when connecting (initial connection attempt).
+     * Render when connecting (initial connection attempt and the slow-connection
+     * threshold has not yet elapsed).
      */
     renderConnecting: () => ReactNode;
     /**
-     * Render when connection is taking longer than expected.
+     * Render when connection is taking longer than expected. Fires when
+     * `connectionState === 'connecting'` and `isConnectingSlow === true`.
      */
     renderConnectingSlow: () => ReactNode;
     /**
@@ -41,16 +49,23 @@ export interface ConnectionStateRendererProps {
      */
     renderConnected: (props: ConnectedRenderProps) => ReactNode;
     /**
-     * Render when connection is offline.
+     * Render when offline and no error message is attached. Full-page replacement.
      */
     renderOffline: () => ReactNode;
     /**
-     * Render when connection failed with error.
+     * Render when offline with an error message attached. Full-page replacement.
+     * Previously fired only for the dropped `'offlineError'` state; now fires when
+     * `connectionState === 'offline'` and `error` (or `client.lastError`) is set.
      */
     renderError: (error: string | null) => ReactNode;
 }
 /**
- * Headless component that handles connection state logic.
- * User provides all render callbacks - no default UI.
+ * Headless component that handles connection state logic by invoking one of the supplied
+ * render callbacks based on the current state.
+ *
+ * @deprecated Prefer {@link IkonApp} for new code. `IkonApp` mounts the UI surface once
+ * and layers overlays on top, which gives a smoother UX through `reconnecting` / `offline`
+ * transitions. This component remains as a back-compat shim so existing apps continue to
+ * work without changes when they upgrade the SDK.
  */
-export declare function ConnectionStateRenderer({ connectionState, error, isReady, stores, registry, client, onAction, renderIdle, renderConnecting, renderConnectingSlow, renderConnected, renderOffline, renderError, }: ConnectionStateRendererProps): ReactNode;
+export declare function ConnectionStateRenderer({ connectionState, error, isReady, isConnectingSlow, stores, registry, client, onAction, renderIdle: _renderIdle, renderConnecting, renderConnectingSlow, renderConnected, renderOffline, renderError, }: ConnectionStateRendererProps): ReactNode;

package/app/ikon-app.d.ts

@@ -0,0 +1,55 @@
+import { ReactNode } from 'react';
+import { UseIkonAppResult } from './use-ikon-app';
+/**
+ * Overlay rendered during `connecting`. If a function, it receives `isSlow` so the overlay
+ * can stay invisible during fast connections and reveal a chip once the slow threshold trips.
+ */
+export type ConnectingOverlayProp = ReactNode | ((isSlow: boolean) => ReactNode);
+/** Overlay rendered during `reconnecting` (always on top of the cached surface). */
+export type ReconnectingOverlayProp = ReactNode | (() => ReactNode);
+/**
+ * Overlay rendered during `offline`. The function form receives the optional error string
+ * (the synthetic-internal-error case), so the overlay can render a message line when present.
+ */
+export type OfflineOverlayProp = ReactNode | ((error: string | null) => ReactNode);
+/**
+ * Full-page screen rendered when `accessDeniedReason` is set. The function form receives the
+ * server-provided reason string so the screen can surface it to the user.
+ */
+export type AccessDeniedScreenProp = ReactNode | ((reason: string) => ReactNode);
+export interface IkonAppProps extends UseIkonAppResult {
+    /** Overlay rendered during `connecting` (and `waitingForExternalConnectUrl`). */
+    connectingOverlay?: ConnectingOverlayProp;
+    /** Overlay rendered during `reconnecting`. */
+    reconnectingOverlay?: ReconnectingOverlayProp;
+    /** Overlay rendered during `offline`. Receives the optional error message. */
+    offlineOverlay?: OfflineOverlayProp;
+    /**
+     * Full-page screen rendered when the backend denied access (HTTP 403 — e.g. domain
+     * allowlist mismatch). Takes priority over all overlays. If omitted, nothing is rendered
+     * for the access-denied case; pass a screen (or handle it upstream) for a real UI.
+     */
+    accessDeniedScreen?: AccessDeniedScreenProp;
+}
+/**
+ * High-level shell that mounts the Ikon UI surface and layers an overlay on top
+ * based on the connection state. Always renders the surface once it has been populated
+ * for the first time, so the UI stays visible through `reconnecting` and `offline`.
+ *
+ * Usage:
+ * ```tsx
+ * const app = useIkonApp({ modules: [...] });
+ *
+ * <IkonApp
+ *   {...app}
+ *   connectingOverlay={(isSlow) => isSlow ? <ConnectingChip /> : null}
+ *   reconnectingOverlay={<ReconnectingOverlay />}
+ *   offlineOverlay={(error) => <OfflineOverlay error={error} />}
+ * />
+ * ```
+ *
+ * Debug keyboard shortcuts (Ctrl+Shift+1..6, 0, E) are wired up automatically when SDK
+ * debug mode is on (URL has `?ikon-debug=true`). See `useIkonDebug` for the full map.
+ * No on-screen indicator is rendered for active overrides.
+ */
+export declare function IkonApp(props: IkonAppProps): ReactNode;

package/app/index.d.ts

@@ -1,2 +1,4 @@
 export { ConnectionStateRenderer, type ConnectedRenderProps, type ConnectionStateRendererProps } from './connection-state-renderer';
 export { useIkonApp, type IkonUiModuleRegistration, type UseIkonAppOptions, type UseIkonAppResult } from './use-ikon-app';
+export { IkonApp, type IkonAppProps, type ConnectingOverlayProp, type ReconnectingOverlayProp, type OfflineOverlayProp, type AccessDeniedScreenProp } from './ikon-app';
+export { useIkonDebug, type UseIkonDebugResult } from './use-ikon-debug';

package/app/use-ikon-app.d.ts

@@ -126,6 +126,12 @@ export interface UseIkonAppResult {
      * Whether the connection is ready to render UI.
      */
     isReady: boolean;
+    /**
+     * True after `connectionState === 'connecting'` has lasted longer than the slow-connection
+     * threshold (default 5s, configurable via `timeouts.slowConnectionThresholdMs`). The connecting
+     * overlay can use this signal to delay showing feedback so a fast connection doesn't flash a chip.
+     */
+    isConnectingSlow: boolean;
     /**
      * All WebRTC video streams keyed by track index.
      */

package/app/use-ikon-debug.d.ts

@@ -0,0 +1,41 @@
+import { ConnectionState } from '../../../sdk/src/index.ts';
+import { UseIkonAppResult } from './use-ikon-app';
+/**
+ * Result of useIkonDebug — same shape as the input `UseIkonAppResult` (so it can be spread
+ * straight into `<IkonApp />`), plus diagnostic fields the host may surface itself.
+ */
+export interface UseIkonDebugResult {
+    /**
+     * The (possibly overridden) app value. Spread into `<IkonApp />` to apply forced states.
+     * When no override is active, this is the original `app` reference unchanged.
+     */
+    app: UseIkonAppResult;
+    /** Non-null when a state override is active. */
+    forcedState: ConnectionState | null;
+    /** True when the empty-stores override is active (forces the "no UI ever rendered" path). */
+    emptyStores: boolean;
+    /** Non-null when a synthetic error is being injected into the offline overlay. */
+    forcedError: string | null;
+    /** Non-null when the access-denied override is active. */
+    forcedAccessDenied: string | null;
+    /** True when the debug shortcuts are active in this environment. */
+    debugEnabled: boolean;
+}
+/**
+ * Listens for `Ctrl+Shift+<key>` shortcuts (active only when SDK debug mode is on, i.e. the
+ * URL has `?ikon-debug=true`) and returns an overridden app result that forces connection
+ * states / surface emptiness / error messages. Render-time effects only — no on-screen
+ * indicator. `<IkonApp />` calls this hook internally; you only need it if you bypass
+ * `<IkonApp />` and want the same behavior.
+ *
+ * Shortcut map (all require Ctrl+Shift, `event.code`-based so layout-independent):
+ * - Digit1 → force `connecting` (an internal 5s timer flips isConnectingSlow to true so you can see both phases without a second shortcut)
+ * - Digit2 → force `connected`
+ * - Digit3 → force `reconnecting`
+ * - Digit4 → force `offline` (no error)
+ * - Digit5 → force `offline` with synthetic error
+ * - Digit6 → force access-denied (synthetic reason — exercises the accessDeniedScreen path)
+ * - Digit0 → clear all state overrides
+ * - KeyE  → toggle empty-stores override (simulates "initial connection never produced UI")
+ */
+export declare function useIkonDebug(app: UseIkonAppResult): UseIkonDebugResult;

package/index.d.ts

@@ -13,7 +13,7 @@ export type { UiComponentRenderer, UiComponentLibrary, UiNode, UiRenderContext,
 export { UiStreamStore, type UiStylePayload } from '../../sdk-ui/src/index.ts';
 export { renderMotionLetters } from './shared/render-motion-letters';
 export { type AuthConfig, type AuthContextValue, type AuthSession, type AuthState, type AuthUser, type LoginMethod, clearAuthSession, loadAuthSession, saveAuthSession, sessionToUser, authenticateAnonymous, buildOAuthRedirectUrl, clearOAuthParams, parseOAuthCallback, parseOAuthError, sendLoginCode, verifyLoginCode, type OAuthCallbackResult, type SendLoginCodeOptions, type VerifyLoginCodeOptions, AuthProvider, useAuth, useAuthOptional, type AuthProviderProps, useAuthGuard, type UseAuthGuardOptions, type UseAuthGuardResult, } from './auth';
-export { ConnectionStateRenderer, type ConnectedRenderProps, type ConnectionStateRendererProps, useIkonApp, type IkonUiModuleRegistration, type UseIkonAppOptions, type UseIkonAppResult, } from './app';
+export { ConnectionStateRenderer, type ConnectedRenderProps, type ConnectionStateRendererProps, useIkonApp, type IkonUiModuleRegistration, type UseIkonAppOptions, type UseIkonAppResult, IkonApp, type IkonAppProps, type ConnectingOverlayProp, type ReconnectingOverlayProp, type OfflineOverlayProp, type AccessDeniedScreenProp, useIkonDebug, type UseIkonDebugResult, } from './app';
 export { useLazyFont, useToasts, useIkonReactive, useReactive, type Toast } from './hooks';
 export { I18nProvider, useI18n, type I18nContextValue, type I18nProviderProps } from './i18n';
 export { InspectOverlay, type InspectElementPayload } from './inspect/inspect-overlay';