Node connection flow plan

Status: partial implementation prepared in an isolated worktree, not deployed. Uses existing components, colors, spacing, glass cards, typography and motion. Connection reliability and the remaining acceptance below must be qualified before this flow ships.

Implemented UI step — 2026-10-08

Web5 exposes Connect with Nodes and Connected Nodes above the mobile collapse.
Existing Federation route has Discover, Requests, Connected and Network Map tabs even with zero peers. The route query retains selection; legacy view=list opens Connected. Existing node detail modals preserve the underlying view.
Discovery reuses the existing component inline, with local name/identity search, retained results/search across tab switches and stale-response rejection. The existing 30-second RPC timeout and signing confirmation remain in place. Presence advertisements explicitly do not imply reachability or authorization.
Existing requests open Requests and existing peers open their detail; fresh requests still use the existing confirmation and Observer semantics. Own-node Trusted linking remains the separate, existing authenticated invite action.
Requests has an empty state and active count. Action errors remain visible across tabs. Approved—connecting and Peer added remain distinct: persisted local membership does not assert reciprocal connection confirmation.
Navigating away during initial identity loading cannot start a later orphaned polling timer. No backend, API contract, trust elevation or payment changes.

Additional return-path step:

Cloud entry preserves its selected tab/category on return, including loading a directly restored Paid Files tab. Fleet separates Connect with Nodes from its explicit Link your own nodes entry, without automatically creating an invite.
Peer Files returns to the correct node detail and Connected view. Closing that detail clears only the selection query so refresh cannot reopen it.
Manual direct entry routes known discovery identities/current requests through the existing flow. Failed sends keep the confirmation, message and address for retry; duplicate clicks issue one request. Unknown approval age stays unresolved rather than enabling an accidental second request; valid expiry follows the backend's existing 30-day limit.

Validation: 33 focused cases across seven affected files pass, plus app-project vue-tsc -p tsconfig.app.json --noEmit. The initial second-slice run had 32 passes and one stale Vue wrapper assertion after rerender; reacquiring the current dialog and checking visible error text passed all eight targeted discovery cases. No production source fix was needed for that test assertion. Source browser checks pass at 390/1440px with no page errors, document overflow or unexpected RPC. The first cold navigation timed out during Vite dependency optimization; the bounded warm retry passed. No deployed-artifact, actual companion or live-node acceptance is claimed. Evidence: release-qualification/connection-journey-20261008/ under the local Archipelago state directory. Browser fixture allows only loopback synthetic RPC.

Still open: authenticated reciprocal confirmation/retry acceptance, stale-advertisement age when supplied by the protocol, desktop/phone UAT and before/after timings. These UI steps do not complete the real-node release gates.

Entry and return paths

Web5 always exposes Connect with Nodes, including when mobile quick actions are collapsed. Keep Connected Nodes beside the entry or directly below it.
Cloud peer files links to the same connection flow and retains its return location. Successful connection returns to that peer's files when appropriate.
Fleet provides the same connection entry, with an explicit distinction between connecting to another person's node and linking a node the operator owns.
Open the route immediately with cached safe summaries or a loading state; discovery and transport checks run after navigation. Do not await remote calls before rendering the destination. Cancel obsolete work on navigation away.

Connect with Nodes

Use one page with existing tabs: Discover, Requests, Connected. On mobile keep tabs in one horizontally scrollable row. Preserve the selected view, search and scroll position when opening a node and returning.

Discover shows the existing opt-in Nostr presence results and an explicit invite entry. Search updates locally; refresh provides immediate progress, timeout and retry feedback. Distinguish stale advertisements from recently contacted nodes. A presence event is discovery information, not authorization or proof of reachability.

Each node has a single clear action: Request connection, View request, or Open node according to its actual state. Explain what information the request shares. Avoid duplicate requests on repeated taps or when responses arrive late.

Requests and approval

Display incoming and sent Nostr requests in the same Requests view, with counts and a readable node identity/name. Incoming requests offer Approve or Reject; sent requests offer Cancel. Keep completed history available but secondary.

An approval progresses through distinct states:

Request sent / Awaiting approval.
Approved / Connecting — authenticated invitation accepted, join not confirmed.
Connected — persisted relationship and authenticated reciprocal confirmation.
Connection delayed — show bounded retry and a useful error; retain the approved operation so restart, lost acknowledgement or transient outage can recover.

Do not label relay acceptance as peer connection. A retry must reuse the same logical operation, prevent duplicate peers and retain the operator's trust choice. Cancellation/rejection delivery failures must be visible rather than reported as successfully notified. Define recovery for already-approved legacy requests.

Normal discovery connections grant Observer access. Link your own nodes must be a separate explicit flow with existing ownership/authentication requirements; being reachable over FIPS never grants Trusted access or remote management rights.

Connected nodes and Fleet

Show actual connection state and last successful authenticated contact. Distinguish Offline, Connecting, Unknown and Metrics unavailable. Last report age alone does not establish when a node went offline. Future/skewed timestamps must not make a node permanently online.

Default ordering: online, connecting, unknown, confirmed offline; stable ordering within groups. Honor manually selected sorting/filtering and do not disrupt the user's selection while metrics update. Offline rows show last contact; show an "offline for" duration only when an observed transition supports it.

The existing network map uses matching status labels and accessible details; color alone is insufficient. Node detail keeps Connect/Retry, Files and permitted management actions together. Do not add duplicate connection mechanisms.

Acceptance before deployment

Two real nodes: request, approval, reciprocal connection and persisted lists.
Retry after lost reply, duplicate/reordered events, restart on each side, unavailable relay, FIPS outage and supported transport recovery.
Invalid signatures, unsolicited invites, wrong identities, stale/cancelled requests and blocked peers cannot gain access or elevate trust.
Desktop and actual companion: first connection, revisit, back navigation, search, tab switching, refresh, background/resume and interrupted network.
Measure tap-to-feedback, first usable content, discovery completion and approval-to-confirmed-connection before and after. Preserve unknown data.
Operator UAT gives exact nodes, steps and expected states; no extra payment or wallet/channel changes are needed for connection testing.

7.7 KiB Raw Blame History