Merge feature/v2.1.0-quick-wins: Configurable settings and UX improvements

Closes #20, Closes #11

Features:
- Configurable title display duration (5, 10, 15, or 30 seconds)
- Flash on meeting start option (default off)
- Shows 'Please Setup' for unconfigured plugins

Bug fixes:
- Fixed title display duration bug (was showing minutes instead of seconds)
- Fixed startup race condition causing buttons to get stuck on Loading

Author: pedrofuentes

.github/copilot-instructions.md

@@ -145,8 +145,11 @@ Checkboxes require specific HTML structure for SDPI styling:
 When checking boolean settings, handle `undefined` for backwards compatibility:
 
 ```typescript
-// undefined = true (default), false = false, true = true
-const setting = value === undefined ? true : Boolean(value);
+// excludeAllDay: undefined = true (default on), false = false, true = true
+const excludeAllDay = value === undefined ? true : Boolean(value);
+
+// flashOnMeetingStart: undefined = false (default off), must explicitly be true
+const flashEnabled = settings.flashOnMeetingStart === true;
 ```
 
 ## Common Issues
@@ -158,6 +161,8 @@ const setting = value === undefined ? true : Boolean(value);
 | Checkbox not visible | Wrong SDPI HTML structure | Use `type="checkbox"` on parent div, label with span |
 | Debug panel always showing | `display: block` hardcoded | Set `display: none`, show only when `isDebugMode` |
 | Outlook times wrong | Windows timezone not mapped | Check `timezone-service.ts` mapping |
+| Buttons stuck on "Loading" | Startup race condition | `waitForCacheAndStart` uses 500ms polling with `actionRef` fallback |
+| Title shows for too long | Duration multiplied twice | `getTitleDisplayDuration()` returns seconds, caller multiplies by 1000 |
 
 ## File Locations
 
@@ -170,44 +175,142 @@ const setting = value === undefined ? true : Boolean(value);
 
 ## Release Process
 
-### Creating a Release Package
+### Complete Release Workflow
+
+Follow these steps in order for a complete release:
+
+#### 1. Pre-Release Checklist
+
+```powershell
+# Ensure all tests pass
+npm test
+
+# Ensure you're on the feature branch with all changes committed
+git status
+git log --oneline -5
+```
+
+#### 2. Update Version Numbers
+
+Update version in both files (must match):
+- `manifest.json`: 4-part version `"Version": "X.Y.Z.0"`
+- `package.json`: 3-part version `"version": "X.Y.Z"`
+
+#### 3. Merge Feature Branch to Main
+
+```powershell
+# Switch to main and pull latest
+git checkout main
+git pull origin main
+
+# Merge feature branch (use --no-ff to preserve history)
+# Include issue references to auto-close them
+git merge --no-ff feature/vX.Y.Z-branch-name -m "Merge feature/vX.Y.Z-branch-name: Brief description
+
+Closes #XX, Closes #YY"
+
+# Push to main
+git push origin main
+```
+
+#### 4. Create Release Package
 
 **CRITICAL**: Always use the Stream Deck CLI to create packages. Manual zipping will create invalid packages.
 
 ```powershell
-# 1. Build for production (outputs to release/ folder)
+# Build for production (outputs to release/ folder)
 npm run build:production
 
-# 2. Create package using Stream Deck CLI
+# Create package using Stream Deck CLI
 streamdeck pack "release/com.pedrofuentes.ical.sdPlugin" --output release
 
-# 3. Creates: release/com.pedrofuentes.ical.streamDeckPlugin
+# Verify package was created
+Get-Item "release/com.pedrofuentes.ical.streamDeckPlugin"
 ```
 
-### Creating a GitHub Release
+#### 5. Test the Package (Optional but Recommended)
 
 ```powershell
-# 1. Create annotated tag
-git tag -a vX.Y.Z -m "vX.Y.Z - Description"
+# Remove dev plugin and test the package
+Stop-Process -Name "StreamDeck" -Force
+Remove-Item "$env:APPDATA\Elgato\StreamDeck\Plugins\com.pedrofuentes.ical.sdPlugin" -Recurse -Force
+Start-Process "$env:ProgramFiles\Elgato\StreamDeck\StreamDeck.exe"
+# Then double-click the .streamDeckPlugin file to install and verify it works
+```
+
+#### 6. Create Git Tag
+
+```powershell
+# Create annotated tag on main branch
+git tag -a vX.Y.Z -m "vX.Y.Z - Brief description of release"
+
+# Push tag to remote
 git push origin vX.Y.Z
+```
+
+#### 7. Create GitHub Release
 
-# 2. Create release with plugin package
+**IMPORTANT**: Use GitHub keywords to automatically close related issues. Include `Closes #X`, `Fixes #X`, or `Resolves #X` in the release notes for each issue addressed.
+
+```powershell
+# Create release with plugin package attached
 gh release create vX.Y.Z "release/com.pedrofuentes.ical.streamDeckPlugin" `
