feat: add macOS WidgetKit widget extension

[stolot0mt0m]

Summary

This PR adds a native macOS WidgetKit widget extension that displays Claude usage data with Apple-style circular progress rings.

Features

• Small Widget: Shows 5-hour limit with percentage and reset time
• Medium Widget: Shows up to 3 usage rings (5h, 7d, Sonnet) with percentages and reset times
• Apple-style Design: Circular progress rings with text labels in center
• Dark/Light Theme Support: Adaptive background and colors for both themes
• Color-coded Progress: Matches main app's color scheme
• Auto-refresh: Widget updates every 15 minutes

Widget Display

Limit Type	Center Label	Color Scheme
5-Hour	5h	Green → Orange → Red
7-Day	7d	Light Purple → Deep Purple → Magenta
Sonnet	S	Light Blue → Blue → Indigo

Technical Details

New Files

• Usage4ClaudeWidget/ - Widget extension target
  • Usage4ClaudeWidget.swift - Main widget with TimelineProvider and views
  • Usage4ClaudeWidgetBundle.swift - Widget bundle entry point
  • Usage4ClaudeWidget.entitlements - Widget entitlements (App Group)
  • SharedUsageData.swift - Widget-only data model

Data Sharing

• Uses App Groups (group.xyz.fi5h.Usage4Claude) via UserDefaults(suiteName:) for sandbox-safe data sharing between app and widget
• Main app writes data on refresh, widget reads on timeline update

Modified Files

• Usage4Claude/Shared/SharedUsageData.swift - Shared data model with App Group storage
• Usage4Claude/Usage4Claude.entitlements - Added App Group entitlement
• Usage4Claude/Helpers/DataRefreshManager.swift - Widget sync on data refresh
• project.pbxproj - Added Widget extension target (Xcode-style UUIDs)

Signing & Sandbox

• Main app signing config unchanged (Manual, Usage4Claude-CodeSigning, sandbox enabled)
• Widget extension uses same signing style
• Both targets have ENABLE_APP_SANDBOX = YES

Deployment Target

• Both main app and widget target macOS 14.0 (WidgetKit requires macOS 14.0+)
• Note: This is a bump from the previous 13.0 — required for WidgetKit APIs

Test Plan

• Build and run main app
• Verify widget appears in widget gallery (requires signing)
• Add Small widget to desktop - shows 5h ring with % and reset time
• Add Medium widget to desktop - shows 3 rings with % and reset times
• Verify data syncs from main app to widget via App Group
• Verify colors match main app's color scheme
• Test Dark and Light theme appearance
• Verify widget refreshes automatically

[stolot0mt0m]

Hey @f-is-h! 👋

I've rebased this PR on the latest main so it's conflict-free and ready for review.

I think a native macOS widget would be a great addition to Usage4Claude — here's why:

• At-a-glance monitoring — Users can see their current usage without opening the app or clicking the menu bar icon. The circular progress rings make it instantly clear where they stand.
• Proactive awareness — With the widget sitting on the desktop or in Notification Center, users are less likely to hit rate limits unexpectedly. They can plan their Claude usage throughout the day.
• Reset time visibility — Showing when limits reset helps users decide whether to wait or keep going, especially when they're close to the cap.
• Native feel — WidgetKit integrates seamlessly with macOS, supporting both light and dark mode. It feels like a natural extension of the app rather than an afterthought.

Would love to hear your thoughts — happy to make adjustments if needed!

[f-is-h]

Hi, thanks for putting this together! The widget concept is great and I'd love to have it in the app.

A few things that need to be addressed before merging:

1. The pbxproj IDs (WIDGET001, WIDGETTARGET, etc.) are hand-written rather than Xcode-generated UUIDs. This will likely cause build issues. Could you add the widget target through Xcode directly so it generates proper IDs?

2. Please don't change the main app's signing config (CODE_SIGN_STYLE, CODE_SIGN_IDENTITY) or sandbox settings (ENABLE_APP_SANDBOX). Those should stay as they are.

3. For data sharing between the app and widget, App Groups would be the proper approach instead of writing to ~/.Usage4Claude/. File-based sharing works without sandbox, but turning off sandbox is a step backwards for security.

4. The widget's MACOSX_DEPLOYMENT_TARGET is 14.0 while the main app targets 13.0. These should be consistent.

Let me know if you have any questions!

[stolot0mt0m]

Hi @f-is-h, thanks for the detailed review! I've addressed all your feedback:

1. pbxproj IDs — Replaced all hand-written IDs (WIDGET001, WIDGETTARGET, etc.) with proper 24-character hex UUIDs.

2. Main app signing config — Restored CODE_SIGN_STYLE = Manual, CODE_SIGN_IDENTITY = "Usage4Claude-CodeSigning", and ENABLE_APP_SANDBOX = YES. Only added CODE_SIGN_ENTITLEMENTS for the App Group entitlement, everything else is untouched.

3. App Groups for data sharing — Switched from file-based storage (~/.Usage4Claude/) to UserDefaults(suiteName: "group.xyz.fi5h.Usage4Claude"). Sandbox stays enabled for both targets. Added the com.apple.security.application-groups entitlement to both the main app and widget.

4. Deployment target — One thing to flag: WidgetKit on macOS requires a minimum deployment target of macOS 14.0 (Sonoma). Setting it to 13.0 would cause build errors since WidgetKit APIs aren't available on macOS 13. I've set both targets to 14.0 to keep them consistent. If you'd prefer to keep the main app at 13.0, we could conditionally compile the widget sync code, but the widget extension target itself would still need 14.0+. Let me know how you'd like to handle this!

Also rebased on the latest main to pick up the recent fixes.

[stolot0mt0m]

Hi @f-is-h, just rebased on the latest main — conflicts are resolved and the PR is mergeable again. Did you get a chance to take another look? No rush, just wanted to check in. Thanks!