@sriinnu/runic 1.0.0

package/Sources/Runic/UsagePaceText.swift

@@ -0,0 +1,52 @@
+import RunicCore
+import Foundation
+
+enum UsagePaceText {
+    private static let minimumExpectedPercent: Double = 3
+
+    static func weekly(provider: UsageProvider, window: RateWindow, now: Date = .init()) -> String? {
+        guard provider == .codex || provider == .claude else { return nil }
+        guard window.remainingPercent > 0 else { return nil }
+        guard let pace = UsagePace.weekly(window: window, now: now, defaultWindowMinutes: 10080) else { return nil }
+        guard pace.expectedUsedPercent >= Self.minimumExpectedPercent else { return nil }
+
+        let label = Self.label(for: pace.stage)
+        let deltaSuffix = Self.deltaSuffix(for: pace)
+        let etaSuffix = Self.etaSuffix(for: pace, now: now)
+
+        if let etaSuffix {
+            return "Pace: \(label)\(deltaSuffix) · \(etaSuffix)"
+        }
+        return "Pace: \(label)\(deltaSuffix)"
+    }
+
+    private static func label(for stage: UsagePace.Stage) -> String {
+        switch stage {
+        case .onTrack: "On pace"
+        case .slightlyAhead, .ahead, .farAhead: "Ahead"
+        case .slightlyBehind, .behind, .farBehind: "Behind"
+        }
+    }
+
+    private static func deltaSuffix(for pace: UsagePace) -> String {
+        let deltaValue = Int(abs(pace.deltaPercent).rounded())
+        let sign = pace.deltaPercent >= 0 ? "+" : "-"
+        return " (\(sign)\(deltaValue)%)"
+    }
+
+    private static func etaSuffix(for pace: UsagePace, now: Date) -> String? {
+        if pace.willLastToReset { return "Lasts to reset" }
+        guard let etaSeconds = pace.etaSeconds else { return nil }
+        let etaText = Self.durationText(seconds: etaSeconds, now: now)
+        if etaText == "now" { return "Runs out now" }
+        return "Runs out in \(etaText)"
+    }
+
+    private static func durationText(seconds: TimeInterval, now: Date) -> String {
+        let date = now.addingTimeInterval(seconds)
+        let countdown = UsageFormatter.resetCountdownDescription(from: date, now: now)
+        if countdown == "now" { return "now" }
+        if countdown.hasPrefix("in ") { return String(countdown.dropFirst(3)) }
+        return countdown
+    }
+}

package/Sources/Runic/UsageProgressBar.swift

