@sriinnu/runic 1.2.0 → 2.11.1

package/docs/minimax.md

@@ -1,71 +0,0 @@
----
-summary: "MiniMax web-only usage fetcher (cookies + local storage token)."
-read_when:
-  - Working on MiniMax provider fetch/parsing
-  - Debugging MiniMax session/cookie handling
----
-
-# MiniMax
-
-MiniMax is web-only. Usage is fetched from the Coding Plan remains API using a session cookie header.
-
-Status: none yet.
-
-## Data sources + fallback order
-1) Browser cookie import (automatic).
-2) Chromium local storage access token (automatic).
-3) Manual session cookie header (optional override).
-
-### Browser cookie import (automatic)
-- Cookie order from provider metadata (default: Safari → Chrome → Firefox).
-- Merges Chromium profile cookies across primary + Network stores before attempting a request.
-- Tries each browser source until the Coding Plan API accepts the cookies.
-- Domain filters: `platform.minimax.io`, `minimax.io`.
-
-### Browser local storage access token (Chromium-based)
-- Reads `access_token` (and related tokens) from Chromium local storage (LevelDB).
-- If decoding fails, falls back to a text-entry scan for `minimax.io` keys/values and filters for MiniMax JWT claims.
-- Used automatically; no UI field.
-- Also extracts `GroupId` when present (appends query param).
-
-### Manual session cookie header (optional override)
-- Stored in Keychain via Preferences → Providers → MiniMax (Cookie header).
-- Accepts a raw `Cookie:` header or a full "Copy as cURL" string.
-- When a cURL string is pasted, MiniMax extracts:
-  - `Cookie:` header
-  - `Authorization: Bearer ...`
-  - `GroupId=...` query param when present
-- CLI/runtime env: `MINIMAX_COOKIE` or `MINIMAX_COOKIE_HEADER`.
-
-## Endpoints
-- `GET https://platform.minimax.io/user-center/payment/coding-plan`
-  - HTML parse for "Available usage" and plan name.
-- `GET https://platform.minimax.io/v1/api/openplatform/coding_plan/remains`
-  - Fallback when HTML parsing fails.
-  - Sent with `Referer` to the Coding Plan page.
-  - Adds `Authorization: Bearer <access_token>` when available.
-  - Adds `GroupId` query param when known.
-
-## Cookie capture (optional override)
-1) Open the Coding Plan page.
-2) DevTools → Network.
-3) Select the request to `/v1/api/openplatform/coding_plan/remains`.
-4) Copy the Cookie request header (or use "Copy as cURL" and paste the whole line).
-5) Paste into Preferences → Providers → MiniMax only if automatic import fails.
-
-## Notes
-- Cookies alone often return status `1004` ("cookie is missing, log in again"); the remains API expects a Bearer token.
-- MiniMax stores `access_token` in Chromium local storage (LevelDB). Some entries serialize the storage key without a scheme (ex: `minimax.io`), so origin matching must account for host-only keys.
-- Raw JWT scan fallback remains as a safety net if Chromium key formats change.
-- If local storage keys don’t decode (some Chrome builds), the MiniMax-specific text scan avoids a full raw-byte scan.
-
-## Cookie file paths
-- Safari: `~/Library/Cookies/Cookies.binarycookies`
-- Chrome/Chromium forks: `~/Library/Application Support/Google/Chrome/*/Cookies`
-- Firefox: `~/Library/Application Support/Firefox/Profiles/*/cookies.sqlite`
-
-## Snapshot mapping
-- Primary: percent used from `model_remains` (used/total) or HTML "Available usage".
-- Window: derived from `start_time`/`end_time` or HTML duration text.
-- Reset: derived from `remains_time` (fallback to `end_time`) or HTML "Resets in ...".
-- Plan/tier: best-effort from response fields or HTML title.

package/docs/packaging.md

