feat(keyboard): ship AI hint carousel, home library cards, and clipboard polish

Rotate AI idle suggestions with optional remote packs, move history/dictionary onto self-sizing Home preview cards, harden clipboard capture/prompting, and simplify keyboard chrome by dropping most liquid-glass shadows.
2026-08-13 01:00:51 +08:00
parent fd6e0d3e7e
commit 9f308fadd2
202 changed files with 10897 additions and 5962 deletions
@@ -0,0 +1,43 @@
+// FlowAck.swift
+// OSGKeyboard · Shared
+
+import Foundation
+
+/// Keyboard delivery acknowledgement. It carries the echoed result identity,
+/// generation, and revision; matching identity/revision releases that terminal result.
+public struct FlowAck: Codable, Equatable, Sendable {
+    public enum DeliveryOutcome: String, Codable, Sendable {
+        case replaced
+        case appended
+        case rejected
+    }
+
+    public let protocolVersion: Int
+    public let sessionId: UUID
+    public let utteranceId: UUID
+    public let commandSeq: Int64
+    public let hostGeneration: String?
+    public let revision: Int64?
+    public let deliveryOutcome: DeliveryOutcome?
+    public let consumedAt: TimeInterval
+
+    public init(
+        protocolVersion: Int = 1,
+        sessionId: UUID,
+        utteranceId: UUID,
+        commandSeq: Int64,
+        hostGeneration: String? = nil,
+        revision: Int64? = nil,
+        deliveryOutcome: DeliveryOutcome? = nil,
+        consumedAt: TimeInterval = Date().timeIntervalSince1970
+    ) {
+        self.protocolVersion = protocolVersion
+        self.sessionId = sessionId
+        self.utteranceId = utteranceId
+        self.commandSeq = commandSeq
+        self.hostGeneration = hostGeneration
+        self.revision = revision
+        self.deliveryOutcome = deliveryOutcome
+        self.consumedAt = consumedAt
+    }
+}
@@ -0,0 +1,87 @@
+// FlowCommand.swift
+// OSGKeyboard · Shared
+
+import Foundation
+
+public struct FlowCommand: Codable, Equatable, Sendable {
+    public enum Action: String, Codable, Sendable {
+        case startRecording
+        case stopRecording
+        case abort
+        /// Light warm-up: ASR locale/assets only — no mic capture.
+        case prewarm
+        /// User has touched the mic; prime capture before tap/hold resolves.
+        case primeAudio
+        /// Touch ended without an utterance adopting the primed capture.
+        case cancelPrimeAudio
+        /// Remove one temporary AI conversation from host memory.
+        case endAIConversation
+        /// AI mode: submit a prefilled question and skip ASR.
+        case submitAIQuestion
+    }
+
+    /// Wire version that includes submitAIQuestion + aiQuestionText.
+    public static let currentProtocolVersion = 5
+
+    public let protocolVersion: Int
+    public let sessionId: UUID
+    public let utteranceId: UUID
+    public let commandSeq: Int64
+    public let action: Action
+    public let localeId: String
+    public let createdAt: TimeInterval
+    public let fieldContext: FlowFieldContext?
+    /// Dictation (default) vs explicit edit mode. Absent on legacy v1 → dictation.
+    public let utteranceMode: FlowUtteranceMode?
+    /// Verified source for explicit last-input editing.
+    public let editSourceText: String?
+    public let sourceHistoryEntryID: UUID?
+    public let sourceHistoryEntryRevision: Int64?
+    /// Host-memory conversation used only by `.aiQuestion`.
+    public let aiConversationID: UUID?
+    /// Prefilled question used only by `.submitAIQuestion`.
+    public let aiQuestionText: String?
+    /// Absolute wall-clock deadlines survive extension reconstruction.
+    public let startDeadlineAt: TimeInterval?
+    public let processingDeadlineAt: TimeInterval?
+
+    public init(
+        protocolVersion: Int = FlowCommand.currentProtocolVersion,
+        sessionId: UUID,
+        utteranceId: UUID,
+        commandSeq: Int64,
+        action: Action,
+        localeId: String,
+        createdAt: TimeInterval = Date().timeIntervalSince1970,
+        fieldContext: FlowFieldContext? = nil,
+        utteranceMode: FlowUtteranceMode? = nil,
+        editSourceText: String? = nil,
+        sourceHistoryEntryID: UUID? = nil,
+        sourceHistoryEntryRevision: Int64? = nil,
+        aiConversationID: UUID? = nil,
+        aiQuestionText: String? = nil,
+        startDeadlineAt: TimeInterval? = nil,
+        processingDeadlineAt: TimeInterval? = nil
+    ) {
+        self.protocolVersion = protocolVersion
+        self.sessionId = sessionId
+        self.utteranceId = utteranceId
+        self.commandSeq = commandSeq
+        self.action = action
+        self.localeId = localeId
+        self.createdAt = createdAt
+        self.fieldContext = fieldContext
+        self.utteranceMode = utteranceMode
+        self.editSourceText = editSourceText
+        self.sourceHistoryEntryID = sourceHistoryEntryID
+        self.sourceHistoryEntryRevision = sourceHistoryEntryRevision
+        self.aiConversationID = aiConversationID
+        self.aiQuestionText = aiQuestionText
+        self.startDeadlineAt = startDeadlineAt
+        self.processingDeadlineAt = processingDeadlineAt
+    }
+
+    public var resolvedUtteranceMode: FlowUtteranceMode {
+        utteranceMode ?? .dictation
+    }
+}
@@ -0,0 +1,43 @@
+// FlowFieldContext.swift
+// OSGKeyboard · Shared
+
+import Foundation
+
+public struct FlowFieldContext: Codable, Equatable, Sendable {
+    public let precedingText: String?
+    public let followingText: String?
+    public let keyboardType: String?
+    public let returnKeyType: String?
+    public let isSecureEntry: Bool
+    /// Distinguishes a known-empty field from unavailable document context.
+    public let isEmptyField: Bool
+    public let isContextAvailable: Bool
+
+    public init(
+        precedingText: String? = nil,
+        followingText: String? = nil,
+        keyboardType: String? = nil,
+        returnKeyType: String? = nil,
+        isSecureEntry: Bool = false,
+        isEmptyField: Bool = false,
+        isContextAvailable: Bool = false
+    ) {
+        self.precedingText = isSecureEntry ? nil : precedingText
+        self.followingText = isSecureEntry ? nil : followingText
+        self.keyboardType = keyboardType
+        self.returnKeyType = returnKeyType
+        self.isSecureEntry = isSecureEntry
+        self.isEmptyField = isSecureEntry ? false : isEmptyField
+        self.isContextAvailable = isSecureEntry ? false : isContextAvailable
+    }
+
+    public var deliveryFingerprint: String? {
+        guard !isSecureEntry else { return nil }
+        return [
+            keyboardType ?? "",
+            returnKeyType ?? "",
+            precedingText.map { String($0.suffix(80)) } ?? "",
+            followingText.map { String($0.prefix(40)) } ?? "",
+        ].joined(separator: "|")
+    }
+}
@@ -0,0 +1,67 @@
+// FlowReadySnapshot.swift
+// OSGKeyboard · Shared
+
+import Foundation
+
+public struct FlowReadySnapshot: Codable, Equatable, Sendable {
+    public enum Reason: String, Codable, Sendable {
+        case ready
+        case noSession
+        case starting
+        case audioEngineNotLive
+        case waitingForAudioProof
+        case recording
+        case processing
+        case awaitingDelivery
+        case permissionMissing
+        case appGroupUnavailable
+        case hostLost
+        case error
+    }
+
+    public let protocolVersion: Int
+    public let sessionId: UUID?
+    public let ready: Bool
+    public let reason: Reason
+    public let heartbeatAt: TimeInterval
+    public let readyAt: TimeInterval?
+    public let audioProofAt: TimeInterval?
+    public let engineMode: String
+    public let localeId: String
+    public let busyUtteranceId: UUID?
+    public let sessionExpiresAt: TimeInterval?
+    /// Host process generation that wrote this snapshot. A snapshot whose
+    /// generation no longer matches `FlowSessionKeys.hostGeneration` was
+    /// written by a dead process and is void immediately — no need to wait
+    /// out the heartbeat-zombie window. Optional for wire compatibility with
+    /// snapshots written before this field existed.
+    public let hostGeneration: String?
+
+    public init(
+        protocolVersion: Int = 1,
+        sessionId: UUID?,
+        ready: Bool,
+        reason: Reason,
+        heartbeatAt: TimeInterval = Date().timeIntervalSince1970,
+        readyAt: TimeInterval? = nil,
+        audioProofAt: TimeInterval? = nil,
+        engineMode: String,
+        localeId: String,
+        busyUtteranceId: UUID? = nil,
+        sessionExpiresAt: TimeInterval? = nil,
+        hostGeneration: String? = nil
+    ) {
+        self.protocolVersion = protocolVersion
+        self.sessionId = sessionId
+        self.ready = ready
+        self.reason = reason
+        self.heartbeatAt = heartbeatAt
+        self.readyAt = readyAt
+        self.audioProofAt = audioProofAt
+        self.engineMode = engineMode
+        self.localeId = localeId
+        self.busyUtteranceId = busyUtteranceId
+        self.sessionExpiresAt = sessionExpiresAt
+        self.hostGeneration = hostGeneration
+    }
+}
@@ -0,0 +1,88 @@
+// FlowResult.swift
+// OSGKeyboard · Shared
+
+import Foundation
+
+public struct FlowResult: Codable, Equatable, Sendable {
+    public enum Status: String, Codable, Sendable {
+        case partial
+        case rawReady
+        /// AI-mode LLM answer draft (not ASR). Non-terminal.
+        case streaming
+        case final
+        case error
+        case aborted
+        case timeout
+    }
+
+    public let protocolVersion: Int
+    public let sessionId: UUID
+    public let utteranceId: UUID
+    public let commandSeq: Int64
+    public let status: Status
+    public let text: String?
+    public let warning: String?
+    public let errorKind: FlowSessionKeys.TranscriptionErrorKind?
+    /// Raw ASR survives polish/network failure and host process churn.
+    public let rawText: String?
+    public let hostGeneration: String?
+    /// Monotonically increases within one session/utterance; readers may discard
+    /// an equal or lower non-nil revision as a stale or duplicate delivery.
+    public let revision: Int64?
+    public let fieldFingerprint: String?
+    public let createdAt: TimeInterval
+    /// Echo of the command mode so the extension can skip raw fallback.
+    public let utteranceMode: FlowUtteranceMode?
+    /// History row created by normal dictation, or edited by edit mode.
+    public let historyEntryID: UUID?
+    public let historyEntryRevision: Int64?
+    /// Echoed for AI result validation; absent for dictation and edit.
+    public let aiConversationID: UUID?
+
+    public init(
+        protocolVersion: Int = FlowCommand.currentProtocolVersion,
+        sessionId: UUID,
+        utteranceId: UUID,
+        commandSeq: Int64,
+        status: Status,
+        text: String? = nil,
+        warning: String? = nil,
+        errorKind: FlowSessionKeys.TranscriptionErrorKind? = nil,
+        rawText: String? = nil,
+        hostGeneration: String? = nil,
+        revision: Int64? = nil,
+        fieldFingerprint: String? = nil,
+        createdAt: TimeInterval = Date().timeIntervalSince1970,
+        utteranceMode: FlowUtteranceMode? = nil,
+        historyEntryID: UUID? = nil,
+        historyEntryRevision: Int64? = nil,
+        aiConversationID: UUID? = nil
+    ) {
+        self.protocolVersion = protocolVersion
+        self.sessionId = sessionId
+        self.utteranceId = utteranceId
+        self.commandSeq = commandSeq
+        self.status = status
+        self.text = text
+        self.warning = warning
+        self.errorKind = errorKind
+        self.rawText = rawText
+        self.hostGeneration = hostGeneration
+        self.revision = revision
+        self.fieldFingerprint = fieldFingerprint
+        self.createdAt = createdAt
+        self.utteranceMode = utteranceMode
+        self.historyEntryID = historyEntryID
+        self.historyEntryRevision = historyEntryRevision
+        self.aiConversationID = aiConversationID
+    }
+
+    public var resolvedUtteranceMode: FlowUtteranceMode {
+        utteranceMode ?? .dictation
+    }
+
+    /// Instruction deliveries must never insert raw ASR into the field.
+    public var allowsRawFallback: Bool {
+        resolvedUtteranceMode == .dictation
+    }
+}
@@ -0,0 +1,33 @@
+// FlowStartTransaction.swift
+// OSGKeyboard · Shared
+
+import Foundation
+
+public struct FlowStartTransaction: Codable, Equatable, Sendable {
+    public enum Phase: String, Codable, Sendable {
+        case issued
+        case starting
+        case recording
+        case terminal
+    }
+
+    public let sessionID: UUID
+    public let utteranceID: UUID
+    public let deadlineAt: TimeInterval
+    public let phase: Phase
+    public let updatedAt: TimeInterval
+
+    public init(
+        sessionID: UUID,
+        utteranceID: UUID,
+        deadlineAt: TimeInterval,
+        phase: Phase,
+        updatedAt: TimeInterval = Date().timeIntervalSince1970
+    ) {
+        self.sessionID = sessionID
+        self.utteranceID = utteranceID
+        self.deadlineAt = deadlineAt
+        self.phase = phase
+        self.updatedAt = updatedAt
+    }
+}
@@ -0,0 +1,14 @@
+// FlowTranscriptionError.swift
+// OSGKeyboard · Shared
+
+import Foundation
+
+public struct FlowTranscriptionError: Equatable, Sendable {
+    public let message: String
+    public let kind: FlowSessionKeys.TranscriptionErrorKind
+
+    public init(message: String, kind: FlowSessionKeys.TranscriptionErrorKind) {
+        self.message = message
+        self.kind = kind
+    }
+}