Add Dragon-ISO installer design spec

2026-05-31 10:56:30 -04:00 · 2026-05-31 10:56:30 -04:00 · c5314ebae3
commit c5314ebae3
parent ab47cccd42
1 changed files with 207 additions and 0 deletions
--- a/docs/superpowers/specs/2026-05-31-dragon-iso-installer-design.md
+++ b/docs/superpowers/specs/2026-05-31-dragon-iso-installer-design.md
@ -0,0 +1,207 @@
+# Dragon-ISO Installer Design
+
+**Date:** 2026-05-31  
+**Status:** Design Complete  
+**Audience:** End users downloading and installing Dragon-ISO
+
+---
+
+## Overview
+
+Update the existing WiX Toolset v5 MSI installer from TeamsISO branding to Dragon-ISO. The installer provides a simple, professional Windows installation experience for end users with minimal choices (Next → Install).
+
+**Key characteristics:**
+- Per-machine installation to `Program Files\Wild Dragon\Dragon-ISO\`
+- Simple UI (no customization dialogs)
+- Start Menu and Desktop shortcuts
+- Professional Add/Remove Programs (ARP) metadata
+- Prerequisite detection for .NET 8 Desktop Runtime and NDI 6 Runtime (warn, don't block)
+- Version: 1.0.0.0
+
+---
+
+## File and Naming Structure
+
+### Files to Rename
+- `installer/TeamsISO.Installer.wixproj` → `installer/Dragon-ISO.Installer.wixproj`
+- `installer/Package.wxs` → remains (generic name, no change needed)
+
+### Build Output
+- **Current (TeamsISO):** `TeamsISO-Setup-1.0.0.0.msi`
+- **Updated (Dragon-ISO):** `Dragon-ISO-Setup-1.0.0.0.msi`
+
+### Asset References
+- Icon: References `Dragon-ISO.ico` (already exists in `src/Dragon-ISO.App/Assets/`)
+- App directory: `src/Dragon-ISO.App/` (updated from `src/TeamsISO.App/`)
+- Publish output: `publish/Dragon-ISO/` (updated from `publish/TeamsISO/`)
+
+---
+
+## Branding Updates (in Package.wxs)
+
+### Product Metadata
+- **Package Name:** `"Dragon-ISO"` (from `"TeamsISO"`)
+- **Manufacturer:** `"Wild Dragon LLC"` (unchanged)
+- **UpgradeCode:** Keep existing GUID (allows upgrades from TeamsISO to Dragon-ISO)
+- **Version:** `1.0.0.0`
+
+### Summary Information
+- **Description:** "Dragon-ISO — per-participant NDI ISO controller for Microsoft Teams. Splits each Teams participant into a normalized NDI source for vMix / OBS / Ross / hardware switchers."
+- **Keywords:** "Dragon-ISO, NDI, Microsoft Teams, ISO recording, broadcast, live production, vMix, OBS, switcher, Wild Dragon"
+
+### Add/Remove Programs (ARP) Metadata
+- **Help Link:** `https://forge.wilddragon.net/zgaetano/dragon-iso`
+- **About Link:** `https://wilddragon.net`
+- **Support Contact:** `Wild Dragon LLC — support@wilddragon.net`
+- **Comments:** "Dragon-ISO turns Microsoft Teams' raw NDI broadcast into clean, normalized, per-participant NDI sources for ingestion by a live-production switcher (vMix, OBS, Ross, hardware capture). Each participant gets an individually-addressable source with configurable framerate, resolution, aspect mode, and audio routing."
+
+### Registry Keys
+- **Location:** `Software\Wild Dragon\Dragon-ISO` (from `Software\Wild Dragon\TeamsISO`)
+- Used for: Start Menu shortcut tracking, Desktop shortcut tracking, Install path storage
+
+### Shortcuts
+- **Start Menu:** `Wild Dragon → Dragon-ISO`
+- **Desktop:** `Dragon-ISO` shortcut
+- **Target:** `[INSTALLFOLDER]Dragon-ISO.exe`
+- **Icon:** Dragon-ISO icon from assets
+- **Description:** "Per-Participant NDI ISO Controller for Microsoft Teams"
+
+---
+
+## Installation Layout
+
+### Directory Structure
+```
+Program Files\Wild Dragon\Dragon-ISO\
+  ├── Dragon-ISO.exe                    (main executable)
+  ├── DragonISO.dll                     (core assembly)
+  ├── Assets\                           (icons, fonts, resources)
+  ├── Themes\                           (XAML theme files)
+  ├── [.NET dependencies]               (runtime assets, supporting DLLs)
+  └── [all other published files]
+```
+
+### Shortcuts Created
+- **Start Menu:** `%ProgramMenu%\Wild Dragon\Dragon-ISO.lnk`
+- **Desktop:** `%UserProfile%\Desktop\Dragon-ISO.lnk`
+- Both use stable GUIDs for reliable uninstall tracking
+
+### Uninstall Behavior
+- Standard Windows uninstall via Add/Remove Programs
+- Removes all application files and shortcuts
+- Removes registry entries under `Software\Wild Dragon\Dragon-ISO`
+- **Preserves:** User config files in `%APPDATA%\Dragon-ISO\` (for future upgrades)
+
+### Add/Remove Programs Entry
+Users see:
+- **Name:** Dragon-ISO
+- **Version:** 1.0.0.0
+- **Publisher:** Wild Dragon LLC
+- **Help:** Link to Forge repository
+- **About:** Link to wilddragon.net
+- **Contact:** support@wilddragon.net
+- **Icon:** Dragon-ISO app icon
+
+---
+
+## Build Process
+
+### Prerequisites
+- .NET 8 SDK
+- WiX Toolset v5 (`dotnet workload install wix`)
+
+### Build Steps
+
+1. **Publish the application:**
+   ```powershell
+   dotnet publish src/Dragon-ISO.App/Dragon-ISO.App.csproj `
+     -c Release -r win-x64 `
+     -o publish/Dragon-ISO
+   ```
+
+2. **Build the MSI:**
+   ```powershell
+   dotnet build installer/Dragon-ISO.Installer.wixproj -c Release
+   ```
+
+3. **Output:**
+   - Location: `installer/bin/Release/Dragon-ISO-Setup-1.0.0.0.msi`
+   - Ready for end-user distribution
+
+### Version Management
+- MSI version is driven by the app's `.csproj` `<Version>` tag
+- Update version once, builds auto-propagate to the MSI filename
+- UpgradeCode remains constant across versions (enables upgrade detection)
+
+### CI/CD Integration
+- Update existing `.forgejo/workflows/` to use new project paths
+- Scripts already handle publish → build → sign → release
+- Just update path references and output filename
+
+---
+
+## Prerequisites & Runtime Detection
+
+### .NET 8 Desktop Runtime
+- **Check:** Registry lookup for installed .NET 8 Desktop Runtime
+- **If missing:** Display warning dialog with link to download
+- **Install behavior:** Continue installation anyway (user can install .NET 8 later)
+- **At app launch:** App checks again; shows MessageBox with install link if still missing
+
+### NDI 6 Runtime
+- **Check:** Environment variable `NDI_RUNTIME_DIR_V6`
+- **If missing:** Display warning dialog
+- **Install behavior:** Continue installation anyway
+- **At app launch:** App checks again; shows MessageBox with install link if still missing
+
+**Rationale:** Allows staged deployment where IT can install Dragon-ISO first, then NDI/runtime later. End users get clear guidance at both install-time and app-launch time.
+
+---
+
+## Major Upgrade Behavior
+
+The installer detects when a newer version is already installed and:
+1. **Prevents downgrade:** Blocks installation of older versions with a clear error message
+2. **In-place upgrade:** Newer installs replace older ones seamlessly
+3. **Config preservation:** User configuration in `%APPDATA%\Dragon-ISO\` is preserved
+4. **UpgradeCode:** Constant GUID ensures upgrade detection works (TeamsISO → Dragon-ISO, and future versions)
+
+---
+
+## Error Handling
+
+### Installation Failures
+- WiX standard rollback behavior: if installation fails, all changes are undone
+- Clear error messages for common issues (insufficient permissions, disk space, etc.)
+
+### Shortcut Creation
+- If shortcut creation fails, installation continues (non-blocking)
+- User can manually create shortcuts from `Program Files\Wild Dragon\Dragon-ISO\Dragon-ISO.exe`
+
+### Registry Operations
+- If registry write fails, installation continues (non-blocking)
+- ARP entry may be incomplete but app is still functional
+
+---
+
+## Testing Checklist
+
+- [ ] MSI builds successfully with new branding
+- [ ] Install to clean system works end-to-end
+- [ ] Shortcuts appear in Start Menu and on Desktop
+- [ ] ARP entry shows correct metadata
+- [ ] Uninstall removes all files and shortcuts
+- [ ] Upgrade from TeamsISO to Dragon-ISO works
+- [ ] .NET 8 runtime detection shows warning if missing
+- [ ] NDI runtime detection shows warning if missing
+- [ ] App launches after installation
+- [ ] Help/About links in ARP entry work
+
+---
+
+## Future Enhancements (Out of Scope)
+
+- Code signing for published MSI
+- Automatic update checks via Squirrel.Windows
+- Per-user installation option
+- Silent/unattended install mode (for enterprise deployment)