4.2 KiB
Agent Note: Native Windows installer pages
Status: implemented
English | 中文
Problem
The Windows installation interface needs branded light and dark pages without introducing another application runtime or replacing the release mechanisms that extract, register, upgrade, and uninstall Desktop.
Decision
The installer adds custom welcome, progress, and completion pages through electron-builder's NSIS include. The stock script remains responsible for installation and uninstaller generation. A custom full script bypasses electron-builder's separate uninstaller signing path and is therefore unsuitable for this interface change. The Desktop release decision continues to own release identity, update distribution, and signing requirements.
NSIS native controls preserve directory editing, folder selection, checkbox state, and keyboard interaction. An x86 Win32/GDI+ helper retains DWM shadows and draws installation progress on the UI thread while the stock installation worker runs. Stock page visibility is suppressed even when NSIS shows the page after MUI's callback. Windows 11 supplies the outer corner radius; Windows 10 retains its supported frame appearance.
Installation is per-user. Welcome-page leave validation reads the current edit control for mouse and keyboard navigation; the debounced inline hint is not an installation authority. Running-process checks match the affected executable path, leaving other installations independent. Completion-page leave honors the launch checkbox for both mouse and keyboard navigation. Electron-builder resolves the registered directory before custom initialization, so silent updates without /D= retain that directory. The installation engine does not add transactional rollback or take ownership of first-launch profile preparation.
Alternatives considered
An Electron installer interface adds a runtime before the application exists and requires a separate installation bridge. Native controls provide the required interaction within the existing installer.
Replacing the full NSIS script with the lightweight prototype also replaces upgrade, registry, uninstaller, and signing behavior. The prototype's transaction mechanism requires separate release qualification and is excluded from the UI integration.
A window region for rounded corners disables the DWM frame shadow. The system frame preserves the shadow while accepting the platform's corner radius.
Consequences
Windows packaging additionally requires the x86 Visual C++ compiler and Windows SDK. The helper is signed by the same signer as other Windows artifacts. The preparation hook returns true on every platform: electron-builder treats a falsy return as external dependency ownership and omits its production node_modules collection. The pinned app-builder-lib patch adds three optional extraction/copy notifications while preserving the stock worker. Stage callbacks preserve NSIS registers, stack, and error flags. The helper ignores the reused internal progress control, starts at zero, and bounds a monotonic time estimate within each real worker stage. Temporary-file cleanup receives its own progress interval; no timer marks installation complete. The frame stays hidden until branded controls are ready and is initialized once; page transitions preserve its position. Finish hides the window before creating the installed process directly under the current user. An explicitly elevated installer retains shell-mediated launch. Launch failure restores the finish page. Application startup time is independent of installer dismissal.
The native installer regression uses a unique product identity and private installation directory to verify path rejection, folder selection, launch choices, upgrade, running-process preservation, hidden stock progress, first-show readiness, and uninstall. A deterministic native progress test covers slow copy, cleanup, and stale stage notifications. Its screenshots and expected behavior belong to Desktop tests rather than recorded Session snapshots. Signed release qualification still requires the configured certificate and token, and actual Windows update artifacts.