fix(exploration): normalize displayLabel keys, score-first ordering, persistence compat

Author: jfarcand

CONTRIBUTING.md

@@ -164,9 +164,10 @@ mirroir-mcp/
 │   │   └── ProcessExtensions.swift  # Timeout-aware Process.wait
 │   │
 │   └── FakeMirroring/               # Test double app for CI (not a mock — a real macOS app)
-│       ├── main.swift               # Entry point
-│       ├── FakeScreenDrawing.swift  # Renders OCR-detectable text labels
-│       └── Scenarios.swift          # Screen scenarios for integration tests
+│       ├── main.swift               # Entry point, window setup, input handling
+│       ├── FakeScreenDrawing.swift  # Renders OCR-detectable text labels, cards, tab bars
+│       ├── Scenarios.swift          # Screen scenarios + NavigationMap for tap routing
+│       └── HealthScenarios.swift    # Health-related scenarios (extracted for file size)
 │
 ├── Tests/
 │   ├── MCPServerTests/        # XCTest — server routing, tool handlers, exploration (71 files)
@@ -390,6 +391,120 @@ All timing and numeric constants can be overridden via environment variables. Th
 |----------|---------|-------------|
 | `IPHONE_KEYBOARD_LAYOUT` | *(not set)* | Opt-in non-US keyboard layout for character translation (e.g., `Canadian-CSA` or `com.apple.keylayout.Canadian-CSA`). When unset, US QWERTY keycodes are sent. |
 
