@lattices/cli 0.4.1 → 0.4.5

package/app/Sources/PiInstallCallout.swift

@@ -0,0 +1,86 @@
+import SwiftUI
+
+struct PiInstallCallout: View {
+    @ObservedObject var session: PiChatSession
+    let compact: Bool
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: compact ? 10 : 12) {
+            HStack(spacing: 8) {
+                Circle()
+                    .fill(Palette.kill)
+                    .frame(width: compact ? 6 : 7, height: compact ? 6 : 7)
+
+                Text("PI REQUIRED")
+                    .font(Typo.geistMonoBold(compact ? 9 : 10))
+                    .foregroundColor(Palette.kill.opacity(0.95))
+
+                Text("assistant unavailable")
+                    .font(Typo.mono(compact ? 9 : 10))
+                    .foregroundColor(Palette.textMuted)
+            }
+
+            Text("Install the official Pi coding agent CLI to use the in-app assistant. Lattices can copy the command or run it in \(Preferences.shared.terminal.rawValue).")
+                .font(Typo.mono(compact ? 10 : 11))
+                .foregroundColor(Palette.textDim)
+                .fixedSize(horizontal: false, vertical: true)
+
+            Text(session.piInstallCommand)
+                .font(Typo.mono(compact ? 10 : 11))
+                .foregroundColor(Palette.text)
+                .textSelection(.enabled)
+                .frame(maxWidth: .infinity, alignment: .leading)
+                .padding(.horizontal, compact ? 10 : 12)
+                .padding(.vertical, compact ? 8 : 10)
+                .background(
+                    RoundedRectangle(cornerRadius: compact ? 6 : 8)
+                        .fill(Color.black.opacity(0.35))
+                        .overlay(
+                            RoundedRectangle(cornerRadius: compact ? 6 : 8)
+                                .strokeBorder(Palette.border, lineWidth: 0.5)
+                        )
+                )
+
+            HStack(spacing: 8) {
+                actionButton(compact ? "COPY" : "COPY CMD", tint: Palette.running) {
+                    session.copyPiInstallCommand()
+                }
+
+                actionButton(compact ? "INSTALL" : "INSTALL IN TERMINAL", tint: Palette.detach) {
+                    session.installPiInTerminal()
+                }
+
+                actionButton("REFRESH", tint: Palette.textMuted) {
+                    session.refreshBinaryAvailability()
+                }
+            }
+        }
+        .padding(.horizontal, compact ? 10 : 16)
+        .padding(.vertical, compact ? 10 : 14)
+        .background(
+            RoundedRectangle(cornerRadius: compact ? 6 : 8)
+                .fill(Palette.kill.opacity(0.06))
+                .overlay(
+                    RoundedRectangle(cornerRadius: compact ? 6 : 8)
+                        .strokeBorder(Palette.kill.opacity(0.22), lineWidth: 0.5)
+                )
+        )
+    }
+
+    private func actionButton(_ label: String, tint: Color, action: @escaping () -> Void) -> some View {
+        Button(label, action: action)
+            .buttonStyle(.plain)
+            .font(Typo.geistMonoBold(compact ? 9 : 10))
+            .foregroundColor(tint)
+            .padding(.horizontal, compact ? 8 : 10)
+            .padding(.vertical, compact ? 5 : 6)
+            .background(
+                Capsule()
+                    .fill(Color.white.opacity(0.03))
+                    .overlay(
+                        Capsule()
+                            .strokeBorder(Palette.border, lineWidth: 0.5)
+                    )
+            )
+    }
+}

package/app/Sources/PiProviderSetupCallout.swift

