feat(a11y): set AT-SPI app name + add --page/--zoom/--rail launch flags

- Application.Name = "RailReader2" so the app registers on the a11y bus
  under its real name instead of the generic "Avalonia Application" (frame
  is already named railreader2). Needs a live atspi re-check to confirm.
- Known-state startup flags for agents / scripted launches: --page <n>
  (1-based), --zoom <pct> (e.g. 300), --rail. Parsed in App startup
  (ParseStartupFlags) and applied after the document opens via new
  MainWindowViewModel.ApplyStartupView (GoToPage + SetZoomPercent + an
  analysis-poll that forces rail once the page is analysed).
- Document both in docs/agent-playbook.md.

Build clean (6 projects, 0 warnings).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: sjvrensburg

docs/agent-playbook.md

@@ -46,12 +46,17 @@ gsettings set org.gnome.desktop.interface toolkit-accessibility true
 # Launch on a document (positional arg = PDF path)
 railreader2 /path/to/paper.pdf
 #   or from source:  dotnet run -c Release --project src/RailReader2 -- /path/to/paper.pdf
+
+# Known-state startup flags (any combination; applied once the document opens):
+railreader2 /path/to/paper.pdf --page 7 --zoom 300 --rail
+#   --page <n>      1-based page to open on
+#   --zoom <pct>    zoom percentage (e.g. 300 = 300%); clamped to 50–2000
+#   --rail          engage rail mode (forces it at the viewport centre once the page is
+#                   analysed; a --zoom above the rail threshold engages it on its own)
 ```
 
-**App identity on the a11y bus:** the application registers as **`Avalonia Application`**
-(Avalonia doesn't derive it from the assembly); the top-level **frame is named
-`railreader2`**. Match on the frame, or on the Avalonia app name. There are no
-`--page/--zoom/--rail` startup flags yet — reach the desired state with the actions below.
+**App identity on the a11y bus:** the application registers as **`RailReader2`** (set via
+`Application.Name`), with the top-level **frame named `railreader2`**. Match on either.
 
 ---
 
@@ -168,7 +173,6 @@ continue when parked) · `J` jump mode · `H` line highlight · `F` line focus d
 ## 8. Known gaps / caveats (as of 2026-06-27)
 
 - **Menus aren't AT-SPI-actionable** — use buttons + accelerators (§1).
-- App name on the bus is the generic `Avalonia Application` (frame is `railreader2`).
 - **Input/screencast transport:** AT-SPI (the tree above) is display-server-agnostic, but an
   agent's *input injection and screen capture* on Wayland go through the portals
   (RemoteDesktop/ScreenCast); on X11 they're direct. This playbook covers the a11y tree, not

src/RailReader2/App.axaml.cs

@@ -30,6 +30,10 @@ private static bool IsFirstRun()
 
     public override void Initialize()
     {
+        // The accessibility/automation backends surface this as the application's name on the bus
+        // (AT-SPI on Linux); without it the app registers as the generic "Avalonia Application", which an
+        // agent/screen reader can't identify. The window frame is named separately (via the window title).
+        Name = "RailReader2";
         AvaloniaXamlLoader.Load(this);
     }
 
@@ -76,12 +80,49 @@ public override void OnFrameworkInitializationCompleted()
                 // First non-flag argument that names an existing file is the PDF to open.
                 var docPath = args?.FirstOrDefault(a => !a.StartsWith("--") && File.Exists(a));
                 if (docPath is not null)
-                    window.Opened += (_, _) => vm.FireAndForget(vm.OpenDocument(docPath), nameof(vm.OpenDocument));
+                {
+                    // Optional known-state startup flags (for agents / scripted launches):
+                    //   --page <n> (1-based)   --zoom <percent, e.g. 300>   --rail
+                    var (startPage, startZoom, startRail) = ParseStartupFlags(args!);
+                    window.Opened += (_, _) => vm.FireAndForget(OpenStartupDocument(), nameof(vm.OpenDocument));
+
+                    async System.Threading.Tasks.Task OpenStartupDocument()
+                    {
+                        await vm.OpenDocument(docPath);
+                        if (startPage is not null || startZoom is not null || startRail)
+                            vm.ApplyStartupView(startPage, startZoom, startRail);
+                    }
+                }
 
                 window.Show();
             }, DispatcherPriority.Background);
         }
 
         base.OnFrameworkInitializationCompleted();
     }
+
+    /// <summary>Parse the optional known-state startup flags: <c>--page &lt;n&gt;</c> (1-based),
+    /// <c>--zoom &lt;percent&gt;</c> (e.g. 300 for 300%), and <c>--rail</c>. Unknown/malformed values are
+    /// ignored; the PDF path is a separate positional argument.</summary>
+    private static (int? Page, double? Zoom, bool Rail) ParseStartupFlags(string[] args)
+    {
+        int? page = null;
+        double? zoom = null;
+        bool rail = false;
+        for (int i = 0; i < args.Length; i++)
+        {
+            switch (args[i])
+            {
+                case "--page" when i + 1 < args.Length && int.TryParse(args[i + 1], out var p):
+                    page = p; i++; break;
+                case "--zoom" when i + 1 < args.Length && double.TryParse(
+                        args[i + 1], System.Globalization.NumberStyles.Float,
+                        System.Globalization.CultureInfo.InvariantCulture, out var z):
+                    zoom = z; i++; break;
+                case "--rail":
+                    rail = true; break;
+            }
+        }
+        return (page, zoom, rail);
+    }
 }

src/RailReader2/ViewModels/MainWindowViewModel.Navigation.cs

@@ -1,3 +1,4 @@
+using Avalonia.Threading;
 using CommunityToolkit.Mvvm.Input;
 using RailReader.Core;
 using RailReader.Core.Models;
@@ -191,6 +192,36 @@ public void StartRailHere()
         ActivateRailAtClick(ww / 2.0, wh / 2.0);
     }
 
+    /// <summary>Apply a requested initial view from launch flags (<c>--page</c>/<c>--zoom</c>/<c>--rail</c>),
+    /// after the startup document has opened. Page is 1-based; zoom is a percentage (e.g. 300 = 300%).
+    /// Rail engages once the page is analysed: a high enough zoom seats it via the tick, otherwise this
+    /// forces it at the viewport centre (a short poll waits for analysis, then gives up — no model = no
+    /// rail).</summary>
+    public void ApplyStartupView(int? page1Based, double? zoomPercent, bool rail)
+    {
+        if (ActiveTab is not { } tab) return;
+        if (page1Based is { } p)
+            GoToPage(Math.Clamp(p - 1, 0, Math.Max(0, tab.PageCount - 1)));
+        if (zoomPercent is { } z)
+            SetZoomPercent(z);
+        if (!rail) return;
+
+        StartBackgroundAnalysis();
+        // Rail needs the current page analysed; poll briefly, then force rail if the tick hasn't already
+        // engaged it (a >threshold zoom would have). Capped so a missing ONNX model can't poll forever.
+        int attempts = 0;
+        var timer = new DispatcherTimer { Interval = TimeSpan.FromMilliseconds(150) };
+        timer.Tick += (_, _) =>
+        {
+            attempts++;
+            if (ActiveTab is not { } t || attempts > 80) { timer.Stop(); return; }
+            if (!t.AnalysisCache.ContainsKey(t.State.CurrentPage)) return;
+            timer.Stop();
+            if (!t.Rail.Active && !ForcedRailActive) StartRailHere();
+        };
+        timer.Start();
+    }
+
     /// <summary>True while rail is held active below the zoom threshold by a forced "start rail here"
     /// activation. Used to drive an Escape that releases it.</summary>
     public bool ForcedRailActive => _controller.ForcedRailActive;