@@ -1,25 +0,0 @@
----
-summary: "Packaging, signing, and bundled CLI notes."
-read_when:
-  - Packaging/signing builds
-  - Updating bundle layout or CLI bundling
----
-
-# Packaging & signing
-
-## Scripts
-- `Scripts/package_app.sh`: builds host arch by default; set `ARCHES="arm64 x86_64"` for universal. Verifies slices.
-- `Scripts/compile_and_run.sh`: uses host arch; pass `--release-universal` or `--release-arches="arm64 x86_64"` for release packaging.
-- `Scripts/sign-and-notarize.sh`: signs, notarizes, staples, zips (accepts `ARCHES` for universal).
-- `Scripts/make_appcast.sh`: generates Sparkle appcast and embeds HTML release notes.
-- `Scripts/changelog-to-html.sh`: converts the per-version changelog section to HTML for Sparkle.
-
-## Bundle contents
-- `RunicWidget.appex` bundled with app-group entitlements.
-- `RunicCLI` copied to `Runic.app/Contents/Helpers/` for symlinking.
-- SwiftPM resource bundles (e.g. `KeyboardShortcuts_KeyboardShortcuts.bundle`) copied into `Contents/Resources` (required for `KeyboardShortcuts.Recorder`).
-
-## Releases
-- Full checklist in `docs/RELEASING.md`.
-
-See also: `docs/sparkle.md`.

package/docs/progress-bar-improvements.md