@@ -0,0 +1,99 @@
+import SwiftUI
+
+struct PiProviderSetupCallout: View {
+    @ObservedObject var session: PiChatSession
+    let compact: Bool
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: compact ? 10 : 12) {
+            HStack(spacing: 8) {
+                Circle()
+                    .fill(Palette.detach)
+                    .frame(width: compact ? 6 : 7, height: compact ? 6 : 7)
+
+                Text("SET UP YOUR AI")
+                    .font(Typo.geistMonoBold(compact ? 9 : 10))
+                    .foregroundColor(Palette.detach.opacity(0.95))
+            }
+
+            Text(session.isAuthenticating
+                ? "Finish the setup above. As soon as that one step is done, the chat box unlocks."
+                : "Next step: connect \(session.currentProvider.name). You only have to do this once.")
+                .font(Typo.mono(compact ? 10 : 11))
+                .foregroundColor(Palette.textDim)
+                .fixedSize(horizontal: false, vertical: true)
+
+            HStack(spacing: 8) {
+                capsuleLabel(session.currentProvider.name.uppercased(), tint: Palette.text)
+                capsuleLabel(session.currentProvider.authMode == .oauth ? "SIGN IN" : "API KEY", tint: Palette.running)
+            }
+
+            if session.isAuthenticating {
+                PiAuthNextStepCard(session: session, compact: compact)
+            } else {
+                Text(session.currentProvider.authMode == .oauth
+                    ? "The setup panel above is already open, so you can connect right now."
+                    : "Paste your key in the setup panel above, save it once, and you are done.")
+                    .font(Typo.mono(compact ? 9 : 10))
+                    .foregroundColor(Palette.textMuted)
+            }
+
+            if session.currentProvider.authMode == .oauth && !session.isAuthenticating {
+                primaryActionButton(
+                    "CONNECT \(session.currentProvider.name.uppercased())",
+                    tint: Palette.running
+                ) {
+                    session.startSelectedAuthFlow()
+                }
+            }
+        }
+        .padding(.horizontal, compact ? 10 : 16)
+        .padding(.vertical, compact ? 10 : 14)
+        .background(
+            RoundedRectangle(cornerRadius: compact ? 6 : 8)
+                .fill(Palette.detach.opacity(0.06))
+                .overlay(
+                    RoundedRectangle(cornerRadius: compact ? 6 : 8)
+                        .strokeBorder(Palette.detach.opacity(0.22), lineWidth: 0.5)
+                )
+        )
+    }
+
+    private func primaryActionButton(_ label: String, tint: Color, disabled: Bool = false, action: @escaping () -> Void) -> some View {
+        Button(action: action) {
+            Text(label)
+                .font(Typo.geistMonoBold(compact ? 10 : 11))
+                .foregroundColor(disabled ? Palette.textMuted : tint)
+                .frame(maxWidth: .infinity)
+                .padding(.horizontal, compact ? 10 : 12)
+                .padding(.vertical, compact ? 8 : 10)
+                .background(
+                    RoundedRectangle(cornerRadius: compact ? 6 : 8)
+                        .fill(tint.opacity(disabled ? 0.05 : 0.12))
+                        .overlay(
+                            RoundedRectangle(cornerRadius: compact ? 6 : 8)
+                                .strokeBorder((disabled ? Palette.border : tint.opacity(0.35)), lineWidth: 0.5)
+                        )
+                )
+        }
+        .buttonStyle(.plain)
+        .opacity(disabled ? 0.65 : 1)
+        .disabled(disabled)
+    }
+
+    private func capsuleLabel(_ text: String, tint: Color) -> some View {
+        Text(text)
+            .font(Typo.geistMonoBold(compact ? 9 : 10))
+            .foregroundColor(tint.opacity(0.95))
+            .padding(.horizontal, compact ? 7 : 8)
+            .padding(.vertical, compact ? 4 : 5)
+            .background(
+                Capsule()
+                    .fill(tint.opacity(0.10))
+                    .overlay(
+                        Capsule()
+                            .strokeBorder(tint.opacity(0.28), lineWidth: 0.5)
+                    )
+            )
+    }
+}

package/app/Sources/PiWorkspaceView.swift

