From 21d5090db2d3ea08eaddd840e775a6cbb56b8011 Mon Sep 17 00:00:00 2001
From: bflatastic <bombayapirat@gmail.com>
Date: Tue, 20 Oct 2026 00:13:47 +0700
Subject: [PATCH] #874: --control starts in a new file whatever the preference
 (control callers expect a document), with a test

---
 apps/figcraft/src/main.rs | 25 ++++++++++++++++++++++---
 docs/mcp.md               |  3 ++-
 2 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/apps/figcraft/src/main.rs b/apps/figcraft/src/main.rs
index e98f9373..00856c5d 100644
--- a/apps/figcraft/src/main.rs
+++ b/apps/figcraft/src/main.rs
@@ -193,10 +193,8 @@ fn main() -> eframe::Result {
     // default, never a build from source unless asked).
     session.live.links = figcraft_collab_net::links::system();
     session.invite_links_startup();
-    // A first run (no settings kept yet, nothing to open) starts on the home screen, with its
-    // tips and templates; later runs start in a new file unless the preference says Home.
     let first_run = svc.prefs.is_none() && args.join.is_none();
-    if session.docs.is_empty() && !first_run && !session.prefs.start_on_home {
+    if session.docs.is_empty() && opens_new_file(first_run, session.prefs.start_on_home, port.is_some()) {
         let _ = session.execute("file.new", &json!({}));
     }
     // The interface language from the first frame on, and for the message when the window can't
@@ -268,6 +266,14 @@ fn main() -> eframe::Result {
     result
 }
 
+/// With nothing to open, whether the window starts in a new file rather than on the home screen.
+/// A first run (no settings kept yet) shows the home screen's tips and templates, and later runs
+/// start in a new file unless the preference asks for Home, which `--control` overrides: its
+/// callers expect a document to act on.
+fn opens_new_file(first_run: bool, start_on_home: bool, control: bool) -> bool {
+    !first_run && (!start_on_home || control)
+}
+
 fn desktop_title_bar() -> figcraft_ui_egui::TitleBar {
     use figcraft_ui_egui::TitleBar;
     if cfg!(target_os = "macos") { TitleBar::Inset } else { TitleBar::Custom }
@@ -292,3 +298,16 @@ mod linux_window_tests {
         assert_eq!(viewport.decorations, Some(false));
     }
 }
+
+#[cfg(test)]
+mod start_tests {
+    use super::opens_new_file;
+
+    #[test]
+    fn the_home_preference_starts_on_home_except_for_control_callers() {
+        assert!(opens_new_file(false, false, false), "a new file by default");
+        assert!(!opens_new_file(false, true, false), "Home when the preference asks");
+        assert!(opens_new_file(false, true, true), "--control still starts with a document");
+        assert!(!opens_new_file(true, false, false), "a first run shows the home screen");
+    }
+}
diff --git a/docs/mcp.md b/docs/mcp.md
index 90cc75f5..fb94dabf 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -420,7 +420,8 @@ on; `key` resolves keys the way the canvas does. Commands behind keys:
 - `pref.autoSave {on?}`: files that have a path save themselves a few seconds after they change
   (off by default; the desktop app's timer does it, so scripts still call `file.save`).
 - `pref.startOnHome {on?}`: the desktop app starts on the Home screen instead of in a new file
-  (off by default; files named on the command line still open).
+  (off by default; files named on the command line still open, and `--control` starts in a new
+  file anyway, so control callers have a document).
 - `pref.language {language: system|en|cs|ru|es|es-419|fr|de|pt-BR|ja|ko|zh-Hans|…}`: the app's interface language, applied live ("system":
 - `pref.language {language: system|en|es|es-419|fr|de|pt-BR|ja|ko|sv|zh-Hans|…}`: the app's interface language, applied live ("system":
   the OS or browser language; a language without a catalog shows English). Command ids, labels and