@@ -1,240 +0,0 @@
-# Progress Bar Design Improvements
-
-## Overview
-
-The `UsageProgressBar` component has been completely redesigned with modern visual effects and enhanced functionality.
-
-## Key Improvements
-
-### 1. Enhanced Gradient Effect
-- **Before**: Simple 2-color gradient (top to bottom)
-- **After**: 3-color gradient with depth, creating a more dimensional appearance
-- The new gradient uses `[0.98, 0.85, 0.92]` opacity levels for a subtle wave effect
-
-```swift
-// Before
-LinearGradient(
-    colors: [
-        base.opacity(0.95),
-        base.opacity(0.75),
-    ],
-    startPoint: .top,
-    endPoint: .bottom)
-
-// After
-LinearGradient(
-    colors: [
-        base.opacity(0.98),
-        base.opacity(0.85),
-        base.opacity(0.92),
-    ],
-    startPoint: .top,
-    endPoint: .bottom)
-```
-
-### 2. Glow Effect
-Added a subtle shadow that creates a soft glow around the filled portion:
-- Radius: 40% of bar height (adaptive to size)
-- Color: Matches the tint color at 30% opacity
-- Automatically disabled when highlighted (menu selection state)
-
-```swift
-.shadow(
-    color: tintColor.opacity(self.isHighlighted ? 0 : 0.3),
-    radius: self.barHeight * 0.4,
-    x: 0,
-    y: 0)
-```
-
-### 3. Glossy Top Highlight
-Added a subtle white highlight overlay on the top half for a glossy, polished look:
-
-```swift
-.overlay {
-    Capsule()
-        .fill(
-            LinearGradient(
-                colors: [
-                    Color.white.opacity(0.2),
-                    Color.clear,
-                ],
-                startPoint: .top,
-                endPoint: .center))
-        .frame(width: max(fillWidth, self.barHeight))
-}
-```
-
-### 4. Enhanced Track Styling
-The background track now has a subtle border for better definition:
-
-```swift
-Capsule()
-    .fill(trackColor)
-    .overlay {
-        Capsule()
-            .strokeBorder(
-                trackColor.opacity(0.3),
-                lineWidth: 0.5)
-    }
-```
-
-### 5. Spring-Based Animation
-Replaced linear easing with natural spring physics:
-
-```swift
-// Before
-withAnimation(.easeOut(duration: 0.35)) {
-    self.animatedPercent = newValue
-}
-
-// After
-withAnimation(.spring(response: 0.5, dampingFraction: 0.8)) {
-    self.animatedPercent = newValue
-}
-```
-
-**Benefits:**
-- More natural, organic movement
-- Subtle bounce adds personality
-- Better matches macOS system animations
-
-### 6. Height Options
-Added three size variants for different contexts:
-
-```swift
-enum Height {
-    case compact    // 6pt - dense layouts, team rows
-    case regular    // 8pt - default, menu cards
-    case large      // 10pt - prominent displays
-}
-```
-
-**Usage Examples:**
-
-```swift
-// Compact - for team member rows
-UsageProgressBar(
-    percent: 75,
-    tint: .blue,
-    accessibilityLabel: "Quota usage",
-    height: .compact)
-
-// Regular - default, most menu cards (parameter optional)
-UsageProgressBar(
-    percent: 60,
-    tint: .green,
-    accessibilityLabel: "API usage")
-
-// Large - for dashboard hero sections
-UsageProgressBar(
-    percent: 85,
-    tint: .orange,
-    accessibilityLabel: "Team usage",
-    height: .large)
-```
-
-### 7. Enhanced Accessibility
-Improved VoiceOver support:
-
-```swift
-.accessibilityElement(children: .ignore)
-.accessibilityLabel(self.accessibilityLabel)
-.accessibilityValue("\(Int(self.clamped)) percent")
-.accessibilityAddTraits(.updatesFrequently)
-```
-
-**Improvements:**
-- Marks element as frequently updating for better screen reader experience
-- Ignores child elements to prevent confusion
-- Clear percentage value announcement
-
-## Implementation Locations
-
-### Files Updated
-
-1. **`/Sources/Runic/UsageProgressBar.swift`**
-   - Core component with all visual improvements
-   - Added height enum and gradient enhancements
-
-2. **`/Sources/Runic/Views/Team/TeamMemberRow.swift`**
-   - Updated to use `.compact` height for dense layout
-
-3. **`/Sources/Runic/Views/Team/TeamDashboardView.swift`**
-   - Updated to use `.large` height for prominent display
-
-4. **`/Sources/Runic/Views/Team/TeamManagementView.swift`**
-   - Updated to use `.regular` height explicitly
-
-### Usage Across Codebase
-
-The progress bar is used in these contexts:
-
-| Location | Purpose | Height |
-|----------|---------|--------|
-| `MenuCardView.swift` | Provider usage metrics | Regular (default) |
-| `ProjectBudgetMenuView.swift` | Budget tracking | Regular (default) |
-| `TeamMemberRow.swift` | Member quota in list | Compact |
-| `TeamDashboardView.swift` | Team overview hero | Large |
-| `TeamManagementView.swift` | Team quota summary | Regular |
-
-## Visual Comparison
-
-### Before
-- Flat gradient (2 colors)
-- No glow or shadow
-- Simple easeOut animation
-- Fixed 8pt height
-- Basic track background
-
-### After
-- Rich 3-color gradient with depth
-- Subtle glow effect (shadow radius: 3.2pt @ 8pt height)
-- Glossy top highlight overlay
-- Spring physics animation (response: 0.5s, damping: 0.8)
-- Three height options (6pt, 8pt, 10pt)
-- Enhanced track with subtle border
-- Improved accessibility traits
-
-## Performance Considerations
-
-All visual effects use:
-- `drawingGroup()` for GPU acceleration
-- Efficient SwiftUI modifiers
-- No runtime calculations in body
-- Smooth 60fps animations
-
-## Design Principles
-
-1. **Subtle but Refined**: Effects are noticeable but not distracting
-2. **Context-Aware**: Adapts to menu highlight state automatically
-3. **Accessible**: Full VoiceOver support with proper traits
-4. **Consistent**: Uses MenuHighlightStyle for color consistency
-5. **Performant**: GPU-accelerated rendering
-6. **Flexible**: Height options for different contexts
-
-## Migration Guide
-
-Existing code continues to work with no changes required. The `height` parameter is optional and defaults to `.regular` (8pt).
-
-**Optional Enhancement:**
-To take advantage of the new height options:
-
-```swift
-// For compact layouts (was .frame(height: 4-6))
-UsageProgressBar(..., height: .compact)
-
-// For default layouts (was .frame(height: 8))
-UsageProgressBar(...) // or height: .regular
-
-// For prominent displays (was .frame(height: 10-12))
-UsageProgressBar(..., height: .large)
-```
-
-## Future Enhancements
-
-Potential future additions:
-- [ ] Animated shimmer effect for loading states
-- [ ] Pulsing animation for critical thresholds
-- [ ] Color transitions when crossing thresholds
-- [ ] Custom height values beyond presets
-- [ ] Striped pattern option for different data types

