#1391 Add menu entry and docs for running app in remote mode

doc/helgobox/modules/ROOT/nav.adoc

@@ -13,5 +13,6 @@
 *** xref:app/user-interface/navigation-bar.adoc[]
 *** xref:app/user-interface/settings-dialog.adoc[]
 *** xref:app/user-interface/keyboard-shortcuts.adoc[]
+*** xref:app/user-interface/cli.adoc[]
 * xref:reaper-actions.adoc[]
 * xref:configuration-files.adoc[]

doc/helgobox/modules/ROOT/pages/app.adoc

@@ -2,4 +2,74 @@
 
 ____
 include::partial$app-desc.adoc[]
-____
+____
+
+You can run the app in two ways: *Embedded* or *Remote*
+
+[[app-embedded-mode]]
+== Embedded mode
+
+Each Helgobox instance can display its own xref:app.adoc[] window, directly embedded into REAPER:
+
+. Open the xref:plug-in.adoc[]
+. Press menu:Menu[Show App]
+
+Embedded mode is the recommended way to run the app, offering seamless integration with REAPER.
+
+[[app-remote-mode]]
+== Remote mode
+
+There's an additional way to use the app: To run it as a separate program that connects with REAPER over a network connection.
+
+=== Use cases
+
+Running the app in remote mode opens up interesting possibilities.
+
+Crash protection::
+You can start the app on the same machine, but outside of REAPER.
+If it crashes for some reason, only the app itself will crash.
+REAPER and the xref:plug-in.adoc[] will continue running. It's similar to running plug-ins in REAPER in bridged mode. This could be interesting for live scenarios.
+
+Additional views::
+You can open additional app windows on the same machine and connect them to the same xref:key-concepts.adoc#instance[]. This gives you multiple views on the same instance.
+
+Performance optimization::
+You can run the app on an extra computer and connect it to REAPER on the main machine. This way, you can be sure that the app doesn't take any valuable processing power away from REAPER and the xref:plug-in.adoc[].
+
+Touch screen operation::
+Maybe your main machine is a powerful Mac mini standing somewhere further away from you. You could take a Windows tablet (and in the future an iOS or Android tablet) and run the app there, connecting to your main machine.
+
+=== How to do it
+
+==== Starting the server
+
+To allow connections to Helgobox from computers in the same network, you need to start the xref:plug-in/user-interface/menu-bar.adoc#server[Helgobox Server].
+
+. Open the xref:plug-in.adoc[]
+. Press menu:Menu[Server > Enable and start!]
+
+This needs to be done only once.
+
+==== Starting the app
+
+Just like the plug-in, the app is part of the Helgobox installation and is located in your REAPER resource directory:
+
+. Open the xref:plug-in.adoc[]
+. Press menu:Menu[Server > Open app folder]
+. Start the executable:
+[horizontal]
+Windows:: `helgobox.exe`
+macOS:: `helgobox`
+Linux:: `helgobox`
+
+By default, the app connects to the xref:plug-in.adoc[] running on the same machine. You can change this by running the app with xref:app/user-interface/cli.adoc[command line arguments].
+
+.Copying the app directory somewhere else
+[CAUTION]
+====
+You may copy the app directory to another location or even to another computer. However, you should renew your copy whenever you update Helgobox! An update often contains both a new version of the xref:plug-in.adoc[] **and** a new version of the xref:app.adoc[].
+
+If you connect the app to a plug-in and the versions don't match, you will see the following error message:
+
+> Host API version doesn't match
+====

doc/helgobox/modules/ROOT/pages/app/user-interface.adoc

@@ -1,11 +1,8 @@
 = User interface
 
-Each Helgobox instance can display its own xref:app.adoc[] window, embedded into REAPER:
-
-. Open the xref:plug-in.adoc[]
-. Press menu:Menu[Show App]
+Unlike the xref:plug-in.adoc[], the App offers a modern and fancy user interface.
+At the moment, it primarily provides the user interface for xref:playtime::introduction.adoc[Playtime], but it will contain more stuff in the future.
 
 .App window
 image::generated/screenshots/main/home-screen.png[]
 
-At the moment, the app primarily provides the user interface for xref:playtime::introduction.adoc[Playtime], but it will contain more stuff in the future.

doc/helgobox/modules/ROOT/pages/app/user-interface/cli.adoc

