Files

gsxdsm 3b52a4d2d9 FN-7527: fix desktop server switching redirects

Route desktop shell server switches through the live runtime/profile state.

- Replace separate local/remote redirect effects with a shared resolver that uses localRuntime/baseUrl and active remote profiles.
- Remove the dead localServer shell state field and document the local/remote switch navigation behavior.
- Add regression coverage for desktop shell redirect targets and include a patch changeset.

Files changed:
 .changeset/fn-7527-desktop-switch-server-navigation.md    |   7 +
 docs/native-shell.md                               |   2 +-
 packages/dashboard/app/App.tsx                     |  44 ++---
 packages/dashboard/app/components/__tests__/App.test.tsx          |   1 -
 packages/dashboard/app/types/native-shell.d.ts     |  13 +-
 packages/dashboard/app/utils/__tests__/appLifecycle.test.ts       | 180 +++++++++++++++++++++
 packages/dashboard/app/utils/appLifecycle.ts       |  70 ++++++++
 7 files changed, 280 insertions(+), 37 deletions(-)

Fusion-Task-Id: FN-7527

Fusion-Task-Lineage: a0fe5cbc-120b-4a56-b791-48306223a636

Co-authored-by: Fusion (runfusion.ai) <noreply@runfusion.ai>

2026-07-04 13:43:59 -07:00

4.7 KiB

Raw Blame History

Native Shell Connection Guide

← Docs index

This is the canonical guide for how Fusion native shells (mobile and desktop) connect to remote Fusion dashboards, persist saved connections, and hand off shell state to the dashboard.

Overview

Native shells expose a shared window.fusionShell bridge that the dashboard reads through ShellContext.

Mobile shell always runs in remote mode and requires an active connection profile.
Desktop shell supports both Local Fusion and Remote Server modes.
Web/PWA does not use shell onboarding.

First-run onboarding flow

The dashboard gates first-run shell onboarding in requiresNativeShellOnboarding(...) (packages/dashboard/app/App.tsx):

host === "mobile-shell": onboarding is required until activeProfileId is set.
host === "desktop-shell":
- desktopMode === "local": onboarding is not required.
- desktopMode === "remote" (or unset): onboarding is required until activeProfileId is set.

NativeShellOnboardingModal then provides:

Desktop mode choice (desktop only):
- Local Fusion → calls setDesktopMode("local").
- Remote Server → stays in remote flow.
Remote connection entry (mobile + desktop remote mode):
- Scan QR (startQrScan())
- Manual fields: profile name, server URL, optional auth token
Continue:
- Saves profile via saveProfile(...)
- Sets desktop mode to remote when relevant
- Activates profile via setActiveProfile(...)
- Redirects to selected remote dashboard URL (adds rt=<token> query when token is present)

QR scan and manual fallback

QR scan is optional convenience. Manual entry is always supported.

QR payload parsing accepts either:

JSON payload with serverUrl and optional authToken
URL payload, reading token from authToken or rt

If scanning fails or is unavailable, users can continue with manual URL + token entry.

Saved connection profiles

Profiles are first-class saved objects shared by onboarding and Connection Manager:

name
serverUrl
optional authToken
timestamps (createdAt, updatedAt, lastUsedAt)

Connection Manager supports:

Desktop Switch server presents the built-in Local Server separately from saved Remote servers. Local Server is always available in the desktop shell; selecting it calls setDesktopMode("local") and returns the shell to the embedded/local Fusion server without deleting remote profiles. Choosing Local Server or a remote profile from this in-dashboard menu navigates the renderer to the selected server's origin (the running local runtime's baseUrl, or the remote profile's serverUrl) — the same end result as switching modes from the native desktop menu (FN-7527).
Add remote server is the desktop CTA for saving another Fusion server profile. The remote profile editor stays collapsed until a user chooses Add remote server or edits an existing saved profile, so local-only desktop users do not see an empty setup form.
Use (activate a saved remote profile). In desktop local mode, using a remote profile first switches desktop mode back to remote, then activates the selected profile.
Edit (update name/URL/token)
Delete
Mobile Add connection / Scan QR remains focused on remote profile setup and does not show the desktop-only Local Server guidance.

Activation updates activeProfileId and stamps lastUsedAt on the selected profile.

Desktop remote handoff behavior

Desktop shell stores shell settings separately from Fusion project/global settings.

When desktop mode is remote and an active profile exists, App.tsx redirects to that profile URL and appends rt when a token exists.

When desktop mode is local and the local server reports ready with a port, App.tsx redirects to http://localhost:<port>.

Persistence model

Mobile shell: connection profiles + active profile are persisted through Capacitor Preferences (packages/mobile/src/plugins/connection-profiles.ts).
Desktop shell: shell settings are persisted in app-owned JSON at app.getPath("userData")/shell-connections.json (packages/desktop/src/shell-settings.ts).

Security guidance

Tokenized URLs and QR payloads are secrets.

Treat rt/authToken values like passwords.
Do not paste tokenized links into chats, screenshots, or tickets.
Prefer short-lived token workflows when sharing access.

For canonical token caveats and operator guidance, see Remote Access runbook.

4.7 KiB Raw Blame History