@oxyhq/core 5.4.2 → 5.5.0

package/dist/types/index.d.ts

@@ -95,12 +95,13 @@ export type { SsoReturnKind, SsoReturnResult, ConsumeSsoReturnDeps } from './uti
 export { generateSsoState } from './mixins/OxyServices.sso';
 export { establishIdpSessionAfterClaim } from './utils/ssoEstablish';
 export type { SsoEstablishClient, EstablishAfterClaimDeps } from './utils/ssoEstablish';
-export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, ssoPriorSessionKey, ssoSignedOutKey, ssoCallbackBootstrapKey, ssoNavigate, getSsoCallbackBootstrapScript, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, silentRestoreSuppressed, allowSsoBounce, } from './utils/ssoBounce';
+export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, ssoPriorSessionKey, ssoSignedOutKey, ssoOutcomeKey, ssoCallbackBootstrapKey, ssoNavigate, getSsoCallbackBootstrapScript, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, silentRestoreSuppressed, allowSsoBounce, } from './utils/ssoBounce';
 export type { SsoBounceGate } from './utils/ssoBounce';
 export { runColdBoot } from './utils/coldBoot';
 export type { ColdBootStep, ColdBootStepResult, ColdBootSession, ColdBootSkip, ColdBootOutcome, RunColdBootOptions, } from './utils/coldBoot';
 export { SessionClient } from './session/SessionClient';
 export type { TokenTransport, SessionClientHost, SessionClientOptions } from './session/SessionClient';
+export type { SocketIOFactory, MinimalSocket } from './session/socketLoader';
 export { createSessionClientHost } from './session/sessionClientHost';
 export { createSessionClient } from './session/createSessionClient';
 export { deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountIdsOf, } from './session/projectSessionState';

package/dist/types/mixins/OxyServices.user.d.ts