+## FakeMirroring
+
+FakeMirroring is a real macOS app that stands in for iPhone Mirroring during testing. It renders OCR-detectable text at known positions, responds to CGEvent taps, and supports scrolling — everything the real mirroring window does, without needing a physical iPhone.
+
+### Build & Run
+
+```bash
+swift build -c release --product FakeMirroring
+./scripts/package-fake-app.sh
+open .build/release/FakeMirroring.app
+```
+
+The app window is 410x898pt (matching iPhone screen dimensions) and floats above other windows so CGEvent taps always land on it.
+
+### Scenarios
+
+FakeMirroring renders different screen layouts via **scenarios**. Switch scenarios from the Scenario menu or programmatically via `bridge.triggerMenuAction(menu: "Scenario", item: "Settings")`.
+
+Key scenarios:
+
+| Scenario | Content | Navigation |
+|----------|---------|------------|
+| `settings` | 6 rows with chevrons (General, Privacy, etc.) | General → detail, Notifications → notifications |
+| `detailWithBack` | Detail screen with `<` back button | `<` → back to source |
+| `healthSummary` | 3 viewports: cards + setup rows + articles | Activity/Workouts/Steps → detailWithBack |
+| `scrollableList` | 20 rows at 60pt spacing (scroll testing) | General → detail |
+| `feed` | Instagram-style posts with images | Tab bar navigation |
+
+### Adding a Scenario
+
+1. Add a case to `FakeScenario` enum in `Scenarios.swift`
+2. Add a `static func myScenario() -> ScenarioData` in the appropriate file (extract to a new file if `Scenarios.swift` is near 500 lines)
+3. Wire it in `ScenarioContent.data(for:)` switch
+4. Add tap routing in `NavigationMap.destination(from:tapping:)` — return the target scenario for each tappable label, or `nil` for dead taps
+
+`ScenarioData` supports: `rows` (label + chevron), `cards` (Health-style summary cards), `plainTexts`, `buttons`, `placeholders`, and `hasTabBar` / `hasBackChevron`.
+
+### NavigationMap
+
+`NavigationMap.destination(from: scenario, tapping: label)` defines what happens when a label is tapped. Returns the target `FakeScenario` for navigation, or `nil` if the tap is a dead tap (no screen change). The BFS explorer uses this to discover new screens during integration tests.
+
+### Input Handling
+
+FakeMirroring handles: mouse clicks (tap), `scrollWheel` (swipe/scroll), `mouseDragged` (drag), long press (0.4s threshold), double tap (0.3s gap), and `keyDown` (text field typing). Hit regions are computed from rendered element positions. The `AlwaysAcceptingWindow` subclass accepts mouse events even when not the key window, so CGEvent-posted taps work during integration tests.
+
+## Integration Tests
+
+Integration tests in `Tests/IntegrationTests/` run real OCR against FakeMirroring's rendered text. They exercise the full pipeline: OCR → coordinate mapping → CGEvent tap → verify screen change.
+
+### Running
+
+```bash
+# Build and launch FakeMirroring first
+swift build -c release --product FakeMirroring
+./scripts/package-fake-app.sh
+open .build/release/FakeMirroring.app
+
+# Run integration tests (FakeMirroring must be visible)
+swift test --filter IntegrationTests
+
+# Run a single test
+swift test --filter BFSExplorationIntegrationTests/testMultiViewportExploration
+```
+
+Integration tests are **skipped in CI** (`swift test --skip IntegrationTests`) because they require a visible macOS window and CGEvent access. They run locally before merging.
+
+### Test Pattern
+
+Every integration test follows this pattern:
+
+```swift
+override func setUpWithError() throws {
+    try IntegrationTestHelper.ensureFakeMirroringRunning()
+    bridge = MirroringBridge(bundleID: IntegrationTestHelper.fakeBundleID)
+    guard IntegrationTestHelper.ensureWindowReady(bridge: bridge) else {
+        throw IntegrationTestError.windowNotCapturable
+    }
+    describer = ScreenDescriber(bridge: bridge, capture: ScreenCapture(bridge: bridge))
+    input = InputSimulation(bridge: bridge)
+
+    _ = bridge.triggerMenuAction(menu: "Scenario", item: "Settings")
+    usleep(500_000)
+}
+
+override func tearDown() {
+    // Restore default scenario for other tests
+    _ = bridge?.triggerMenuAction(menu: "Scenario", item: "Settings")
+    usleep(500_000)
+}
+```
+
+Tests create `ScreenDescriber`, `InputSimulation`, and `ExplorationSession` directly — no MCP transport needed.
+
+### Testing BFS Exploration
+
+Two approaches, use the right one:
+
+| Approach | When to use | Speed |
+|----------|-------------|-------|
+| **Unit tests** (`MockExplorerDescriber`) | Testing scroll logic, plan building, action counters, specific code paths | Fast (~2s) |
+| **Integration tests** (FakeMirroring) | Testing full exploration loop with real OCR, tap routing, backtracking | Slow (~2min) |
+
+Unit test mocks return a pre-defined sequence of screens. Integration tests use real OCR output that varies slightly between runs. Use `seed: 42` for deterministic tap ordering in integration tests.
+
+## Component Skills
+
+Component definitions are `.md` files that describe iOS UI patterns (table rows, summary cards, modal sheets). The BFS explorer matches OCR elements against these definitions to decide what to tap.
+
+Definitions live in the sibling [mirroir-skills](https://github.com/jfarcand/mirroir-skills) repo at `components/ios/`. They're loaded at runtime from `~/.mirroir-mcp/skills/components/ios/` or `<cwd>/.mirroir-mcp/skills/components/ios/` or `../mirroir-skills/components/ios/`.
+
+Each definition has: Match Rules (zone, element count, chevron/numeric patterns), Interaction (click target, expected result), Exploration (explorable flag, role, priority), and Grouping (row absorption).
+
+Test a definition against the current live screen with `calibrate_component`. See [Component Detection](docs/components.md) for the full format.
+
 ## Code Conventions
 
 ### File Headers

Sources/mirroir-mcp/ComponentSkillParser.swift

@@ -414,10 +414,20 @@ enum ComponentSkillParser {
         _ text: String, interaction: ComponentInteraction
     ) -> ComponentExploration {
         let kv = extractKeyValues(from: text)
+        let roleStr = kv["role"] ?? "depth_navigation"
+        let priorityStr = kv["priority"] ?? "normal"
+        if kv["role"] != nil && ExplorationRole(rawValue: roleStr) == nil {
+            DebugLog.log("components",
+                "WARNING: invalid exploration role '\(roleStr)' — defaulting to depth_navigation")
+        }
+        if kv["priority"] != nil && ExplorationPriority(rawValue: priorityStr) == nil {
+            DebugLog.log("components",
+                "WARNING: invalid exploration priority '\(priorityStr)' — defaulting to normal")
+        }
         return ComponentExploration(
             explorable: parseBool(kv["explorable"]) ?? interaction.clickable,
-            role: ExplorationRole(rawValue: kv["role"] ?? "depth_navigation") ?? .depthNavigation,
-            priority: ExplorationPriority(rawValue: kv["priority"] ?? "normal") ?? .normal
+            role: ExplorationRole(rawValue: roleStr) ?? .depthNavigation,
+            priority: ExplorationPriority(rawValue: priorityStr) ?? .normal
         )
     }
 

Sources/mirroir-mcp/GraphPathFinder.swift

@@ -212,7 +212,7 @@ enum GraphPathFinder {
         from path: [NavigationEdge],
         snapshot: GraphSnapshot
     ) -> String {
-        let labels = path.map(\.elementText).filter { !$0.isEmpty }
+        let labels = path.map(\.displayLabel).filter { !$0.isEmpty }
         if labels.isEmpty { return "exploration" }
 
         // Try landmark-based naming for longer paths

Sources/mirroir-mcp/GraphPersistence.swift

@@ -94,7 +94,8 @@ struct SerializableEdge: Codable, Sendable {
     let toFingerprint: String
     let actionType: String
     let elementText: String
-    let displayLabel: String
+    /// Optional for backward compatibility: v1 graphs lack displayLabel.
+    let displayLabel: String?
     let edgeType: String
     /// Learned action-value estimate. Optional for backward compatibility with v1 graphs.
     let qValue: Double?
@@ -115,7 +116,7 @@ struct SerializableEdge: Codable, Sendable {
             toFingerprint: toFingerprint,
             actionType: actionType,
             elementText: elementText,
-            displayLabel: displayLabel,
+            displayLabel: displayLabel ?? elementText,
             edgeType: EdgeType(rawValue: edgeType) ?? .push,
             qValue: qValue ?? 1.0
         )
@@ -133,8 +134,8 @@ struct SerializableGraph: Codable, Sendable {
     /// CEGAR refinement levels per fingerprint (optional for backward compatibility).
     let refinementLevels: [String: StateAbstraction.RefinementLevel]?
 
-    /// Current format version. Bump when the schema changes.
-    static let currentVersion = 1
+    /// Current format version. v2 added optional displayLabel on edges.
+    static let currentVersion = 2
 }
 
 /// Saves and loads NavigationGraph state to disk for incremental exploration.
@@ -203,9 +204,10 @@ enum GraphPersistence {
             decoder.dateDecodingStrategy = .iso8601
             let serializable = try decoder.decode(SerializableGraph.self, from: data)
 
-            guard serializable.version == SerializableGraph.currentVersion else {
-                DebugLog.log("persistence", "Stale graph version \(serializable.version) " +
-                    "for \(bundleID), expected \(SerializableGraph.currentVersion)")
+            // Accept v1 (legacy, no displayLabel on edges) and v2 (current).
+            guard serializable.version >= 1 && serializable.version <= SerializableGraph.currentVersion else {
+                DebugLog.log("persistence", "Unsupported graph version \(serializable.version) " +
+                    "for \(bundleID), expected 1–\(SerializableGraph.currentVersion)")
                 return nil
             }
 

Sources/mirroir-mcp/NavigationGraph.swift

@@ -336,6 +336,8 @@ final class NavigationGraph: @unchecked Sendable {
     }
 
     /// Get unvisited elements for a screen, filtered by the visited set.
+    /// Visited elements are stored by displayLabel (component-cleaned name),
+    /// so this comparison uses displayLabel-compatible matching.
     func unvisitedElements(for fingerprint: String) -> [TapPoint] {
         lock.lock()
         defer { lock.unlock() }

Sources/mirroir-mcp/NavigationGraphVerification.swift

@@ -123,13 +123,15 @@ extension NavigationGraph {
 
     /// Update Q-value for the most recent edge from a screen after observing the outcome.
     /// Called after `recordTransition` to learn from each action's result.
+    /// Matches on displayLabel (the clean component label) since the BFS explorer
+    /// passes displayLabel as the key for Q-updates and dead-edge marks.
     func updateQValue(fromFingerprint: String, elementText: String, result: TransitionResult) {
         lock.lock()
         defer { lock.unlock() }
 
-        // Find the edge to update (last matching edge in the adjacency list)
+        // Find the edge to update by displayLabel (BFS passes displayLabel as elementText)
         guard var edgeList = adjacency[fromFingerprint],
-              let idx = edgeList.lastIndex(where: { $0.elementText == elementText }) else {
+              let idx = edgeList.lastIndex(where: { $0.displayLabel == elementText }) else {
             return
         }
 
@@ -148,7 +150,7 @@ extension NavigationGraph {
 
         // Keep the flat edges array in sync
         if let flatIdx = edges.lastIndex(where: {
-            $0.fromFingerprint == fromFingerprint && $0.elementText == elementText
+            $0.fromFingerprint == fromFingerprint && $0.displayLabel == elementText
         }) {
             edges[flatIdx] = edge
         }
@@ -159,17 +161,18 @@ extension NavigationGraph {
         lock.lock()
         defer { lock.unlock() }
         return adjacency[fromFingerprint]?
-            .last(where: { $0.elementText == elementText })?.qValue ?? 1.0
+            .last(where: { $0.displayLabel == elementText })?.qValue ?? 1.0
     }
 
     // MARK: - Dead Edge Tracking
 
     /// Mark an edge as dead (tap had no effect on the screen).
     /// Dead edges are excluded from future exploration plans.
+    /// Uses displayLabel for consistency with Q-value lookups.
     ///
     /// - Parameters:
     ///   - fromFingerprint: The screen where the dead tap occurred.
-    ///   - elementText: The element text that was tapped.
+    ///   - elementText: The display label of the element that was tapped.
     func markEdgeDead(fromFingerprint: String, elementText: String) {
         lock.lock()
         defer { lock.unlock() }

Sources/mirroir-mcp/ScreenPlanner.swift

@@ -97,7 +97,7 @@ enum ScreenPlanner {
                 )
                 return RankedElement(point: element.point, score: score, reason: reason)
             }
-            .sorted { $0.point.tapY != $1.point.tapY ? $0.point.tapY < $1.point.tapY : $0.score > $1.score }
+            .sorted { $0.score != $1.score ? $0.score > $1.score : $0.point.tapY < $1.point.tapY }
     }
 
     // MARK: - Component-Based Plan Building
@@ -151,7 +151,7 @@ enum ScreenPlanner {
                 return RankedElement(point: tapTarget, score: score, reason: reason,
                     displayLabel: component.displayLabel, isBreadthNavigation: isBreadth)
             }
-            .sorted { $0.point.tapY != $1.point.tapY ? $0.point.tapY < $1.point.tapY : $0.score > $1.score }
+            .sorted { $0.score != $1.score ? $0.score > $1.score : $0.point.tapY < $1.point.tapY }
     }
 
     // MARK: - Private
@@ -320,6 +320,6 @@ enum ScreenPlanner {
                     isBreadthNavigation: element.isBreadthNavigation
                 )
             }
-            .sorted { $0.point.tapY != $1.point.tapY ? $0.point.tapY < $1.point.tapY : $0.score > $1.score }
+            .sorted { $0.score != $1.score ? $0.score > $1.score : $0.point.tapY < $1.point.tapY }
     }
 }