@@ -19,7 +19,7 @@ struct PiWorkspaceView: View {
                 .fill(Palette.border)
                 .frame(height: 0.5)
 
-            if session.isAuthPanelVisible {
+            if session.hasPiBinary && session.isAuthPanelVisible {
                 authPanel
 
                 Rectangle()
@@ -33,12 +33,31 @@ struct PiWorkspaceView: View {
                 .fill(Palette.border)
                 .frame(height: 0.5)
 
-            composer
+            if session.hasPiBinary && !session.needsProviderSetup {
+                composer
+            } else if session.needsProviderSetup {
+                if session.isAuthPanelVisible {
+                    setupLockedPanel
+                } else {
+                    PiProviderSetupCallout(session: session, compact: false)
+                        .padding(.horizontal, 16)
+                        .padding(.vertical, 14)
+                        .background(Palette.surface.opacity(0.22))
+                }
+            } else {
+                PiInstallCallout(session: session, compact: false)
+                    .padding(.horizontal, 16)
+                    .padding(.vertical, 14)
+                    .background(Palette.surface.opacity(0.22))
+            }
         }
         .background(Palette.bg)
         .onAppear {
-            DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
-                composerFocused = true
+            session.prepareForDisplay()
+            if session.hasPiBinary && !session.needsProviderSetup {
+                DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
+                    composerFocused = true
+                }
             }
         }
     }
@@ -51,14 +70,27 @@ struct PiWorkspaceView: View {
                         .fill(session.hasPiBinary ? Palette.running : Palette.kill)
                         .frame(width: 7, height: 7)
 
-                    Text("PI WORKSPACE")
+                    Text("WORKSPACE CHAT")
                         .font(Typo.geistMonoBold(11))
                         .foregroundColor(Palette.text)
 
-                    capsuleLabel(session.statusText.uppercased(), tint: session.isSending ? Palette.detach : Palette.running)
+                    capsuleLabel(
+                        session.statusText.uppercased(),
+                        tint: session.statusText == "missing pi"
+                            ? Palette.kill
+                            : ((session.statusText == "setup ai" || session.statusText == "connecting...")
+                                ? Palette.detach
+                                : (session.isSending ? Palette.detach : Palette.running))
+                    )
                 }
 
-                Text("Full conversation surface for longer prompts, auth, and provider switching.")
+                Text(session.hasPiBinary
+                    ? (session.isAuthenticating
+                        ? session.authStepDescription
+                        : (session.needsProviderSetup
+                            ? "Next step: connect a provider to unlock chat."
+                            : "Full conversation surface for longer prompts, auth, and provider switching."))
+                    : "Install Pi to unlock longer prompts, provider auth, and the full in-app assistant surface.")
                     .font(Typo.mono(10))
                     .foregroundColor(Palette.textDim)
             }
