chore: update doc

Author: mlhiter

CLAUDE.md

@@ -16,6 +16,12 @@ Open Sidenotes is a macOS menu bar application that provides a floating side pan
 - **Edge-triggered Activation**: Move mouse to right edge to toggle panel
 - **Auto-save**: Changes saved automatically after 1 second
 - **Drawer UI**: Slide-in note list overlay
+- **Settings Panel**: Comprehensive customization options
+  - Dock icon visibility control
+  - Auto-hide behavior with configurable delay (0-3s)
+  - Custom keyboard shortcuts (default: ⌘⌃Space)
+  - Storage location selection
+- **Session Persistence**: Automatically restores last opened note on launch
 
 ## Tech Stack
 
@@ -57,6 +63,8 @@ Or use Xcode: Open `open-sidenotes.xcodeproj` and press Cmd+R to run.
 - Implements edge-triggered activation: moving mouse to right screen edge (within 2px) toggles window visibility
 - Uses global mouse event monitoring (`NSEvent.addGlobalMonitorForEvents`)
 - Animates window slide-in/out with 0.2s duration using `NSAnimationContext`
+- Auto-hide on mouse exit with configurable delay (0-3s)
+- Supports global keyboard shortcut for window toggle (default: ⌘⌃Space)
 - Window properties:
   - Width: 400px
   - Height: Full screen visible frame
@@ -97,29 +105,62 @@ Or use Xcode: Open `open-sidenotes.xcodeproj` and press Cmd+R to run.
     - On blur: When losing focus
   - Preserves cursor position during re-rendering
 
+**Settings System**
+- `SettingsView`: Comprehensive settings panel with custom UI components
+  - `CustomToggleStyle`: Sage green toggle switches
+  - `CustomSlider`: Styled slider for delay adjustment (0-3s range)
+  - Settings categories: Appearance, Storage, Window Behavior, Keyboard Shortcuts
+- `ShortcutSettings`: ObservableObject managing user preferences
+  - `showDockIcon`: Toggle Dock icon visibility (requires restart)
+  - `autoHideOnMouseExit`: Auto-hide window when mouse leaves
+  - `hideDelay`: Configurable delay before auto-hide (0-3s)
+  - `toggleWindowShortcut`: Custom global keyboard shortcut
+  - Persisted via UserDefaults
+- `ShortcutRecorderView`: Custom keyboard shortcut recorder
+  - Interactive key capture with visual feedback
+  - Supports all modifier keys (⌘⌃⌥⇧)
+  - Clear button to remove shortcuts
+  - Real-time preview of recorded shortcut
+
+**Session Management**
+- `LastOpenedNoteManager`: Persists and restores last active note
+  - Saves note ID on selection change
+  - Auto-restores on app launch
+  - Uses UserDefaults for storage
+
 ### Data Flow
 
-1. User moves mouse to right edge → `SideNotesWindowController` detects → Window slides in
-2. User selects note → Updates `selectedNote` state → Loads Markdown content from `NoteStore`
-3. User types Markdown → `MarkdownEditor` updates plain text binding
-4. Render trigger fires (space/newline/1s delay) → `MarkdownRenderer` applies styling to source
-5. Auto-save triggers (1s after edit) → `NoteStore.updateNote` persists to JSON
-6. Mouse moves to edge again → Window slides out
+1. **App Launch** → Loads `ShortcutSettings` and `LastOpenedNoteManager` → Restores last note if exists
+2. **Edge Trigger** → User moves mouse to right edge → `SideNotesWindowController` detects → Window slides in
+3. **Keyboard Toggle** → User presses shortcut (⌘⌃Space) → `ShortcutManager` triggers window toggle
+4. **Note Selection** → User selects note → Saves to `LastOpenedNoteManager` → Loads content from `NoteStore`
+5. **Markdown Editing** → User types → Render triggers (space/newline/1s delay) → `MarkdownRenderer` applies styling
+6. **Auto-save** → 1s after edit → `NoteStore.updateNote` persists to file
+7. **Auto-hide** → Mouse exits window → Delay timer (0-3s) → Window slides out (if enabled)
+8. **Settings Change** → User modifies preferences → `ShortcutSettings` persists to UserDefaults → Notifies observers
 
 ### Key Technical Patterns
 
 - **Custom Markdown Rendering**: Regex-based parser applies styles without deleting source
-- **SwiftUI + AppKit Bridge**: Uses `NSViewRepresentable` to wrap NSTextView
+- **SwiftUI + AppKit Bridge**: Uses `NSViewRepresentable` to wrap NSTextView and custom controls
 - **Smart Debouncing**: Context-aware rendering triggers (immediate on space/newline, delayed otherwise)
