From f95e320907dd2b40f826eefbff753b5099fbe77e Mon Sep 17 00:00:00 2001
From: BFlat <bombayapirat@gmail.com>
Date: Fri, 9 Oct 2026 20:41:53 +0700
Subject: [PATCH] Packaging: Windows MSI gets a setup wizard with version and
 launch box

Double-clicking the MSI used to flash a progress bar and close, so users couldn't tell it had
installed. It now opens a wizard: Welcome, install folder (remembered across upgrades), Ready,
progress, and a Finish page that says where to find the app with a ticked "Launch VectorCraft"
box. Every page names the full version, pre-release tag included. The wizard art is drawn from
the app icon at package time; msiexec /qn still installs silently.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/packaging-lint.yml    |  2 +-
 .github/workflows/release.yml           |  4 ++-
 .github/workflows/windows-arm64.yml     |  4 ++-
 docs/releasing.md                       |  7 ++++
 packaging/windows/package.ps1           | 43 +++++++++++++++++++++-
 packaging/windows/vectorcraft.en-us.wxl | 11 ++++++
 packaging/windows/vectorcraft.wxs       | 47 ++++++++++++++++++++++---
 7 files changed, 109 insertions(+), 9 deletions(-)
 create mode 100644 packaging/windows/vectorcraft.en-us.wxl

diff --git a/.github/workflows/packaging-lint.yml b/.github/workflows/packaging-lint.yml
index 23db4e93..7b5fa2c7 100644
--- a/.github/workflows/packaging-lint.yml
+++ b/.github/workflows/packaging-lint.yml
@@ -46,7 +46,7 @@ jobs:
           }
       - name: XML, desktop entry, AppStream, Flatpak manifest
         run: |
