From 471fb6723edd409d1f8593a917a757e88f7cf3fa Mon Sep 17 00:00:00 2001 From: Hariharan Mudaliar Date: Fri, 1 Aug 2025 23:08:40 +0530 Subject: [PATCH] Update README --- ReadMe.md | 477 ++++++++++++++++++++++++++++++++++++++++++++---------- logic.md | 41 ++++- 2 files changed, 433 insertions(+), 85 deletions(-) diff --git a/ReadMe.md b/ReadMe.md index 6fd8b06..61777de 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -4,52 +4,93 @@ DynamicIsland Logo

-> **DynamicIsland** enhances the notch on your MacBook M3 Pro with interactive, customizable widgets, transforming it into a dynamic control center for multitasking, notifications, and more. +> **DynamicIsland** transforms your MacBook's notch into a powerful, interactive control center with advanced system monitoring, music controls, timers, and customizable widgets. Experience smooth animations and intelligent vertical expansion for enhanced productivity. -## Preview +## 🎬 Preview ![DynamicIsland Preview](https://github.com/Ebullioscopic/DynamicIsland/blob/main/dynamic-island-preview.jpeg) -## Demonstration +## 🚀 Demonstration ![DynamicIsland Demo](https://github.com/Ebullioscopic/DynamicIsland/blob/main/dynamic-island-demo.gif)
📑 Table of Contents -- [Features](#features) -- [Demo](#demo) -- [Getting Started](#getting-started) +- [✨ Features](#-features) +- [🆕 What's New](#-whats-new) +- [🎥 Demo](#-demo) +- [🚀 Getting Started](#-getting-started) - [Prerequisites](#prerequisites) - [Installation](#installation) -- [Usage](#usage) +- [📖 Usage](#-usage) - [Basic Controls](#basic-controls) + - [System Monitoring](#system-monitoring) - [Customization Options](#customization-options) -- [Configuration](#configuration) -- [Roadmap](#roadmap) -- [Troubleshooting](#troubleshooting) -- [Contributing](#contributing) -- [License](#license) -- [Acknowledgments](#acknowledgments) -- [Contributors](#contributors) +- [⚙️ Configuration](#️-configuration) +- [🚧 Roadmap](#-roadmap) +- [🔧 Troubleshooting](#-troubleshooting) +- [🤝 Contributing](#-contributing) +- [📜 License](#-license) +- [🏆 Acknowledgments](#-acknowledgments) +- [👥 Contributors](#-contributors)
--- -## 🌟 Features +## ✨ Features -- **Music Controls**: Play, pause, and skip tracks from the notch area. -- **Battery Status**: Real-time battery percentage and low-battery alerts. -- **Calendar Reminders**: Displays upcoming events directly in the notch. -- **Weather Updates**: Get current weather conditions at a glance. -- **Multitasking Tools**: Quickly switch between open applications. -- **Customizable Themes**: Light, dark, and custom color themes. -- **Gesture Support**: Use gestures for quick actions. +### 🎵 **Music & Media Controls** +- **Live Music Activity**: Real-time album art, track info, and playback controls +- **Audio Visualizer**: Dynamic spectrum visualization with color adaptation +- **Multi-Platform Support**: Works with Apple Music, Spotify, YouTube Music, and more +- **Smooth Transitions**: Elegant animations between tracks and states + +### 📊 **Advanced System Monitoring** +- **Real-Time Performance Stats**: CPU, Memory, GPU usage with live graphs +- **Network Activity**: Upload/download monitoring with dual-quadrant visualization +- **Disk I/O Tracking**: Read/write speeds with real-time data +- **Intelligent Layout**: Vertical expansion for 4+ graphs with optimized spacing +- **Customizable Visibility**: Toggle individual graphs on/off +- **Smooth Animations**: Debounced updates prevent conflicts and ensure fluid transitions + +### ⏱️ **Timer & Productivity** +- **Multiple Timers**: Create and manage multiple named timers +- **Live Activities**: Background timer monitoring with notifications +- **Custom Colors**: Personalize timer appearance +- **Quick Access**: Direct timer controls from the notch + +### 🔋 **Battery & System Status** +- **Intelligent Battery Alerts**: Smart notifications for charging states +- **Power Management**: Low battery warnings and charging status +- **System Integration**: Native macOS battery monitoring + +### 🎨 **Modern UI & Animations** +- **Smooth Transitions**: Professionally animated state changes +- **Hover Effects**: Interactive feedback with haptic support +- **Gesture Controls**: Swipe to open/close, tap interactions +- **Adaptive Sizing**: Dynamic height expansion for complex content +- **Perfect Alignment**: Maintains center positioning across all states + +## 🆕 What's New + +### **Enhanced Stats Feature** +- ✅ **Vertical Expansion Layout**: No more horizontal stretching - stats expand downward naturally +- ✅ **5-Graph Support**: CPU, Memory, GPU, Network, and Disk monitoring +- ✅ **Dual-Quadrant Graphs**: Network and disk stats show upload/download or read/write in split views +- ✅ **Smart Layout System**: 1-3 graphs in single row, 4 graphs in 2×2 grid, 5 graphs in 3+2 layout +- ✅ **Smooth Animations**: Debounced updates eliminate jarring transitions +- ✅ **Individual Controls**: Toggle each graph type independently +- ✅ **Perfect Centering**: Maintains alignment across all display configurations ## 🎥 Demo -Check out a quick demo of DynamicIsland in action: +Experience **DynamicIsland** in action with our comprehensive demo showcasing: +- **Smooth vertical expansion** for system stats +- **Real-time performance monitoring** with live graphs +- **Seamless music integration** with album art and controls +- **Intelligent layout transitions** between different content types ![DynamicIsland Demo](https://github.com/Ebullioscopic/DynamicIsland/raw/main/demo.gif) @@ -57,14 +98,15 @@ Check out a quick demo of DynamicIsland in action: ## 🚀 Getting Started -These instructions will get you a copy of **DynamicIsland** up and running on your local machine. +Get **DynamicIsland** running on your macOS system with these simple steps. ### Prerequisites -- **macOS Ventura 14.2** or later. -- **Xcode 15.0** or later. -- **SwiftUI** and **Objective-C** frameworks installed. -- **Make** installed for build automation. +- **macOS Sonoma 14.0** or later (optimized for macOS Sequoia 15.0+) +- **MacBook with Notch** (MacBook Pro 14"/16" M1 Pro/Max/M2/M3 series) +- **Xcode 15.0** or later +- **Swift 5.9** or later +- **Admin privileges** for system monitoring features ### Installation @@ -74,21 +116,62 @@ These instructions will get you a copy of **DynamicIsland** up and running on yo cd DynamicIsland ``` -2. **Install Dependencies** - Make sure you have all required libraries and frameworks installed. Use Homebrew for some dependencies if needed: - ```bash - brew install make - ``` - -3. **Build and Run the Project** - Open the project in Xcode, select your target device, and run: +2. **Open in Xcode** ```bash open DynamicIsland.xcodeproj ``` -4. **Run the App in Xcode** - Build and run the app from Xcode by pressing `Cmd + R`: - - If prompted by macOS, allow permissions for **Privacy & Security**. +3. **Configure Permissions** + - Enable **Accessibility** permissions in System Settings + - Allow **Screen Recording** for proper notch integration + - Grant **Full Disk Access** for system monitoring features + +4. **Build and Run** + - Select your Mac as the target device + - Press `Cmd + R` to build and run + - The app will appear in your menu bar and activate the notch + +--- + +## 📖 Usage + +**DynamicIsland** provides an intuitive interface that adapts to your workflow needs. + +### Basic Controls + +- **Hover to Activate**: Move your cursor near the notch to expand the interface +- **Click to Open**: Tap the notch area to access full controls +- **Gesture Support**: Swipe down to expand, swipe up to close +- **Tab Navigation**: Switch between Home, Shelf, Timer, and Stats tabs + +### System Monitoring + +#### **Stats Tab Features** +- **CPU Usage**: Real-time processor utilization with historical graph +- **Memory Stats**: RAM usage tracking with pressure indicators +- **GPU Monitoring**: Graphics processor load for intensive tasks +- **Network Activity**: Live upload/download speeds with dual visualization +- **Disk I/O**: Read/write operations monitoring for storage performance + +#### **Layout Intelligence** +- **1-3 Graphs**: Single row layout for minimal overhead +- **4 Graphs**: 2×2 quadrant arrangement for balanced viewing +- **5 Graphs**: 3+2 optimized layout with centered bottom row +- **Smooth Transitions**: Animated layout changes with perfect centering + +### Customization Options + +#### **Stats Configuration** +1. Navigate to **Settings → Stats** +2. **Enable/Disable Graphs**: Toggle individual monitoring features +3. **Update Frequency**: Adjust refresh rates for performance optimization +4. **Visual Preferences**: Customize colors and graph styles + +#### **General Settings** +1. **Appearance**: Choose system theme or custom colors +2. **Behavior**: Configure hover sensitivity and auto-close timing +3. **Gestures**: Enable/disable swipe controls and haptic feedback +4. **Display**: Multi-monitor support and positioning options --- @@ -116,66 +199,208 @@ To personalize your DynamicIsland experience: ## ⚙️ Configuration -Configuration settings can be found in the `config.json` file located in the root directory. +**DynamicIsland** offers extensive customization through its intuitive settings interface. -### `config.json` Example +### Settings Categories -```json -{ - "theme": "dark", - "batteryWidget": true, - "musicWidget": true, - "weatherWidget": true, - "gestureSettings": { - "tap": "toggleMusic", - "swipeLeft": "previousApp", - "swipeRight": "nextApp", - "longPress": "openSettings" - } -} +#### **📊 Stats Configuration** +```swift +// Enable/disable individual monitoring features +CPU Monitoring: ✅ Enabled +Memory Tracking: ✅ Enabled +GPU Monitoring: ✅ Enabled +Network Activity: ✅ Enabled +Disk I/O Monitoring: ✅ Enabled ``` -- **`theme`**: Options are `"light"`, `"dark"`, or `"auto"`. -- **`batteryWidget`, `musicWidget`, `weatherWidget`**: Toggle visibility for each widget. -- **`gestureSettings`**: Assign actions to tap, swipe, and long-press gestures. +#### **🎵 Music & Media** +- **Visualizer Type**: Spectrum analyzer or Lottie animations +- **Color Adaptation**: Dynamic colors based on album art +- **Live Activity**: Background playback monitoring +- **Media Sources**: Apple Music, Spotify, YouTube Music support + +#### **⏱️ Timer & Productivity** +- **Default Timer Duration**: Customizable presets +- **Notification Style**: Banner, alert, or silent +- **Timer Colors**: Personal color schemes +- **Auto-start Options**: Quick timer creation + +#### **🎨 Appearance & Behavior** +- **Theme**: System, light, dark, or custom +- **Hover Sensitivity**: Adjust activation distance +- **Animation Speed**: Control transition timing +- **Corner Radius**: Customize notch appearance +- **Shadow Effects**: Enable/disable depth effects + +### Advanced Settings + +#### **🖥️ Multi-Display Support** +- **Primary Display**: Choose main monitor for the notch +- **Show on All Displays**: Extend to multiple screens +- **Display Switching**: Automatic adaptation to external monitors + +#### **⌨️ Keyboard Shortcuts** +- **Toggle DynamicIsland**: `⌘ + ⌥ + D` +- **Open Settings**: `⌘ + ,` +- **Quick Stats**: `⌘ + ⌥ + S` +- **Timer Control**: `⌘ + ⌥ + T` --- ## 🚧 Roadmap -Planned updates for future releases: +Exciting features planned for upcoming releases: -- [ ] **Advanced Calendar Integration**: Add support for weekly and monthly views. -- [ ] **Customizable Shortcuts**: Create custom app shortcuts. -- [ ] **Additional Widget Support**: Add widgets for finance, fitness, and more. -- [ ] **Voice Commands**: Enable Siri shortcuts for quick commands. -- [ ] **Animation Improvements**: Smooth animations for a more polished UI. +### **🔄 Version 2.1 (Next Release)** +- [ ] **Enhanced Calendar Integration**: Weekly/monthly views with event details +- [ ] **Weather Widget**: Location-based forecasts with beautiful animations +- [ ] **Custom Shortcuts**: User-defined quick actions and app launchers +- [ ] **Performance Optimizations**: Reduced memory footprint and battery usage + +### **🚀 Version 2.2 (Future)** +- [ ] **Voice Commands**: Siri integration for hands-free control +- [ ] **Widget Marketplace**: Community-created custom widgets +- [ ] **Advanced Analytics**: Historical performance data and trends +- [ ] **Cloud Sync**: Settings synchronization across devices + +### **🌟 Version 3.0 (Vision)** +- [ ] **AI-Powered Insights**: Intelligent system recommendations +- [ ] **3D Animations**: Enhanced visual effects with depth +- [ ] **Plugin Architecture**: Third-party developer extensions +- [ ] **Cross-Platform**: iPad and iPhone companion apps --- ## 🔧 Troubleshooting -### Common Issues +### Common Issues & Solutions -- **Permissions**: Go to **System Preferences > Security & Privacy** to manually enable permissions if the app fails to start. -- **Widgets Not Displaying**: Ensure your `config.json` file has valid settings, then restart the app. -- **Build Errors in Xcode**: Run `make clean` to reset the project, then re-build. +#### **🚫 Permissions & Access** +**Issue**: DynamicIsland not appearing or functioning properly +**Solutions**: +- Go to **System Settings → Privacy & Security → Accessibility** and enable DynamicIsland +- Enable **Screen Recording** permissions for notch integration +- Grant **Full Disk Access** for system monitoring features +- Restart the app after granting permissions -### Useful Commands +#### **📊 Stats Not Updating** +**Issue**: Performance graphs showing no data or frozen +**Solutions**: +- Check that **Stats Feature** is enabled in Settings +- Verify individual graph toggles are enabled +- Restart the monitoring service: Settings → Stats → Restart Monitoring +- Ensure app has necessary system access permissions -- **Clean Build Files**: - ```bash - make clean - ``` -- **Reset Configurations**: - ```bash - rm config.json && cp config.default.json config.json - ``` +#### **🎵 Music Controls Not Working** +**Issue**: Music widget not responding or showing incorrect information +**Solutions**: +- Verify media app is actively playing (Apple Music, Spotify, etc.) +- Check **Music & Media** permissions in System Settings +- Restart the music application +- Toggle **Live Activity** setting in DynamicIsland preferences + +#### **⚡ Performance Issues** +**Issue**: High CPU usage or slow animations +**Solutions**: +- Reduce stats update frequency: Settings → Stats → Update Interval +- Disable unused monitoring features to reduce overhead +- Close unnecessary background applications +- Restart DynamicIsland if memory usage is high + +### Advanced Troubleshooting + +#### **🔧 Reset to Defaults** +```bash +# Reset all settings to factory defaults +defaults delete com.ebullioscopic.DynamicIsland +``` + +#### **📱 Clean Reinstall** +1. Quit DynamicIsland completely +2. Delete app from Applications folder +3. Remove settings: `~/Library/Preferences/com.ebullioscopic.DynamicIsland.plist` +4. Reinstall from latest build + +#### **🐛 Debug Mode** +Enable detailed logging for troubleshooting: +1. Hold `⌥` while opening Settings +2. Navigate to **Advanced → Debug Mode** +3. Enable **Verbose Logging** +4. Reproduce the issue and check Console.app for detailed logs + +### **💬 Getting Help** +- **GitHub Issues**: Report bugs or request features +- **Discussions**: Community support and tips +- **Documentation**: Detailed guides and API reference --- ## 🤝 Contributing +We welcome contributions from developers, designers, and users alike! + +### **🛠️ For Developers** + +#### **Setting Up Development Environment** +1. **Fork the Repository** +2. **Clone Your Fork**: + ```bash + git clone https://github.com/yourusername/DynamicIsland.git + cd DynamicIsland + ``` +3. **Install Development Dependencies**: + ```bash + # SwiftLint for code formatting + brew install swiftlint + + # SwiftFormat for consistent styling + brew install swiftformat + ``` + +#### **Development Workflow** +1. **Create Feature Branch**: + ```bash + git checkout -b feature/your-feature-name + ``` +2. **Follow Code Standards**: + - Use SwiftUI best practices + - Follow Apple's Human Interface Guidelines + - Add comprehensive comments for complex logic + - Include unit tests for new functionality + +3. **Commit Guidelines**: + ```bash + git commit -m "feat: add network monitoring graphs + + - Implement dual-quadrant visualization + - Add upload/download speed tracking + - Include BSD socket integration + - Update settings UI for new feature" + ``` + +4. **Push and Create PR**: + ```bash + git push origin feature/your-feature-name + ``` + +### **🎨 For Designers** +- **UI/UX Improvements**: Mockups and design suggestions +- **Icon Design**: System icons and app branding +- **Animation Concepts**: Motion design for smooth interactions + +### **📚 For Documentation** +- **User Guides**: Step-by-step tutorials +- **API Documentation**: Technical reference materials +- **Translations**: Localization for international users + +### **Code Review Process** +1. All PRs require review from core maintainers +2. Automated testing must pass (CI/CD pipeline) +3. Code coverage should not decrease significantly +4. Follow semantic versioning for releases + +## 🤝 Contributing + We welcome contributions from the community! Follow the steps below to contribute: 1. **Fork the repository**. @@ -204,22 +429,110 @@ For major changes, please open an issue first to discuss what you’d like to ch ## 📜 License -This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. +This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for complete details. + +### **License Summary** +- ✅ **Commercial Use**: Use in commercial projects +- ✅ **Modification**: Modify and adapt the code +- ✅ **Distribution**: Share and redistribute +- ✅ **Private Use**: Use for personal projects +- ❗ **Attribution Required**: Credit the original authors --- ## 🏆 Acknowledgments -Special thanks to: -- **Apple Design Principles** for inspiration. -- **Boring Notch** project for initial ideas. +**DynamicIsland** exists thanks to the contributions and inspiration from: + +### **🎯 Core Inspiration** +- **Apple's Dynamic Island**: The innovative hardware feature that inspired this software implementation +- **NotchNook & HiDock**: Early notch customization pioneers +- **macOS Design Principles**: Following Apple's human interface guidelines + +### **🛠️ Technical Foundation** +- **SwiftUI Framework**: For modern, reactive user interfaces +- **Combine Framework**: Reactive programming and data flow +- **AVFoundation**: Audio processing and media integration +- **IOKit**: Low-level system monitoring capabilities + +### **🎨 Design & Animation** +- **Lottie by Airbnb**: Beautiful animations and micro-interactions +- **SF Symbols**: Consistent iconography throughout the app +- **Apple Design Resources**: Color palettes and spacing guidelines + +### **🌟 Community** +- **Open Source Contributors**: Everyone who submitted code, bug reports, and feature requests +- **Beta Testers**: Early adopters who helped refine the experience +- **Design Feedback**: UI/UX suggestions from the community + +### **📚 Educational Resources** +- **Stanford CS193p**: SwiftUI development techniques +- **Apple WWDC Sessions**: Best practices and new framework features +- **Ray Wenderlich Tutorials**: Advanced iOS/macOS development patterns --- ## 👥 Contributors +Meet the team behind **DynamicIsland**: + - + + -

Ebullioscopic
Creator		 + + Ebullioscopic +
+ Ebullioscopic + +
+ 🚀 Creator & Lead Developer +
+ Core architecture, UI/UX design + 		+ + You! +
+ Your Name Here + +
+ 🤝 Future Contributor +
+ Join the project! +
\ No newline at end of file + + +### **🌟 Special Recognition** + +#### **📊 Stats Feature Development** +- **System Monitoring**: Advanced CPU, Memory, GPU tracking +- **Network Analytics**: Real-time upload/download visualization +- **Vertical Layout System**: Intelligent graph arrangement +- **Performance Optimization**: Debounced updates and smooth animations + +#### **🎵 Music Integration** +- **Multi-Platform Support**: Apple Music, Spotify, YouTube Music +- **Audio Visualization**: Real-time spectrum analysis +- **Live Activities**: Background playback monitoring + +#### **⚡ Performance & Reliability** +- **Memory Management**: Efficient resource utilization +- **Animation System**: Smooth, conflict-free transitions +- **Error Handling**: Robust system with graceful degradation + +--- + +
+ +### **⭐ Star this repository if DynamicIsland enhanced your Mac experience!** + +### **🔗 Connect with the Project** +[![GitHub Stars](https://img.shields.io/github/stars/Ebullioscopic/DynamicIsland?style=social)](https://github.com/Ebullioscopic/DynamicIsland/stargazers) +[![GitHub Forks](https://img.shields.io/github/forks/Ebullioscopic/DynamicIsland?style=social)](https://github.com/Ebullioscopic/DynamicIsland/network/members) +[![GitHub Issues](https://img.shields.io/github/issues/Ebullioscopic/DynamicIsland)](https://github.com/Ebullioscopic/DynamicIsland/issues) +[![GitHub Pull Requests](https://img.shields.io/github/issues-pr/Ebullioscopic/DynamicIsland)](https://github.com/Ebullioscopic/DynamicIsland/pulls) + +**Built with ❤️ for the macOS community** + +
\ No newline at end of file diff --git a/logic.md b/logic.md index fd36d04..5c6977f 100644 --- a/logic.md +++ b/logic.md @@ -80,11 +80,46 @@ This means the content already knows how to size itself. The window can stay at This eliminates the timing issue completely because the window never changes size after initial creation. -## REAL ROOT CAUSE FOUND AND FIXED +## CRITICAL DISCOVERY - Clipboard is NOT a Tab View -### The ACTUAL Problem: Window Creation with Wrong Size +### Major Finding +**The `.clipboard` case doesn't exist in `NotchViews` enum!** -The issue was NOT positioning logic - it was that **`createDynamicIslandWindow()` always created windows with `openNotchSize`** instead of the current required size! +```swift +public enum NotchViews { + case home + case shelf + case timer + case stats +} +``` + +### What This Means +- All my protective logic for `coordinator.currentView == .clipboard` is **ineffective** +- Clipboard functionality works differently - likely as a popover or overlay, not a tab +- The hover collapse issue is NOT about tab transitions but about popover interactions + +### Investigation Results +1. **ContentView switch statement** only handles: `.home`, `.shelf`, `.timer`, `.stats` +2. **No clipboard tab content rendering** in the main view switch +3. **Clipboard must be implemented as popover/overlay** system + +### New Hypothesis +The clipboard "area" the user refers to is likely: +1. **ClipboardHistoryPopover** - a popover that opens over the Dynamic Island +2. **ClipboardManager integration** - clipboard content shown in existing tabs +3. **Overlay system** - clipboard UI overlaid on top of main content + +### Critical Issue Identified +My previous fix added protections for `.clipboard` view that **DOESN'T EXIST**, meaning: +- Protections are not working +- Hover collapse still happening during clipboard interactions +- Need to find actual clipboard interaction boundaries + +### Next Steps +1. **Find real clipboard implementation** - how is clipboard content actually shown? +2. **Identify clipboard hover boundaries** - what UI element represents "clipboard area"? +3. **Fix actual interaction conflicts** - coordinate between clipboard popover and main hover logic #### When This Caused Problems: