@lattices/cli 0.4.2 → 0.4.5

package/app/Sources/CompanionKeyboardController.swift

@@ -0,0 +1,141 @@
+import AppKit
+import Foundation
+
+enum CompanionKeyboardError: LocalizedError {
+    case unknownKey(String)
+    case eventSourceUnavailable
+
+    var errorDescription: String? {
+        switch self {
+        case .unknownKey(let key):
+            return "Unsupported key for forwarding: \(key)"
+        case .eventSourceUnavailable:
+            return "Unable to create a keyboard event source."
+        }
+    }
+}
+
+final class CompanionKeyboardController {
+    static let shared = CompanionKeyboardController()
+
+    private init() {}
+
+    func send(key rawKey: String, modifiers rawModifiers: [String]) throws -> String {
+        let parsed = parse(key: rawKey, modifiers: rawModifiers)
+        guard let keyCode = keyCode(for: parsed.key) else {
+            throw CompanionKeyboardError.unknownKey(rawKey)
+        }
+        guard let source = CGEventSource(stateID: .combinedSessionState) else {
+            throw CompanionKeyboardError.eventSourceUnavailable
+        }
+
+        let flags = eventFlags(for: parsed.modifiers)
+        guard
+            let down = CGEvent(keyboardEventSource: source, virtualKey: keyCode, keyDown: true),
+            let up = CGEvent(keyboardEventSource: source, virtualKey: keyCode, keyDown: false)
+        else {
+            throw CompanionKeyboardError.eventSourceUnavailable
+        }
+
+        down.flags = flags
+        up.flags = flags
+        down.post(tap: .cghidEventTap)
+        usleep(12_000)
+        up.post(tap: .cghidEventTap)
+
+        return displayName(key: parsed.key, modifiers: parsed.modifiers)
+    }
+}
+
+private extension CompanionKeyboardController {
+    func parse(key rawKey: String, modifiers rawModifiers: [String]) -> (key: String, modifiers: Set<String>) {
+        var modifiers = Set(rawModifiers.map(normalizeModifier).filter { !$0.isEmpty })
+        var key = rawKey
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .lowercased()
+
+        let symbolModifiers: [(String, String)] = [
+            ("⌘", "command"),
+            ("cmd", "command"),
+            ("command", "command"),
+            ("⌥", "option"),
+            ("option", "option"),
+            ("alt", "option"),
+            ("⌃", "control"),
+            ("ctrl", "control"),
+            ("control", "control"),
+            ("⇧", "shift"),
+            ("shift", "shift"),
+        ]
+
+        for (symbol, modifier) in symbolModifiers where key.contains(symbol) {
+            modifiers.insert(modifier)
+            key = key.replacingOccurrences(of: symbol, with: "")
+        }
+
+        key = key
+            .replacingOccurrences(of: "+", with: "")
+            .replacingOccurrences(of: " ", with: "")
+            .replacingOccurrences(of: "⎋", with: "escape")
+            .replacingOccurrences(of: "⇥", with: "tab")
+            .replacingOccurrences(of: "↩", with: "enter")
+            .replacingOccurrences(of: "⏎", with: "enter")
+            .replacingOccurrences(of: "return", with: "enter")
+            .replacingOccurrences(of: "←", with: "left")
+            .replacingOccurrences(of: "→", with: "right")
+            .replacingOccurrences(of: "↑", with: "up")
+            .replacingOccurrences(of: "↓", with: "down")
+
+        if key == "esc" {
+            key = "escape"
+        }
+
+        return (key.isEmpty ? rawKey.lowercased() : key, modifiers)
+    }
+
+    func normalizeModifier(_ modifier: String) -> String {
+        switch modifier.trimmingCharacters(in: .whitespacesAndNewlines).lowercased() {
+        case "cmd", "command", "meta", "⌘":
+            return "command"
+        case "opt", "option", "alt", "⌥":
+            return "option"
+        case "ctrl", "control", "⌃":
+            return "control"
+        case "shift", "⇧":
+            return "shift"
+        default:
+            return ""
+        }
+    }
+
+    func eventFlags(for modifiers: Set<String>) -> CGEventFlags {
+        var flags: CGEventFlags = []
+        if modifiers.contains("command") { flags.insert(.maskCommand) }
+        if modifiers.contains("option") { flags.insert(.maskAlternate) }
+        if modifiers.contains("control") { flags.insert(.maskControl) }
+        if modifiers.contains("shift") { flags.insert(.maskShift) }
+        return flags
+    }
+
+    func keyCode(for key: String) -> CGKeyCode? {
+        let codes: [String: CGKeyCode] = [
+            "a": 0, "s": 1, "d": 2, "f": 3, "h": 4, "g": 5, "z": 6, "x": 7,
+            "c": 8, "v": 9, "b": 11, "q": 12, "w": 13, "e": 14, "r": 15,
+            "y": 16, "t": 17, "1": 18, "2": 19, "3": 20, "4": 21, "6": 22,
+            "5": 23, "=": 24, "9": 25, "7": 26, "-": 27, "8": 28, "0": 29,
+            "]": 30, "o": 31, "u": 32, "[": 33, "i": 34, "p": 35, "enter": 36,
+            "l": 37, "j": 38, "'": 39, "k": 40, ";": 41, "\\": 42, ",": 43,
+            "/": 44, "n": 45, "m": 46, ".": 47, "tab": 48, "space": 49,
+            "`": 50, "delete": 51, "backspace": 51, "escape": 53,
+            "command": 55, "cmd": 55, "shift": 56, "capslock": 57, "option": 58,
+            "alt": 58, "control": 59, "left": 123, "right": 124, "down": 125,
+            "up": 126,
+        ]
+        return codes[key]
+    }
+
+    func displayName(key: String, modifiers: Set<String>) -> String {
+        let ordered = ["control", "option", "shift", "command"].filter { modifiers.contains($0) }
+        return (ordered + [key]).joined(separator: "+")
+    }
+}

