@bobfrankston/msger 0.1.387 → 0.1.388

package/README.md

@@ -118,6 +118,40 @@ Notes:
 - The two `requestAnimationFrame` calls let layout settle before reading computed style — needed for `contrast-color`, gradients, etc.
 - The original `-noshow -save` behavior is unchanged: it still exits after saving without ever creating a WebView.
 
+### Render mode (`-render`) — capture the page to an image
+
+`-render` turns msger into a headless page→bitmap renderer: no window ever appears; the page loads, settles, gets screenshotted, and msger exits. Windows (WebView2) only for now.
+
+```bash
+# Write a PNG of a web page (format follows the extension: .png/.jpg/.bmp)
+msger -url "https://example.com" -size 1024,768 -render page.png
+
+# Render inline HTML (charts, badges, generated markup)
+msger -html "<h1 style='color:steelblue'>Build OK</h1>" -size 400,150 -render status.png
+
+# No file → the image comes back base64 in the JSON result
+msger -message "hello" -render
+# → { "button": "render", "render": { "format": "png", "data": "iVBOR...", "width": 500, "height": 375 } }
+```
+
+The Node API mirrors this:
+
+```typescript
+// Write a file; result.render = { path, width, height, format }
+await showMessageBox({ url: "https://example.com", size: { width: 1024, height: 768 }, render: "page.png" });
+
+// Or get the image as an object; result.render = { data (base64), width, height, format }
+const result = await showMessageBox({ html: "<h1>Chart</h1>", render: true });
+fs.writeFileSync("out.png", Buffer.from(result.render!.data!, "base64"));
+```
+
+Notes:
+- The capture fires after the page's `load` event + two `requestAnimationFrame`s + a settle delay (`renderDelay` option, default 100ms). If the page never fires `load`, msger captures best-effort at the timeout (default 30s in render mode).
+- Width/height are physical pixels — a 400×300 window on a 125% DPI display captures at 500×375.
+- `renderFormat` (`png`/`jpeg`/`bmp`) can be set explicitly in the API; the CLI derives it from the file extension.
+- A failed capture rejects the promise (CLI: error on stderr, nonzero exit).
+- msgview supports the same `-render` option via Electron's `capturePage()` on all its platforms.
+
 ## JSON Configuration Files
 
 You can store message box configuration in a JSON file for reuse. JSON files support comments (JSON5 format).
@@ -290,6 +324,9 @@ Options:
   -fullscreen, --fullscreen       Start window in fullscreen mode (F11 to toggle, Escape to exit)
   -raw, --raw                     With -html: load HTML as-is, no msger template/buttons (alias: -full)
   -debug, --debug                 Return debug info (HTML, size, autoSize) in result
+  -render, --render [file]        Render the page to a bitmap instead of displaying it.
+                                  With <file>, writes the image (.png/.jpg/.bmp by extension);
+                                  without, returns it base64 in result.render. [Windows only]
   -noshow, --noshow               Don't display the window. With -save, exits after saving.
                                   Otherwise the WebView still loads + runs scripts so a page
                                   can post a result via window.ipc.postMessage; only the
@@ -432,6 +469,10 @@ interface MessageBoxOptions {
     rawHtml?: boolean;        // With html: load HTML as-is, no msger template/buttons (used by mdview). CLI: -raw
     debug?: boolean;          // Return debug info (HTML, size, autoSize) in result
     noResult?: boolean;       // Suppress JSON result on stdout (CLI: -noresult, -result re-enables)
+    render?: boolean | string; // Render to a bitmap instead of displaying. String = file to write
+                               // (format from extension), true = base64 object in result.render.
+    renderDelay?: number;     // Render mode: ms between page load and capture (default 100)
+    renderFormat?: string;    // Render mode: png (default) | jpeg | bmp
 }
 ```
 
@@ -460,6 +501,14 @@ interface MessageBoxResult {
         height: number;   // Window height
         autoSize: boolean; // Whether auto-sizing is enabled
     };
+    render?: {            // Captured screenshot (render mode)
+        format: string;   // png | jpeg | bmp
+        width: number;    // Physical pixels (includes DPI scale)
+        height: number;
+        data?: string;    // Base64 image bytes (render: true)
+        path?: string;    // Absolute path of written file (render: "file")
+    };
+    renderError?: string; // Why render produced no image (the promise rejects with this)
 }
 ```
 

package/cli.js

@@ -40,6 +40,12 @@ Options:
   -ontop                  Keep window always on top of other windows
   -load <file>            Load options from JSON file (supports comments)
   -save <file>            Save current options to JSON file
+  -render [file]          Render to a bitmap instead of displaying a window. Waits for
+                          the page to load, captures a screenshot, and exits — nothing
+                          appears on screen. With <file>, writes the image there (format
+                          from extension: .png/.jpg/.bmp) and the JSON result carries
+                          {render:{path,width,height,format}}. Without <file>, the image
+                          is returned base64 in {render:{data,...}}. [Windows only]
   -noshow                 Don't display the window. With -save, also exits after saving.
                           Otherwise the WebView still loads and runs scripts (so a page can
                           query the DOM/CSS and post a result via window.ipc.postMessage)
@@ -70,6 +76,10 @@ Examples:
   echo -e "\\x1b[31mError:\\x1b[0m Something failed" | msger
   echo '{"message":"Test","buttons":["OK"]}' | msger
 
+  # Render a page to an image without showing a window
+  msger -url "https://example.com" -size 1024,768 -render page.png
+  msger -html "<h1>Chart</h1>" -render chart.png
+
   # Headless evaluation — use the WebView as a CSS/JS engine, no UI
   msger -noshow -html "<div id=x style='color:contrast-color(steelblue)'></div><script>requestAnimationFrame(()=>requestAnimationFrame(()=>window.ipc.postMessage(JSON.stringify({button:'x',value:getComputedStyle(document.getElementById('x')).color}))))</script>" -result value
 

package/index.d.ts

@@ -1 +1 @@
-export { showMessageBox, showMessageBoxEx, MessageBoxHandle, closeMessageBox, showService, ServiceHandle, MessageBoxOptions, MessageBoxResult, setAppName, setAppIcon } from "./shower.js";
+export { showMessageBox, showMessageBoxEx, MessageBoxHandle, closeMessageBox, showService, ServiceHandle, MessageBoxOptions, MessageBoxResult, RenderResult, setAppName, setAppIcon } from "./shower.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/msger",
-  "version": "0.1.387",
+  "version": "0.1.388",
   "description": "Fast, lightweight, cross-platform message box - Rust-powered alternative to msgview",
   "type": "module",
   "main": "./index.js",

package/shower.d.ts

@@ -51,6 +51,19 @@ export interface MessageBoxOptions {
     service?: boolean; /** Service mode: bidirectional IPC with parent. Stdin/stdout stay open. */
     contentDir?: string; /** Base directory for custom protocol file serving (avoids file:// URLs) */
     hidden?: boolean; /** Create the window invisible. The WebView still renders so JS / CSS / layout queries (e.g. `getComputedStyle`, `contrast-color()`) resolve; the window just isn't mapped on screen. Set by the CLI's `-noshow` flag. */
+    render?: boolean | string; /** Render to a bitmap instead of displaying. The window stays hidden; after the page loads (plus renderDelay) a screenshot is captured and msger exits. A string is a file path to write — format from extension (.png/.jpg/.jpeg/.bmp), result.render = {format,width,height,path}. `true` returns the image in result.render = {format,width,height,data(base64)}. Windows (WebView2) only for now. */
+    renderDelay?: number; /** Render mode: settle delay in ms between the page's load event and the capture (fonts/images/async paint). Default 100. */
+    renderFormat?: string; /** Render mode image format: png (default), jpeg, or bmp. Derived from the file extension when `render` is a path; settable directly when `render: true`. */
+}
+/** Screenshot returned in MessageBoxResult.render (render mode). Width/height
+ *  are physical pixels — the capture includes the monitor's DPI scale, so a
+ *  400x300 logical window on a 125% display comes back 500x375. */
+export interface RenderResult {
+    format: string; /** png | jpeg | bmp */
+    width: number; /** Physical pixel width */
+    height: number; /** Physical pixel height */
+    data?: string; /** Base64 image bytes (render: true) */
+    path?: string; /** Absolute path of the written file (render: "file") */
 }
 export interface MessageBoxResult {
     button: string;
@@ -65,6 +78,8 @@ export interface MessageBoxResult {
         height: number;
         autoSize: boolean;
     };
+    render?: RenderResult; /** Captured screenshot (render mode) */
+    renderError?: string; /** Why render mode produced no image — the result promise rejects with this */
 }
 /** Set the app name used for the per-user bin dir AND the per-app exe filename.
  *  Call before showService/showMessageBox — e.g. `setAppName("mailx")` makes

package/shower.js

@@ -362,6 +362,13 @@ function resolveBinaryPath() {
 }
 function createMessageBoxHandle(options) {
     const binaryPath = resolveBinaryPath();
+    // Render mode: string = write the image to this file, true = return it
+    // base64 in result.render. Either way the image travels back as base64
+    // JSON on stdout, which detach mode throws away — so the combo is an error.
+    const renderTarget = typeof options.render === 'string' ? path.resolve(options.render) : undefined;
+    if (options.render && options.detach) {
+        throw new Error('render cannot be combined with detach — the image comes back on stdout, which detach discards');
+    }
     // Validate the binary up front and synchronously. Doing this inside the
     // Promise executor used to leave `child` undefined when the binary was
     // missing, then `new MessageBoxHandle(child, ...)` blew up on `child.pid`
@@ -421,6 +428,23 @@ function createMessageBoxHandle(options) {
             }
             try {
                 const result = JSON.parse(stdout.trim());
+                if (options.render) {
+                    if (result.renderError || !result.render?.data) {
+                        reject(new Error(`render failed: ${result.renderError || 'no image in result'}`));
+                        return;
+                    }
+                    if (renderTarget) {
+                        // Write the file and hand back a path instead of the
+                        // (large) base64 payload.
+                        fs.writeFileSync(renderTarget, Buffer.from(result.render.data, 'base64'));
+                        result.render = {
+                            format: result.render.format,
+                            width: result.render.width,
+                            height: result.render.height,
+                            path: renderTarget
+                        };
+                    }
+                }
                 resolve(result);
             }
             catch (error) {
@@ -443,6 +467,19 @@ function createMessageBoxHandle(options) {
             if (optionsToSend.autoSize === undefined && !optionsToSend.size) {
                 optionsToSend.autoSize = true;
             }
+            // Render mode: Rust wants a bare boolean plus a format string; the
+            // file path (if any) stays on this side. Force hidden so no window
+            // ever flashes on screen.
+            if (optionsToSend.render) {
+                if (renderTarget && !optionsToSend.renderFormat) {
+                    const ext = path.extname(renderTarget).toLowerCase();
+                    optionsToSend.renderFormat =
+                        ext === '.bmp' ? 'bmp' :
+                            (ext === '.jpg' || ext === '.jpeg') ? 'jpeg' : 'png';
+                }
+                optionsToSend.render = true;
+                optionsToSend.hidden = true;
+            }
             // Convert ANSI escape sequences to HTML if message is provided
             // ansi-to-html will escape HTML characters and convert ANSI codes to colored spans
             // Only do this if the message contains actual ANSI codes to preserve plain text as-is