@bobfrankston/msgapidefs 0.1.40 → 0.1.42

package/.commitmsg

@@ -0,0 +1,9 @@
+Add msgapi.dns.lookup; document that udp host may be a hostname
+
+- `dns?: { lookup(hostname, { family?, timeoutMs? }) }` with `MsgDnsAddress` /
+  `MsgDnsLookupOptions`. Resolves to [{address, family}] (v4 first, never empty) or
+  rejects with error.code 'ENOTFOUND' / 'ETIMEOUT'. msger + msga; msgview on demand.
+- udp.send / udp.sendReceive: `host` documented as IP literal OR hostname, resolved in
+  the host by the same resolver. (The hosts always resolved names; it was undocumented.)
+- README: DNS section + platform matrix row; msgapi-plan.md status rows.
+  Requirements: msgx/dnsrequest.md (2026-09-17, Claude Code at Bob's direction).

package/README.md

@@ -135,8 +135,10 @@ nothing about capability.
 | `shell.open()` | ❌ | ❌ | ✅ | Android: Intent.ACTION_VIEW; Windows: ShellExecute |
 | `shell.showInFolder()` | ❌ | ❌ | ❌ | Defined in interface, not yet implemented |
 | `shell.trash()` | ❌ | ❌ | ❌ | Defined in interface, not yet implemented |
+| **DNS** | | | | **`window.msgapi.dns.*`** (added 2026-09-17) |
+| `dns.lookup()` | ❌ | ✅ | ✅ | Rust `ToSocketAddrs` (getaddrinfo) / C# `System.Net.Dns`; 2 s default timeout, 30 s cache. msger after 0.1.431, msga 1.5.53+. msgview: on demand |
 | **UDP Networking** | | | | **`window.msgapi.udp.*`** |
-| `udp.send()` | ✅ | ✅ | ✅ | Node dgram / Rust UdpSocket / C# UdpClient |
+| `udp.send()` | ✅ | ✅ | ✅ | Node dgram / Rust UdpSocket / C# UdpClient. `host` = IP **or hostname** |
 | `udp.listen()` | ✅ | ✅ | ✅ | Background receive loop in all hosts |
 | `udp.sendReceive()` | ✅ | ✅ | ✅ | Send + wait with timeout |
 | `udp.broadcast()` | ✅ | ✅ | ✅ | 255.255.255.255 broadcast |
@@ -216,7 +218,21 @@ for (const e of exits) {
 
 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.
+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, plus one `Relaunched <gap> after previous exit: ...` line per start (held until logging is turned on). See [msga/exit-diagnostics.md](../msga/exit-diagnostics.md) for the full design notes.
+
+**Staying alive / coming back** (msga Android; other hosts resolve `'n/a'`):
+
+- `diag.getInstallInfo()` - Returns `MsgInstallInfo`: `installer` / `selfInstalled` (whether the next update can be silent), `canDrawOverlays`, `canInstallPackages`, `isHomeApp` (1.5.52+), `sdkInt`.
+- `diag.requestHome()` - Make msga the device's **Home app**. Android relaunches the Home app after *any* process death — self-update, System WebView update, crash, low-memory kill — with no other permission. On Android 10+ this shows the system's own one-button "Set as default Home app?" confirmation and resolves `'granted'` / `'denied'`; older Android opens the Home-settings list (`'opened'`). `'already'` if it is Home already. Recommended one-time step for a wall panel; a web app can offer it whenever `isHomeApp` is false. (msga 1.5.52+)
+- `diag.requestOverlay()` - Opens the "Display over other apps" settings page (`'already'` / `'opened'`). The older alternative: with the grant, the post-self-update relaunch is allowed to reach the foreground, but it does nothing for a WebView-update kill. Prefer `requestHome()`.
+
+```javascript
+// Panel setup: one tap, Android's own dialog
+const info = await window.msgapi?.diag?.getInstallInfo?.();
+if (info && info.isHomeApp === false) {
+    const r = await window.msgapi.diag.requestHome();   // 'granted' | 'denied' | 'opened' | ...
+}
+```
 
 ### Window Control
 
@@ -247,10 +263,39 @@ Direct path operations (give the webview full filesystem access — msga only cu
 
 > **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.
 
+### DNS
+
+Page script cannot resolve a hostname — a browser resolves names only inside its own requests and
+never hands the address back. The host can. (Added 2026-09-17 by Claude Code; requirements in
+[../dnsrequest.md](../dnsrequest.md).)
+
+- `dns.lookup(hostname, { family?, timeoutMs? })` - Resolves to `[{ address, family }]`, IPv4 first,
+  **never empty**; rejects otherwise. `family` (4 | 6) restricts the answer. `timeoutMs` defaults to 2000.
+  An IP literal resolves to itself.
+- Rejections carry `error.code`: `'ENOTFOUND'` (no such name, or no address of the requested family)
+  or `'ETIMEOUT'` (resolver silent for `timeoutMs`). The message names the hostname and the resolver's reason.
+- Answers are cached in the host for 30 s (the platform resolvers do not expose the record TTL).
+  "No such host" is cached the same way (a cold negative lookup was measured at ~2.1 s on Windows — without
+  this every command to a vanished name would wait out the timeout before the caller's IP fallback);
+  a timeout is not an answer and is never cached. A cached name answers instantly, so `timeoutMs` only bounds an uncached lookup.
+- Absent (`window.msgapi?.dns?.lookup` undefined) in a plain browser, msgview, and older hosts —
+  callers fall back to the address they already have.
+
+```ts
+const found = await window.msgapi?.dns?.lookup('wiz_7c47f4.aaz.lt').catch(() => null);
+const ip = found?.[0].address ?? fallbackIp;
+```
+
 ### UDP Networking
 
 Native UDP socket access — no WebSocket proxy needed when running inside a msgapi host.
 
+`host` in `udp.send` / `udp.sendReceive` is an IP literal **or a hostname**. A hostname is resolved in
+the host process by the same resolver as `dns.lookup` (timeout, cache) before the datagram leaves; one
+that does not resolve rejects with `error.code` `'ENOTFOUND'` / `'ETIMEOUT'`. (Both hosts always
+resolved names here — the platform send calls do it — but it was undocumented and had no timeout,
+cache or typed error before 2026-09-17.) Sockets are IPv4; a name with only IPv6 addresses rejects in msga.
+
 - `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

package/msgapi-plan.md

@@ -40,8 +40,10 @@ Shared planning document for msgapi across implementations:
 | shell.open() | ❌ | ❌ | ✅ | Android: Intent.ACTION_VIEW; Windows: ShellExecute |
 | shell.showInFolder() | ❌ | ❌ | ❌ | Defined in interface, not yet implemented |
 | shell.trash() | ❌ | ❌ | ❌ | Defined in interface, not yet implemented |
+| **DNS** (2026-09-17) |
+| dns.lookup() | ❌ | ✅ | ✅ | getaddrinfo via Rust std / C# System.Net.Dns; 2 s timeout, 30 s cache, ENOTFOUND/ETIMEOUT codes. See README. |
 | **UDP** |
-| udp.send() | ✅ | ✅ | ✅ | Node dgram / Rust UdpSocket / C# UdpClient |
+| udp.send() | ✅ | ✅ | ✅ | Node dgram / Rust UdpSocket / C# UdpClient. host = IP or hostname (msger/msga share the dns.lookup resolver) |
 | udp.listen() | ✅ | ✅ | ✅ | Background receive loop in all hosts |
 | udp.sendReceive() | ✅ | ✅ | ✅ | Send + wait with timeout |
 | udp.broadcast() | ✅ | ✅ | ✅ | 255.255.255.255 broadcast |

package/msgapidefs.d.ts

@@ -0,0 +1,194 @@
+export interface MsgResult {
+    button: string;
+    value?: string;
+    form?: Record<string, any>;
+    closed?: boolean;
+    dismissed?: boolean;
+    timeout?: boolean;
+}
+export interface FileInfo {
+    name: string;
+    path: string;
+    isDir: boolean;
+    size: number;
+    modified?: string;
+    created?: string;
+    attributes?: number;
+}
+export interface FileDialogOptions {
+    title?: string;
+    defaultFilename?: string;
+    filters?: Array<{
+        name: string;
+        extensions: string[];
+    }>;
+    defaultPath?: string;
+}
+export interface SelectedFile {
+    name: string;
+    path: string;
+    content: string;
+}
+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: MsgHost;
+    version: string;
+    platform: MsgPlatform;
+    appName?: string;
+    updateUrl?: string;
+    apkUrl?: string;
+    localIp?: string;
+    localMask?: string;
+}
+export interface MsgApkInfo {
+    name: string;
+    url: string;
+    description: string;
+    icon: string;
+    file: string;
+    sizeMB: number;
+    built: string;
+    default?: boolean;
+}
+export interface MsgExitInfo {
+    timestamp: number;
+    reason: string;
+    description?: string;
+    importance?: string;
+    pss?: number;
+    rss?: number;
+    processName?: string;
+    pid?: number;
+    status?: number;
+    stateSummary?: string;
+    trace?: string;
+}
+export interface MsgVersionInfo {
+    version: string;
+    buildDate: string;
+    apks: MsgApkInfo[];
+}
+/** Why an update prompted, and whether the post-update relaunch can reach the foreground.
+ *  Android permits a silent self-update only when the updating app is the installer of record, so
+ *  a browser or adb sideload makes the NEXT update prompt (selfInstalled false). Separately, a
+ *  background process may not start an activity without canDrawOverlays, which is why a silent
+ *  update can leave the user on the home screen. */
+export interface MsgInstallInfo {
+    package: string;
+    installer: string;
+    selfInstalled: boolean;
+    canDrawOverlays: boolean;
+    canInstallPackages: boolean;
+    isHomeApp?: boolean;
+    sdkInt: number;
+}
+/** Handle returned by udp.listen(). send/broadcast leave from this listener's own socket, so the
+ *  device's reply arrives back at this listener rather than at whichever one registered first.
+ *  send/broadcast are optional: msga builds before 1.5.45 return a handle with only close(). */
+export interface UdpListenHandle {
+    close(): void;
+    send?(host: string, port: number, data: string | Uint8Array): Promise<void>;
+    broadcast?(port: number, data: string | Uint8Array): Promise<void>;
+}
+/** One address from dns.lookup(). */
+export interface MsgDnsAddress {
+    address: string;
+    family: 4 | 6;
+}
+/** Options for dns.lookup(). */
+export interface MsgDnsLookupOptions {
+    family?: 4 | 6;
+    timeoutMs?: number;
+}
+export interface MsgAPI {
+    version?: string;
+    updateUrl?: string;
+    info?: MsgHostInfo;
+    setLogging?(value?: LoggingMode, name?: string): LoggingMode;
+    setAutoUpdate?(value?: AutoUpdateMode): AutoUpdateMode;
+    installUpdate?(url: string): Promise<void>;
+    getNetworkInfo?(): Promise<{
+        localIp: string;
+        localMask: string;
+    }>;
+    diag?: {
+        getExitReasons(max?: number): Promise<MsgExitInfo[]>;
+        getInstallInfo?(): Promise<MsgInstallInfo>;
+        requestOverlay?(): Promise<'already' | 'opened' | 'n/a'>;
+        requestHome?(): Promise<'already' | 'granted' | 'denied' | 'opened' | 'n/a'>;
+    };
+    toggleFullscreen(): void;
+    setFullscreen(enabled: boolean): void;
+    minimize(): void;
+    maximize(): void;
+    setSize(width: number, height: number): void;
+    setPosition(x: number, y: number): void;
+    setAlwaysOnTop(enabled: boolean): void;
+    close(result?: Partial<MsgResult>): void;
+    fs?: {
+        selectFile(options?: FileDialogOptions): Promise<SelectedFile | null>;
+        selectFiles(options?: FileDialogOptions): Promise<SelectedFile[]>;
+        saveFileAs(content: string, defaultFilename?: string, options?: FileDialogOptions): Promise<string | null>;
+        selectFolder(options?: FileDialogOptions): Promise<string | null>;
+        read(path: string, options?: {
+            encoding?: 'utf8' | 'base64' | 'binary';
+        }): Promise<string | Uint8Array>;
+        readAsDataUrl(path: string, mimeType?: string): Promise<string>;
+        write(path: string, content: string): Promise<void>;
+        list(path: string): Promise<FileInfo[]>;
+        exists(path: string): Promise<boolean>;
+        delete(path: string): Promise<void>;
+    };
+    dns?: {
+        /** Resolve a hostname in the host process. Resolves to at least one address (v4 first), or
+         *  REJECTS — never an empty success. The Error's `code` is 'ENOTFOUND' (no such name / no
+         *  address of the requested family) or 'ETIMEOUT' (resolver did not answer within timeoutMs);
+         *  the message names the hostname and the resolver's reason. An IP literal resolves to itself.
+         *  Answers are cached in the host for ~30 s. msger after 0.1.431, msga 1.5.53+. */
+        lookup(hostname: string, opts?: MsgDnsLookupOptions): Promise<MsgDnsAddress[]>;
+    };
+    udp?: {
+        send(host: string, port: number, data: string | Uint8Array): Promise<void>;
+        listen(port: number, callback: (data: Uint8Array, sender: {
+            host: string;
+            port: number;
+        }) => void): Promise<UdpListenHandle>;
+        sendReceive(host: string, port: number, data: string | Uint8Array, timeoutMs?: number): Promise<Uint8Array>;
+        broadcast(port: number, data: string | Uint8Array): Promise<void>;
+    };
+    tcp?: {
+        connect(host: string, port: number, tls: boolean): Promise<number>;
+        write(streamId: number, data: string): Promise<void>;
+        onData(streamId: number, callback: (data: string) => void): void;
+        onClose(streamId: number, callback: (hadError: boolean) => void): void;
+        onError(streamId: number, callback: (message: string) => void): void;
+        upgradeTLS(streamId: number, servername: string): Promise<void>;
+        close(streamId: number): void;
+    };
+    http?: {
+        fetch(url: string, init?: RequestInit): Promise<Response>;
+    };
+    shell?: {
+        exec(command: string, args?: string[], options?: {
+            cwd?: string;
+            timeout?: number;
+            stdin?: string;
+            encoding?: 'utf8' | 'base64';
+        }): Promise<{
+            stdout: string;
+            stderr: string;
+            exitCode: number;
+        }>;
+        open(path: string): Promise<void>;
+        showInFolder(path: string): Promise<void>;
+        trash(path: string): Promise<void>;
+    };
+}
+declare global {
+    interface Window {
+        msgapi?: MsgAPI;
+    }
+}

package/msgapidefs.js

@@ -0,0 +1,8 @@
+// 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 {};

package/msgapidefs.ts

@@ -101,6 +101,7 @@ export interface MsgInstallInfo {
     selfInstalled: boolean;     // true => next update can be silent
     canDrawOverlays: boolean;   // true => post-update relaunch is allowed to foreground
     canInstallPackages: boolean;// "Install unknown apps" for this app
+    isHomeApp?: boolean;        // true => msga is the device's Home app: Android relaunches it after ANY process death (msga 1.5.52+)
     sdkInt: number;
 }
 
@@ -113,6 +114,18 @@ export interface UdpListenHandle {
     broadcast?(port: number, data: string | Uint8Array): Promise<void>;
 }
 
+/** One address from dns.lookup(). */
+export interface MsgDnsAddress {
+    address: string;            // Literal address, e.g. "172.20.1.42" or "fe80::1"
+    family: 4 | 6;
+}
+
+/** Options for dns.lookup(). */
+export interface MsgDnsLookupOptions {
+    family?: 4 | 6;             // Restrict the answer to one family; default = both, v4 first
+    timeoutMs?: number;         // Bounded wait for the resolver (default 2000)
+}
+
 export interface MsgAPI {
 
     version?: string;  // Host app version (e.g. "1.3.0") — semver string, compare numerically not lexicographically
@@ -134,6 +147,7 @@ export interface MsgAPI {
         getExitReasons(max?: number): Promise<MsgExitInfo[]>;  // Previous-run exit records, newest first (default max 5). msga Android 11+ only; [] elsewhere.
         getInstallInfo?(): Promise<MsgInstallInfo>;   // Installer of record + permission state (msga 1.5.48+)
         requestOverlay?(): Promise<'already' | 'opened' | 'n/a'>;  // Open the Display-over-other-apps settings page
+        requestHome?(): Promise<'already' | 'granted' | 'denied' | 'opened' | 'n/a'>;  // Make msga the Home app: system one-button confirmation (Android 10+), settings list before. Home app = automatic relaunch after self-update / WebView update / crash. msga 1.5.52+
     };
 
     // ── Window Control ──────────────────────────────────────────
@@ -162,8 +176,25 @@ export interface MsgAPI {
         delete(path: string): Promise<void>;          // Delete file or directory (requires allowFs)
     };
 
+    // ── DNS ─────────────────────────────────────────────────────
+    // 2026-09-17 — Claude Code (Fable 5.1), at Bob's direction (dnsrequest.md). Page script cannot
+    // resolve a name itself; the host can. Absent (plain browser, older host) = "not available":
+    // callers fall back to the address they already have.
+
+    dns?: {
+        /** Resolve a hostname in the host process. Resolves to at least one address (v4 first), or
+         *  REJECTS — never an empty success. The Error's `code` is 'ENOTFOUND' (no such name / no
+         *  address of the requested family) or 'ETIMEOUT' (resolver did not answer within timeoutMs);
+         *  the message names the hostname and the resolver's reason. An IP literal resolves to itself.
+         *  Answers are cached in the host for ~30 s. msger after 0.1.431, msga 1.5.53+. */
+        lookup(hostname: string, opts?: MsgDnsLookupOptions): Promise<MsgDnsAddress[]>;
+    };
+
     // ── UDP Networking ──────────────────────────────────────────
     // Native UDP — no httpudp WebSocket proxy needed
+    // `host` is an IP literal OR a hostname. A hostname is resolved in the host process (same
+    // resolver, timeout and cache as dns.lookup) before the datagram leaves; one that does not
+    // resolve rejects with code 'ENOTFOUND' / 'ETIMEOUT' so the caller can fall back to an address.
 
     udp?: {
         send(host: string, port: number, data: string | Uint8Array): Promise<void>;  // Send UDP packet to host:port

package/npmchanges.md

@@ -0,0 +1,6 @@
+# npm Publish Changes
+
+## v0.1.41 — 2026-09-14
+
+diag.requestHome() and MsgInstallInfo.isHomeApp (msga 1.5.52): make msga the device's Home app via Android's own confirmation dialog so relaunch after self-update / WebView update / crash is automatic; README Diagnostics documents getInstallInfo/requestHome/requestOverlay and the per-start "Relaunched <gap>" log line.
+

package/package.json

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

package/tsconfig.json

@@ -2,7 +2,7 @@
     "compilerOptions": {
         "types": ["node"],
         "target": "ES2020",
-        "module": "ES2020",
+        "module": "NodeNext",
         "lib": ["ES2020", "DOM"],
         "declaration": true,
         "outDir": ".",
@@ -11,7 +11,7 @@
         "esModuleInterop": true,
         "skipLibCheck": true,
         "forceConsistentCasingInFileNames": true,
-        "moduleResolution": "node",
+        "moduleResolution": "NodeNext",
         "newLine": "lf"
     },
     "include": ["msgapidefs.ts"],