Build first-success onboarding with Metal keyboard journey

Author: malpern

Package.swift

@@ -185,7 +185,9 @@ let package = Package(
             ],
             path: "Sources/KeyPathAppKit",
             exclude: [
-                "InstallationWizard/README.md"
+                "InstallationWizard/README.md",
+                // Compiled into default.metallib by CompileKeyboardStageMetal.
+                "UI/KeyboardStage/Metal/KeyboardStage.metal"
             ],
             resources: [
                 .process("Resources")
@@ -194,7 +196,12 @@ let package = Package(
                 .swiftLanguageMode(.v6)
             ],
             linkerSettings: [
-                .linkedFramework("IOKit")
+                .linkedFramework("IOKit"),
+                .linkedFramework("Metal"),
+                .linkedFramework("MetalKit")
+            ],
+            plugins: [
+                .plugin(name: "CompileKeyboardStageMetal")
             ]
         ),
         // Main executable entry point
@@ -319,6 +326,11 @@ let package = Package(
                 .swiftLanguageMode(.v6)
             ]
         ),
+        .plugin(
+            name: "CompileKeyboardStageMetal",
+            capability: .buildTool(),
+            path: "Plugins/CompileKeyboardStageMetal"
+        ),
         // Tests
         .testTarget(
             name: "KeyPathSmokeTests",

Plugins/CompileKeyboardStageMetal/CompileKeyboardStageMetal.swift

@@ -0,0 +1,30 @@
+import Foundation
+import PackagePlugin
+
+@main
+struct CompileKeyboardStageMetal: BuildToolPlugin {
+    func createBuildCommands(
+        context: PluginContext,
+        target: any Target
+    ) async throws -> [Command] {
+        let shader = target.directoryURL
+            .appendingPathComponent("UI/KeyboardStage/Metal/KeyboardStage.metal")
+        let library = context.pluginWorkDirectoryURL
+            .appendingPathComponent("default.metallib")
+        let xcrun = URL(fileURLWithPath: "/usr/bin/xcrun")
+
+        return [
+            .buildCommand(
+                displayName: "Compile KeyboardStage default.metallib",
+                executable: xcrun,
+                arguments: [
+                    "-sdk", "macosx", "metal",
+                    shader.path,
+                    "-o", library.path,
+                ],
+                inputFiles: [shader],
+                outputFiles: [library]
+            ),
+        ]
+    }
+}

Sources/KeyPathAppKit/App.swift

@@ -774,7 +774,11 @@ class AppDelegate: NSObject, NSApplicationDelegate {
             return
         }
 
-        let initialPage = targetPage ?? resolveWizardInitialPage()
+        // The one-time welcome gate has a QA override. Use an explicit welcome
+        // target so the wizard's health-summary routing cannot bypass it.
+        let initialPage = UserDefaults.standard.bool(forKey: WizardWelcomeGate.forceWelcomeKey)
+            ? .welcome
+            : targetPage ?? resolveWizardInitialPage()
         WizardWindowController.shared.showWindow(
             initialPage: initialPage,
             kanataViewModel: vm,

Sources/KeyPathAppKit/InstallationWizard/WizardWindowController.swift

@@ -23,6 +23,7 @@ final class WizardWindowController {
     private var hostingView: NSView?
     private var windowDelegate: WizardWindowDelegate?
     private var onDismiss: (() -> Void)?
+    private var onboardingViewModel: KanataViewModel?
     private var sizeObserver: NSObjectProtocol?
     private var resizeDebounceWorkItem: DispatchWorkItem?
 
@@ -35,6 +36,9 @@ final class WizardWindowController {
         onDismiss: (() -> Void)? = nil
     ) {
         self.onDismiss = onDismiss
+        if let kanataViewModel {
+            onboardingViewModel = kanataViewModel
+        }
 
         // If window already exists and is visible, just bring it to front
         if let existingWindow = window, existingWindow.isVisible {
@@ -49,7 +53,12 @@ final class WizardWindowController {
 
         AppLogger.shared.log("🔮 [WizardWindow] Opening wizard window (initialPage: \(initialPage?.displayName ?? "nil"))")
 
-        let wizardView = InstallationWizardView(initialPage: initialPage)
+        let wizardView = InstallationWizardView(
+            initialPage: initialPage,
+            onFirstSuccess: { [weak self] in
+                self?.showFirstSuccessOnboarding()
+            }
+        )
 
         // Create hosting view - let SwiftUI determine ideal height
         let styledView = wizardView
@@ -211,6 +220,17 @@ final class WizardWindowController {
         onDismiss = nil
     }
 
+    private func showFirstSuccessOnboarding() {
+        // Let AppKit complete the wizard close before presenting a separate
+        // learning panel. This keeps the two moments spatially distinct.
+        let viewModel = onboardingViewModel ?? (NSApp.delegate as? AppDelegate)?.viewModel
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.25) {
+            FirstSuccessOnboardingWindowController.show(
+                kanataViewModel: viewModel
+            )
+        }
+    }
+
     /// Check if the wizard window is currently visible
     var isVisible: Bool {
         window?.isVisible ?? false

Sources/KeyPathAppKit/Managers/RuntimeCoordinator.swift

@@ -415,14 +415,7 @@ public class RuntimeCoordinator: SaveCoordinatorDelegate {
         // Wire up RuleCollectionsManager callbacks
         ruleCollectionsManager.onRulesChanged = { [weak self] in
             guard let self else { return }
-            _ = await triggerConfigReload()
-            await MainActor.run {
-                self.notifyStateChanged()
-            }
-            // Notify overlay to rebuild layer mapping
-            AppLogger.shared.debug("🔔 [RuntimeCoordinator] Posting kanataConfigChanged notification")
-
-            NotificationCenter.default.post(name: .kanataConfigChanged, object: nil)
+            _ = await applyPersistedRuleChanges()
         }
         ruleCollectionsManager.onLayerChanged = { [weak self] layerName in
             self?.currentLayerName = layerName
@@ -1176,6 +1169,22 @@ public class RuntimeCoordinator: SaveCoordinatorDelegate {
         await configReloadCoordinator.triggerConfigReload()
     }
 
+    /// Apply rule changes that have already been validated and persisted.
+    ///
+    /// Most rule saves reach this through `onRulesChanged`. Transactions that
+    /// deliberately suppress that callback so they can verify the live result
+    /// use this same path explicitly, keeping state and overlay notifications
+    /// consistent without issuing a duplicate reload.
+    func applyPersistedRuleChanges() async -> ReloadResult {
+        let result = await triggerConfigReload()
+        notifyStateChanged()
+        AppLogger.shared.debug(
+            "🔔 [RuntimeCoordinator] Posting kanataConfigChanged notification"
+        )
+        NotificationCenter.default.post(name: .kanataConfigChanged, object: nil)
+        return result
+    }
+
     /// TCP-based config reload (no authentication required - see ADR-013)
     func triggerTCPReload() async -> TCPReloadResult {
         await configReloadCoordinator.triggerTCPReload()