# Lume – Current Features

What the app currently has.

---

## Overlay

- **Time display** – HH:mm (24h) or 12h format with AM/PM
- **Full-screen overlay** – Transparent, always on top, click-through
- **Primary display** – Overlay on the main screen
- **Background options** – Color, opacity (10–100%), corner radius (0–24px)
- **Hidden-window fix** – Persistent frame callback keeps clock updating when overlay is covered/unfocused

---

## Typography & Style

- **Font selector** – 10 Google Fonts: Inter, Roboto, Open Sans, Lato, Montserrat, Poppins, Raleway, Nunito, Oswald, Source Sans 3
- **Font size** – 12–120px
- **Text style** – Bold, Italic, Underline toggles
- **Time color** – Preset color grid (8 options)
- **Opacity** – 20–100%

---

## Layout & Position

- **9-position grid** – Top-left, top-center, top-right, center-left, center, center-right, bottom-left, bottom-center, bottom-right
- **Nudge position** – Draggable preview to fine-tune offset (±50px) from grid position
- **Edge spacing** – 0–64px padding from screen edges

---

## Options

- **24-hour format** – Toggle 12h/24h
- **Background** – Optional background behind time
- **Border** – Optional border around time

---

## Control Window

- **700×950** – Draggable, custom title bar
- **App icon in title bar** – lume.ico icon next to "Lume" text (replaces schedule icon)
- **Settings persistence** – All settings saved with shared_preferences
- **Scrollable** – Scrollable content when window is small
- **Header layout** – Show overlay, position grid, and nudge position in one horizontal row (140×140 cards)
- **Title bar** – DragToMoveArea on title area; back, settings, minimize/maximize/close buttons
- **Close button** – Hides window to system tray when “Minimize to tray” is on; exits app when off
- **Minimize to tray** – Option to hide control window to system tray; right-click tray icon for Show Lume / Exit
- **System tray** – Optional; can be disabled in Settings
- **Global hotkey** – Customizable overlay toggle (default Ctrl+Shift+L)

---

## Settings Screen

- **App card** – lume.ico icon, version badge (v1.0.0)
- **Dark mode toggle** – Light/dark theme, persisted, default dark
- **Behavior section** – Launch at startup, system tray toggle, minimize to tray, overlay hotkey customizer
- **Launch at startup** – Defaults to true; starts Lume in system tray when you sign in to Windows
- **Launch to tray** – When launch at startup and system tray are both enabled, app starts minimized to tray (control window hidden until user clicks tray icon)
- **Hotkey customizer** – Keyboard-style key chips; hold modifiers then press key; confirmation dialog; reset to default
- **About card** – Developer (Ahmad Abdulla Hasan, QALA.DEV), photo, website link, Facebook link
- **Copyright** – © 2026 Lume. Free and open source.
- **Links** – Website (https://qaladeveloper.site/) and Facebook open in browser via url_launcher

---

## Theme

- **Light & dark** – `LumeControlColors.light` and `LumeControlColors.dark`
- **Theme-aware UI** – `context.lumeColors` extension for all control/settings screens
- **Default** – Dark mode
- **No flash** – Theme loaded before first frame (hot reload, cold start)

---

## Technical Specifications

### Branding & Icons

- **Unified icon** – `assets/lume.ico` used for Windows app icon, system tray, settings app card, and custom title bar
- **Windows app icon** – `windows/runner/resources/app_icon.ico` (copied from lume.ico)

### Platform & Runtime

- **Platform** – Windows (Flutter desktop)
- **Dart SDK** – ^3.11.0
- **Framework** – Flutter

### Dependencies

| Package | Purpose |
|---------|---------|
| `window_manager` | Window control (always on top, opacity, frameless, click-through) |
| `desktop_multi_window` | Multi-window (main + overlay), inter-window method calls |
| `screen_retriever` | Primary display size and position for overlay placement |
| `google_fonts` | Time font loading (Inter, Roboto, etc.) |
| `shared_preferences` | Settings persistence |
| `flutter_localizations` | Material localizations |
| `flutter_colorpicker` | (Available, not used – preset colors only) |
| `url_launcher` | Open website and social links in browser |
| `system_tray` | System tray icon, minimize to tray, context menu |
| `hotkey_manager` | Customizable global hotkey for overlay toggle |
| `path_provider` | Temp path for tray icon |
| `launch_at_startup` | Launch app at Windows login |

### Project Structure

```
lib/
├── main.dart                 # Entry point, window routing, LumeApp, overlay method handler
├── screens/
│   ├── control_window.dart   # Main settings UI, custom window caption
│   ├── overlay_window.dart   # Time overlay
│   └── settings.dart         # App info, About, dark mode, Behavior (tray, hotkey), links
├── models/
│   ├── window_arguments.dart # OverlayWindowArguments, JSON serialization
│   └── overlay_settings_stream.dart  # Stream for live settings updates
├── services/
│   ├── settings_service.dart # shared_preferences load/save (incl. darkMode, systemTrayEnabled, hotkeyJson)
│   ├── hotkey_service.dart   # Registers overlay toggle hotkey from settings
│   ├── launch_at_startup_service.dart  # Launch at Windows login
│   └── tray_service.dart    # System tray init/destroy, context menu
└── theme/
    └── lume_theme.dart       # LumeControlColors (light/dark), themes
assets/
├── dev.JPEG                  # Developer photo for About card
└── lume.ico                  # App icon (Windows app, tray, settings, title bar)
```

### Architecture

- **Two windows** – Main (control) and overlay; overlay created via `WindowController.create` with `hiddenAtLaunch: true`, shown after first frame to avoid startup flash
- **Settings flow** – Control → `invokeMethod('updateSettings')` → `OverlaySettingsStream.emit` → Overlay rebuild
- **Persistence** – `LumeSettings` loads on init, saves on change; overlay state restored on launch
- **Theme** – Loaded in `_runMainWindow` before `runApp`; passed as `initialDarkMode` to avoid flash on hot reload
- **Tray & hotkey** – Tray init and hotkey registration conditional on `systemTrayEnabled`; hotkey from `overlayToggleHotKey` (HotKey.toJson/fromJson)