@@ -0,0 +1,224 @@
+import SwiftUI
+
+/// Modern progress bar with gradient fill, glow effects, and smooth animations.
+///
+/// Features:
+/// - Gradient fill for depth and visual interest
+/// - Subtle glow/shadow on the filled portion
+/// - Smooth animations with spring physics
+/// - Multiple height options for different contexts
+/// - Accessible with VoiceOver support
+/// - Adapts to menu highlight state
+struct UsageProgressBar: View {
+    /// Height variants for different use cases
+    enum Height {
+        case compact    // 6pt - for dense layouts, team member rows
+        case regular    // 8pt - default, used in most menus
+        case large      // 10pt - for prominent displays
+
+        var value: CGFloat {
+            switch self {
+            case .compact: return 6
+            case .regular: return 8
+            case .large: return 10
+            }
+        }
+    }
+
+    let percent: Double
+    let tint: Color
+    let accessibilityLabel: String
+    let height: Height
+
+    @Environment(\.menuItemHighlighted) private var isHighlighted
+    @State private var animatedPercent: Double = 0
+    @State private var sheenPhase: CGFloat = 0
+    @State private var sheenTask: Task<Void, Never>?
+
+    init(
+        percent: Double,
+        tint: Color,
+        accessibilityLabel: String,
+        height: Height = .regular)
+    {
+        self.percent = percent
+        self.tint = tint
+        self.accessibilityLabel = accessibilityLabel
+        self.height = height
+    }
+
+    private var clamped: Double {
+        min(100, max(0, self.percent))
+    }
+
+    private var barHeight: CGFloat {
+        self.height.value
+    }
+
+    var body: some View {
+        GeometryReader { proxy in
+            let width = proxy.size.width
+            let fillWidth = (self.animatedPercent / 100) * width
+            let trackColor = Color(nsColor: .tertiaryLabelColor).opacity(self.isHighlighted ? RunicColors.Opacity.medium : RunicColors.Opacity.medium)
+            let tintColor = self.tint
+
+            ZStack(alignment: .leading) {
+                // Background track with depth
+                Capsule()
+                    .fill(trackColor)
+                    .overlay {
+                        Capsule()
+                            .strokeBorder(
+                                trackColor.opacity(RunicColors.Opacity.strong),
+                                lineWidth: 0.5)
+                    }
+                    .overlay {
+                        Capsule()
+                            .fill(
+                                LinearGradient(
+                                    colors: [
+                                        Color.white.opacity(self.isHighlighted ? RunicColors.Opacity.subtle : RunicColors.Opacity.light),
+                                        Color.clear,
+                                    ],
+                                    startPoint: .top,
+                                    endPoint: .bottom))
+                    }
+
+                // Tick marks (subtle)
+                ForEach([0.25, 0.5, 0.75], id: \.self) { fraction in
+                    Rectangle()
+                        .fill(Color.white.opacity(RunicColors.Opacity.light))
+                        .frame(width: 1, height: self.barHeight - 2)
+                        .offset(x: width * fraction - 0.5)
+                        .blendMode(.screen)
+                }
+
+                // Filled portion with gradient, texture, and glow
+                if fillWidth > 0 {
+                    Capsule()
+                        .fill(self.fillGradient(base: tintColor))
+                        .frame(width: max(fillWidth, self.barHeight))
+                        .shadow(
+                            color: tintColor.opacity(self.isHighlighted ? 0 : 0.3),
+                            radius: self.barHeight * 0.4,
+                            x: 0,
+                            y: 0)
+                        .overlay {
+                            ZStack {
+                                // Subtle highlight on top for glossy effect
+                                Capsule()
+                                    .fill(
+                                        LinearGradient(
+                                            colors: [
+                                                Color.white.opacity(RunicColors.Opacity.medium),
+                                                Color.clear,
+                                            ],
+                                            startPoint: .top,
+                                            endPoint: .center))
+                                    .frame(width: max(fillWidth, self.barHeight))
+
+                                // Texture segments for a premium "status bar" look
+                                self.segmentTexture(width: max(fillWidth, self.barHeight))
+                            }
+                        }
+                        .overlay {
+                            if fillWidth > self.barHeight * 2 {
+                                self.sheenOverlay(width: max(fillWidth, self.barHeight), tint: tintColor)
+                            }
+                        }
+
+                    // End cap glow
+                    let capSize = self.barHeight * 0.9
+                    let capX = min(max(fillWidth, capSize / 2), width - capSize / 2)
+                    Circle()
+                        .fill(tintColor)
+                        .frame(width: capSize, height: capSize)
+                        .shadow(color: tintColor.opacity(RunicColors.Opacity.strong), radius: 4, x: 0, y: 0)
+                        .overlay(
+                            Circle()
+                                .stroke(Color.white.opacity(RunicColors.Opacity.emphasis), lineWidth: 0.5))
+                        .offset(x: capX - capSize / 2)
+                }
+            }
+            .frame(width: width, height: self.barHeight, alignment: .leading)
+        }
+        .frame(height: self.barHeight)
+        .accessibilityElement(children: .ignore)
+        .accessibilityLabel(self.accessibilityLabel)
+        .accessibilityValue("\(Int(self.clamped)) percent")
+        .accessibilityAddTraits(.updatesFrequently)
+        .drawingGroup(opaque: false)
+        .onAppear {
+            // Initial animation with slight delay for staggered effect
+            withAnimation(RunicAnimation.barAppear) {
+                self.animatedPercent = self.clamped
+            }
+            self.playSheen()
+        }
+        .onChange(of: self.clamped) { _, newValue in
+            // Smooth spring animation on value changes
+            withAnimation(RunicAnimation.barUpdate) {
+                self.animatedPercent = newValue
+            }
+            self.playSheen()
+        }
+    }
+
+    /// Creates a modern gradient fill with depth
+    private func fillGradient(base: Color) -> LinearGradient {
+        LinearGradient(
+            colors: [
+                base.opacity(0.98),
+                base.opacity(0.85),
+                base.opacity(0.92),
+            ],
+            startPoint: .top,
+            endPoint: .bottom)
+    }
+
+    private func segmentTexture(width: CGFloat) -> some View {
+        let count = max(6, Int(width / 22))
+        return HStack(spacing: RunicSpacing.xxxs) {
+            ForEach(0..<count, id: \.self) { _ in
+                RoundedRectangle(cornerRadius: 2, style: .continuous)
+                    .fill(Color.white.opacity(self.isHighlighted ? RunicColors.Opacity.subtle : RunicColors.Opacity.light))
+            }
+        }
+        .padding(.horizontal, RunicSpacing.xxxs)
+        .padding(.vertical, 1)
+        .mask(Capsule())
+    }
+
+    private func sheenOverlay(width: CGFloat, tint: Color) -> some View {
+        let gradient = LinearGradient(
+            colors: [
+                Color.white.opacity(0.0),
+                Color.white.opacity(self.isHighlighted ? 0.2 : 0.45),
+                Color.white.opacity(0.0),
+            ],
+            startPoint: .top,
+            endPoint: .bottom)
+        let travel = width + self.barHeight * 2
+        let offset = (self.sheenPhase * travel) - (travel / 2)
+
+        return Rectangle()
+            .fill(gradient)
+            .frame(width: self.barHeight * 2, height: self.barHeight * 2)
+            .rotationEffect(.degrees(20))
+            .offset(x: offset)
+            .mask(Capsule().frame(width: width, height: self.barHeight))
+            .blendMode(.screen)
+    }
+
+    private func playSheen() {
+        self.sheenTask?.cancel()
+        self.sheenPhase = 0
+        withAnimation(.easeOut(duration: RunicAnimation.sheenDuration)) {
+            self.sheenPhase = 1
+        }
+        self.sheenTask = Task { @MainActor in
+            try? await Task.sleep(for: RunicAnimation.sheenResetDelay)
+            self.sheenPhase = 0
+        }
+    }
+}

