@bobfrankston/msgapidefs 0.1.30 → 0.1.31

package/README.md

@@ -1,7 +1,24 @@
 # @bobfrankston/msgapidefs
 
-TypeScript definitions for the **msgapi** JavaScript API used in msgview and msger. See the Typescript definitions in
-[msgdpidefs.ts](msgapidefs.ts) for more info
+> **⚠️ 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
 
@@ -35,6 +52,23 @@ 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
@@ -46,33 +80,41 @@ window.close();  // Instead of msgapi.close() if not passing result
 | `setLogging(value?)` | ❌ | ❌ | ✅ | Returns previous state |
 | `setAutoUpdate(value?)` | ❌ | ❌ | ✅ | `'auto'`/`'check'`/`'off'`; msga Android only |
 | **Window Control** | | | | **`window.msgapi.*`** |
-| `toggleFullscreen()` | ❌ | ⚠️ | ✅ | msger: via IPC, not on window.msgapi |
-| `setFullscreen(bool)` | ✅ | ⚠️ | ✅ | msger: via IPC, not on window.msgapi |
-| `minimize()` | ✅ | ⚠️ | ✅ | msga: Windows only; msger: via IPC |
-| `maximize()` | ✅ | ⚠️ | ✅ | msga: Windows only; msger: via IPC |
-| `setSize(w, h)` | ✅ | ⚠️ | ✅ | msga: Windows only; msger: via IPC |
-| `setPosition(x, y)` | ✅ | ⚠️ | ✅ | msga: Windows only; msger: via IPC |
-| `setAlwaysOnTop(bool)` | ✅ | ⚠️ | ❌ | msger: via IPC |
-| `close(result?)` | ✅ | ✅ | ✅ | msger: on window.msger |
+| `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: C# exists, not wired to JS |
-| `fs.selectFiles()` | ✅ | ✅ | ⚠️ | msga: C# exists, not wired to JS |
-| `fs.saveFileAs()` | ✅ | ✅ | ❌ | |
-| `fs.selectFolder()` | ✅ | ✅ | ❌ | |
-| `fs.read(path)` | ✅ | ✅ | ❌ | Requires allowFs flag |
-| `fs.write(path, content)` | ✅ | ✅ | ❌ | Requires allowFs flag |
-| `fs.list(path)` | ✅ | ✅ | ❌ | Requires allowFs flag |
-| `fs.exists(path)` | ✅ | ✅ | ❌ | Requires allowFs flag |
-| `fs.delete(path)` | ✅ | ✅ | ❌ | Requires allowFs flag |
+| `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()` | ❌ | ❌ | ✅ | msga: C# UdpClient |
-| `udp.listen()` | ❌ | ❌ | ✅ | msga: background receive loop |
-| `udp.sendReceive()` | ❌ | ❌ | ✅ | msga: send + wait with timeout |
-| `udp.broadcast()` | ❌ | ❌ | ✅ | msga: EnableBroadcast=true |
+| `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 note:** Window control functionality exists in Rust but is exposed via `window.msger` + IPC actions (`window.ipc.postMessage({_action: ...})`), not as `window.msgapi` methods. Alignment to `window.msgapi` is needed.
+> **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.
 
@@ -117,14 +159,15 @@ File dialogs (user picks interactively — safe without special permissions):
 - `fs.saveFileAs(content, filename?, options?)` - Save file dialog
 - `fs.selectFolder(options?)` - Folder picker
 
-Direct path operations (give the webview full filesystem access):
-- `fs.read(path)` - Read file
+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
-- `fs.exists(path)` - Check if file exists
-- `fs.delete(path)` - Delete 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
 
-> **`allowFs` flag:** Direct path operations are intended to require an explicit `--allowFs` CLI flag (e.g., `msger -url "..." --allowFs`) since they grant unrestricted filesystem access. This flag is documented in the interface but **not yet enforced** — the methods currently work without it in both msger and msgview. Enforcement is planned.
+> **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
 
@@ -135,6 +178,38 @@ Native UDP socket access — no WebSocket proxy needed when running inside a msg
 - `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
 
 See [samples.html](samples.html) for interactive examples and demos of all API features!
@@ -174,9 +249,9 @@ The samples demonstrate:
 
 ### 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.msger` object
+- **JS API:** `msger-native/src/msger-api.js` creates `window.msgapi` object
 - **Mechanism:** `window.ipc.postMessage(JSON.stringify(...))` to Rust IPC handler
-- **Note:** Currently exposes `window.msger` (not `window.msgapi`) - alignment needed
+- **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)

package/msgapi-plan.md

@@ -14,7 +14,7 @@ Shared planning document for msgapi across implementations:
 | API | msgview | msger | msga | Notes |
 |-----|---------|-------|------|-------|
 | **Window Control** |