-          xmllint --noout packaging/windows/vectorcraft.wxs packaging/macos/*.plist* packaging/linux/*.xml*
+          xmllint --noout packaging/windows/vectorcraft.wxs packaging/windows/vectorcraft.en-us.wxl packaging/macos/*.plist* packaging/linux/*.xml*
           # Windows Installer needs Icon ids ending in .ico or .exe, or shortcuts show a blank icon.
           if grep -oE '<Icon Id="[^"]*"' packaging/windows/vectorcraft.wxs | grep -vE '\.(ico|exe)"$'; then
             echo "::error::Icon Id must end in .ico or .exe"; exit 1
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 3633d9a4..24a27ef8 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -148,7 +148,9 @@ jobs:
         run: cargo xtask version set "$VECTORCRAFT_VERSION"
       - name: Install WiX
         shell: pwsh
-        run: dotnet tool install --global wix --version 5.0.2
+        run: |
+          dotnet tool install --global wix --version 5.0.2
+          wix extension add -g WixToolset.UI.wixext/5.0.2 WixToolset.Util.wixext/5.0.2
       - name: Build, sign, package
         shell: pwsh
         env:
diff --git a/.github/workflows/windows-arm64.yml b/.github/workflows/windows-arm64.yml
index d1cb4c9c..c99b75fa 100644
--- a/.github/workflows/windows-arm64.yml
+++ b/.github/workflows/windows-arm64.yml
@@ -45,7 +45,9 @@ jobs:
           key: windows-arm64-package
       - name: Install WiX
         shell: pwsh
-        run: dotnet tool install --global wix --version 5.0.2
+        run: |
+          dotnet tool install --global wix --version 5.0.2
+          wix extension add -g WixToolset.UI.wixext/5.0.2 WixToolset.Util.wixext/5.0.2
       - name: Build and package (unsigned)
         shell: pwsh
         env:
diff --git a/docs/releasing.md b/docs/releasing.md
index 31e9579a..deeab197 100644
--- a/docs/releasing.md
+++ b/docs/releasing.md
@@ -99,6 +99,13 @@ to the target triple, so host build scripts aren't affected.
 - `vectorcraft.wxs` (WiX) is a per-machine install into Program Files with a Start Menu shortcut
   and an App Paths entry (Win+R `vectorcraft`). Same-version upgrades are allowed, so release
   candidates replace each other.
+- Double-clicking the MSI opens a setup wizard (WixUI_InstallDir without the licence page):
+  Welcome, install folder (remembered for upgrades in `HKLM\Software\VectorCraft\InstallDir`),
+  Ready, a progress page, and a Finish page that says where to find the app, with a ticked "Launch
+  VectorCraft" box. The pages name the full version (`vectorcraft.en-us.wxl`). `package.ps1` draws
+  the wizard's banner and side bitmaps from the app icon, so no WiX stock art ships. `msiexec /qn`
+  still installs silently. Building needs the WiX UI and Util extensions:
+  `wix extension add -g WixToolset.UI.wixext/5.0.2 WixToolset.Util.wixext/5.0.2`.
 - The ARM64 build is cross-compiled on the x64 runner. `.github/workflows/windows-arm64.yml`
   installs that MSI on a Windows 11 ARM64 runner, checks that both installed programs are ARM64,
   runs `vectorcraft-cli --version` natively and uninstalls.
diff --git a/packaging/windows/package.ps1 b/packaging/windows/package.ps1
index de574a43..96ed677e 100644
--- a/packaging/windows/package.ps1
+++ b/packaging/windows/package.ps1
@@ -13,6 +13,7 @@
 
   Needs: Rust (MSVC toolchain + the target), the Windows SDK (rc.exe, signtool.exe),
   and WiX v5: dotnet tool install --global wix --version 5.0.2
+             wix extension add -g WixToolset.UI.wixext/5.0.2 WixToolset.Util.wixext/5.0.2
 
 .EXAMPLE
   pwsh packaging/windows/package.ps1 -Arch x64
@@ -91,10 +92,50 @@ Copy-Item (Join-Path $Bin 'vectorcraft.exe'), (Join-Path $Bin 'vectorcraft-cli.e
 & (Join-Path $PSScriptRoot 'sign.ps1') (Join-Path $Stage 'vectorcraft.exe') (Join-Path $Stage 'vectorcraft-cli.exe')
 
 # ---- MSI ---------------------------------------------------------------------------------------
+# The setup wizard's art, drawn here from the app icon so the MSI shows VectorCraft rather than
+# WiX's stock bitmaps: a 493x58 banner across the top of the inner pages (the page title is drawn
+# over its left side, so that stays white) and a 493x312 backdrop for the Welcome and Finish pages
+# (their text sits on the right; the left 164 px are ours). Both must be 24-bit BMPs.
+function New-InstallerArt([string] $IconPng, [string] $BannerOut, [string] $DialogOut) {
+  Add-Type -AssemblyName System.Drawing
+  $paper = [System.Drawing.ColorTranslator]::FromHtml('#efe9dc')
+  $accent = [System.Drawing.ColorTranslator]::FromHtml('#e8573f')
+  $icon = [System.Drawing.Image]::FromFile($IconPng)
+  try {
+    foreach ($spec in @(@($BannerOut, 493, 58), @($DialogOut, 493, 312))) {
+      $bmp = New-Object System.Drawing.Bitmap $spec[1], $spec[2], ([System.Drawing.Imaging.PixelFormat]::Format24bppRgb)
+      $g = [System.Drawing.Graphics]::FromImage($bmp)
+      try {
+        $g.InterpolationMode = [System.Drawing.Drawing2D.InterpolationMode]::HighQualityBicubic
+        $g.SmoothingMode = [System.Drawing.Drawing2D.SmoothingMode]::AntiAlias
+        $g.Clear([System.Drawing.Color]::White)
+        if ($spec[2] -eq 58) {
+          $g.DrawImage($icon, 493 - 46 - 8, 6, 46, 46)
+        } else {
+          $panel = New-Object System.Drawing.SolidBrush $paper
+          $stripe = New-Object System.Drawing.SolidBrush $accent
+          $g.FillRectangle($panel, 0, 0, 164, 312)
+          $g.FillRectangle($stripe, 160, 0, 4, 312)
+          $g.DrawImage($icon, 18, 64, 124, 124)
+          $panel.Dispose(); $stripe.Dispose()
+        }
+      } finally { $g.Dispose() }
+      $bmp.Save($spec[0], [System.Drawing.Imaging.ImageFormat]::Bmp)
+      $bmp.Dispose()
+    }
+  } finally { $icon.Dispose() }
+}
+$Banner = Join-Path $Stage 'installer-banner.bmp'
+$Dialog = Join-Path $Stage 'installer-dialog.bmp'
+New-InstallerArt (Join-Path $Root 'assets\app-icon\hicolor\256x256\apps\ai.storyteller.vectorcraft.png') $Banner $Dialog
+
 $Msi = Join-Path $Dist "vectorcraft-$Version-windows-$Arch.msi"
 Invoke-Native 'wix build' {
   wix build (Join-Path $PSScriptRoot 'vectorcraft.wxs') -arch $Arch `
-    -d "Version=$MsiVersion" -d "BinDir=$Stage" -d "IconPath=$(Join-Path $Root 'assets\app-icon\vectorcraft.ico')" `
+    -ext WixToolset.UI.wixext -ext WixToolset.Util.wixext `
+    -culture en-US -loc (Join-Path $PSScriptRoot 'vectorcraft.en-us.wxl') `
+    -d "Version=$MsiVersion" -d "DisplayVersion=$Version" -d "BinDir=$Stage" -d "IconPath=$(Join-Path $Root 'assets\app-icon\vectorcraft.ico')" `
+    -d "BannerBmp=$Banner" -d "DialogBmp=$Dialog" `
     -o $Msi
 }
 # wix writes its debug symbols (.wixpdb) next to the MSI; keep them out of the release assets.
diff --git a/packaging/windows/vectorcraft.en-us.wxl b/packaging/windows/vectorcraft.en-us.wxl
new file mode 100644
index 00000000..c064e56d
--- /dev/null
+++ b/packaging/windows/vectorcraft.en-us.wxl
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Overrides for the setup wizard's WixUI strings, so its pages name the version being installed
+  ([VectorcraftVersion] is the full version, pre-release tag included, set in vectorcraft.wxs).
+-->
+<WixLocalization Culture="en-US" xmlns="http://wixtoolset.org/schemas/v4/wxl">
+  <String Id="WelcomeDlgTitle" Value="{\WixUI_Font_Bigger}Welcome to the [ProductName] [VectorcraftVersion] Setup Wizard" />
+  <String Id="WelcomeDlgDescription" Value="The Setup Wizard will install [ProductName] version [VectorcraftVersion] on your computer. Click Next to continue or Cancel to exit the Setup Wizard." />
+  <String Id="VerifyReadyDlgInstallTitle" Value="{\WixUI_Font_Title}Ready to install [ProductName] [VectorcraftVersion]" />
+  <String Id="ExitDialogTitle" Value="{\WixUI_Font_Bigger}Completed the [ProductName] [VectorcraftVersion] Setup Wizard" />
+</WixLocalization>
diff --git a/packaging/windows/vectorcraft.wxs b/packaging/windows/vectorcraft.wxs
index c09ec79f..338ee1f6 100644
--- a/packaging/windows/vectorcraft.wxs
+++ b/packaging/windows/vectorcraft.wxs
@@ -1,13 +1,19 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!--
-  VectorCraft MSI (WiX Toolset v5: `dotnet tool install -g wix`). Built by package.ps1:
+  VectorCraft MSI (WiX Toolset v5: `dotnet tool install -g wix`, plus the UI and Util extensions:
+  `wix extension add -g WixToolset.UI.wixext/5.0.2 WixToolset.Util.wixext/5.0.2`). Built by package.ps1:
 
-    wix build vectorcraft.wxs -arch x64 -d Version=1.2.3 -d BinDir=... -d IconPath=... -o out.msi
+    wix build vectorcraft.wxs -arch x64 -ext WixToolset.UI.wixext -ext WixToolset.Util.wixext
+      -culture en-US -loc vectorcraft.en-us.wxl -d Version=1.2.3 -d DisplayVersion=1.2.3-rc.1
+      -d BinDir=... -d IconPath=... -d BannerBmp=... -d DialogBmp=... -o out.msi
 
-  Per-machine install into Program Files, a Start Menu shortcut and an App Paths entry (so
-  `vectorcraft` starts from the Run dialog), plus vectorcraft-cli.
+  Per-machine install with a setup wizard that names the version: Welcome, install folder (Program Files\VectorCraft by
+  default, remembered for upgrades), Ready, a progress page, and a Finish page with a ticked
+  "Launch VectorCraft" box. Installs a Start Menu shortcut and an App Paths entry (so `vectorcraft`
+  starts from the Run dialog), plus vectorcraft-cli. `msiexec /qn` still installs silently.
 -->
-<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs">
+<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs"
+     xmlns:ui="http://wixtoolset.org/schemas/v4/wxs/ui">
   <Package
       Name="VectorCraft"
       Manufacturer="Learning Machines LLC"
@@ -34,9 +40,39 @@
     </StandardDirectory>
     <StandardDirectory Id="ProgramMenuFolder" />
 
+    <!-- An upgrade installs where the user put the previous version (written by VectorcraftApp). -->
+    <Property Id="INSTALLFOLDER">
+      <RegistrySearch Id="PreviousInstallFolder" Root="HKLM" Key="Software\VectorCraft" Name="InstallDir" Type="raw" />
+    </Property>
+
     <Feature Id="Main" Title="VectorCraft" Level="1">
       <ComponentGroupRef Id="VectorcraftFiles" />
     </Feature>
+
+    <!-- The setup wizard: WixUI_InstallDir without its licence page (the code is MIT OR
+         Apache-2.0; there is nothing to accept). A later NewDialog on the same button wins. -->
+    <ui:WixUI Id="WixUI_InstallDir" InstallDirectory="INSTALLFOLDER" />
+    <UI>
+      <Publish Dialog="WelcomeDlg" Control="Next" Event="NewDialog" Value="InstallDirDlg" Order="2" Condition="NOT Installed" />
+      <Publish Dialog="InstallDirDlg" Control="Back" Event="NewDialog" Value="WelcomeDlg" Order="2" />
+      <Publish Dialog="ExitDialog" Control="Finish" Event="DoAction" Value="LaunchVectorcraft"
+          Condition="WIXUI_EXITDIALOGOPTIONALCHECKBOX = 1 AND NOT Installed" />
+    </UI>
+    <!-- Our own art, generated by package.ps1 from the app icon (not WiX's stock bitmaps). -->
+    <WixVariable Id="WixUIBannerBmp" Value="$(var.BannerBmp)" />
+    <WixVariable Id="WixUIDialogBmp" Value="$(var.DialogBmp)" />
+
+    <!-- The full version (Version is numeric, so it drops a pre-release tag), shown on the wizard's
+         pages through vectorcraft.en-us.wxl. -->
+    <Property Id="VectorcraftVersion" Value="$(var.DisplayVersion)" />
+
+    <!-- Finish page: say where to find the app, and offer to start it (ticked by default). -->
+    <Property Id="WIXUI_EXITDIALOGOPTIONALTEXT" Value="VectorCraft $(var.DisplayVersion) is installed. You can start it any time from the Start menu." />
+    <Property Id="WIXUI_EXITDIALOGOPTIONALCHECKBOXTEXT" Value="Launch VectorCraft" />
+    <Property Id="WIXUI_EXITDIALOGOPTIONALCHECKBOX" Value="1" />
+    <Property Id="WixShellExecTarget" Value="[#VectorcraftExe]" />
+    <!-- Runs in the wizard's own (unelevated) process, so the app starts as the user, not as admin. -->
+    <CustomAction Id="LaunchVectorcraft" BinaryRef="Wix4UtilCA_$(sys.BUILDARCHSHORT)" DllEntry="WixShellExec" Impersonate="yes" Return="ignore" />
   </Package>
 
   <Fragment>
@@ -49,6 +85,7 @@
         </File>
 
         <RegistryValue Root="HKLM" Key="Software\Microsoft\Windows\CurrentVersion\App Paths\vectorcraft.exe" Value="[#VectorcraftExe]" Type="string" />
+        <RegistryValue Root="HKLM" Key="Software\VectorCraft" Name="InstallDir" Value="[INSTALLFOLDER]" Type="string" />
       </Component>
 
       <Component Id="VectorcraftCli">