package/app/Sources/DesktopModel.swift

@@ -81,6 +81,10 @@ final class DesktopModel: ObservableObject {
         Array(windows.values).sorted { $0.zIndex < $1.zIndex }
     }
 
+    func frontmostWindow() -> WindowEntry? {
+        windows.values.min { $0.zIndex < $1.zIndex }
+    }
+
     func lastInteractionDate(for wid: UInt32) -> Date? {
         interactionDates[wid]
     }

package/app/Sources/HandsOffSession.swift

@@ -43,7 +43,14 @@ final class HandsOffSession: ObservableObject {
         case thinking
     }
 
-    @Published var state: State = .idle
+    @Published var state: State = .idle {
+        didSet {
+            if state != oldValue {
+                stateChangedAt = Date()
+            }
+        }
+    }
+    @Published private(set) var stateChangedAt: Date = Date()
     @Published var lastTranscript: String?
     @Published var lastResponse: String?
     @Published var audibleFeedbackEnabled: Bool = false
@@ -58,6 +65,7 @@ final class HandsOffSession: ObservableObject {
         let frame: WindowFrame
     }
     private(set) var frameHistory: [FrameSnapshot] = []
+    private(set) var frameHistoryUpdatedAt: Date?
 
     /// Snapshot current frames for all windows that are about to be moved.
     /// Stores frames in CG/AX coordinates (top-left origin) for direct use with batchRestoreWindows.
@@ -77,10 +85,12 @@ final class HandsOffSession: ObservableObject {
                 break
             }
         }
+        frameHistoryUpdatedAt = frameHistory.isEmpty ? nil : Date()
     }
 
     func clearFrameHistory() {
         frameHistory.removeAll()
+        frameHistoryUpdatedAt = nil
     }
 
     /// Running chat log — visible in the voice chat panel. Persists across turns.
@@ -327,7 +337,9 @@ final class HandsOffSession: ObservableObject {
                 }
             }
 
-            // Single dispatch — all @Published mutations in one block
+            // Single dispatch — all @Published mutations in one block.
+            // The pending callback also mutates @Published state, so it must
+            // run on main with the rest of the turn completion.
             DispatchQueue.main.async { [weak self] in
                 guard let self else { return }
                 if let spoken { self.lastResponse = spoken }
@@ -342,9 +354,8 @@ final class HandsOffSession: ObservableObject {
                     self.executeActions(actions)
                 }
                 self.state = .idle
+                cb?(json)
             }
-
-            cb?(json)
         }
     }
 

package/app/Sources/HomeDashboardView.swift

