feat(overlay): fade suggestions in with an opacity ramp, toggleable in Settings (#749)

Author: FuJacob

Cotabby.xcodeproj/project.pbxproj

@@ -71,6 +71,7 @@
 		157A55EB796BEB7819B90D5D /* ClipboardRelevanceFilter.swift in Sources */ = {isa = PBXBuildFile; fileRef = D3A2AC525DC664DB540D4F19 /* ClipboardRelevanceFilter.swift */; };
 		15D4C75B6BA901E110AC929F /* InlinePreviewPanelController.swift in Sources */ = {isa = PBXBuildFile; fileRef = AAEFF8BAEC9168CADEDD4757 /* InlinePreviewPanelController.swift */; };
 		15FA56CEF6FB5FF54C2FBA6F /* PermissionAndContextModelTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = E7F42112F14026E6253BB865 /* PermissionAndContextModelTests.swift */; };
+		1671E0A3C8D6DF30C5AD7F9F /* SuggestionFadeInPolicy.swift in Sources */ = {isa = PBXBuildFile; fileRef = 764EE0693994E2E126E7FC77 /* SuggestionFadeInPolicy.swift */; };
 		1681C0F22323FB1156579D99 /* AGPL-3.0.txt in Resources */ = {isa = PBXBuildFile; fileRef = 6F0EE728C0B1A7AD6B19CD0C /* AGPL-3.0.txt */; };
 		175C4FA56C29DEE58C2D4D7E /* SuggestionSettingsModel.swift in Sources */ = {isa = PBXBuildFile; fileRef = 86460C747AA883FDE756BDBA /* SuggestionSettingsModel.swift */; };
 		18382D1919D90E3C1EE143C2 /* AppSurfaceClassifierTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = C451E144D220D5C63372A8C0 /* AppSurfaceClassifierTests.swift */; };
@@ -295,6 +296,7 @@
 		610650A14AC5E8EDDC81B4E9 /* PermissionReminderView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 168A0DBF62BEF674B96CEBD2 /* PermissionReminderView.swift */; };
 		6106B16C0DBA94EBF838D93E /* PermissionOverlayTracker.swift in Sources */ = {isa = PBXBuildFile; fileRef = E6423D6CC8CC371D2DA899DE /* PermissionOverlayTracker.swift */; };
 		613C60F5D664655CB4D8CC27 /* WelcomePermissionStepView.swift in Sources */ = {isa = PBXBuildFile; fileRef = D27A2CEA7B4E0CDACBC986C2 /* WelcomePermissionStepView.swift */; };
+		614F45951D2BD56406E1F95E /* SuggestionFadeInPolicy.swift in Sources */ = {isa = PBXBuildFile; fileRef = 764EE0693994E2E126E7FC77 /* SuggestionFadeInPolicy.swift */; };
 		61635150B8004F6CB2FACE65 /* AppSurfaceClassifier.swift in Sources */ = {isa = PBXBuildFile; fileRef = 94B0830FBE4F2E239F670DBA /* AppSurfaceClassifier.swift */; };
 		61EC9D635D416115E7C96E0F /* PermissionOverlayWindowController.swift in Sources */ = {isa = PBXBuildFile; fileRef = 92C6EB9FDA48ADF425A116A9 /* PermissionOverlayWindowController.swift */; };
 		62DBCF429B7F464A6B467725 /* OnboardingFeatureShowcase.swift in Sources */ = {isa = PBXBuildFile; fileRef = 926B332E7B4CFEE42C4CAA75 /* OnboardingFeatureShowcase.swift */; };
@@ -392,6 +394,7 @@
 		88BCD795A14E1C9308F7BB31 /* SuggestionAvailabilityEvaluatorTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = C05B0439348261163B37C508 /* SuggestionAvailabilityEvaluatorTests.swift */; };
 		89329024F050602EFBC7CC6B /* FocusTracker.swift in Sources */ = {isa = PBXBuildFile; fileRef = 5C9FDF029F7828CAF3FE8850 /* FocusTracker.swift */; };
 		8A47597B097058832453C2FF /* LlamaSuggestionEvalTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = A691EB51A7B93D1FAC38657F /* LlamaSuggestionEvalTests.swift */; };
+		8A88C3A598E65E4127FEEC3D /* SuggestionFadeInPolicyTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 442507A5399ACD81D1DB4936 /* SuggestionFadeInPolicyTests.swift */; };
 		8B26F7B26358438D6EB88C2E /* PerformanceMetricsStoreTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 7C0FCC5CCF6AE528E3C4DDA7 /* PerformanceMetricsStoreTests.swift */; };
 		8B2DFC860803C0A7C4D34A36 /* ContextBuffer.swift in Sources */ = {isa = PBXBuildFile; fileRef = 54EF3C7F5D9D6F3FA50FD51C /* ContextBuffer.swift */; };
 		8D0F66DD1E6C988368A4545D /* DownloadFileRescuer.swift in Sources */ = {isa = PBXBuildFile; fileRef = B4B4A2E2DD6733658EC05BD8 /* DownloadFileRescuer.swift */; };
@@ -804,6 +807,7 @@
 		421FD16E18622824E038DFB4 /* CaretRunPlacementTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CaretRunPlacementTests.swift; sourceTree = "<group>"; };
 		43D627C4A55359EAF4676FF7 /* InsertionSafetyGateTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = InsertionSafetyGateTests.swift; sourceTree = "<group>"; };
 		43E37A7E835D3BDE6265843C /* TerminalAppDetectorTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = TerminalAppDetectorTests.swift; sourceTree = "<group>"; };
+		442507A5399ACD81D1DB4936 /* SuggestionFadeInPolicyTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SuggestionFadeInPolicyTests.swift; sourceTree = "<group>"; };
 		4451D6673112575DF24C4A48 /* OnboardingTemplate.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OnboardingTemplate.swift; sourceTree = "<group>"; };
 		44595B534DD7323F0AD60825 /* MenuBarPopoverDismisser.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MenuBarPopoverDismisser.swift; sourceTree = "<group>"; };
 		45A896811745673061AF3612 /* SuggestionFocusFreshnessTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SuggestionFocusFreshnessTests.swift; sourceTree = "<group>"; };
@@ -875,6 +879,7 @@
 		7513810E78F3C94FE972EB07 /* LGPL-3.0.txt */ = {isa = PBXFileReference; lastKnownFileType = text; path = "LGPL-3.0.txt"; sourceTree = "<group>"; };
 		75396860978E81EFAA506CD4 /* EmojiQueryRunTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = EmojiQueryRunTests.swift; sourceTree = "<group>"; };
 		764659D09C3F0E8FBD267102 /* EmojiPickerPanelController.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = EmojiPickerPanelController.swift; sourceTree = "<group>"; };
+		764EE0693994E2E126E7FC77 /* SuggestionFadeInPolicy.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SuggestionFadeInPolicy.swift; sourceTree = "<group>"; };
 		77B0121E7BB173F8A2B0B108 /* WindowScreenshotService.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = WindowScreenshotService.swift; sourceTree = "<group>"; };
 		78AFA4586C82E92D7FBF381B /* ArithmeticEvaluatorTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ArithmeticEvaluatorTests.swift; sourceTree = "<group>"; };
 		78E280F4F39A9D86840800D2 /* SuggestionCoordinator+Lifecycle.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "SuggestionCoordinator+Lifecycle.swift"; sourceTree = "<group>"; };
@@ -1558,6 +1563,7 @@
 				FD60968AEA8A5843F4E24618 /* SuggestionDebugLoggerTests.swift */,
 				470A7DAE3D6A2C873B395AE3 /* SuggestionEngineModelsTests.swift */,
 				3BDA36955CCCFA87C1F67268 /* SuggestionEngineRouterTests.swift */,
+				442507A5399ACD81D1DB4936 /* SuggestionFadeInPolicyTests.swift */,
 				45A896811745673061AF3612 /* SuggestionFocusFreshnessTests.swift */,
 				8CB1D4F2681FAF59014AE115 /* SuggestionInteractionStateTests.swift */,
 				CDB25ABC4FFB0E63477CDCB0 /* SuggestionOverlayStabilityGateTests.swift */,
@@ -1772,6 +1778,7 @@
 				299BD7B741DA4AAE6A061BAD /* StreamedGhostTextPolicy.swift */,
 				E99C99D2782EAF0492F964EF /* SuggestionAnchorCache.swift */,
 				3609CC88A5280B3AA40414DF /* SuggestionAvailabilityEvaluator.swift */,
