# @bobfrankston/msger
Fast, lightweight, cross-platform message box implementation using Rust + wry.
This is a native implementation alternative to `@bobfrankston/msgview` (Electron-based) with:
- **10-20x faster startup** (~50-200ms vs ~2-3s)
- **50x smaller binary** (~2-5MB vs ~100MB)
- **5x less memory** (~20-50MB vs ~100-200MB)
- **Cross-platform**: Windows (WebView2), macOS (WebKit), Linux (WebKitGTK)
## Architecture
```
Node.js (msgview CLI)
↓ spawns with JSON input via stdin OR JSON file + CLI args
Rust msger executable
↓ creates native window with webview
↓ displays HTML message with buttons
↓ handles user interaction
↓ outputs JSON result to stdout
Node.js reads and returns result
```
## Usage Modes
### 1. Stdin (Original)
```bash
echo '{"message":"Hello"}' | msgernative
```
### 2. JSON File
```bash
msgernative config.json
# or
msgernative -json config.json
```
### 3. JSON File + CLI Overrides
```bash
msgernative config.json --title "New Title" --width 800
```
### 4. Pure CLI (No JSON)
```bash
msgernative --message "Hello World" --buttons "OK,Cancel"
```
## API Compatibility
This implementation is 100% compatible with `@bobfrankston/msgview` API:
### MessageBoxOptions (Complete Structure)
```json
{
"title": "Window Title",
"message": "Plain text message",
"html": "Optional HTML content
",
"url": "https://example.com",
"width": 600,
"height": 400,
"pos": {
"x": 100,
"y": 100,
"screen": 0
},
"buttons": ["Cancel", "OK"],
"defaultValue": "default input",
"inputPlaceholder": "Enter text...",
"allowInput": false,
"timeout": 30,
"autoSize": false,
"alwaysOnTop": false,
"fullscreen": false,
"zoomPercent": 100,
"debug": false,
"icon": "path/to/icon.png",
"dev": false
}
```
### Command-Line Arguments
All JSON options can be overridden via command-line:
```
OPTIONS:
-j, --json JSON file to load defaults from
--title Window title
--message <MESSAGE> Plain text message
--html <HTML> HTML content
--url <URL> URL to load
--width <WIDTH> Window width
--height <HEIGHT> Window height
--x <X> Window X position
--y <Y> Window Y position
--screen <SCREEN> Screen number (multi-monitor)
--buttons <BUTTONS>... Button labels (comma-separated)
--default-value <VALUE> Default input value
--input-placeholder <TEXT> Input placeholder
--allow-input Allow text input
--timeout <SECONDS> Auto-close timeout
--auto-size Auto-size window to content
--always-on-top Keep window on top
--fullscreen Start in fullscreen
--zoom-percent <PERCENT> Zoom level
--debug Enable debug mode
--icon <PATH> Window icon path
--dev Enable developer mode
```
### MessageBoxResult (output to stdout)
```json
{
"button": "OK",
"value": "user input text",
"closed": true,
"dismissed": false
}
```
## Building
### Prerequisites
- **Rust** (install from https://rustup.rs/)
- **Windows**: Visual Studio Build Tools with C++ development tools
- **macOS**: Xcode Command Line Tools
- **Linux**: WebKitGTK development packages
### Simple Build (Recommended)
The project includes a build script that handles the compilation:
```bash
npm run build
```
This will:
1. Build the Rust binary in release mode
2. Copy it to `./bin/` for easy access
3. Show the binary size
The build script automatically uses cargo, which will find the Visual Studio linker on Windows.
### Manual Build
If you prefer to build manually:
```bash
# Debug build (faster compile, larger binary)
cargo build
# Release build (optimized, smaller binary)
cargo build --release
```
**Note**: If you encounter linker errors on Windows, make sure Visual Studio Build Tools with C++ workload is installed.
### Cross-Platform Builds
```bash
# Windows
cargo build --release --target x86_64-pc-windows-msvc
# Linux (from Linux or WSL)
cargo build --release --target x86_64-unknown-linux-gnu
# macOS (requires macOS or CI)
cargo build --release --target x86_64-apple-darwin
cargo build --release --target aarch64-apple-darwin # Apple Silicon
```
## Testing
### Standalone Test
```bash
echo '{"message":"Hello from Rust!","buttons":["Cancel","OK"]}' | ./target/release/msger
```
### With Input Field
```bash
echo '{"message":"Enter your name:","allowInput":true,"defaultValue":"John","buttons":["Cancel","Submit"]}' | ./target/release/msger
```
### With HTML Content
```bash
echo '{"title":"Rich Content","html":"<h2>Welcome</h2><p>This is <strong>HTML</strong> content</p>","buttons":["Close"]}' | ./target/release/msger
```
## Integration with Node.js
The msgview npm package will detect and use the Rust binary if available:
```javascript
import { spawn } from 'child_process';
import { existsSync } from 'fs';
const nativeBinary = './native/msger.exe';
if (existsSync(nativeBinary)) {
// Use fast Rust version
const child = spawn(nativeBinary);
child.stdin.write(JSON.stringify(options));
child.stdin.end();
child.stdout.on('data', (data) => {
const result = JSON.parse(data.toString());
console.log('Result:', result);
});
} else {
// Fallback to Electron version
// ... existing msgview code
}
```
## Features
- ✅ Cross-platform native webview
- ✅ Full HTML/CSS support
- ✅ URL loading support
- ✅ Customizable buttons
- ✅ Input field support
- ✅ Keyboard shortcuts (Enter, Escape, F11)
- ✅ Window close detection
- ✅ JSON stdin/stdout communication
- ✅ JSON file configuration support
- ✅ Command-line argument overrides
- ✅ Multi-monitor positioning
- ✅ Window icon support
- ✅ Auto-size and fullscreen modes
- ✅ Timeout support
- ✅ System menu integration (Windows)
- About dialog showing window info
- Position, size, DPI scaling details
- ✅ Small binary size (~2-5MB)
- ✅ Fast startup (~50-200ms)
## Performance Comparison
| | **Electron (msgview)** | **Rust (msger)** | **Improvement** |
|---|---|---|---|
| **Binary Size** | ~100MB | ~2-5MB | **50x smaller** |
| **Startup Time** | ~2-3 seconds | ~50-200ms | **10-20x faster** |
| **Memory Usage** | ~100-200MB | ~20-50MB | **5x less** |
| **Cross-Platform** | ✅ Win/Mac/Linux | ✅ Win/Mac/Linux | Same |
| **Full HTML/CSS** | ✅ Chromium | ✅ WebView2/WebKit | Same |
## Dependencies
- **wry** (0.47): Cross-platform webview library
- **tao** (0.30): Cross-platform windowing
- **serde** / **serde_json** (1.0): JSON serialization
## License
ISC
## Author
Bob Frankston