@bobfrankston/msgapidefs 0.1.36 → 0.1.38

package/README.md

@@ -13,8 +13,8 @@ TypeScript definitions for the **msgapi** JavaScript API used by msga, msger, an
 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)
+├── msger         - Rust/wry webview host (Windows, Linux, Mac, Pi) — PRIMARY
+├── msgview       - Electron webview host (desktop) — SEMI-RETIRED, see below
 ├── msga          - .NET MAUI webview host (Android, Windows)
 ├── build         - Release build orchestration script (build/build.ts)
 └── md            - Shared documentation
@@ -61,14 +61,41 @@ window.close();  // Instead of msgapi.close() if not passing result
 | **Windows** | ✅ | ✅ | ✅ |
 | **Linux** | ✅ | ✅ | ❌ |
 | **macOS** | 🔧 wry supports it | ✅ | 🔧 Mac Catalyst |
-| **Raspberry Pi** | ⚠️ runs but no display | ✅ | ❌ |
+| **Raspberry Pi** | ✅ | ✅ | ❌ |
 | **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.
+> **msger** uses wry (Rust webview) and is the **primary host**. Desktop platforms (Win/Linux/Mac) are mature. The Pi display bug ("runs but renders shredded scanlines") was WebKitGTK's DMABUF renderer on vc4/v3d — msger now sets `WEBKIT_DISABLE_DMABUF_RENDERER=1` automatically on Raspberry Pi hardware (both the JS launcher and the binary), and the Pi renders correctly as of 2026-07-31.
+> **msgview** is **semi-retired** as of 2026-07-31 — see below.
 > **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.
 
+### msgview is semi-retired (2026-07-31)
+
+msger + msga cover every platform, so the Electron host has no platform to itself.
+**Do not do feature-parity work on msgview.** New features land in msger (and msga
+where it makes sense); msgview catches up only on demand, if a real need appears.
+
+**As of 2026-08-01 msgview has no capability msger lacks.** The two things that
+used to be Electron-only are both settled:
+
+- **Unpacked Chrome extensions** (`-extension`) — not how add-ins are done here.
+  **`window.msgapi` (this package) plus injected init scripts is the add-in
+  mechanism**: `initScript` / `initScriptPath` inject app JS into every document
+  before page scripts run, with the full msgapi surface available — host-native,
+  works in msger and msga, no Chromium required. If something genuinely needs
+  Chrome extension APIs, run it in Chrome.
+- **`-render` off Windows** — ported. msger now captures on Linux/Pi through
+  WebKitGTK's snapshot API (see the render row above), verified on a Pi 5 for both
+  PNG and JPEG output.
+
+Engine currency is *not* a reason: a feature probe on Pi 5 / WebKitGTK 2.50.6
+(2026-07-31) passed 23 of 24 modern checks — `:has()`, CSS nesting, container
+queries, subgrid, `backdrop-filter`, `color-mix`, `oklch`, Popover, View
+Transitions, `Object.groupBy`, `Promise.withResolvers`, `Intl.Segmenter`, WebGL2,
+OffscreenCanvas — failing only the RegExp `v` flag. The WebKitGTK user-agent token
+(`Version/60.5`) is a WebKitGTK version string, not a Safari generation; it says
+nothing about capability.
+
 ## Implementation Status
 
 ✅ = Implemented | ⚠️ = Partial | ❌ = Not implemented
@@ -79,6 +106,8 @@ window.close();  // Instead of msgapi.close() if not passing result
 | `version` | ❌ | ❌ | ✅ | `window.msgapi.version` string |
 | `setLogging(value?)` | ❌ | ❌ | ✅ | Returns previous state |
 | `setAutoUpdate(value?)` | ❌ | ❌ | ✅ | `'auto'`/`'check'`/`'off'`; msga Android only |
