Atoll/ReadMe.md

<div align="center">
   <img src="https://github.com/Ebullioscopic/DynamicIsland/blob/main/DynamicIslandSamples/logo.png" alt="DynamicIsland Logo" width="120"/>
</div>

# DynamicIsland

<p align="center">
   <b>Transform your MacBook's notch into a powerful, interactive control center.</b><br>
   <i>Advanced system monitoring, music controls, timers, widgets, and more — all with beautiful animations and intelligent layouts.</i>
</p>

<p align="center">
   <a href="https://github.com/Ebullioscopic/DynamicIsland/stargazers"><img src="https://img.shields.io/github/stars/Ebullioscopic/DynamicIsland?style=social"/></a>
   <a href="https://github.com/Ebullioscopic/DynamicIsland/network/members"><img src="https://img.shields.io/github/forks/Ebullioscopic/DynamicIsland?style=social"/></a>
   <a href="https://github.com/Ebullioscopic/DynamicIsland/issues"><img src="https://img.shields.io/github/issues/Ebullioscopic/DynamicIsland"/></a>
   <a href="https://github.com/Ebullioscopic/DynamicIsland/pulls"><img src="https://img.shields.io/github/issues-pr/Ebullioscopic/DynamicIsland"/></a>
</p>

---

## 📑 Table of Contents