-- **Global Event Monitoring**: Tracks mouse position system-wide to detect edge triggers
-- **File-based Persistence**: Markdown files with YAML front matter in Documents directory
-- **Stateful Window Management**: Tracks `isShown` and `lastAtRightEdge` to implement toggle behavior
+- **Global Event Monitoring**: Tracks mouse position and keyboard events system-wide
+- **File-based Persistence**: Markdown files in configurable storage directory
+- **Stateful Window Management**: Tracks `isShown`, `lastAtRightEdge`, and auto-hide timers
+- **Settings Persistence**: UserDefaults-based configuration with reactive updates
+- **Custom UI Components**: Hand-crafted toggle switches, sliders, and shortcut recorder
+- **Session Restoration**: Automatic recovery of last opened note on launch
+- **Hot Keys System**: Global keyboard shortcut registration using Carbon framework
 
 ## Development Notes
 
-- The app runs without a dock icon or standard menu bar (menu bar utility pattern)
+- The app runs as a menu bar utility (Dock icon visibility is configurable)
 - Window appears across all spaces and during full-screen apps
 - Markdown editing preserves all syntax - fully reversible
 - Mouse edge detection threshold is 2px from right screen edge
-- Window background has 98% opacity for semi-transparency
-- **No external dependencies** - pure Swift/AppKit implementation (Down library removed)
+- Auto-hide delay is configurable from 0-3 seconds (default: 0.5s)
+- Default keyboard shortcut: ⌘⌃Space (customizable)
+- Settings require app restart for Dock icon changes to take effect
+- Last opened note is automatically restored on app launch
+- Custom storage directory selection with real-time reload
+- **No external dependencies** - pure Swift/AppKit implementation

DESIGN_SYSTEM.md

@@ -132,7 +132,7 @@ Minimal, directional shadows create a sense of layering without being heavy-hand
 - **Secondary Text**: Smaller (12pt), lighter gray
 - **Centered vertically and horizontally**
 
-### Drawer Layout (NEW)
+### Drawer Layout
 - **Window Width**: 400px (compact side panel)
 - **Drawer Width**: 280px
 - **Editor Width**: Full 400px (336px usable after 32px padding on each side)
@@ -153,6 +153,62 @@ Minimal, directional shadows create a sense of layering without being heavy-hand
 #### Design Rationale
 The drawer pattern maximizes editor space (336px usable width vs. previous 44px) while maintaining quick access to the note list. The semi-transparent overlay and slide-in animation clearly communicate the layered interaction model. This approach keeps the window compact (400px) suitable for a side panel application while providing full editing capability.
 