package/Sources/Runic/Utilities/DisplayLink.swift

@@ -0,0 +1,96 @@
+import AppKit
+import CoreVideo
+import Observation
+import QuartzCore
+
+/// Minimal display link driver using NSScreen.displayLink on macOS 15+,
+/// and CVDisplayLink on macOS 14.
+/// Publishes ticks on the main thread at the requested frame rate.
+@MainActor
+@Observable
+final class DisplayLinkDriver {
+    // Published counter used to drive SwiftUI updates.
+    var tick: Int = 0
+    private var displayLink: CADisplayLink?
+    private var cvDisplayLink: CVDisplayLink?
+    private var targetInterval: CFTimeInterval = 1.0 / 60.0
+    private var lastTickTimestamp: CFTimeInterval = 0
+    private let onTick: (() -> Void)?
+
+    init(onTick: (() -> Void)? = nil) {
+        self.onTick = onTick
+    }
+
+    func start(fps: Double = 12) {
+        guard self.displayLink == nil, self.cvDisplayLink == nil else { return }
+        let clampedFps = max(fps, 1)
+        self.targetInterval = 1.0 / clampedFps
+        self.lastTickTimestamp = 0
+        if #available(macOS 15, *), let screen = NSScreen.main {
+            // NSScreen.displayLink is macOS 15+ only.
+            let displayLink = screen.displayLink(target: self, selector: #selector(self.step))
+            let rate = Float(clampedFps)
+            displayLink.preferredFrameRateRange = CAFrameRateRange(
+                minimum: rate,
+                maximum: rate,
+                preferred: rate)
+            displayLink.add(to: .main, forMode: .common)
+            self.displayLink = displayLink
+        } else {
+            self.startCVDisplayLink()
+        }
+    }
+
+    func stop() {
+        self.displayLink?.invalidate()
+        self.displayLink = nil
+        if let cvDisplayLink = self.cvDisplayLink {
+            CVDisplayLinkStop(cvDisplayLink)
+        }
+        self.cvDisplayLink = nil
+    }
+
+    @objc private func step(_: AnyObject) {
+        self.handleTick()
+    }
+
+    private func handleTick() {
+        let now = CACurrentMediaTime()
+        if self.lastTickTimestamp > 0, now - self.lastTickTimestamp < self.targetInterval {
+            return
+        }
+        self.lastTickTimestamp = now
+        // Safe on main runloop; drives SwiftUI updates.
+        self.tick &+= 1
+        self.onTick?()
+    }
+
+    private func startCVDisplayLink() {
+        var link: CVDisplayLink?
+        if CVDisplayLinkCreateWithActiveCGDisplays(&link) != kCVReturnSuccess {
+            return
+        }
+        guard let link else { return }
+        let callback: CVDisplayLinkOutputCallback = { _, _, _, _, _, userInfo in
+            guard let userInfo else { return kCVReturnSuccess }
+            let driver = Unmanaged<DisplayLinkDriver>.fromOpaque(userInfo).takeUnretainedValue()
+            driver.scheduleTick()
+            return kCVReturnSuccess
+        }
+        CVDisplayLinkSetOutputCallback(link, callback, Unmanaged.passUnretained(self).toOpaque())
+        CVDisplayLinkStart(link)
+        self.cvDisplayLink = link
+    }
+
+    private nonisolated func scheduleTick() {
+        Task { @MainActor [weak self] in
+            self?.handleTick()
+        }
+    }
+
+    deinit {
+        Task { @MainActor [weak self] in
+            self?.stop()
+        }
+    }
+}

package/Sources/Runic/Utilities/LoadingPattern.swift