@@ -60,9 +60,22 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         _serviceApiKey: string | null;
         _serviceApiSecret: string | null;
         /**
-         * Get profile by username
-         */
-        getProfileByUsername(username: string): Promise<User>;
+         * Get profile by username.
+         *
+         * @param username - The profile's username.
+         * @param options.cache - Defaults to `true` (5-minute TTL), matching prior
+         *   behavior. Pass `{ cache: false }` to force a registry-fresh read: the
+         *   request bypasses BOTH the cache lookup and the post-fetch cache write
+         *   (see {@link HttpService.request}'s `cache` handling), so it neither
+         *   serves nor overwrites any entry already cached for this key — a
+         *   previously cached response (if one exists) is left in place until its
+         *   own TTL expires or is explicitly invalidated elsewhere. Use this when a
+         *   caller must observe a just-written change (e.g. a privacy/consent flag)
+         *   that would otherwise be masked by the TTL window.
+         */
+        getProfileByUsername(username: string, options?: {
+            cache?: boolean;
+        }): Promise<User>;
         /**
          * Lightweight username lookup for login flows.
          * Returns minimal public info: exists, color, avatar, name.displayName.
@@ -134,9 +147,22 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          */
         getSimilarProfiles(userId: string, limit?: number): Promise<User[]>;
         /**
-         * Get user by ID
-         */
-        getUserById(userId: string): Promise<User>;
+         * Get user by ID.
+         *
+         * @param userId - The target user's id.
+         * @param options.cache - Defaults to `true` (5-minute TTL), matching prior
+         *   behavior. Pass `{ cache: false }` to force a registry-fresh read: the
+         *   request bypasses BOTH the cache lookup and the post-fetch cache write
+         *   (see {@link HttpService.request}'s `cache` handling), so it neither
+         *   serves nor overwrites any entry already cached for this key — a
+         *   previously cached response (if one exists) is left in place until its
+         *   own TTL expires or is explicitly invalidated elsewhere. Use this when a
+         *   caller must observe a just-written change (e.g. a privacy/consent flag)
+         *   that would otherwise be masked by the TTL window.
+         */
+        getUserById(userId: string, options?: {
+            cache?: boolean;
+        }): Promise<User>;
         /**
          * Fetch many users by id in one round-trip per chunk.
          *

package/dist/types/session/SessionClient.d.ts

@@ -1,5 +1,5 @@
 import { type DeviceSessionState } from '@oxyhq/contracts';
-import type { MinimalSocket } from './socketLoader';
+import type { MinimalSocket, SocketIOFactory } from './socketLoader';
 export interface TokenTransport {
     /** Ensure this app holds a per-domain access token for state.activeAccountId (mint via FedCM/silent/sso/keychain). Best-effort. */
     ensureActiveToken(state: DeviceSessionState): Promise<void>;
@@ -16,6 +16,18 @@ export interface SessionClientHost {
 }
 export interface SessionClientOptions {
     transport?: TokenTransport;
+    /**
+     * Statically-injected `socket.io-client` factory (its `io` export).
+     * `@oxyhq/services` and `@oxyhq/auth` list `socket.io-client` as a real
+     * dependency and pass `io` in directly, so realtime session sync never
+     * depends on a runtime dynamic `import('socket.io-client')` of a bare
+     * specifier — which is bundler-fragile in Metro/Expo-web and Vite when
+     * `@oxyhq/core` is consumed as its published dist (the import resolves to
+     * nothing → `connectSocket` warns and falls back to REST-only). When this is
+     * provided, `connectSocket` uses it and never touches the lazy loader; when
+     * absent it falls back to `getSocketIO()`.
+     */
+    socketFactory?: SocketIOFactory;
 }
 type StateListener = (state: DeviceSessionState | null) => void;
 export declare class SessionClient {

package/dist/types/session/createSessionClient.d.ts

@@ -1,5 +1,6 @@
 import type { OxyServices } from '../OxyServices';
 import { SessionClient, type TokenTransport } from './SessionClient';
+import type { SocketIOFactory } from './socketLoader';
 import { createSessionClientHost } from './sessionClientHost';
 /**
  * Wires a `SessionClient` over the given `OxyServices` instance: builds the
@@ -16,8 +17,14 @@ import { createSessionClientHost } from './sessionClientHost';
  * The host is returned alongside the client (not just the client) so the
  * caller can call `host.setCurrentAccountId(...)` as the active account
  * changes.
+ *
+ * `socketFactory` is the statically-injected `socket.io-client` `io` export.
+ * Consumers that bundle socket.io-client as a real dependency pass it so
+ * realtime sync never depends on core's lazy dynamic import of a bare
+ * specifier (bundler-fragile in Metro/Expo-web and Vite against the published
+ * dist). When omitted, the client falls back to the lazy loader.
  */
-export declare function createSessionClient(oxyServices: OxyServices, transport: TokenTransport): {
+export declare function createSessionClient(oxyServices: OxyServices, transport: TokenTransport, socketFactory?: SocketIOFactory): {
     client: SessionClient;
     host: ReturnType<typeof createSessionClientHost>;
 };

package/dist/types/utils/ssoBounce.d.ts

@@ -122,6 +122,24 @@ export declare function ssoPriorSessionKey(origin: string): string;
  * clears it first, so the user can always sign back in.
  */
 export declare function ssoSignedOutKey(origin: string): string;
+/**
+ * Per-origin key holding the LAST consumed SSO-return outcome (`ok` | `none` |
+ * `error`, plus an optional machine-readable `reason` on the non-`ok` outcomes).
+ *
+ * Lives in per-tab `sessionStorage` like the other loop-breaker keys, and for
+ * the same reason: a `none`/`error` return HARD-navigates the RP off the
+ * internal callback path back to its real destination (a fresh document load),
+ * so the outcome an RP wants to render ("the central IdP had no session — show a
+ * branded sign-in screen instead of bouncing again") must survive that
+ * round-trip. The RP reads it on the destination load to decide whether an
+ * AUTOMATIC (guard-driven) sign-in should re-bounce or defer to a user gesture.
+ *
+ * Written as a small JSON blob (`{kind, reason?}`). Set whenever a return is
+ * consumed; cleared on a successful session commit and on an explicit
+ * user-gesture sign-in / full sign-out (so a deliberate retry is never
+ * suppressed by a prior automatic none/error).
+ */
+export declare function ssoOutcomeKey(origin: string): string;
 /**
  * Per-origin marker written by the pre-hydration callback bootstrap.
  *

package/dist/types/utils/ssoReturn.d.ts

@@ -29,12 +29,22 @@ export type SsoReturnKind = 'ok' | 'none' | 'error';
  * The parsed result of an SSO return fragment.
  *
  * `code` is present only for `kind: 'ok'`. `state` echoes the CSRF state the RP
- * generated for the bounce (when the IdP round-tripped it).
+ * generated for the bounce (when the IdP round-tripped it). `reason` is present
+ * only for a NON-`ok` outcome when the IdP supplied one.
  */
 export interface SsoReturnResult {
     kind: SsoReturnKind;
     code?: string;
     state?: string;
+    /**
+     * Machine-readable reason accompanying a NON-`ok` outcome, when the central
+     * IdP supplies one (e.g. `no_cookie` | `stale_session` | `no_grant` |
+     * `no_grant_establish` on a `none` bounce). Purely informational: it lets a
+     * Relying Party surface WHY a silent probe returned no session (e.g. to brand
+     * a "sign in" screen) without re-deriving it. Absent on `ok`, and whenever the
+     * IdP did not include a `reason` param.
+     */
+    reason?: string;
 }
 /**
  * Parse an SSO return fragment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "5.4.2",
+  "version": "5.5.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/index.ts

@@ -545,6 +545,7 @@ export {
     ssoAttemptedKey,
     ssoPriorSessionKey,
     ssoSignedOutKey,
+    ssoOutcomeKey,
     ssoCallbackBootstrapKey,
     ssoNavigate,
     getSsoCallbackBootstrapScript,
@@ -571,6 +572,10 @@ export type {
 // ---------------------------------------------------------------------------
 export { SessionClient } from './session/SessionClient';
 export type { TokenTransport, SessionClientHost, SessionClientOptions } from './session/SessionClient';
+// The injectable socket factory type: consumers that bundle socket.io-client
+// (services/auth-sdk) pass its `io` export as `socketFactory` so realtime sync
+// never relies on core's lazy dynamic import of a bare specifier.
+export type { SocketIOFactory, MinimalSocket } from './session/socketLoader';
 
 // Shared SessionClient integration layer: the host adapter, the pure
 // DeviceSessionState projection helpers, and the client factory are defined

package/src/mixins/OxyServices.user.ts

@@ -101,12 +101,23 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     declare _serviceApiSecret: string | null;
 
     /**
-     * Get profile by username
-     */
-    async getProfileByUsername(username: string): Promise<User> {
+     * Get profile by username.
+     *
+     * @param username - The profile's username.
+     * @param options.cache - Defaults to `true` (5-minute TTL), matching prior
+     *   behavior. Pass `{ cache: false }` to force a registry-fresh read: the
+     *   request bypasses BOTH the cache lookup and the post-fetch cache write
+     *   (see {@link HttpService.request}'s `cache` handling), so it neither
+     *   serves nor overwrites any entry already cached for this key — a
+     *   previously cached response (if one exists) is left in place until its
+     *   own TTL expires or is explicitly invalidated elsewhere. Use this when a
+     *   caller must observe a just-written change (e.g. a privacy/consent flag)
+     *   that would otherwise be masked by the TTL window.
+     */
+    async getProfileByUsername(username: string, options?: { cache?: boolean }): Promise<User> {
       try {
         const user = await this.makeRequest<User>('GET', `/profiles/username/${username}`, undefined, {
-          cache: true,
+          cache: options?.cache ?? true,
           cacheTTL: 5 * 60 * 1000, // 5 minutes cache for profiles
         });
         return normalizeUserIdentity(user);
@@ -335,12 +346,23 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
     /**
-     * Get user by ID
-     */
-    async getUserById(userId: string): Promise<User> {
+     * Get user by ID.
+     *
+     * @param userId - The target user's id.
+     * @param options.cache - Defaults to `true` (5-minute TTL), matching prior
+     *   behavior. Pass `{ cache: false }` to force a registry-fresh read: the
+     *   request bypasses BOTH the cache lookup and the post-fetch cache write
+     *   (see {@link HttpService.request}'s `cache` handling), so it neither
+     *   serves nor overwrites any entry already cached for this key — a
+     *   previously cached response (if one exists) is left in place until its
+     *   own TTL expires or is explicitly invalidated elsewhere. Use this when a
+     *   caller must observe a just-written change (e.g. a privacy/consent flag)
+     *   that would otherwise be masked by the TTL window.
+     */
+    async getUserById(userId: string, options?: { cache?: boolean }): Promise<User> {
       try {
         const user = await this.makeRequest<User>('GET', `/users/${userId}`, undefined, {
-          cache: true,
+          cache: options?.cache ?? true,
           cacheTTL: 5 * 60 * 1000, // 5 minutes cache
         });
         return normalizeUserIdentity(user);

package/src/mixins/__tests__/userReadCacheBypass.test.ts

@@ -0,0 +1,121 @@
+/**
+ * Per-call cache-bypass tests for `getUserById` / `getProfileByUsername`.
+ *
+ * Both mixin methods cache their GET response for 5 minutes via
+ * `HttpService`'s identity-scoped TTL cache. A consumer that just wrote a
+ * setting readable through one of these endpoints (e.g. Mention's federation
+ * consent flag) needs a way to force a registry-fresh read instead of
+ * silently getting served the pre-write snapshot for up to 5 minutes.
+ *
+ * These tests pin down that:
+ *  - default behavior is UNCHANGED: a second call within the TTL is served
+ *    from cache (no second network call),
+ *  - `{ cache: false }` always hits the network, even immediately after a
+ *    cached call, and never overwrites the still-live cached entry — a
+ *    subsequent default-cache call keeps serving the ORIGINAL cached value.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+/**
+ * Build a non-verified JWT whose payload decodes to the given claims.
+ * `jwtDecode` only base64url-decodes the middle segment (no signature check).
+ */
+function makeJwt(payload: Record<string, unknown>): string {
+  const b64url = (obj: Record<string, unknown>): string =>
+    Buffer.from(JSON.stringify(obj)).toString('base64url');
+  const fullPayload = { exp: Math.floor(Date.now() / 1000) + 3600, ...payload };
+  return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url(fullPayload)}.sig`;
+}
+
+/** A JSON `Response` mimicking the API's `{ data: ... }` success envelope. */
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+describe('getUserById / getProfileByUsername cache bypass', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    oxy.httpService.setTokens(makeJwt({ userId: 'me' }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  describe('getUserById', () => {
+    it('default call: a second read within the TTL is served from cache', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-1', username: 'alice' }));
+      const first = await oxy.getUserById('user-1');
+      expect(first.username).toBe('alice');
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+
+      const second = await oxy.getUserById('user-1');
+      expect(second.username).toBe('alice');
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('{ cache: false } always hits the network, even right after a cached call', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-1', username: 'alice' }));
+      await oxy.getUserById('user-1');
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-1', username: 'alice-renamed' }));
+      const fresh = await oxy.getUserById('user-1', { cache: false });
+      expect(fresh.username).toBe('alice-renamed');
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+
+    it('{ cache: false } does not overwrite the still-live cached entry', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-1', username: 'alice' }));
+      await oxy.getUserById('user-1');
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+
+      // Bypass read observes server-side truth that has since changed...
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-1', username: 'alice-renamed' }));
+      await oxy.getUserById('user-1', { cache: false });
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+
+      // ...but a plain cached read afterward still serves the ORIGINAL cached
+      // value — the bypass call never wrote to the cache slot.
+      const cached = await oxy.getUserById('user-1');
+      expect(cached.username).toBe('alice');
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('getProfileByUsername', () => {
+    it('default call: a second read within the TTL is served from cache', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-2', username: 'bob' }));
+      const first = await oxy.getProfileByUsername('bob');
+      expect(first.id).toBe('user-2');
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+
+      const second = await oxy.getProfileByUsername('bob');
+      expect(second.id).toBe('user-2');
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('{ cache: false } always hits the network, even right after a cached call', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-2', username: 'bob', bio: 'old' }));
+      await oxy.getProfileByUsername('bob');
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-2', username: 'bob', bio: 'new' }));
+      const fresh = await oxy.getProfileByUsername('bob', { cache: false });
+      expect((fresh as unknown as { bio: string }).bio).toBe('new');
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+  });
+});

package/src/session/SessionClient.ts

@@ -6,7 +6,7 @@ import {
 } from '@oxyhq/contracts';
 import { logger } from '../utils/loggerUtils';
 import { getSocketIO } from './socketLoader';
-import type { MinimalSocket } from './socketLoader';
+import type { MinimalSocket, SocketIOFactory } from './socketLoader';
 
 export interface TokenTransport {
   /** Ensure this app holds a per-domain access token for state.activeAccountId (mint via FedCM/silent/sso/keychain). Best-effort. */
@@ -24,6 +24,18 @@ export interface SessionClientHost {
 
 export interface SessionClientOptions {
   transport?: TokenTransport;
+  /**
+   * Statically-injected `socket.io-client` factory (its `io` export).
+   * `@oxyhq/services` and `@oxyhq/auth` list `socket.io-client` as a real
+   * dependency and pass `io` in directly, so realtime session sync never
+   * depends on a runtime dynamic `import('socket.io-client')` of a bare
+   * specifier — which is bundler-fragile in Metro/Expo-web and Vite when
+   * `@oxyhq/core` is consumed as its published dist (the import resolves to
+   * nothing → `connectSocket` warns and falls back to REST-only). When this is
+   * provided, `connectSocket` uses it and never touches the lazy loader; when
+   * absent it falls back to `getSocketIO()`.
+   */
+  socketFactory?: SocketIOFactory;
 }
 
 type StateListener = (state: DeviceSessionState | null) => void;
@@ -157,7 +169,10 @@ export class SessionClient {
   }
 
   private async connectSocket(): Promise<void> {
-    const io = await getSocketIO();
+    // Prefer a statically-injected factory (services/auth-sdk bundle
+    // socket.io-client as a real dep); fall back to the lazy loader — and warn
+    // if THAT yields nothing — only when no factory was injected.
+    const io = this.options.socketFactory ?? (await getSocketIO());
     if (!io) {
       logger.warn('[SessionClient] no socket.io-client; running REST-only (no realtime sync)', { component: 'SessionClient' });
       return;

package/src/session/__tests__/SessionClient.socketFactory.test.ts

@@ -0,0 +1,79 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import * as socketLoader from '../socketLoader';
+import type { MinimalSocket, SocketIOFactory } from '../socketLoader';
+import { SessionClient, type SessionClientHost } from '../SessionClient';
+
+/**
+ * P0 (bundler-fragility): SessionClient must NOT depend on a runtime dynamic
+ * `import('socket.io-client')` when a consumer (services/auth-sdk) injects the
+ * `io` factory statically. These tests pin the two branches of `connectSocket`:
+ *
+ *  1. `socketFactory` injected  → the injected factory is used and the lazy
+ *     loader (`getSocketIO`) is NEVER invoked (the exact call that fails in the
+ *     Metro/Expo-web + Vite published-dist consumers).
+ *  2. no `socketFactory`        → the lazy loader IS invoked (fallback).
+ */
+
+type Handler = (...args: unknown[]) => void;
+class FakeSocket implements MinimalSocket {
+  connected = false;
+  handlers = new Map<string, Handler[]>();
+  on(event: string, cb: Handler) { const l = this.handlers.get(event) ?? []; l.push(cb); this.handlers.set(event, l); }
+  off(event: string, cb?: Handler) { if (!cb) { this.handlers.delete(event); return; } this.handlers.set(event, (this.handlers.get(event) ?? []).filter((h) => h !== cb)); }
+  connect() { this.connected = true; }
+  disconnect() { this.connected = false; }
+}
+
+const STATE = (rev: number): DeviceSessionState => ({ deviceId: 'd1', accounts: [{ accountId: 'a1', sessionId: 's1', authuser: 0 }], activeAccountId: 'a1', revision: rev, updatedAt: 1720000000000 });
+const SYNC = (rev: number) => ({ state: STATE(rev), activeToken: { accessToken: `jwt-${rev}`, expiresAt: 'x' } });
+
+function makeHost(over: Partial<SessionClientHost> = {}): SessionClientHost {
+  return {
+    makeRequest: jest.fn().mockResolvedValue(SYNC(1)),
+    getBaseURL: () => 'http://test.invalid',
+    getAccessToken: () => 'tok',
+    onTokensChanged: () => () => undefined,
+    setTokens: jest.fn(),
+    getCurrentAccountId: () => 'a1',
+    ...over,
+  };
+}
+
+describe('SessionClient injected socketFactory', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('uses the injected factory and NEVER invokes the lazy loader', async () => {
+    const loaderSpy = jest.spyOn(socketLoader, 'getSocketIO');
+    let created: FakeSocket | null = null;
+    const factory: SocketIOFactory = jest.fn((_uri: string) => {
+      created = new FakeSocket();
+      created.connected = true;
+      return created;
+    });
+
+    const client = new SessionClient(makeHost(), { socketFactory: factory });
+    await client.start();
+
+    expect(factory).toHaveBeenCalledTimes(1);
+    expect(factory).toHaveBeenCalledWith('http://test.invalid', expect.objectContaining({ transports: ['websocket'] }));
+    expect(loaderSpy).not.toHaveBeenCalled();
+    expect(created).not.toBeNull();
+    client.stop();
+  });
+
+  it('falls back to the lazy loader when no factory is injected', async () => {
+    const fake = new FakeSocket();
+    fake.connected = true;
+    const lazyFactory: SocketIOFactory = jest.fn(() => fake);
+    const loaderSpy = jest.spyOn(socketLoader, 'getSocketIO').mockResolvedValue(lazyFactory);
+
+    const client = new SessionClient(makeHost());
+    await client.start();
+
+    expect(loaderSpy).toHaveBeenCalledTimes(1);
+    expect(lazyFactory).toHaveBeenCalledWith('http://test.invalid', expect.objectContaining({ transports: ['websocket'] }));
+    client.stop();
+  });
+});

package/src/session/createSessionClient.ts

@@ -1,5 +1,6 @@
 import type { OxyServices } from '../OxyServices';
 import { SessionClient, type TokenTransport } from './SessionClient';
+import type { SocketIOFactory } from './socketLoader';
 import { createSessionClientHost } from './sessionClientHost';
 
 /**
@@ -17,15 +18,22 @@ import { createSessionClientHost } from './sessionClientHost';
  * The host is returned alongside the client (not just the client) so the
  * caller can call `host.setCurrentAccountId(...)` as the active account
  * changes.
+ *
+ * `socketFactory` is the statically-injected `socket.io-client` `io` export.
+ * Consumers that bundle socket.io-client as a real dependency pass it so
+ * realtime sync never depends on core's lazy dynamic import of a bare
+ * specifier (bundler-fragile in Metro/Expo-web and Vite against the published
+ * dist). When omitted, the client falls back to the lazy loader.
  */
 export function createSessionClient(
   oxyServices: OxyServices,
   transport: TokenTransport,
+  socketFactory?: SocketIOFactory,
 ): {
   client: SessionClient;
   host: ReturnType<typeof createSessionClientHost>;
 } {
   const host = createSessionClientHost(oxyServices);
-  const client = new SessionClient(host, { transport });
+  const client = new SessionClient(host, { transport, socketFactory });
   return { client, host };
 }

package/src/utils/__tests__/ssoReturn.test.ts

@@ -70,6 +70,13 @@ describe('parseSsoReturnFragment', () => {
 
       expect(result).toEqual({ kind: 'ok', code: 'a+b/c', state: 's t' });
     });
+
+    it('ignores a stray reason on an ok outcome', () => {
+      const result = parseSsoReturnFragment('#oxy_sso=ok&code=abc123&state=xyz&reason=no_cookie');
+
+      expect(result).toEqual({ kind: 'ok', code: 'abc123', state: 'xyz' });
+      expect(result?.reason).toBeUndefined();
+    });
   });
 
   describe('none', () => {
@@ -85,6 +92,18 @@ describe('parseSsoReturnFragment', () => {
       expect(result).toEqual({ kind: 'none', state: 'xyz' });
       expect(result?.code).toBeUndefined();
     });
+
+    it('carries a machine-readable reason on a none outcome', () => {
+      const result = parseSsoReturnFragment('#oxy_sso=none&reason=no_cookie&state=xyz');
+
+      expect(result).toEqual({ kind: 'none', state: 'xyz', reason: 'no_cookie' });
+    });
+
+    it('omits reason when the none outcome carries none', () => {
+      const result = parseSsoReturnFragment('#oxy_sso=none&state=xyz');
+
+      expect(result?.reason).toBeUndefined();
+    });
   });
 
   describe('error', () => {
@@ -100,6 +119,12 @@ describe('parseSsoReturnFragment', () => {
       expect(result).toEqual({ kind: 'error' });
       expect(result?.code).toBeUndefined();
     });
+
+    it('carries a machine-readable reason on an error outcome', () => {
+      const result = parseSsoReturnFragment('#oxy_sso=error&reason=no_grant_establish');
+
+      expect(result).toEqual({ kind: 'error', reason: 'no_grant_establish' });
+    });
   });
 
   describe('null (not an oxy_sso fragment)', () => {

package/src/utils/ssoBounce.ts

@@ -70,6 +70,7 @@ const ATTEMPTED_KEY_PREFIX = 'oxy_sso_attempted:';
 const CALLBACK_BOOTSTRAP_KEY_PREFIX = 'oxy_sso_callback_bootstrap:';
 const PRIOR_SESSION_KEY_PREFIX = 'oxy_sso_prior_session:';
 const SIGNED_OUT_KEY_PREFIX = 'oxy_signed_out:';
+const OUTCOME_KEY_PREFIX = 'oxy_sso_outcome:';
 
 /** Per-origin CSRF state key (matched on return to defeat fragment forgery). */
 export function ssoStateKey(origin: string): string {
@@ -157,6 +158,27 @@ export function ssoSignedOutKey(origin: string): string {
   return `${SIGNED_OUT_KEY_PREFIX}${origin}`;
 }
 
+/**
+ * Per-origin key holding the LAST consumed SSO-return outcome (`ok` | `none` |
+ * `error`, plus an optional machine-readable `reason` on the non-`ok` outcomes).
+ *
+ * Lives in per-tab `sessionStorage` like the other loop-breaker keys, and for
+ * the same reason: a `none`/`error` return HARD-navigates the RP off the
+ * internal callback path back to its real destination (a fresh document load),
+ * so the outcome an RP wants to render ("the central IdP had no session — show a
+ * branded sign-in screen instead of bouncing again") must survive that
+ * round-trip. The RP reads it on the destination load to decide whether an
+ * AUTOMATIC (guard-driven) sign-in should re-bounce or defer to a user gesture.
+ *
+ * Written as a small JSON blob (`{kind, reason?}`). Set whenever a return is
+ * consumed; cleared on a successful session commit and on an explicit
+ * user-gesture sign-in / full sign-out (so a deliberate retry is never
+ * suppressed by a prior automatic none/error).
+ */
+export function ssoOutcomeKey(origin: string): string {
+  return `${OUTCOME_KEY_PREFIX}${origin}`;
+}
+
 /**
  * Per-origin marker written by the pre-hydration callback bootstrap.
  *

package/src/utils/ssoReturn.ts

@@ -41,12 +41,22 @@ export type SsoReturnKind = 'ok' | 'none' | 'error';
  * The parsed result of an SSO return fragment.
  *
  * `code` is present only for `kind: 'ok'`. `state` echoes the CSRF state the RP
- * generated for the bounce (when the IdP round-tripped it).
+ * generated for the bounce (when the IdP round-tripped it). `reason` is present
+ * only for a NON-`ok` outcome when the IdP supplied one.
  */
 export interface SsoReturnResult {
   kind: SsoReturnKind;
   code?: string;
   state?: string;
+  /**
+   * Machine-readable reason accompanying a NON-`ok` outcome, when the central
+   * IdP supplies one (e.g. `no_cookie` | `stale_session` | `no_grant` |
+   * `no_grant_establish` on a `none` bounce). Purely informational: it lets a
+   * Relying Party surface WHY a silent probe returned no session (e.g. to brand
+   * a "sign in" screen) without re-deriving it. Absent on `ok`, and whenever the
+   * IdP did not include a `reason` param.
+   */
+  reason?: string;
 }
 
 const VALID_KINDS: ReadonlySet<string> = new Set<SsoReturnKind>(['ok', 'none', 'error']);
@@ -99,6 +109,13 @@ export function parseSsoReturnFragment(hash: string | undefined | null): SsoRetu
     if (code !== null && code.length > 0) {
       result.code = code;
     }
+  } else {
+    // A machine-readable reason accompanies a NON-`ok` outcome when the IdP
+    // supplies one. Success carries no reason, so it is only read here.
+    const reason = params.get('reason');
+    if (reason !== null && reason.length > 0) {
+      result.reason = reason;
+    }
   }
 
   return result;