- [🎬 Demo](#-demo)
- [✨ Features](#-features)
- [🚀 Getting Started](#-getting-started)
- [📖 Usage](#-usage)
- [⚙️ Configuration](#️-configuration)
- [🚧 Roadmap](#-roadmap)
- [🔧 Troubleshooting](#-troubleshooting)
- [🤝 Contributing](#-contributing)
- [📜 License](#-license)
- [🏆 Acknowledgments](#-acknowledgments)
- [👥 Contributors](#-contributors)

---

## 🎬 Demo

<div align="center">
   <img src="https://github.com/Ebullioscopic/DynamicIsland/blob/main/DynamicIslandSamples/dynamicislandscreenrecord.gif" alt="DynamicIsland Demo" width="700"/>
</div>

---

## ✨ Features

<div align="center">
   <img src="https://github.com/Ebullioscopic/DynamicIsland/blob/main/DynamicIslandSamples/statsmonitor.png" alt="Stats Monitor" width="350"/>
   <br>
   <img src="https://github.com/Ebullioscopic/DynamicIsland/blob/main/DynamicIslandSamples/media.png" alt="Media Controls" width="350"/>
</div>

### 🎵 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**: Apple Music, Spotify, YouTube Music, and more
- **Smooth Transitions**: Elegant animations between tracks and states
- **Minimalistic Mode**: Streamlined 420px compact layout for essential controls
- **Lighting Effects**: Beautiful album art glow effects with player tinting
- **Sneak Peek**: Standard and inline preview modes for quick glances

### 📊 Advanced System Monitoring
- **CPU, Memory, GPU, Network, Disk**: Real-time stats with live graphs
- **Dual-Quadrant Graphs**: Network and disk stats show upload/download or read/write
- **Intelligent Layout**: Vertical expansion, 1-5 graph layouts, perfect centering
- **Customizable Visibility**: Toggle individual graphs on/off
- **Smooth Animations**: Debounced updates for fluid transitions
- **Stats Panel**: Floating window with detailed system metrics

### 🎨 ColorPicker
<div align="center">
   <img src="https://github.com/Ebullioscopic/DynamicIsland/blob/main/DynamicIslandSamples/colorpickerpanel.png" alt="ColorPicker Panel" width="350"/>
   <br>
   <img src="https://github.com/Ebullioscopic/DynamicIsland/blob/main/DynamicIslandSamples/colorpickerpopover.png" alt="ColorPicker Popover" width="350"/>
</div>

- **Screen Color Picking**: Raycast-inspired panel, real-time magnification
- **Multiple Formats**: HEX, RGB, HSL, SwiftUI, UIColor, NSColor, CSS, and more
- **History & Quick Copy**: Recent colors, hover info, click to copy
- **Global Shortcut**: Cmd+Shift+P (customizable)
- **Panel & Popover Modes**: Choose between floating panel or integrated popover
- **Settings Integration**: Full control over features and appearance

### 📋 Clipboard Manager
<div align="center">
   <img src="https://github.com/Ebullioscopic/DynamicIsland/blob/main/DynamicIslandSamples/clipboardpanel.png" alt="Clipboard Panel" width="350"/>
   <br>
   <img src="https://github.com/Ebullioscopic/DynamicIsland/blob/main/DynamicIslandSamples/clipboardpopover.png" alt="Clipboard Popover" width="350"/>
</div>

- **Clipboard History**: Access recent clipboard items with thumbnails
- **Panel & Popover**: Dual display modes for flexible access
- **Always Active**: Clipboard monitoring enabled by default
- **Quick Access**: Click to copy, keyboard shortcuts for rapid paste

### 🧠 Screen Assistant
- **AI-Powered Analysis**: Intelligent screen content understanding
- **Panel & Popover Modes**: Flexible display options
- **Context-Aware**: Smart suggestions based on screen content
- **Keyboard Shortcut**: Quick access to screen analysis

### ✨ Minimalistic Mode (NEW!)
- **Compact Layout**: 420px width (vs 640px normal)
- **Essential Features Only**: Music controls, HUDs, timer - no clutter
- **Perfect for Light Use**: Minimal interface for everyday tasks
- **Auto-Configuration**: Profile-based setup during onboarding
- **Smooth Transitions**: Seamless switching between modes

### 🎯 Smart Onboarding (NEW!)
- **User Profiles**: Developer, Designer, Light Use, Student
- **Multi-Select**: Choose multiple profiles for combined features
- **Auto-Configuration**: Settings applied based on selected profiles
- **Privacy Policy**: Integrated privacy policy links
- **Guided Setup**: Camera, calendar, music permissions with clear explanations

### ⏱️ Timer & Productivity
- **Multiple Timers**: Create/manage named timers
- **Live Activities**: Background timer monitoring, 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, charging status
- **System Integration**: Native macOS battery monitoring

### 🖥️ Modern UI & Animations
- **Smooth Transitions**: Professionally animated state changes
- **Hover Effects**: Interactive feedback, 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

### 🗂️ Widgets & Panels
- **Multiple Panel Modes**: Floating panels and integrated popovers
- **Clipboard Manager**: Quick access to recent clipboard items (always enabled)
- **Screen Assistant**: AI-powered screen content analysis
- **ColorPicker**: Professional color picking tool
- **Stats Panel**: Floating system monitoring window
- **Weather Widget**: Displays current weather (location access required)
- **Calendar Integration**: View upcoming events and schedules
- **App Switcher**: Swipe gestures for fast app switching

### ⌨️ Keyboard Shortcuts
- **Toggle Notch**: Customizable shortcut to open/close DynamicIsland
- **Clipboard Panel**: Quick access to clipboard history
- **ColorPicker**: Instant color picker activation (Cmd+Shift+P)
- **Screen Assistant**: AI analysis shortcut
- **Stats Panel**: Toggle system monitoring window
- **Demo Timer**: Start 5-minute demo timer
- **Sneak Peek**: Quick preview toggle
- **Fully Customizable**: All shortcuts can be remapped

### 🎨 Customization & Theming
- **Minimalistic Mode**: Toggle between full-featured and minimal layouts
- **Corner Radius Scaling**: Adjust notch roundness
- **Lighting Effects**: Album art glow and player tinting
- **Shadow Effects**: Customize drop shadows
- **Mirror Feature**: Quick camera preview
- **Custom Animations**: Modern or classic close animations
- **Profile-Based Setup**: Auto-configure based on use case

---

## 🚀 Getting Started

### Prerequisites
- **macOS Sonoma 14.0+** (Optimized for Sequoia 15.0+)
- **MacBook with Notch** (Pro 14"/16" M1/M2/M3/M4 series)
- **Xcode 15.0+**, **Swift 5.9+**
- **Admin privileges** for system monitoring features

### Installation
```bash
git clone https://github.com/Ebullioscopic/DynamicIsland.git
cd DynamicIsland
open DynamicIsland.xcodeproj
```
1. Build and run in Xcode (`Cmd + R`)
2. **First Launch Onboarding**:
   - Choose your profile(s): Developer, Designer, Light Use, or Student
   - Grant permissions: Camera (for mirror), Calendar, Music
   - Settings auto-configured based on your selection
3. Enable **Accessibility** for advanced features (ColorPicker, Screen Assistant)
4. The app will appear in your menu bar and activate the notch

### Quick Start Profiles

**🔧 Developer**
- ColorPicker, Stats, Screen Assistant, Timer enabled
- Full feature set for coding workflows

**🎨 Designer**
- ColorPicker, Mirror, Lighting Effects enabled
- Visual-focused tools and aesthetics

**✨ Light Use**
- Minimalistic Mode (420px compact layout)
- Essential features only: Music, HUDs, Timer

**📚 Student**
- Calendar, Timer, Clipboard enabled
- Organization-focused feature set

**Note**: Clipboard Manager is always enabled regardless of profile selection.

---

## 📖 Usage

### Basic Controls
- **Hover to Activate**: Move cursor near the notch to expand
- **Click to Open**: Tap the notch area for full controls
- **Gesture Support**: Swipe down to expand, swipe up to close
- **Tab Navigation**: Switch between Home, Stats, Timer, and more

### First Time Setup
1. **Choose Your Profile**: Select Developer, Designer, Light Use, or Student
2. **Grant Permissions**: Camera, Calendar, Music access as needed
3. **Enable Accessibility**: For ColorPicker and Screen Assistant (optional)
4. **Customize**: Visit Settings to fine-tune features

### Music & Media
- **Now Playing**: Album art, track info, playback controls
- **Visualizer**: Real-time audio spectrum (enable in Settings)
- **Minimalistic Mode**: Compact 420px layout for essential controls
- **Sneak Peek**: Quick preview without fully opening

### System Monitoring
- **Stats Tab**: CPU, Memory, GPU, Network, Disk with live graphs
- **Layout Intelligence**: 1-3 graphs in a row, 4+ in grid layout
- **Stats Panel**: Floating window for persistent monitoring
- **Smooth Transitions**: Animated layout changes, perfect centering

### ColorPicker
- **Quick Access**: Cmd+Shift+P or from tab navigation
- **Pick Colors**: Click anywhere on screen to sample
- **Copy Formats**: HEX, RGB, HSL, SwiftUI, CSS, and more
- **History**: Access recently picked colors
- **Panel/Popover**: Choose your preferred display mode

### Clipboard Manager
- **Always Active**: Clipboard history automatically tracked
- **Panel Access**: Keyboard shortcut or tab navigation
- **Quick Copy**: Click any item to copy to clipboard
- **Visual Previews**: See thumbnails of copied content

### Screen Assistant
- **AI Analysis**: Intelligent screen content understanding
- **Context Aware**: Smart suggestions based on what you're viewing
- **Keyboard Shortcut**: Quick activation
- **Privacy First**: Local processing, no data sent externally

### Customization
- **Settings Window**: Click menubar icon → Settings
- **Profile Switch**: Change between Developer/Designer/Light/Student modes
- **Minimalistic Toggle**: Enable/disable compact layout
- **Feature Toggles**: Enable/disable individual features
- **Keyboard Shortcuts**: Customize all hotkeys
- **Themes**: Light, dark, system adaptive

---

## ⚙️ Configuration

### Settings Categories

#### General
- **Menubar Icon**: Show/hide menubar icon
- **Multi-Display Support**: Choose main monitor, show on all displays
- **Minimalistic Mode**: Enable compact 420px layout
- **User Profiles**: Switch between Developer/Designer/Light/Student

#### Appearance
- **Corner Radius Scaling**: Adjust notch roundness
- **Lighting Effects**: Album art glow and player tinting
- **Shadow Effects**: Enable/disable drop shadows
- **Mirror Feature**: Toggle camera preview
- **Modern Animations**: Choose animation styles
- **Themes**: Light, dark, system adaptive

#### Behavior
- **Hover Sensitivity**: Adjust activation distance
- **Open on Hover**: Auto-expand on cursor proximity
- **Haptic Feedback**: Enable/disable haptics
- **Gestures**: Customize swipe, tap, long-press actions

#### Features
- **Stats Monitoring**: Enable/disable CPU, Memory, GPU, Network, Disk
- **ColorPicker**: Toggle feature, set keyboard shortcut, panel/popover mode
- **Clipboard Manager**: Always enabled, configure display mode
- **Screen Assistant**: Enable/disable, set keyboard shortcut
- **Timer**: Default duration, notification style, colors
- **Music & Media**: Visualizer type, color adaptation, media sources

#### Keyboard Shortcuts
- **Toggle Notch**: Open/close DynamicIsland
- **Sneak Peek**: Quick preview toggle
- **Clipboard**: Open clipboard panel
- **ColorPicker**: Activate color picker (default: Cmd+Shift+P)
- **Screen Assistant**: Open AI assistant
- **Stats Panel**: Toggle monitoring window
- **Demo Timer**: Start 5-minute timer
- **All Customizable**: Remap any shortcut

#### Privacy & Permissions
- **Accessibility**: Required for ColorPicker, Screen Assistant
- **Camera**: For mirror feature
- **Calendar**: For event display
- **Music**: For playback controls

### Reset to Defaults
Use the included script to reset all settings:
```bash
./reset_app_defaults.sh
```
This will:
- Clear all UserDefaults
- Remove application support files
- Remove caches and preferences
- Reset to fresh install state (shows onboarding)

---

## 🚧 Roadmap

### ✅ Recently Added
- **Minimalistic Mode**: Compact 420px layout for light use
- **Smart Onboarding**: Profile-based setup (Developer/Designer/Light/Student)
- **ColorPicker**: Professional screen color picking tool
- **Clipboard Manager**: Always-on clipboard history
- **Screen Assistant**: AI-powered screen analysis
- **Panel System**: Floating windows and integrated popovers
- **Lighting Effects**: Album art glow and player tinting
- **Stats Panel**: Floating system monitoring window
- **Enhanced Keyboard Shortcuts**: Full customization support

### 🔄 Upcoming Features
- **Enhanced Calendar Integration**: Weekly/monthly views, event details
- **Weather Widget**: Location-based forecasts, beautiful animations
- **Custom Shortcuts**: User-defined quick actions, app launchers
- **Performance Optimizations**: Reduced memory/battery usage
- **Voice Commands**: Siri integration
- **Widget Marketplace**: Community custom widgets
- **Advanced Analytics**: Historical performance data
- **Cloud Sync**: Settings across devices
- **AI-Powered Insights**: Intelligent system recommendations
- **3D Animations**: Enhanced visual effects
- **Plugin Architecture**: Third-party extensions
- **Cross-Platform**: iPad/iPhone companion apps
- **Localization**: Multi-language support

---

## 🔧 Troubleshooting

### Common Issues & Solutions

#### Permissions
- **Accessibility**: Required for ColorPicker and Screen Assistant
  - Go to System Settings → Privacy & Security → Accessibility
  - Enable DynamicIsland
  - **Important**: Quit and restart the app after granting permission
- **Camera**: For mirror feature
- **Calendar**: For event display
- **Screen Recording**: For advanced features (optional)

#### Stats Not Updating
- Check feature toggles in Settings → Stats
- Verify Stats feature is enabled
- Restart monitoring from Settings
- Check Activity Monitor for CPU/memory usage

#### Music Controls Not Working
- Ensure media app (Music, Spotify, etc.) is playing
- Check Music permission in System Settings
- Restart DynamicIsland
- Try switching between media apps

#### ColorPicker Not Working
- Grant Accessibility permission (see above)
- **Must quit and restart** app after granting permission
- Check keyboard shortcut isn't conflicting
- Verify ColorPicker feature is enabled in Settings

#### Window Positioning Issues
- If notch appears shifted after toggling Minimalistic Mode:
  - This was fixed in recent updates
  - Update to latest version
  - Window now repositions immediately

#### Performance Issues
- Reduce stats update frequency in Settings
- Disable unused features (Stats, Visualizer, etc.)
- Check "Minimalistic Mode" for lighter resource usage
- Close other resource-intensive apps
- Restart DynamicIsland

### Advanced Troubleshooting

#### Reset to Factory Defaults
Use the included reset script:
```bash
cd /path/to/DynamicIsland
./reset_app_defaults.sh
```

Or manually:
```bash
# Clear UserDefaults
defaults delete com.karthikinformationtechnology.DynamicIsland

# Remove app data
rm -rf ~/Library/Application\ Support/DynamicIsland
rm -rf ~/Library/Caches/com.karthikinformationtechnology.DynamicIsland
rm -f ~/Library/Preferences/com.karthikinformationtechnology.DynamicIsland.plist
rm -rf ~/Library/Saved\ Application\ State/com.karthikinformationtechnology.DynamicIsland.savedState
```

#### Clean Reinstall
1. Quit DynamicIsland
2. Delete app from Applications
3. Run reset script (above)
4. Rebuild from Xcode

#### Debug Mode
- Hold `⌥` while opening Settings
- Navigate to Advanced → Debug Mode
- Enable Verbose Logging
- Check Console.app for detailed logs

### Getting Help
- **GitHub Issues**: [Report bugs or request features](https://github.com/Ebullioscopic/DynamicIsland/issues)
- **Discussions**: [Ask questions, share ideas](https://github.com/Ebullioscopic/DynamicIsland/discussions)
- **Documentation**: Check `ONBOARDING_ENHANCEMENT.md`, `SYSTEM_TIMER_DETECTION.md` for detailed guides

---

## 🤝 Contributing

We welcome contributions from developers, designers, and users!

### For Developers
1. **Fork the repository**
2. **Clone your fork**
    ```bash
    git clone https://github.com/yourusername/DynamicIsland.git
    cd DynamicIsland
    ```
3. **Install dev dependencies**
    ```bash
    brew install swiftlint
    brew install swiftformat
    ```
4. **Create a feature branch**
    ```bash
    git checkout -b feature/your-feature-name
    ```
5. **Commit & Push**
    ```bash
    git commit -m "feat: add new feature"
    git push origin feature/your-feature-name
    ```
6. **Open a Pull Request**

### For Designers
- UI/UX improvements, icon design, animation concepts

### For Documentation
- User guides, API docs, translations

---

## 📜 License

This project is licensed under the **MIT License** — see [LICENSE](LICENSE) for details.

---

## 🏆 Acknowledgments

- **Apple's Dynamic Island** — inspiration for this project
- **NotchNook & HiDock** — early notch customization pioneers
- **SwiftUI, Combine, AVFoundation, IOKit** — technical foundation
- **Lottie, SF Symbols, Apple Design Resources** — design & animation
- **Open Source Contributors, Beta Testers, Community**

---

## 👥 Contributors

<table>
   <tr>
      <td align="center">
         <a href="https://github.com/Ebullioscopic">
            <img src="https://github.com/Ebullioscopic.png" width="100px;" alt="Ebullioscopic"/>
            <br />
            <sub><b>Ebullioscopic</b></sub>
         </a>
         <br />
         <sub>🚀 Creator & Lead Developer</sub>
         <br />
         <sub>Core architecture, UI/UX design</sub>
      </td>
   </tr>
</table>

---

<div align="center">
   <b>⭐ Star this repository if DynamicIsland enhanced your Mac experience!</b>
   <br><br>
   <a href="https://github.com/Ebullioscopic/DynamicIsland">🔗 GitHub Project</a>
</div>

## 🎬 Preview

![DynamicIsland Preview](https://github.com/Ebullioscopic/DynamicIsland/blob/main/dynamic-island-preview.jpeg)

## 🚀 Demonstration

![DynamicIsland Demo](https://github.com/Ebullioscopic/DynamicIsland/blob/main/dynamic-island-demo.gif)

<details open>
<summary>📑 Table of Contents</summary>

- [✨ Features](#-features)
- [🆕 What's New](#-whats-new)
- [🎥 Demo](#-demo)
- [🚀 Getting Started](#-getting-started)
  - [Prerequisites](#prerequisites)
  - [Installation](#installation)
- [📖 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)

</details>

---

## ✨ Features

### 🎵 **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

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)

---

## 🚀 Getting Started

Get **DynamicIsland** running on your macOS system with these simple steps.

### Prerequisites

- **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

1. **Clone the Repository**
   ```bash
   git clone https://github.com/Ebullioscopic/DynamicIsland.git
   cd DynamicIsland
   ```

2. **Open in Xcode**
   ```bash
   open DynamicIsland.xcodeproj
   ```

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

---

## 📖 Usage

Once **DynamicIsland** is installed and running, it will display widgets and controls in the MacBook's notch area. Here are some usage tips and customization options.

### Basic Controls

- **Music Controls**: Hover over the notch and use on-screen buttons to control playback.
- **Battery Status**: A battery indicator will be displayed in the notch. Low battery alerts will appear automatically.
- **Weather Widget**: Displays current weather for your location (requires location access).
- **App Switcher**: Swipe gestures allow you to quickly switch between open applications.

### Customization Options

To personalize your DynamicIsland experience:

1. **Open Preferences**: Access the Preferences pane by long-pressing on the notch area.
2. **Themes**: Choose between **light**, **dark**, or **system adaptive** themes.
3. **Widget Settings**: Enable/disable specific widgets, adjust sizes, and set display preferences.
4. **Gestures**: Customize swipe, tap, and long-press actions for app switching and widget controls.

---

## ⚙️ Configuration

**DynamicIsland** offers extensive customization through its intuitive settings interface.

### Settings Categories

#### **📊 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
```

#### **🎵 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

Exciting features planned for upcoming releases:

### **🔄 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 & Solutions

#### **🚫 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

#### **📊 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

#### **🎵 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**.
2. **Clone Your Fork**:
    ```bash
    git clone https://github.com/yourusername/DynamicIsland.git
    cd DynamicIsland
    ```
3. **Create a New Branch**:
    ```bash
    git checkout -b feature/YourFeatureName
    ```
4. **Make Your Changes** and **Commit**:
    ```bash
    git commit -m "Added new feature"
    ```
5. **Push to Your Fork**:
    ```bash
    git push origin feature/YourFeatureName
    ```
6. **Create a Pull Request**: Head to the original repository and open a pull request.

For major changes, please open an issue first to discuss what you’d like to change.

---

## 📜 License

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

**DynamicIsland** exists thanks to the contributions and inspiration from:

### **🎯 Core Inspiration**
- **BoringNotch**: The base project on which DynamicIsland is built on
- **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**:

<table>
  <tr>
    <td align="center">
      <a href="https://github.com/Ebullioscopic">
        <img src="https://github.com/Ebullioscopic.png" width="100px;" alt="Ebullioscopic"/>
        <br />
        <sub><b>Ebullioscopic</b></sub>
      </a>
      <br />
      <sub>🚀 Creator & Lead Developer</sub>
      <br />
      <sub>Core architecture, UI/UX design</sub>
    </td>
  </tr>
</table>

### **🌟 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

---

<div align="center">

### **⭐ 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**

</div>