The Action Button: A Control, a One-Shot Request, and a Retry

// LaunchRequest.swift (watch app and widget extension)
import Foundation

/// A one-shot request that survives a cold launch. The process that reads it may not exist yet when
/// the button is pressed, so it lives in UserDefaults, and reading it clears it: a request left armed
/// would reopen the microphone every time the wearer comes back to the app.
enum LaunchRequest {
    private static let key = "spark.launch.speak"

    /// An App Group suite both the watch app and its widget extension are entitled to. Each
    /// target's UserDefaults.standard is its own domain: a flag the extension writes there
    /// is a flag the app never reads.
    static var shared: UserDefaults { UserDefaults(suiteName: "group.com.example.spark.watch") ?? .standard }

    static func arm(_ defaults: UserDefaults = shared) {
        defaults.set(true, forKey: key)
    }

    static func consume(_ defaults: UserDefaults = shared) -> Bool {
        guard defaults.bool(forKey: key) else { return false }
        defaults.removeObject(forKey: key)
        return true
    }
}

// SpeakIntent.swift: compiled into BOTH the watch app and its widget extension. When the app carries
// the same type, the system runs this app-opening intent in the app's process.
import AppIntents

struct SpeakToSparkIntent: AppIntent {
    static let title: LocalizedStringResource = "Speak to Spark"
    static let description = IntentDescription("Opens Spark's dictation so you can capture a thought.")
    static let openAppWhenRun = true    // dictation needs the app on screen; never pretend to capture silently

    @available(watchOS 26.0, *)
    static var supportedModes: IntentModes { .foreground(.immediate) }

    /// Set by the watch app at launch. nil in the widget extension.
    @MainActor static var onPerform: (@MainActor () -> Void)?

    @MainActor
    func perform() async throws -> some IntentResult {
        if let start = Self.onPerform {
            start()                     // in the app: the hook decides, door now or request for later
        } else {
            LaunchRequest.arm()         // in the extension: into the shared suite, for the app's first view
        }
        return .result()
    }
}

// SpeakControl.swift (widget extension): the Action Button's road since watchOS 26.
import SwiftUI
import WidgetKit

@available(watchOS 26.0, *)
struct SpeakControl: ControlWidget {
    var body: some ControlWidgetConfiguration {
        StaticControlConfiguration(kind: "com.example.spark.control.speak") {
            ControlWidgetButton(action: SpeakToSparkIntent()) {
                Label("Speak to Spark", systemImage: "mic.fill")
            }
        }
        .displayName("Speak to Spark")
        .description("Opens dictation.")
    }
}

// In the extension's WidgetBundle, beside the complication:
//     SparkComplication()
//     if #available(watchOS 26.0, *) { SpeakControl() }
//
// In the watch app's App.init: open the door when the app is already in front; while it is
// still coming up, leave the request for the first view instead.
//     SpeakToSparkIntent.onPerform = {
//         if WKApplication.shared().applicationState == .active { /* open the dictation door */ }
//         else { LaunchRequest.arm() }
//     }

import SwiftUI

struct SparkWatchRoot: View {
    /// The dictation door from the dictation lesson: false while no controller is visible yet.
    let openDictation: @MainActor () -> Bool
    @Environment(\.scenePhase) private var phase
    @State private var wantsDictation = false

    var body: some View {
        Button("Speak", systemImage: "mic.fill") { request() }
            .onOpenURL { url in                                        // the complication's tap, same door
                if url.scheme == "spark", url.host() == "speak" { request() }
            }
            .onAppear {
                if LaunchRequest.consume() { wantsDictation = true }   // a cold press of the Action Button
                attempt()
            }
            .onChange(of: phase) { _, now in
                guard now == .active else { return }
                if LaunchRequest.consume() { wantsDictation = true }   // a press while the app was alive
                attempt()
            }
    }

    private func request() {
        wantsDictation = true
        attempt()
    }

    /// Unavailable is a moment, not a state: keep the wish until the door actually opens.
    private func attempt() {
        guard wantsDictation else { return }
        if openDictation() { wantsDictation = false }
    }
}