@ikonai/sdk-react-ui 1.5.0 → 1.7.0

package/app/connection-recovery.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What a recovery attempt has to do to stand a chance.
+ *
+ * - `reload` — load the page again. The offline overlay only ever appears when reconnecting cannot
+ *   help (the server instance stopped, the first connect never succeeded, or the SDK gave up), so a
+ *   fresh document is the honest cure for every case but one.
+ * - `freshSession` — load the page without the `ikon-session` deep link. The named session has
+ *   ended; a plain reload would rejoin it and fail identically.
+ */
+export type ConnectionRecoveryKind = 'reload' | 'freshSession';
+export interface ConnectionRecovery {
+    kind: ConnectionRecoveryKind;
+    /** Perform the recovery. Navigates the page, so nothing after it runs. */
+    run: () => void;
+}
+export interface ConnectionRecoveryOptions {
+    /** `useIkonApp().isSessionExpired`. */
+    isSessionExpired: boolean;
+}
+/**
+ * The way out of the offline state, for an overlay to put behind a button.
+ *
+ * An installed PWA (`"display": "standalone"`, which every scaffolded app ships) has no reload
+ * control the user can reach — buried in a menu on desktop, absent entirely on an iOS home-screen
+ * app — so telling them to refresh is advice they cannot act on. The button is the affordance.
+ */
+export declare function getConnectionRecovery({ isSessionExpired }: ConnectionRecoveryOptions): ConnectionRecovery;

package/app/index.d.ts

@@ -2,3 +2,4 @@ export { ConnectionStateRenderer, type ConnectedRenderProps, type ConnectionStat
 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';
+export { getConnectionRecovery, type ConnectionRecovery, type ConnectionRecoveryKind, type ConnectionRecoveryOptions } from './connection-recovery';

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

@@ -36,6 +36,22 @@ export type IkonUiModuleRegistration = (registry: IkonUiRegistry) => void;
  * SessionIdentity the connect resolves to, so a hand-typed query parameter must not displace one.
  */
 export declare function mergeConnectParameters(urlParameters: Record<string, string>, appParameters?: Record<string, string>): Record<string, string>;
+/**
+ * Who a session is for, as opposed to what it presents to prove it.
+ *
+ * A browser access token is worth 15 minutes and is renewed roughly every 13, and a renewal is the
+ * same person holding a fresher credential. Keying the connection on the token's value made every
+ * renewal look like a different session, so a signed-in app tore its IkonClient down and rebuilt it
+ * every renewal period on a perfectly healthy network. Keying on the subject instead leaves only a
+ * genuine change of user — or of sign-in method — forcing a reconnect.
+ *
+ * A token whose subject cannot be read falls back to the token itself: two credentials nobody can
+ * identify must not be assumed to name the same person.
+ */
+export declare function resolveSessionIdentity(session: {
+    token: string;
+    provider: string;
+} | null | undefined): string | null;
 /**
  * Options for the useIkonApp hook.
  */
@@ -92,9 +108,16 @@ export interface UseIkonAppOptions {
     /**
      * Enable WebTransport. Off by default — WebTransport has proven unreliable on
      * bad networks. Set to `true` to opt in (also selectable at runtime with
-     * `?ikon-webtransport=true`). When unset or `false`, the SDK uses WebSocket only.
+     * `?ikon-transport=wt`). When unset or `false`, the SDK uses WebSocket only.
      */
     webtransport?: boolean;
+    /**
+     * Force the HTTP stream transport only (`true`), or exclude it (`false`). Unset by default, which
+     * leaves it as the last rung of the ladder — the one that survives a network permitting HTTPS to
+     * this origin while blocking the WebSocket upgrade. Also settable per session with
+     * `?ikon-transport=http`.
+     */
+    httpstream?: boolean;
     /**
      * Pin the connect tier. When true, only the on-host proxy on 443 is used, and only proxy endpoint
      * types with it. When false, proxy types are excluded. `'lb'` pins the same-origin stream tier

package/index.d.ts

@@ -15,7 +15,7 @@ export type { UiComponentRenderer, UiComponentLibrary, UiNode, UiRenderContext,
 export { UiStreamStore, type UiStylePayload } from '../sdk/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, IkonApp, type IkonAppProps, type ConnectingOverlayProp, type ReconnectingOverlayProp, type OfflineOverlayProp, type AccessDeniedScreenProp, useIkonDebug, type UseIkonDebugResult, } 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, getConnectionRecovery, type ConnectionRecovery, type ConnectionRecoveryKind, type ConnectionRecoveryOptions, } from './app';
 export { useToasts, useIkonReactive, useReactive, type Toast } from './hooks';
 export { I18nProvider, useI18n, type I18nContextValue, type I18nProviderProps } from './i18n';
 export { InspectOverlay, type InspectElementPayload } from './inspect/inspect-overlay';