@@ -68,12 +100,16 @@ struct PiWorkspaceView: View {
             HStack(spacing: 6) {
                 capsuleLabel(session.currentProvider.name.uppercased(), tint: Palette.textDim)
 
-                actionChip(session.isAuthPanelVisible ? "AUTH -" : "AUTH +") {
-                    session.toggleAuthPanel()
+                if session.hasPiBinary && !session.needsProviderSetup {
+                    actionChip(session.isAuthPanelVisible ? "AUTH -" : "AUTH +") {
+                        session.toggleAuthPanel()
+                    }
                 }
 
-                actionChip("RESET") {
-                    session.clearConversation()
+                if session.hasConversationHistory {
+                    actionChip("RESET") {
+                        session.clearConversation()
+                    }
                 }
             }
         }
@@ -83,99 +119,113 @@ struct PiWorkspaceView: View {
 
     private var authPanel: some View {
         VStack(alignment: .leading, spacing: 12) {
-            HStack(spacing: 8) {
-                Text("provider")
-                    .font(Typo.geistMonoBold(9))
-                    .foregroundColor(Palette.textMuted)
+            if session.isAuthenticating {
+                VStack(alignment: .leading, spacing: 4) {
+                    Text("Finish Setup")
+                        .font(Typo.geistMonoBold(11))
+                        .foregroundColor(Palette.text)
 
-                Picker("Provider", selection: $session.authProviderID) {
-                    ForEach(session.providerOptions) { provider in
-                        Text(provider.name).tag(provider.id)
-                    }
+                    Text("Ignore the rest for a second and just do the next step below.")
+                        .font(Typo.mono(10))
+                        .foregroundColor(Palette.textDim)
+                        .fixedSize(horizontal: false, vertical: true)
                 }
-                .labelsHidden()
-                .pickerStyle(.menu)
-                .font(Typo.mono(10))
-
-                Spacer()
-
-                capsuleLabel(
-                    session.currentProvider.authMode == .oauth ? "OAUTH" : "TOKEN",
-                    tint: session.currentProvider.authMode == .oauth ? Palette.detach : Palette.running
-                )
-            }
-
-            Text(session.currentProvider.helpText)
-                .font(Typo.mono(10))
-                .foregroundColor(Palette.textDim)
-                .fixedSize(horizontal: false, vertical: true)
 
-            if session.currentProvider.authMode == .apiKey {
                 HStack(spacing: 8) {
-                    SecureField(session.currentProvider.tokenPlaceholder, text: $session.authToken)
-                        .textFieldStyle(.plain)
-                        .font(Typo.mono(11))
-                        .foregroundColor(Palette.text)
-                        .focused($authFieldFocused)
-                        .onSubmit {
-                            session.saveSelectedToken()
-                        }
+                    capsuleLabel(session.currentProvider.name.uppercased(), tint: Palette.text)
+                    capsuleLabel("IN PROGRESS", tint: Palette.detach)
+                    Spacer()
+                }
 
-                    actionChip("SAVE") {
-                        session.saveSelectedToken()
-                    }
+                if let prompt = session.pendingAuthPrompt {
+                    PiAuthPromptCard(session: session, prompt: prompt, compact: false, focus: $authFieldFocused)
+                } else {
+                    PiAuthNextStepCard(session: session, compact: false)
+                }
+            } else {
+                if session.needsProviderSetup {
+                    VStack(alignment: .leading, spacing: 4) {
+                        Text("Set Up Your AI")
+                            .font(Typo.geistMonoBold(11))
+                            .foregroundColor(Palette.text)
 
-                    if session.hasSelectedCredential {
-                        actionChip("CLEAR") {
-                            session.removeSelectedCredential()
-                        }
+                        Text("Choose a provider, connect it once, and the chat box unlocks automatically.")
+                            .font(Typo.mono(10))
+                            .foregroundColor(Palette.textDim)
+                            .fixedSize(horizontal: false, vertical: true)
                     }
                 }
-                .padding(.horizontal, 12)
-                .padding(.vertical, 10)
-                .background(authCardBackground(tint: Palette.running))
-            } else {
+
                 HStack(spacing: 8) {
-                    actionChip(session.isAuthenticating ? "CANCEL" : "LOGIN") {
-                        if session.isAuthenticating {
-                            session.cancelAuthFlow()
-                        } else {
-                            session.startSelectedAuthFlow()
-                        }
-                    }
+                    Text(session.needsProviderSetup ? "choose provider" : "provider")
+                        .font(Typo.geistMonoBold(9))
+                        .foregroundColor(Palette.textMuted)
 
-                    if session.hasSelectedCredential {
-                        actionChip("CLEAR") {
-                            session.removeSelectedCredential()
+                    Picker("Provider", selection: $session.authProviderID) {
+                        ForEach(session.providerOptions) { provider in
+                            Text(provider.name).tag(provider.id)
                         }
                     }
+                    .labelsHidden()
+                    .pickerStyle(.menu)
+                    .font(Typo.mono(10))
+
+                    Spacer()
+
+                    capsuleLabel(
+                        session.currentProvider.authMode == .oauth ? "OAUTH" : "TOKEN",
+                        tint: session.currentProvider.authMode == .oauth ? Palette.detach : Palette.running
+                    )
                 }
-                .padding(.horizontal, 12)
-                .padding(.vertical, 10)
-                .background(authCardBackground(tint: session.isAuthenticating ? Palette.detach : Palette.running))
 
-                if let prompt = session.pendingAuthPrompt {
+                Text(session.currentProvider.helpText)
+                    .font(Typo.mono(10))
+                    .foregroundColor(Palette.textDim)
+                    .fixedSize(horizontal: false, vertical: true)
+
+                if session.currentProvider.authMode == .apiKey {
                     HStack(spacing: 8) {
-                        TextField(prompt.placeholder ?? prompt.message, text: $session.authPromptInput)
+                        SecureField(session.currentProvider.tokenPlaceholder, text: $session.authToken)
                             .textFieldStyle(.plain)
                             .font(Typo.mono(11))
                             .foregroundColor(Palette.text)
                             .focused($authFieldFocused)
                             .onSubmit {
-                                session.submitAuthPrompt()
+                                session.saveSelectedToken()
+                            }
+
+                        actionChip("SAVE KEY") {
+                            session.saveSelectedToken()
+                        }
+
+                        if session.hasSelectedCredential {
+                            actionChip("CLEAR") {
+                                session.removeSelectedCredential()
                             }
+                        }
+                    }
+                    .padding(.horizontal, 12)
+                    .padding(.vertical, 10)
+                    .background(authCardBackground(tint: Palette.running))
+                } else {
+                    HStack(spacing: 8) {
+                        actionChip("CONNECT") {
+                            session.startSelectedAuthFlow()
+                        }
 
-                        actionChip("CONTINUE") {
-                            session.submitAuthPrompt()
+                        if session.hasSelectedCredential {
+                            actionChip("CLEAR") {
+                                session.removeSelectedCredential()
+                            }
                         }
                     }
                     .padding(.horizontal, 12)
                     .padding(.vertical, 10)
-                    .background(authCardBackground(tint: Palette.detach))
+                    .background(authCardBackground(tint: Palette.running))
                 }
             }
 
-            if let notice = session.authNoticeText, !notice.isEmpty {
+            if !session.isAuthenticating, let notice = session.authNoticeText, !notice.isEmpty {
                 Text(notice)
                     .font(Typo.mono(9))
                     .foregroundColor(Palette.textDim)
@@ -192,6 +242,43 @@ struct PiWorkspaceView: View {
         .padding(.horizontal, 16)
         .padding(.vertical, 14)
         .background(Palette.surface.opacity(0.35))
+        .onAppear {
+            focusAuthFieldIfNeeded()
+        }
+        .onChange(of: session.authProviderID) { _ in
+            focusAuthFieldIfNeeded()
+        }
+        .onChange(of: session.pendingAuthPrompt?.message) { prompt in
+            if prompt != nil {
+                focusAuthFieldIfNeeded()
+            }
+        }
+    }
+
+    private var setupLockedPanel: some View {
+        HStack(alignment: .center, spacing: 10) {
+            Circle()
+                .fill(Palette.detach)
+                .frame(width: 7, height: 7)
+
+            VStack(alignment: .leading, spacing: 3) {
+                Text("SETUP IN PROGRESS")
+                    .font(Typo.geistMonoBold(10))
+                    .foregroundColor(Palette.text)
+
+                Text(session.isAuthenticating
+                    ? "Stay with the setup panel above for now. The chat box unlocks as soon as you finish that step."
+                    : "Finish the setup panel above to unlock the chat box.")
+                    .font(Typo.mono(10))
+                    .foregroundColor(Palette.textDim)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+
+            Spacer()
+        }
+        .padding(.horizontal, 16)
+        .padding(.vertical, 14)
+        .background(Palette.surface.opacity(0.22))
     }
 
     private var transcript: some View {
@@ -312,6 +399,14 @@ struct PiWorkspaceView: View {
         }
     }
 
+    private func focusAuthFieldIfNeeded() {
+        if session.currentProvider.authMode == .apiKey || session.pendingAuthPrompt != nil {
+            DispatchQueue.main.asyncAfter(deadline: .now() + 0.05) {
+                authFieldFocused = true
+            }
+        }
+    }
+
     private func roleColor(for role: PiChatMessage.Role) -> Color {
         switch role {
         case .system: return Palette.detach
@@ -336,11 +431,11 @@ struct PiWorkspaceView: View {
             )
     }
 
-    private func actionChip(_ label: String, action: @escaping () -> Void) -> some View {
+    private func actionChip(_ label: String, tint: Color = Palette.textMuted, disabled: Bool = false, action: @escaping () -> Void) -> some View {
         Button(label, action: action)
             .buttonStyle(.plain)
             .font(Typo.geistMonoBold(9))
-            .foregroundColor(Palette.textMuted)
+            .foregroundColor(disabled ? Palette.textMuted : tint)
             .padding(.horizontal, 8)
             .padding(.vertical, 5)
             .background(
@@ -351,6 +446,8 @@ struct PiWorkspaceView: View {
                             .strokeBorder(Palette.border, lineWidth: 0.5)
                     )
             )
+            .opacity(disabled ? 0.65 : 1)
+            .disabled(disabled)
     }
 
     private func authCardBackground(tint: Color) -> some View {

package/app/Sources/Preferences.swift

@@ -1,3 +1,4 @@
+import DeckKit
 import Foundation
 
 enum InteractionMode: String {
@@ -8,6 +9,11 @@ enum InteractionMode: String {
 class Preferences: ObservableObject {
     static let shared = Preferences()
 
+    private enum CompanionDefaultsKey {
+        static let trackpadEnabled = "companion.trackpad.enabled"
+        static let cockpitLayout = "companion.cockpit.layout"
+    }
+
     @Published var terminal: Terminal {
         didSet { UserDefaults.standard.set(terminal.rawValue, forKey: "terminal") }
     }
@@ -20,6 +26,22 @@ class Preferences: ObservableObject {
         didSet { UserDefaults.standard.set(mode.rawValue, forKey: "mode") }
     }
 
+    @Published var dragSnapEnabled: Bool {
+        didSet { UserDefaults.standard.set(dragSnapEnabled, forKey: "windowSnap.enabled") }
+    }
+
+    @Published var companionTrackpadEnabled: Bool {
+        didSet { UserDefaults.standard.set(companionTrackpadEnabled, forKey: CompanionDefaultsKey.trackpadEnabled) }
+    }
+
+    @Published var companionCockpitLayout: LatticesCompanionCockpitLayout {
+        didSet { persistCompanionCockpitLayout() }
+    }
+
+    @Published var mouseGesturesEnabled: Bool {
+        didSet { UserDefaults.standard.set(mouseGesturesEnabled, forKey: "mouseGestures.enabled") }
+    }
+
     // MARK: - AI / Claude
 
     @Published var claudePath: String {
@@ -128,6 +150,25 @@ class Preferences: ObservableObject {
             self.mode = .learning
         }
 
+        if UserDefaults.standard.object(forKey: "windowSnap.enabled") != nil {
+            self.dragSnapEnabled = UserDefaults.standard.bool(forKey: "windowSnap.enabled")
+        } else {
+            self.dragSnapEnabled = true
+        }
+
+        if UserDefaults.standard.object(forKey: CompanionDefaultsKey.trackpadEnabled) != nil {
+            self.companionTrackpadEnabled = UserDefaults.standard.bool(forKey: CompanionDefaultsKey.trackpadEnabled)
+        } else {
+            self.companionTrackpadEnabled = true
+        }
+
+        self.companionCockpitLayout = Self.loadCompanionCockpitLayout()
+
+        if UserDefaults.standard.object(forKey: "mouseGestures.enabled") != nil {
+            self.mouseGesturesEnabled = UserDefaults.standard.bool(forKey: "mouseGestures.enabled")
+        } else {
+            self.mouseGesturesEnabled = false
+        }
         // AI / Claude
         self.claudePath = UserDefaults.standard.string(forKey: "claude.path") ?? ""
         self.advisorModel = UserDefaults.standard.string(forKey: "claude.advisorModel") ?? "haiku"
@@ -155,4 +196,41 @@ class Preferences: ObservableObject {
         let savedAcc = UserDefaults.standard.string(forKey: "ocr.accuracy") ?? "accurate"
         self.ocrAccuracy = savedAcc
     }
+
+    func updateCompanionCockpitSlot(
+        pageID: String,
+        index: Int,
+        shortcutID: String
+    ) {
+        var normalized = LatticesCompanionCockpitCatalog.normalized(companionCockpitLayout)
+        guard let pageIndex = normalized.pages.firstIndex(where: { $0.id == pageID }),
+              normalized.pages[pageIndex].slotIDs.indices.contains(index) else {
+            return
+        }
+        normalized.pages[pageIndex].slotIDs[index] = shortcutID
+        companionCockpitLayout = normalized
+    }
+
+    func resetCompanionCockpitLayout() {
+        companionCockpitLayout = LatticesCompanionCockpitCatalog.defaultLayout
+    }
+
+    private static func loadCompanionCockpitLayout() -> LatticesCompanionCockpitLayout {
+        guard let data = UserDefaults.standard.data(forKey: CompanionDefaultsKey.cockpitLayout),
+              let decoded = try? JSONDecoder().decode(LatticesCompanionCockpitLayout.self, from: data) else {
+            return LatticesCompanionCockpitCatalog.defaultLayout
+        }
+        return LatticesCompanionCockpitCatalog.normalized(decoded)
+    }
+
+    private func persistCompanionCockpitLayout() {
+        let normalized = LatticesCompanionCockpitCatalog.normalized(companionCockpitLayout)
+        if normalized != companionCockpitLayout {
+            companionCockpitLayout = normalized
+            return
+        }
+
+        guard let data = try? JSONEncoder().encode(normalized) else { return }
+        UserDefaults.standard.set(data, forKey: CompanionDefaultsKey.cockpitLayout)
+    }
 }