@bobfrankston/msgapidefs 0.1.29 → 0.1.31

package/README.md

@@ -1,6 +1,24 @@
 # @bobfrankston/msgapidefs
 
-TypeScript definitions for the **msgapi** JavaScript API used in msgview and msger.
+> **⚠️ SECURITY:** msgapi gives full native OS access (filesystem, processes, networking). Intended ONLY for trusted apps — native apps written as web pages. Do not expose to untrusted content.
+
+> **⚠️ EXPERIMENTAL:** APIs are experimental and subject to change.
+
+TypeScript definitions for the **msgapi** JavaScript API used by msga, msger, and msgview. See the Typescript definitions in
+[msgapidefs.ts](msgapidefs.ts) for more info
+
+## Workspace Structure
+
+```
+msgx (workspace root)
+├── msgapidefs    - TypeScript type definitions for window.msgapi (this package)
+├── msgcommon     - Shared CLI parsing, templates, pinning utilities
+├── msger         - Rust/wry webview host (Windows, Linux)
+├── msgview       - Electron webview host (Windows, Linux, Mac, Pi)
+├── msga          - .NET MAUI webview host (Android, Windows)
+├── build         - Release build orchestration script (build/build.ts)
+└── md            - Shared documentation
+```
 
 ## Installation
 
@@ -34,8 +52,94 @@ localStorage.setItem('key', 'value');  // Instead of msgapi.saveData()
 window.close();  // Instead of msgapi.close() if not passing result
 ```
 
+## Platform Support
+
+✅ = Current | 🔧 = Possible (recompile/rebuild needed) | ❌ = Not feasible
+
+| Platform | msger (Rust/wry) | msgview (Electron) | msga (.NET MAUI) |
+|----------|:----------------:|:------------------:|:----------------:|
+| **Windows** | ✅ | ✅ | ✅ |
+| **Linux** | ✅ | ✅ | ❌ |
+| **macOS** | 🔧 wry supports it | ✅ | 🔧 Mac Catalyst |
+| **Raspberry Pi** | ⚠️ runs but no display | ✅ | ❌ |
+| **Android** | ❌ | ❌ | ✅ (primary) |
+| **iOS** | ❌ | ❌ | ❌ |
+
+> **msger** uses wry (Rust webview). Desktop platforms (Win/Linux/Mac) are mature. msger can cross-compile and run on the Pi but does not display properly (wry/GTK rendering issues) — not a priority to fix.
+> **msgview** runs wherever Electron does — desktop only, no mobile.
+> **msga** targets Android primarily; Windows for dev/testing. **iOS** would be the most realistic path — MAUI supports iOS natively, so msga could target it with an iOS build profile, Apple developer account, and platform-specific conditional code (`#if IOS`) for permissions and APIs. No current plans.
+
+## Implementation Status
+
+✅ = Implemented | ⚠️ = Partial | ❌ = Not implemented
+
+| API | msgview | msger | msga | Notes |
+|-----|:-------:|:-----:|:----:|-------|
+| **Configuration** | | | | |
+| `version` | ❌ | ❌ | ✅ | `window.msgapi.version` string |
+| `setLogging(value?)` | ❌ | ❌ | ✅ | Returns previous state |
+| `setAutoUpdate(value?)` | ❌ | ❌ | ✅ | `'auto'`/`'check'`/`'off'`; msga Android only |
+| **Window Control** | | | | **`window.msgapi.*`** |
+| `toggleFullscreen()` | ❌ | ✅ | ✅ | msger: via `window.msgapi` (msger-api.js) |
+| `setFullscreen(bool)` | ✅ | ✅ | ✅ | |
+| `minimize()` | ✅ | ✅ | ✅ | msga: Windows only |
+| `maximize()` | ✅ | ✅ | ✅ | msga: Windows only |
+| `setSize(w, h)` | ✅ | ✅ | ✅ | msga: Windows only |
+| `setPosition(x, y)` | ✅ | ✅ | ✅ | msga: Windows only |
+| `setAlwaysOnTop(bool)` | ✅ | ✅ | ❌ | |
+| `close(result?)` | ✅ | ✅ | ✅ | |
+| `navigate(url)` | ❌ | ❌ | ✅ | msga only |
+| `reload()` | ❌ | ❌ | ✅ | msga only |
+| **File System** | | | | **`window.msgapi.fs.*`** |
+| `fs.selectFile()` | ❌ | ❌ | ✅ | msga: full JS bridge wired |
+| `fs.selectFiles()` | ❌ | ❌ | ✅ | msga: full JS bridge wired |
+| `fs.saveFileAs()` | ❌ | ❌ | ✅ | msga: Windows only |
+| `fs.selectFolder()` | ❌ | ❌ | ✅ | msga: Windows only |
+| `fs.read(path)` | ❌ | ❌ | ✅ | msga: binary→base64→TextDecoder |
+| `fs.readAsDataUrl(path)` | ❌ | ❌ | ✅ | msga: auto-detects MIME from extension |
+| `fs.write(path, content)` | ❌ | ❌ | ✅ | |
+| `fs.list(path)` | ❌ | ❌ | ✅ | msga: includes attributes/created on Windows |
+| `fs.exists(path)` | ❌ | ❌ | ✅ | |
+| `fs.delete(path)` | ❌ | ❌ | ✅ | |
+| **Shell** | | | | **`window.msgapi.shell.*`** |
+| `shell.exec()` | ❌ | ❌ | ✅ | Process with stdout/stderr; limited on non-rooted Android |
+| `shell.open()` | ❌ | ❌ | ✅ | Android: Intent.ACTION_VIEW; Windows: ShellExecute |
+| `shell.showInFolder()` | ❌ | ❌ | ❌ | Defined in interface, not yet implemented |
+| `shell.trash()` | ❌ | ❌ | ❌ | Defined in interface, not yet implemented |
+| **UDP Networking** | | | | **`window.msgapi.udp.*`** |
+| `udp.send()` | ✅ | ✅ | ✅ | Node dgram / Rust UdpSocket / C# UdpClient |
+| `udp.listen()` | ✅ | ✅ | ✅ | Background receive loop in all hosts |
+| `udp.sendReceive()` | ✅ | ✅ | ✅ | Send + wait with timeout |
+| `udp.broadcast()` | ✅ | ✅ | ✅ | 255.255.255.255 broadcast |
+| **HTTP Fetch** | | | | **`window.msgapi.http.*`** |
+| `http.fetch()` | ✅ | ✅ | ✅ | Native HTTP — bypasses CORS/mixed-content |
+
+> **msger** now injects `window.msgapi` via `msger-api.js` with window control, UDP, and HTTP. File system and shell are not yet implemented in msger or msgview.
+
+[httpudp-client](../../homecontrol/utils/udp/httpudp-client/README.md) auto-detects `window.msgapi?.udp` and uses native UDP when available, falling back to the httpudp WebSocket proxy otherwise.
+
+See [`msgapi-plan.md`](./msgapi-plan.md) for the full implementation plan and roadmap.
+
 ## API Reference
 