+| **Diagnostics** | | | | **`window.msgapi.diag.*`** |
+| `diag.getExitReasons(max?)` | ❌ | ❌ | ✅ | Why the previous run exited; msga Android 11+ only, `[]` elsewhere |
 | **Window Control** | | | | **`window.msgapi.*`** |
 | `toggleFullscreen()` | ❌ | ✅ | ✅ | msger: via `window.msgapi` (msger-api.js) |
 | `setFullscreen(bool)` | ✅ | ✅ | ✅ | |
@@ -123,9 +152,9 @@ window.close();  // Instead of msgapi.close() if not passing result
 | `http.fetch()` | ✅ | ✅ | ✅ | Native HTTP — bypasses CORS/mixed-content |
 | **Host Launcher Features** | | | | *Not part of `window.msgapi`; CLI / launcher-side* |
 | Markdown rendering (`.md`/`.markdown` auto-render) | ✅ | ✅ | ❌ | Local `file://` URL → rendered HTML via `msgcommon/markdown` (marked + light/dark CSS). msga could match it in `MainPage.xaml.cs` URL interception — not done yet. |
-| Unpacked Chrome extension loading (`-extension <dir>`) | ✅ | ❌ | ❌ | msgview-only via `session.extensions.loadExtension`. wry has no public extension API; WebKitGTK has none at all. msga would need a separate Android/WebView2 plumbing — not planned. |
+| Unpacked Chrome extension loading (`-extension <dir>`) | ✅ | ❌ | ❌ | msgview-only via `session.extensions.loadExtension`. wry has no public extension API; WebKitGTK has none at all. **Not the add-in mechanism here** — app add-ins are `window.msgapi` + injected init scripts (`initScript` / `initScriptPath`), which work in msger and msga without Chromium. Chrome-extension-specific needs go to Chrome. |
 | Headless mode (`-noshow` without `-save`) | ✅ | ✅ | ❌ | msger creates the WebView invisible (`with_visible(false)`) but still loads HTML and runs scripts — an embedded `<script>` can query the engine and `window.ipc.postMessage` a result back. Combined with `-result <fieldname>` for clean stdout, this lets msger act as a headless CSS/JS resolver (`contrast-color()`, `getComputedStyle()`, `CSS.supports()`). msgview matches with `BrowserWindow({show:false})` + `backgroundThrottling:false`. |
-| Render to bitmap (`-render [file]`, `render` option) | ✅ | ✅ | ❌ | Headless page→image capture: the window is never shown; the page loads, settles (`renderDelay`, default 100ms after `load` + two rAFs), is screenshotted, and the host exits. `-render <file>` writes the image (format from extension: `.png`/`.jpg`/`.bmp`) and the JSON result carries `render: {path, width, height, format}`; bare `-render` (or API `render: true`) returns it as `render: {data (base64), width, height, format}`. Library API: `showMessageBox({render: "shot.png" \| true, renderDelay?, renderFormat?})`; a failed capture rejects (msger) or sets `renderError` in the result. Both hosts fall back to capturing whatever rendered if the page hasn't loaded within the timeout (default 30s in render mode). msger: WebView2 DevTools `Page.captureScreenshot` — **Windows only** for now; msgview: `webContents.capturePage()` — all Electron platforms. Width/height are physical pixels (include DPI scale). |
+| Render to bitmap (`-render [file]`, `render` option) | ✅ | ✅ | ❌ | Headless page→image capture: the window is never shown; the page loads, settles (`renderDelay`, default 100ms after `load` + two rAFs), is screenshotted, and the host exits. `-render <file>` writes the image (format from extension: `.png`/`.jpg`/`.bmp`) and the JSON result carries `render: {path, width, height, format}`; bare `-render` (or API `render: true`) returns it as `render: {data (base64), width, height, format}`. Library API: `showMessageBox({render: "shot.png" \| true, renderDelay?, renderFormat?})`; a failed capture rejects (msger) or sets `renderError` in the result. Both hosts fall back to capturing whatever rendered if the page hasn't loaded within the timeout (default 30s in render mode). msger: WebView2 DevTools `Page.captureScreenshot` on Windows, `webkit_web_view_get_snapshot()` → cairo PNG on Linux/Pi (2026-08-01); msgview: `webContents.capturePage()`. Both msger paths produce the same base64 PNG, so format transcoding and file writing are shared. **Linux caveat:** WebKitGTK cannot snapshot a window that was never mapped, so on Linux the render window IS mapped — made invisible by going fully transparent and skipping the taskbar, since Wayland has no way to park a window off-screen. Width/height are physical pixels (include DPI scale) and cover the WebView viewport, not the window frame. |
 
 > **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.
 >