@@ -4,6 +4,7 @@ struct HomeDashboardView: View {
     var onNavigate: ((AppPage) -> Void)? = nil
 
     @ObservedObject private var scanner = ProjectScanner.shared
+    @ObservedObject private var piSession = PiChatSession.shared
 
     var body: some View {
         VStack(spacing: 0) {
@@ -16,6 +17,9 @@ struct HomeDashboardView: View {
             MainView(scanner: scanner, layout: .embedded)
         }
         .background(Palette.bg)
+        .onAppear {
+            piSession.refreshBinaryAvailability()
+        }
     }
 
     private var hero: some View {
@@ -26,7 +30,7 @@ struct HomeDashboardView: View {
                         .font(Typo.heading(18))
                         .foregroundColor(Palette.text)
 
-                    Text("Launch workspaces, jump into the screen map, or open a full Pi session from one place.")
+                    Text("Workspace status, project launch, layout, search, and chat in one place.")
                         .font(Typo.mono(11))
                         .foregroundColor(Palette.textDim)
                         .fixedSize(horizontal: false, vertical: true)
@@ -37,8 +41,8 @@ struct HomeDashboardView: View {
 
             HStack(spacing: 10) {
                 homeActionCard(
-                    title: "Screen Map",
-                    subtitle: "Spatial window layout",
+                    title: "Layout",
+                    subtitle: "Arrange windows",
                     icon: "rectangle.3.group",
                     tint: Palette.running
                 ) {
@@ -46,19 +50,23 @@ struct HomeDashboardView: View {
                 }
 
                 homeActionCard(
-                    title: "Desktop Inventory",
-                    subtitle: "Enumerate displays and spaces",
-                    icon: "macwindow.on.rectangle",
+                    title: "Search",
+                    subtitle: "Find workspace context",
+                    icon: "magnifyingglass",
                     tint: Palette.detach
                 ) {
                     onNavigate?(.desktopInventory)
                 }
 
                 homeActionCard(
-                    title: "Pi Workspace",
-                    subtitle: "Standalone conversation surface",
-                    icon: "terminal",
-                    tint: Palette.text
+                    title: "Chat",
+                    subtitle: piSession.hasPiBinary
+                        ? (piSession.needsProviderSetup || piSession.isAuthenticating
+                            ? piSession.setupStatusSummary
+                            : "Standalone conversation surface")
+                        : "Install Pi to enable the assistant",
+                    icon: "bubble.left.and.bubble.right",
+                    tint: piSession.hasPiBinary ? Palette.text : Palette.kill
                 ) {
                     onNavigate?(.pi)
                 }

package/app/Sources/HotkeyStore.swift

@@ -31,7 +31,7 @@ enum HotkeyAction: String, CaseIterable, Codable {
     // Tiling
     case tileLeft, tileRight, tileMaximize, tileCenter
     case tileTopLeft, tileTopRight, tileBottomLeft, tileBottomRight
-    case tileTop, tileBottom, tileDistribute
+    case tileTop, tileBottom, tileDistribute, tileTypeGrid
     case tileLeftThird, tileCenterThird, tileRightThird
 
     var label: String {
@@ -40,11 +40,11 @@ enum HotkeyAction: String, CaseIterable, Codable {
         case .screenMap:       return "Screen Map"
         case .bezel:           return "Window Bezel"
         case .cheatSheet:      return "Cheat Sheet"
-        case .desktopInventory: return "Desktop Inventory"
-        case .omniSearch:      return "Omni Search"
+        case .desktopInventory: return "Search"
+        case .omniSearch:      return "Search"
         case .voiceCommand:    return "Voice Command"
         case .handsOff:        return "Hands-Off Mode"
-        case .unifiedWindow:   return "Unified Window"
+        case .unifiedWindow:   return "Workspace Home"
         case .hud:             return "HUD"
         case .mouseFinder:     return "Find Mouse"
         case .layer1:          return "Layer 1"
@@ -70,6 +70,7 @@ enum HotkeyAction: String, CaseIterable, Codable {
         case .tileTop:         return "Top Half"
         case .tileBottom:      return "Bottom Half"
         case .tileDistribute:  return "Distribute"
+        case .tileTypeGrid:    return "Grid Type"
         case .tileLeftThird:   return "Left Third"
         case .tileCenterThird: return "Center Third"
         case .tileRightThird:  return "Right Third"
@@ -122,6 +123,7 @@ enum HotkeyAction: String, CaseIterable, Codable {
         case .tileTop:         return 308
         case .tileBottom:      return 309
         case .tileDistribute:  return 310
+        case .tileTypeGrid:    return 314
         case .tileLeftThird:   return 311
         case .tileCenterThird: return 312
         case .tileRightThird:  return 313
@@ -226,7 +228,7 @@ class HotkeyStore: ObservableObject {
 
         // App
         bind(.palette,   46, cmdShift)   // Cmd+Shift+M
-        bind(.unifiedWindow, 18, hyper)  // Hyper+1 (Screen Map + Desktop Inventory)
+        bind(.unifiedWindow, 18, hyper)  // Hyper+1 (Workspace Home)
         bind(.bezel,     19, hyper)      // Hyper+2
         bind(.hud,       20, hyper)      // Hyper+3 (HUD overlay)
         bind(.voiceCommand, 21, hyper)   // Hyper+4 (moved from Hyper+3)
@@ -259,6 +261,7 @@ class HotkeyStore: ObservableObject {
         bind(.tileBottomLeft,   38, ctrlOpt)  // Ctrl+Opt+J
         bind(.tileBottomRight,  40, ctrlOpt)  // Ctrl+Opt+K
         bind(.tileDistribute,    2, ctrlOpt)  // Ctrl+Opt+D
+        bind(.tileTypeGrid,      5, hyper)    // Hyper+G
         bind(.tileLeftThird,    18, ctrlOpt)  // Ctrl+Opt+1
         bind(.tileCenterThird,  19, ctrlOpt)  // Ctrl+Opt+2
         bind(.tileRightThird,   20, ctrlOpt)  // Ctrl+Opt+3

package/app/Sources/IntentEngine.swift

@@ -381,7 +381,7 @@ final class IntentEngine {
 
         register(IntentDef(
             name: "distribute",
-            description: "Distribute windows evenly in a grid, optionally filtered by app and constrained to a screen region",
+            description: "Distribute windows evenly in a grid, optionally filtered by app or window type and constrained to a screen region",
             examples: [
                 "spread out the windows",
                 "distribute everything",
@@ -394,6 +394,9 @@ final class IntentEngine {
             slots: [
                 IntentSlot(name: "app", type: "string", required: false,
                            description: "Filter to windows of this app (e.g. 'iTerm2', 'Google Chrome')", enumValues: nil),
+                IntentSlot(name: "type", type: "string", required: false,
+                           description: "Filter to a window type (e.g. 'terminal', 'browser', 'editor')",
+                           enumValues: AppType.allCases.map(\.rawValue)),
                 IntentSlot(name: "region", type: "position", required: false,
                            description: "Constrain the grid to a screen region. Uses tile position names.",
                            enumValues: ["left", "right", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right",
@@ -404,6 +407,9 @@ final class IntentEngine {
                 if let app = req.slots["app"]?.stringValue {
                     params["app"] = .string(app)
                 }
+                if let type = req.slots["type"]?.stringValue {
+                    params["type"] = .string(type)
+                }
                 if let region = req.slots["region"]?.stringValue {
                     params["region"] = .string(region)
                 }

package/app/Sources/LatticesApi.swift

@@ -1,5 +1,6 @@
 import AppKit
 import ApplicationServices
+import DeckKit
 import Foundation
 
 // MARK: - Registry Types
@@ -197,6 +198,7 @@ final class LatticesApi {
         api.model(ApiModel(name: "Space", fields: [
             Field(name: "id", type: "int", required: true, description: "Space ID"),
             Field(name: "index", type: "int", required: true, description: "Space index"),
+            Field(name: "name", type: "string", required: true, description: "Lattices display name for the space"),
             Field(name: "display", type: "int", required: true, description: "Display index"),
             Field(name: "isCurrent", type: "bool", required: true, description: "Whether this is the active space"),
         ]))
@@ -736,6 +738,7 @@ final class LatticesApi {
                             .object([
                                 "id": .int(space.id),
                                 "index": .int(space.index),
+                                "name": .string(Self.defaultSpaceName(for: space.index)),
                                 "display": .int(space.display),
                                 "isCurrent": .bool(space.isCurrent)
                             ])
@@ -773,6 +776,45 @@ final class LatticesApi {
             }
         ))
 
+        api.register(Endpoint(
+            method: "deck.manifest",
+            description: "Get the shared companion deck manifest exposed by the macOS app",
+            access: .read,
+            params: [],
+            returns: .custom("DeckKit manifest for the Lattices companion surface"),
+            handler: { _ in
+                try Self.encodeDeckValue(LatticesDeckHost.shared.manifestSync())
+            }
+        ))
+
+        api.register(Endpoint(
+            method: "deck.snapshot",
+            description: "Get the current companion deck runtime snapshot",
+            access: .read,
+            params: [],
+            returns: .custom("DeckKit runtime snapshot with voice, layout, switcher, and history state"),
+            handler: { _ in
+                try Self.encodeDeckValue(LatticesDeckHost.shared.runtimeSnapshotSync())
+            }
+        ))
+
+        api.register(Endpoint(
+            method: "deck.perform",
+            description: "Perform a companion deck action and return the updated runtime snapshot",
+            access: .mutate,
+            params: [
+                Param(name: "pageID", type: "string", required: false, description: "Deck page ID"),
+                Param(name: "actionID", type: "string", required: true, description: "Deck action identifier"),
+                Param(name: "payload", type: "object", required: false, description: "Deck action payload"),
+            ],
+            returns: .custom("DeckKit action result"),
+            handler: { params in
+                let request = try Self.decodeDeckActionRequest(from: params)
+                let result = try LatticesDeckHost.shared.performSync(request)
+                return try Self.encodeDeckValue(result)
+            }
+        ))
+
         api.register(Endpoint(
             method: "daemon.status",
             description: "Get daemon status including uptime and counts",
@@ -1339,10 +1381,11 @@ final class LatticesApi {
 
         api.register(Endpoint(
             method: "layout.distribute",
-            description: "Distribute windows evenly in a grid, optionally filtered by app and constrained to a screen region",
+            description: "Distribute windows evenly in a grid, optionally filtered by app or type and constrained to a screen region",
             access: .mutate,
             params: [
                 Param(name: "app", type: "string", required: false, description: "Filter to windows of this app (e.g. 'iTerm2')"),
+                Param(name: "type", type: "string", required: false, description: "Filter to an app type (e.g. 'terminal', 'browser', 'editor')"),
                 Param(name: "region", type: "string", required: false, description: "Constrain grid to a screen region (e.g. 'right', 'left', 'top-right'). Uses tile position names."),
             ],
             returns: .ok,
@@ -1351,9 +1394,11 @@ final class LatticesApi {
                 if case .object(let obj) = params {
                     dict = obj
                 }
-                // If app is provided, switch to app scope
+                // Explicit filters select the matching scope automatically.
                 if dict["app"] != nil && dict["scope"] == nil {
                     dict["scope"] = .string("app")
+                } else if dict["type"] != nil && dict["scope"] == nil {
+                    dict["scope"] = .string("type")
                 } else {
                     dict["scope"] = dict["scope"] ?? .string("visible")
                 }
@@ -1367,9 +1412,10 @@ final class LatticesApi {
             description: "Optimize a set of windows using an explicit scope and strategy",
             access: .mutate,
             params: [
-                Param(name: "scope", type: "string", required: false, description: "Optimization scope: visible, active-app, app, or selection"),
+                Param(name: "scope", type: "string", required: false, description: "Optimization scope: visible, active-app, active-type, app, type, or selection"),
                 Param(name: "strategy", type: "string", required: false, description: "Optimization strategy: balanced or mosaic"),
                 Param(name: "app", type: "string", required: false, description: "App name for app-scoped optimization"),
+                Param(name: "type", type: "string", required: false, description: "App type for type-scoped optimization"),
                 Param(name: "title", type: "string", required: false, description: "Optional title substring for app-scoped optimization"),
                 Param(name: "windowIds", type: "[uint32]", required: false, description: "Explicit window selection for selection scope"),
             ],
@@ -1872,6 +1918,27 @@ final class LatticesApi {
 }
 
 private extension LatticesApi {
+    static func decodeDeckActionRequest(from json: JSON?) throws -> DeckActionRequest {
+        guard let json else {
+            throw RouterError.missingParam("actionID")
+        }
+        guard case .object(var object) = json else {
+            throw RouterError.custom("Invalid deck action request: params must be an object")
+        }
+        object["payload"] = object["payload"] ?? .object([:])
+        let data = try JSONEncoder().encode(JSON.object(object))
+        do {
+            return try JSONDecoder().decode(DeckActionRequest.self, from: data)
+        } catch {
+            throw RouterError.custom("Invalid deck action request: \(error.localizedDescription)")
+        }
+    }
+
+    static func encodeDeckValue<T: Encodable>(_ value: T) throws -> JSON {
+        let data = try JSONEncoder().encode(value)
+        return try JSONDecoder().decode(JSON.self, from: data)
+    }
+
     static func parsePlacement(from json: JSON?) -> PlacementSpec? {
         PlacementSpec(json: json)
     }
@@ -2070,6 +2137,19 @@ private extension LatticesApi {
         ])
     }
 
+    static func defaultSpaceName(for index: Int) -> String {
+        if let layers = WorkspaceManager.shared.config?.layers,
+           layers.indices.contains(index - 1) {
+            return layers[index - 1].label
+        }
+
+        let defaults = ["main", "code", "chat", "review", "media", "notes", "ops", "admin", "scratch"]
+        if defaults.indices.contains(index - 1) {
+            return defaults[index - 1]
+        }
+        return "space \(index)"
+    }
+
     static func executeSpaceOptimization(params: JSON?) throws -> JSON {
         let scope = try parseOptimizationScope(from: params)
         let strategy = try parseOptimizationStrategy(params?["strategy"]?.stringValue)
@@ -2135,10 +2215,15 @@ private extension LatticesApi {
         if params?["app"] != nil {
             return "app"
         }
+        if params?["type"] != nil {
+            return "type"
+        }
 
         let scope = normalizeToken(params?["scope"]?.stringValue ?? "visible")
         switch scope {
-        case "visible", "selection", "app", "active-app", "frontmost-app", "current-app":
+        case "visible", "selection", "app", "type",
+             "active-app", "frontmost-app", "current-app",
+             "active-type", "frontmost-type", "current-type":
             return scope
         default:
             throw RouterError.custom("Unsupported optimization scope: \(params?["scope"]?.stringValue ?? scope)")
@@ -2179,6 +2264,21 @@ private extension LatticesApi {
                 (titleFilter == nil || $0.title.localizedCaseInsensitiveContains(titleFilter!))
             })
 
+        case "type":
+            guard let typeName = params?["type"]?.stringValue,
+                  let appType = parseOptimizationAppType(typeName) else {
+                trace.append(.string("missing or unknown type for type scope"))
+                return []
+            }
+            trace.append(.string("filtered by type \(appType.rawValue)"))
+            if let titleFilter {
+                trace.append(.string("title contains \(titleFilter)"))
+            }
+            return dedupeWindows(visible.filter {
+                AppTypeClassifier.matches($0.app, type: appType) &&
+                (titleFilter == nil || $0.title.localizedCaseInsensitiveContains(titleFilter!))
+            })
+
         case "active-app", "frontmost-app", "current-app":
             let activeApp = params?["app"]?.stringValue ?? frontmostOptimizableApp()
             guard let activeApp else {
@@ -2194,12 +2294,33 @@ private extension LatticesApi {
                 (titleFilter == nil || $0.title.localizedCaseInsensitiveContains(titleFilter!))
             })
 
+        case "active-type", "frontmost-type", "current-type":
+            let activeApp = params?["app"]?.stringValue ?? frontmostOptimizableApp()
+            guard let activeApp else {
+                trace.append(.string("no active app available"))
+                return []
+            }
+            let grouping = AppTypeClassifier.grouping(for: activeApp)
+            trace.append(.string("resolved active type \(grouping.label) from \(activeApp)"))
+            if let titleFilter {
+                trace.append(.string("title contains \(titleFilter)"))
+            }
+            return dedupeWindows(visible.filter {
+                AppTypeClassifier.matches($0.app, grouping: grouping) &&
+                (titleFilter == nil || $0.title.localizedCaseInsensitiveContains(titleFilter!))
+            })
+
         default:
             trace.append(.string("using visible window scope"))
             return dedupeWindows(visible)
         }
     }
 
+    static func parseOptimizationAppType(_ raw: String) -> AppType? {
+        let normalized = normalizeToken(raw)
+        return AppType.allCases.first { $0.rawValue == normalized }
+    }
+
     static func selectedWindowIds(from json: JSON?) -> [UInt32] {
         guard case .array(let values) = json else { return [] }
         return values.compactMap(\.uint32Value)