+### Configuration
+
+- `version` - Host app version string (e.g., `"1.2.0"`)
+- `setLogging(value?)` - Control debug logging. Returns previous state as string.
+  - `'msga'` - C# host logging only (logit-msga)
+  - `'msgapi'` - JS bridge logging only (logit-msgapi)
+  - `'on'` - Both streams
+  - `'off'` / `'none'` - All off
+  - `null` / `''` - Query current state without changing
+  - Returns: `'msga'`, `'msgapi'`, `'msga,msgapi'`, or `'none'`
+- `setAutoUpdate(value?)` - Control APK auto-update behavior. Returns previous state as string. msga Android only.
+  - `'auto'` - Check versions.json, download + install silently (no prompt)
+  - `'check'` - Check versions.json, prompt "Install now?" before downloading
+  - `'off'` - No update checking
+  - `null` / `undefined` - Query current state without changing
+  - Default: `'auto'` (configurable via `AUTO_UPDATE` in msga.env)
+  - Checks on startup then every `UPDATE_INTERVAL_MINUTES` (default 60)
+
 ### Window Control
 
 - `toggleFullscreen()` - Toggle fullscreen mode
@@ -49,15 +153,62 @@ window.close();  // Instead of msgapi.close() if not passing result
 
 ### File System
 
+File dialogs (user picks interactively — safe without special permissions):
 - `fs.selectFile(options?)` - Open file picker
 - `fs.selectFiles(options?)` - Open multi-file picker
 - `fs.saveFileAs(content, filename?, options?)` - Save file dialog
 - `fs.selectFolder(options?)` - Folder picker
-- `fs.read(path)` - Read file (requires allowFs flag)
-- `fs.write(path, content)` - Write file (requires allowFs flag)
-- `fs.list(path)` - List directory (requires allowFs flag)
-- `fs.exists(path)` - Check if file exists (requires allowFs flag)
-- `fs.delete(path)` - Delete file (requires allowFs flag)
+
+Direct path operations (give the webview full filesystem access — msga only currently):
+- `fs.read(path, options?)` - Read file. Options: `{ encoding: 'utf8' | 'base64' | 'binary' }`. Default `'utf8'` returns string; `'base64'` returns raw base64 string (efficient for images); `'binary'` returns `Uint8Array`.
+- `fs.readAsDataUrl(path, mimeType?)` - Read file as data URL (`data:image/jpeg;base64,...`). Auto-detects MIME from extension if omitted.
+- `fs.write(path, content)` - Write file
+- `fs.list(path)` - List directory. Returns `FileInfo[]` with `attributes` (Win32 flags) and `created` on Windows.
+- `fs.exists(path)` - Check if file/directory exists
+- `fs.delete(path)` - Delete file or directory
+
+> **Note:** File system operations are currently implemented only in msga. msger and msgview do not yet have `window.msgapi.fs` — these hosts have their own internal fs mechanisms but have not wired them to the msgapi interface.
+
+### UDP Networking
+
+Native UDP socket access — no WebSocket proxy needed when running inside a msgapi host.
+
+- `udp.send(host, port, data)` - Send UDP packet to specific host
+- `udp.listen(port, callback)` - Listen for incoming UDP packets (returns `{close()}` handle)
+- `udp.sendReceive(host, port, data, timeoutMs?)` - Send and wait for response
+- `udp.broadcast(port, data)` - Broadcast to local network
+
+### Shell / Process Execution
+
+Native process execution — run commands, open files with default handler. msga only currently.
+
+- `shell.exec(command, args?, options?)` - Run external command and capture output. Returns `{ stdout, stderr, exitCode }`. Options: `cwd`, `timeout` (ms), `stdin`, `encoding` (`'utf8'`|`'base64'`). Limited on non-rooted Android.
+- `shell.open(path)` - Open file/URL with system default handler (Windows: ShellExecute, Android: Intent.ACTION_VIEW)
+- `shell.showInFolder(path)` - Select file in Explorer / file manager (not yet implemented)
+- `shell.trash(path)` - Move to Recycle Bin / Trash (not yet implemented)
+
+### HTTP Fetch
+
+Native HTTP client — bypasses browser CORS and mixed-content restrictions. Use when an HTTPS-served web app needs to reach HTTP endpoints (e.g., local devices on the LAN).
+
+- `http.fetch(url, init?)` - Drop-in replacement for browser `fetch()`. Same `RequestInit` params, returns a real `Response` object (`.ok`, `.status`, `.json()`, `.text()`, `.headers`, `.clone()`, etc.)
+
+```javascript
+// HTTP from an HTTPS page — blocked by browsers, works via msgapi
+const r = await window.msgapi.http.fetch('http://192.168.1.5/api/status');
+const data = await r.json();
+
+// POST with headers and body
+const r2 = await window.msgapi.http.fetch('http://192.168.1.5/api/cmd', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ cmd: 'reboot' })
+});
+```
+
+**Platform implementations:** msga uses C# `HttpClient`, msger uses Rust `ureq`, msgview uses Node.js `fetch()`. All return a real `Response` object constructed on the JS side.
+
+**Unsupported `init` fields** (silently ignored — not meaningful for native HTTP): `mode`, `credentials`, `cache`, `signal`, `redirect`. `new Headers()` objects are normalized to plain objects.
 
 ## Examples
 
