@oxyhq/core 12.0.0 → 12.1.0

package/dist/types/index.d.ts

@@ -99,7 +99,7 @@ export { deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountId
 export { projectSwitchableAccounts, switchableAccountIds, } from './session/accountProjection';
 export type { SwitchableAccount, SwitchableAccountUser, ProjectSwitchableAccountsInput, } from './session/accountProjection';
 export { AccountDialogController, createAccountDialogController, } from './session/accountDialogController';
-export type { AccountDialogControllerOptions, AccountDialogSnapshot, AccountDialogView, SignInFlowPhase, SignInFlowState, } from './session/accountDialogController';
+export type { AccountDialogControllerOptions, AccountDialogSnapshot, AccountDialogView, CommonsAvailability, SignInFlowPhase, SignInFlowState, } from './session/accountDialogController';
 export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, } from './session/authStateStore';
 export type { PersistedAuthState, AuthStateStore, NativeKeyValueStorage, } from './session/authStateStore';
 export { refreshPersistedSession, refreshDeviceSecretArm, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './session/refresh';

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

@@ -12,17 +12,23 @@
  *   - the unified account list (via {@link projectSwitchableAccounts}), fetched
  *     from `SessionClient` state ∪ `oxyServices.listAccounts()` and hydrated
  *     with `oxyServices.getUsersByIds()`;
- *   - the dialog `view` state machine (`accounts` | `signin` | `qr` | `add`);
+ *   - the dialog `view` state machine (`accounts` | `signin` | `qr` | `add` |
+ *     `signup`);
  *   - `switchTo` (the uniform switch: `SessionClient.switchAccount` for an
  *     account already on the device, `oxyServices.switchToAccount` to mint on
  *     first entry into a graph account — reusing the existing SDK primitives, no
  *     new switch path);
  *   - the "Sign in with Oxy" device flow (same-device shared-keychain via
  *     `oxyServices.signInWithSharedIdentity`, else the cross-device QR handoff
- *     via `startCommonsSignIn` → poll → `claimSessionByToken`).
+ *     via `startCommonsSignIn` → poll → `claimSessionByToken`);
+ *   - `commonsAvailability` — whether Commons is installed on this device
+ *     (native only, via the injected `canOpenApp` probe), so the QR view can
+ *     offer a "Get Commons" fallback instead of a same-device dead end.
  *
  * Sign-in is passkey (WebAuthn) or the Commons QR / shared-keychain handoff —
- * password, social login, and 2FA were removed ecosystem-wide.
+ * password, social login, and 2FA were removed ecosystem-wide. Account
+ * creation (`signup` view) is the same two identity backends: a passkey
+ * ceremony on web, or a Commons-created identity.
  */
 import type { OxyServices } from '../OxyServices';
 import type { SessionLoginResponse, MinimalUserData } from '../models/session';
@@ -30,7 +36,19 @@ import type { SessionClient } from './SessionClient';
 import type { SocketIOFactory } from './socketLoader';
 import { type SwitchableAccount } from './accountProjection';
 /** The dialog's top-level view. */
-export type AccountDialogView = 'accounts' | 'signin' | 'qr' | 'add';
+export type AccountDialogView = 'accounts' | 'signin' | 'qr' | 'add' | 'signup';
+/**
+ * Whether Commons is installed on this device, as resolved by the injected
+ * `canOpenApp` probe:
+ *   - `'unknown'` — not yet probed, OR no probe was injected (web — there is
+ *     no API to ask a browser whether a custom URL scheme is registered, so
+ *     this stays `'unknown'` forever there and the QR view renders
+ *     unconditionally, no gating).
+ *   - `'checking'` — the probe is in flight.
+ *   - `'available'` / `'unavailable'` — the probe's resolved terminal answer
+ *     (native only). A probe error is treated as `'unavailable'` (fail-closed).
+ */
+export type CommonsAvailability = 'unknown' | 'checking' | 'available' | 'unavailable';
 /** Lifecycle phase of the "Sign in with Oxy" device flow. */
 export type SignInFlowPhase = 'idle' | 'starting' | 'waiting' | 'authorized' | 'error';
 /** State of the "Sign in with Oxy" (shared-key / QR) device flow. */