package/docs/progress-bar-quick-reference.md

@@ -1,283 +0,0 @@
-# UsageProgressBar Quick Reference
-
-## Basic Usage
-
-```swift
-UsageProgressBar(
-    percent: 75,                           // 0-100 (values outside clamped)
-    tint: .blue,                          // Any SwiftUI Color
-    accessibilityLabel: "API usage"       // VoiceOver label
-)
-```
-
-## With Height Option
-
-```swift
-UsageProgressBar(
-    percent: 85,
-    tint: .red,
-    accessibilityLabel: "Quota",
-    height: .compact                       // .compact | .regular | .large
-)
-```
-
-## Height Guide
-
-| Height    | Size | Use When                              | Example Context          |
-|-----------|------|---------------------------------------|--------------------------|
-| `.compact`| 6pt  | Dense layouts, list items             | Team member rows         |
-| `.regular`| 8pt  | Default, standard cards (default)     | Menu cards, budgets      |
-| `.large`  | 10pt | Hero sections, prominent displays     | Dashboard overview       |
-
-## Common Patterns
-
-### API Usage Card
-```swift
-VStack(alignment: .leading, spacing: 4) {
-    Text("API Usage")
-        .font(.body.weight(.medium))
-
-    UsageProgressBar(
-        percent: 61.7,
-        tint: .blue,
-        accessibilityLabel: "API usage")
-
-    Text("61.7% used")
-        .font(.caption)
-}
-```
-
-### Budget Warning
-```swift
-UsageProgressBar(
-    percent: 90,
-    tint: percentUsed >= 90 ? .red : percentUsed >= 75 ? .orange : .blue,
-    accessibilityLabel: "Budget usage")
-```
-
-### Team Member Quota
-```swift
-HStack {
-    Text("8,500 / 10,000")
-        .font(.caption2)
-
-    UsageProgressBar(
-        percent: 85,
-        tint: .red,
-        accessibilityLabel: "John Doe quota",
-        height: .compact)
-        .frame(maxWidth: 120)
-}
-```
-
-## Color Recommendations
-
-| Percentage Range | Suggested Color | Meaning       |
-|------------------|-----------------|---------------|
-| 0-50%            | `.green`        | Safe          |
-| 50-75%           | `.blue`         | Normal        |
-| 75-90%           | `.orange`       | Warning       |
-| 90-100%          | `.red`          | Critical      |
-
-## Visual Features
-
-✅ **Gradient fill** - 3-color depth effect
-✅ **Glow/shadow** - Subtle ambient shadow (3.2pt @ regular)
-✅ **Glossy highlight** - White gradient on top half
-✅ **Track border** - 0.5pt definition stroke
-✅ **Spring animation** - Natural bounce (0.5s response, 0.8 damping)
-✅ **Menu aware** - Adapts to highlight state automatically
-
-## Accessibility
-
-```swift
-// VoiceOver announcement:
-"[Label], [Percentage] percent, updates frequently"
-
-// Example:
-"API usage, 75 percent, updates frequently"
-```
-
-## Migration from Old Code
-
-### Before
-```swift
-UsageProgressBar(percent: 75, tint: .blue, accessibilityLabel: "Usage")
-    .frame(height: 6)  // ← Remove this
-```
-
-### After
-```swift
-UsageProgressBar(
-    percent: 75,
-    tint: .blue,
-    accessibilityLabel: "Usage",
-    height: .compact)  // ← Use semantic height
-```
-
-## State Adaptation
-
-The progress bar automatically adapts to menu highlight state:
-
-| State       | Track Color            | Tint Color              | Glow      |
-|-------------|------------------------|-------------------------|-----------|
-| Normal      | Tertiary label (22%)   | Provided color          | Visible   |
-| Highlighted | Selection text (22%)   | Selection text (white)  | Hidden    |
-
-## Animation Behavior
-
-```swift
-// On appear: Spring animation to current value
-.onAppear {
-    withAnimation(.spring(response: 0.6, dampingFraction: 0.75)) {
-        animatedPercent = percent
-    }
-}
-
-// On change: Spring animation to new value
-.onChange(of: percent) {
-    withAnimation(.spring(response: 0.5, dampingFraction: 0.8)) {
-        animatedPercent = newValue
-    }
-}
-```
-
-## Performance Notes
-
-- **GPU accelerated** via `drawingGroup()`
-- **60fps animations** on all devices
-- **Minimal memory** (~324 bytes per instance)
-- **No layout thrashing** - efficient rendering
-
-## Common Mistakes to Avoid
-
-❌ Don't manually set `.frame(height:)` anymore
-```swift
-UsageProgressBar(...).frame(height: 8)  // Old way
-```
-
-✅ Use semantic height parameter
-```swift
-UsageProgressBar(..., height: .regular)  // New way
-```
-
-❌ Don't pass percentages outside 0-100
-```swift
-UsageProgressBar(percent: 150, ...)  // Will be clamped to 100
-```
-
-✅ Clamp before passing
-```swift
-UsageProgressBar(percent: min(100, max(0, value)), ...)
-```
-
-❌ Don't use generic accessibility labels
-```swift
-accessibilityLabel: "Progress"  // Too vague
-```
-
-✅ Use descriptive labels
-```swift
-accessibilityLabel: "API usage"  // Specific and clear
-```
-
-## Troubleshooting
-
-### Bar not visible
-- Check percent is > 0
-- Verify tint color is not clear
-- Ensure parent has non-zero width
-
-### Animation not smooth
-- Verify not overriding with explicit `.animation()`
-- Check for layout thrashing (multiple updates per frame)
-- Ensure running on main thread
-
-### Wrong height
-- Don't use both `height` parameter AND `.frame(height:)`
-- Use semantic height: `.compact`, `.regular`, or `.large`
-- Default is `.regular` (8pt) if not specified
-
-### VoiceOver not working
-- Ensure `accessibilityLabel` is provided
-- Check label is descriptive (not empty)
-- Verify value is between 0-100
-
-## Complete Example
-
-```swift
-// Full-featured usage card
-VStack(alignment: .leading, spacing: 8) {
-    // Header
-    HStack {
-        Text("API Usage")
-            .font(.body.weight(.medium))
-        Spacer()
-        Text("1,234 / 2,000")
-            .font(.caption)
-            .foregroundStyle(.secondary)
-    }
-
-    // Progress bar
-    UsageProgressBar(
-        percent: 61.7,
-        tint: .blue,
-        accessibilityLabel: "API usage",
-        height: .regular)
-
-    // Footer
-    HStack {
-        Text("61.7% used")
-            .font(.caption)
-        Spacer()
-        Text("Resets in 12 days")
-            .font(.caption)
-            .foregroundStyle(.secondary)
-    }
-}
-.padding()
-.background(
-    RoundedRectangle(cornerRadius: 8)
-        .fill(Color(nsColor: .controlBackgroundColor)))
-```
-
-## API Summary
-
-```swift
-struct UsageProgressBar: View {
-    enum Height {
-        case compact    // 6pt
-        case regular    // 8pt (default)
-        case large      // 10pt
-    }
-
-    init(
-        percent: Double,              // Required: 0-100
-        tint: Color,                  // Required: Any SwiftUI Color
-        accessibilityLabel: String,   // Required: VoiceOver label
-        height: Height = .regular     // Optional: Size variant
-    )
-}
-```
-
-## Related Files
-
-- **Component**: `/Sources/Runic/UsageProgressBar.swift`
-- **Styles**: `/Sources/Runic/Views/Menu/MenuHighlightStyle.swift`
-- **Documentation**: `/docs/progress-bar-improvements.md`
-- **Technical**: `/docs/progress-bar-technical-details.md`
-- **Visual Tests**: `/docs/progress-bar-visual-test.swift`
-
-## Support
-
-For issues or questions:
-1. Check this quick reference first
-2. Review technical details documentation
-3. Run visual test file to compare behavior
-4. Verify accessibility with VoiceOver
-
----
-
-**Last Updated**: January 2026
-**Version**: 2.0 (Modern redesign)
-**Compatibility**: macOS 12+, SwiftUI 3+