@@ -86,10 +237,49 @@ The samples demonstrate:
 - And more!
 
 
+## Cross-Platform Implementation
+
+`msgapidefs` defines the TypeScript interface only. Each host implements the `window.msgapi` bridge differently:
+
+### msgview (Electron)
+- **Bridge:** Electron `contextBridge.exposeInMainWorld('msgapi', ...)` in `preload/preload.ts`
+- **Mechanism:** `ipcRenderer.invoke()` calls to main process IPC handlers
+- **Window control:** Electron `BrowserWindow` API
+- **File system:** Node.js `fs` module via IPC, file dialogs via Electron `dialog`
+
+### msger (Rust/wry)
+- **Bridge:** JavaScript injected via wry `with_initialization_script()` in `msger-native/src/main.rs`
+- **JS API:** `msger-native/src/msger-api.js` creates `window.msgapi` object
+- **Mechanism:** `window.ipc.postMessage(JSON.stringify(...))` to Rust IPC handler
+- **Capabilities:** Window control, UDP, HTTP fetch via `window.msgapi`
+- **Limitations:** wry 0.47.2 has IPC issues; `close()` uses `window.close()` workaround
+
+### msga (.NET MAUI)
+- **Bridge:** JavaScript injected via `WebViewControl.EvaluateJavaScriptAsync()` in `MainPage.xaml.cs`
+- **JS API:** `GetMsgApiScript()` creates `window.msgapi` object inline
+- **Mechanism:** `msgapi://` URL interception — JS creates hidden iframes, C# intercepts in `OnNavigating`
+- **Async:** Promise callbacks via `callNativeAsync()` → `window._msgapiResolve()` / `_msgapiReject()`
+- **Window control:** Platform-conditional (`#if WINDOWS` uses WinUI AppWindow APIs)
+- **File system:** MAUI `FilePicker`, Windows-specific `FileSavePicker`/`FolderPicker`
+- **Platforms:** Android (primary target), Windows (development/testing)
+
+### Adding New Sub-Objects
+
+Each capability is an optional sub-object on `MsgAPI` (e.g., `fs?`, `udp?`). To add a new one:
+1. Define the interface in [`msgapidefs.ts`](./msgapidefs.ts) as an optional sub-object on `MsgAPI`
+2. Implement the native side in each host:
+   - **msgview:** Add IPC handlers in `main.ts`, expose in `preload/preload.ts`
+   - **msger:** Add Rust handler in `main.rs`, expose in `msger-api.js`
+   - **msga:** Add C# methods + JS injection in `GetMsgApiScript()` (see [msga readme](../msga/readme.md))
+3. Browser code uses optional chaining: `window.msgapi?.newFeature?.method()` — works everywhere, undefined when unavailable
+
+See [`msgapi-plan.md`](./msgapi-plan.md) for the full feature matrix and implementation status across all three hosts.
+
 ## Related Packages
 
 - [@bobfrankston/msgview](https://www.npmjs.com/package/@bobfrankston/msgview) - Electron-based message box (slower, works on Pi)
 - [@bobfrankston/msger](https://www.npmjs.com/package/@bobfrankston/msger) - Rust/wry-based message box (fast, lightweight)
+- [msga](https://github.com/BobFrankston/msga) - .NET MAUI Android/Windows wrapper app
 
 ## License
 

package/msgapi-plan.md

@@ -1,10 +1,11 @@
 # msgapi Implementation Plan
 
+> **This is the authoritative plan for msgapi.** Other TODOs (md/todo.md) reference here for msgapi-related items.
 Shared planning document for msgapi across implementations:
-- **TypeScript**: msgapidefs (this repo) - types/definitions
-- **TypeScript/Electron**: msgview
-- **Rust/wry**: msger
-- **C#/.NET MAUI**: msga (y:\dev\utils\msga)
+- **TypeScript**: [msgapidefs](../msgapidefs/) (this repo) - types/definitions ([README](../msgapidefs/README.md))
+- **TypeScript/Electron**: [msgview](../msgview/)
+- **Rust/wry**: [msger](../msger/)
+- **C#/.NET MAUI**: [msga](../msga/) ([readme](../msga/readme.md))
 
 ## Current Status
 
@@ -13,72 +14,144 @@ Shared planning document for msgapi across implementations:
 | API | msgview | msger | msga | Notes |
 |-----|---------|-------|------|-------|
 | **Window Control** |
-| toggleFullscreen() | ✅ | ✅ | ⚠️ | msga: C# exists, not wired |
-| setFullscreen(bool) | ✅ | ✅ | ⚠️ | msga: C# exists, not wired |
-| minimize() | ✅ | ✅ | ⚠️ | msga: Windows only in C# |
-| maximize() | ✅ | ✅ | ⚠️ | msga: Windows only in C# |
-| setSize(w,h) | ✅ | ✅ | ⚠️ | msga: Windows only in C# |
-| setPosition(x,y) | ✅ | ✅ | ⚠️ | msga: Windows only in C# |
+| toggleFullscreen() | ❌ | ✅ | ✅ | msga: fire-and-forget JS→C# |
+| setFullscreen(bool) | ✅ | ✅ | ✅ | |
+| minimize() | ✅ | ✅ | ✅ | msga: Windows only |
+| maximize() | ✅ | ✅ | ✅ | msga: Windows only |
+| setSize(w,h) | ✅ | ✅ | ✅ | msga: Windows only |
+| setPosition(x,y) | ✅ | ✅ | ✅ | msga: Windows only |
 | setAlwaysOnTop(bool) | ✅ | ✅ | ❌ | |
-| close(result?) | ✅ | ✅ | ⚠️ | msga: basic close only |
+| close(result?) | ✅ | ✅ | ✅ | |
+| navigate(url) | ❌ | ❌ | ✅ | msga only |
+| reload() | ❌ | ❌ | ✅ | msga only |
 | **File System** |
-| fs.selectFile() | ✅ | ✅ | ⚠️ | msga: C# exists, not wired |
-| fs.selectFiles() | ✅ | ✅ | ⚠️ | msga: C# exists, not wired |
-| fs.saveFileAs() | ✅ | ✅ | ❌ | |
-| fs.selectFolder() | ✅ | ✅ | ❌ | |
-| fs.read(path) | ✅ | ✅ | ❌ | Requires allowFs flag |
-| fs.write(path) | ✅ | ✅ | ❌ | Requires allowFs flag |
-| fs.list(path) | ✅ | ✅ | ❌ | Requires allowFs flag |
-| fs.exists(path) | ✅ | ✅ | ❌ | Requires allowFs flag |
-| fs.delete(path) | ✅ | ✅ | ❌ | Requires allowFs flag |
-
-Legend: ✅ Implemented | ⚠️ Partial/Not wired | ❌ Not implemented
+| fs.selectFile() | ❌ | ❌ | ✅ | msga: full JS bridge wired |
+| fs.selectFiles() | ❌ | ❌ | ✅ | msga: full JS bridge wired |
+| fs.saveFileAs() | ❌ | ❌ | ✅ | msga: Windows only |
+| fs.selectFolder() | ❌ | ❌ | ✅ | msga: Windows only |
+| fs.read(path, options?) | ❌ | ❌ | ✅ | encoding: utf8/base64/binary |
+| fs.readAsDataUrl(path) | ❌ | ❌ | ✅ | Auto-detects MIME from extension |
+| fs.write(path) | ❌ | ❌ | ✅ | |
+| fs.list(path) | ❌ | ❌ | ✅ | Includes attributes/created on Windows |
+| fs.exists(path) | ❌ | ❌ | ✅ | |
+| fs.delete(path) | ❌ | ❌ | ✅ | |
+| **Shell** |
+| shell.exec() | ❌ | ❌ | ✅ | Process with stdout/stderr; limited on non-rooted Android |
+| shell.open() | ❌ | ❌ | ✅ | Android: Intent.ACTION_VIEW; Windows: ShellExecute |
+| shell.showInFolder() | ❌ | ❌ | ❌ | Defined in interface, not yet implemented |
+| shell.trash() | ❌ | ❌ | ❌ | Defined in interface, not yet implemented |
+| **UDP** |
+| udp.send() | ✅ | ✅ | ✅ | Node dgram / Rust UdpSocket / C# UdpClient |
+| udp.listen() | ✅ | ✅ | ✅ | Background receive loop in all hosts |
+| udp.sendReceive() | ✅ | ✅ | ✅ | Send + wait with timeout |
+| udp.broadcast() | ✅ | ✅ | ✅ | 255.255.255.255 broadcast |
+| **HTTP** |
+| http.fetch() | ✅ | ✅ | ✅ | CORS/mixed-content bypass via native HTTP; returns real Response object |
+| **Configuration** |
+| setLogging(value?, name?) | ❌ | ❌ | ✅ | Returns old state; 'msga'/'msgapi'/'on'/'off'/null; name included in log messages/filenames |
+| setAutoUpdate(value?) | ❌ | ❌ | ✅ | 'auto'/'check'/'off'; defaults to 'off' (web app owns policy) |
+| installUpdate(url) | ❌ | ❌ | ✅ | Download + install APK; Android only. Web app calls this. |
+| getNetworkInfo() | ❌ | ❌ | ✅ | Fresh local IP + subnet mask; used by httpudp-client isAddressReachable() |
+| info | ❌ | ❌ | ✅ | `MsgHostInfo`: host, version, platform, updateUrl |
+| updateUrl | ❌ | ❌ | ✅ | URL to versions.json — install source for update checks |
+| version | ❌ | ❌ | ✅ | `window.msgapi.version` = app version string |
+
+Legend: ✅ Implemented | ❌ Not implemented
+
+### msga Logging
+
+Two independent log streams, both via `https://rmf39.aaz.lt/logit/`:
+
+| Stream | Log name | Controlled by | Content |
+|--------|----------|---------------|---------|
+| **C# (MsgALog)** | `logit-msga` | `LOGGING=false` in msga.env | OnNavigated, msgapi:// dispatch, SendAsync, UDP recv |
+| **JS (_logit)** | `logit-msgapi` | `JS_LOGGING=false` in msga.env | msgapi inject, msgapi object creation |
+
+**Startup defaults** are `false` in `msga.env` — logging is off unless the web app enables it. At **runtime**:
+```javascript
+msgapi.setLogging()              // → 'none' (query current, no change)
+msgapi.setLogging('on')          // enables both C# and JS logging
+msgapi.setLogging('on', 'test')  // enables both; C# logs to logit-msga-test, JS to logit-msgapi-test, 'test' in messages
+msgapi.setLogging('msga')        // enables C# only
+msgapi.setLogging('msgapi')      // enables JS only
+msgapi.setLogging('off')         // disables both
+```
+Always returns previous state as string: `'msga'`, `'msgapi'`, `'msga,msgapi'`, or `'none'`.
+The optional `name` parameter is included in: log file names (`logit-msga-{name}`, `logit-msgapi-{name}`) and C# log message prefix.
 
-### msga Wiring Status
+### msga Implementation Status
 
-The MsgApiBridge.cs file in msga has C# implementations but the JavaScript bridge is not connected:
-- JavaScript injection exists in MainPage.xaml.cs
-- C# handler methods exist in Services/MsgApiBridge.cs
-- Missing: WebView JavaScript-to-C# message handler wiring
+msga has the most complete msgapi.udp implementation. The JS bridge is fully wired:
+- `GetMsgApiScript()` in MainPage.xaml.cs injects `window.msgapi` with all sub-objects
+- Window control: fire-and-forget calls via `MsgABridge.invokeMethod()`
+- UDP: async Promise-based calls via `msgapi://udp/*` URL routing → `UdpService.cs`
+- Data transport: base64 encoding for binary data over the bridge
+- Listener callbacks: pushed via `window._msgapiUdpReceive()` from C#
 
 ---
 
-## Planned Features
-
-### 1. UDP Communication
+## UDP Interface
 
-**Use case**: Local device control, IoT messaging, low-latency communication
+Defined in [`msgapidefs.ts`](./msgapidefs.ts) and implemented in [msga](../msga/). Types available via `@bobfrankston/msgapidefs`.
 
 ```typescript
 interface MsgAPI {
-    udp: {
-        // Send UDP datagram
+    udp?: {
         send(host: string, port: number, data: string | Uint8Array): Promise<void>;
-
-        // Listen for UDP datagrams on a port
         listen(port: number, callback: (data: Uint8Array, sender: {host: string, port: number}) => void): Promise<{close: () => void}>;
-
-        // Send and wait for response (with timeout)
         sendReceive(host: string, port: number, data: string | Uint8Array, timeoutMs?: number): Promise<Uint8Array>;
-
-        // Broadcast to subnet
         broadcast(port: number, data: string | Uint8Array): Promise<void>;
     }
 }
 ```
 
-**Implementation notes**:
-- TypeScript: Define types only (browser cannot do UDP)
-- Electron (msgview): Use dgram module
-- Rust (msger): Use std::net::UdpSocket or tokio UDP
-- C#/MAUI (msga): Use System.Net.Sockets.UdpClient
+**Platform implementations (UDP)**:
+- **msga** (C#/MAUI): ✅ `System.Net.Sockets.UdpClient` via `UdpService.cs`
+- **msgview** (Electron): ✅ Node.js `dgram` via `ipcMain.handle` / preload
+- **msger** (Rust/wry): ✅ `std::net::UdpSocket` via `NativeEvent` + event loop
 
-**Security considerations**:
-- Require explicit allowUdp flag or permission prompt
-- Consider port restrictions (no well-known ports < 1024?)
-- Localhost-only mode option
+**Platform implementations (HTTP fetch)**:
+- **msga** (C#/MAUI): ✅ `HttpClient` — static instance, async `SendAsync`
+- **msgview** (Electron): ✅ Node.js `fetch()` via `ipcMain.handle`
+- **msger** (Rust/wry): ✅ `ureq` crate — blocking in `std::thread::spawn`, results via event loop
 
-### 2. Enhanced File System
+**httpudp-client integration**: `HttpUdpClient.connect()` detects `window.msgapi?.udp` and uses it directly when available, falling back to the httpudp WebSocket proxy otherwise. Callers never know which path was taken.
+
+---
+
+## Web-App-Driven APK Updates
+
+Update policy is owned by the web app (houser), not msga. msga provides the `installUpdate(url)` primitive; the web app decides when/whether to use it.
+
+**How it works:**
+1. Web app fetches `versions.json` from `https://rmf39.aaz.lt/msga/versions.json`
+2. Compares remote version with `window.msgapi.version`
+3. If newer, calls `await window.msgapi.installUpdate(apkUrl)` to download + install
+4. Optionally, UDP broadcast can notify about available updates (no polling needed)
+
+**`setAutoUpdate` defaults to `'off'`** — the C#-side timer-based auto-update is disabled by default. Web app calls `installUpdate()` directly when it decides an update is needed. `setAutoUpdate('auto')` can still be used to re-enable C#-side silent updates if desired.
+
+```javascript
+// Web app update check example (types: MsgVersionInfo, MsgApkInfo from msgapidefs)
+// Versions are strings like "1.5.21" — compare numerically, not lexicographically
+const isNewer = (remote, current) => {
+    const c = current.split('.').map(Number);
+    return remote.split('.').map(Number).map((v, i) => v - c[i]).reduce((r, d) => r || d, 0) > 0;
+};
+const resp = await fetch(window.msgapi.updateUrl);
+const info = await resp.json();  // MsgVersionInfo
+if (isNewer(info.version, window.msgapi.version)) {
+    const apk = info.apks.find(a => a.name === 'houser45');
+    const baseUrl = window.msgapi.updateUrl.replace(/\/[^/]*$/, '/');
+    await window.msgapi.installUpdate(baseUrl + apk.file);
+}
+```
+
+---
+
+## Planned Features
+
+### 1. Enhanced File System
 
 **Use case**: Full file system access for local apps, document management
 
@@ -160,26 +233,33 @@ interface MsgAPI {
 
 ## Implementation Priorities
 
-### Phase 1: Wire Up msga (Current)
-1. Connect JavaScript bridge to C# handlers in msga
-2. Test existing window control APIs on Android/Windows
-3. Ensure parity with msgview/msger for basic features
-
-### Phase 2: UDP Support
-1. Add UDP types to msgapidefs
-2. Implement in msger (Rust) - fastest iteration
-3. Port to msgview (Electron)
-4. Port to msga (C#/MAUI)
-
-### Phase 3: Enhanced File System
-1. Add new fs types to msgapidefs
-2. Implement mkdir, rename, copy, stat
-3. Add file watching (platform-specific)
-
-### Phase 4: System Integration
+### Phase 1: msga msgapi + UDP ✅ Done
+1. ✅ JavaScript bridge wired in msga (GetMsgApiScript → msgapi:// URL routing)
+2. ✅ Window control working on Android/Windows
+3. ✅ UDP types added to msgapidefs
+4. ✅ UDP fully implemented in msga (UdpService.cs)
+5. ✅ httpudp-client detects msgapi.udp and uses it natively
+
+### Phase 2: UDP in msger/msgview ✅ Done
+1. ✅ msger (Rust) — `std::net::UdpSocket` via NativeEvent + thread::spawn
+2. ✅ msgview (Electron) — Node.js `dgram` via ipcMain.handle + preload
+
+### Phase 3: File System + Shell in msga ✅ Done
+1. ✅ fs.read with encoding options (utf8/base64/binary)
+2. ✅ fs.readAsDataUrl with MIME auto-detection
+3. ✅ fs.list with attributes/created on Windows
+4. ✅ shell.exec — process execution with stdout/stderr capture
+5. ✅ shell.open — open files/URLs with system default handler
+
+### Phase 4: File System + Shell in msger/msgview
+1. Implement fs.* via msgcommon shared code
+2. Implement shell.exec/open via msgcommon shared code
+3. Add mkdir, rename, copy, stat extensions
+
+### Phase 5: System Integration (Lower Priority)
 1. Clipboard support
 2. Notifications
-3. Platform detection
+3. shell.showInFolder, shell.trash
 
 ---
 
@@ -200,6 +280,24 @@ Test categories:
 
 ---
 
+## Known Issues (Resolved)
+
+### msga: hash navigations killed UDP listener (fixed v1.4.0)
+
+MAUI fires OnNavigated for in-page hash changes (#Floor3, #Office, etc.) even though it's a SPA. OnNavigated was disposing UdpService on every such event, killing the listener that httpudp-client set up via msgapi.udp.listen(). Sends still worked (ephemeral sockets) but responses were lost. Symptom: "works once then stops" as the first room switch killed the listener.
+
+**Fix:** OnNavigated now compares the base URL (without hash) and skips disposal + re-injection for hash-only changes.
+
+### msga: httpudp://start caused stuck loading overlay (fixed v1.5.3)
+
+httpudp-client does `location.href = 'httpudp://start'` to try launching the httpudp proxy app on Android. This custom URL scheme triggered MAUI navigation events in unexpected order (OnNavigated before OnNavigating), causing the loading overlay to get stuck and — in some cases — preventing msgapi injection entirely.
+
+**Fix (v1.5.3):** OnNavigating and OnNavigated now skip non-http/https URLs via `IsHttpUrl()` check. LinkNavigationWebViewClient blocks non-http schemes (`return true` = "handled") so the Android WebView doesn't try to load them.
+
+**Note:** httpudp-client's `ensureHttpUdpProxy()` should NOT fire when running inside msga (msgapi.udp is available natively). If `httpudp://start` navigations appear in logs, it means httpudp-client isn't detecting msgapi.udp — check that `msgapiready` event fires before httpudp-client's `connect()` runs.
+
+---
+
 ## Notes
 
 - msgapi is injected as `window.msgapi` global

package/msgapidefs.ts

@@ -1,263 +1,152 @@
-/**
- * TypeScript definitions for the msgapi JavaScript API
- *
- * This module provides type-safe access to msgapi's window control,
- * data persistence, and file system features (used by msgview and msger).
- *
- * See README.md for complete usage documentation and examples.
- */
-
-/**
- * Result object returned when the window closes
- */
-export interface MsgResult {
-    /** Button that was clicked */
-    button: string;
-    /** Optional input field value */
-    value?: string;
-    /** Optional form data */
-    form?: Record<string, any>;
-    /** True if window was closed via close button */
-    closed?: boolean;
-    /** True if window was dismissed via Escape key */
-    dismissed?: boolean;
-    /** True if window was closed due to timeout */
-    timeout?: boolean;
+// TypeScript definitions for the msgapi JavaScript API
+// Type-safe access to msgapi's window control, file system, shell, and UDP features
+// Used by msgview, msger, and msga. See README.md for docs.
+//
+// ⚠️ SECURITY: msgapi gives full native OS access (filesystem, processes, networking).
+// Intended ONLY for trusted apps — native apps written as web pages. Do not expose to untrusted content.
+// ⚠️ EXPERIMENTAL: APIs are experimental and subject to change.
+
+export interface MsgResult {  // Result object returned when the window closes
+    button: string;           // Button that was clicked
+    value?: string;           // Optional input field value
+    form?: Record<string, any>;  // Optional form data
+    closed?: boolean;         // True if closed via close button
+    dismissed?: boolean;      // True if dismissed via Escape key
+    timeout?: boolean;        // True if closed due to timeout
 }
 
-/**
- * File information returned by file system operations
- */
-export interface FileInfo {
-    /** File name */
-    name: string;
-    /** Full file path */
-    path: string;
-    /** True if this is a directory */
-    isDir: boolean;
-    /** File size in bytes (0 for directories) */
-    size: number;
-    /** Last modified timestamp (ISO 8601 string) */
-    modified?: string;
+export interface FileInfo {   // File information from file system operations
+    name: string;             // File name
+    path: string;             // Full file path
+    isDir: boolean;           // True if this is a directory
+    size: number;             // File size in bytes (0 for directories)
+    modified?: string;        // Last modified timestamp (ISO 8601 string)
+    created?: string;         // Creation time (ISO 8601 string); undefined on platforms without creation time
+    attributes?: number;      // Win32 FILE_ATTRIBUTE_* flags (e.g. 0x00400000 = RECALL_ON_DATA_ACCESS for OneDrive cloud-only); undefined on Android/Linux
 }
 
-/**
- * Options for file selection dialogs
- */
-export interface FileDialogOptions {
-    /** Dialog title */
-    title?: string;
-    /** Default filename for save dialogs */
-    defaultFilename?: string;
-    /** File filters (e.g., [{name: "Text", extensions: ["txt", "md"]}]) */
-    filters?: Array<{name: string; extensions: string[]}>;
-    /** Default directory to open */
-    defaultPath?: string;
+export interface FileDialogOptions {  // Options for file selection dialogs
+    title?: string;                   // Dialog title
+    defaultFilename?: string;         // Default filename for save dialogs
+    filters?: Array<{name: string; extensions: string[]}>;  // File filters
+    defaultPath?: string;             // Default directory to open
 }
 
-/**
- * Selected file with content
- */
-export interface SelectedFile {
-    /** File name */
-    name: string;
-    /** Full file path */
-    path: string;
-    /** File content as string */
-    content: string;
+export interface SelectedFile {  // Selected file with content
+    name: string;                // File name
+    path: string;                // Full file path
+    content: string;             // File content as string
 }
 
-/**
- * msgapi JavaScript API
- *
- * Available when running inside msgview/msger via window.msgapi
- */
-export interface MsgAPI {
-    // ========================================
-    // Window Control
-    // ========================================
+export type MsgHost = 'msga' | 'msger' | 'msgview';
+export type MsgPlatform = 'android' | 'windows' | 'linux' | 'macos';
+export type AutoUpdateMode = 'auto' | 'check' | 'off';
+export type LoggingMode = 'msga' | 'msgapi' | 'on' | 'off' | 'none';
+
+export interface MsgHostInfo {    // Host application identity and capabilities
+    host: MsgHost;                // Which host app is running
+    version: string;              // App version (e.g. "1.5.21") — semver string, compare numerically not lexicographically
+    platform: MsgPlatform;        // Runtime platform
+    appName?: string;             // APK variant name (e.g. "houser46") — derived from package ID, matches versions.json apks[].name
+    updateUrl?: string;           // URL to versions.json — install source for update checks (msga only)
+    apkUrl?: string;              // Direct URL to this APK (e.g. "https://rmf39.aaz.lt/msga/apks/houser46.apk")
+    localIp?: string;             // Device IP on current network (e.g. "172.20.1.42")
+    localMask?: string;           // Subnet mask (e.g. "255.255.0.0") — msga uses ip+mask to reject udp.send() when destination is off-network
+}
 
-    /**
-     * Toggle fullscreen mode on/off
-     * @example
-     * msgapi.toggleFullscreen();
-     */
-    toggleFullscreen(): void;
+export interface MsgApkInfo {     // One APK entry in versions.json
+    name: string;                 // App variant name (e.g. "houser", "houser45")
+    url: string;                  // Default URL the APK loads
+    description: string;          // Human-readable description
+    icon: string;                 // Icon URL
+    file: string;                 // APK file path relative to versions.json (e.g. "apks/houser.apk")
+    sizeMB: number;               // Approximate size in MB
+    built: string;                // Build timestamp (ISO 8601)
+    default?: boolean;            // True if this is the default APK
+}
 
-    /**
-     * Set fullscreen mode
-     * @param enabled - true to enter fullscreen, false to exit
-     * @example
-     * msgapi.setFullscreen(true);
-     */
-    setFullscreen(enabled: boolean): void;
+export interface MsgVersionInfo {  // Structure of versions.json
+    version: string;               // Latest available version (e.g. "1.5.21") — semver string, compare numerically not lexicographically
+    buildDate: string;             // Build timestamp (ISO 8601)
+    apks: MsgApkInfo[];            // Available APK variants
+}
 
-    /**
-     * Minimize the window
-     * @example
-     * msgapi.minimize();
-     */
-    minimize(): void;
+// msgapi JavaScript API — available via window.msgapi inside msgview/msger/msga
+export interface MsgAPI {
 
-    /**
-     * Toggle maximize/restore window
-     * @example
-     * msgapi.maximize();
-     */
-    maximize(): void;
+    version?: string;  // Host app version (e.g. "1.3.0") — semver string, compare numerically not lexicographically
+    updateUrl?: string;  // URL to versions.json — install source for update checks
+    info?: MsgHostInfo;  // Host identity: host name, version, platform, updateUrl
 
-    /**
-     * Set window size
-     * @param width - Window width in pixels
-     * @param height - Window height in pixels
-     * @example
-     * msgapi.setSize(800, 600);
-     */
-    setSize(width: number, height: number): void;
+    // ── Configuration ────────────────────────────────────────────
 
-    /**
-     * Set window position
-     * @param x - X coordinate in pixels
-     * @param y - Y coordinate in pixels
-     * @example
-     * msgapi.setPosition(100, 100);
-     */
-    setPosition(x: number, y: number): void;
+    setLogging?(value?: LoggingMode, name?: string): LoggingMode;  // null/undefined = query only. name included in log messages/filenames. Returns previous state.
+    setAutoUpdate?(value?: AutoUpdateMode): AutoUpdateMode;  // null/undefined = query only. Returns previous state. msga Android only.
+    installUpdate?(url: string): Promise<void>;  // Download + install APK from url. msga Android only; web app owns update policy.
+    getNetworkInfo?(): Promise<{ localIp: string; localMask: string }>;  // Current device IP + subnet mask (fresh, not cached)
 
-    /**
-     * Set always-on-top behavior
-     * @param enabled - true to keep window on top
-     * @example
-     * msgapi.setAlwaysOnTop(true);
-     */
-    setAlwaysOnTop(enabled: boolean): void;
+    // ── Window Control ──────────────────────────────────────────
 
-    /**
-     * Close the window and return result to parent process
-     * @param result - Optional result to return to parent process
-     * @example
-     * // Close with default dismissed result
-     * msgapi.close();
-     *
-     * // Close with custom result
-     * msgapi.close({button: 'OK', value: 'user data'});
-     */
-    close(result?: Partial<MsgResult>): void;
+    toggleFullscreen(): void;                      // Toggle fullscreen mode on/off
+    setFullscreen(enabled: boolean): void;         // Set fullscreen mode
+    minimize(): void;                              // Minimize the window
+    maximize(): void;                              // Toggle maximize/restore
+    setSize(width: number, height: number): void;  // Set window size in pixels
+    setPosition(x: number, y: number): void;       // Set window position in pixels
+    setAlwaysOnTop(enabled: boolean): void;        // Keep window on top
+    close(result?: Partial<MsgResult>): void;      // Close window, return result to parent
 
-    // ========================================
-    // File System Access
-    // ========================================
+    // ── File System Access ──────────────────────────────────────
 
-    /**
-     * File system operations namespace
-     */
     fs?: {
-        /**
-         * Select a file using native file picker
-         * @param options - File dialog options
-         * @returns Selected file with content, or null if cancelled
-         * @example
-         * const file = await msgapi.fs.selectFile({
-         *     title: 'Open File',
-         *     filters: [{name: 'Text', extensions: ['txt', 'md']}]
-         * });
-         * if (file) {
-         *     console.log(file.content);
-         * }
-         */
-        selectFile(options?: FileDialogOptions): Promise<SelectedFile | null>;
-
-        /**
-         * Select multiple files using native file picker
-         * @param options - File dialog options
-         * @returns Array of selected files with content
-         * @example
-         * const files = await msgapi.fs.selectFiles({
-         *     title: 'Open Files'
-         * });
-         */
-        selectFiles(options?: FileDialogOptions): Promise<SelectedFile[]>;
-
-        /**
-         * Save file using native save dialog
-         * @param content - File content to save
-         * @param defaultFilename - Default filename
-         * @param options - Additional dialog options
-         * @returns Path where file was saved, or null if cancelled
-         * @example
-         * const path = await msgapi.fs.saveFileAs('Hello World', 'greeting.txt');
-         */
-        saveFileAs(
-            content: string,
-            defaultFilename?: string,
-            options?: FileDialogOptions
-        ): Promise<string | null>;
-
-        /**
-         * Select a directory using native folder picker
-         * @param options - Dialog options
-         * @returns Selected directory path, or null if cancelled
-         * @example
-         * const dir = await msgapi.fs.selectFolder({
-         *     title: 'Select Output Folder'
-         * });
-         */
-        selectFolder(options?: FileDialogOptions): Promise<string | null>;
+        selectFile(options?: FileDialogOptions): Promise<SelectedFile | null>;  // Native file picker (null if cancelled)
+        selectFiles(options?: FileDialogOptions): Promise<SelectedFile[]>;      // Multi-file picker
+        saveFileAs(content: string, defaultFilename?: string, options?: FileDialogOptions): Promise<string | null>;  // Save dialog (returns path or null)
+        selectFolder(options?: FileDialogOptions): Promise<string | null>;      // Folder picker (null if cancelled)
+        read(path: string, options?: { encoding?: 'utf8' | 'base64' | 'binary' }): Promise<string | Uint8Array>;  // Read file; utf8 (default)=text, base64=raw b64 string, binary=Uint8Array
+        readAsDataUrl(path: string, mimeType?: string): Promise<string>;  // Read file as data URL (auto-detects MIME from extension if omitted)
+        write(path: string, content: string): Promise<void>;  // Write file contents (requires allowFs)
+        list(path: string): Promise<FileInfo[]>;      // List directory contents (requires allowFs)
+        exists(path: string): Promise<boolean>;       // Check if file/directory exists (requires allowFs)
+        delete(path: string): Promise<void>;          // Delete file or directory (requires allowFs)
+    };
 
-        /**
-         * Read file contents
-         * Note: Requires allowFs: true flag when launching msgview/msger
-         * @param path - File path to read
-         * @returns File content as string
-         * @example
-         * const content = await msgapi.fs.read('/path/to/file.txt');
-         */
-        read(path: string): Promise<string>;
+    // ── UDP Networking ──────────────────────────────────────────
+    // Native UDP — no httpudp WebSocket proxy needed
 
-        /**
-         * Write file contents
-         * Note: Requires allowFs: true flag when launching msgview/msger
-         * @param path - File path to write
-         * @param content - Content to write
-         * @example
-         * await msgapi.fs.write('/path/to/file.txt', 'Hello World');
-         */
-        write(path: string, content: string): Promise<void>;
+    udp?: {
+        send(host: string, port: number, data: string | Uint8Array): Promise<void>;  // Send UDP packet to host:port
+        listen(port: number, callback: (data: Uint8Array, sender: { host: string; port: number }) => void): Promise<{ close: () => void }>;  // Listen on port (0=ephemeral), returns {close()}
+        sendReceive(host: string, port: number, data: string | Uint8Array, timeoutMs?: number): Promise<Uint8Array>;  // Send and wait for response
+        broadcast(port: number, data: string | Uint8Array): Promise<void>;  // Broadcast to local network
+    };
 
-        /**
-         * List directory contents
-         * Note: Requires allowFs: true flag when launching msgview/msger
-         * @param path - Directory path to list
-         * @returns Array of file information
-         * @example
-         * const files = await msgapi.fs.list('/path/to/dir');
-         */
-        list(path: string): Promise<FileInfo[]>;
+    // ── HTTP Fetch (CORS/mixed-content bypass) ──────────────────
+    // Routes requests through the native host — no mixed-content or CORS restrictions
+    // Returns a real Response object: .ok, .status, .json(), .text(), .headers, .clone()
 
-        /**
-         * Check if file or directory exists
-         * Note: Requires allowFs: true flag when launching msgview/msger
-         * @param path - Path to check
-         * @returns true if exists
-         * @example
-         * const exists = await msgapi.fs.exists('/path/to/file.txt');
-         */
-        exists(path: string): Promise<boolean>;
+    http?: {
+        fetch(url: string, init?: RequestInit): Promise<Response>;  // Drop-in fetch() replacement via native HTTP
+    };
 
-        /**
-         * Delete file or directory
-         * Note: Requires allowFs: true flag when launching msgview/msger
-         * @param path - Path to delete
-         * @example
-         * await msgapi.fs.delete('/path/to/file.txt');
-         */
-        delete(path: string): Promise<void>;
+    // ── Shell / Process Execution ─────────────────────────────────
+    // Native process execution — run commands, open files with default handler
+    // ⚠️ Powerful: grants full process execution. Use only in trusted apps.
+
+    shell?: {
+        exec(command: string, args?: string[], options?: {  // Run external command, capture output
+            cwd?: string;           // Working directory
+            timeout?: number;       // Timeout in ms (0 = no timeout)
+            stdin?: string;         // Pipe string to stdin
+            encoding?: 'utf8' | 'base64';  // stdout/stderr encoding (default utf8)
+        }): Promise<{ stdout: string; stderr: string; exitCode: number }>;
+        open(path: string): Promise<void>;            // Open file/URL with system default handler (ShellExecute / Intent.ACTION_VIEW)
+        showInFolder(path: string): Promise<void>;    // Select file in Explorer / file manager
+        trash(path: string): Promise<void>;           // Move to Recycle Bin / Trash (soft delete, not permanent)
     };
 }
 
-/**
- * Declare global window.msgapi
- */
+// Global window.msgapi declaration
 declare global {
     interface Window {
         msgapi?: MsgAPI;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/msgapidefs",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "TypeScript definitions for msgapi JavaScript API (msgview/msger)",
   "type": "module",
   "main": "./msgapidefs.js",
@@ -34,5 +34,8 @@
     "preversion": "git add -A",
     "postversion": "git push && git push --tags",
     "release": "npm run prerelease:local && npm version patch && npm publish --quiet"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.1"
   }
 }