2eba5a007c
Adds a native shell integration guide (FN-3577) with fusionShell bridge contract documentation, wired into the docs navigation, plus a regression test; also hardens the dependency graph's task filtering (FN-3085) to include in-review tasks and handle orphan edges, with corresponding test coverage ac Fusion-Task-Id: FN-3577
96 lines
3.6 KiB
Markdown
96 lines
3.6 KiB
Markdown
# Native Shell Connection Guide
|
|
|
|
[← Docs index](./README.md)
|
|
|
|
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:
|
|
|
|
1. **Desktop mode choice** (desktop only):
|
|
- **Local Fusion** → calls `setDesktopMode("local")`.
|
|
- **Remote Server** → stays in remote flow.
|
|
2. **Remote connection entry** (mobile + desktop remote mode):
|
|
- **Scan QR** (`startQrScan()`)
|
|
- Manual fields: profile name, server URL, optional auth token
|
|
3. **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:
|
|
|
|
- **Use** (activate profile)
|
|
- **Edit** (update name/URL/token)
|
|
- **Delete**
|
|
- **Add connection**
|
|
|
|
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](./remote-access.md).
|
|
|
|
## Related docs
|
|
|
|
- [Dashboard Guide](./dashboard-guide.md)
|
|
- [Architecture](./architecture.md)
|
|
- [Mobile Development Guide](../MOBILE.md)
|
|
- [Remote Access runbook](./remote-access.md)
|