@@ -0,0 +1,58 @@
+= Command line interface
+
+When running in xref:app.adoc#app-remote-mode[], the app session can optionally be configured using command line arguments.
+
+== Synopsis
+
+*helgobox* [_OPTIONS_]
+
+== Options
+
+--connection=<URL>::
+URL that decides how the app connects to the xref:plug-in.adoc[].
++
+
+.Connection examples
+[cols="1,2"]
+|===
+|
+`grpc:://localhost:39051` +
+`grpc:://127.0.0.1:39051`
+|
+Connects to the plug-in running on the same machine, assuming a xref:configuration-files.adoc#realearn-ini[standard server configuration] (`server_grpc_port=39051`).
+
+This is the default if the connection option is omitted.
+
+|
+`grpc:://winpc:39051` +
+`grpc:://192.168.1.47:39051`
+|
+Connects to the plug-in running on the machine with the host name `winpc` or the IP address 192.168.1.47.
+|===
+
+--location::
+Path that decides which page is shown initially.
++
+This is not a file system path. It's comparable to the path of a URL that you would see in a web browser's address bar.
++
+
+.Location examples
+[cols="1,2"]
+|===
+|
+`/instance/apc/projection`
+|
+Opens the xref:realearn::user-interface/projection.adoc[projection page] for the xref:key-concepts.adoc#instance[] with xref:key-concepts.adoc#instance-key[] `apc`.
+
+|
+`/instance/3/playtime`
+|
+Opens the xref:playtime::user-interface.adoc[Playtime] page for the xref:key-concepts.adoc#instance[] with xref:key-concepts.adoc#instance-id[] *3*.
+
+Numbers are always interpreted as instance IDs and strings as instance keys. Normally, you want to use an xref:key-concepts.adoc#instance-key[instance key] to refer to the desired instance, because instance IDs are likely to change after restarting REAPER.
+
+
+|===
+
+--help::
+Displays an overview of all supported command line options.

doc/helgobox/modules/ROOT/pages/configuration-files.adoc

@@ -27,7 +27,7 @@ Helgobox itself maintains the following files:
 
 `Helgoboss/Server/certificates`:: Contains a list of certificates and corresponding private keys in order to allow encrypted communication with ReaLearn Companion and App.
 
-`Helgoboss/ReaLearn/realearn.ini`:: Very basic global configuration.
+[[realearn-ini]] `Helgoboss/ReaLearn/realearn.ini`:: Very basic global configuration.
 The reference to ReaLearn is there just for historical reasons.
 Most properties in here affect Helgobox as a whole.
 +

doc/helgobox/modules/ROOT/pages/key-concepts.adoc

@@ -10,5 +10,18 @@ For example, you could place one instance on the monitoring FX chain and two ins
 [[instance-id]]
 == Instance ID
 
-A randomly assigned ID that uniquely identifies a particular <<instance>>.
-Will most likely change after a restart of REAPER!
+A *randomly assigned*, *non-persistent* identifier that identifies a particular <<instance>> and is *guaranteed to be unique* within one REAPER session.
+
+CAUTION: This ID can change after a restart of REAPER! If you are looking for something that doesn't change, use the <<instance-key>>.
+
+[[instance-key]]
+== Instance key
+
+A *user-defined*, *persistent* identifier that identifies a particular <<instance>>.
+The instance key gets relevant if you want to connect to an instance from an xref:app.adoc[] running in xref:app.adoc#app-remote-mode[].
+
+You can change the instance key of an instance by changing the xref:realearn::further-concepts/unit.adoc#unit-key[] of the instance's xref:realearn::key-concepts.adoc#unit[main unit] -- they are the same.
+
+
+.Make your instance keys unique!
+CAUTION: Because the instance key is user-defined, uniqueness can't be guaranteed. For example, if you just copy and paste a Helgobox FX instance, you end up with two instances that have the same key. You should avoid this.

doc/helgobox/modules/ROOT/pages/plug-in/user-interface/menu-bar.adoc

@@ -20,12 +20,16 @@ Shows the xref:helgobox::app.adoc[] associated with this xref:helgobox::key-conc
 Closes the xref:helgobox::app.adoc[] associated with this xref:helgobox::key-concepts.adoc#instance[].
 
 [[server]] Server::
-Helgobox features a built-in server which allows the old ReaLearn Companion App (and in the future also the xref:helgobox::app.adoc[]) to connect to Helgobox.
+Helgobox features a built-in server which allows the xref:app.adoc[] (and the old ReaLearn Companion App) to connect to Helgobox.
 The server runs globally, not per instance!
 
-Enable and start!::: This starts the server and makes sure it will automatically be started next time you use Helgobox.
+[[enable-and-start-server]] Enable and start!::: This starts the server and makes sure it will automatically be started next time you use Helgobox.
+
 Disable and stop!::: This stops the server and makes sure it will not be started next time you use Helgobox.
