From 49606073550a67b295dcab9f6d94518a8ac5ff79 Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Sun, 28 Jun 2026 12:36:58 +0200
Subject: [PATCH 01/18] feat(runner): configurable global APP_ID passed to
 maestro as -e

Add an App ID setting that maestro-deck forwards to every run as
`-e APP_ID=<value>`, so flow files referencing ${APP_ID} (the CI
placeholder) run locally without per-file edits. Empty value passes
nothing, preserving prior behavior. Threaded through all four runners
(Android, Web, iOS sim, iOS physical).
---
 src-tauri/src/ipc/commands.rs               | 12 +++--
 src-tauri/src/runner/mod.rs                 | 58 ++++++++++++++++++++-
 src/components/MainView.tsx                 |  6 +--
 src/components/settings/GeneralSettings.tsx | 20 +++++++
 src/lib/ipc.ts                              |  3 +-
 src/stores/settingsStore.test.ts            |  9 ++++
 src/stores/settingsStore.ts                 | 11 ++++
 7 files changed, 110 insertions(+), 9 deletions(-)

diff --git a/src-tauri/src/ipc/commands.rs b/src-tauri/src/ipc/commands.rs
index 881a2d9..435b54f 100644
--- a/src-tauri/src/ipc/commands.rs
+++ b/src-tauri/src/ipc/commands.rs
@@ -953,6 +953,7 @@ pub async fn install_ios_device_bridge() -> AppResult<String> {
 #[tauri::command]
 pub async fn run_flow(
     file_path: String,
+    app_id: Option<String>,
     app: AppHandle,
     state: State<'_, AppState>,
 ) -> AppResult<u32> {
@@ -962,12 +963,16 @@ pub async fn run_flow(
         .clone()
         .ok_or(AppError::NoDevice)?;
 
+    // Configured global APP_ID, forwarded to maestro as `-e APP_ID=…` so flows
+    // referencing `${APP_ID}` (the CI placeholder) run locally unchanged.
+    let app_id = app_id.as_deref();
+
     if device.platform == crate::device::Platform::Web {
         // Web flows run with no `--udid`; maestro targets the browser via the
         // flow's `url:` header. Pause the studio keeper so its browser doesn't
         // contend with the one `maestro test` launches.
         teardown_web(state.inner()).await;
-        return runner::spawn_web_runner(app, &file_path).await;
+        return runner::spawn_web_runner(app, &file_path, app_id).await;
     }
 
     if device.platform == crate::device::Platform::Ios {
@@ -981,6 +986,7 @@ pub async fn run_flow(
                 &device.serial,
                 &file_path,
                 crate::ios_session::PHYSICAL_BRIDGE_PORT,
+                app_id,
             )
             .await;
         }
@@ -1000,7 +1006,7 @@ pub async fn run_flow(
         state
             .ios_sim_run_active
             .store(true, std::sync::atomic::Ordering::SeqCst);
-        let spawned = runner::spawn_ios_runner(app, &device.serial, &file_path).await;
+        let spawned = runner::spawn_ios_runner(app, &device.serial, &file_path, app_id).await;
         if spawned.is_err() {
             state
                 .ios_sim_run_active
@@ -1027,7 +1033,7 @@ pub async fn run_flow(
     // With maestro 2.5.x, `maestro test` uses an adb-socket
     // (AdbSocketFactory) instead of a host TCP forward, so it cohabits
     // peacefully with our running studio. No cleanup needed.
-    runner::spawn_runner(app, &serial, &file_path, None).await
+    runner::spawn_runner(app, &serial, &file_path, app_id, None).await
 }
 
 #[tauri::command]
diff --git a/src-tauri/src/runner/mod.rs b/src-tauri/src/runner/mod.rs
index a1dcefc..f8c30c2 100644
--- a/src-tauri/src/runner/mod.rs
+++ b/src-tauri/src/runner/mod.rs
@@ -51,6 +51,18 @@ fn maestro_bin() -> String {
     crate::tool_paths::maestro_bin()
 }
 
+/// Build the `-e APP_ID=<value>` args for a maestro `test` invocation, or an
+/// empty vec when no app id is configured. This lets a single global APP_ID
+/// (set in Settings) feed the `${APP_ID}` placeholder users keep in their CI
+/// flow files, so those flows run locally without per-file edits. `-e` is a
+/// `test`-subcommand option, so callers must insert these args *after* `test`.
+fn app_id_env_args(app_id: Option<&str>) -> Vec<String> {
+    match app_id.map(str::trim).filter(|s| !s.is_empty()) {
+        Some(value) => vec!["-e".to_string(), format!("APP_ID={value}")],
+        None => Vec::new(),
+    }
+}
+
 /// Spawn `maestro --udid <serial> test <flow>` and stream stdout/stderr to
 /// the frontend via Tauri events. The PID is returned so the frontend can
 /// request a stop.
@@ -63,10 +75,12 @@ pub async fn spawn_runner(
     app: AppHandle,
     serial: &str,
     flow_path: &str,
+    app_id: Option<&str>,
     on_exit: Option<Box<dyn FnOnce(AppHandle) + Send + 'static>>,
 ) -> AppResult<u32> {
     let bin = maestro_bin();
     info!(bin = %bin, serial, flow = %flow_path, "spawning maestro");
+    let env_args = app_id_env_args(app_id);
 
     // Maestro 2.5.x's session manager calls `dadb.Dadb.list()` which
     // walks every adb-server transport before honoring `--udid` — any
@@ -112,6 +126,7 @@ pub async fn spawn_runner(
     let mut child = Command::new(&bin)
         .no_window()
         .args(["--udid", serial, "test"])
+        .args(&env_args)
         .arg(flow_path)
         .stdout(Stdio::piped())
         .stderr(Stdio::piped())
@@ -185,14 +200,20 @@ pub async fn spawn_runner(
 /// Maestro targets the browser via the flow's `url:` header, and no adb
 /// emulator-ghost preamble (irrelevant to web). Streams stdout/stderr and
 /// emits `runner:exit` exactly like [`spawn_runner`].
-pub async fn spawn_web_runner(app: AppHandle, flow_path: &str) -> AppResult<u32> {
+pub async fn spawn_web_runner(
+    app: AppHandle,
+    flow_path: &str,
+    app_id: Option<&str>,
+) -> AppResult<u32> {
     let bin = maestro_bin();
     info!(bin = %bin, flow = %flow_path, "spawning maestro (web)");
+    let env_args = app_id_env_args(app_id);
 
     let mut child = Command::new(&bin)
         .no_window()
         // `-p web` is a global flag and must precede the `test` subcommand.
         .args(["-p", "web", "test"])
+        .args(&env_args)
         .arg(flow_path)
         .stdout(Stdio::piped())
         .stderr(Stdio::piped())
@@ -257,13 +278,20 @@ pub async fn spawn_web_runner(app: AppHandle, flow_path: &str) -> AppResult<u32>
 /// iOS). The caller stops the studio keeper first so `maestro test` can bring up
 /// its own XCTest driver on :22087 without contention. Streams stdout/stderr and
 /// emits `runner:exit` exactly like the other runners.
-pub async fn spawn_ios_runner(app: AppHandle, udid: &str, flow_path: &str) -> AppResult<u32> {
+pub async fn spawn_ios_runner(
+    app: AppHandle,
+    udid: &str,
+    flow_path: &str,
+    app_id: Option<&str>,
+) -> AppResult<u32> {
     let bin = maestro_bin();
     info!(bin = %bin, udid, flow = %flow_path, "spawning maestro (ios)");
+    let env_args = app_id_env_args(app_id);
 
     let mut child = Command::new(&bin)
         .no_window()
         .args(["--udid", udid, "test"])
+        .args(&env_args)
         .arg(flow_path)
         .stdout(Stdio::piped())
         .stderr(Stdio::piped())
@@ -381,6 +409,7 @@ pub async fn spawn_ios_device_runner(
     udid: &str,
     flow_path: &str,
     port: u16,
+    app_id: Option<&str>,
 ) -> AppResult<u32> {
     let bin = maestro_bin();
     if !maestro_supports_driver_host_port(&bin).await {
@@ -392,10 +421,12 @@ pub async fn spawn_ios_device_runner(
     }
     let port_str = port.to_string();
     info!(bin = %bin, udid, port, flow = %flow_path, "spawning maestro (ios physical)");
+    let env_args = app_id_env_args(app_id);
 
     let mut child = Command::new(&bin)
         .no_window()
         .args(["--driver-host-port", &port_str, "--device", udid, "test"])
+        .args(&env_args)
         .arg(flow_path)
         .stdout(Stdio::piped())
         .stderr(Stdio::piped())
@@ -478,4 +509,27 @@ mod tests {
         let res = kill_runner(987_654_321).await;
         assert!(matches!(res, Err(AppError::RunnerFailed(_))));
     }
+
+    #[test]
+    fn app_id_env_args_emits_e_flag_when_set() {
+        assert_eq!(
+            app_id_env_args(Some("com.example.app")),
+            vec!["-e".to_string(), "APP_ID=com.example.app".to_string()]
+        );
+    }
+
+    #[test]
+    fn app_id_env_args_trims_whitespace() {
+        assert_eq!(
+            app_id_env_args(Some("  com.example.app  ")),
+            vec!["-e".to_string(), "APP_ID=com.example.app".to_string()]
+        );
+    }
+
+    #[test]
+    fn app_id_env_args_empty_when_none_or_blank() {
+        assert!(app_id_env_args(None).is_empty());
+        assert!(app_id_env_args(Some("")).is_empty());
+        assert!(app_id_env_args(Some("   ")).is_empty());
+    }
 }
diff --git a/src/components/MainView.tsx b/src/components/MainView.tsx
index a8e5f67..8b8cf6d 100644
--- a/src/components/MainView.tsx
+++ b/src/components/MainView.tsx
@@ -94,7 +94,7 @@ export function MainView() {
       }
       resetSteps();
       initSteps(parseFlow(content).steps);
-      const pid = await ipc.runFlow(path);
+      const pid = await ipc.runFlow(path, useSettingsStore.getState().appId);
       setRunning(pid);
       appendLog("system", `[runner started pid ${pid} · ${path}]`);
     } catch (err) {
@@ -119,7 +119,7 @@ export function MainView() {
       const { content: c2 } = useFlowStore.getState();
       resetSteps();
       initSteps(parseFlow(c2).steps);
-      const pid = await ipc.runFlow(folder);
+      const pid = await ipc.runFlow(folder, useSettingsStore.getState().appId);
       setRunning(pid);
       appendLog("system", `[runner started pid ${pid} · all flows in ${folder}]`);
     } catch (err) {
@@ -147,7 +147,7 @@ export function MainView() {
         }));
         resetSteps();
         initSteps(remappedSteps);
-        const pid = await ipc.runFlow(tempPath);
+        const pid = await ipc.runFlow(tempPath, useSettingsStore.getState().appId);
         setRunning(pid);
         appendLog(
           "system",
diff --git a/src/components/settings/GeneralSettings.tsx b/src/components/settings/GeneralSettings.tsx
index c315dc9..82c2f2d 100644
--- a/src/components/settings/GeneralSettings.tsx
+++ b/src/components/settings/GeneralSettings.tsx
@@ -28,6 +28,8 @@ export function GeneralSettings() {
   const setAutoCheckUpdatesEnabled = useSettingsStore((s) => s.setAutoCheckUpdatesEnabled);
   const confirmBeforeQuit = useSettingsStore((s) => s.confirmBeforeQuit);
   const setConfirmBeforeQuit = useSettingsStore((s) => s.setConfirmBeforeQuit);
+  const appId = useSettingsStore((s) => s.appId);
+  const setAppId = useSettingsStore((s) => s.setAppId);
 
   return (
     <SettingsSection
@@ -82,6 +84,24 @@ export function GeneralSettings() {
         </label>
       </SettingsSubgroup>
 
+      <SettingsSubgroup title="Flows">
+        <label className="flex flex-col gap-1.5">
+          <span>App ID</span>
+          <input
+            type="text"
+            value={appId}
+            placeholder="com.example.app"
+            onChange={(e) => setAppId(e.currentTarget.value)}
+            className="w-full rounded border border-border bg-background px-2 py-1 font-mono text-xs"
+          />
+          <span className="text-xs text-muted-foreground">
+            Passed to maestro as <code>-e APP_ID=…</code> on every run, so flows that reference{" "}
+            <code>{"${APP_ID}"}</code> (e.g. your CI flows) run locally without editing each file.
+            Leave empty to pass nothing.
+          </span>
+        </label>
+      </SettingsSubgroup>
+
       <SettingsSubgroup title="Application">
         <ToggleRow
           label="Check for updates on startup"
diff --git a/src/lib/ipc.ts b/src/lib/ipc.ts
index 07ad730..d9a0306 100644
--- a/src/lib/ipc.ts
+++ b/src/lib/ipc.ts
@@ -78,7 +78,8 @@ export const ipc = {
   getDarkMode: () => call<boolean>("get_dark_mode"),
   // iOS-only: press the Home button to return to the home screen.
   iosPressHome: () => call<void>("ios_press_home"),
-  runFlow: (filePath: string) => call<number>("run_flow", { filePath }),
+  runFlow: (filePath: string, appId?: string) =>
+    call<number>("run_flow", { filePath, appId: appId?.trim() || null }),
   stopFlow: (pid: number) => call<void>("stop_flow", { pid }),
   listWorkspace: (path: string) => call<WorkspaceNode>("list_workspace", { path }),
   startStream: () => call<void>("start_stream"),
diff --git a/src/stores/settingsStore.test.ts b/src/stores/settingsStore.test.ts
index 804a90b..afa3b74 100644
--- a/src/stores/settingsStore.test.ts
+++ b/src/stores/settingsStore.test.ts
@@ -33,6 +33,7 @@ beforeEach(() => {
     fastHierarchyEnabled: false,
     autoSaveEnabled: true,
     consoleMode: "simple",
+    appId: "",
   });
 });
 
@@ -48,6 +49,7 @@ describe("settingsStore defaults", () => {
     expect(s.consoleMode).toBe("simple");
     // Web support is beta — the target stays hidden until opted in.
     expect(s.webBrowserEnabled).toBe(false);
+    expect(s.appId).toBe("");
   });
 });
 
@@ -98,4 +100,11 @@ describe("settingsStore setters", () => {
     useSettingsStore.getState().setConsoleMode("simple");
     expect(useSettingsStore.getState().consoleMode).toBe("simple");
   });
+
+  it("setAppId stores a trimmed value", () => {
+    useSettingsStore.getState().setAppId("  com.example.app  ");
+    expect(useSettingsStore.getState().appId).toBe("com.example.app");
+    useSettingsStore.getState().setAppId("");
+    expect(useSettingsStore.getState().appId).toBe("");
+  });
 });
diff --git a/src/stores/settingsStore.ts b/src/stores/settingsStore.ts
index 039c7c0..af76490 100644
--- a/src/stores/settingsStore.ts
+++ b/src/stores/settingsStore.ts
@@ -36,6 +36,13 @@ interface SettingsState {
    * from the dialog itself ("don't ask again") or re-enable it in Settings. */
   confirmBeforeQuit: boolean;
   consoleMode: ConsoleMode;
+  /**
+   * Value fed to maestro as `-e APP_ID=<appId>` on every run, so flow files
+   * can reference `${APP_ID}` (the same placeholder used in CI) and still run
+   * locally without editing each file. Empty string = pass nothing, behaving
+   * exactly as before.
+   */
+  appId: string;
   setInspectKey: (k: string) => void;
   setShowFps: (v: boolean) => void;
   setTheme: (t: ThemeMode) => void;
@@ -47,6 +54,7 @@ interface SettingsState {
   setWebBrowserEnabled: (v: boolean) => void;
   setConfirmBeforeQuit: (v: boolean) => void;
   setConsoleMode: (m: ConsoleMode) => void;
+  setAppId: (id: string) => void;
 }
 
 export const useSettingsStore = create<SettingsState>()(
@@ -63,6 +71,7 @@ export const useSettingsStore = create<SettingsState>()(
       webBrowserEnabled: false,
       confirmBeforeQuit: true,
       consoleMode: "simple",
+      appId: "",
       setInspectKey: (inspectKey) => set({ inspectKey }),
       setShowFps: (showFps) => set({ showFps }),
       setTheme: (theme) => set({ theme }),
@@ -74,6 +83,7 @@ export const useSettingsStore = create<SettingsState>()(
       setWebBrowserEnabled: (webBrowserEnabled) => set({ webBrowserEnabled }),
       setConfirmBeforeQuit: (confirmBeforeQuit) => set({ confirmBeforeQuit }),
       setConsoleMode: (consoleMode) => set({ consoleMode }),
+      setAppId: (appId) => set({ appId: appId.trim() }),
     }),
     {
       name: "maestro-deck.settings",
@@ -89,6 +99,7 @@ export const useSettingsStore = create<SettingsState>()(
         webBrowserEnabled: s.webBrowserEnabled,
         confirmBeforeQuit: s.confirmBeforeQuit,
         consoleMode: s.consoleMode,
+        appId: s.appId,
       }),
     },
   ),

From dce3d5eed384c114f0470e50c963d4ed0b4febde Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Sun, 28 Jun 2026 13:12:07 +0200
Subject: [PATCH 02/18] feat(settings): editable Billy AI system prompt with
 reset to default

Add a 'Billy AI' settings section that lets users override Billy's
system prompt and reset back to the version shipped with the app. The
override is stored as customPrompt|null in a persisted store, so users
who never customize keep receiving the latest embedded prompt across
updates; getEffectiveBillyPrompt() resolves override ?? embedded and is
read fresh on each message.
---
 src/components/settings/BillySettings.tsx    | 72 ++++++++++++++++++++
 src/components/settings/SettingsPage.test.ts |  1 +
 src/components/settings/sections.tsx         |  2 +
 src/lib/chat/systemPrompt.ts                 | 11 +++
 src/stores/billyPromptStore.test.ts          | 49 +++++++++++++
 src/stores/billyPromptStore.ts               | 35 ++++++++++
 src/stores/chatStore.ts                      |  4 +-
 7 files changed, 172 insertions(+), 2 deletions(-)
 create mode 100644 src/components/settings/BillySettings.tsx
 create mode 100644 src/stores/billyPromptStore.test.ts
 create mode 100644 src/stores/billyPromptStore.ts

diff --git a/src/components/settings/BillySettings.tsx b/src/components/settings/BillySettings.tsx
new file mode 100644
index 0000000..d59ccd5
--- /dev/null
+++ b/src/components/settings/BillySettings.tsx
@@ -0,0 +1,72 @@
+// Copyright (c) 2026 Ethan Morisset
+// SPDX-License-Identifier: BUSL-1.1
+
+import { useState } from "react";
+
+import { Button } from "@/components/ui/Button";
+import { SettingsSection } from "@/components/settings/SettingsPrimitives";
+import { BILLY_SYSTEM_PROMPT } from "@/lib/chat/systemPrompt";
+import { useBillyPromptStore } from "@/stores/billyPromptStore";
+
+export function BillySettings() {
+  const customPrompt = useBillyPromptStore((s) => s.customPrompt);
+  const setCustomPrompt = useBillyPromptStore((s) => s.setCustomPrompt);
+  const reset = useBillyPromptStore((s) => s.reset);
+
+  // Draft starts from the effective prompt: the override if one exists, else
+  // the embedded default. Editing only persists on Save.
+  const [draft, setDraft] = useState(customPrompt ?? BILLY_SYSTEM_PROMPT);
+
+  const isCustomized = customPrompt !== null;
+  const effective = customPrompt ?? BILLY_SYSTEM_PROMPT;
+  const dirty = draft !== effective;
+
+  const onSave = () => setCustomPrompt(draft);
+  const onReset = () => {
+    reset();
+    setDraft(BILLY_SYSTEM_PROMPT);
+  };
+
+  return (
+    <SettingsSection
+      title="Billy AI"
+      description="Billy is the in-app AI assistant. This is its system prompt — the role and Maestro knowledge it works from. Edit it to tailor Billy to your project; reset to restore the version shipped with the app."
+    >
+      <div className="flex flex-col gap-2">
+        <div className="flex items-center justify-between">
+          <span className="text-[11px] font-semibold uppercase tracking-wide text-muted-foreground">
+            System prompt
+          </span>
+          {isCustomized ? (
+            <span className="rounded-full bg-primary/10 px-2 py-0.5 text-[10px] font-medium text-primary">
+              Customized
+            </span>
+          ) : (
+            <span className="text-[10px] text-muted-foreground">Default</span>
+          )}
+        </div>
+
+        <textarea
+          value={draft}
+          onChange={(e) => setDraft(e.currentTarget.value)}
+          spellCheck={false}
+          className="h-80 w-full resize-y rounded border border-border bg-background px-3 py-2 font-mono text-xs leading-relaxed"
+        />
+
+        <p className="text-[11px] text-muted-foreground">
+          Changes take effect on Billy&apos;s next message. Clearing the editor and saving is
+          treated as a reset to the default.
+        </p>
+
+        <div className="flex gap-2">
+          <Button size="sm" onClick={onSave} disabled={!dirty}>
+            Save
+          </Button>
+          <Button size="sm" variant="outline" onClick={onReset} disabled={!isCustomized}>
+            Reset to default
+          </Button>
+        </div>
+      </div>
+    </SettingsSection>
+  );
+}
diff --git a/src/components/settings/SettingsPage.test.ts b/src/components/settings/SettingsPage.test.ts
index 4b915b4..5417448 100644
--- a/src/components/settings/SettingsPage.test.ts
+++ b/src/components/settings/SettingsPage.test.ts
@@ -26,6 +26,7 @@ describe("resolveSection", () => {
       "device",
       "tools",
       "ai",
+      "billy",
       "about",
     ]);
   });
diff --git a/src/components/settings/sections.tsx b/src/components/settings/sections.tsx
index 479d1f3..00206ae 100644
--- a/src/components/settings/sections.tsx
+++ b/src/components/settings/sections.tsx
@@ -6,6 +6,7 @@ import type { ReactNode } from "react";
 import { AiSettings } from "@/components/AiSettings";
 import { ToolPathsSettings } from "@/components/ToolPathsSettings";
 import { AboutSettings } from "@/components/settings/AboutSettings";
+import { BillySettings } from "@/components/settings/BillySettings";
 import { DevicePerformanceSettings } from "@/components/settings/DevicePerformanceSettings";
 import { GeneralSettings } from "@/components/settings/GeneralSettings";
 
@@ -21,6 +22,7 @@ export const SETTINGS_SECTIONS: SettingsSectionDef[] = [
   { id: "device", label: "Device & Performance", render: () => <DevicePerformanceSettings /> },
   { id: "tools", label: "Tools", render: () => <ToolPathsSettings /> },
   { id: "ai", label: "AI", render: () => <AiSettings /> },
+  { id: "billy", label: "Billy AI", render: () => <BillySettings /> },
   { id: "about", label: "About", render: () => <AboutSettings /> },
 ];
 
diff --git a/src/lib/chat/systemPrompt.ts b/src/lib/chat/systemPrompt.ts
index ea3367d..a53df1e 100644
--- a/src/lib/chat/systemPrompt.ts
+++ b/src/lib/chat/systemPrompt.ts
@@ -6,4 +6,15 @@
 // no code changes needed, just bump the .md and rebuild.
 import prompt from "./billy-prompt.md?raw";
 
+import { useBillyPromptStore } from "@/stores/billyPromptStore";
+
 export const BILLY_SYSTEM_PROMPT: string = prompt;
+
+/**
+ * The system prompt Billy should actually use: the user's override when set,
+ * otherwise the embedded default. Read fresh on each call (don't cache) so an
+ * edit in Settings takes effect on the next message without a reload.
+ */
+export function getEffectiveBillyPrompt(): string {
+  return useBillyPromptStore.getState().customPrompt ?? BILLY_SYSTEM_PROMPT;
+}
diff --git a/src/stores/billyPromptStore.test.ts b/src/stores/billyPromptStore.test.ts
new file mode 100644
index 0000000..77b37c4
--- /dev/null
+++ b/src/stores/billyPromptStore.test.ts
@@ -0,0 +1,49 @@
+// Copyright (c) 2026 Ethan Morisset
+// SPDX-License-Identifier: BUSL-1.1
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.hoisted(() => {
+  const storage = new Map<string, string>();
+  (globalThis as unknown as { localStorage: Storage }).localStorage = {
+    getItem: (k: string) => storage.get(k) ?? null,
+    setItem: (k: string, v: string) => {
+      storage.set(k, v);
+    },
+    removeItem: (k: string) => {
+      storage.delete(k);
+    },
+    clear: () => storage.clear(),
+    key: () => null,
+    length: 0,
+  } as Storage;
+});
+
+import { useBillyPromptStore } from "./billyPromptStore";
+
+beforeEach(() => {
+  useBillyPromptStore.setState({ customPrompt: null });
+});
+
+describe("billyPromptStore", () => {
+  it("defaults to no override", () => {
+    expect(useBillyPromptStore.getState().customPrompt).toBeNull();
+  });
+
+  it("setCustomPrompt stores the override", () => {
+    useBillyPromptStore.getState().setCustomPrompt("You are a pirate.");
+    expect(useBillyPromptStore.getState().customPrompt).toBe("You are a pirate.");
+  });
+
+  it("setCustomPrompt with blank/whitespace input clears the override", () => {
+    useBillyPromptStore.getState().setCustomPrompt("something");
+    useBillyPromptStore.getState().setCustomPrompt("   \n  ");
+    expect(useBillyPromptStore.getState().customPrompt).toBeNull();
+  });
+
+  it("reset drops the override", () => {
+    useBillyPromptStore.getState().setCustomPrompt("custom");
+    useBillyPromptStore.getState().reset();
+    expect(useBillyPromptStore.getState().customPrompt).toBeNull();
+  });
+});
diff --git a/src/stores/billyPromptStore.ts b/src/stores/billyPromptStore.ts
new file mode 100644
index 0000000..3019c64
--- /dev/null
+++ b/src/stores/billyPromptStore.ts
@@ -0,0 +1,35 @@
+// Copyright (c) 2026 Ethan Morisset
+// SPDX-License-Identifier: BUSL-1.1
+
+import { create } from "zustand";
+import { persist, createJSONStorage } from "zustand/middleware";
+
+interface BillyPromptState {
+  /**
+   * User override for Billy's system prompt. `null` means "no override" — the
+   * app falls back to the embedded `BILLY_SYSTEM_PROMPT`. Storing null (rather
+   * than a copy of the default) means users who never customized keep receiving
+   * the latest embedded prompt as the app updates; only those who overrode keep
+   * their own version.
+   */
+  customPrompt: string | null;
+  /** Persist an override. Blank/whitespace-only input is treated as a reset so
+   *  Billy never ends up with an empty system prompt. */
+  setCustomPrompt: (prompt: string) => void;
+  /** Drop the override and fall back to the embedded default. */
+  reset: () => void;
+}
+
+export const useBillyPromptStore = create<BillyPromptState>()(
+  persist(
+    (set) => ({
+      customPrompt: null,
+      setCustomPrompt: (prompt) => set({ customPrompt: prompt.trim() === "" ? null : prompt }),
+      reset: () => set({ customPrompt: null }),
+    }),
+    {
+      name: "maestro-deck.billy-prompt",
+      storage: createJSONStorage(() => localStorage),
+    },
+  ),
+);
diff --git a/src/stores/chatStore.ts b/src/stores/chatStore.ts
index 546eb45..6d0696b 100644
--- a/src/stores/chatStore.ts
+++ b/src/stores/chatStore.ts
@@ -5,7 +5,7 @@ import { create } from "zustand";
 import { persist, createJSONStorage } from "zustand/middleware";
 
 import { getProvider } from "@/lib/chat/registry";
-import { BILLY_SYSTEM_PROMPT } from "@/lib/chat/systemPrompt";
+import { getEffectiveBillyPrompt } from "@/lib/chat/systemPrompt";
 import { useFlowStore } from "@/stores/flowStore";
 import { useWorkspaceStore } from "@/stores/workspaceStore";
 import type { WorkspaceNode } from "@/types";
@@ -113,7 +113,7 @@ export const useChatStore = create<ChatState>()(
           const systemMsg: ChatMessage = {
             id: "system",
             role: "system",
-            content: BILLY_SYSTEM_PROMPT,
+            content: getEffectiveBillyPrompt(),
             createdAt: 0,
           };
 

From fc5543d05d95569423fef031c00d9e6f7468234b Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Sun, 28 Jun 2026 13:44:40 +0200
Subject: [PATCH 03/18] feat(metrics): parse frame-time percentiles from
 gfxinfo

---
 src-tauri/src/metrics/parsers.rs | 51 ++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/src-tauri/src/metrics/parsers.rs b/src-tauri/src/metrics/parsers.rs
index f025d32..1ba8994 100644
--- a/src-tauri/src/metrics/parsers.rs
+++ b/src-tauri/src/metrics/parsers.rs
@@ -485,6 +485,28 @@ Active UID stats:
 pub struct GfxStats {
     pub total_frames: u32,
     pub janky_frames: u32,
+    pub p50_ms: Option<f32>,
+    pub p90_ms: Option<f32>,
+    pub p95_ms: Option<f32>,
+    pub p99_ms: Option<f32>,
+}
+
+/// Parse the `<N>th percentile: <X>ms` value for a given percentile label.
+fn parse_percentile_ms(s: &str, label: &str) -> Option<f32> {
+    for line in s.lines() {
+        let t = line.trim();
+        if let Some(rest) = t.strip_prefix(label) {
+            let digits: String = rest
+                .trim()
+                .chars()
+                .take_while(|c| c.is_ascii_digit() || *c == '.')
+                .collect();
+            if let Ok(v) = digits.parse::<f32>() {
+                return Some(v);
+            }
+        }
+    }
+    None
 }
 
 pub fn parse_gfxinfo(s: &str) -> Option<GfxStats> {
@@ -501,6 +523,10 @@ pub fn parse_gfxinfo(s: &str) -> Option<GfxStats> {
     Some(GfxStats {
         total_frames: total?,
         janky_frames: janky?,
+        p50_ms: parse_percentile_ms(s, "50th percentile:"),
+        p90_ms: parse_percentile_ms(s, "90th percentile:"),
+        p95_ms: parse_percentile_ms(s, "95th percentile:"),
+        p99_ms: parse_percentile_ms(s, "99th percentile:"),
     })
 }
 
@@ -536,4 +562,29 @@ Graphics info for pid 1234 [com.example.app]
         // Total present but janky missing — treat as None to avoid lying to UI
         assert!(parse_gfxinfo("Total frames rendered: 100\n").is_none());
     }
+
+    #[test]
+    fn parses_frame_time_percentiles() {
+        let input = "\
+  Total frames rendered: 420
+  Janky frames: 38 (9.05%)
+  50th percentile: 8ms
+  90th percentile: 14ms
+  95th percentile: 17ms
+  99th percentile: 23ms
+";
+        let s = parse_gfxinfo(input).expect("should parse");
+        assert_eq!(s.p50_ms, Some(8.0));
+        assert_eq!(s.p90_ms, Some(14.0));
+        assert_eq!(s.p95_ms, Some(17.0));
+        assert_eq!(s.p99_ms, Some(23.0));
+    }
+
+    #[test]
+    fn percentiles_none_when_absent() {
+        let input = "  Total frames rendered: 10\n  Janky frames: 1 (10.00%)\n";
+        let s = parse_gfxinfo(input).expect("should parse");
+        assert_eq!(s.p50_ms, None);
+        assert_eq!(s.p99_ms, None);
+    }
 }

From e0eeafadb2610c02de60552fd5035821f311fcad Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Sun, 28 Jun 2026 13:47:47 +0200
Subject: [PATCH 04/18] feat(metrics): parse thermal status from dumpsys
 thermalservice

---
 src-tauri/src/metrics/parsers.rs | 44 ++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/src-tauri/src/metrics/parsers.rs b/src-tauri/src/metrics/parsers.rs
index 1ba8994..4b7ab93 100644
--- a/src-tauri/src/metrics/parsers.rs
+++ b/src-tauri/src/metrics/parsers.rs
@@ -588,3 +588,47 @@ Graphics info for pid 1234 [com.example.app]
         assert_eq!(s.p99_ms, None);
     }
 }
+
+/// Parse the device thermal status code from `dumpsys thermalservice`.
+/// Handles both the "Thermal Status: N" line and the "mStatus=N" form.
+pub fn parse_thermal_status(s: &str) -> Option<u8> {
+    for line in s.lines() {
+        let t = line.trim();
+        for marker in ["Thermal Status:", "mStatus="] {
+            if let Some(idx) = t.find(marker) {
+                let rest = &t[idx + marker.len()..];
+                let digits: String = rest
+                    .trim_start()
+                    .chars()
+                    .take_while(|c| c.is_ascii_digit())
+                    .collect();
+                if let Ok(v) = digits.parse::<u8>() {
+                    return Some(v);
+                }
+            }
+        }
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests_thermal {
+    use super::*;
+
+    #[test]
+    fn parses_thermal_status_label_form() {
+        let dump = "Thermal Status: 2\nCached temperatures:\n  ...\n";
+        assert_eq!(parse_thermal_status(dump), Some(2));
+    }
+
+    #[test]
+    fn parses_mstatus_form() {
+        let dump = "IsStatusOverride: false\nmStatus=0\n";
+        assert_eq!(parse_thermal_status(dump), Some(0));
+    }
+
+    #[test]
+    fn none_when_absent() {
+        assert_eq!(parse_thermal_status("no thermal data here"), None);
+    }
+}

From e4d549bf1a1a9b42b7c66cb3ce8be2ec7d8db155 Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Sun, 28 Jun 2026 13:51:49 +0200
Subject: [PATCH 05/18] feat(metrics): emit frame-time percentiles and thermal
 status (android)

---
 src-tauri/src/metrics/collector.rs | 22 +++++++++++++++++++---
 src-tauri/src/metrics/mod.rs       | 23 ++++++++++++++++++++++-
 2 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/src-tauri/src/metrics/collector.rs b/src-tauri/src/metrics/collector.rs
index 8d04d60..61a5faf 100644
--- a/src-tauri/src/metrics/collector.rs
+++ b/src-tauri/src/metrics/collector.rs
@@ -9,8 +9,8 @@ use std::time::Instant;
 use crate::device::adb;
 use crate::error::{AppError, AppResult};
 use crate::metrics::parsers::{
-    cpu_percent, parse_gfxinfo, parse_netstats_detail_for_uid, parse_proc_stat, parse_vm_rss_mb,
-    parse_xt_qtaguid_for_uid, NetBytes, ProcStat,
+    cpu_percent, parse_gfxinfo, parse_netstats_detail_for_uid, parse_proc_stat,
+    parse_thermal_status, parse_vm_rss_mb, parse_xt_qtaguid_for_uid, NetBytes, ProcStat,
 };
 
 const ANDROID_USER_HZ: u32 = 100;
@@ -33,6 +33,10 @@ pub struct NetSample {
 pub struct GfxSample {
     pub fps: f32,
     pub jank_pct: f32,
+    pub p50_ms: Option<f32>,
+    pub p90_ms: Option<f32>,
+    pub p95_ms: Option<f32>,
+    pub p99_ms: Option<f32>,
 }
 
 pub fn fetch_cpu_mem(
@@ -158,7 +162,19 @@ pub fn fetch_gfx(serial: &str, package: &str) -> AppResult<Option<GfxSample>> {
     // Window is 5s — FPS is total/5.
     let fps = stats.total_frames as f32 / 5.0;
     let jank_pct = stats.janky_frames as f32 * 100.0 / stats.total_frames as f32;
-    Ok(Some(GfxSample { fps, jank_pct }))
+    Ok(Some(GfxSample {
+        fps,
+        jank_pct,
+        p50_ms: stats.p50_ms,
+        p90_ms: stats.p90_ms,
+        p95_ms: stats.p95_ms,
+        p99_ms: stats.p99_ms,
+    }))
+}
+
+pub fn fetch_thermal(serial: &str) -> AppResult<Option<u8>> {
+    let out = adb::exec_shell(serial, "dumpsys thermalservice")?;
+    Ok(parse_thermal_status(&out))
 }
 
 #[cfg(test)]
diff --git a/src-tauri/src/metrics/mod.rs b/src-tauri/src/metrics/mod.rs
index d18b133..fbbb4c9 100644
--- a/src-tauri/src/metrics/mod.rs
+++ b/src-tauri/src/metrics/mod.rs
@@ -21,7 +21,7 @@ use tokio::sync::{oneshot, Mutex as AsyncMutex};
 use tracing::{debug, info, warn};
 
 use crate::error::{AppError, AppResult};
-use crate::metrics::collector::{fetch_cpu_mem, fetch_gfx, GfxSample};
+use crate::metrics::collector::{fetch_cpu_mem, fetch_gfx, fetch_thermal, GfxSample};
 use crate::metrics::foreground::{resolve_target, Target};
 use crate::metrics::parsers::ProcStat;
 
@@ -45,6 +45,11 @@ pub struct MetricsSample {
     pub mem_mb: f32,
     pub fps: Option<f32>,
     pub jank_pct: Option<f32>,
+    pub frame_p50_ms: Option<f32>,
+    pub frame_p90_ms: Option<f32>,
+    pub frame_p95_ms: Option<f32>,
+    pub frame_p99_ms: Option<f32>,
+    pub thermal_status: Option<u8>,
     pub net_rx_kbps: f32,
     pub net_tx_kbps: f32,
     pub ts: u64,
@@ -91,6 +96,7 @@ async fn run_loop(app: AppHandle, serial: String, mut cancel: oneshot::Receiver<
     let mut target: Option<Target> = None;
     let mut prev_stat: Option<(ProcStat, Instant)> = None;
     let mut last_gfx: Option<GfxSample> = None;
+    let mut last_thermal: Option<u8> = None;
     let mut last_fg_check = Instant::now() - FOREGROUND_CHECK_INTERVAL;
     let mut last_gfx_poll = Instant::now() - GFX_INTERVAL;
     let mut consecutive_errors: u32 = 0;
@@ -133,6 +139,7 @@ async fn run_loop(app: AppHandle, serial: String, mut cancel: oneshot::Receiver<
                         );
                         prev_stat = None;
                         last_gfx = None;
+                        last_thermal = None;
                     }
                     target = Some(new_target);
                 }
@@ -200,6 +207,15 @@ async fn run_loop(app: AppHandle, serial: String, mut cancel: oneshot::Receiver<
                     warn!(error = ?e, "gfx fetch failed");
                 }
             }
+            let serial_for_thermal = serial.clone();
+            match tokio::task::spawn_blocking(move || fetch_thermal(&serial_for_thermal))
+                .await
+                .unwrap_or_else(|e| {
+                    Err(AppError::MetricsFailed(format!("thermal join failed: {e}")))
+                }) {
+                Ok(t) => last_thermal = t,
+                Err(e) => warn!(error = ?e, "thermal fetch failed"),
+            }
         }
 
         if consecutive_errors >= MAX_CONSECUTIVE_ERRORS {
@@ -215,6 +231,11 @@ async fn run_loop(app: AppHandle, serial: String, mut cancel: oneshot::Receiver<
             mem_mb: cpu_mem.mem_mb,
             fps: last_gfx.map(|g| g.fps),
             jank_pct: last_gfx.map(|g| g.jank_pct),
+            frame_p50_ms: last_gfx.and_then(|g| g.p50_ms),
+            frame_p90_ms: last_gfx.and_then(|g| g.p90_ms),
+            frame_p95_ms: last_gfx.and_then(|g| g.p95_ms),
+            frame_p99_ms: last_gfx.and_then(|g| g.p99_ms),
+            thermal_status: last_thermal,
             net_rx_kbps: 0.0,
             net_tx_kbps: 0.0,
             ts: ts_ms(),

From 67e11e32d03f9d3a5b8ec021744f45a8614f985e Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Sun, 28 Jun 2026 13:54:51 +0200
Subject: [PATCH 06/18] feat(metrics): add ps cpu/rss parser for ios simulator

---
 src-tauri/src/metrics/ios_sim.rs | 39 ++++++++++++++++++++++++++++++++
 src-tauri/src/metrics/mod.rs     |  1 +
 2 files changed, 40 insertions(+)
 create mode 100644 src-tauri/src/metrics/ios_sim.rs

diff --git a/src-tauri/src/metrics/ios_sim.rs b/src-tauri/src/metrics/ios_sim.rs
new file mode 100644
index 0000000..1138ba4
--- /dev/null
+++ b/src-tauri/src/metrics/ios_sim.rs
@@ -0,0 +1,39 @@
+// Copyright (c) 2026 Ethan Morisset
+// SPDX-License-Identifier: BUSL-1.1
+
+//! iOS simulator metrics. A simulated app runs as a host macOS process, so its
+//! CPU% and resident memory are readable with `ps`. Collection commands live in
+//! the collector loop (mod.rs); the pure `ps` parser lives here for testing.
+
+/// Parse `ps -o %cpu=,rss= -p <pid>` output → (cpu_pct, mem_mb).
+/// macOS reports RSS in KiB. Returns None if the line can't be parsed (e.g. the
+/// process has exited and ps printed nothing).
+pub fn parse_ps_cpu_rss(s: &str) -> Option<(f32, f32)> {
+    let line = s.lines().map(str::trim).find(|l| !l.is_empty())?;
+    let mut cols = line.split_whitespace();
+    let cpu: f32 = cols.next()?.parse().ok()?;
+    let rss_kib: f32 = cols.next()?.parse().ok()?;
+    Some((cpu, rss_kib / 1024.0))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_cpu_and_rss() {
+        let (cpu, mem) = parse_ps_cpu_rss(" 12.5 204800\n").expect("should parse");
+        assert!((cpu - 12.5).abs() < 0.01, "cpu {cpu}");
+        assert!((mem - 200.0).abs() < 0.01, "mem {mem}");
+    }
+
+    #[test]
+    fn none_on_empty() {
+        assert_eq!(parse_ps_cpu_rss("\n  \n"), None);
+    }
+
+    #[test]
+    fn none_on_garbage() {
+        assert_eq!(parse_ps_cpu_rss("not numbers here"), None);
+    }
+}
diff --git a/src-tauri/src/metrics/mod.rs b/src-tauri/src/metrics/mod.rs
index fbbb4c9..3490ca0 100644
--- a/src-tauri/src/metrics/mod.rs
+++ b/src-tauri/src/metrics/mod.rs
@@ -10,6 +10,7 @@
 
 pub mod collector;
 pub mod foreground;
+pub mod ios_sim;
 pub mod parsers;
 
 use std::time::{Duration, Instant};

From 9f0cd24ca568f6f2e583c100362cf7cbb628ce12 Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Sun, 28 Jun 2026 14:01:32 +0200
Subject: [PATCH 07/18] feat(metrics): dispatch collection by platform
 (android, ios-sim, unsupported)

---
 src-tauri/src/ipc/commands.rs    |   7 +-
 src-tauri/src/metrics/ios_sim.rs |  91 ++++++++++++++++++++++++
 src-tauri/src/metrics/mod.rs     | 117 +++++++++++++++++++++++++++++--
 3 files changed, 205 insertions(+), 10 deletions(-)

diff --git a/src-tauri/src/ipc/commands.rs b/src-tauri/src/ipc/commands.rs
index 435b54f..720b711 100644
--- a/src-tauri/src/ipc/commands.rs
+++ b/src-tauri/src/ipc/commands.rs
@@ -1048,13 +1048,12 @@ pub fn list_workspace(path: String) -> AppResult<WorkspaceNode> {
 
 #[tauri::command]
 pub async fn start_metrics(app: AppHandle, state: State<'_, AppState>) -> AppResult<()> {
-    let serial = state
+    let device = state
         .connected_device
         .read()
-        .as_ref()
-        .map(|d| d.serial.clone())
+        .clone()
         .ok_or(AppError::NoDevice)?;
-    metrics::start(app, serial).await
+    metrics::start(app, device).await
 }
 
 #[tauri::command]
diff --git a/src-tauri/src/metrics/ios_sim.rs b/src-tauri/src/metrics/ios_sim.rs
index 1138ba4..ce40d1b 100644
--- a/src-tauri/src/metrics/ios_sim.rs
+++ b/src-tauri/src/metrics/ios_sim.rs
@@ -5,6 +5,10 @@
 //! CPU% and resident memory are readable with `ps`. Collection commands live in
 //! the collector loop (mod.rs); the pure `ps` parser lives here for testing.
 
+use std::process::Command;
+
+use crate::error::{AppError, AppResult};
+
 /// Parse `ps -o %cpu=,rss= -p <pid>` output → (cpu_pct, mem_mb).
 /// macOS reports RSS in KiB. Returns None if the line can't be parsed (e.g. the
 /// process has exited and ps printed nothing).
@@ -16,6 +20,57 @@ pub fn parse_ps_cpu_rss(s: &str) -> Option<(f32, f32)> {
     Some((cpu, rss_kib / 1024.0))
 }
 
+/// Find the host PID + bundle id of the foreground app under test from
+/// `simctl spawn <udid> launchctl list` output. Rows look like
+/// `<pid>\t<status>\tUIKitApplication:<bundleId>[hex][rb-legacy]`.
+///
+/// The list mixes the app under test with Apple system apps and the Maestro
+/// driver, so we skip any bundle starting with `com.apple.` or containing
+/// `maestro-driver`, then take the LAST remaining row (most recently launched).
+pub fn parse_launchctl_frontmost(launchctl_list: &str) -> Option<(u32, String)> {
+    const MARKER: &str = "UIKitApplication:";
+    let mut found: Option<(u32, String)> = None;
+    for line in launchctl_list.lines() {
+        let Some(idx) = line.find(MARKER) else {
+            continue;
+        };
+        let after = &line[idx + MARKER.len()..];
+        let bundle = after.split('[').next().unwrap_or("").trim();
+        if bundle.is_empty()
+            || bundle.starts_with("com.apple.")
+            || bundle.contains("maestro-driver")
+        {
+            continue;
+        }
+        let Some(pid) = line.split_whitespace().next().and_then(|t| t.parse().ok()) else {
+            continue;
+        };
+        found = Some((pid, bundle.to_string()));
+    }
+    found
+}
+
+/// Resolve the foreground simulated app's host PID + bundle id by shelling
+/// `xcrun simctl spawn <udid> launchctl list` and parsing the result.
+pub fn frontmost_pid_and_bundle(udid: &str) -> AppResult<Option<(u32, String)>> {
+    let out = Command::new("xcrun")
+        .args(["simctl", "spawn", udid, "launchctl", "list"])
+        .output()
+        .map_err(AppError::Io)?;
+    let text = String::from_utf8_lossy(&out.stdout);
+    Ok(parse_launchctl_frontmost(&text))
+}
+
+/// Sample CPU% and resident MB for a host PID via `ps`.
+pub fn sample_cpu_mem(pid: u32) -> AppResult<Option<(f32, f32)>> {
+    let out = Command::new("ps")
+        .args(["-o", "%cpu=,rss=", "-p", &pid.to_string()])
+        .output()
+        .map_err(AppError::Io)?;
+    let text = String::from_utf8_lossy(&out.stdout);
+    Ok(parse_ps_cpu_rss(&text))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -36,4 +91,40 @@ mod tests {
     fn none_on_garbage() {
         assert_eq!(parse_ps_cpu_rss("not numbers here"), None);
     }
+
+    #[test]
+    fn frontmost_skips_system_and_driver_apps() {
+        let out = "\
+1729\t0\tUIKitApplication:com.apple.chrono.WidgetRenderer-Default[565c][rb-legacy]
+2452\t0\tUIKitApplication:com.apple.mobilecal[ca73][rb-legacy]
+2139\t0\tUIKitApplication:dev.mobile.maestro-driver-iosUITests.xctrunner[c7a5][rb-legacy]
+1748\t0\tUIKitApplication:com.apple.Spotlight[b257][rb-legacy]
+1900\t0\tUIKitApplication:com.example.myapp[abcd][rb-legacy]
+";
+        assert_eq!(
+            parse_launchctl_frontmost(out),
+            Some((1900, "com.example.myapp".to_string()))
+        );
+    }
+
+    #[test]
+    fn frontmost_none_when_only_system_apps() {
+        let out = "\
+1748\t0\tUIKitApplication:com.apple.Spotlight[b257][rb-legacy]
+2139\t0\tUIKitApplication:dev.mobile.maestro-driver-iosUITests.xctrunner[c7a5][rb-legacy]
+";
+        assert_eq!(parse_launchctl_frontmost(out), None);
+    }
+
+    #[test]
+    fn frontmost_picks_last_of_multiple_user_apps() {
+        let out = "\
+1900\t0\tUIKitApplication:com.example.first[aaaa][rb-legacy]
+1950\t0\tUIKitApplication:com.example.second[bbbb][rb-legacy]
+";
+        assert_eq!(
+            parse_launchctl_frontmost(out),
+            Some((1950, "com.example.second".to_string()))
+        );
+    }
 }
diff --git a/src-tauri/src/metrics/mod.rs b/src-tauri/src/metrics/mod.rs
index 3490ca0..87c9f59 100644
--- a/src-tauri/src/metrics/mod.rs
+++ b/src-tauri/src/metrics/mod.rs
@@ -68,16 +68,39 @@ pub struct StoppedReason {
     pub message: Option<String>,
 }
 
-pub async fn start(app: AppHandle, serial: String) -> AppResult<()> {
+pub async fn start(app: AppHandle, device: crate::device::Device) -> AppResult<()> {
+    use crate::device::Platform;
     let mut guard = RUNNING.lock().await;
     if guard.is_some() {
         return Err(AppError::MetricsAlreadyRunning);
     }
-    let (tx, rx) = oneshot::channel::<()>();
-    let join = tokio::spawn(run_loop(app, serial, rx));
-    *guard = Some((tx, join));
-    info!("metrics task started");
-    Ok(())
+    match (device.platform, device.physical) {
+        (Platform::Android, _) => {
+            let (tx, rx) = oneshot::channel::<()>();
+            let join = tokio::spawn(run_loop(app, device.serial, rx));
+            *guard = Some((tx, join));
+            info!("android metrics task started");
+            Ok(())
+        }
+        (Platform::Ios, false) => {
+            let (tx, rx) = oneshot::channel::<()>();
+            let join = tokio::spawn(run_loop_ios_sim(app, device.serial, rx));
+            *guard = Some((tx, join));
+            info!("ios-sim metrics task started");
+            Ok(())
+        }
+        (Platform::Ios, true) => {
+            emit_unsupported(
+                &app,
+                "Per-app metrics aren't available on physical iPhones (requires Instruments).",
+            );
+            Ok(())
+        }
+        (Platform::Web, _) => {
+            emit_unsupported(&app, "The Web target has no per-app performance metrics.");
+            Ok(())
+        }
+    }
 }
 
 pub async fn stop() -> AppResult<()> {
@@ -257,10 +280,92 @@ async fn run_loop(app: AppHandle, serial: String, mut cancel: oneshot::Receiver<
     });
 }
 
+/// iOS-simulator polling loop. A simulated app runs as a host macOS process, so
+/// we resolve the frontmost `UIKitApplication`'s host PID + bundle id and sample
+/// CPU%/RAM via `ps`. All other metric fields (fps, jank, frame times, thermal,
+/// net) are unavailable on this path and ship as `None`/`0.0`.
+async fn run_loop_ios_sim(app: AppHandle, udid: String, mut cancel: oneshot::Receiver<()>) {
+    let mut consecutive_errors: u32 = 0;
+    let mut ticker = tokio::time::interval(TICK_INTERVAL);
+    ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+
+    loop {
+        tokio::select! {
+            _ = &mut cancel => {
+                emit_stopped(&app, "user", None);
+                break;
+            }
+            _ = ticker.tick() => {}
+        }
+
+        let udid_for_pid = udid.clone();
+        let resolved =
+            tokio::task::spawn_blocking(move || ios_sim::frontmost_pid_and_bundle(&udid_for_pid))
+                .await
+                .unwrap_or_else(|e| {
+                    Err(AppError::MetricsFailed(format!("ios pid join failed: {e}")))
+                });
+        let (pid, bundle) = match resolved {
+            Ok(Some(v)) => v,
+            Ok(None) => continue,
+            Err(e) => {
+                warn!(error = ?e, "ios pid resolution failed");
+                consecutive_errors += 1;
+                if consecutive_errors >= MAX_CONSECUTIVE_ERRORS {
+                    emit_stopped(&app, "error", Some(e.to_string()));
+                    break;
+                }
+                continue;
+            }
+        };
+
+        let cpu_mem = tokio::task::spawn_blocking(move || ios_sim::sample_cpu_mem(pid))
+            .await
+            .unwrap_or_else(|e| Err(AppError::MetricsFailed(format!("ios ps join failed: {e}"))));
+        let (cpu_pct, mem_mb) = match cpu_mem {
+            Ok(Some(v)) => v,
+            _ => continue,
+        };
+        consecutive_errors = 0;
+
+        let sample = MetricsSample {
+            package: bundle,
+            cpu_pct,
+            mem_mb,
+            fps: None,
+            jank_pct: None,
+            frame_p50_ms: None,
+            frame_p90_ms: None,
+            frame_p95_ms: None,
+            frame_p99_ms: None,
+            thermal_status: None,
+            net_rx_kbps: 0.0,
+            net_tx_kbps: 0.0,
+            ts: ts_ms(),
+        };
+        let _ = app.emit(EVT_SAMPLE, sample);
+    }
+
+    info!("ios-sim metrics task exited");
+    tokio::spawn(async {
+        *RUNNING.lock().await = None;
+    });
+}
+
 fn emit_stopped(app: &AppHandle, reason: &'static str, message: Option<String>) {
     let _ = app.emit(EVT_STOPPED, StoppedReason { reason, message });
 }
 
+fn emit_unsupported(app: &AppHandle, message: &str) {
+    let _ = app.emit(
+        EVT_STOPPED,
+        StoppedReason {
+            reason: "unsupported",
+            message: Some(message.to_string()),
+        },
+    );
+}
+
 fn ts_ms() -> u64 {
     std::time::SystemTime::now()
         .duration_since(std::time::UNIX_EPOCH)

From 91ba6ba816025575bbce171d67087eb6d6d0478e Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Sun, 28 Jun 2026 14:05:25 +0200
Subject: [PATCH 08/18] feat(metrics): extend frontend payload/store with
 percentiles + thermal

---
 src/App.tsx                     |  5 +++++
 src/lib/ipc.ts                  |  7 ++++++-
 src/stores/metricsStore.test.ts | 36 +++++++++++++++++++++++++++++++++
 src/stores/metricsStore.ts      |  5 +++++
 4 files changed, 52 insertions(+), 1 deletion(-)

diff --git a/src/App.tsx b/src/App.tsx
index ebd102f..478d14c 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -146,6 +146,11 @@ export default function App() {
           memMb: p.mem_mb,
           fps: p.fps,
           jankPct: p.jank_pct,
+          frameP50: p.frame_p50_ms,
+          frameP90: p.frame_p90_ms,
+          frameP95: p.frame_p95_ms,
+          frameP99: p.frame_p99_ms,
+          thermalStatus: p.thermal_status,
           netRxKbps: p.net_rx_kbps,
           netTxKbps: p.net_tx_kbps,
         }),
diff --git a/src/lib/ipc.ts b/src/lib/ipc.ts
index d9a0306..da40793 100644
--- a/src/lib/ipc.ts
+++ b/src/lib/ipc.ts
@@ -34,6 +34,11 @@ export interface MetricsSamplePayload {
   mem_mb: number;
   fps: number | null;
   jank_pct: number | null;
+  frame_p50_ms: number | null;
+  frame_p90_ms: number | null;
+  frame_p95_ms: number | null;
+  frame_p99_ms: number | null;
+  thermal_status: number | null;
   net_rx_kbps: number;
   net_tx_kbps: number;
   ts: number;
@@ -45,7 +50,7 @@ export interface TargetChangedPayload {
 }
 
 export interface MetricsStoppedPayload {
-  reason: "user" | "device_disconnected" | "error";
+  reason: "user" | "device_disconnected" | "error" | "unsupported";
   message: string | null;
 }
 
diff --git a/src/stores/metricsStore.test.ts b/src/stores/metricsStore.test.ts
index 5f028bf..21b5524 100644
--- a/src/stores/metricsStore.test.ts
+++ b/src/stores/metricsStore.test.ts
@@ -10,10 +10,31 @@ const mkSample = (ts: number): Sample => ({
   memMb: 0,
   fps: null,
   jankPct: null,
+  frameP50: null,
+  frameP90: null,
+  frameP95: null,
+  frameP99: null,
+  thermalStatus: null,
   netRxKbps: 0,
   netTxKbps: 0,
 });
 
+const sample = (over: Partial<Sample> = {}): Sample => ({
+  ts: 1,
+  cpuPct: 10,
+  memMb: 100,
+  fps: null,
+  jankPct: null,
+  frameP50: null,
+  frameP90: null,
+  frameP95: null,
+  frameP99: null,
+  thermalStatus: null,
+  netRxKbps: 0,
+  netTxKbps: 0,
+  ...over,
+});
+
 beforeEach(() => {
   useMetricsStore.getState().reset();
 });
@@ -81,3 +102,18 @@ describe("metricsStore.reset", () => {
     expect(s.stoppedReason).toBeNull();
   });
 });
+
+describe("metricsStore", () => {
+  it("keeps appended samples", () => {
+    useMetricsStore.getState().appendSample(sample({ cpuPct: 42 }));
+    const s = useMetricsStore.getState().samples;
+    expect(s).toHaveLength(1);
+    expect(s[0].cpuPct).toBe(42);
+  });
+
+  it("caps history at 60 samples", () => {
+    for (let i = 0; i < 70; i++) useMetricsStore.getState().appendSample(sample({ ts: i }));
+    expect(useMetricsStore.getState().samples).toHaveLength(60);
+    expect(useMetricsStore.getState().samples[0].ts).toBe(10);
+  });
+});
diff --git a/src/stores/metricsStore.ts b/src/stores/metricsStore.ts
index 46b2d54..5ac53bc 100644
--- a/src/stores/metricsStore.ts
+++ b/src/stores/metricsStore.ts
@@ -9,6 +9,11 @@ export interface Sample {
   memMb: number;
   fps: number | null;
   jankPct: number | null;
+  frameP50: number | null;
+  frameP90: number | null;
+  frameP95: number | null;
+  frameP99: number | null;
+  thermalStatus: number | null;
   netRxKbps: number;
   netTxKbps: number;
 }

From d178f724002a751f822f7f4fb1c2a390c77d197c Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Sun, 28 Jun 2026 14:11:25 +0200
Subject: [PATCH 09/18] refactor(metrics): single open/close source of truth,
 capture only when open

---
 src/App.tsx                                   |  9 +++----
 src/components/MainView.tsx                   | 11 +++-----
 src/components/MetricsPanel.tsx               |  5 ++--
 src/components/RunConsole.tsx                 | 27 +++++++++----------
 .../settings/DevicePerformanceSettings.tsx    | 11 --------
 src/stores/metricsStore.test.ts               | 19 -------------
 src/stores/metricsStore.ts                    |  7 -----
 src/stores/panelsStore.test.ts                | 15 ++++++++---
 src/stores/panelsStore.ts                     |  9 +++----
 src/stores/settingsStore.test.ts              |  6 +----
 src/stores/settingsStore.ts                   |  5 ----
 11 files changed, 39 insertions(+), 85 deletions(-)

diff --git a/src/App.tsx b/src/App.tsx
index 478d14c..8f20083 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -18,6 +18,7 @@ import { applyTheme, watchSystemTheme } from "@/lib/theme";
 import { useDeviceStore } from "@/stores/deviceStore";
 import { useInspectorStore } from "@/stores/inspectorStore";
 import { useMetricsStore } from "@/stores/metricsStore";
+import { usePanelsStore } from "@/stores/panelsStore";
 import { useRunStore } from "@/stores/runStore";
 import { useSettingsStore } from "@/stores/settingsStore";
 import { useStreamStore } from "@/stores/streamStore";
@@ -207,13 +208,11 @@ export default function App() {
     };
   }, []);
 
-  const panelOpen = useMetricsStore((s) => s.panelOpen);
-  const perfEnabled = useSettingsStore((s) => s.perfMonitoringEnabled);
+  const metricsOpen = usePanelsStore((s) => s.visible.metrics);
   const deviceConnected = useDeviceStore((s) => Boolean(s.current));
-  const currentPlatform = useDeviceStore((s) => s.current?.platform ?? null);
 
   useEffect(() => {
-    if (!perfEnabled || !panelOpen || !deviceConnected || currentPlatform !== "android") {
+    if (!metricsOpen || !deviceConnected) {
       void ipc.stopMetrics().catch(() => {});
       return;
     }
@@ -226,7 +225,7 @@ export default function App() {
     return () => {
       void ipc.stopMetrics().catch(() => {});
     };
-  }, [perfEnabled, panelOpen, deviceConnected, currentPlatform]);
+  }, [metricsOpen, deviceConnected]);
 
   return (
     <>
diff --git a/src/components/MainView.tsx b/src/components/MainView.tsx
index 8b8cf6d..7b7c984 100644
--- a/src/components/MainView.tsx
+++ b/src/components/MainView.tsx
@@ -23,7 +23,6 @@ import { buildPartialFlow } from "@/lib/partialFlow";
 import { useShortcuts } from "@/lib/keyboard";
 import { useChatStore } from "@/stores/chatStore";
 import { useFlowStore } from "@/stores/flowStore";
-import { useMetricsStore } from "@/stores/metricsStore";
 import { useInspectorStore } from "@/stores/inspectorStore";
 import { usePanelsStore } from "@/stores/panelsStore";
 import { useRunStore } from "@/stores/runStore";
@@ -52,8 +51,6 @@ export function MainView() {
   const runningPid = useRunStore((s) => s.pid);
 
   const streamEnabled = useSettingsStore((s) => s.streamEnabled);
-  const panelOpen = useMetricsStore((s) => s.panelOpen);
-  const perfEnabled = useSettingsStore((s) => s.perfMonitoringEnabled);
   const panels = usePanelsStore((s) => s.visible);
   const chatOpen = useChatStore((s) => s.isOpen);
 
@@ -74,7 +71,7 @@ export function MainView() {
   // editor + device get the most room; the user can drag it taller and the
   // size persists. `BOTTOM_MIN` must match the `main-bottom` Panel's `minSize`.
   const BOTTOM_MIN = 10;
-  const bottomVisible = panels.console || (perfEnabled && panelOpen && panels.metrics);
+  const bottomVisible = panels.console || panels.metrics;
   const mainTopSize = bottomVisible ? 100 - BOTTOM_MIN : 100;
   const mainBottomSize = 100 - mainTopSize;
 
@@ -278,7 +275,7 @@ export function MainView() {
                 </PanelGroup>
               </Panel>
 
-              {panels.console || (perfEnabled && panelOpen && panels.metrics) ? (
+              {panels.console || panels.metrics ? (
                 <>
                   <PanelResizeHandle className={RESIZE_HANDLE_V} />
                   <Panel
@@ -292,7 +289,7 @@ export function MainView() {
                         <Panel
                           id="console"
                           order={1}
-                          defaultSize={perfEnabled && panelOpen && panels.metrics ? 70 : 100}
+                          defaultSize={panels.metrics ? 70 : 100}
                           minSize={20}
                         >
                           <PanelShell id="console">
@@ -301,7 +298,7 @@ export function MainView() {
                         </Panel>
                       ) : null}
 
-                      {perfEnabled && panelOpen && panels.metrics ? (
+                      {panels.metrics ? (
                         <>
                           {panels.console ? (
                             <PanelResizeHandle className={RESIZE_HANDLE_H} />
diff --git a/src/components/MetricsPanel.tsx b/src/components/MetricsPanel.tsx
index f3659d2..cb4ec8f 100644
--- a/src/components/MetricsPanel.tsx
+++ b/src/components/MetricsPanel.tsx
@@ -8,9 +8,10 @@ import { MetricsSparkline } from "@/components/MetricsSparkline";
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/Tooltip";
 import { useDeviceStore } from "@/stores/deviceStore";
 import { useMetricsStore } from "@/stores/metricsStore";
+import { usePanelsStore } from "@/stores/panelsStore";
 
 export function MetricsPanel() {
-  const setPanelOpen = useMetricsStore((s) => s.setPanelOpen);
+  const hidePanel = usePanelsStore((s) => s.hide);
   const pkg = useMetricsStore((s) => s.currentPackage);
   const samples = useMetricsStore((s) => s.samples);
   const stopped = useMetricsStore((s) => s.stoppedReason);
@@ -30,7 +31,7 @@ export function MetricsPanel() {
         <Button
           size="xs"
           variant="ghost"
-          onClick={() => setPanelOpen(false)}
+          onClick={() => hidePanel("metrics")}
           aria-label="Close performance panel"
         >
           <X className="h-3 w-3" />
diff --git a/src/components/RunConsole.tsx b/src/components/RunConsole.tsx
index 2fbfd78..8315bc9 100644
--- a/src/components/RunConsole.tsx
+++ b/src/components/RunConsole.tsx
@@ -10,7 +10,7 @@ import { humanLabel, formatDuration } from "@/lib/stepRenderer";
 import { cn } from "@/lib/utils";
 import { useRunStore } from "@/stores/runStore";
 import type { StepRunState } from "@/stores/runStore";
-import { useMetricsStore } from "@/stores/metricsStore";
+import { usePanelsStore } from "@/stores/panelsStore";
 import { useSettingsStore } from "@/stores/settingsStore";
 
 export function RunConsole({ onRun, onStop }: { onRun: () => void; onStop: () => void }) {
@@ -19,9 +19,8 @@ export function RunConsole({ onRun, onStop }: { onRun: () => void; onStop: () =>
   const logs = useRunStore((s) => s.logs);
   const clearConsole = useRunStore((s) => s.clearConsole);
 
-  const perfEnabled = useSettingsStore((s) => s.perfMonitoringEnabled);
-  const panelOpen = useMetricsStore((s) => s.panelOpen);
-  const togglePanel = useMetricsStore((s) => s.togglePanel);
+  const metricsOpen = usePanelsStore((s) => s.visible.metrics);
+  const toggleMetrics = usePanelsStore((s) => s.toggle);
 
   const consoleMode = useSettingsStore((s) => s.consoleMode);
   const setConsoleMode = useSettingsStore((s) => s.setConsoleMode);
@@ -91,17 +90,15 @@ export function RunConsole({ onRun, onStop }: { onRun: () => void; onStop: () =>
               Technical
             </button>
           </div>
-          {perfEnabled && (
-            <Button
-              size="xs"
-              variant={panelOpen ? "default" : "ghost"}
-              onClick={togglePanel}
-              title="Toggle performance HUD"
-            >
-              <Activity className="h-3 w-3" />
-              Perf
-            </Button>
-          )}
+          <Button
+            size="xs"
+            variant={metricsOpen ? "default" : "ghost"}
+            onClick={() => toggleMetrics("metrics")}
+            title="Toggle performance HUD"
+          >
+            <Activity className="h-3 w-3" />
+            Performance
+          </Button>
           <Button
             size="xs"
             variant="ghost"
diff --git a/src/components/settings/DevicePerformanceSettings.tsx b/src/components/settings/DevicePerformanceSettings.tsx
index dfff454..ec32745 100644
--- a/src/components/settings/DevicePerformanceSettings.tsx
+++ b/src/components/settings/DevicePerformanceSettings.tsx
@@ -11,8 +11,6 @@ import { useSettingsStore } from "@/stores/settingsStore";
 export function DevicePerformanceSettings() {
   const streamEnabled = useSettingsStore((s) => s.streamEnabled);
   const setStreamEnabled = useSettingsStore((s) => s.setStreamEnabled);
-  const perfMonitoringEnabled = useSettingsStore((s) => s.perfMonitoringEnabled);
-  const setPerfMonitoringEnabled = useSettingsStore((s) => s.setPerfMonitoringEnabled);
   const fastHierarchyEnabled = useSettingsStore((s) => s.fastHierarchyEnabled);
   const setFastHierarchyEnabled = useSettingsStore((s) => s.setFastHierarchyEnabled);
   const webBrowserEnabled = useSettingsStore((s) => s.webBrowserEnabled);
@@ -54,15 +52,6 @@ export function DevicePerformanceSettings() {
         />
       </SettingsSubgroup>
 
-      <SettingsSubgroup title="Monitoring">
-        <ToggleRow
-          label="Enable performance monitoring"
-          description="Adds a performance HUD next to the console."
-          checked={perfMonitoringEnabled}
-          onCheckedChange={setPerfMonitoringEnabled}
-        />
-      </SettingsSubgroup>
-
       <SettingsSubgroup title="Beta targets">
         <ToggleRow
           label={
diff --git a/src/stores/metricsStore.test.ts b/src/stores/metricsStore.test.ts
index 21b5524..dbfb00b 100644
--- a/src/stores/metricsStore.test.ts
+++ b/src/stores/metricsStore.test.ts
@@ -39,23 +39,6 @@ beforeEach(() => {
   useMetricsStore.getState().reset();
 });
 
-describe("metricsStore.togglePanel / setPanelOpen", () => {
-  it("toggle flips panelOpen", () => {
-    const { togglePanel } = useMetricsStore.getState();
-    togglePanel();
-    expect(useMetricsStore.getState().panelOpen).toBe(true);
-    togglePanel();
-    expect(useMetricsStore.getState().panelOpen).toBe(false);
-  });
-
-  it("setPanelOpen sets the value explicitly", () => {
-    useMetricsStore.getState().setPanelOpen(true);
-    expect(useMetricsStore.getState().panelOpen).toBe(true);
-    useMetricsStore.getState().setPanelOpen(false);
-    expect(useMetricsStore.getState().panelOpen).toBe(false);
-  });
-});
-
 describe("metricsStore.appendSample", () => {
   it("appends samples in order", () => {
     const { appendSample } = useMetricsStore.getState();
@@ -90,13 +73,11 @@ describe("metricsStore.onTargetChanged", () => {
 describe("metricsStore.reset", () => {
   it("returns store to initial values", () => {
     const s0 = useMetricsStore.getState();
-    s0.setPanelOpen(true);
     s0.appendSample(mkSample(1));
     s0.onTargetChanged("com.x");
     s0.setStoppedReason("oom");
     s0.reset();
     const s = useMetricsStore.getState();
-    expect(s.panelOpen).toBe(false);
     expect(s.currentPackage).toBeNull();
     expect(s.samples).toEqual([]);
     expect(s.stoppedReason).toBeNull();
diff --git a/src/stores/metricsStore.ts b/src/stores/metricsStore.ts
index 5ac53bc..aa13f2a 100644
--- a/src/stores/metricsStore.ts
+++ b/src/stores/metricsStore.ts
@@ -21,12 +21,9 @@ export interface Sample {
 const MAX_SAMPLES = 60;
 
 interface MetricsState {
-  panelOpen: boolean;
   currentPackage: string | null;
   samples: Sample[];
   stoppedReason: string | null;
-  togglePanel: () => void;
-  setPanelOpen: (v: boolean) => void;
   appendSample: (s: Sample) => void;
   onTargetChanged: (pkg: string) => void;
   setStoppedReason: (r: string | null) => void;
@@ -34,12 +31,9 @@ interface MetricsState {
 }
 
 export const useMetricsStore = create<MetricsState>((set) => ({
-  panelOpen: false,
   currentPackage: null,
   samples: [],
   stoppedReason: null,
-  togglePanel: () => set((s) => ({ panelOpen: !s.panelOpen })),
-  setPanelOpen: (panelOpen) => set({ panelOpen }),
   appendSample: (s) =>
     set((state) => {
       const next = [...state.samples, s];
@@ -50,7 +44,6 @@ export const useMetricsStore = create<MetricsState>((set) => ({
   setStoppedReason: (stoppedReason) => set({ stoppedReason }),
   reset: () =>
     set({
-      panelOpen: false,
       currentPackage: null,
       samples: [],
       stoppedReason: null,
diff --git a/src/stores/panelsStore.test.ts b/src/stores/panelsStore.test.ts
index 55af1de..bcc0efb 100644
--- a/src/stores/panelsStore.test.ts
+++ b/src/stores/panelsStore.test.ts
@@ -26,7 +26,7 @@ beforeEach(() => {
 });
 
 describe("panelsStore", () => {
-  it("defaults all panels to visible", () => {
+  it("defaults panels to visible except the metrics tab", () => {
     const { visible } = usePanelsStore.getState();
     expect(visible).toEqual({
       workspace: true,
@@ -34,7 +34,8 @@ describe("panelsStore", () => {
       device: true,
       editor: true,
       console: true,
-      metrics: true,
+      // The Performance tab is closed by default — opening it starts capture.
+      metrics: false,
     });
   });
 
@@ -64,13 +65,19 @@ describe("panelsStore", () => {
     expect(v.console).toBe(true);
   });
 
-  it("showAll restores every panel", () => {
+  it("showAll restores every panel except the metrics tab", () => {
     const s = usePanelsStore.getState();
     s.hide("workspace");
     s.hide("inspector");
     s.hide("device");
     s.showAll();
     const v = usePanelsStore.getState().visible;
-    expect(Object.values(v).every(Boolean)).toBe(true);
+    expect(v.workspace).toBe(true);
+    expect(v.inspector).toBe(true);
+    expect(v.device).toBe(true);
+    expect(v.editor).toBe(true);
+    expect(v.console).toBe(true);
+    // Restoring panels shouldn't silently start metric capture.
+    expect(v.metrics).toBe(false);
   });
 });
diff --git a/src/stores/panelsStore.ts b/src/stores/panelsStore.ts
index 32f1b2a..3a0a548 100644
--- a/src/stores/panelsStore.ts
+++ b/src/stores/panelsStore.ts
@@ -33,10 +33,9 @@ export const usePanelsStore = create<PanelsState>()(
         device: true,
         editor: true,
         console: true,
-        // Metrics is still gated by the global perfMonitoringEnabled
-        // setting; this flag just decides whether the pane is shown
-        // when perf monitoring *is* enabled.
-        metrics: true,
+        // Performance tab is closed by default — opening it is what starts
+        // metric capture (see App.tsx). It does not auto-capture on launch.
+        metrics: false,
       },
       toggle: (id) =>
         set((s) => ({
@@ -58,7 +57,7 @@ export const usePanelsStore = create<PanelsState>()(
             device: true,
             editor: true,
             console: true,
-            metrics: true,
+            metrics: false,
           },
         })),
     }),
diff --git a/src/stores/settingsStore.test.ts b/src/stores/settingsStore.test.ts
index afa3b74..e0a56b1 100644
--- a/src/stores/settingsStore.test.ts
+++ b/src/stores/settingsStore.test.ts
@@ -29,7 +29,6 @@ beforeEach(() => {
     showFps: INITIAL.showFps,
     theme: "system",
     streamEnabled: true,
-    perfMonitoringEnabled: false,
     fastHierarchyEnabled: false,
     autoSaveEnabled: true,
     consoleMode: "simple",
@@ -43,7 +42,6 @@ describe("settingsStore defaults", () => {
     expect(s.inspectKey).toBe("i");
     expect(s.theme).toBe("system");
     expect(s.streamEnabled).toBe(true);
-    expect(s.perfMonitoringEnabled).toBe(false);
     expect(s.fastHierarchyEnabled).toBe(false);
     expect(s.autoSaveEnabled).toBe(true);
     expect(s.consoleMode).toBe("simple");
@@ -74,15 +72,13 @@ describe("settingsStore setters", () => {
     }
   });
 
-  it("setStreamEnabled / setPerfMonitoringEnabled / setFastHierarchyEnabled / setAutoSaveEnabled toggle their flags", () => {
+  it("setStreamEnabled / setFastHierarchyEnabled / setAutoSaveEnabled toggle their flags", () => {
     const s = useSettingsStore.getState();
     s.setStreamEnabled(false);
-    s.setPerfMonitoringEnabled(true);
     s.setFastHierarchyEnabled(true);
     s.setAutoSaveEnabled(false);
     const after = useSettingsStore.getState();
     expect(after.streamEnabled).toBe(false);
-    expect(after.perfMonitoringEnabled).toBe(true);
     expect(after.fastHierarchyEnabled).toBe(true);
     expect(after.autoSaveEnabled).toBe(false);
   });
diff --git a/src/stores/settingsStore.ts b/src/stores/settingsStore.ts
index af76490..2dea54d 100644
--- a/src/stores/settingsStore.ts
+++ b/src/stores/settingsStore.ts
@@ -12,7 +12,6 @@ interface SettingsState {
   showFps: boolean;
   theme: ThemeMode;
   streamEnabled: boolean;
-  perfMonitoringEnabled: boolean;
   /**
    * When enabled, inspect mode spawns `maestro studio` once at startup
    * (slow: 10-15s) and then fetches the hierarchy over direct gRPC on
@@ -47,7 +46,6 @@ interface SettingsState {
   setShowFps: (v: boolean) => void;
   setTheme: (t: ThemeMode) => void;
   setStreamEnabled: (v: boolean) => void;
-  setPerfMonitoringEnabled: (v: boolean) => void;
   setFastHierarchyEnabled: (v: boolean) => void;
   setAutoSaveEnabled: (v: boolean) => void;
   setAutoCheckUpdatesEnabled: (v: boolean) => void;
@@ -64,7 +62,6 @@ export const useSettingsStore = create<SettingsState>()(
       showFps: false,
       theme: "system",
       streamEnabled: true,
-      perfMonitoringEnabled: false,
       fastHierarchyEnabled: false,
       autoSaveEnabled: true,
       autoCheckUpdatesEnabled: true,
@@ -76,7 +73,6 @@ export const useSettingsStore = create<SettingsState>()(
       setShowFps: (showFps) => set({ showFps }),
       setTheme: (theme) => set({ theme }),
       setStreamEnabled: (streamEnabled) => set({ streamEnabled }),
-      setPerfMonitoringEnabled: (perfMonitoringEnabled) => set({ perfMonitoringEnabled }),
       setFastHierarchyEnabled: (fastHierarchyEnabled) => set({ fastHierarchyEnabled }),
       setAutoSaveEnabled: (autoSaveEnabled) => set({ autoSaveEnabled }),
       setAutoCheckUpdatesEnabled: (autoCheckUpdatesEnabled) => set({ autoCheckUpdatesEnabled }),
@@ -92,7 +88,6 @@ export const useSettingsStore = create<SettingsState>()(
         inspectKey: s.inspectKey,
         theme: s.theme,
         streamEnabled: s.streamEnabled,
-        perfMonitoringEnabled: s.perfMonitoringEnabled,
         fastHierarchyEnabled: s.fastHierarchyEnabled,
         autoSaveEnabled: s.autoSaveEnabled,
         autoCheckUpdatesEnabled: s.autoCheckUpdatesEnabled,

From 86b6a53191560c4ec8459e9c3e398080f3398163 Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Sun, 28 Jun 2026 14:14:52 +0200
Subject: [PATCH 10/18] fix(metrics): force Performance panel closed on
 upgrade; tidy toggle title

Add persist version:1 + migrate to panelsStore so that upgrading users
with metrics:true in localStorage have it forced to false exactly once,
honouring the closed-by-default / opening-starts-capture design intent.
Export migratePanelsStore for direct unit-test coverage (3 new tests).
Update RunConsole toggle title from "Toggle performance HUD" to
"Toggle performance panel" to match the visible label.
---
 src/components/RunConsole.tsx  |  2 +-
 src/stores/panelsStore.test.ts | 41 +++++++++++++++++++++++++++++++++-
 src/stores/panelsStore.ts      | 22 ++++++++++++++++++
 3 files changed, 63 insertions(+), 2 deletions(-)

diff --git a/src/components/RunConsole.tsx b/src/components/RunConsole.tsx
index 8315bc9..4ad3c45 100644
--- a/src/components/RunConsole.tsx
+++ b/src/components/RunConsole.tsx
@@ -94,7 +94,7 @@ export function RunConsole({ onRun, onStop }: { onRun: () => void; onStop: () =>
             size="xs"
             variant={metricsOpen ? "default" : "ghost"}
             onClick={() => toggleMetrics("metrics")}
-            title="Toggle performance HUD"
+            title="Toggle performance panel"
           >
             <Activity className="h-3 w-3" />
             Performance
diff --git a/src/stores/panelsStore.test.ts b/src/stores/panelsStore.test.ts
index bcc0efb..6c93a69 100644
--- a/src/stores/panelsStore.test.ts
+++ b/src/stores/panelsStore.test.ts
@@ -19,7 +19,7 @@ vi.hoisted(() => {
   } as Storage;
 });
 
-import { usePanelsStore } from "./panelsStore";
+import { usePanelsStore, migratePanelsStore } from "./panelsStore";
 
 beforeEach(() => {
   usePanelsStore.getState().showAll();
@@ -65,6 +65,45 @@ describe("panelsStore", () => {
     expect(v.console).toBe(true);
   });
 
+  it("migratePanelsStore v0→v1 forces metrics:false even when persisted as true", () => {
+    const persisted = {
+      visible: {
+        workspace: true,
+        inspector: true,
+        device: true,
+        editor: true,
+        console: true,
+        metrics: true, // old persisted value from before the closed-by-default change
+      },
+    };
+    const result = migratePanelsStore(persisted, 0) as {
+      visible: Record<string, boolean>;
+    };
+    expect(result.visible.metrics).toBe(false);
+    // Other flags must be preserved
+    expect(result.visible.workspace).toBe(true);
+    expect(result.visible.inspector).toBe(true);
+    expect(result.visible.device).toBe(true);
+    expect(result.visible.editor).toBe(true);
+    expect(result.visible.console).toBe(true);
+  });
+
+  it("migratePanelsStore v0→v1 tolerates missing visible object", () => {
+    const result = migratePanelsStore(null, 0) as {
+      visible: Record<string, boolean>;
+    };
+    expect(result.visible.metrics).toBe(false);
+  });
+
+  it("migratePanelsStore is a no-op for current version (fromVersion >= 1)", () => {
+    const persisted = {
+      visible: { workspace: false, metrics: true },
+    };
+    const result = migratePanelsStore(persisted, 1);
+    // Must return the persisted value unchanged
+    expect(result).toBe(persisted);
+  });
+
   it("showAll restores every panel except the metrics tab", () => {
     const s = usePanelsStore.getState();
     s.hide("workspace");
diff --git a/src/stores/panelsStore.ts b/src/stores/panelsStore.ts
index 3a0a548..91ff5d4 100644
--- a/src/stores/panelsStore.ts
+++ b/src/stores/panelsStore.ts
@@ -4,6 +4,26 @@
 import { create } from "zustand";
 import { createJSONStorage, persist } from "zustand/middleware";
 
+/**
+ * Zustand persist migration — exported for unit-test coverage.
+ *
+ * v0 → v1: Force `visible.metrics` to `false`.
+ * Old builds defaulted metrics to `true`; upgrade must honour the new
+ * "closed-by-default / opening starts capture" design without clobbering
+ * the user's other panel visibility preferences.
+ */
+export function migratePanelsStore(persisted: unknown, fromVersion: number): unknown {
+  if (fromVersion < 1) {
+    const state = persisted as Record<string, unknown> | null | undefined;
+    const visible = (state?.visible ?? {}) as Record<string, unknown>;
+    return {
+      ...state,
+      visible: { ...visible, metrics: false },
+    };
+  }
+  return persisted;
+}
+
 /**
  * Which panels are visible in the main layout. Hidden panels collapse
  * to zero size in the `PanelGroup` — their sibling(s) absorb the space.
@@ -64,6 +84,8 @@ export const usePanelsStore = create<PanelsState>()(
     {
       name: "maestro-deck.panels",
       storage: createJSONStorage(() => localStorage),
+      version: 1,
+      migrate: migratePanelsStore,
     },
   ),
 );

From 66f41a2c88ecfb8241fbd854d933b96dc9f4bd40 Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Sun, 28 Jun 2026 14:18:58 +0200
Subject: [PATCH 11/18] feat(metrics): device-aware Performance cards
 (percentiles, thermal, ios/web states)

---
 src/components/MetricsPanel.tsx | 122 +++++++++++++++++++++++---------
 src/lib/metricsCards.test.ts    |  44 ++++++++++++
 src/lib/metricsCards.ts         |  48 +++++++++++++
 3 files changed, 182 insertions(+), 32 deletions(-)
 create mode 100644 src/lib/metricsCards.test.ts
 create mode 100644 src/lib/metricsCards.ts

diff --git a/src/components/MetricsPanel.tsx b/src/components/MetricsPanel.tsx
index cb4ec8f..e5dd9c2 100644
--- a/src/components/MetricsPanel.tsx
+++ b/src/components/MetricsPanel.tsx
@@ -6,6 +6,7 @@ import { X } from "lucide-react";
 import { Button } from "@/components/ui/Button";
 import { MetricsSparkline } from "@/components/MetricsSparkline";
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/Tooltip";
+import { metricsForDevice, thermalLabel, type MetricCardId } from "@/lib/metricsCards";
 import { useDeviceStore } from "@/stores/deviceStore";
 import { useMetricsStore } from "@/stores/metricsStore";
 import { usePanelsStore } from "@/stores/panelsStore";
@@ -18,6 +19,7 @@ export function MetricsPanel() {
   const device = useDeviceStore((s) => s.current);
 
   const last = samples[samples.length - 1];
+  const layout = device ? metricsForDevice(device.platform, device.physical) : null;
 
   return (
     <section className="flex h-full min-h-0 w-full flex-col border-l border-border bg-muted/30">
@@ -39,43 +41,23 @@ export function MetricsPanel() {
       </header>
 
       <div className="min-h-0 flex-1 overflow-auto px-3 py-2 text-[11px]">
-        {!device ? (
+        {!device || !layout ? (
           <div className="text-muted-foreground">Connect a device to monitor performance.</div>
-        ) : stopped ? (
+        ) : layout.kind === "limited" ? (
+          <div className="text-muted-foreground">{layout.message}</div>
+        ) : stopped && stopped !== "unsupported" ? (
           <div className="text-red-600 dark:text-red-400">Monitoring stopped ({stopped}).</div>
         ) : samples.length === 0 ? (
           <div className="text-muted-foreground">Waiting for samples…</div>
         ) : (
           <TooltipProvider delayDuration={300}>
             <div className="space-y-3">
-              <Card
-                label="CPU"
-                value={last?.cpuPct.toFixed(1) ?? "—"}
-                unit="%"
-                series={samples.map((s) => s.cpuPct)}
-                tooltip="CPU time consumed by the app process. 100% means one core is fully saturated; values above 100% mean multiple cores are in use. Read from /proc/<pid>/stat on the device."
-              />
-              <Card
-                label="RAM"
-                value={last?.memMb.toFixed(0) ?? "—"}
-                unit="MB"
-                series={samples.map((s) => s.memMb)}
-                tooltip="Resident memory (VmRSS) used by the app process on the device. Includes shared system libraries, so it slightly overstates the app's exclusive memory usage."
-              />
-              <Card
-                label="FPS"
-                value={last?.fps != null ? last.fps.toFixed(0) : "—"}
-                unit=""
-                series={samples.map((s) => s.fps)}
-                tooltip="Frames per second rendered by the app's UI, averaged over the last 5 seconds. An idle app stays near 0 (nothing to redraw). Read from `dumpsys gfxinfo`."
-              />
-              <Card
-                label="Jank"
-                value={last?.jankPct != null ? last.jankPct.toFixed(1) : "—"}
-                unit="%"
-                series={samples.map((s) => s.jankPct)}
-                tooltip="Percentage of frames that missed the 16.67 ms deadline (60 FPS target). Under 5% feels smooth; over 10% is visible lag. This is the best indicator of perceived smoothness."
-              />
+              {layout.cards.map((id) => (
+                <MetricCard key={id} id={id} samples={samples} last={last} />
+              ))}
+              {layout.note ? (
+                <div className="pt-1 text-[10px] text-muted-foreground">{layout.note}</div>
+              ) : null}
             </div>
           </TooltipProvider>
         )}
@@ -84,6 +66,82 @@ export function MetricsPanel() {
   );
 }
 
+function MetricCard({
+  id,
+  samples,
+  last,
+}: {
+  id: MetricCardId;
+  samples: import("@/stores/metricsStore").Sample[];
+  last: import("@/stores/metricsStore").Sample | undefined;
+}) {
+  switch (id) {
+    case "cpu":
+      return (
+        <Card
+          label="CPU"
+          value={last?.cpuPct.toFixed(1) ?? "—"}
+          unit="%"
+          series={samples.map((s) => s.cpuPct)}
+          tooltip="CPU time consumed by the app process. 100% = one core saturated."
+        />
+      );
+    case "ram":
+      return (
+        <Card
+          label="RAM"
+          value={last?.memMb.toFixed(0) ?? "—"}
+          unit="MB"
+          series={samples.map((s) => s.memMb)}
+          tooltip="Resident memory (RSS) used by the app process."
+        />
+      );
+    case "fps":
+      return (
+        <Card
+          label="FPS"
+          value={last?.fps != null ? last.fps.toFixed(0) : "—"}
+          unit=""
+          series={samples.map((s) => s.fps)}
+          tooltip="Frames per second over the last 5s. Idle apps stay near 0. From dumpsys gfxinfo."
+        />
+      );
+    case "jank":
+      return (
+        <Card
+          label="Jank"
+          value={last?.jankPct != null ? last.jankPct.toFixed(1) : "—"}
+          unit="%"
+          series={samples.map((s) => s.jankPct)}
+          tooltip="Percent of frames missing the 16.67ms deadline. <5% feels smooth."
+        />
+      );
+    case "frameTimes":
+      return (
+        <Card
+          label="Frame time (p95)"
+          value={last?.frameP95 != null ? last.frameP95.toFixed(0) : "—"}
+          unit="ms"
+          series={samples.map((s) => s.frameP95)}
+          tooltip={`Per-frame render time percentiles (ms). Latest — p50: ${fmt(last?.frameP50)}, p90: ${fmt(last?.frameP90)}, p95: ${fmt(last?.frameP95)}, p99: ${fmt(last?.frameP99)}. Lower is smoother; watch p95/p99 for hitches.`}
+        />
+      );
+    case "thermal":
+      return (
+        <Card
+          label="Thermal"
+          value={thermalLabel(last?.thermalStatus ?? null)}
+          unit=""
+          tooltip="Device thermal throttling state (dumpsys thermalservice). Anything above 'None' will depress CPU/GPU and skew other metrics."
+        />
+      );
+  }
+}
+
+function fmt(v: number | null | undefined): string {
+  return v != null ? v.toFixed(0) : "—";
+}
+
 function Card({
   label,
   value,
@@ -94,7 +152,7 @@ function Card({
   label: string;
   value: string;
   unit: string;
-  series: (number | null)[];
+  series?: (number | null)[];
   tooltip: string;
 }) {
   return (
@@ -109,7 +167,7 @@ function Card({
               {value} <span className="text-[10px] text-muted-foreground">{unit}</span>
             </span>
           </div>
-          <MetricsSparkline values={series} className="text-foreground/60" />
+          {series ? <MetricsSparkline values={series} className="text-foreground/60" /> : null}
         </div>
       </TooltipTrigger>
       <TooltipContent side="left" className="max-w-[260px] text-[11px] leading-snug">
diff --git a/src/lib/metricsCards.test.ts b/src/lib/metricsCards.test.ts
new file mode 100644
index 0000000..e09cf8f
--- /dev/null
+++ b/src/lib/metricsCards.test.ts
@@ -0,0 +1,44 @@
+// Copyright (c) 2026 Ethan Morisset
+// SPDX-License-Identifier: BUSL-1.1
+
+import { describe, it, expect } from "vitest";
+
+import { metricsForDevice, thermalLabel } from "./metricsCards";
+
+describe("metricsForDevice", () => {
+  it("android shows the full card set", () => {
+    const r = metricsForDevice("android", false);
+    expect(r.kind).toBe("cards");
+    if (r.kind === "cards") {
+      expect(r.cards).toEqual(["cpu", "ram", "fps", "jank", "frameTimes", "thermal"]);
+    }
+  });
+
+  it("ios simulator shows cpu/ram with a note", () => {
+    const r = metricsForDevice("ios", false);
+    expect(r.kind).toBe("cards");
+    if (r.kind === "cards") {
+      expect(r.cards).toEqual(["cpu", "ram"]);
+      expect(r.note).toBeTruthy();
+    }
+  });
+
+  it("ios physical is limited", () => {
+    expect(metricsForDevice("ios", true).kind).toBe("limited");
+  });
+
+  it("web is limited", () => {
+    expect(metricsForDevice("web", false).kind).toBe("limited");
+  });
+});
+
+describe("thermalLabel", () => {
+  it("maps known codes", () => {
+    expect(thermalLabel(0)).toBe("None");
+    expect(thermalLabel(3)).toBe("Severe");
+  });
+  it("handles null/unknown", () => {
+    expect(thermalLabel(null)).toBe("—");
+    expect(thermalLabel(42)).toBe("Unknown");
+  });
+});
diff --git a/src/lib/metricsCards.ts b/src/lib/metricsCards.ts
new file mode 100644
index 0000000..95a689d
--- /dev/null
+++ b/src/lib/metricsCards.ts
@@ -0,0 +1,48 @@
+// Copyright (c) 2026 Ethan Morisset
+// SPDX-License-Identifier: BUSL-1.1
+
+export type MetricCardId = "cpu" | "ram" | "fps" | "jank" | "frameTimes" | "thermal";
+
+export type DevicePlatform = "android" | "ios" | "web";
+
+export type MetricsLayout =
+  | { kind: "cards"; cards: MetricCardId[]; note?: string }
+  | { kind: "limited"; message: string };
+
+/** Which metric cards a device can provide, or a "limited support" message. */
+export function metricsForDevice(platform: DevicePlatform, physical: boolean): MetricsLayout {
+  if (platform === "android") {
+    return { kind: "cards", cards: ["cpu", "ram", "fps", "jank", "frameTimes", "thermal"] };
+  }
+  if (platform === "ios" && !physical) {
+    return {
+      kind: "cards",
+      cards: ["cpu", "ram"],
+      note: "FPS and frame timing aren't available on the iOS simulator.",
+    };
+  }
+  if (platform === "ios" && physical) {
+    return {
+      kind: "limited",
+      message:
+        "Per-app performance metrics aren't available on physical iPhones — they require Instruments.",
+    };
+  }
+  return { kind: "limited", message: "The Web target has no per-app performance metrics." };
+}
+
+const THERMAL_LABELS: Record<number, string> = {
+  0: "None",
+  1: "Light",
+  2: "Moderate",
+  3: "Severe",
+  4: "Critical",
+  5: "Emergency",
+  6: "Shutdown",
+};
+
+/** Map an Android THERMAL_STATUS_* code to a label. */
+export function thermalLabel(code: number | null): string {
+  if (code == null) return "—";
+  return THERMAL_LABELS[code] ?? "Unknown";
+}

From b67bda9024d14214216945d866d0763e04993704 Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Sun, 28 Jun 2026 14:34:11 +0200
Subject: [PATCH 12/18] fix(metrics): restart capture on device switch; harden
 ios-sim loop
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Replace deviceConnected with deviceKey (serial:platform:physical) in
  the metrics capture effect so a direct A→B device switch re-runs the
  effect, stopping the old collector and clearing stale samples before
  the new one starts — prevents misattributed data.

- Guard run_loop / run_loop_ios_sim self-clear against stop()→start()
  race: track exit_by_cancel and skip the tokio::spawn self-clear on
  cancel exits, since stop() already .take()s the RUNNING slot.

- Distinguish Ok(None) from Err(e) in ios-sim cpu_mem match: errors
  now increment consecutive_errors and trigger MAX_CONSECUTIVE_ERRORS
  bail with emit_stopped, matching the pid-resolution path.
---
 src-tauri/src/metrics/mod.rs | 47 +++++++++++++++++++++++++-----------
 src/App.tsx                  | 17 ++++++++++---
 2 files changed, 47 insertions(+), 17 deletions(-)

diff --git a/src-tauri/src/metrics/mod.rs b/src-tauri/src/metrics/mod.rs
index 87c9f59..467642e 100644
--- a/src-tauri/src/metrics/mod.rs
+++ b/src-tauri/src/metrics/mod.rs
@@ -124,12 +124,18 @@ async fn run_loop(app: AppHandle, serial: String, mut cancel: oneshot::Receiver<
     let mut last_fg_check = Instant::now() - FOREGROUND_CHECK_INTERVAL;
     let mut last_gfx_poll = Instant::now() - GFX_INTERVAL;
     let mut consecutive_errors: u32 = 0;
+    // Track whether exit was triggered by stop() so we can skip the self-clear.
+    // stop() already .take()s the RUNNING slot before signalling, so there is
+    // nothing left to clear for cancel exits; only self-exits (error bailout)
+    // need to null the slot.
+    let mut exit_by_cancel = false;
     let mut ticker = tokio::time::interval(TICK_INTERVAL);
     ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
 
     loop {
         tokio::select! {
             _ = &mut cancel => {
+                exit_by_cancel = true;
                 emit_stopped(&app, "user", None);
                 break;
             }
@@ -268,16 +274,14 @@ async fn run_loop(app: AppHandle, serial: String, mut cancel: oneshot::Receiver<
     }
 
     info!("metrics task exited");
-    // Self-clear the RUNNING slot when the task exits without an explicit
-    // stop() — e.g. on error bailout. We spawn this because we cannot await
-    // the mutex from inside the task's own body without risking reentrancy
-    // if stop() is concurrently holding the lock.
-    tokio::spawn(async {
-        let mut guard = RUNNING.lock().await;
-        // If stop() already took the slot (normal shutdown), nothing to do.
-        // Otherwise clear so a new start() can proceed.
-        *guard = None;
-    });
+    // Only self-clear on error/self-exit. When stop() was called it already
+    // .take()d the slot before signalling; self-clearing after a cancel exit
+    // would race with a subsequent start() that put a new task in the slot.
+    if !exit_by_cancel {
+        tokio::spawn(async {
+            *RUNNING.lock().await = None;
+        });
+    }
 }
 
 /// iOS-simulator polling loop. A simulated app runs as a host macOS process, so
@@ -286,12 +290,15 @@ async fn run_loop(app: AppHandle, serial: String, mut cancel: oneshot::Receiver<
 /// net) are unavailable on this path and ship as `None`/`0.0`.
 async fn run_loop_ios_sim(app: AppHandle, udid: String, mut cancel: oneshot::Receiver<()>) {
     let mut consecutive_errors: u32 = 0;
+    // See run_loop for rationale: skip self-clear when exiting via stop() cancel.
+    let mut exit_by_cancel = false;
     let mut ticker = tokio::time::interval(TICK_INTERVAL);
     ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
 
     loop {
         tokio::select! {
             _ = &mut cancel => {
+                exit_by_cancel = true;
                 emit_stopped(&app, "user", None);
                 break;
             }
@@ -324,7 +331,17 @@ async fn run_loop_ios_sim(app: AppHandle, udid: String, mut cancel: oneshot::Rec
             .unwrap_or_else(|e| Err(AppError::MetricsFailed(format!("ios ps join failed: {e}"))));
         let (cpu_pct, mem_mb) = match cpu_mem {
             Ok(Some(v)) => v,
-            _ => continue,
+            // Process exited between pid resolution and ps — benign, try again.
+            Ok(None) => continue,
+            Err(e) => {
+                warn!(error = ?e, "ios cpu_mem fetch failed");
+                consecutive_errors += 1;
+                if consecutive_errors >= MAX_CONSECUTIVE_ERRORS {
+                    emit_stopped(&app, "error", Some(e.to_string()));
+                    break;
+                }
+                continue;
+            }
         };
         consecutive_errors = 0;
 
@@ -347,9 +364,11 @@ async fn run_loop_ios_sim(app: AppHandle, udid: String, mut cancel: oneshot::Rec
     }
 
     info!("ios-sim metrics task exited");
-    tokio::spawn(async {
-        *RUNNING.lock().await = None;
-    });
+    if !exit_by_cancel {
+        tokio::spawn(async {
+            *RUNNING.lock().await = None;
+        });
+    }
 }
 
 fn emit_stopped(app: &AppHandle, reason: &'static str, message: Option<String>) {
diff --git a/src/App.tsx b/src/App.tsx
index 8f20083..ad0a53e 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -209,13 +209,24 @@ export default function App() {
   }, []);
 
   const metricsOpen = usePanelsStore((s) => s.visible.metrics);
-  const deviceConnected = useDeviceStore((s) => Boolean(s.current));
+  // Use device identity (serial + platform + physical) rather than mere presence
+  // so that a direct A→B switch (where deviceConnected stays true) still causes
+  // the effect to re-run, stopping the old collector and starting a new one for
+  // the correct device.
+  const deviceKey = useDeviceStore((s) =>
+    s.current
+      ? `${s.current.serial}:${s.current.platform}:${String(s.current.physical)}`
+      : null,
+  );
 
   useEffect(() => {
-    if (!metricsOpen || !deviceConnected) {
+    if (!metricsOpen || !deviceKey) {
       void ipc.stopMetrics().catch(() => {});
       return;
     }
+    // Clear any stale samples/package from a previous device so nothing is
+    // misattributed while we wait for the new collector's first sample.
+    useMetricsStore.getState().reset();
     void ipc.startMetrics().catch((err) => {
       toast.error(
         "Performance monitoring failed to start",
@@ -225,7 +236,7 @@ export default function App() {
     return () => {
       void ipc.stopMetrics().catch(() => {});
     };
-  }, [metricsOpen, deviceConnected]);
+  }, [metricsOpen, deviceKey]);
 
   return (
     <>

From 2e2020e5be4fecb7630dcaf8b04d9acb2bf76ea5 Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Sun, 28 Jun 2026 14:39:39 +0200
Subject: [PATCH 13/18] fix(metrics): start() replaces a running collector to
 avoid device-switch race

---
 src-tauri/src/error.rs       |  3 ---
 src-tauri/src/metrics/mod.rs | 11 +++++++++--
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/src-tauri/src/error.rs b/src-tauri/src/error.rs
index f1dd6b6..ecf3d98 100644
--- a/src-tauri/src/error.rs
+++ b/src-tauri/src/error.rs
@@ -45,9 +45,6 @@ pub enum AppError {
     #[error("Performance metrics collection failed: {0}")]
     MetricsFailed(String),
 
-    #[error("Performance metrics already running")]
-    MetricsAlreadyRunning,
-
     #[error("iOS tooling missing: {0}")]
     IosToolMissing(String),
 
diff --git a/src-tauri/src/metrics/mod.rs b/src-tauri/src/metrics/mod.rs
index 467642e..262dc99 100644
--- a/src-tauri/src/metrics/mod.rs
+++ b/src-tauri/src/metrics/mod.rs
@@ -71,8 +71,15 @@ pub struct StoppedReason {
 pub async fn start(app: AppHandle, device: crate::device::Device) -> AppResult<()> {
     use crate::device::Platform;
     let mut guard = RUNNING.lock().await;
-    if guard.is_some() {
-        return Err(AppError::MetricsAlreadyRunning);
+    // Replace any running collector. On a device switch the frontend can call
+    // start() before the previous stop()'s join has completed, so reject-if-
+    // running would spuriously fail. Cancel + join the predecessor while
+    // holding the lock so there is no overlap. Safe from deadlock: a cancelled
+    // loop exits via the cancel arm and does NOT self-clear RUNNING (see
+    // exit_by_cancel), so it never tries to lock RUNNING during this join.
+    if let Some((tx, join)) = guard.take() {
+        let _ = tx.send(());
+        let _ = join.await;
     }
     match (device.platform, device.physical) {
         (Platform::Android, _) => {

From 821073704117b0bab9b1102846ee1f3de0c3b259 Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Mon, 29 Jun 2026 00:18:31 +0200
Subject: [PATCH 14/18] =?UTF-8?q?docs:=20design=20banque=20de=20screenshot?=
 =?UTF-8?q?s=20&=20d=C3=A9tection=20de=20r=C3=A9gression=20visuelle?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...06-29-screenshot-bank-regression-design.md | 199 ++++++++++++++++++
 1 file changed, 199 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-29-screenshot-bank-regression-design.md

diff --git a/docs/superpowers/specs/2026-06-29-screenshot-bank-regression-design.md b/docs/superpowers/specs/2026-06-29-screenshot-bank-regression-design.md
new file mode 100644
index 0000000..d314acc
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-29-screenshot-bank-regression-design.md
@@ -0,0 +1,199 @@
+# Banque de screenshots & détection de régression visuelle — Design
+
+**Date :** 2026-06-29
+**Statut :** Design (premier jet, local uniquement)
+**Portée :** Maestro Deck, fonctionnalité locale (pas de cloud/sync pour l'instant)
+
+## Objectif
+
+Éviter les régressions visuelles utilisateur entre deux exécutions d'un flow Maestro.
+Le principe : maintenir une **banque de screenshots de référence** (la « vérité ») par
+device, et à chaque run comparer pixel par pixel les nouveaux screenshots à cette
+référence. Toute divergence significative est signalée comme **régression** et soumise à
+la revue de l'utilisateur, qui décide de garder la référence ou de la remplacer.
+
+## Décisions clés (verrouillées)
+
+| Sujet | Décision |
+|-------|----------|
+| Source des screenshots | Commandes `takeScreenshot: <nom>` du flow YAML ; `<nom>` = clé de matching |
+| Algorithme de diff | Pixelmatch-like : seuil % de pixels changés + tolérance couleur par pixel |
+| Masques / zones ignorées | **Hors scope v1** (prévu v2) |
+| Sémantique du refus | Garder la banque = **régression détectée** (signal d'alerte) ; banque inchangée |
+| Sémantique de l'acceptation | Remplacer = la nouvelle capture devient la vérité (écrase la banque) |
+| Portée | **Tout** run d'un flow (single + Run All) |
+| Clé de banque | `<model>_<W>x<H>` (modèle + résolution, sanitizé) |
+| Emplacement | `<workspace>/maestro/bank/<key>/` (créer `bank/` si `maestro/` existe déjà) |
+| Récupération PNG | Non invasif : CWD du runner = **dossier du flow** ; collecte des `<nom>.png` sur place |
+| Implémentation diff | **Rust** (crate `image`), le front ne reçoit que verdicts + chemins |
+| Banque vide (1er run) | Seed : tous les screenshots deviennent la référence, sans revue |
+
+## Architecture
+
+```
+Run flow (single ou Run All)
+        │
+        ▼
+[Rust] run_flow : CWD du runner = dossier du flow
+        │
+        ▼
+Maestro exécute, écrit <nom>.png à côté du flow
+        │
+   runner:exit
+        │
+        ▼
+[Rust] Comparateur de banque
+   ├─ parse YAML → liste des noms takeScreenshot attendus
+   ├─ résout clé device = <model>_<W>x<H>
+   ├─ pour chaque <nom>.png :
+   │     ├─ pas de baseline → Seed (copie dans bank/)
+   │     ├─ dimensions ≠   → DimensionMismatch (flag)
+   │     ├─ diff > seuil    → Changed (flag + diff.png + bbox)
+   │     ├─ diff ≤ seuil    → Match
+   │     └─ attendu absent  → Missing (flag)
+   └─ écrit maestro/.runs/<run_id>/report.json
+        │
+        ▼ (event screenshot:report)
+[Front] Panneau de revue (si ≥1 Changed/Missing/DimensionMismatch)
+   ├─ Gauche : banque (vérité) | Droite : nouvelle + bbox encadrée
+   ├─ Toggle overlay diff (rouge)
+   └─ Action : « Garder la banque » | « Remplacer par la nouvelle »
+        │
+        ▼
+[Rust] resolve_comparison(name, decision)
+   ├─ Keep    → enregistre régression dans report.json
+   └─ Replace → écrase bank/<key>/<nom>.png
+```
+
+## Composants
+
+### 1. Stockage de la banque
+
+```
+<workspace>/maestro/
+├── bank/
+│   └── <model>_<W>x<H>/          ex: iPhone15_1179x2556/
+│       ├── .bank.json            { key, model, width, height, created_at }
+│       ├── login.png
+│       └── home.png
+└── .runs/
+    └── <run_id>/
+        ├── report.json           rapport de comparaison du run
+        └── diffs/<nom>.png       images de diff générées (overlay rouge)
+```
+
+- Clé device = `sanitize(Device.model) + "_" + width + "x" + height`. Sanitize :
+  espaces, `/`, et caractères non-alphanumériques → `_`.
+- `<nom>` provient de l'argument `takeScreenshot:` (string simple ou champ `path:`).
+- Création paresseuse : `mkdir -p` de `maestro/bank/<key>/` au besoin (ne touche pas à
+  un `maestro/` existant au-delà d'y ajouter `bank/`).
+
+### 2. Pipeline de capture (Rust, runner)
+
+- `run_flow` fixe `Command.current_dir(<dossier du fichier flow>)` pour les variantes du
+  runner (android, ios-sim, ios-device, web). C'est la convention Maestro standard ; les
+  chemins relatifs des flows sont résolus correctement et les `takeScreenshot` atterrissent
+  à côté du flow de façon déterministe.
+- Parse du YAML du flow pour extraire la **liste ordonnée des noms** `takeScreenshot`
+  (sert au matching et à détecter un `Missing`).
+- Au `runner:exit` (code 0 ou non), collecte des `<nom>.png` attendus dans le dossier du
+  flow.
+
+### 3. Moteur de comparaison (Rust, nouveau module `src-tauri/src/bank/`)
+
+- Décodage PNG via la crate `image`.
+- Diff pixelmatch-like :
+  - Si dimensions ≠ → `DimensionMismatch` immédiat.
+  - Sinon, pour chaque pixel : distance couleur (YIQ ou euclidienne RGBA) au-delà d'une
+    **tolérance** → pixel compté comme changé.
+  - `changed_ratio = pixels_changés / total`. Si `changed_ratio > seuil` → `Changed`.
+  - Génère `diffs/<nom>.png` (overlay rouge sur les pixels changés) et le **bounding box**
+    englobant (x, y, w, h) pour l'encadré UI.
+- Seuils par défaut configurables (constantes v1, settings plus tard) :
+  - tolérance couleur ≈ 0.1 (échelle pixelmatch)
+  - seuil ratio ≈ 0.001 (0.1 % des pixels)
+
+### 4. Modèle de résultat
+
+```rust
+enum ComparisonStatus { Seeded, Match, Changed, Missing, DimensionMismatch }
+
+struct ScreenshotComparison {
+    name: String,
+    status: ComparisonStatus,
+    bank_path: Option<String>,
+    new_path: Option<String>,
+    diff_path: Option<String>,
+    changed_ratio: f32,
+    bbox: Option<[u32; 4]>,        // x, y, w, h
+}
+
+struct RunReport {
+    run_id: String,
+    flow_path: String,
+    device_key: String,
+    comparisons: Vec<ScreenshotComparison>,
+    regressions: Vec<String>,     // noms gardés en banque (régression confirmée)
+}
+```
+
+- Émis vers le front via un event Tauri (`screenshot:report`) en fin de run.
+- Persisté dans `maestro/.runs/<run_id>/report.json` pour la traçabilité.
+
+### 5. UI de revue (front React)
+
+- Nouveau composant `ScreenshotReview` ouvert en fin de run **si** ≥1 statut
+  `Changed | Missing | DimensionMismatch`.
+- File d'attente si plusieurs : un screenshot à la fois.
+- Layout :
+  - **Gauche** : image de la banque (la vérité).
+  - **Droite** : nouvelle capture, avec **bbox encadrée** sur la zone divergente.
+  - Toggle overlay diff (rouge) optionnel.
+- Deux actions par screenshot :
+  - **Garder la banque** → `resolve_comparison(name, Keep)` : banque inchangée, régression
+    enregistrée dans le rapport.
+  - **Remplacer par la nouvelle** → `resolve_comparison(name, Replace)` : écrase
+    `bank/<key>/<nom>.png`.
+- Les statuts `Seeded` ne déclenchent pas de revue : simple bandeau « N références créées ».
+- `Match` : silencieux.
+
+### 6. Commandes IPC (Rust ↔ front)
+
+- `run_flow` (existant) — étendu : fixe le CWD, et après l'exit déclenche la comparaison.
+- `get_run_report(run_id) -> RunReport` — lire le rapport.
+- `resolve_comparison(run_id, name, decision: Keep | Replace)` — applique la décision.
+
+## Gestion des erreurs / cas limites
+
+- **PNG manquant** alors qu'attendu (`takeScreenshot` dans le YAML mais pas de fichier) →
+  statut `Missing` (le flow a peut-être échoué avant cette étape). Signalé, pas bloquant.
+- **Run échoué** (exit ≠ 0) → on compare quand même les screenshots produits ; un run
+  interrompu produira des `Missing`.
+- **YAML non parsable** → on ne bloque pas le run ; on collecte les PNG présents par leur
+  nom de fichier en best-effort, et on log un avertissement.
+- **Nouvelle résolution / nouveau modèle** → nouvelle clé de banque → comportement seed
+  (1er run sur ce device-type).
+- **Collisions de noms** (deux `takeScreenshot: login` dans le même flow) → hors scope v1 ;
+  on documente que les noms doivent être uniques par flow.
+
+## Tests
+
+- **Unit (Rust)** — moteur de diff : images identiques → `Match` ; 1 bloc modifié →
+  `Changed` + bbox correct ; dimensions ≠ → `DimensionMismatch` ; tolérance absorbe le
+  bruit anti-aliasing ; seed quand banque vide.
+- **Unit (Rust)** — clé device : sanitize correct, mêmes model+résolution → même clé.
+- **Unit (Rust)** — parse YAML : extraction des noms `takeScreenshot` (forme string et
+  forme `path:`).
+- **Intégration** — `resolve_comparison(Replace)` écrase bien le fichier banque ; `Keep`
+  laisse la banque intacte et enregistre la régression.
+- **Front** — `ScreenshotReview` : file de plusieurs diffs, actions Keep/Replace,
+  rendu de la bbox et de l'overlay.
+
+## Hors scope (v2+)
+
+- Masques / zones à ignorer (horloge, barre de statut) par screenshot.
+- Réglages de seuils dans l'UI Settings.
+- Historique/diff entre runs au-delà de la dernière référence.
+- Synchronisation cloud / partage d'équipe de la banque.
+- Fallback de clé par UUID device.
+```

From 709439b9e6bae382e9282c63948a1cc4840785d3 Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Mon, 29 Jun 2026 00:22:08 +0200
Subject: [PATCH 15/18] =?UTF-8?q?docs:=20seuils=20configurables=20(Param?=
 =?UTF-8?q?=C3=A8tres)=20+=20comparaison=20conditionn=C3=A9e=20=C3=A0=20la?=
 =?UTF-8?q?=20r=C3=A9ussite=20du=20run?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...06-29-screenshot-bank-regression-design.md | 57 ++++++++++++++-----
 1 file changed, 42 insertions(+), 15 deletions(-)

diff --git a/docs/superpowers/specs/2026-06-29-screenshot-bank-regression-design.md b/docs/superpowers/specs/2026-06-29-screenshot-bank-regression-design.md
index d314acc..414de74 100644
--- a/docs/superpowers/specs/2026-06-29-screenshot-bank-regression-design.md
+++ b/docs/superpowers/specs/2026-06-29-screenshot-bank-regression-design.md
@@ -18,10 +18,12 @@ la revue de l'utilisateur, qui décide de garder la référence ou de la remplac
 |-------|----------|
 | Source des screenshots | Commandes `takeScreenshot: <nom>` du flow YAML ; `<nom>` = clé de matching |
 | Algorithme de diff | Pixelmatch-like : seuil % de pixels changés + tolérance couleur par pixel |
+| Seuils | **Configurables** dans une nouvelle section des Paramètres (tolérance + seuil %) |
 | Masques / zones ignorées | **Hors scope v1** (prévu v2) |
 | Sémantique du refus | Garder la banque = **régression détectée** (signal d'alerte) ; banque inchangée |
 | Sémantique de l'acceptation | Remplacer = la nouvelle capture devient la vérité (écrase la banque) |
-| Portée | **Tout** run d'un flow (single + Run All) |
+| Portée | **Tout** run d'un flow (single + Run All), **uniquement si le run réussit** (exit 0) |
+| Run en échec | Exit ≠ 0 → **aucun** traitement de banque (ni comparaison ni seed) |
 | Clé de banque | `<model>_<W>x<H>` (modèle + résolution, sanitizé) |
 | Emplacement | `<workspace>/maestro/bank/<key>/` (créer `bank/` si `maestro/` existe déjà) |
 | Récupération PNG | Non invasif : CWD du runner = **dossier du flow** ; collecte des `<nom>.png` sur place |
@@ -41,8 +43,9 @@ Maestro exécute, écrit <nom>.png à côté du flow
         │
    runner:exit
         │
-        ▼
-[Rust] Comparateur de banque
+        ├─ exit ≠ 0 → STOP (aucun traitement de banque)
+        ▼ exit == 0
+[Rust] Comparateur de banque (seuils lus depuis les Paramètres)
    ├─ parse YAML → liste des noms takeScreenshot attendus
    ├─ résout clé device = <model>_<W>x<H>
    ├─ pour chaque <nom>.png :
@@ -96,8 +99,9 @@ Maestro exécute, écrit <nom>.png à côté du flow
   à côté du flow de façon déterministe.
 - Parse du YAML du flow pour extraire la **liste ordonnée des noms** `takeScreenshot`
   (sert au matching et à détecter un `Missing`).
-- Au `runner:exit` (code 0 ou non), collecte des `<nom>.png` attendus dans le dossier du
-  flow.
+- Au `runner:exit` : **si exit ≠ 0, on s'arrête là** — pas de comparaison, pas de seed.
+  Un run en échec n'a aucune logique de traitement de banque (état non fiable).
+- Si exit == 0, collecte des `<nom>.png` attendus dans le dossier du flow, puis comparaison.
 
 ### 3. Moteur de comparaison (Rust, nouveau module `src-tauri/src/bank/`)
 
@@ -109,9 +113,11 @@ Maestro exécute, écrit <nom>.png à côté du flow
   - `changed_ratio = pixels_changés / total`. Si `changed_ratio > seuil` → `Changed`.
   - Génère `diffs/<nom>.png` (overlay rouge sur les pixels changés) et le **bounding box**
     englobant (x, y, w, h) pour l'encadré UI.
-- Seuils par défaut configurables (constantes v1, settings plus tard) :
-  - tolérance couleur ≈ 0.1 (échelle pixelmatch)
-  - seuil ratio ≈ 0.001 (0.1 % des pixels)
+- **Seuils fournis par l'appel** (lus depuis les Paramètres côté front, passés à la commande
+  de comparaison) :
+  - `tolerance` : tolérance couleur par pixel (échelle pixelmatch, défaut 0.1)
+  - `threshold` : ratio de pixels changés au-delà duquel on flague (défaut 0.001 = 0.1 %)
+  - Si les Paramètres n'ont jamais été modifiés → valeurs par défaut embarquées.
 
 ### 4. Modèle de résultat
 
@@ -157,18 +163,37 @@ struct RunReport {
 - Les statuts `Seeded` ne déclenchent pas de revue : simple bandeau « N références créées ».
 - `Match` : silencieux.
 
-### 6. Commandes IPC (Rust ↔ front)
+### 6. Paramètres — section « Régression visuelle » (front)
+
+Suit le pattern existant (cf. prompt Billy : store Zustand dédié + `persist` localStorage,
+section enregistrée dans `SETTINGS_SECTIONS`).
+
+- Nouveau store `src/stores/visualRegressionStore.ts`, clé localStorage
+  `maestro-deck.visual-regression` :
+  - `tolerance: number | null` (null → défaut 0.1)
+  - `threshold: number | null` (null → défaut 0.001)
+  - setters + `reset()` (remet à `null` = défauts embarqués, façon Billy).
+- Nouveau composant `src/components/settings/VisualRegressionSettings.tsx` :
+  deux champs numériques (tolérance, seuil %) avec valeurs par défaut et bouton reset,
+  enveloppés dans `<SettingsSection>`.
+- Enregistrement dans `src/components/settings/sections.tsx` :
+  `{ id: "visual-regression", label: "Régression visuelle", render: () => <VisualRegressionSettings /> }`.
+- Au lancement d'un run, le front lit `visualRegressionStore.getState()` et passe
+  `tolerance` + `threshold` (résolus avec leurs défauts) à la commande de comparaison.
+
+### 7. Commandes IPC (Rust ↔ front)
 
-- `run_flow` (existant) — étendu : fixe le CWD, et après l'exit déclenche la comparaison.
+- `run_flow` (existant) — étendu : fixe le CWD ; après l'exit, **si exit == 0**, déclenche la
+  comparaison avec les seuils reçus.
 - `get_run_report(run_id) -> RunReport` — lire le rapport.
 - `resolve_comparison(run_id, name, decision: Keep | Replace)` — applique la décision.
 
 ## Gestion des erreurs / cas limites
 
-- **PNG manquant** alors qu'attendu (`takeScreenshot` dans le YAML mais pas de fichier) →
-  statut `Missing` (le flow a peut-être échoué avant cette étape). Signalé, pas bloquant.
-- **Run échoué** (exit ≠ 0) → on compare quand même les screenshots produits ; un run
-  interrompu produira des `Missing`.
+- **Run échoué** (exit ≠ 0) → **aucun** traitement de banque (ni comparaison, ni seed, ni
+  rapport). Un flow en erreur laisse un état device non fiable : pas de logique à appliquer.
+- **PNG manquant** sur un run réussi (`takeScreenshot` dans le YAML mais pas de fichier
+  produit) → statut `Missing`. Signalé, pas bloquant. Cas rare puisque le flow a réussi.
 - **YAML non parsable** → on ne bloque pas le run ; on collecte les PNG présents par leur
   nom de fichier en best-effort, et on log un avertissement.
 - **Nouvelle résolution / nouveau modèle** → nouvelle clé de banque → comportement seed
@@ -186,13 +211,15 @@ struct RunReport {
   forme `path:`).
 - **Intégration** — `resolve_comparison(Replace)` écrase bien le fichier banque ; `Keep`
   laisse la banque intacte et enregistre la régression.
+- **Intégration** — run en échec (exit ≠ 0) → aucun rapport, aucune écriture dans `bank/`.
+- **Unit** — seuils : `tolerance`/`threshold` reçus en paramètre modifient bien le verdict ;
+  store front résout `null` → défauts (0.1 / 0.001).
 - **Front** — `ScreenshotReview` : file de plusieurs diffs, actions Keep/Replace,
   rendu de la bbox et de l'overlay.
 
 ## Hors scope (v2+)
 
 - Masques / zones à ignorer (horloge, barre de statut) par screenshot.
-- Réglages de seuils dans l'UI Settings.
 - Historique/diff entre runs au-delà de la dernière référence.
 - Synchronisation cloud / partage d'équipe de la banque.
 - Fallback de clé par UUID device.

From 08287957247f71f0901cd30eb99f8fe12a684e46 Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Mon, 29 Jun 2026 00:28:04 +0200
Subject: [PATCH 16/18] release: v0.6.0

---
 LICENSE                   | 2 +-
 package.json              | 2 +-
 src-tauri/Cargo.toml      | 2 +-
 src-tauri/tauri.conf.json | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/LICENSE b/LICENSE
index d9a526e..5499dcd 100644
--- a/LICENSE
+++ b/LICENSE
@@ -15,7 +15,7 @@ Additional Use Grant: You may use the Licensed Work in production,
                       (in original or modified form) as a commercial
                       product or as part of a commercial offering.
 
-Change Date:          2030-06-14
+Change Date:          2030-06-28
 
 Change License:       Apache License, Version 2.0
 
diff --git a/package.json b/package.json
index 8cb1b7f..d728f7e 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "maestro-deck",
   "private": true,
-  "version": "0.5.5",
+  "version": "0.6.0",
   "type": "module",
   "description": "Source-available visual IDE for Maestro mobile tests",
   "license": "BUSL-1.1",
diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml
index d2c6b59..92b607b 100644
--- a/src-tauri/Cargo.toml
+++ b/src-tauri/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "maestro-deck"
-version = "0.5.5"
+version = "0.6.0"
 description = "Source-available visual IDE for Maestro mobile tests"
 authors = ["Ethan Morisset <blueshork.dev@gmail.com>"]
 license = "BUSL-1.1"
diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json
index d20956e..8f00856 100644
--- a/src-tauri/tauri.conf.json
+++ b/src-tauri/tauri.conf.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://schema.tauri.app/config/2",
   "productName": "Maestro Deck",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "identifier": "dev.blueshork.maestrodeck",
   "build": {
     "beforeDevCommand": "pnpm dev",

From c96c55ff956f00857bca6ee55d27da9a9222aa40 Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Mon, 29 Jun 2026 00:44:42 +0200
Subject: [PATCH 17/18] =?UTF-8?q?docs:=20plan=20d'impl=C3=A9mentation=20ba?=
 =?UTF-8?q?nque=20de=20screenshots=20&=20r=C3=A9gression=20visuelle?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../2026-06-29-screenshot-bank-regression.md  | 1449 +++++++++++++++++
 1 file changed, 1449 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-06-29-screenshot-bank-regression.md

diff --git a/docs/superpowers/plans/2026-06-29-screenshot-bank-regression.md b/docs/superpowers/plans/2026-06-29-screenshot-bank-regression.md
new file mode 100644
index 0000000..b2325e6
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-29-screenshot-bank-regression.md
@@ -0,0 +1,1449 @@
+# Banque de screenshots & régression visuelle — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Maintenir une banque de screenshots de référence par device et signaler les régressions visuelles entre runs, avec revue utilisateur (garder la banque / remplacer).
+
+**Architecture:** Rust = moteur pur (crate `image`, diff YIQ pixelmatch, I/O banque) exposé via deux commandes Tauri. Le front orchestre : à la fin d'un run réussi (`runner:exit` code 0), il appelle `compare_screenshots` avec les seuils (Paramètres), le device et le workspace ; le rapport renvoyé alimente une modale de revue. Les `takeScreenshot: <nom>` du flow YAML produisent `<nom>.png` à côté du flow (CWD du runner fixé sur le dossier du flow).
+
+**Tech Stack:** Rust (Tauri 2, tokio, serde, crate `image`), React + TypeScript + Zustand + Vitest.
+
+## Global Constraints
+
+- En-tête de licence en tête de **chaque nouveau fichier** (copier verbatim depuis un fichier voisin existant) :
+  `// Copyright (c) 2026 Ethan Morisset` puis `// SPDX-License-Identifier: BUSL-1.1`.
+- Commits **sans** attribution Claude / Co-Authored-By.
+- Clé device = `<model>_<screen_width>x<screen_height>`, sanitizée (tout caractère non `[A-Za-z0-9]` → `_`).
+- Emplacement banque : `<workspace>/maestro/bank/<key>/<nom>.png` ; runs : `<workspace>/maestro/.runs/<run_id>/`.
+- Seuils par défaut : `tolerance = 0.1` (delta couleur par pixel, échelle pixelmatch), `threshold = 0.001` (ratio de pixels changés).
+- Aucun traitement de banque si le run échoue (exit ≠ 0) : orchestré côté front (n'appelle `compare_screenshots` que si `code === 0`).
+- Tests Rust : `cargo test` dans `src-tauri/`. Tests front : `pnpm test` (vitest, fichiers `src/**/*.test.ts(x)`).
+- Imports front via alias `@/` (ex: `@/stores/...`).
+
+---
+
+### Task 1: Module `bank` + clé device + dépendance `image`
+
+**Files:**
+- Modify: `src-tauri/Cargo.toml` (section `[dependencies]`)
+- Create: `src-tauri/src/bank/mod.rs`
+- Modify: `src-tauri/src/lib.rs` (déclaration du module)
+
+**Interfaces:**
+- Produces: `pub fn device_key(model: &str, width: u32, height: u32) -> String`
+
+- [ ] **Step 1: Écrire le test qui échoue**
+
+Ajouter à la fin de `src-tauri/src/bank/mod.rs` (créer le fichier avec l'en-tête licence) :
+
+```rust
+// Copyright (c) 2026 Ethan Morisset
+// SPDX-License-Identifier: BUSL-1.1
+
+pub fn device_key(model: &str, width: u32, height: u32) -> String {
+    todo!()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn device_key_sanitizes_and_appends_resolution() {
+        assert_eq!(device_key("iPhone 15 Pro", 1179, 2556), "iPhone_15_Pro_1179x2556");
+        assert_eq!(device_key("Pixel/6", 1080, 2400), "Pixel_6_1080x2400");
+    }
+}
+```
+
+Déclarer le module dans `src-tauri/src/lib.rs` (à côté des autres `mod ...;`, ex. près de `mod runner;`) :
+
+```rust
+mod bank;
+```
+
+- [ ] **Step 2: Lancer le test, vérifier l'échec**
+
+Run: `cd src-tauri && cargo test bank::tests::device_key_sanitizes -- --nocapture`
+Expected: PANIC `not yet implemented` (todo!).
+
+- [ ] **Step 3: Implémenter**
+
+Remplacer le corps de `device_key` :
+
+```rust
+pub fn device_key(model: &str, width: u32, height: u32) -> String {
+    let sanitized: String = model
+        .chars()
+        .map(|c| if c.is_ascii_alphanumeric() { c } else { '_' })
+        .collect();
+    format!("{sanitized}_{width}x{height}")
+}
+```
+
+- [ ] **Step 4: Ajouter la dépendance `image`**
+
+Dans `src-tauri/Cargo.toml`, sous `[dependencies]`, ajouter (PNG uniquement, pas de features superflues) :
+
+```toml
+image = { version = "0.25", default-features = false, features = ["png"] }
+```
+
+- [ ] **Step 5: Lancer le test, vérifier le succès**
+
+Run: `cd src-tauri && cargo test bank::tests::device_key_sanitizes`
+Expected: PASS (1 test).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src-tauri/Cargo.toml src-tauri/Cargo.lock src-tauri/src/bank/mod.rs src-tauri/src/lib.rs
+git commit -m "feat(bank): module + device_key + image crate"
+```
+
+---
+
+### Task 2: Extraction des noms `takeScreenshot` du flow YAML
+
+**Files:**
+- Create: `src-tauri/src/bank/flow.rs`
+- Modify: `src-tauri/src/bank/mod.rs` (ajouter `pub mod flow;`)
+
+**Interfaces:**
+- Produces: `pub fn screenshot_names(flow_yaml: &str) -> Vec<String>`
+  Extrait, dans l'ordre, les noms des commandes `takeScreenshot`. Supporte la forme courte
+  (`- takeScreenshot: login`) et la forme objet (`- takeScreenshot:\n    path: login`).
+
+- [ ] **Step 1: Écrire le test qui échoue**
+
+Créer `src-tauri/src/bank/flow.rs` :
+
+```rust
+// Copyright (c) 2026 Ethan Morisset
+// SPDX-License-Identifier: BUSL-1.1
+
+/// Extrait les noms des commandes `takeScreenshot` d'un flow Maestro, dans l'ordre.
+pub fn screenshot_names(flow_yaml: &str) -> Vec<String> {
+    todo!()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn extracts_short_and_object_forms() {
+        let yaml = r#"
+appId: com.example
+---
+- launchApp
+- takeScreenshot: login
+- tapOn: "Next"
+- takeScreenshot:
+    path: home
+"#;
+        assert_eq!(screenshot_names(yaml), vec!["login".to_string(), "home".to_string()]);
+    }
+
+    #[test]
+    fn returns_empty_when_none() {
+        assert_eq!(screenshot_names("- launchApp\n").len(), 0);
+    }
+}
+```
+
+Ajouter dans `src-tauri/src/bank/mod.rs`, sous l'en-tête, avant `device_key` :
+
+```rust
+pub mod flow;
+```
+
+- [ ] **Step 2: Lancer le test, vérifier l'échec**
+
+Run: `cd src-tauri && cargo test bank::flow`
+Expected: PANIC `not yet implemented`.
+
+- [ ] **Step 3: Implémenter (parsing ligne à ligne, sans dépendance YAML)**
+
+Remplacer le corps de `screenshot_names` :
+
+```rust
+pub fn screenshot_names(flow_yaml: &str) -> Vec<String> {
+    let mut names = Vec::new();
+    let mut lines = flow_yaml.lines().peekable();
+    while let Some(raw) = lines.next() {
+        let line = raw.trim_start_matches('-').trim();
+        let Some(rest) = line.strip_prefix("takeScreenshot:") else {
+            continue;
+        };
+        let inline = rest.trim();
+        if !inline.is_empty() {
+            // Forme courte: `takeScreenshot: name`
+            names.push(unquote(inline));
+        } else if let Some(next) = lines.peek() {
+            // Forme objet: `path: name` sur la ligne suivante
+            if let Some(path) = next.trim().strip_prefix("path:") {
+                names.push(unquote(path.trim()));
+            }
+        }
+    }
+    names
+}
+
+fn unquote(s: &str) -> String {
+    s.trim_matches(|c| c == '"' || c == '\'').to_string()
+}
+```
+
+- [ ] **Step 4: Lancer les tests, vérifier le succès**
+
+Run: `cd src-tauri && cargo test bank::flow`
+Expected: PASS (2 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src-tauri/src/bank/flow.rs src-tauri/src/bank/mod.rs
+git commit -m "feat(bank): extract takeScreenshot names from flow yaml"
+```
+
+---
+
+### Task 3: Cœur du diff pixel (YIQ pixelmatch)
+
+**Files:**
+- Create: `src-tauri/src/bank/diff.rs`
+- Modify: `src-tauri/src/bank/mod.rs` (ajouter `pub mod diff;`)
+
+**Interfaces:**
+- Produces:
+  ```rust
+  pub struct DiffOutcome {
+      pub changed_ratio: f32,
+      pub bbox: Option<[u32; 4]>,   // x, y, w, h des pixels changés
+      pub diff_png: Vec<u8>,        // PNG: copie de `new` avec pixels changés en rouge
+  }
+  pub fn diff_images(bank_png: &[u8], new_png: &[u8], tolerance: f64) -> Result<DiffOutcome, image::ImageError>
+  ```
+  Renvoie une erreur si l'un des PNG ne décode pas. (Les dimensions différentes sont gérées
+  par l'appelant — voir Task 4 — donc ici on suppose dimensions égales ; sinon `panic` testé séparément n'est pas requis.)
+
+- [ ] **Step 1: Écrire le test qui échoue**
+
+Créer `src-tauri/src/bank/diff.rs` :
+
+```rust
+// Copyright (c) 2026 Ethan Morisset
+// SPDX-License-Identifier: BUSL-1.1
+
+use image::{ImageEncoder, RgbaImage};
+
+pub struct DiffOutcome {
+    pub changed_ratio: f32,
+    pub bbox: Option<[u32; 4]>,
+    pub diff_png: Vec<u8>,
+}
+
+pub fn diff_images(bank_png: &[u8], new_png: &[u8], tolerance: f64) -> Result<DiffOutcome, image::ImageError> {
+    todo!()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use image::RgbaImage;
+
+    fn png_bytes(img: &RgbaImage) -> Vec<u8> {
+        let mut buf = Vec::new();
+        image::codecs::png::PngEncoder::new(&mut buf)
+            .write_image(img.as_raw(), img.width(), img.height(), image::ExtendedColorType::Rgba8)
+            .unwrap();
+        buf
+    }
+
+    #[test]
+    fn identical_images_have_zero_ratio() {
+        let img = RgbaImage::from_pixel(4, 4, image::Rgba([10, 20, 30, 255]));
+        let out = diff_images(&png_bytes(&img), &png_bytes(&img), 0.1).unwrap();
+        assert_eq!(out.changed_ratio, 0.0);
+        assert!(out.bbox.is_none());
+    }
+
+    #[test]
+    fn one_changed_pixel_is_detected_with_bbox() {
+        let bank = RgbaImage::from_pixel(4, 4, image::Rgba([0, 0, 0, 255]));
+        let mut new = bank.clone();
+        new.put_pixel(2, 1, image::Rgba([255, 255, 255, 255])); // blanc vs noir
+        let out = diff_images(&png_bytes(&bank), &png_bytes(&new), 0.1).unwrap();
+        assert!(out.changed_ratio > 0.0);
+        assert_eq!(out.bbox, Some([2, 1, 1, 1]));
+    }
+}
+```
+
+Ajouter dans `src-tauri/src/bank/mod.rs` : `pub mod diff;`
+
+- [ ] **Step 2: Lancer le test, vérifier l'échec**
+
+Run: `cd src-tauri && cargo test bank::diff`
+Expected: PANIC `not yet implemented`.
+
+- [ ] **Step 3: Implémenter le diff YIQ**
+
+Remplacer le corps de `diff_images` et ajouter les helpers :
+
+```rust
+pub fn diff_images(bank_png: &[u8], new_png: &[u8], tolerance: f64) -> Result<DiffOutcome, image::ImageError> {
+    let bank = image::load_from_memory(bank_png)?.to_rgba8();
+    let mut new = image::load_from_memory(new_png)?.to_rgba8();
+    let (w, h) = (new.width(), new.height());
+
+    // Seuil pixelmatch : delta max possible (noir↔blanc) = 35215.
+    let max_delta = 35215.0 * tolerance * tolerance;
+
+    let (mut min_x, mut min_y, mut max_x, mut max_y) = (u32::MAX, u32::MAX, 0u32, 0u32);
+    let mut changed = 0u64;
+
+    for y in 0..h {
+        for x in 0..w {
+            let a = bank.get_pixel(x, y).0;
+            let b = new.get_pixel(x, y).0;
+            if color_delta(a, b) > max_delta {
+                changed += 1;
+                min_x = min_x.min(x);
+                min_y = min_y.min(y);
+                max_x = max_x.max(x);
+                max_y = max_y.max(y);
+                new.put_pixel(x, y, image::Rgba([255, 0, 0, 255]));
+            }
+        }
+    }
+
+    let total = (w as u64) * (h as u64);
+    let changed_ratio = if total == 0 { 0.0 } else { changed as f32 / total as f32 };
+    let bbox = if changed == 0 {
+        None
+    } else {
+        Some([min_x, min_y, max_x - min_x + 1, max_y - min_y + 1])
+    };
+
+    let mut diff_png = Vec::new();
+    image::codecs::png::PngEncoder::new(&mut diff_png).write_image(
+        new.as_raw(),
+        w,
+        h,
+        image::ExtendedColorType::Rgba8,
+    )?;
+
+    Ok(DiffOutcome { changed_ratio, bbox, diff_png })
+}
+
+fn color_delta(a: [u8; 4], b: [u8; 4]) -> f64 {
+    let (ay, ai, aq) = yiq(a);
+    let (by, bi, bq) = yiq(b);
+    let (dy, di, dq) = (ay - by, ai - bi, aq - bq);
+    0.5053 * dy * dy + 0.299 * di * di + 0.1957 * dq * dq
+}
+
+fn yiq(p: [u8; 4]) -> (f64, f64, f64) {
+    let (r, g, b) = (p[0] as f64, p[1] as f64, p[2] as f64);
+    let y = r * 0.29889531 + g * 0.58662247 + b * 0.11448223;
+    let i = r * 0.59597799 - g * 0.27417610 - b * 0.32180189;
+    let q = r * 0.21147017 - g * 0.52261711 + b * 0.31114694;
+    (y, i, q)
+}
+```
+
+- [ ] **Step 4: Lancer les tests, vérifier le succès**
+
+Run: `cd src-tauri && cargo test bank::diff`
+Expected: PASS (2 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src-tauri/src/bank/diff.rs src-tauri/src/bank/mod.rs
+git commit -m "feat(bank): YIQ pixelmatch diff core with bbox + diff png"
+```
+
+---
+
+### Task 4: Orchestration de comparaison sur un flow (seed/match/changed/missing/dimension)
+
+**Files:**
+- Create: `src-tauri/src/bank/compare.rs`
+- Modify: `src-tauri/src/bank/mod.rs` (ajouter `pub mod compare;` + ré-exports)
+
+**Interfaces:**
+- Consumes: `device_key`, `flow::screenshot_names`, `diff::diff_images`.
+- Produces:
+  ```rust
+  #[derive(serde::Serialize, Clone)]
+  #[serde(rename_all = "snake_case")]
+  pub enum Status { Seeded, Match, Changed, Missing, DimensionMismatch }
+
+  #[derive(serde::Serialize, Clone)]
+  pub struct Comparison {
+      pub name: String,
+      pub status: Status,
+      pub changed_ratio: f32,
+      pub bbox: Option<[u32; 4]>,
+      #[serde(skip_serializing_if = "Option::is_none")] pub bank_b64: Option<String>,
+      #[serde(skip_serializing_if = "Option::is_none")] pub new_b64: Option<String>,
+      #[serde(skip_serializing_if = "Option::is_none")] pub diff_b64: Option<String>,
+  }
+
+  pub struct CompareInput<'a> {
+      pub workspace: &'a Path,
+      pub flow_path: &'a Path,
+      pub model: &'a str,
+      pub width: u32,
+      pub height: u32,
+      pub tolerance: f64,
+      pub threshold: f64,
+  }
+
+  pub fn compare_flow(input: CompareInput) -> std::io::Result<(String, Vec<Comparison>)>
+  // renvoie (device_key, comparisons)
+  ```
+  Règles : pour chaque nom attendu (du flow), résoudre `<flow_dir>/<name>.png` (produit) et
+  `<workspace>/maestro/bank/<key>/<name>.png` (référence).
+  - produit absent → `Missing`.
+  - produit présent, référence absente → copier le produit dans la banque → `Seeded`.
+  - les deux présents, dimensions ≠ → `DimensionMismatch` (+ b64 bank/new).
+  - les deux présents, `changed_ratio > threshold` → `Changed` (+ b64 bank/new/diff, bbox).
+  - sinon → `Match`.
+  Le `device_key` directory est créé au besoin (`create_dir_all`).
+
+- [ ] **Step 1: Écrire le test qui échoue**
+
+Créer `src-tauri/src/bank/compare.rs` avec l'en-tête licence, la déclaration des types ci-dessus,
+un `pub fn compare_flow(...) -> ... { todo!() }`, et les tests :
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use image::{ImageEncoder, RgbaImage};
+    use std::fs;
+
+    fn write_png(path: &Path, img: &RgbaImage) {
+        let mut buf = Vec::new();
+        image::codecs::png::PngEncoder::new(&mut buf)
+            .write_image(img.as_raw(), img.width(), img.height(), image::ExtendedColorType::Rgba8)
+            .unwrap();
+        fs::create_dir_all(path.parent().unwrap()).unwrap();
+        fs::write(path, buf).unwrap();
+    }
+
+    fn temp_dir(tag: &str) -> std::path::PathBuf {
+        let dir = std::env::temp_dir().join(format!("mdbank_{tag}"));
+        let _ = fs::remove_dir_all(&dir);
+        fs::create_dir_all(&dir).unwrap();
+        dir
+    }
+
+    #[test]
+    fn seeds_when_bank_empty_then_matches_next_run() {
+        let ws = temp_dir("seed");
+        let flow_dir = ws.join("flows");
+        let flow_path = flow_dir.join("f.yaml");
+        fs::create_dir_all(&flow_dir).unwrap();
+        fs::write(&flow_path, "- takeScreenshot: home\n").unwrap();
+        write_png(&flow_dir.join("home.png"), &RgbaImage::from_pixel(2, 2, image::Rgba([1, 2, 3, 255])));
+
+        let input = CompareInput {
+            workspace: &ws, flow_path: &flow_path, model: "Dev", width: 2, height: 2,
+            tolerance: 0.1, threshold: 0.001,
+        };
+        let (key, comps) = compare_flow(input).unwrap();
+        assert_eq!(comps.len(), 1);
+        assert!(matches!(comps[0].status, Status::Seeded));
+        // la référence existe maintenant
+        assert!(ws.join("maestro/bank").join(&key).join("home.png").exists());
+
+        // 2e run identique → Match
+        let input2 = CompareInput {
+            workspace: &ws, flow_path: &flow_path, model: "Dev", width: 2, height: 2,
+            tolerance: 0.1, threshold: 0.001,
+        };
+        let (_, comps2) = compare_flow(input2).unwrap();
+        assert!(matches!(comps2[0].status, Status::Match));
+    }
+
+    #[test]
+    fn flags_changed_pixels() {
+        let ws = temp_dir("changed");
+        let flow_dir = ws.join("flows");
+        let flow_path = flow_dir.join("f.yaml");
+        fs::create_dir_all(&flow_dir).unwrap();
+        fs::write(&flow_path, "- takeScreenshot: home\n").unwrap();
+        let key = device_key("Dev", 4, 4);
+        // référence noire
+        write_png(&ws.join("maestro/bank").join(&key).join("home.png"),
+                  &RgbaImage::from_pixel(4, 4, image::Rgba([0, 0, 0, 255])));
+        // produit avec un coin blanc
+        let mut produced = RgbaImage::from_pixel(4, 4, image::Rgba([0, 0, 0, 255]));
+        produced.put_pixel(0, 0, image::Rgba([255, 255, 255, 255]));
+        write_png(&flow_dir.join("home.png"), &produced);
+
+        let (_, comps) = compare_flow(CompareInput {
+            workspace: &ws, flow_path: &flow_path, model: "Dev", width: 4, height: 4,
+            tolerance: 0.1, threshold: 0.001,
+        }).unwrap();
+        assert!(matches!(comps[0].status, Status::Changed));
+        assert!(comps[0].diff_b64.is_some());
+        assert_eq!(comps[0].bbox, Some([0, 0, 1, 1]));
+    }
+
+    #[test]
+    fn missing_when_no_produced_file() {
+        let ws = temp_dir("missing");
+        let flow_dir = ws.join("flows");
+        let flow_path = flow_dir.join("f.yaml");
+        fs::create_dir_all(&flow_dir).unwrap();
+        fs::write(&flow_path, "- takeScreenshot: home\n").unwrap();
+        let (_, comps) = compare_flow(CompareInput {
+            workspace: &ws, flow_path: &flow_path, model: "Dev", width: 2, height: 2,
+            tolerance: 0.1, threshold: 0.001,
+        }).unwrap();
+        assert!(matches!(comps[0].status, Status::Missing));
+    }
+}
+```
+
+Ajouter dans `mod.rs` : `pub mod compare;`
+
+- [ ] **Step 2: Lancer les tests, vérifier l'échec**
+
+Run: `cd src-tauri && cargo test bank::compare`
+Expected: PANIC `not yet implemented`.
+
+- [ ] **Step 3: Implémenter**
+
+Corps de `compare.rs` (au-dessus des tests, après les types) :
+
+```rust
+use std::fs;
+use std::path::Path;
+
+use base64::Engine;
+
+use crate::bank::device_key;
+use crate::bank::diff::diff_images;
+use crate::bank::flow::screenshot_names;
+
+fn b64(bytes: &[u8]) -> String {
+    format!("data:image/png;base64,{}", base64::engine::general_purpose::STANDARD.encode(bytes))
+}
+
+fn dims(png: &[u8]) -> Option<(u32, u32)> {
+    image::load_from_memory(png).ok().map(|i| (i.width(), i.height()))
+}
+
+pub fn compare_flow(input: CompareInput) -> std::io::Result<(String, Vec<Comparison>)> {
+    let key = device_key(input.model, input.width, input.height);
+    let bank_dir = input.workspace.join("maestro").join("bank").join(&key);
+    fs::create_dir_all(&bank_dir)?;
+
+    let flow_dir = input.flow_path.parent().unwrap_or(Path::new("."));
+    let yaml = fs::read_to_string(input.flow_path).unwrap_or_default();
+    let names = screenshot_names(&yaml);
+
+    let mut comps = Vec::new();
+    for name in names {
+        let produced = flow_dir.join(format!("{name}.png"));
+        let reference = bank_dir.join(format!("{name}.png"));
+
+        if !produced.exists() {
+            comps.push(Comparison {
+                name, status: Status::Missing, changed_ratio: 0.0, bbox: None,
+                bank_b64: None, new_b64: None, diff_b64: None,
+            });
+            continue;
+        }
+        let new_bytes = fs::read(&produced)?;
+
+        if !reference.exists() {
+            fs::copy(&produced, &reference)?;
+            comps.push(Comparison {
+                name, status: Status::Seeded, changed_ratio: 0.0, bbox: None,
+                bank_b64: None, new_b64: None, diff_b64: None,
+            });
+            continue;
+        }
+        let bank_bytes = fs::read(&reference)?;
+
+        if dims(&bank_bytes) != dims(&new_bytes) {
+            comps.push(Comparison {
+                name, status: Status::DimensionMismatch, changed_ratio: 0.0, bbox: None,
+                bank_b64: Some(b64(&bank_bytes)), new_b64: Some(b64(&new_bytes)), diff_b64: None,
+            });
+            continue;
+        }
+
+        match diff_images(&bank_bytes, &new_bytes, input.tolerance) {
+            Ok(out) if out.changed_ratio as f64 > input.threshold => comps.push(Comparison {
+                name,
+                status: Status::Changed,
+                changed_ratio: out.changed_ratio,
+                bbox: out.bbox,
+                bank_b64: Some(b64(&bank_bytes)),
+                new_b64: Some(b64(&new_bytes)),
+                diff_b64: Some(b64(&out.diff_png)),
+            }),
+            Ok(out) => comps.push(Comparison {
+                name, status: Status::Match, changed_ratio: out.changed_ratio, bbox: None,
+                bank_b64: None, new_b64: None, diff_b64: None,
+            }),
+            Err(_) => comps.push(Comparison {
+                name, status: Status::Missing, changed_ratio: 0.0, bbox: None,
+                bank_b64: None, new_b64: None, diff_b64: None,
+            }),
+        }
+    }
+    Ok((key, comps))
+}
+```
+
+Ajouter la dépendance `base64` si absente de `src-tauri/Cargo.toml` (vérifier d'abord — déjà utilisée ailleurs dans le projet pour l'encodage PNG ; si présente, ne rien faire) :
+
+```toml
+base64 = "0.22"
+```
+
+- [ ] **Step 4: Lancer les tests, vérifier le succès**
+
+Run: `cd src-tauri && cargo test bank::compare`
+Expected: PASS (3 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src-tauri/src/bank/compare.rs src-tauri/src/bank/mod.rs src-tauri/Cargo.toml src-tauri/Cargo.lock
+git commit -m "feat(bank): compare_flow orchestration (seed/match/changed/missing/dimension)"
+```
+
+---
+
+### Task 5: Commandes Tauri `compare_screenshots` + `resolve_comparison`
+
+**Files:**
+- Create: `src-tauri/src/bank/ipc.rs`
+- Modify: `src-tauri/src/bank/mod.rs` (`pub mod ipc;`)
+- Modify: `src-tauri/src/lib.rs` (enregistrer les 2 commandes dans `generate_handler!`)
+
+**Interfaces:**
+- Consumes: `compare::{compare_flow, CompareInput, Comparison}`.
+- Produces (commandes Tauri) :
+  ```rust
+  #[tauri::command]
+  pub async fn compare_screenshots(
+      workspace: String, flow_path: String, model: String,
+      width: u32, height: u32, tolerance: f64, threshold: f64, run_id: String,
+  ) -> Result<RunReport, String>
+
+  #[tauri::command]
+  pub async fn resolve_comparison(
+      workspace: String, run_id: String, device_key: String, name: String, decision: String,
+  ) -> Result<(), String>
+  ```
+  `RunReport { run_id, device_key, comparisons }` (le front lira `run_id`/`device_key`/`comparisons`). `compare_screenshots` copie d'abord chaque PNG produit (à côté du flow) dans `<workspace>/maestro/.runs/<run_id>/`, lance `compare_flow`, puis écrit un `report.json` *slim* (sans b64) dans ce même dossier.
+  `resolve_comparison` : `decision == "replace"` → copie `.runs/<run_id>/<name>.png` → `bank/<device_key>/<name>.png` (écrase la référence). `decision == "keep"` → no-op (banque inchangée, régression déjà tracée).
+
+- [ ] **Step 1: Écrire le test qui échoue (résolution `replace`)**
+
+Créer `src-tauri/src/bank/ipc.rs` avec en-tête licence, types + commandes en `todo!()`, et un test
+unitaire sur la fonction pure de remplacement (la logique testable hors Tauri) :
+
+```rust
+// Copyright (c) 2026 Ethan Morisset
+// SPDX-License-Identifier: BUSL-1.1
+
+use std::fs;
+use std::path::Path;
+
+use serde::Serialize;
+
+use crate::bank::compare::{compare_flow, CompareInput, Comparison};
+
+#[derive(Serialize, Clone)]
+pub struct RunReport {
+    pub run_id: String,
+    pub device_key: String,
+    pub comparisons: Vec<Comparison>,
+}
+
+/// Remplace l'image de banque `<workspace>/maestro/bank/<key>/<name>.png`
+/// par la nouvelle capture stockée dans `<workspace>/maestro/.runs/<run_id>/<name>.png`.
+/// (La nouvelle capture est copiée dans le dossier de run par `compare_screenshots`.)
+pub fn replace_bank_image(workspace: &Path, run_id: &str, device_key: &str, name: &str) -> std::io::Result<()> {
+    todo!()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn replace_overwrites_bank_with_run_image() {
+        let ws = std::env::temp_dir().join("mdbank_replace");
+        let _ = fs::remove_dir_all(&ws);
+        let bank = ws.join("maestro/bank/Dev_2x2");
+        let run = ws.join("maestro/.runs/r1");
+        fs::create_dir_all(&bank).unwrap();
+        fs::create_dir_all(&run).unwrap();
+        fs::write(bank.join("home.png"), b"OLD").unwrap();
+        fs::write(run.join("home.png"), b"NEW").unwrap();
+
+        replace_bank_image(&ws, "r1", "Dev_2x2", "home").unwrap();
+        assert_eq!(fs::read(bank.join("home.png")).unwrap(), b"NEW");
+    }
+}
+```
+
+Ajouter `pub mod ipc;` dans `mod.rs`.
+
+- [ ] **Step 2: Lancer le test, vérifier l'échec**
+
+Run: `cd src-tauri && cargo test bank::ipc`
+Expected: PANIC `not yet implemented`.
+
+- [ ] **Step 3: Implémenter les commandes + helper**
+
+Dans `ipc.rs`, implémenter `replace_bank_image` et les deux commandes. `compare_screenshots`
+copie chaque PNG produit (à côté du flow) dans le dossier de run **avant** de comparer, pour que
+`resolve replace` ait une source stable ; il écrit aussi le `report.json` slim.
+
+```rust
+pub fn replace_bank_image(workspace: &Path, run_id: &str, device_key: &str, name: &str) -> std::io::Result<()> {
+    let src = workspace.join("maestro").join(".runs").join(run_id).join(format!("{name}.png"));
+    let dst = workspace.join("maestro").join("bank").join(device_key).join(format!("{name}.png"));
+    if let Some(parent) = dst.parent() {
+        fs::create_dir_all(parent)?;
+    }
+    fs::copy(src, dst)?;
+    Ok(())
+}
+
+#[tauri::command]
+pub async fn compare_screenshots(
+    workspace: String,
+    flow_path: String,
+    model: String,
+    width: u32,
+    height: u32,
+    tolerance: f64,
+    threshold: f64,
+    run_id: String,
+) -> Result<RunReport, String> {
+    let ws = std::path::PathBuf::from(&workspace);
+    let flow = std::path::PathBuf::from(&flow_path);
+    let flow_dir = flow.parent().map(|p| p.to_path_buf()).unwrap_or_default();
+
+    // Copier les PNG produits dans le dossier de run (source stable pour `replace`).
+    let run_dir = ws.join("maestro").join(".runs").join(&run_id);
+    fs::create_dir_all(&run_dir).map_err(|e| e.to_string())?;
+    let yaml = fs::read_to_string(&flow).unwrap_or_default();
+    for name in crate::bank::flow::screenshot_names(&yaml) {
+        let produced = flow_dir.join(format!("{name}.png"));
+        if produced.exists() {
+            let _ = fs::copy(&produced, run_dir.join(format!("{name}.png")));
+        }
+    }
+
+    let (device_key, comparisons) = compare_flow(CompareInput {
+        workspace: &ws,
+        flow_path: &flow,
+        model: &model,
+        width,
+        height,
+        tolerance,
+        threshold,
+    })
+    .map_err(|e| e.to_string())?;
+
+    // report.json slim (statuts seulement, sans base64).
+    let slim: Vec<_> = comparisons
+        .iter()
+        .map(|c| serde_json::json!({ "name": c.name, "status": c.status, "changed_ratio": c.changed_ratio }))
+        .collect();
+    let report = serde_json::json!({ "run_id": run_id, "device_key": device_key, "comparisons": slim });
+    let _ = fs::write(run_dir.join("report.json"), serde_json::to_vec_pretty(&report).unwrap_or_default());
+
+    Ok(RunReport { run_id, device_key, comparisons })
+}
+
+#[tauri::command]
+pub async fn resolve_comparison(
+    workspace: String,
+    run_id: String,
+    device_key: String,
+    name: String,
+    decision: String,
+) -> Result<(), String> {
+    if decision == "replace" {
+        // "replace" : la nouvelle capture (copiée dans le dossier de run) devient la vérité.
+        replace_bank_image(Path::new(&workspace), &run_id, &device_key, &name)
+            .map_err(|e| e.to_string())?;
+    }
+    // "keep" : régression confirmée, banque inchangée (déjà tracée dans report.json).
+    Ok(())
+}
+```
+
+- [ ] **Step 4: Enregistrer les commandes**
+
+Dans `src-tauri/src/lib.rs`, ajouter dans `tauri::generate_handler![ ... ]` (après `stop_flow,`) :
+
+```rust
+        bank::ipc::compare_screenshots,
+        bank::ipc::resolve_comparison,
+```
+
+- [ ] **Step 5: Lancer test + build, vérifier le succès**
+
+Run: `cd src-tauri && cargo test bank::ipc && cargo build`
+Expected: tests PASS, build OK (commandes enregistrées sans erreur de macro).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src-tauri/src/bank/ipc.rs src-tauri/src/bank/mod.rs src-tauri/src/lib.rs
+git commit -m "feat(bank): compare_screenshots + resolve_comparison tauri commands"
+```
+
+---
+
+### Task 6: CWD du runner = dossier du flow
+
+**Files:**
+- Modify: `src-tauri/src/runner/mod.rs` (4 sites `Command::new(...)` : lignes ~126, ~212, ~291, ~426)
+
+**Interfaces:**
+- Aucune nouvelle interface publique ; comportement : les `takeScreenshot` de Maestro écrivent
+  `<nom>.png` dans le dossier du fichier flow.
+
+- [ ] **Step 1: Insérer `.current_dir(...)` dans `spawn_runner`**
+
+Avant le `.spawn()` de la commande maestro (après le dernier `.arg(flow_path)` / `.args(&env_args)`,
+juste avant `.stdout(Stdio::piped())`), insérer (calculer le dossier parent une fois en haut de la fn) :
+
+```rust
+let flow_dir = std::path::Path::new(flow_path)
+    .parent()
+    .map(|p| p.to_path_buf())
+    .unwrap_or_else(|| std::path::PathBuf::from("."));
+```
+
+puis sur la chaîne `Command::new(&bin)` ajouter `.current_dir(&flow_dir)` :
+
+```rust
+let mut child = Command::new(&bin)
+    .no_window()
+    .args(["--udid", serial, "test"])
+    .args(&env_args)
+    .arg(flow_path)
+    .current_dir(&flow_dir)
+    .stdout(Stdio::piped())
+    .stderr(Stdio::piped())
+    .kill_on_drop(true)
+    .spawn()
+```
+
+- [ ] **Step 2: Répéter pour les 3 autres runners**
+
+Appliquer la même `flow_dir` + `.current_dir(&flow_dir)` dans `spawn_web_runner` (~212),
+`spawn_ios_runner` (~291), `spawn_ios_device_runner` (~426). (Le binaire maestro reçoit `flow_path`
+en chemin relatif/absolu inchangé — un chemin absolu reste valide quel que soit le CWD.)
+
+- [ ] **Step 3: Vérifier la compilation**
+
+Run: `cd src-tauri && cargo build`
+Expected: build OK.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src-tauri/src/runner/mod.rs
+git commit -m "feat(runner): set CWD to flow directory so takeScreenshot lands next to flow"
+```
+
+---
+
+### Task 7: Store de réglages `visualRegressionStore`
+
+**Files:**
+- Create: `src/stores/visualRegressionStore.ts`
+- Create: `src/stores/visualRegressionStore.test.ts`
+
+**Interfaces:**
+- Produces:
+  ```ts
+  export const DEFAULT_TOLERANCE = 0.1;
+  export const DEFAULT_THRESHOLD = 0.001;
+  export interface VisualRegressionState {
+    tolerance: number | null;   // null → défaut
+    threshold: number | null;   // null → défaut
+    setTolerance: (v: number | null) => void;
+    setThreshold: (v: number | null) => void;
+    reset: () => void;
+  }
+  export const useVisualRegressionStore = create<VisualRegressionState>()(...);
+  export function effectiveThresholds(): { tolerance: number; threshold: number };
+  ```
+
+- [ ] **Step 1: Écrire le test qui échoue**
+
+Créer `src/stores/visualRegressionStore.test.ts` :
+
+```ts
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  useVisualRegressionStore,
+  effectiveThresholds,
+  DEFAULT_TOLERANCE,
+  DEFAULT_THRESHOLD,
+} from "@/stores/visualRegressionStore";
+
+describe("visualRegressionStore", () => {
+  beforeEach(() => useVisualRegressionStore.getState().reset());
+
+  it("returns defaults when unset", () => {
+    expect(effectiveThresholds()).toEqual({
+      tolerance: DEFAULT_TOLERANCE,
+      threshold: DEFAULT_THRESHOLD,
+    });
+  });
+
+  it("uses custom values when set", () => {
+    useVisualRegressionStore.getState().setTolerance(0.2);
+    useVisualRegressionStore.getState().setThreshold(0.05);
+    expect(effectiveThresholds()).toEqual({ tolerance: 0.2, threshold: 0.05 });
+  });
+});
+```
+
+- [ ] **Step 2: Lancer le test, vérifier l'échec**
+
+Run: `pnpm test src/stores/visualRegressionStore.test.ts`
+Expected: FAIL (module introuvable).
+
+- [ ] **Step 3: Implémenter le store (calqué sur `billyPromptStore.ts`)**
+
+Créer `src/stores/visualRegressionStore.ts` :
+
+```ts
+// Copyright (c) 2026 Ethan Morisset
+// SPDX-License-Identifier: BUSL-1.1
+
+import { create } from "zustand";
+import { persist, createJSONStorage } from "zustand/middleware";
+
+export const DEFAULT_TOLERANCE = 0.1;
+export const DEFAULT_THRESHOLD = 0.001;
+
+export interface VisualRegressionState {
+  tolerance: number | null;
+  threshold: number | null;
+  setTolerance: (v: number | null) => void;
+  setThreshold: (v: number | null) => void;
+  reset: () => void;
+}
+
+export const useVisualRegressionStore = create<VisualRegressionState>()(
+  persist(
+    (set) => ({
+      tolerance: null,
+      threshold: null,
+      setTolerance: (v) => set({ tolerance: v }),
+      setThreshold: (v) => set({ threshold: v }),
+      reset: () => set({ tolerance: null, threshold: null }),
+    }),
+    {
+      name: "maestro-deck.visual-regression",
+      storage: createJSONStorage(() => localStorage),
+    },
+  ),
+);
+
+export function effectiveThresholds(): { tolerance: number; threshold: number } {
+  const { tolerance, threshold } = useVisualRegressionStore.getState();
+  return {
+    tolerance: tolerance ?? DEFAULT_TOLERANCE,
+    threshold: threshold ?? DEFAULT_THRESHOLD,
+  };
+}
+```
+
+- [ ] **Step 4: Lancer le test, vérifier le succès**
+
+Run: `pnpm test src/stores/visualRegressionStore.test.ts`
+Expected: PASS (2 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/stores/visualRegressionStore.ts src/stores/visualRegressionStore.test.ts
+git commit -m "feat(settings): visual regression thresholds store"
+```
+
+---
+
+### Task 8: Bindings IPC front + types
+
+**Files:**
+- Modify: `src/lib/ipc.ts` (ajouter `compareScreenshots`, `resolveComparison` dans `ipc`)
+- Create: `src/types/visualRegression.ts`
+
+**Interfaces:**
+- Consumes: commandes Rust `compare_screenshots`, `resolve_comparison`.
+- Produces:
+  ```ts
+  // src/types/visualRegression.ts
+  export type ComparisonStatus = "seeded" | "match" | "changed" | "missing" | "dimension_mismatch";
+  export interface Comparison {
+    name: string;
+    status: ComparisonStatus;
+    changed_ratio: number;
+    bbox: [number, number, number, number] | null;
+    bank_b64?: string;
+    new_b64?: string;
+    diff_b64?: string;
+  }
+  export interface RunReport {
+    run_id: string;
+    device_key: string;
+    comparisons: Comparison[];
+  }
+
+  // ajoutés à l'objet `ipc` :
+  compareScreenshots(args: {
+    workspace: string; flowPath: string; model: string; width: number; height: number;
+    tolerance: number; threshold: number; runId: string;
+  }): Promise<RunReport>;
+  resolveComparison(args: {
+    workspace: string; runId: string; deviceKey: string; name: string; decision: "keep" | "replace";
+  }): Promise<void>;
+  ```
+
+- [ ] **Step 1: Créer les types**
+
+Créer `src/types/visualRegression.ts` avec l'en-tête licence et les types ci-dessus
+(`ComparisonStatus`, `Comparison`, `RunReport`).
+
+- [ ] **Step 2: Ajouter les bindings dans `src/lib/ipc.ts`**
+
+Importer les types en haut du fichier :
+
+```ts
+import type { RunReport } from "@/types/visualRegression";
+```
+
+Dans l'objet `ipc` (à côté de `runFlow`/`stopFlow`), ajouter — les clés d'argument correspondent
+aux noms de paramètres Rust (Tauri convertit camelCase→snake_case automatiquement) :
+
+```ts
+  compareScreenshots: (args: {
+    workspace: string; flowPath: string; model: string; width: number; height: number;
+    tolerance: number; threshold: number; runId: string;
+  }) => call<RunReport>("compare_screenshots", args),
+  resolveComparison: (args: {
+    workspace: string; runId: string; deviceKey: string; name: string; decision: "keep" | "replace";
+  }) => call<void>("resolve_comparison", args),
+```
+
+- [ ] **Step 3: Vérifier le typecheck**
+
+Run: `pnpm typecheck`
+Expected: aucune erreur.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/lib/ipc.ts src/types/visualRegression.ts
+git commit -m "feat(ipc): bindings + types for screenshot comparison"
+```
+
+---
+
+### Task 9: Section Paramètres « Régression visuelle »
+
+**Files:**
+- Create: `src/components/settings/VisualRegressionSettings.tsx`
+- Modify: `src/components/settings/sections.tsx` (ajouter l'entrée + import)
+
+**Interfaces:**
+- Consumes: `useVisualRegressionStore`, `DEFAULT_TOLERANCE`, `DEFAULT_THRESHOLD`, `SettingsSection`.
+
+- [ ] **Step 1: Créer le composant (calqué sur `BillySettings.tsx`)**
+
+Créer `src/components/settings/VisualRegressionSettings.tsx` :
+
+```tsx
+// Copyright (c) 2026 Ethan Morisset
+// SPDX-License-Identifier: BUSL-1.1
+
+import { Button } from "@/components/ui/Button";
+import { SettingsSection } from "@/components/settings/SettingsPrimitives";
+import {
+  useVisualRegressionStore,
+  DEFAULT_TOLERANCE,
+  DEFAULT_THRESHOLD,
+} from "@/stores/visualRegressionStore";
+
+export function VisualRegressionSettings() {
+  const tolerance = useVisualRegressionStore((s) => s.tolerance);
+  const threshold = useVisualRegressionStore((s) => s.threshold);
+  const setTolerance = useVisualRegressionStore((s) => s.setTolerance);
+  const setThreshold = useVisualRegressionStore((s) => s.setThreshold);
+  const reset = useVisualRegressionStore((s) => s.reset);
+
+  const isCustomized = tolerance !== null || threshold !== null;
+
+  return (
+    <SettingsSection
+      title="Régression visuelle"
+      description="Seuils de comparaison des screenshots de la banque. La tolérance contrôle la sensibilité par pixel (échelle pixelmatch). Le seuil est la part de pixels modifiés au-delà de laquelle un screenshot est signalé."
+    >
+      <div className="flex flex-col gap-3">
+        <label className="flex flex-col gap-1 text-sm">
+          <span>Tolérance par pixel (défaut {DEFAULT_TOLERANCE})</span>
+          <input
+            type="number"
+            step="0.01"
+            min="0"
+            max="1"
+            value={tolerance ?? DEFAULT_TOLERANCE}
+            onChange={(e) =>
+              setTolerance(e.target.value === "" ? null : Number(e.target.value))
+            }
+            className="w-32 rounded border border-neutral-300 bg-transparent px-2 py-1 dark:border-neutral-700"
+          />
+        </label>
+        <label className="flex flex-col gap-1 text-sm">
+          <span>Seuil de pixels changés (défaut {DEFAULT_THRESHOLD})</span>
+          <input
+            type="number"
+            step="0.001"
+            min="0"
+            max="1"
+            value={threshold ?? DEFAULT_THRESHOLD}
+            onChange={(e) =>
+              setThreshold(e.target.value === "" ? null : Number(e.target.value))
+            }
+            className="w-32 rounded border border-neutral-300 bg-transparent px-2 py-1 dark:border-neutral-700"
+          />
+        </label>
+        <div>
+          <Button size="sm" variant="outline" onClick={reset} disabled={!isCustomized}>
+            Réinitialiser
+          </Button>
+        </div>
+      </div>
+    </SettingsSection>
+  );
+}
+```
+
+- [ ] **Step 2: Enregistrer la section**
+
+Dans `src/components/settings/sections.tsx`, importer en haut :
+
+```tsx
+import { VisualRegressionSettings } from "@/components/settings/VisualRegressionSettings";
+```
+
+et ajouter dans `SETTINGS_SECTIONS` (avant `about`) :
+
+```tsx
+  { id: "visual-regression", label: "Régression visuelle", render: () => <VisualRegressionSettings /> },
+```
+
+- [ ] **Step 3: Vérifier typecheck + lint**
+
+Run: `pnpm typecheck && pnpm lint`
+Expected: aucune erreur.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/components/settings/VisualRegressionSettings.tsx src/components/settings/sections.tsx
+git commit -m "feat(settings): visual regression thresholds section"
+```
+
+---
+
+### Task 10: Store de revue + orchestration post-run
+
+**Files:**
+- Create: `src/stores/reviewStore.ts`
+- Modify: `src/App.tsx` (handler `onRunnerExit`, lignes ~131-141 ; et accès au flow courant)
+
+**Interfaces:**
+- Consumes: `ipc.compareScreenshots`, `effectiveThresholds`, `RunReport`, stores workspace/device, chemin du flow courant.
+- Produces:
+  ```ts
+  export interface ReviewState {
+    report: RunReport | null;
+    queue: string[];          // noms des comparaisons à revoir (status changed/dimension_mismatch)
+    open: boolean;
+    setReport: (r: RunReport | null) => void;
+    next: () => void;         // retire la tête de queue ; ferme si vide
+    close: () => void;
+  }
+  export const useReviewStore = create<ReviewState>()(...);
+  ```
+
+- [ ] **Step 1: Créer le store de revue**
+
+Créer `src/stores/reviewStore.ts` :
+
+```ts
+// Copyright (c) 2026 Ethan Morisset
+// SPDX-License-Identifier: BUSL-1.1
+
+import { create } from "zustand";
+import type { RunReport } from "@/types/visualRegression";
+
+const REVIEWABLE = new Set(["changed", "dimension_mismatch"]);
+
+export interface ReviewState {
+  report: RunReport | null;
+  queue: string[];
+  open: boolean;
+  setReport: (r: RunReport | null) => void;
+  next: () => void;
+  close: () => void;
+}
+
+export const useReviewStore = create<ReviewState>((set, get) => ({
+  report: null,
+  queue: [],
+  open: false,
+  setReport: (r) => {
+    const queue = r ? r.comparisons.filter((c) => REVIEWABLE.has(c.status)).map((c) => c.name) : [];
+    set({ report: r, queue, open: queue.length > 0 });
+  },
+  next: () => {
+    const queue = get().queue.slice(1);
+    set({ queue, open: queue.length > 0 });
+  },
+  close: () => set({ open: false, queue: [] }),
+}));
+```
+
+- [ ] **Step 2: Identifier le flow courant dans `App.tsx`**
+
+Repérer comment `onRun` connaît le fichier de flow lancé (probablement via `runStore`/`workspaceStore`,
+ex. `useWorkspaceStore.getState().lastOpenFile`). Utiliser ce chemin comme `flowPath`. Si plusieurs
+flows (Run All), le handler s'exécute pour le flow effectivement lancé — réutiliser la même source que
+`ipc.runFlow(filePath, ...)`.
+
+- [ ] **Step 3: Brancher la comparaison sur `onRunnerExit`**
+
+Dans `src/App.tsx`, dans le handler `events.onRunnerExit(({ code }) => { ... })`, après `setStopped(code)`,
+ajouter (n'agir que si succès et contexte disponible) :
+
+```ts
+        if (code === 0) {
+          const ws = useWorkspaceStore.getState().folderPath;
+          const device = useDeviceStore.getState().current;
+          const flowPath = useWorkspaceStore.getState().lastOpenFile; // même source que runFlow
+          if (ws && device && flowPath) {
+            const { tolerance, threshold } = effectiveThresholds();
+            const runId = String(useRunStore.getState().pid ?? Date.now());
+            ipc
+              .compareScreenshots({
+                workspace: ws,
+                flowPath,
+                model: device.model,
+                width: device.screen_width,
+                height: device.screen_height,
+                tolerance,
+                threshold,
+                runId,
+              })
+              .then((report) => useReviewStore.getState().setReport(report))
+              .catch((err) => console.error("compare_screenshots failed", err));
+          }
+        }
+```
+
+Ajouter les imports nécessaires en haut de `App.tsx` :
+
+```ts
+import { useReviewStore } from "@/stores/reviewStore";
+import { effectiveThresholds } from "@/stores/visualRegressionStore";
+import { useWorkspaceStore } from "@/stores/workspaceStore";
+import { useDeviceStore } from "@/stores/deviceStore";
+// `ipc`, `useRunStore` sont déjà importés ; sinon les ajouter.
+```
+
+> `runId` = PID du run (déjà unique et présent dans `runStore`). À défaut, `Date.now()`.
+
+- [ ] **Step 4: Vérifier typecheck**
+
+Run: `pnpm typecheck`
+Expected: aucune erreur.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/stores/reviewStore.ts src/App.tsx
+git commit -m "feat(review): trigger comparison on successful run, queue reviewable diffs"
+```
+
+---
+
+### Task 11: Modale de revue `ScreenshotReview`
+
+**Files:**
+- Create: `src/components/ScreenshotReview.tsx`
+- Modify: `src/components/MainView.tsx` (monter `<ScreenshotReview />` à côté de `RunConsole`, ~ligne 296)
+
+**Interfaces:**
+- Consumes: `useReviewStore`, `ipc.resolveComparison`, `useWorkspaceStore`, `Comparison`.
+- Produces: composant sans props `export function ScreenshotReview()`.
+
+- [ ] **Step 1: Créer la modale**
+
+Créer `src/components/ScreenshotReview.tsx`. Affiche la comparaison en tête de `queue` :
+gauche = banque (`bank_b64`), droite = nouvelle (`new_b64`) avec la bbox encadrée ; toggle overlay diff
+(`diff_b64`). Deux actions appellent `resolveComparison` puis `next()`.
+
+```tsx
+// Copyright (c) 2026 Ethan Morisset
+// SPDX-License-Identifier: BUSL-1.1
+
+import { useState } from "react";
+
+import { Button } from "@/components/ui/Button";
+import { ipc } from "@/lib/ipc";
+import { useReviewStore } from "@/stores/reviewStore";
+import { useWorkspaceStore } from "@/stores/workspaceStore";
+
+export function ScreenshotReview() {
+  const open = useReviewStore((s) => s.open);
+  const report = useReviewStore((s) => s.report);
+  const queue = useReviewStore((s) => s.queue);
+  const next = useReviewStore((s) => s.next);
+  const [showDiff, setShowDiff] = useState(true); // overlay diff visible par défaut
+
+  if (!open || !report || queue.length === 0) return null;
+  const name = queue[0];
+  const comp = report.comparisons.find((c) => c.name === name);
+  if (!comp) return null;
+
+  const workspace = useWorkspaceStore.getState().folderPath ?? "";
+
+  const decide = async (decision: "keep" | "replace") => {
+    try {
+      await ipc.resolveComparison({
+        workspace,
+        runId: report.run_id,
+        deviceKey: report.device_key,
+        name,
+        decision,
+      });
+    } catch (err) {
+      console.error("resolve_comparison failed", err);
+    } finally {
+      setShowDiff(false);
+      next();
+    }
+  };
+
+  const bbox = comp.bbox;
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/60">
+      <div className="flex max-h-[90vh] w-[90vw] max-w-5xl flex-col gap-3 rounded-lg bg-white p-4 shadow-xl dark:bg-neutral-900">
+        <div className="flex items-center justify-between">
+          <h2 className="text-sm font-semibold">
+            Régression visuelle — « {name} » ({queue.length} restant{queue.length > 1 ? "s" : ""})
+          </h2>
+          <label className="flex items-center gap-1 text-xs">
+            <input type="checkbox" checked={showDiff} onChange={(e) => setShowDiff(e.target.checked)} />
+            Overlay diff
+          </label>
+        </div>
+
+        <div className="grid grid-cols-2 gap-3 overflow-auto">
+          <figure className="flex flex-col items-center gap-1">
+            <figcaption className="text-xs text-neutral-500">Banque (référence)</figcaption>
+            <img src={comp.bank_b64} alt="banque" className="max-h-[70vh] object-contain" />
+          </figure>
+          <figure className="flex flex-col items-center gap-1">
+            <figcaption className="text-xs text-neutral-500">
+              Nouvelle capture {bbox ? "(zone changée en rouge via l'overlay)" : ""}
+            </figcaption>
+            <img
+              src={showDiff ? comp.diff_b64 ?? comp.new_b64 : comp.new_b64}
+              alt="nouvelle"
+              className="max-h-[70vh] object-contain"
+            />
+          </figure>
+        </div>
+
+        <div className="flex justify-end gap-2">
+          <Button size="sm" variant="outline" onClick={() => void decide("keep")}>
+            Garder la banque (régression)
+          </Button>
+          <Button size="sm" onClick={() => void decide("replace")}>
+            Remplacer par la nouvelle
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+> Localisation du changement : en v1, l'**overlay diff** (pixels rouges, visible par défaut) est le
+> moyen visuel principal de repérer la zone qui a varié — robuste quel que soit le scaling
+> `object-contain`. La `bbox` est conservée dans le rapport (utile pour une v2 qui dessinerait un
+> encadré à l'échelle), mais pas rendue comme rectangle superposé en v1.
+
+- [ ] **Step 2: Monter la modale**
+
+Dans `src/components/MainView.tsx`, près du `<RunConsole .../>` (~ligne 296), ajouter en frère :
+
+```tsx
+<ScreenshotReview />
+```
+
+et l'import en haut :
+
+```tsx
+import { ScreenshotReview } from "@/components/ScreenshotReview";
+```
+
+- [ ] **Step 3: Vérifier typecheck + lint + build**
+
+Run: `pnpm typecheck && pnpm lint && pnpm test`
+Expected: aucune erreur ; tests existants + nouveaux PASS.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/components/ScreenshotReview.tsx src/components/MainView.tsx
+git commit -m "feat(review): screenshot comparison review modal (keep/replace)"
+```
+
+---
+
+## Vérification finale (manuelle, après toutes les tâches)
+
+- [ ] `cd src-tauri && cargo test` → tous les tests `bank::*` PASS.
+- [ ] `pnpm test && pnpm typecheck && pnpm lint` → OK.
+- [ ] `pnpm tauri:dev` : ouvrir un workspace, connecter un device, lancer un flow contenant
+  `takeScreenshot: <nom>`.
+  - 1er run (banque vide) → aucune modale ; `<workspace>/maestro/bank/<key>/<nom>.png` créé.
+  - Modifier l'app pour provoquer un changement visuel, relancer → modale de revue s'ouvre
+    (gauche banque / droite nouvelle + overlay diff).
+  - « Remplacer » → `bank/<key>/<nom>.png` mis à jour. « Garder » → banque inchangée.
+  - Run en échec (exit ≠ 0) → aucune modale, aucune écriture banque.
+- [ ] Paramètres → section « Régression visuelle » : modifier les seuils, vérifier la persistance
+  (recharger l'app), « Réinitialiser » revient aux défauts.
+```

From d2ff273aeef6d3ea59b07a4d76e53998abe1708b Mon Sep 17 00:00:00 2001
From: Ethan <mrcalcifer123@gmail.com>
Date: Tue, 7 Jul 2026 20:24:39 +0200
Subject: [PATCH 18/18] fix(lint): fix lint

---
 src/App.tsx | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/src/App.tsx b/src/App.tsx
index ad0a53e..eaea44d 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -214,9 +214,7 @@ export default function App() {
   // the effect to re-run, stopping the old collector and starting a new one for
   // the correct device.
   const deviceKey = useDeviceStore((s) =>
-    s.current
-      ? `${s.current.serial}:${s.current.platform}:${String(s.current.physical)}`
-      : null,
+    s.current ? `${s.current.serial}:${s.current.platform}:${String(s.current.physical)}` : null,
   );
 
   useEffect(() => {