@@ -67,6 +85,8 @@ export interface AccountDialogSnapshot {
     switchingAccountId: string | null;
     /** The "Sign in with Oxy" device-flow state. */
     signIn: SignInFlowState;
+    /** Whether Commons is installed on this device. See {@link CommonsAvailability}. */
+    commonsAvailability: CommonsAvailability;
 }
 /** Construction options for {@link AccountDialogController}. */
 export interface AccountDialogControllerOptions {
@@ -84,15 +104,36 @@ export interface AccountDialogControllerOptions {
     /** Locale for display-name resolution. */
     locale?: string;
     /**
-     * Commit a freshly-authorized session (device flow / shared identity / minted
-     * graph switch) into the host's session set — device-first registration +
-     * durable persist + profile hydration. The consumer supplies its provider's
-     * commit path (`useOxy().handleWebSession` / the auth-sdk equivalent). Called
-     * AFTER the SDK has planted the access token. When omitted the controller
-     * falls back to `SessionClient.registerAndActivate` (registration + activation
-     * only — no provider-side durable persist/hydration).
+     * Commit a freshly-authorized SIGN-IN session (device flow / shared identity)
+     * into the host's session set — device-first registration + durable persist +
+     * profile hydration. The consumer supplies its provider's commit path
+     * (`useOxy().handleWebSession` / the auth-sdk equivalent). Called AFTER the SDK
+     * has planted the access token. When omitted the controller falls back to
+     * `SessionClient.registerAndActivate` (registration + activation only — no
+     * provider-side durable persist/hydration).
+     *
+     * This is the SIGN-IN commit: on an official web origin it may run the
+     * cross-origin hub-sync (a full-page redirect to `auth.oxy.so/sync`) that
+     * bootstraps silent OAuth restore on OTHER origins. A first sign-in on a web
+     * origin legitimately needs that. An account SWITCH does NOT — see
+     * {@link commitSwitchedSession}.
      */
     commitSession?: (session: SessionLoginResponse) => Promise<void>;
+    /**
+     * Commit a minted graph SWITCH session into the host's session set — same
+     * device-first registration + durable persist + profile hydration as
+     * {@link commitSession}, but IN-PLACE: it must NOT trigger the cross-origin
+     * hub-sync redirect. Switching into an account you already operate reuses the
+     * device credential that was already hub-synced at the original sign-in, so
+     * re-syncing is redundant and a full-page redirect on switch is the exact
+     * regression this separation prevents. Cross-tab/app propagation of the switch
+     * still happens instantly via the server's device-scoped `session_state` /
+     * `session_accounts_changed` socket broadcast — no navigation required.
+     *
+     * When omitted the controller falls back to {@link commitSession} (if wired)
+     * and then to `SessionClient.registerAndActivate`.
+     */
+    commitSwitchedSession?: (session: SessionLoginResponse) => Promise<void>;
     /** Notified after a completed sign-in (bearer planted + session committed). */
     onSignedIn?: (user: MinimalUserData) => void;
     /**
@@ -133,6 +174,7 @@ export declare class AccountDialogController {
     private readonly clientId;
     private readonly locale?;
     private readonly commitSession?;
+    private readonly commitSwitchedSession?;
     private readonly onSignedIn?;
     private readonly pollIntervalMs;
     private readonly openUrl?;
@@ -146,6 +188,7 @@ export declare class AccountDialogController {
     private error;
     private switchingAccountId;
     private signIn;
+    private commonsAvailability;
     /** The secret device-flow token of the active QR flow (never surfaced). */
     private signInToken;
     private pollTimer;
@@ -214,6 +257,8 @@ export declare class AccountDialogController {
     close(): void;
     /** Switch to the "add account" view (the sign-in entry chooser). */
     add(): void;
+    /** Switch to the "create account" view (passkey / Commons signup entry). */
+    startSignup(): void;
     /**
      * Reload the account graph and per-account profiles, then re-project. Safe to
      * call repeatedly; concurrent calls are reconciled by a sequence guard so a
@@ -259,11 +304,25 @@ export declare class AccountDialogController {
      */
     showQr(): Promise<void>;
     /**
-     * When a `canOpenApp` probe is injected and reports Commons installed, open the
-     * approve deep link via the injected `openUrl`. Best-effort and non-blocking: a
-     * probe/open failure is logged and swallowed — the QR/polling fallback remains.
+     * Resolve whether Commons is installed on this device via the injected
+     * `canOpenApp` probe, updating {@link commonsAvailability} as durable,
+     * observable snapshot state. Native only — a no-op when `canOpenApp` was
+     * not injected (web), where `commonsAvailability` stays `'unknown'` forever
+     * and the QR view renders unconditionally (no gating).
+     *
+     * Replaces the old `maybeOpenCommons` fire-and-forget probe, whose outcome
+     * was only ever reflected by whether Commons silently opened — a probe
+     * failure or "not installed" answer was swallowed into a debug log with no
+     * way for the UI to react. `commonsAvailability` fixes that.
      */
-    private maybeOpenCommons;
+    private resolveCommonsAvailability;
+    /**
+     * When Commons is confirmed installed, deep-link straight into its approve
+     * screen via the injected `openUrl` with the same `oxycommons://approve?...`
+     * payload the QR encodes. Best-effort and non-blocking — the QR/polling
+     * fallback stays live regardless of the outcome here.
+     */
+    private deepLinkIntoCommonsIfAvailable;
     /** Tear down the active sign-in device flow (timers + socket + token) and reset to idle. */
     cancelSignIn(): void;
     private scheduleNextPoll;
@@ -283,8 +342,14 @@ export declare class AccountDialogController {
     private completeSignIn;
     /**
      * Register a token-planted session into the device set. Prefers the
-     * consumer's `commitSession` (durable persist + hydration); falls back to
+     * consumer's commit funnel (durable persist + hydration); falls back to
      * `SessionClient.registerAndActivate` (registration + activation only).
+     *
+     * A SWITCH (`opts.fromSwitch`) uses the IN-PLACE `commitSwitchedSession` funnel
+     * so it never runs the cross-origin hub-sync redirect; a SIGN-IN uses
+     * `commitSession` (which may hub-sync on an official web origin). When the
+     * switch funnel is not wired it falls back to the sign-in funnel, then to
+     * `registerAndActivate`.
      */
     private commitAuthorizedSession;
     private failSignIn;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "12.0.0",
+  "version": "12.1.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

@@ -623,6 +623,7 @@ export type {
     AccountDialogControllerOptions,
     AccountDialogSnapshot,
     AccountDialogView,
+    CommonsAvailability,
     SignInFlowPhase,
     SignInFlowState,
 } from './session/accountDialogController';

package/src/session/__tests__/accountDialogController.test.ts

@@ -152,6 +152,7 @@ describe('AccountDialogController — initial + views', () => {
     expect(snap.loading).toBe(false);
     expect(snap.switchingAccountId).toBeNull();
     expect(snap.signIn.phase).toBe('idle');
+    expect(snap.commonsAvailability).toBe('unknown');
   });
 
   it('setView / add / close move between views and notify subscribers', () => {
@@ -169,6 +170,19 @@ describe('AccountDialogController — initial + views', () => {
     expect(seen).toEqual(['add', 'signin', 'accounts']);
   });
 
+  it('startSignup moves to the signup view and notifies subscribers', () => {
+    const { controller } = makeHarness();
+    const seen: string[] = [];
+    controller.subscribe((s) => seen.push(s.view));
+
+    controller.startSignup();
+    expect(controller.getSnapshot().view).toBe('signup');
+    controller.close();
+    expect(controller.getSnapshot().view).toBe('accounts');
+
+    expect(seen).toEqual(['signup', 'accounts']);
+  });
+
   it('getSnapshot returns a stable reference until a change occurs', () => {
     const { controller } = makeHarness();
     const a = controller.getSnapshot();
@@ -391,6 +405,54 @@ describe('AccountDialogController — switchTo (uniform switch)', () => {
     expect(commitSession.mock.calls[0][0]).toMatchObject({ sessionId: 'sess-org', accessToken: 'access-org' });
   });
 
+  it('commits a graph switch via the IN-PLACE commitSwitchedSession — never the hub-syncing commitSession', async () => {
+    // PROBLEM 2: an account switch must not run the cross-origin hub-sync
+    // full-page redirect. When both funnels are wired, the mint-switch must use
+    // commitSwitchedSession (in-place) and NEVER commitSession (which may
+    // redirect on an official web origin).
+    const oxy = makeOxy();
+    const sc = new TestSessionClient(host());
+    sc.set(state([{ accountId: 'a1', sessionId: 's1' }], 'a1'));
+    jest.spyOn(sc, 'switchAccount').mockResolvedValue(undefined);
+    oxy.switchToAccount.mockResolvedValue({
+      sessionId: 'sess-org',
+      deviceId: 'device-1',
+      expiresAt: '2030-01-01T00:00:00Z',
+      accessToken: 'access-org',
+      user: user('org1'),
+    });
+    const commitSession = jest.fn().mockResolvedValue(undefined);
+    const commitSwitchedSession = jest.fn().mockResolvedValue(undefined);
+    const controller = new AccountDialogController({
+      oxyServices: oxy as unknown as OxyServices,
+      sessionClient: sc,
+      clientId: 'oxy_dk_test',
+      commitSession,
+      commitSwitchedSession,
+    });
+
+    await controller.switchTo('org1');
+
+    expect(commitSwitchedSession).toHaveBeenCalledTimes(1);
+    expect(commitSwitchedSession.mock.calls[0][0]).toMatchObject({ sessionId: 'sess-org', accessToken: 'access-org' });
+    expect(commitSession).not.toHaveBeenCalled();
+  });
+
+  it('surfaces a failed switch as snapshot.error instead of silently no-op\'ing', async () => {
+    // PROBLEM 1: switching into an account the server refuses (e.g. a 403 for a
+    // personal-kind target) must tell the user why — the error is recorded on
+    // the snapshot, the switch does not throw, and switchingAccountId resets.
+    const { controller, oxy, sc } = makeHarness();
+    sc.set(state([{ accountId: 'a1', sessionId: 's1' }], 'a1'));
+    oxy.switchToAccount.mockRejectedValue(new Error('Cannot switch into a personal account'));
+
+    await expect(controller.switchTo('org1')).resolves.toBeUndefined();
+
+    const snap = controller.getSnapshot();
+    expect(snap.error).toBe('Cannot switch into a personal account');
+    expect(snap.switchingAccountId).toBeNull();
+  });
+
   it('falls back to SessionClient.registerAndActivate when no commitSession is supplied', async () => {
     const oxy = makeOxy();
     const sc = new TestSessionClient(host());
@@ -579,7 +641,7 @@ describe('AccountDialogController — sign in with Oxy', () => {
   });
 });
 
-describe('AccountDialogController — Commons deep-link (canOpenApp)', () => {
+describe('AccountDialogController — Commons availability (canOpenApp)', () => {
   const START_HANDLE = {
     sessionToken: 'secret-tok',
     authorizeCode: 'AUTH-CODE',
@@ -621,6 +683,7 @@ describe('AccountDialogController — Commons deep-link (canOpenApp)', () => {
     expect(snap.view).toBe('qr');
     expect(snap.signIn.phase).toBe('waiting');
     expect(snap.signIn.qrPayload).toBe('oxycommons://approve?v=1&code=AUTH-CODE');
+    expect(snap.commonsAvailability).toBe('available');
     controller.cancelSignIn();
   });
 
@@ -635,6 +698,7 @@ describe('AccountDialogController — Commons deep-link (canOpenApp)', () => {
     expect(canOpenApp).toHaveBeenCalledWith('oxycommons://');
     expect(openUrl).not.toHaveBeenCalled();
     expect(controller.getSnapshot().signIn.phase).toBe('waiting');
+    expect(controller.getSnapshot().commonsAvailability).toBe('unavailable');
     controller.cancelSignIn();
   });
 
@@ -647,10 +711,11 @@ describe('AccountDialogController — Commons deep-link (canOpenApp)', () => {
 
     expect(openUrl).not.toHaveBeenCalled();
     expect(controller.getSnapshot().signIn.qrPayload).toBe('oxycommons://approve?v=1&code=AUTH-CODE');
+    expect(controller.getSnapshot().commonsAvailability).toBe('unknown');
     controller.cancelSignIn();
   });
 
-  it('swallows a canOpenApp probe rejection and keeps the QR fallback', async () => {
+  it('swallows a canOpenApp probe rejection, keeps the QR fallback, and records unavailable', async () => {
     const openUrl = jest.fn();
     const canOpenApp = jest.fn().mockRejectedValue(new Error('probe boom'));
     const { controller } = makeController({ openUrl, canOpenApp });
@@ -660,8 +725,20 @@ describe('AccountDialogController — Commons deep-link (canOpenApp)', () => {
 
     expect(openUrl).not.toHaveBeenCalled();
     expect(controller.getSnapshot().signIn.phase).toBe('waiting');
+    expect(controller.getSnapshot().commonsAvailability).toBe('unavailable');
     controller.cancelSignIn();
   });
+
+  it('start() eagerly resolves commonsAvailability without requiring a QR flow', async () => {
+    const canOpenApp = jest.fn().mockResolvedValue(true);
+    const { controller } = makeController({ canOpenApp });
+
+    controller.start();
+    await flush();
+
+    expect(canOpenApp).toHaveBeenCalledWith('oxycommons://');
+    expect(controller.getSnapshot().commonsAvailability).toBe('available');
+  });
 });
 
 describe('AccountDialogController — /auth-session socket (instant QR wake)', () => {

package/src/session/__tests__/accountProjection.test.ts

@@ -164,6 +164,36 @@ describe('projectSwitchableAccounts', () => {
     });
     expect(rows.every((r) => !r.isCurrent)).toBe(true);
   });
+
+  it('keeps the OPERATOR full set when acting-as a sub-account (no collapse to the active account)', () => {
+    // nate operates albert: albert is the active on-device account, nate is also
+    // on-device, and the graph is OPERATOR-anchored (the server returns nate's
+    // full forest regardless of which account is active). The projection must
+    // faithfully union — switching in only changes which row is `isCurrent`,
+    // never which accounts are listed. This is the switcher-collapse regression.
+    const rows = projectSwitchableAccounts({
+      state: state([{ accountId: 'nate', sessionId: 's-nate' }, { accountId: 'albert', sessionId: 's-albert' }], 'albert'),
+      graph: [
+        graphNode('nate', { kind: 'personal', relationship: 'self' }),
+        graphNode('albert', { relationship: 'owner' }),
+        graphNode('oxy', { relationship: 'owner' }),
+        graphNode('faircoin', { relationship: 'owner' }),
+      ],
+      profilesById: mapOf(user('nate'), user('albert'), user('oxy'), user('faircoin')),
+      resolveAvatarUrl: noAvatar,
+    });
+
+    // The full operable set is present even though a leaf sub-account is active.
+    expect(rows.map((r) => r.accountId).sort()).toEqual(['albert', 'faircoin', 'nate', 'oxy']);
+    // Exactly the active sub-account is flagged current; operator + siblings stay.
+    expect(rows.find((r) => r.accountId === 'albert')?.isCurrent).toBe(true);
+    expect(rows.filter((r) => r.isCurrent)).toHaveLength(1);
+    // The operator's own personal account is not dropped by acting-as.
+    expect(rows.find((r) => r.accountId === 'nate')).toBeDefined();
+    // Graph-only siblings (operable but not yet on this device) still appear.
+    expect(rows.find((r) => r.accountId === 'oxy')?.onDevice).toBe(false);
+    expect(rows.find((r) => r.accountId === 'faircoin')?.onDevice).toBe(false);
+  });
 });
 
 describe('switchableAccountIds', () => {

package/src/session/accountDialogController.ts

@@ -12,17 +12,23 @@
  *   - the unified account list (via {@link projectSwitchableAccounts}), fetched
  *     from `SessionClient` state ∪ `oxyServices.listAccounts()` and hydrated
  *     with `oxyServices.getUsersByIds()`;
- *   - the dialog `view` state machine (`accounts` | `signin` | `qr` | `add`);
+ *   - the dialog `view` state machine (`accounts` | `signin` | `qr` | `add` |
+ *     `signup`);
  *   - `switchTo` (the uniform switch: `SessionClient.switchAccount` for an
  *     account already on the device, `oxyServices.switchToAccount` to mint on
  *     first entry into a graph account — reusing the existing SDK primitives, no
  *     new switch path);
  *   - the "Sign in with Oxy" device flow (same-device shared-keychain via
  *     `oxyServices.signInWithSharedIdentity`, else the cross-device QR handoff
- *     via `startCommonsSignIn` → poll → `claimSessionByToken`).
+ *     via `startCommonsSignIn` → poll → `claimSessionByToken`);
+ *   - `commonsAvailability` — whether Commons is installed on this device
+ *     (native only, via the injected `canOpenApp` probe), so the QR view can
+ *     offer a "Get Commons" fallback instead of a same-device dead end.
  *
  * Sign-in is passkey (WebAuthn) or the Commons QR / shared-keychain handoff —
- * password, social login, and 2FA were removed ecosystem-wide.
+ * password, social login, and 2FA were removed ecosystem-wide. Account
+ * creation (`signup` view) is the same two identity backends: a passkey
+ * ceremony on web, or a Commons-created identity.
  */
 
 import type { OxyServices } from '../OxyServices';
@@ -40,7 +46,20 @@ import {
 import type { AccountNode } from '../mixins/OxyServices.accounts';
 
 /** The dialog's top-level view. */
-export type AccountDialogView = 'accounts' | 'signin' | 'qr' | 'add';
+export type AccountDialogView = 'accounts' | 'signin' | 'qr' | 'add' | 'signup';
+
+/**
+ * Whether Commons is installed on this device, as resolved by the injected
+ * `canOpenApp` probe:
+ *   - `'unknown'` — not yet probed, OR no probe was injected (web — there is
+ *     no API to ask a browser whether a custom URL scheme is registered, so
+ *     this stays `'unknown'` forever there and the QR view renders
+ *     unconditionally, no gating).
+ *   - `'checking'` — the probe is in flight.
+ *   - `'available'` / `'unavailable'` — the probe's resolved terminal answer
+ *     (native only). A probe error is treated as `'unavailable'` (fail-closed).
+ */
+export type CommonsAvailability = 'unknown' | 'checking' | 'available' | 'unavailable';
 
 /** Lifecycle phase of the "Sign in with Oxy" device flow. */
 export type SignInFlowPhase = 'idle' | 'starting' | 'waiting' | 'authorized' | 'error';
@@ -80,6 +99,8 @@ export interface AccountDialogSnapshot {
   switchingAccountId: string | null;
   /** The "Sign in with Oxy" device-flow state. */
   signIn: SignInFlowState;
+  /** Whether Commons is installed on this device. See {@link CommonsAvailability}. */
+  commonsAvailability: CommonsAvailability;
 }
 
 /** Construction options for {@link AccountDialogController}. */
@@ -98,15 +119,36 @@ export interface AccountDialogControllerOptions {
   /** Locale for display-name resolution. */
   locale?: string;
   /**
-   * Commit a freshly-authorized session (device flow / shared identity / minted
-   * graph switch) into the host's session set — device-first registration +
-   * durable persist + profile hydration. The consumer supplies its provider's
-   * commit path (`useOxy().handleWebSession` / the auth-sdk equivalent). Called
-   * AFTER the SDK has planted the access token. When omitted the controller
-   * falls back to `SessionClient.registerAndActivate` (registration + activation
-   * only — no provider-side durable persist/hydration).
+   * Commit a freshly-authorized SIGN-IN session (device flow / shared identity)
+   * into the host's session set — device-first registration + durable persist +
+   * profile hydration. The consumer supplies its provider's commit path
+   * (`useOxy().handleWebSession` / the auth-sdk equivalent). Called AFTER the SDK
+   * has planted the access token. When omitted the controller falls back to
+   * `SessionClient.registerAndActivate` (registration + activation only — no
+   * provider-side durable persist/hydration).
+   *
+   * This is the SIGN-IN commit: on an official web origin it may run the
+   * cross-origin hub-sync (a full-page redirect to `auth.oxy.so/sync`) that
+   * bootstraps silent OAuth restore on OTHER origins. A first sign-in on a web
+   * origin legitimately needs that. An account SWITCH does NOT — see
+   * {@link commitSwitchedSession}.
    */
   commitSession?: (session: SessionLoginResponse) => Promise<void>;
+  /**
+   * Commit a minted graph SWITCH session into the host's session set — same
+   * device-first registration + durable persist + profile hydration as
+   * {@link commitSession}, but IN-PLACE: it must NOT trigger the cross-origin
+   * hub-sync redirect. Switching into an account you already operate reuses the
+   * device credential that was already hub-synced at the original sign-in, so
+   * re-syncing is redundant and a full-page redirect on switch is the exact
+   * regression this separation prevents. Cross-tab/app propagation of the switch
+   * still happens instantly via the server's device-scoped `session_state` /
+   * `session_accounts_changed` socket broadcast — no navigation required.
+   *
+   * When omitted the controller falls back to {@link commitSession} (if wired)
+   * and then to `SessionClient.registerAndActivate`.
+   */
+  commitSwitchedSession?: (session: SessionLoginResponse) => Promise<void>;
   /** Notified after a completed sign-in (bearer planted + session committed). */
   onSignedIn?: (user: MinimalUserData) => void;
   /**
@@ -179,6 +221,7 @@ export class AccountDialogController {
   private readonly clientId: string | null;
   private readonly locale?: string;
   private readonly commitSession?: (session: SessionLoginResponse) => Promise<void>;
+  private readonly commitSwitchedSession?: (session: SessionLoginResponse) => Promise<void>;
   private readonly onSignedIn?: (user: MinimalUserData) => void;
   private readonly pollIntervalMs: number;
   private readonly openUrl?: (url: string) => void;
@@ -195,6 +238,7 @@ export class AccountDialogController {
   private error: string | null = null;
   private switchingAccountId: string | null = null;
   private signIn: SignInFlowState = IDLE_SIGN_IN;
+  private commonsAvailability: CommonsAvailability = 'unknown';
 
   // --- Sign-in device-flow bookkeeping ---
   /** The secret device-flow token of the active QR flow (never surfaced). */
@@ -228,6 +272,7 @@ export class AccountDialogController {
     this.clientId = options.clientId ?? null;
     this.locale = options.locale;
     this.commitSession = options.commitSession;
+    this.commitSwitchedSession = options.commitSwitchedSession;
     this.onSignedIn = options.onSignedIn;
     this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
     this.openUrl = options.openUrl;
@@ -288,6 +333,11 @@ export class AccountDialogController {
     // bearer is already planted (warm start); when signed out (cold boot before
     // restore) it re-projects from device state and makes NO private call.
     void this.refresh();
+    // Eager, cached Commons-availability probe (native only — a no-op when no
+    // `canOpenApp` was injected). It's a cheap local OS check, so by the time a
+    // user actually opens the sign-in entry it has almost always resolved —
+    // `showQr`'s own lazy probe below is only the safety net for the rare race.
+    void this.resolveCommonsAvailability();
   }
 
   /**
@@ -378,6 +428,11 @@ export class AccountDialogController {
     this.setView('add');
   }
 
+  /** Switch to the "create account" view (passkey / Commons signup entry). */
+  startSignup(): void {
+    this.setView('signup');
+  }
+
   // =========================================================================
   // Account list
   // =========================================================================
@@ -523,6 +578,10 @@ export class AccountDialogController {
             accessToken: result.accessToken,
           },
           result.user,
+          // A switch is IN-PLACE: commit without the hub-sync redirect (the
+          // device is already known/synced). Cross-tab/app propagation rides the
+          // server's `session_state` socket broadcast, not a navigation.
+          { fromSwitch: true },
         );
       }
       // Re-project + refetch immediately; the subscription also fires.
@@ -591,34 +650,65 @@ export class AccountDialogController {
       // connect, so it now runs at the slow fallback cadence.
       this.openAuthSessionSocket(handle.sessionToken);
       this.scheduleNextPoll(handle.sessionToken);
-      // Same-device convenience: if Commons is installed (native only — `canOpenApp`
-      // is undefined/false on web), deep-link straight into its approve screen with
-      // the same `oxycommons://approve?...` payload the QR encodes. The QR + polling
+      // Same-device convenience: if Commons is confirmed installed (native
+      // only — stays `'unknown'` on web, where this never opens anything),
+      // deep-link straight into its approve screen with the same
+      // `oxycommons://approve?...` payload the QR encodes. The QR + polling
       // stay live as the fallback, so a user who dismisses the app-open still
       // completes the sign-in by scanning.
-      void this.maybeOpenCommons(handle.qrPayload);
+      void this.deepLinkIntoCommonsIfAvailable(handle.qrPayload);
     } catch (error) {
       this.setSignIn({ ...IDLE_SIGN_IN, phase: 'error', error: errorMessage(error) });
     }
   }
 
   /**
-   * When a `canOpenApp` probe is injected and reports Commons installed, open the
-   * approve deep link via the injected `openUrl`. Best-effort and non-blocking: a
-   * probe/open failure is logged and swallowed — the QR/polling fallback remains.
+   * Resolve whether Commons is installed on this device via the injected
+   * `canOpenApp` probe, updating {@link commonsAvailability} as durable,
+   * observable snapshot state. Native only — a no-op when `canOpenApp` was
+   * not injected (web), where `commonsAvailability` stays `'unknown'` forever
+   * and the QR view renders unconditionally (no gating).
+   *
+   * Replaces the old `maybeOpenCommons` fire-and-forget probe, whose outcome
+   * was only ever reflected by whether Commons silently opened — a probe
+   * failure or "not installed" answer was swallowed into a debug log with no
+   * way for the UI to react. `commonsAvailability` fixes that.
    */
-  private async maybeOpenCommons(qrPayload: string): Promise<void> {
-    if (!this.canOpenApp || !this.openUrl) return;
+  private async resolveCommonsAvailability(): Promise<void> {
+    if (!this.canOpenApp) return;
+    this.commonsAvailability = 'checking';
+    this.emit();
+    let available = false;
     try {
-      if (await this.canOpenApp(COMMONS_APP_SCHEME)) {
-        this.openUrl(qrPayload);
-      }
+      available = await this.canOpenApp(COMMONS_APP_SCHEME);
     } catch (error) {
       logger.debug(
-        '[AccountDialogController] Commons deep-link probe failed (QR fallback active)',
+        '[AccountDialogController] Commons availability probe failed',
         { component: 'AccountDialogController' },
         error,
       );
+      available = false; // fail-closed — treat a probe error as "not installed"
+    }
+    this.commonsAvailability = available ? 'available' : 'unavailable';
+    this.emit();
+  }
+
+  /**
+   * When Commons is confirmed installed, deep-link straight into its approve
+   * screen via the injected `openUrl` with the same `oxycommons://approve?...`
+   * payload the QR encodes. Best-effort and non-blocking — the QR/polling
+   * fallback stays live regardless of the outcome here.
+   */
+  private async deepLinkIntoCommonsIfAvailable(qrPayload: string): Promise<void> {
+    if (!this.openUrl) return;
+    if (this.commonsAvailability === 'unknown' || this.commonsAvailability === 'checking') {
+      // The eager `start()` probe hasn't resolved yet (or was never run, e.g.
+      // `showQr` called without a prior `start()`) — resolve it now rather
+      // than skipping the deep link.
+      await this.resolveCommonsAvailability();
+    }
+    if (this.commonsAvailability === 'available') {
+      this.openUrl(qrPayload);
     }
   }
 
@@ -755,15 +845,25 @@ export class AccountDialogController {
 
   /**
    * Register a token-planted session into the device set. Prefers the
-   * consumer's `commitSession` (durable persist + hydration); falls back to
+   * consumer's commit funnel (durable persist + hydration); falls back to
    * `SessionClient.registerAndActivate` (registration + activation only).
+   *
+   * A SWITCH (`opts.fromSwitch`) uses the IN-PLACE `commitSwitchedSession` funnel
+   * so it never runs the cross-origin hub-sync redirect; a SIGN-IN uses
+   * `commitSession` (which may hub-sync on an official web origin). When the
+   * switch funnel is not wired it falls back to the sign-in funnel, then to
+   * `registerAndActivate`.
    */
   private async commitAuthorizedSession(
     session: SessionLoginResponse,
     user: MinimalUserData,
+    opts?: { fromSwitch?: boolean },
   ): Promise<void> {
-    if (this.commitSession) {
-      await this.commitSession(session);
+    const commit = opts?.fromSwitch
+      ? this.commitSwitchedSession ?? this.commitSession
+      : this.commitSession;
+    if (commit) {
+      await commit(session);
     } else {
       await this.sessionClient.registerAndActivate(user.id);
     }
@@ -875,6 +975,7 @@ export class AccountDialogController {
       error: this.error,
       switchingAccountId: this.switchingAccountId,
       signIn: this.signIn,
+      commonsAvailability: this.commonsAvailability,
     };
   }