-  --title "vX.Y.Z - Title" `
-  --notes "Release notes"
+  --title "vX.Y.Z - Release Title" `
+  --notes "## What's New
+
+- ✨ Feature 1 (Closes #XX)
+- ✨ Feature 2 (Closes #YY)
+- 🐛 Bug fix 1 (Fixes #ZZ)
+
+## Installation
+
+Download the \`.streamDeckPlugin\` file and double-click to install."
 ```
 
-### Testing Before Release
+Or create manually on GitHub:
+1. Go to https://github.com/pedrofuentes/stream-deck-ical/releases/new
+2. Choose the tag `vX.Y.Z`
+3. Set release title
+4. Add release notes with `Closes #X` or `Fixes #X` for each issue
+5. Attach `release/com.pedrofuentes.ical.streamDeckPlugin`
+6. Publish release
+
+### Automatic Issue Closing
+
+GitHub automatically closes issues when these keywords are used in:
+- **Commit messages** merged to main: `git commit -m "feat: add feature X (Closes #123)"`
+- **PR descriptions**: Include `Closes #123` in the PR body
+- **Release notes**: Issues are closed when the release is published
+
+**Keywords** (case-insensitive):
+- `Closes #X` / `Close #X`
+- `Fixes #X` / `Fix #X`  
+- `Resolves #X` / `Resolve #X`
+
+**Multiple issues**: `Closes #11, Closes #20` or `Fixes #11, #20`
+
+#### 8. Post-Release Cleanup
 
 ```powershell
-# Remove dev plugin and test the package
-Stop-Process -Name "StreamDeck" -Force
-Remove-Item "$env:APPDATA\Elgato\StreamDeck\Plugins\com.pedrofuentes.ical.sdPlugin" -Recurse -Force
-Start-Process "$env:ProgramFiles\Elgato\StreamDeck\StreamDeck.exe"
-# Then double-click the .streamDeckPlugin file to install
+# Delete merged feature branch (optional)
+git branch -d feature/vX.Y.Z-branch-name
+git push origin --delete feature/vX.Y.Z-branch-name
+
+# Re-link development plugin if needed
+streamdeck link "dist/com.pedrofuentes.ical.sdPlugin"
 ```
 
-### Version Numbers
+### Quick Reference Commands
 
-- `manifest.json`: 4-part version `"Version": "X.Y.Z.0"`
-- `package.json`: 3-part version `"version": "X.Y.Z"`
+```powershell
+# Full release sequence (after testing is complete)
+git checkout main
+git pull origin main
+git merge --no-ff feature/vX.Y.Z-name -m "Merge feature/vX.Y.Z-name"
+git push origin main
+npm run build:production
+streamdeck pack "release/com.pedrofuentes.ical.sdPlugin" --output release
+git tag -a vX.Y.Z -m "vX.Y.Z - Description"
+git push origin vX.Y.Z
+gh release create vX.Y.Z "release/com.pedrofuentes.ical.streamDeckPlugin" --title "vX.Y.Z" --notes "Release notes"
+```

README.md

@@ -6,6 +6,13 @@ iCal Plugin for [elgato Stream Deck](https://www.elgato.com/en/gaming/stream-dec
 
 This plugin is available on the Stream Deck store, you can also download [the last release](https://github.com/pedrofuentes/stream-deck-ical/releases) or build it yourself using the code on this repo.
 
+## ✨ New in v2.1
+
+- ✅ **Configurable Title Display**: Choose how long meeting titles show (5, 10, 15, or 30 seconds)
+- ✅ **Meeting Start Flash**: Optional visual alert when meetings begin
+- ✅ **Improved Startup**: Faster button initialization with better status messages
+- ✅ **Better UX**: Shows "Please Setup" for unconfigured plugins
+
 ## ✨ New in v2.0
 
 - ✅ **Recurring Events Support**: Daily, weekly, monthly recurring events with RRULE
@@ -36,8 +43,10 @@ This plugin is available on the Stream Deck store, you can also download [the la
 ### Next Meeting ###
 * Shows time left until next meeting starts
 * If the button is pushed it will show the title of the next meeting (scrolling marquee)
+  * **Configurable duration**: Choose 5, 10, 15, or 30 seconds for title display
   * If the button is pushed while the text is showing it will go back to show the time left until the next meeting
   * At the end of the title animation, the button will go back to show the time left until the next meeting
+* **Optional flash alert** when meetings are about to start (disabled by default)
 * Changes icon color to orange when there are 5 minutes left for the next meeting to start
 * Changes icon color to red when there are 30 seconds left for the next meeting to start
 
@@ -106,8 +115,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup instructions.
 3. Click "Settings" button
 4. Enter your iCal URL
 5. Choose time window (1, 3, 5, or 7 days)
-6. Optionally uncheck "Exclude All-Day Events" to show all-day events
-7. Click "Save Settings"
+6. Set title display duration (5, 10, 15, or 30 seconds)
+7. Optionally enable "Flash when meeting starts" for visual alerts
+8. Optionally uncheck "Exclude All-Day Events" to show all-day events
+9. Click "Save Settings"
 
 ## Troubleshooting
 
@@ -155,6 +166,14 @@ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
 
 ## Changelog
 
+### v2.1.0 (2026)
+- ✨ **Configurable Title Display Duration**: Choose 5, 10, 15, or 30 seconds (#20)
+- ✨ **Flash on Meeting Start**: Optional visual alert when meetings begin (#11)
+- 🐛 Fixed title display duration bug (was showing for minutes instead of seconds)
+- 🐛 Fixed startup race condition causing buttons to get stuck on "Loading"
+- 🐛 Improved status messages: Shows "Please Setup" for unconfigured plugins
+- ✅ Added 18 new regression tests for v2.1.0 features
+
 ### v2.0.0 (2026)
 - ✨ **Major Update**: Migrated to Node.js SDK v2
 - ✨ Added recurring events support (RRULE, EXDATE)

manifest.json

@@ -40,7 +40,7 @@
   "CategoryIcon": "assets/icalIcon",
   "URL": "https://github.com/pedrofuentes/stream-deck-ical#readme",
   "PropertyInspectorPath": "pi.html",
-  "Version": "2.0.0.0",
+  "Version": "2.1.0.0",
   "Nodejs": {
     "Version": "20",
     "Debug": "enabled"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "stream-deck-ical",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "An elgato Stream Deck plugin that displays information from your calendar using an iCal URL. Visual cues and a countdown will help you end meetings on time and be ready for the next one.",
   "private": true,
   "type": "module",

pi/setup.html

@@ -37,6 +37,24 @@
             </div>
         </div>
 
+        <div class="sdpi-item">
+            <div class="sdpi-item-label">Title Display</div>
+            <select id="titleDisplayDuration" class="sdpi-item-value select">
+                <option value="5">5 seconds</option>
+                <option value="10">10 seconds</option>
+                <option value="15" selected>15 seconds</option>
+                <option value="30">30 seconds</option>
+            </select>
+        </div>
+
+        <div class="sdpi-item" type="checkbox">
+            <div class="sdpi-item-label">Meeting Alert</div>
+            <div class="sdpi-item-value">
+                <input type="checkbox" id="flashOnMeetingStart">
+                <label for="flashOnMeetingStart"><span></span>Flash when meeting starts</label>
+            </div>
+        </div>
+
         <div class="sdpi-item">
             <button class="sdpi-item-value" id="save">Save Settings</button>
             <button class="sdpi-item-value" id="refresh">Force Refresh &#128472;</button>
@@ -45,6 +63,8 @@
         <div class="sdpi-heading">Features</div>
         <div class="content">
             <ul>
+                <li><strong>New:</strong> Configurable title display duration (5, 10, 15, or 30 seconds)</li>
+                <li><strong>New:</strong> Flash button when meeting starts (can be disabled)</li>
                 <li><strong>New:</strong> Support for recurring events (daily, weekly, monthly, etc.)</li>
                 <li><strong>New:</strong> Configurable time window (1, 3, 5, or 7 days)</li>
                 <li><strong>New:</strong> Improved timezone handling for Outlook, Google, and Apple calendars</li>

pi/setup.js

@@ -44,6 +44,10 @@ function saveUrl() {
     const timeWindow = parseInt(document.getElementById('timeWindow').value, 10);
     const excludeAllDayEl = document.getElementById('excludeAllDay');
     const excludeAllDay = excludeAllDayEl ? excludeAllDayEl.checked : true;
+    const titleDisplayDurationEl = document.getElementById('titleDisplayDuration');
+    const titleDisplayDuration = titleDisplayDurationEl ? parseInt(titleDisplayDurationEl.value, 10) : 15;
+    const flashOnMeetingStartEl = document.getElementById('flashOnMeetingStart');
+    const flashOnMeetingStart = flashOnMeetingStartEl ? flashOnMeetingStartEl.checked : true;
 
     if (!url) {
         showAlert('Please enter an iCal URL');
@@ -62,6 +66,8 @@ function saveUrl() {
             url: url,
             timeWindow: timeWindow,
             excludeAllDay: excludeAllDay,
+            titleDisplayDuration: titleDisplayDuration,
+            flashOnMeetingStart: flashOnMeetingStart,
             urlVersion: (opener.globalSettings.urlVersion || 0) + 1
         };
 
@@ -152,6 +158,17 @@ document.addEventListener('DOMContentLoaded', function() {
             // Default to true if not set
             excludeAllDayCheckbox.checked = opener.globalSettings.excludeAllDay !== false;
         }
+        
+        // New settings
+        const titleDisplayDurationSelect = document.getElementById('titleDisplayDuration');
+        if (titleDisplayDurationSelect) {
+            titleDisplayDurationSelect.value = opener.globalSettings.titleDisplayDuration || 15;
+        }
+        const flashOnMeetingStartCheckbox = document.getElementById('flashOnMeetingStart');
+        if (flashOnMeetingStartCheckbox) {
+            // Default to true if not set
+            flashOnMeetingStartCheckbox.checked = opener.globalSettings.flashOnMeetingStart === true;
+        }
     }
 
     // Add event listeners