Invite links: starsync:// opens the app and asks to join; one app per profile; real invite address; clipboard pick-up

- starsync://host:port/?name=&pw= (PROTOCOL.md "Invite link"); the password only when ticked, never in logs
- Linux: launcher entry takes x-scheme-handler/starsync (%u, StartupNotify) and becomes its xdg-mime default; Windows: HKCU\Software\Classes\starsync -> starsync.exe
- InstanceLock: lock file + loopback handoff per profile folder; the running app comes up with the second start's activation token (Wayland/X11) or AllowSetForegroundWindow (Windows)
- Sharing looks up the internet address (HTTPS services with fallbacks); members card picks Internet / Home network / VPN and says when the port needs forwarding
- JoinOffers: link and clipboard prompt with /health, joins through ConnectFlow; dismissed clipboard invites kept as fingerprints

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

apps/desktop/lib/main.dart

@@ -10,16 +10,26 @@ import 'src/app/app_graph.dart';
 import 'src/files/thumbnails.dart' show thumbnailPlayers;
 import 'src/platform/app_log.dart';
 import 'src/platform/app_shutdown.dart' show closeAppWith;
+import 'src/platform/desktop/attention.dart' show exitNow, windowLaunchToken;
 import 'src/platform/desktop/desktop_app_dirs.dart';
+import 'src/platform/desktop/windows_api.dart' show allowSetForegroundWindow;
 import 'src/platform/desktop_entry.dart';
+import 'src/platform/ports/window_activity.dart';
+import 'src/platform/single_instance.dart';
+import 'src/platform/url_scheme.dart';
 import 'src/platform/smoke.dart';
 import 'src/screens/home/ui.dart';
 import 'src/session/app_events.dart' show UpdateAvailable;
+import 'src/session/invite.dart' show InviteLink;
 import 'src/state/settings.dart';
 import 'src/update/update_controller.dart' show UpdatePhase, launchArgs;
 
 Future<void> main(List<String> args) async {
-  launchArgs = List.unmodifiable(args);
+  // An invite link is handled once: Update and restart does not pass it on.
+  launchArgs = List.unmodifiable([
+    for (final a in args)
+      if (InviteLink.parse(a) == null) a,
+  ]);
   if (args.contains('--upgrade')) {
     exitCode = await runUpgrade();
     exit(exitCode);
@@ -44,6 +54,15 @@ Future<void> main(List<String> args) async {
       );
   WidgetsFlutterBinding.ensureInitialized();
   final dirs = await const DesktopAppDirs().resolve();
+  // One app per profile: a second start (a clicked starsync:// link) hands
+  // its arguments to the running one and ends before its window shows.
+  final instance = await InstanceLock.claim(
+    Directory(dirs.hive).parent.path,
+    args: args,
+    activation: await windowLaunchToken(),
+    beforeSend: Platform.isWindows ? allowSetForegroundWindow : null,
+  );
+  if (instance == null) await exitNow();
   await startAppLogging(dirs);
   Hive.init(dirs.hive);
   await AppSettings.instance.ensureLoaded();
@@ -52,14 +71,19 @@ Future<void> main(List<String> args) async {
   final ports = graph.ports;
   // Close button / Alt+F4: the orderly close ([shutDownApp]), so others
   // see "left", your server shuts down and no player outlives the engine.
-  final close = closeAppWith(graph);
+  final close = closeAppWith(graph, instance: instance);
   await ports.shell.start(
       title: dirs.profile == null ? appName : '$appName [${dirs.profile}]', onCloseRequest: () => close());
   // Focus, minimise and restore feed auto sit-out and the Notifier (in
   // the background, notices go out as system notifications).
+  // Coming to the front also looks for an invite on the clipboard (the
+  // join prompt; nothing of it is logged).
   ports.shell.watchActivity((a) {
     graph.coordinator.windowActivity(a);
     graph.notifier.window = a;
+    if (a == WindowActivity.focused) {
+      unawaited(ports.shell.readClipboardText().then(graph.joinOffers.fromClipboard));
+    }
   });
   try {
     await graph.forms.load();
@@ -76,6 +100,8 @@ Future<void> main(List<String> args) async {
   ports.links.warmUp();
   // Linux: the launcher entry and icon Wayland needs (release installs).
   unawaited(installDesktopEntry());
+  // Windows: starsync:// links start this install (HKCU, release builds).
+  unawaited(registerWindowsScheme());
   // A found update is an event too (the band shows it).
   final updates = graph.updates;
   updates.status.addListener(() {
@@ -94,6 +120,14 @@ Future<void> main(List<String> args) async {
   // Home: your own server, quietly (only this app can reach it until
   // Invite).
   unawaited(graph.navigation.start());
+  // A clicked invite link: the one this app started with, then each one a
+  // later start hands over (the window comes to the front for it).
+  graph.joinOffers.fromArgs(args);
+  instance.handoffs.listen((h) {
+    unawaited(ports.shell.focus(activation: h.activation));
+    graph.joinOffers.fromArgs(h.args);
+  });
+  unawaited(ports.shell.readClipboardText().then(graph.joinOffers.fromClipboard));
   // The sound device opens once the window is up, not on the first sound.
   Future.delayed(const Duration(seconds: 2), graph.sfx.warmUp);
 }