From c5314ebae35fc134ebf52af1513dc8991f23343b Mon Sep 17 00:00:00 2001 From: Zac Gaetano Date: Sun, 31 May 2026 10:56:30 -0400 Subject: [PATCH] Add Dragon-ISO installer design spec --- .../2026-05-31-dragon-iso-installer-design.md | 207 ++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-31-dragon-iso-installer-design.md diff --git a/docs/superpowers/specs/2026-05-31-dragon-iso-installer-design.md b/docs/superpowers/specs/2026-05-31-dragon-iso-installer-design.md new file mode 100644 index 0000000..4522a9d --- /dev/null +++ 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` `` 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)