Matrioska Setup (MSP)

A lightweight, web-rendered C++17 installer framework & template engine for Windows.

MSP bridges the visual flexibility of modern web design with the performance and predictability of low-level native systems engineering. It is a three-tier architecture designed to produce a single, self-contained, high-performance installer executable with zero external runtime dependencies.

---

Architectural Classification

MSP is not a black-box generator; it operates across three concrete engineering layers:

• Source-Level Template Framework: A modular, source-first scaffold where developers drop their application payload, define configuration parameters in installer.json, and customize the HTML5/CSS3 frontend without complex build tools.
• WebCore/D3D11 Setup Engine (msp-core.exe): A native installer runtime linking Ultralight directly against Direct3D 11. It mounts an in-memory Virtual FileSystem (MiniLoader) that intercepts WebKit requests and serves assets directly from RAM (.rdata), eliminating disk footprint during execution and delivering a 60 FPS interface.
• Static SFX Stub Wrapper (matrioshka): A compact Win32 loader compiled with the static C runtime (/MT). It packages the engine, dependencies, and payload into PE .rsrc sections, deploys an isolated environment in %TEMP%, synchronizes process execution, and wipes all traces upon termination.

---

Execution Lifecycle

1. Stub Wrapper (matrioshka/main.cpp): A minimal Win32 executable (/MT). At launch, it resolves the embedded archive in its .rsrc section (RCDATA 101), unpacks it to an isolated directory in %TEMP%, and executes msp-core.exe.
2. Core Engine (msp-core.exe): Creates an 800x470 borderless Win32 window backed by Ultralight and Direct3D 11. HTML, CSS, JavaScript, and images are compiled into COFF binary objects (.obj) and loaded directly from memory via MiniLoader.
3. Payload Extraction: Parses and decompresses the application payload (source/app.innern or source/app.zip) directly from memory using miniz, complete with Zip Slip path traversal mitigation.
4. Shell Integration: Registers Desktop and Start Menu shortcuts via native COM interfaces (IShellLinkW, IPersistFile) and launches the application upon completion.
5. Deterministic Cleanup: The stub process waits for msp-core.exe to exit, executes a retry loop with exponential backoff to handle transient AV file locks, wipes the temporary directory, and exits cleanly.

---

Requirements

• Windows 10 / 11 (x64 or x86)
• Microsoft Visual Studio (2019, 2022, or Build Tools) with C++ desktop workload (cl.exe, rc.exe)
• PowerShell 5.1+

---

Building

Run build.bat from a Developer Command Prompt or standard console (auto-detects vcvars):

:: Build 64-bit release binary (default)
build.bat x64

:: Build 32-bit release binary
build.bat x86

:: Build and run immediately for testing
run.bat

The standalone output executable is generated at:

bin\matrioska-setup.exe

Intermediate compilation objects (.obj) are stored in OOTemp\, while compiled asset objects are placed in core\gen\.

---

Configuration (installer.json)

Metadata and default paths are configured in installer.json:

{
  "title": "My Application",
  "desc": "Application setup wizard",
  "internal_name": "MyApp",
  "path": "C:\\Program Files\\MyApp",
  "version": "1.0.0",
  "publisher": "My Company",
  "url": "https://example.com",
  "executable": "app.exe",
  "license": "lib/docs/license",
  "readme": "lib/docs/readme"
}

Packaging the Application Payload

Place your compressed payload archive in:

• source/app.innern (recommended) or source/app.zip

The build pipeline automatically packages and embeds this archive into the executable's resources.

---

Project Structure

├── bin/                    # Final executable and matrioshka bundle
├── core/                   # Runtime engine (Win32, Ultralight, miniz)
│   ├── config.cpp / .h     # JSON parser and config loader
│   ├── inner.cpp / .h      # In-memory miniz payload decompression
│   ├── objconverter.c      # Binary-to-C asset compilation tool
│   ├── objcreator.bat      # Asset conversion script
│   ├── gen/                # Generated C source and object files for assets
│   ├── web/                # Ultralight window, runner, and IPC bridge
│   └── windows/            # Win32 dialogs, shortcuts, and shell integration
├── matrioshka/             # Win32 stub wrapper (extract, supervise, cleanup)
├── lib/
│   ├── docs/               # License and readme text files
│   └── html/               # UI interface (HTML, CSS, JS, images)
├── libs/win/               # Ultralight SDK libraries (x64 and x86)
├── includes/               # Headers and miniz source
├── OOTemp/                 # Intermediate compiler object files (.obj)
├── build.bat               # Release build pipeline
├── installer.json          # Application configuration
└── run.bat                 # Build and test runner

---

Documentation

Detailed architectural documentation is available in docs/:

• Core Architecture Overview
• Matrioshka Stub Module
• Payload Extraction & Security
• Core Runtime & Ultralight
• MiniLoader Virtual FileSystem
• Win32 Window Management
• Windows Shell & COM Integration
• Frontend UI & State Machine
• IPC Message Bridge
• Config Engine
• Build Pipeline Reference

---

License

MIT License. See LICENSE for details and third-party notices.