@@ -155,6 +184,35 @@ See [`msgapi-plan.md`](./msgapi-plan.md) for the full implementation plan and ro
   - Default: `'auto'` (configurable via `AUTO_UPDATE` in msga.env)
   - Checks on startup then every `UPDATE_INTERVAL_MINUTES` (default 60)
 
+### Diagnostics
+
+Why did the previous run exit? Android records the last few process deaths (`ApplicationExitInfo`, Android 11+); the host reads its own history on the next run and exposes it to the web app. This distinguishes crash / ANR / low-memory kill / cached-app freezer — no adb needed. Currently msga Android only; other hosts/platforms return `[]`.
+
+- `diag.getExitReasons(max?)` - Previous-run exit records, newest first (default/max clamp: 5/16). Returns `MsgExitInfo[]`:
+  - `timestamp` - Exit time, ms since epoch
+  - `reason` - `"LowMemory"`, `"Crash"`, `"CrashNative"`, `"Anr"`, `"Freezer"`, `"ExitSelf"`, `"Signaled"`, `"UserRequested"`, `"UserStopped"`, `"DependencyDied"`, `"ExcessiveResourceUsage"`, `"PackageUpdated"`, `"Other"`, ... (Android `ApplicationExitInfo` reason names)
+  - `description` - OS-provided detail (may be null), e.g. `"isolated not needed"` = renderer cleanup
+  - `importance` - Process state at death (e.g. `"Foreground"`, `"Cached"`) — a `Cached` + `LowMemory` kill is normal Android memory reclaim, not a bug
+  - `pss` / `rss` - Memory at exit, KB
+  - `processName` - Which process died: the main package name, or `...:sandboxed_process*` = the WebView renderer. **Records cover every process in the package** — renderer deaths are routine cleanup, not the app dying; filter by processName to find real main-process exits
+  - `pid` - Process ID at exit
+  - `status` - Signal number for `Signaled`, exit code for `ExitSelf`, 0 otherwise
+  - `stateSummary` - App-set marker (`ActivityManager.setProcessStateSummary`); msga stamps `start=<ISO time> v=<version>` at each launch so uptime-at-death is computable
+  - `trace` - First ~4KB of the ANR/native-crash trace when the OS captured one (`Anr`/`CrashNative` only)
+
+```javascript
+// Exit-history tool in a web app (e.g. houser debug panel)
+const exits = await window.msgapi?.diag?.getExitReasons() ?? [];
+for (const e of exits) {
+    console.log(`${new Date(e.timestamp).toLocaleString()} ${e.reason}` +
+        ` (${e.importance ?? '?'}, pss=${e.pss ?? '?'}KB) ${e.description ?? ''}`);
+}
+```
+
+Interpreting common reasons: `LowMemory` = killed by the low-memory killer; `Anr` = main thread hung; `Crash`/`CrashNative` = unhandled exception / native crash; `Freezer` = app was frozen (Android 12+ cached-app freezing — UDP listeners silently suspended, app not actually dead); `UserRequested` = swiped away from recents; `PackageUpdated` = replaced by an APK update; `Signaled` = killed by signal (check `description`).
+
+msga also logs new exit records via MsgALog at startup when `LOGGING=true` in msga.env (`Previous exit: ...`), deduplicated across runs via a `lastSeenExitTimestamp` preference. See [msga/exit-diagnostics.md](../msga/exit-diagnostics.md) for the full design notes.
+
 ### Window Control
 
 - `toggleFullscreen()` - Toggle fullscreen mode

package/msgapi-plan.md

