@bobfrankston/msger 0.1.74 → 0.1.76

package/KNOWN-BUGS.md

@@ -0,0 +1,121 @@
+# Known Bugs and Limitations
+
+## Critical: Window Manipulation via IPC Crashes (wry 0.47.2 Bug)
+
+**Status:** UNFIXED - Library Bug
+**Severity:** Critical
+**Affected Version:** msger using wry 0.47.2
+
+### Description
+
+All window manipulation functions called via JavaScript IPC cause immediate crashes with the following error:
+
+```
+thread 'main' panicked at wry-0.47.2\src\webview2\mod.rs:812:58:
+called `Result::unwrap()` on an `Err` value: http::Error(InvalidUri(InvalidFormat))
+```
+
+### Affected Functions
+
+The following `window.msger` API functions are **DISABLED** to prevent crashes:
+
+- ❌ `msger.toggleFullscreen()` - Crashes
+- ❌ `msger.setFullscreen(enabled)` - Crashes
+- ❌ `msger.minimize()` - Crashes
+- ❌ `msger.maximize()` - Crashes
+- ❌ `msger.setSize(width, height)` - Crashes
+- ❌ `msger.setPosition(x, y)` - Crashes
+- ❌ `msger.setAlwaysOnTop(enabled)` - Crashes
+- ❌ `msger.setTitle(title)` - Crashes
+- ❌ `msger.close(result)` - Crashes (ALL IPC is broken!)
+
+### Working Functions
+
+These functions still work because they don't use IPC:
+
+- ✅ `msger.saveData(key, value)` - Uses localStorage only
+- ✅ `msger.loadData(key, defaultValue)` - Uses localStorage only
+- ✅ `msger.removeData(key)` - Uses localStorage only
+- ✅ `msger.clearData()` - Uses localStorage only
+- ✅ `msger.isAvailable()` - Pure JavaScript check
+- ✅ `msger.testHello()` - Pure JavaScript test
+
+**Note:** Data saved with `saveData()` **persists across restarts** because it uses localStorage!
+
+### Workarounds
+
+#### Window Manipulation
+Use **CLI arguments** when launching msger instead of JavaScript API:
+
+```bash
+# Fullscreen
+node cli.js -url page.html -fullscreen
+
+# Window size
+node cli.js -url page.html -size 1024,768
+
+# Window position
+node cli.js -url page.html -pos 100,100
+
+# Always on top
+node cli.js -url page.html -alwaysOnTop
+
+# Window title
+node cli.js -url page.html -title "My App"
+```
+
+#### Fullscreen Toggle
+Use the **F11 keyboard shortcut** instead of JavaScript:
+- Press F11 to enter fullscreen
+- Press F11 again or Esc to exit fullscreen
+
+This works because F11 is handled at the native window level, not through IPC.
+
+### Technical Details
+
+**Root Cause:**
+The wry 0.47.2 library has a bug where window manipulation operations trigger an internal code path that tries to parse something as an HTTP URI. When this parse fails, it panics in FFI (Foreign Function Interface) code that cannot unwind, causing an immediate abort.
+
+**Why catch_unwind Doesn't Work:**
+The panic occurs in `extern "C"` function boundaries (FFI with WebView2 COM interface), which cannot be unwound across. The `std::panic::catch_unwind` wrapper we added catches Rust panics, but not panics in FFI code marked as "cannot unwind".
+
+**Crash Location:**
+`C:\Users\Bob\.cargo\registry\src\index.crates.io-1949cf8c6b5b557f\wry-0.47.2\src\webview2\mod.rs:812:58`
+
+### Potential Solutions
+
+1. **Update wry** - Check if newer versions (0.48+) have fixed this issue
+2. **Use tauri** - Switch to the full Tauri framework which may have better WebView2 integration
+3. **Alternative WebView** - Consider using a different WebView library
+4. **Native UI** - Build a native UI instead of HTML/JavaScript for window controls
+
+### Testing
+
+Use the provided test page to verify which functions work:
+
+```bash
+node cli.js -url test-msger-functions.html -size 800,900
+```
+
+All disabled functions will:
+- Return `false`
+- Log an error message to the console
+- NOT crash the application
+
+## Other Known Issues
+
+### F11 Key Sometimes Ignored
+
+**Status:** Under Investigation
+**Severity:** Medium
+
+F11 keyboard shortcut for fullscreen may be captured by WebView2 before reaching the window event handler.
+
+**Workaround:** Launch with `-fullscreen` flag to start in fullscreen mode.
+
+---
+
+**Last Updated:** 2025-11-05
+**msger Version:** 0.1.57
+**wry Version:** 0.47.2
+**tao Version:** 0.30

package/MSGER-API-SUMMARY.md

