# msger JavaScript API - Current State (v0.1.74)

## Summary

**The msger JavaScript API is intentionally minimal.** The real value of msger is the CLI tool itself, not a JavaScript library.

## Current API (v0.1.74)

```javascript
// Only one function:
msger.isAvailable()  // Returns true if running in msger environment
```

**That's it!** Everything else uses native browser APIs.

## Recommended: Use Native Browser APIs

```javascript
// Storage - use native localStorage
localStorage.setItem('key', JSON.stringify(value));
const value = JSON.parse(localStorage.getItem('key'));

// Close window - use native API
window.close();

// File input - use native HTML
<input type="file" onchange="handleFiles(this.files)">
```

**Why native APIs?**
- Works in any browser context, not just msger
- No dependency on msger-specific code
- Your app is portable
- Standard, well-documented APIs

## What msger Actually Provides

**msger = Fast CLI wrapper for native windows + HTML + button results**

1. **Create native OS window** (~50-200ms startup)
2. **Display HTML/URL content** (uses OS webview)
3. **Return button/input results** to parent process (template mode only)
4. **Configure everything at launch** via CLI flags

### Example Usage

```bash
# Simple dialog
msger -message "Save changes?" -buttons Yes No Cancel
# Returns: {"button": "Yes"}

# HTML with input
msger -html "<h1>Enter Name</h1><input id='name'>" -buttons OK
# Returns: {"button": "OK", "value": "John"}

# URL viewer
msger -url "https://example.com" -size 1024,768
```

## Future File/Window APIs (Not Yet Implemented)

When you have time for debugging, these will be added:

### File System API
```javascript
// File dialogs (always safe)
await msger.selectFile()
await msger.selectFiles()
await msger.saveFileAs(content, name)
await msger.selectFolder()

// Direct path access (requires --allowFs flag)
await msger.fs.read(path)
await msger.fs.write(path, content)
await msger.fs.list(path)
await msger.fs.exists(path)
```

### Window Manipulation API
```javascript
// Runtime window control (template mode only)
await msger.setSize(width, height)
await msger.setPosition(x, y)
await msger.setTitle(title)
await msger.setAlwaysOnTop(enabled)
```

**Why not implemented yet?**
- Requires bidirectional IPC pattern
- Needs debugging time
- Works only in template mode (URL mode IPC crashes)

See SESSION-NOTES.md for implementation approach.

## Platform App Development

**Current approach (without file API):**
- Use native `<input type="file">` for file selection (gets file content, not path)
- Use localStorage for persistence
- Configure window at startup via CLI flags
- Use template mode for button/input collection

**Future approach (with file API):**
- Native file dialogs for file selection (gets actual paths)
- Direct file read/write/list operations (with --allowFs flag)
- Runtime window manipulation
- Full platform app capabilities

## Technical Details

### IPC Status
- ✅ **Template mode** (`-message`, `-html`, `-htmlfrom`): IPC works perfectly
- ❌ **URL mode** (`-url`): IPC crashes (wry 0.47.2 bug)

### What Works Where

| Feature | Template Mode | URL Mode |
|---------|---------------|----------|
| Native localStorage | ✅ | ✅ |
| Native window.close() | ✅ | ✅ |
| Button results via IPC | ✅ | ❌ (crashes) |
| Future file API | ✅ (when implemented) | ❌ (IPC broken) |
| Future window API | ✅ (when implemented) | ❌ (IPC broken) |

### Storage Location
- Windows: `%LOCALAPPDATA%\msger\webview2\`
- Each app gets isolated storage
- Each URL origin gets its own partition

## Comparison to Electron

| Feature | msger | Electron |
|---------|-------|----------|
| Startup time | ~50-200ms | ~2-3s |
| Binary size | ~2-5MB | ~100MB |
| Memory usage | ~20-50MB | ~100-200MB |
| HTML/CSS support | ✅ (OS webview) | ✅ (Chromium) |
| JavaScript API | Minimal (by design) | Rich |
| File system access | Future (dialog + path) | Full |
| Cross-platform | Win/Linux/Pi | Win/Mac/Linux |

## Philosophy

**msger is a CLI tool, not a framework.**

- Minimal JavaScript API by design
- Prefer native browser APIs
- Fast, lightweight, simple
- Configure via CLI, not runtime APIs
- Perfect for dialogs, notifications, simple HTML displays
- Future: Full platform app support with file/window APIs

Use Electron/Tauri if you need:
- Rich JavaScript APIs out of the box
- Complex desktop app features
- Native menus, system tray, etc.

Use msger if you want:
- Fast startup and low memory
- Simple HTML display with button results
- Minimal dependencies
- Platform apps (future, with file API)