@@ -0,0 +1,60 @@
+import Foundation
+
+enum LoadingPattern: String, CaseIterable, Identifiable {
+    case knightRider
+    case cylon
+    case outsideIn
+    case race
+    case pulse
+    case unbraid
+
+    var id: String { self.rawValue }
+
+    var displayName: String {
+        switch self {
+        case .knightRider: "Knight Rider"
+        case .cylon: "Cylon"
+        case .outsideIn: "Outside-In"
+        case .race: "Race"
+        case .pulse: "Pulse"
+        case .unbraid: "Unbraid (logo → bars)"
+        }
+    }
+
+    // Secondary offset so the lower bar moves differently.
+    var secondaryOffset: Double {
+        switch self {
+        case .knightRider: .pi
+        case .cylon: .pi / 2
+        case .outsideIn: .pi
+        case .race: .pi / 3
+        case .pulse: .pi / 2
+        case .unbraid: .pi / 2
+        }
+    }
+
+    func value(phase: Double) -> Double {
+        let v: Double
+        switch self {
+        case .knightRider:
+            v = 0.5 + 0.5 * sin(phase) // ping-pong
+        case .cylon:
+            let t = phase.truncatingRemainder(dividingBy: .pi * 2) / (.pi * 2)
+            v = t // sawtooth 0→1
+        case .outsideIn:
+            v = abs(cos(phase)) // high at edges, dip center
+        case .race:
+            let t = (phase * 1.2).truncatingRemainder(dividingBy: .pi * 2) / (.pi * 2)
+            v = t
+        case .pulse:
+            v = 0.4 + 0.6 * (0.5 + 0.5 * sin(phase)) // 40–100%
+        case .unbraid:
+            v = 0.5 + 0.5 * sin(phase) // smooth 0→1 for morph
+        }
+        return max(0, min(v * 100, 100))
+    }
+}
+
+extension Notification.Name {
+    static let runicDebugReplayAllAnimations = Notification.Name("runicDebugReplayAllAnimations")
+}

package/Sources/Runic/Utilities/PerformanceConstants.swift

@@ -0,0 +1,85 @@
+import Foundation
+
+/// **Runic Performance & Resource Management**
+///
+/// This file centralizes all performance-critical constants and policies.
+/// The core philosophy: **Zero Token Leakage, Maximum Efficiency**
+enum PerformanceConstants {
+    // MARK: - Animation Frame Rates
+    
+    /// Menubar icon animation (smooth on modern Macs)
+    static let menubarFPS: Double = 60
+    
+    /// Popover menu animations (full detail when user is actively viewing)
+    static let popoverFPS: Double = 60
+    
+    /// Status pulse effect (minimal overhead for subtle feedback)
+    static let statusPulseFPS: Double = 15
+    
+    // MARK: - Data Fetching Policy
+    
+    /// **Zero Token Leakage**: Maximum pings per session
+    /// - Single ping on menu open
+    /// - Additional pings only if truly stale (>5min old)
+    /// - Use cookies/cached data first
+    static let maxPingsPerSession = 1
+    
+    /// Time before data considered stale (use cookies/cache until then)
+    static let staleDuration: TimeInterval = 300 // 5 minutes
+    
+    /// Delay before first ping after menu opens
+    static let menuOpenPingDelay: Duration = .seconds(1.2)
+    
+    // MARK: - Caching
+    
+    /// Icon render cache size (prevent redundant GPU work)
+    static let iconCacheSize = 64
+    
+    /// Morph animation cache size
+    static let morphCacheSize = 512
+    
+    // MARK: - Resource Limits
+    
+    /// Maximum concurrent provider fetches (prevent API spam)
+    static let maxConcurrentFetches = 2
+    
+    /// Network timeout for single ping
+    static let networkTimeout: TimeInterval = 10
+    
+    // MARK: - Animation Lifecycle
+    
+    /// Animation stops when:
+    /// - Data successfully loaded
+    /// - Error state reached (stale flag set)
+    /// - User manually cancels
+    /// - App enters background
+    
+    /// Blink animation duration (slower "breath" to avoid flicker)
+    static let blinkDuration: TimeInterval = 0.8
+    
+    /// Chance of double-blink effect
+    static let doubleBlinkChance: Double = 0.05
+    
+    // MARK: - Memory Management
+    
+    /// Auto-cleanup idle resources after this duration
+    static let idleCleanupDelay: TimeInterval = 60
+}
+
+// MARK: - Performance Annotations
+
+/// Marks methods that are performance-critical and should not be modified
+/// without thorough profiling and testing
+@propertyWrapper
+struct PerformanceCritical<T> {
+    private var value: T
+    
+    init(wrappedValue: T) {
+        self.value = wrappedValue
+    }
+    
+    var wrappedValue: T {
+        get { value }
+        set { value = newValue }
+    }
+}