@@ -0,0 +1,162 @@
+# 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)

package/MSGER-API.md

@@ -0,0 +1,376 @@
+# msger JavaScript API
+
+The **msger** JavaScript API provides window control, data persistence, and file system access for applications running inside msger.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Window Control](#window-control)
+- [Data Persistence](#data-persistence)
+- [File System Access](#file-system-access)
+- [Browser Compatibility](#browser-compatibility)
+
+## Installation
+
+### TypeScript Definitions
+
+```bash
+npm install @bobfrankston/msgerdefs
+```
+
+```typescript
+import type { MsgerAPI } from '@bobfrankston/msgerdefs';
+import { isMsger, getMsgerAPI } from '@bobfrankston/msgerdefs';
+```
+
+## Window Control
+
+Control the msger window from JavaScript.
+
+### toggleFullscreen()
+
+Toggle fullscreen mode on/off.
+
+```javascript
+msger.toggleFullscreen();
+```
+
+**Keyboard Shortcuts:**
+- F11: Toggle fullscreen (native window level)
+- Esc: Exit fullscreen or dismiss window
+
+### setFullscreen(enabled)
+
+Set fullscreen state explicitly.
+
+```javascript
+msger.setFullscreen(true);   // Enter fullscreen
+msger.setFullscreen(false);  // Exit fullscreen
+```
+
+### minimize()
+
+Minimize the window to taskbar.
+
+```javascript
+msger.minimize();
+```
+
+### maximize()
+
+Toggle between maximized and restored window state.
+
+```javascript
+msger.maximize();  // Maximize or restore
+```
+
+### setSize(width, height)
+
+Set window dimensions in pixels.
+
+```javascript
+msger.setSize(800, 600);
+msger.setSize(1920, 1080);
+```
+
+### setPosition(x, y)
+
+Move window to specific screen coordinates.
+
+```javascript
+msger.setPosition(100, 100);  // Top-left corner
+msger.setPosition(0, 0);      // Screen origin
+```
+
+### setAlwaysOnTop(enabled)
+
+Keep window above other windows.
+
+```javascript
+msger.setAlwaysOnTop(true);   // Stay on top
+msger.setAlwaysOnTop(false);  // Normal behavior
+```
+
+### setTitle(title)
+
+Change window title.
+
+```javascript
+msger.setTitle('My Application');
+msger.setTitle(`Status: ${status}`);
+```
+
+### close(result?)
+
+Close the window with optional result data.
+
+```javascript
+// Close with default dismissed result
+msger.close();
+
+// Close with custom result
+msger.close({
+    button: 'OK',
+    value: 'user input',
+    form: { name: 'Bob', email: 'bob@example.com' }
+});
+```
+
+## Data Persistence
+
+Save and load data using localStorage (with `msger_` prefix).
+
+### saveData(key, value)
+
+Store data persistently. Value is automatically JSON.stringify'd.
+
+```javascript
+// Save simple values
+msger.saveData('username', 'bob');
+msger.saveData('count', 42);
+
+// Save objects
+msger.saveData('userPrefs', {
+    theme: 'dark',
+    fontSize: 14,
+    notifications: true
+});
+
+// Save arrays
+msger.saveData('recentFiles', ['/path/to/file1.txt', '/path/to/file2.txt']);
+```
+
+**Returns:** `true` on success, `false` on failure
+
+### loadData(key, defaultValue?)
+
+Load data from storage with optional default.
+
+```javascript
+// Load with default
+const username = msger.loadData('username', 'guest');
+const prefs = msger.loadData('userPrefs', {theme: 'light'});
+
+// Load without default (returns undefined if not found)
+const data = msger.loadData('optionalData');
+```
+
+**Returns:** Stored value (parsed from JSON) or `defaultValue`
+
+### removeData(key)
+
+Delete a specific key from storage.
+
+```javascript
+msger.removeData('tempData');
+msger.removeData('oldSettings');
+```
+
+**Returns:** `true` on success, `false` on failure
+
+### clearData()
+
+Clear all msger-prefixed data from localStorage.
+
+```javascript
+msger.clearData();  // Removes all msger_* keys
+```
+
+**Returns:** `true` on success, `false` on failure
+
+**Note:** Only removes keys with `msger_` prefix, preserving other localStorage data.
+
+## File System Access
+
+**Status:** Coming soon
+
+### File Dialogs (Safe - Always Available)
+
+```javascript
+// Select single file
+const file = await msger.fs.selectFile({
+    title: 'Open File',
+    filters: [{name: 'Text', extensions: ['txt', 'md']}]
+});
+if (file) {
+    console.log(file.name, file.path, file.content);
+}
+
+// Select multiple files
+const files = await msger.fs.selectFiles({
+    title: 'Open Files'
+});
+
+// Save file dialog
+const path = await msger.fs.saveFileAs(
+    'File content here',
+    'default.txt',
+    {filters: [{name: 'Text', extensions: ['txt']}]}
+);
+
+// Select folder
+const folder = await msger.fs.selectFolder({
+    title: 'Select Output Folder'
+});
+```
+
+### Direct File Access (Requires `allowFs: true`)
+
+```javascript
+// Read file
+const content = await msger.fs.read('/path/to/file.txt');
+
+// Write file
+await msger.fs.write('/path/to/file.txt', 'Hello World');
+
+// List directory
+const files = await msger.fs.list('/path/to/dir');
+files.forEach(file => {
+    console.log(file.name, file.isDir, file.size);
+});
+
+// Check existence
+const exists = await msger.fs.exists('/path/to/file.txt');
+
+// Delete file
+await msger.fs.delete('/path/to/file.txt');
+```
+
+**Note:** Direct file access requires launching msger with `--allowFs` flag for security.
+
+## Browser Compatibility
+
+Use `getMsgerAPI()` for cross-platform code that works in both msger and browsers:
+
+```typescript
+import { getMsgerAPI, isMsger } from '@bobfrankston/msgerdefs';
+
+const msger = getMsgerAPI();
+
+// Data persistence works in both!
+msger.saveData('userPrefs', {theme: 'dark'});
+const prefs = msger.loadData('userPrefs', {theme: 'light'});
+
+// Window control - only works in msger (no-op in browser)
+if (isMsger()) {
+    msger.setTitle('My App');
+    msger.toggleFullscreen();
+}
+
+// File system - only available in msger
+if (msger.fs) {
+    const file = await msger.fs.selectFile();
+}
+```
+
+### Browser Behavior
+
+| Feature | msger | Browser |
+|---------|-------|---------|
+| Data persistence | localStorage with `msger_` prefix | localStorage with `msger_` prefix |
+| Window control | Full support | No-op (except `setTitle` → `document.title`) |
+| File system | Full support (with `allowFs` flag) | Not available (`fs` is `undefined`) |
+
+### Detection
+
+```javascript
+import { isMsger } from '@bobfrankston/msgerdefs';
+
+if (isMsger()) {
+    console.log('Running in msger!');
+    // Use msger-specific features
+} else {
+    console.log('Running in browser');
+    // Use browser fallbacks
+}
+```
+
+## Examples
+
+### Persistent Settings
+
+```javascript
+// Save user preferences
+function saveSettings(settings) {
+    msger.saveData('settings', settings);
+}
+
+// Load with defaults
+function loadSettings() {
+    return msger.loadData('settings', {
+        theme: 'light',
+        fontSize: 14,
+        autoSave: true
+    });
+}
+
+// Apply settings on startup
+const settings = loadSettings();
+if (settings.theme === 'dark') {
+    document.body.classList.add('dark-theme');
+}
+```
+
+### Fullscreen Presentation Mode
+
+```javascript
+function enterPresentationMode() {
+    msger.setFullscreen(true);
+    msger.setAlwaysOnTop(true);
+    msger.saveData('wasPresenting', true);
+}
+
+function exitPresentationMode() {
+    msger.setFullscreen(false);
+    msger.setAlwaysOnTop(false);
+    msger.removeData('wasPresenting');
+}
+
+// Restore presentation mode on reload
+if (msger.loadData('wasPresenting', false)) {
+    enterPresentationMode();
+}
+```
+
+### Window Size Presets
+
+```javascript
+const windowSizes = {
+    small: [600, 400],
+    medium: [800, 600],
+    large: [1200, 800],
+    hd: [1920, 1080]
+};
+
+function setWindowSize(preset) {
+    const [width, height] = windowSizes[preset];
+    msger.setSize(width, height);
+    msger.saveData('windowSize', preset);
+}
+
+// Restore last size on startup
+const lastSize = msger.loadData('windowSize', 'medium');
+setWindowSize(lastSize);
+```
+
+## Command Line Integration
+
+```bash
+# Launch with fullscreen
+msger -url "file:///app/index.html" --fullscreen
+
+# Launch with specific size and position
+msger -url "https://example.com" -size 1024,768 -pos 100,100
+
+# Launch always on top
+msger -url "file:///app/monitor.html" --ontop --detach
+
+# Launch with file system access (future)
+msger -url "file:///app/editor.html" --allowFs
+```
+
+## See Also
+
+- [README.md](README.md) - Main msger documentation
+- [msgerdefs](msgerdefs/) - TypeScript definitions package
+- [FULLSCREEN-FEATURE.md](FULLSCREEN-FEATURE.md) - Fullscreen implementation details