@@ -62,6 +62,7 @@ Shared planning document for msgapi across implementations:
 | 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() |
+| diag.getExitReasons(max?) | ❌ | ❌ | ✅ | Why the previous run exited (Android 11+ ApplicationExitInfo); also MsgALog "Previous exit:" at startup under LOGGING. See [msga/exit-diagnostics.md](../msga/exit-diagnostics.md). Added 2026-07-09 (v1.5.40). |
 | info | ❌ | ❌ | ✅ | `MsgHostInfo`: host, version, platform, updateUrl |
 | updateUrl | ❌ | ❌ | ✅ | URL to versions.json — install source for update checks |
 | version | ❌ | ❌ | ✅ | `window.msgapi.version` = app version string |

package/msgapidefs.ts

@@ -65,6 +65,24 @@ export interface MsgApkInfo {     // One APK entry in versions.json
     default?: boolean;            // True if this is the default APK
 }
 
+// Why the previous app process died — from Android ApplicationExitInfo (OS-recorded, survives process death)
+// NOTE: records cover EVERY process in the package, including the sandboxed WebView renderer
+// (processName contains ":sandboxed_process") — renderer deaths like "isolated not needed" are
+// routine cleanup, not the app dying. Filter/dim by processName to find real main-process exits.
+export interface MsgExitInfo {
+    timestamp: number;        // Exit time, ms since epoch
+    reason: string;           // "LowMemory" | "Crash" | "CrashNative" | "Anr" | "Freezer" | "ExitSelf" | "Signaled" | "UserRequested" | "UserStopped" | "DependencyDied" | "InitializationFailure" | "PermissionChange" | "ExcessiveResourceUsage" | "PackageStateChange" | "PackageUpdated" | "Other" | "Unknown"
+    description?: string;     // OS-provided detail (may be null/absent), e.g. "isolated not needed" for renderer cleanup
+    importance?: string;      // Process state at death (e.g. "Foreground", "Cached") — cached kills are normal memory reclaim
+    pss?: number;             // Proportional set size at exit, KB
+    rss?: number;             // Resident set size at exit, KB
+    processName?: string;     // Which process died — main package name, or ":sandboxed_process..." = WebView renderer
+    pid?: number;             // Process ID at exit
+    status?: number;          // Exit status: signal number for "Signaled", exit code for "ExitSelf", 0 otherwise
+    stateSummary?: string;    // App-set marker (msga stamps "start=<ISO time> v=<version>" each run → compute uptime at death)
+    trace?: string;           // First ~4KB of ANR/native-crash trace when the OS captured one (reason "Anr"/"CrashNative")
+}
+
 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)
@@ -85,6 +103,14 @@ export interface MsgAPI {
     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)
 
+    // ── Diagnostics ─────────────────────────────────────────────
+    // Why did the previous run exit? OS records the last few process deaths;
+    // read them on the next run to distinguish crash / ANR / low-memory kill / freezer.
+
+    diag?: {
+        getExitReasons(max?: number): Promise<MsgExitInfo[]>;  // Previous-run exit records, newest first (default max 5). msga Android 11+ only; [] elsewhere.
+    };
+
     // ── Window Control ──────────────────────────────────────────
 
     toggleFullscreen(): void;                      // Toggle fullscreen mode on/off

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/msgapidefs",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "TypeScript definitions for msgapi JavaScript API (msgview/msger)",
   "type": "module",
   "main": "./msgapidefs.js",
@@ -33,6 +33,7 @@
     "prerelease:local": "git add -A && (git diff-index --quiet HEAD || git commit -m \"Pre-release commit\")",
     "preversion": "git add -A",
     "release": "npm run prerelease:local && npm version patch && npm publish --quiet",
+    "build": "tsc",
     "postversion": "git push && git push --tags"
   },
   "devDependencies": {

package/tsconfig.json

@@ -1,5 +1,6 @@
 {
-    "compilerOptions": {
+    "compilerOptions": {
+        "types": ["node"],
         "target": "ES2020",
         "module": "ES2020",
         "lib": ["ES2020", "DOM"],