+### Settings Window
+- **Window Size**: 450px × 570px (expands to 620px when auto-hide is enabled)
+- **Background**: Pure white (#FFFFFF)
+- **Content Padding**: 24px horizontal, 24px vertical top
+- **Section Spacing**: 20px between major sections
+- **Dividers**: Full-width horizontal lines between sections
+
+#### Settings Components
+**Custom Toggle Switch**:
+- **Dimensions**: 48px × 28px rounded rectangle
+- **Off State**: Light gray background (#E0E0E0)
+- **On State**: Sage green background (#7C9885)
+- **Toggle Circle**: White with 2px shadow, 3px padding, slides with spring animation
+- **Animation**: Spring response 0.3, dampingFraction 0.7
+
+**Custom Slider** (for delay adjustment):
+- **Track**: 4px height, 2px corner radius
+- **Track Color**: Light gray (#E0E0E0) inactive, sage green (#7C9885) active
+- **Thumb**: 16px white circle with shadow
+- **Range**: 0.0-3.0 seconds, 0.1 step increments
+- **Value Display**: Shows formatted delay (e.g., "0.5 s") in sage green
+
+**Shortcut Recorder**:
+- **Dimensions**: Auto-width × 32px height
+- **Corner Radius**: 6px
+- **States**:
+  - **Default**: Light gray background (#F5F5F5), placeholder "Click to record"
+  - **Recording**: Light green background (#E8F5E9), sage green border (2px), "Press keys..." text
+  - **Set**: Displays shortcut symbols (⌘⌃⌥⇧) + key name
+- **Clear Button**: 16px circle with "×" icon, appears on hover when shortcut is set
+- **Text**: 12pt system font, medium weight when active
+
+#### Settings Categories
+1. **Appearance**
+   - Show Dock Icon toggle
+   - Note: "Requires app restart to take effect"
+
+2. **Storage Location**
+   - Current path display (gray box, 12px padding)
+   - "Choose Folder" button (sage green)
+   - Reload alert when path changes
+
+3. **Window Behavior**
+   - Auto-hide toggle
+   - Hide delay slider (only visible when auto-hide enabled)
+   - Smooth height animation (0.3s) when toggling
+
+4. **Keyboard Shortcuts**
+   - Toggle Window shortcut recorder
+   - Custom key combination capture
+
+**Reset Button**: Bottom-left, gray background (#F0F0F0), "Reset to Default" text
+
+#### Design Rationale
+The settings window uses custom-styled components that match the app's editorial minimalism aesthetic while providing modern, intuitive controls. The sage green accent color creates visual consistency with the main interface. Inline help text (#999999) provides context without cluttering the design. The expandable layout (570→620px) accommodates conditional controls smoothly.
+
 ---
 
 ## Animation & Motion
@@ -168,6 +224,10 @@ The drawer pattern maximizes editor space (336px usable width vs. previous 44px)
 - **Drawer Slide**: 0.2s easeInOut with `.move(edge: .leading)` transition
 - **Background Overlay**: Fade in/out with drawer (automatic with SwiftUI animation)
 - **Menu Button Hover**: Instant opacity change from 8% to 15%
+- **Toggle Switch**: Spring animation (response 0.3, damping 0.7) for smooth toggle
+- **Settings Height**: 0.3s easeInOut when showing/hiding delay slider
+- **Auto-hide**: Configurable delay (0-3s) before window slides out
+- **Shortcut Recorder**: Instant visual feedback when entering recording state
 
 ### Future Enhancements (Optional)
 - Fade-in for newly created notes
@@ -188,6 +248,10 @@ The drawer pattern maximizes editor space (336px usable width vs. previous 44px)
 - **Hover feedback**: Visual change on all interactive elements
 - **Focus indicators**: System default for keyboard navigation
 - **Semantic colors**: Green for positive/active, red for destructive
+- **Keyboard navigation**: Full keyboard support in settings (Tab to navigate)
+- **Custom shortcuts**: User-configurable for accessibility needs
+- **Clear affordances**: Buttons and controls clearly indicate interactivity
+- **Shortcut recorder**: Visual state changes guide recording process
 
 ### Font Sizes
 - Minimum body text: 15pt (exceeds 12pt minimum recommendation)
@@ -243,6 +307,10 @@ Unlike typical note apps with cold blue accents or stark white backgrounds, Open
 - Minimal shadow usage (drawer and window only)
 - Efficient animation with SwiftUI transitions
 - No heavy animations or effects
+- UserDefaults-based settings persistence (lightweight)
+- Timer-based auto-hide with automatic invalidation
+- Global event monitors only active when needed
+- Custom NSView controls for optimal shortcut recording
 
 ### Future Enhancements
 - Dark mode support (charcoal background with warm accents)

README.md

@@ -16,11 +16,15 @@
 ## Features
 
 - **Edge Activation** — Move your mouse to the right edge of the screen to reveal the notes panel
+- **Keyboard Shortcut** — Toggle window with customizable global shortcut (default: ⌘⌃Space)
 - **Live Markdown** — Typora-style editing with real-time rendering while preserving source syntax
 - **Auto Save** — Your notes are automatically saved as you type
+- **Smart Auto-Hide** — Configurable auto-hide when mouse exits (0-3s delay)
+- **Session Restore** — Automatically reopens your last note on launch
+- **Customizable Settings** — Control Dock icon, storage location, and window behavior
 - **Lightweight** — Native SwiftUI app with minimal resource usage
 - **Always Available** — Works across all spaces and during full-screen apps
-- **Local Storage** — Notes stored as Markdown files in `~/Documents/OpenSidenotes/`
+- **Local Storage** — Notes stored as Markdown files in customizable directory
 
 ## Installation
 
@@ -43,19 +47,28 @@ xcodebuild -project open-sidenotes.xcodeproj -scheme open-sidenotes build
 
 ## Usage
 
-1. Launch the app — it runs in the background without a dock icon
-2. Move your mouse to the **right edge** of the screen
-3. The notes panel slides in automatically
-4. Start writing in Markdown
-5. Move to the edge again to hide the panel
+1. Launch the app — it runs as a menu bar utility
+2. **Show panel**: Move mouse to the right edge OR press `⌘⌃Space`
+3. Start writing in Markdown with live rendering
+4. **Hide panel**: Move to edge again, press shortcut again, or let it auto-hide
+5. Access settings from the menu bar icon
 
 ### Keyboard Shortcuts
 
 | Shortcut | Action |
 |----------|--------|
+| `⌘⌃Space` | Toggle Window (customizable) |
 | `⌘ F` | Find & Replace |
 | `⌘ N` | New Note |
 
+### Settings
+
+Access settings to customize:
+- **Appearance**: Show/hide Dock icon (requires restart)
+- **Storage Location**: Choose where notes are saved
+- **Window Behavior**: Enable auto-hide with custom delay (0-3s)
+- **Keyboard Shortcuts**: Record custom shortcut for window toggle
+
 ### Markdown Support
 
 ```markdown