+				764EE0693994E2E126E7FC77 /* SuggestionFadeInPolicy.swift */,
 				B2F95847D76893C8A5B504B4 /* SuggestionOverlayStabilityGate.swift */,
 				DDE858CB1E687E3CEB8FDD5B /* SuggestionRequestFactory.swift */,
 				CE0AA0503128B0FC3951D700 /* SuggestionSessionReconciler.swift */,
@@ -2191,6 +2198,7 @@
 				094DE1CA4A821D722F173F9D /* SuggestionDebugLogger.swift in Sources */,
 				08A161D7775D09D116E48F6D /* SuggestionEngineModels.swift in Sources */,
 				9973763A9F4EA4D8B4AE59EB /* SuggestionEngineRouter.swift in Sources */,
+				1671E0A3C8D6DF30C5AD7F9F /* SuggestionFadeInPolicy.swift in Sources */,
 				CF2EADEEEF5AA63FB9B9EA8E /* SuggestionInserter.swift in Sources */,
 				F28FB178EC507C3D42A6F893 /* SuggestionInteractionState.swift in Sources */,
 				7DEFC57991AB0C5379AD9CBF /* SuggestionModels.swift in Sources */,
@@ -2437,6 +2445,7 @@
 				3C23336EE6F6559857DE92EE /* SuggestionDebugLogger.swift in Sources */,
 				A93A741C8C3973687D28F0B6 /* SuggestionEngineModels.swift in Sources */,
 				52518CF0760DFEE9AF7C786C /* SuggestionEngineRouter.swift in Sources */,
+				614F45951D2BD56406E1F95E /* SuggestionFadeInPolicy.swift in Sources */,
 				2FC40D4BFDD05C2401D7A5E9 /* SuggestionInserter.swift in Sources */,
 				A982E243A4D8BC1BF7504B3E /* SuggestionInteractionState.swift in Sources */,
 				0AF568AB234033BA2DE4CAA7 /* SuggestionModels.swift in Sources */,
@@ -2612,6 +2621,7 @@
 				9938DE59D9E05BC51A5BA5B8 /* SuggestionDebugLoggerTests.swift in Sources */,
 				19CA1BF8B508E0E219EF4485 /* SuggestionEngineModelsTests.swift in Sources */,
 				449218D0646AB3745B7E4F30 /* SuggestionEngineRouterTests.swift in Sources */,
+				8A88C3A598E65E4127FEEC3D /* SuggestionFadeInPolicyTests.swift in Sources */,
 				5CED06E89FBEF557DCD6C684 /* SuggestionFocusFreshnessTests.swift in Sources */,
 				6CBEF02FCDFCF406E378C27C /* SuggestionInteractionStateTests.swift in Sources */,
 				4C6D8ED0A7B45D2EADF06DA5 /* SuggestionOverlayStabilityGateTests.swift in Sources */,

Cotabby/Models/SuggestionSettingsData.swift