-| toggleFullscreen() | ✅ | ✅ | ✅ | msga: fire-and-forget JS→C# |
+| toggleFullscreen() | ❌ | ✅ | ✅ | msga: fire-and-forget JS→C# |
 | setFullscreen(bool) | ✅ | ✅ | ✅ | |
 | minimize() | ✅ | ✅ | ✅ | msga: Windows only |
 | maximize() | ✅ | ✅ | ✅ | msga: Windows only |
@@ -25,22 +25,30 @@ Shared planning document for msgapi across implementations:
 | 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 |
+| 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() | ❌ | ❌ | ✅ | msga: C# UdpClient |
-| udp.listen() | ❌ | ❌ | ✅ | msga: background receive loop |
-| udp.sendReceive() | ❌ | ❌ | ✅ | msga: send + wait with timeout |
-| udp.broadcast() | ❌ | ❌ | ✅ | msga: EnableBroadcast=true |
+| 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?) | ❌ | ❌ | ✅ | Returns old state; 'msga'/'msgapi'/'on'/'off'/null |
+| 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() |
@@ -48,7 +56,7 @@ Shared planning document for msgapi across implementations:
 | updateUrl | ❌ | ❌ | ✅ | URL to versions.json — install source for update checks |
 | version | ❌ | ❌ | ✅ | `window.msgapi.version` = app version string |
 
-Legend: ✅ Implemented | ⚠️ Partial/Not wired | ❌ Not implemented
+Legend: ✅ Implemented | ❌ Not implemented
 
 ### msga Logging
 
@@ -56,18 +64,20 @@ Two independent log streams, both via `https://rmf39.aaz.lt/logit/`:
 
 | Stream | Log name | Controlled by | Content |
 |--------|----------|---------------|---------|
-| **C# (MsgALog)** | `logit-msga` | `LOGGING=true` in msga.env | OnNavigated, msgapi:// dispatch, SendAsync, UDP recv |
-| **JS (_logit)** | `logit-msgapi` | `JS_LOGGING=true` in msga.env | msgapi inject, msgapi object creation |
+| **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 set in `msga.env`. At **runtime**:
+**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('msga')     // → 'none' (old); enables C# only
-msgapi.setLogging('msgapi')   // → 'msga' (old); enables JS only
-msgapi.setLogging('on')       // → 'msgapi' (old); enables both
-msgapi.setLogging('off')      // → 'msga,msgapi' (old); disables both
+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 Implementation Status
 
@@ -95,10 +105,15 @@ interface MsgAPI {
 }
 ```
 
-**Platform implementations**:
+**Platform implementations (UDP)**:
 - **msga** (C#/MAUI): ✅ `System.Net.Sockets.UdpClient` via `UdpService.cs`
-- **msgview** (Electron): ❌ Planned — Node.js `dgram` via IPC/preload
-- **msger** (Rust/wry): ❌ Planned — `std::net::UdpSocket` or tokio
+- **msgview** (Electron): ✅ Node.js `dgram` via `ipcMain.handle` / preload
+- **msger** (Rust/wry): ✅ `std::net::UdpSocket` via `NativeEvent` + event loop
+
+**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
 
 **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.
 
@@ -225,19 +240,26 @@ interface MsgAPI {
 4. ✅ UDP fully implemented in msga (UdpService.cs)
 5. ✅ httpudp-client detects msgapi.udp and uses it natively
 
-### Phase 2: UDP in msger/msgview
-1. Implement in msger (Rust) — `std::net::UdpSocket` or tokio
-2. Port to msgview (Electron) — Node.js `dgram` via IPC/preload
+### 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 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: 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 4: System Integration
+### Phase 5: System Integration (Lower Priority)
 1. Clipboard support
 2. Notifications
-3. Platform detection
+3. shell.showInFolder, shell.trash
 
 ---
 

package/msgapidefs.ts

@@ -1,6 +1,10 @@
 // TypeScript definitions for the msgapi JavaScript API
-// Type-safe access to msgapi's window control, file system, and UDP features
+// 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
@@ -17,6 +21,8 @@ export interface FileInfo {   // File information from file system operations
     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
 }
 
 export interface FileDialogOptions {  // Options for file selection dialogs
@@ -74,7 +80,7 @@ export interface MsgAPI {
 
     // ── Configuration ────────────────────────────────────────────
 
-    setLogging?(value?: LoggingMode): LoggingMode;  // null/undefined = query only. Returns previous state.
+    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)
@@ -97,7 +103,8 @@ export interface MsgAPI {
         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): Promise<string>;          // Read file contents (requires allowFs)
+        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)
@@ -113,6 +120,30 @@ export interface MsgAPI {
         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
     };
+
+    // ── 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()
+
+    http?: {
+        fetch(url: string, init?: RequestInit): Promise<Response>;  // Drop-in fetch() replacement via native HTTP
+    };
+
+    // ── 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)
+    };
 }
 
 // Global window.msgapi declaration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/msgapidefs",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "description": "TypeScript definitions for msgapi JavaScript API (msgview/msger)",
   "type": "module",
   "main": "./msgapidefs.js",