-Add firewall rule::: Attempts to add a firewall rule for making the server accessible from other devices or displays instructions how to do it.
+
+Add firewall rule::: Attempts to add a firewall rule for making the server accessible from other devices or displays instructions on how to do it.
+
+Open app folder::: Opens the folder which contains the xref:app.adoc[] (in case you want to run it in xref:app.adoc#app-remote-mode[]).
 
 [[export-to-clipboard]]
 == Export to clipboard button

doc/helgobox/modules/ROOT/partials/app-desc.adoc

@@ -1,2 +1,2 @@
 A complement to the xref:plug-in.adoc[] which provides a modern user interface.
-It runs embedded in REAPER and in the future also as a separate mobile app (iOS, Android).
+It runs embedded in REAPER or as a separate program that connects to REAPER. Mobile versions for iOS and Android are planned.

main/src/infrastructure/ui/app/app_instance.rs

@@ -4,13 +4,15 @@ use crate::infrastructure::proto::{
     event_reply, occasional_global_update, reply, EventReply, GetOccasionalGlobalUpdatesReply,
     OccasionalGlobalUpdate, ProtoReceivers, Reply,
 };
+use crate::infrastructure::ui::util::open_in_browser;
 use crate::infrastructure::ui::AppHandle;
 use anyhow::{anyhow, bail, Context, Result};
 use base::hash_util::NonCryptoHashMap;
 use fragile::Fragile;
 use once_cell::sync::Lazy;
 use prost::Message;
-use reaper_medium::Hwnd;
+use reaper_high::Reaper;
+use reaper_medium::{Hwnd, MessageBoxResult, MessageBoxType};
 use std::cell::RefCell;
 use std::fmt::Debug;
 use std::rc::Rc;
@@ -119,7 +121,19 @@ impl AppInstance for DummyAppInstance {
     }
 
     fn start_or_show(&mut self, _owning_window: Window, _page: Option<AppPage>) -> Result<()> {
-        bail!("Linux support for the Helgobox App (including the Playtime user interface) is currently at stage 1! That means the Helgobox App can't yet run embedded within REAPER, but it's possible to use it as a separate program that connects to REAPER (\"remote mode\").\n\nRead the instructions at https://bit.ly/3W51oEe to learn more about this temporary workaround. Subscribe to https://bit.ly/3BQvjcH to follow the development progress of Linux support stage 2.")
+        let msg =
+            "Linux support for the Helgobox App (including the Playtime user interface) is currently at stage 1! That means it can't yet run embedded within REAPER, but it's possible to run it as a separate program that connects to REAPER (\"remote mode\").\n\
+            \n\
+            Do you want to open the instructions?"
+            ;
+        let result =
+            Reaper::get()
+                .medium_reaper()
+                .show_message_box(msg, "Helgobox", MessageBoxType::YesNo);
+        if result == MessageBoxResult::Yes {
+            open_in_browser("https://docs.helgoboss.org/helgobox/goto#app-remote-mode");
+        };
+        Ok(())
     }
 
     fn hide(&mut self) -> Result<()> {

main/src/infrastructure/ui/header_panel.rs

@@ -775,6 +775,7 @@ impl HeaderPanel {
                             MainMenuAction::ToggleServer,
                         ),
                         item("Add firewall rule", MainMenuAction::AddFirewallRule),
+                        item("Open app folder", MainMenuAction::OpenAppFolder),
                     ],
                 ),
                 menu(
@@ -873,6 +874,7 @@ impl HeaderPanel {
                     };
                 }
             }
+            MainMenuAction::OpenAppFolder => self.open_app_folder(),
             MainMenuAction::ToggleUseUnitPresetLinksOnly => {
                 self.toggle_use_unit_preset_links_only()
             }
@@ -2440,6 +2442,12 @@ impl HeaderPanel {
         self.notify_user_on_error(result);
     }
 
+    fn open_app_folder(&self) {
+        let path = BackboneShell::app_binary_base_dir_path();
+        let result = open_in_file_manager(path.as_std_path()).map_err(|e| e.into());
+        self.notify_user_on_error(result);
+    }
+
     fn continue_after_project_independence_check(&self) -> bool {
         let mappings_have_project_references = {
             let compartment = self.active_compartment();
@@ -3186,6 +3194,7 @@ enum MainMenuAction {
     ToggleUpperFloorMembership,
     SetStayActiveWhenProjectInBackground(StayActiveWhenProjectInBackground),
     ToggleServer,
+    OpenAppFolder,
     ToggleBackgroundColors,
     ToggleUseUnitPresetLinksOnly,
     AddFirewallRule,