@@ -75,6 +75,14 @@ struct SuggestionSettingsData: Equatable {
     /// acceptable session the user can Tab into early. When off (the default), the suggestion appears
     /// once, fully formed, after generation finishes.
     var streamSuggestionsWhileGenerating: Bool
+    /// When on (the default), a newly shown suggestion fades in over a short opacity ramp instead of
+    /// snapping to full strength. Purely cosmetic and consumed only by the overlay renderer; the fade
+    /// is suppressed automatically when the system "Reduce Motion" setting is on.
+    var fadeInSuggestions: Bool
+    /// Duration in seconds of that fade-in ramp. Read live by the overlay renderer and surfaced as a
+    /// Slow-to-Fast speed slider in Settings; lower is a faster fade. See
+    /// `SuggestionSettingsStore.clampedFadeInDuration` for the bounds.
+    var fadeInDurationSeconds: Double
     var acceptanceKeyCode: CGKeyCode
     var acceptanceKeyModifiers: ShortcutModifierMask
     var acceptanceKeyLabel: String

Cotabby/Models/SuggestionSettingsModel.swift

@@ -104,6 +104,14 @@ final class SuggestionSettingsModel: ObservableObject {
     @Published private(set) var autoAcceptTrailingPunctuation: Bool
     @Published private(set) var addSpaceAfterAccept: Bool
     @Published private(set) var streamSuggestionsWhileGenerating: Bool
+    /// Whether a newly shown suggestion fades in. Read live by `OverlayController` at present time, so
+    /// toggling it takes effect on the very next suggestion without any subscription bookkeeping. Not
+    /// part of `snapshot`: it never reaches generation, only the overlay renderer.
+    @Published private(set) var fadeInSuggestions: Bool
+    /// Duration of the fade-in ramp in seconds. Read live by `OverlayController` alongside
+    /// `fadeInSuggestions`, so dragging the speed slider takes effect on the next suggestion. Lower is
+    /// a faster fade. Like `fadeInSuggestions`, it never reaches generation, only the overlay renderer.
+    @Published private(set) var fadeInDurationSeconds: Double
     @Published private(set) var acceptanceKeyCode: CGKeyCode
     @Published private(set) var acceptanceKeyModifiers: ShortcutModifierMask
     @Published private(set) var acceptanceKeyLabel: String
@@ -146,6 +154,10 @@ final class SuggestionSettingsModel: ObservableObject {
     static let maximumGhostTextSizeMultiplier = SuggestionSettingsStore.maximumGhostTextSizeMultiplier
     static let defaultGhostTextSizeMultiplier = SuggestionSettingsStore.defaultGhostTextSizeMultiplier
     static let ghostTextSizeMultiplierStep = SuggestionSettingsStore.ghostTextSizeMultiplierStep
+    static let minimumFadeInDuration = SuggestionSettingsStore.minimumFadeInDuration
+    static let maximumFadeInDuration = SuggestionSettingsStore.maximumFadeInDuration
+    static let defaultFadeInDuration = SuggestionSettingsStore.defaultFadeInDuration
+    static let fadeInDurationStep = SuggestionSettingsStore.fadeInDurationStep
     static let maximumExtendedContextCharacters = SuggestionSettingsStore.maximumExtendedContextCharacters
 
     init(
@@ -259,6 +271,8 @@ final class SuggestionSettingsModel: ObservableObject {
         autoAcceptTrailingPunctuation = data.autoAcceptTrailingPunctuation
         addSpaceAfterAccept = data.addSpaceAfterAccept
         streamSuggestionsWhileGenerating = data.streamSuggestionsWhileGenerating
+        fadeInSuggestions = data.fadeInSuggestions
+        fadeInDurationSeconds = data.fadeInDurationSeconds
         acceptanceKeyCode = data.acceptanceKeyCode
         acceptanceKeyModifiers = data.acceptanceKeyModifiers
         acceptanceKeyLabel = data.acceptanceKeyLabel
@@ -616,6 +630,23 @@ final class SuggestionSettingsModel: ObservableObject {
         store.saveStreamSuggestionsWhileGenerating(enabled)
     }
 
+    func setFadeInSuggestions(_ enabled: Bool) {
+        guard fadeInSuggestions != enabled else {
+            return
+        }
+        fadeInSuggestions = enabled
+        store.saveFadeInSuggestions(enabled)
+    }
+
+    func setFadeInDurationSeconds(_ seconds: Double) {
+        let clamped = SuggestionSettingsStore.clampedFadeInDuration(seconds)
+        guard fadeInDurationSeconds != clamped else {
+            return
+        }
+        fadeInDurationSeconds = clamped
+        store.saveFadeInDurationSeconds(clamped)
+    }
+
     func setAcceptanceGranularity(_ granularity: AcceptanceGranularity) {
         guard acceptanceGranularity != granularity else {
             return

Cotabby/Services/UI/OverlayController.swift

@@ -1,6 +1,7 @@
 import AppKit
 import Foundation
 import Logging
+import QuartzCore
 import SwiftUI
 
 /// File overview:
@@ -105,13 +106,35 @@ final class OverlayController: SuggestionOverlayControlling {
             return
         }
 
+        // Decide on the fade using the panel state captured *before* `state` is reassigned below, so
+        // the animation plays only on a genuine appearance. A reposition and a streamed-token
+        // extension re-enter this path while the panel stays visible; restarting the opacity ramp on
+        // either would make stable ghost text flicker. Note `advanceInline` calls `showInline`
+        // directly and never routes through here, so it is exempt by construction without needing
+        // the `overlayWasVisible` guard.
+        let fadesIn = SuggestionFadeInPolicy.shouldFadeIn(
+            isEnabled: suggestionSettings.fadeInSuggestions,
+            overlayWasVisible: state.isVisible,
+            reduceMotionEnabled: reduceMotionEnabled
+        )
+
         // Per-app render-mode overrides are not wired yet, so the policy always resolves without a
         // host bundle identifier; thread the focused app's id here when per-app overrides ship.
         let mode = currentRenderModePolicy.mode(
             for: geometry,
             bundleIdentifier: nil
         )
 
+        // Start fully transparent so the panel's first composited frame is invisible. Setting alpha
+        // before the show paths call `orderFront` avoids a one-frame flash at full opacity. The else
+        // branch resets the model value directly (off the animator), which cancels any stale mid-ramp
+        // animation left paused by an order-out so a non-fading show can't resume semi-transparent.
+        if fadesIn {
+            panel.alphaValue = 0
+        } else {
+            panel.alphaValue = 1
+        }
+
         switch mode {
         case .inline:
             showInline(text: text, geometry: geometry)
@@ -120,6 +143,10 @@ final class OverlayController: SuggestionOverlayControlling {
         }
 
         state = .visible(text: text, geometry: geometry, mode: mode)
+
+        if fadesIn {
+            fadeInPanel()
+        }
     }
 
     /// Hides the floating panel and records why the overlay is no longer visible.
@@ -128,6 +155,26 @@ final class OverlayController: SuggestionOverlayControlling {
         state = .hidden(reason: reason)
     }
 
+    /// Mirrors the system Accessibility "Reduce Motion" preference. Read live so flipping it in
+    /// System Settings suppresses the fade on the next suggestion without relaunching Cotabby.
+    private var reduceMotionEnabled: Bool {
+        NSWorkspace.shared.accessibilityDisplayShouldReduceMotion
+    }
+
+    /// Ramps the panel from fully transparent to opaque over the user's configured fade duration.
+    /// Driven through the AppKit animator proxy, which animates independently of
+    /// `panel.animationBehavior` (kept `.none` so AppKit's own order-in spring stays off). Starting a
+    /// fresh ramp supersedes any still-running one, so a rapid hide/show cannot strand the panel
+    /// mid-fade. The duration is read live (the model keeps it clamped to a sane band), so the
+    /// Settings speed slider takes effect on the very next suggestion.
+    private func fadeInPanel() {
+        NSAnimationContext.runAnimationGroup { context in
+            context.duration = suggestionSettings.fadeInDurationSeconds
+            context.timingFunction = CAMediaTimingFunction(name: .easeOut)
+            panel.animator().alphaValue = 1
+        }
+    }
+
     /// Inline ghost text drawn next to the caret. This is the original rendering path; the body
     /// stays unchanged from the pre-mirror behavior aside from being extracted into its own method.
     ///

Cotabby/Support/SuggestionFadeInPolicy.swift

@@ -0,0 +1,28 @@
+import Foundation
+
+/// Decides whether a freshly shown ghost-text overlay should fade in rather than appear instantly.
+///
+/// The hard rule this protects: a fade may only play on a *genuine appearance* of the overlay, never
+/// on an update to one that is already on screen. Caret repositions, streamed-token extensions, and
+/// word-by-word advances all re-invoke the show path while the panel stays visible; restarting the
+/// opacity animation on any of those would make stable ghost text flicker on every keystroke. The
+/// `overlayWasVisible` input is the panel state captured *before* the new content is applied, so a
+/// `false` value means the panel was hidden and this is a real first paint.
+///
+/// `reduceMotionEnabled` mirrors the system Accessibility "Reduce Motion" preference. Honoring it
+/// suppresses the animation even when the user has the Cotabby toggle on, because non-essential
+/// motion is exactly what that setting asks apps to drop; the suggestion still appears, just without
+/// the fade. Keeping the decision in a pure function lets all three inputs be exhaustively tested
+/// without standing up an `NSPanel` or AppKit animation.
+enum SuggestionFadeInPolicy {
+    static func shouldFadeIn(
+        isEnabled: Bool,
+        overlayWasVisible: Bool,
+        reduceMotionEnabled: Bool
+    ) -> Bool {
+        guard isEnabled, !reduceMotionEnabled else {
+            return false
+        }
+        return !overlayWasVisible
+    }
+}