@bobfrankston/winpos 2.0.52 → 2.0.53

package/README.md

@@ -1,213 +1,296 @@
-# @bobfrankston/winpos
-
-TypeScript implementation of WinPos - A Windows window positioning utility for multi-monitor setups.
-
-## Features
-
-- **Cross-Runtime**: Works with both Node.js (24+) and Bun
-- **FFI-based**: Direct Windows API calls via `koffi` (Node.js) or `bun:ffi` (Bun)
-- **Multi-Monitor**: Full support for multiple displays
-- **Flexible Matching**: Find windows by exact title, prefix, or regex
-- **Window State Management**: Minimize, maximize, restore windows programmatically
-- **Auto-Restore**: Windows are automatically restored from minimized/maximized state when positioning
-- **Library or CLI**: Use as a command-line tool or import as a library
-
-## Installation
-
-```bash
-npm install @bobfrankston/winpos
-```
-
-Or with Bun:
-
-```bash
-bun add @bobfrankston/winpos
-```
-
-## Usage
-
-### Command Line
-
-```bash
-# Move window to screen 0 at position (100, 200)
-winpos "Notepad" 100 200 0
-
-# Move window using percentages
-winpos "Chrome*" 50% 50% 1
-
-# Set window size as well
-winpos "Visual Studio Code" 0 0 0 1920 1080
-
-# List all windows
-winpos *
-
-# Get screen count
-winpos -c
-
-# Debug mode
-winpos -d "Firefox" 0 0 1
-```
-
-### Pattern Matching
-
-- **Exact match**: `winpos "Notepad" 0 0 0`
-- **Prefix match**: `winpos "Chrome*" 0 0 0`
-- **Regex match**: `winpos "/Visual.*Code/" 0 0 0`
-
-### As a Library
-
-```typescript
-import { run } from '@bobfrankston/winpos';
-
-// Move a window programmatically
-run(['Chrome*', '0', '0', '1', '1920', '1080']);
-```
-
-## Screen Numbering
-
-Screens are numbered starting from 0, sorted by position:
-
-```
-  +---+---+
-  | 2 | 3 |
-  +---+---+
-  | 0 | 1 |
-  +---+---+
-```
-
-- 0: Lower right (primary)
-- 1: Lower left
-- 2: Upper left
-- 3: Upper right
-
-## Options
-
-- `-d` - Debug mode
-- `-dbg` - Verbose debug output
-- `-c` - Return screen count
-- `-v` / `-version` - Show version
-- `-title <name>` - Window title/pattern (alternative to positional)
-- `-pos x,y[,screen]` - Position (comma-separated, screen optional)
-- `-size w,h` - Window size (width,height)
-- `-numsize <inches>` - Physical size of the screen-number overlays (default 2)
-- `-min` - Minimize window
-- `-max` - Maximize window
-- `-load <file>` - Load config from JSON file
-- `-save <file>` - Save config to JSON file (merges if exists)
-- `*` - List all windows
-- `**` - List all windows including ignored
-
-## Identifying Screens
-
-`winpos` with no arguments, and `winpos *` (or `**`), flash each screen's number
-in the middle of that screen for 5 seconds - the same idea as the Identify
-button in Windows display settings, so you can see which physical monitor is
-screen 0, 1, 2 ... before positioning anything there. With no arguments the
-numbers come up alongside the usage text and its screen table.
-
-The numbers are drawn with [msger](https://www.npmjs.com/package/@bobfrankston/msger)
-and all appear at once. They close themselves; winpos returns immediately
-without waiting for them. If msger is unavailable the listing still works, just
-without the numbers.
-
-Each overlay is 2 inches square **on the glass**, not 2 inches' worth of pixels
-- `-numsize <inches>` changes that. Sizing anything in pixels (or in CSS
-inches, which are just 96 pixels) comes out a different physical size on every
-monitor, because Windows' scale factor is a preference rather than a
-measurement: a 28" 4K panel left at 100% claims 96 DPI while really being 160.
-winpos asks the display driver for the panel's physical millimetres (EDID, via
-a GDI display DC) and works out each screen's true DPI, so the same square of
-glass lights up on every monitor. Drivers that report nothing fall back to the
-old pixel sizing.
-
-```typescript
-import { showScreenNumbers, enumerateScreens, sortScreens, screenDpi } from '@bobfrankston/winpos';
-
-const screens = sortScreens(enumerateScreens());
-await showScreenNumbers(screens, 5, 2);     // 5 seconds, 2 inches
-console.log(screens.map(screenDpi));        // True DPI per screen
-```
-
-## Parameters
-
-### Positional (legacy)
-```
-winpos <title> <x> <y> <screen> [<width> <height>]
-```
-
-### Flag-based (new)
-```
-winpos <title> -pos x,y[,screen] [-size w,h]
-winpos -title <name> -pos x,y,screen -size w,h
-winpos <title> -min
-```
-
-### JSON Config
-```
-winpos layout.json
-winpos -load layout.json [-save output.json]
-```
-
-## JSON Config Format
-
-Single window:
-```json
-{
-  "name": "Notepad",
-  "pos": { "x": 100, "y": 100, "screen": 0 },
-  "size": { "w": 800, "h": 600 }
-}
-```
-
-Multiple windows:
-```json
-[
-  { "name": "app1", "pos": { "x": 0, "y": 0, "screen": 0 } },
-  { "name": "app2*", "pos": { "x": 100, "y": 100, "screen": 1 } },
-  { "name": "pattern", "regex": true, "pos": { "x": 0, "y": 0, "screen": 2 } },
-  { "name": "minimize-me", "minimize": true }
-]
-```
-
-- `name` - Window title (exact match, prefix with `*`, or regex if `regex: true`)
-- `regex` - If true, `name` is treated as a regex pattern
-- `pos` - Position with x, y, and optional screen index
-- `size` - Size with w (width) and h (height)
-- `minimize` / `maximize` - Window state
-
-## Known Issues
-
-### Windows batch file working directory
-
-When calling `winpos` from a batch file without `call`, the working directory may not be inherited correctly due to a Windows cmd.exe quirk.
-
-**Workarounds:**
-- Use `call winpos` instead of `winpos` in batch files
-- Use `winpos.ps1` instead of `winpos`
-- Use absolute paths for config files: `winpos "%~dp0config.json"`
-
-## Requirements
-
-- Windows OS
-- Node.js 24+ or Bun 1.0+
-
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Watch mode
-npm run watch
-```
-
-## License
-
-MIT
-
-## Author
-
-Bob Frankston
+# @bobfrankston/winpos
+
+TypeScript implementation of WinPos - A Windows window positioning utility for multi-monitor setups.
+
+## Features
+
+- **Cross-Runtime**: Works with both Node.js (24+) and Bun
+- **FFI-based**: Direct Windows API calls via `koffi` (Node.js) or `bun:ffi` (Bun)
+- **Multi-Monitor**: Full support for multiple displays
+- **Flexible Matching**: Find windows by exact title, prefix, or regex
+- **Window State Management**: Minimize, maximize, restore windows programmatically
+- **Auto-Restore**: Windows are automatically restored from minimized/maximized state when positioning
+- **Monitor Arrangement**: Save the monitor layout and put it back when Windows reverts it (`-screens`)
+- **Library or CLI**: Use as a command-line tool or import as a library
+
+## Installation
+
+```bash
+npm install @bobfrankston/winpos
+```
+
+Or with Bun:
+
+```bash
+bun add @bobfrankston/winpos
+```
+
+## Usage
+
+### Command Line
+
+```bash
+# Move window to screen 0 at position (100, 200)
+winpos "Notepad" 100 200 0
+
+# Move window using percentages
+winpos "Chrome*" 50% 50% 1
+
+# Set window size as well
+winpos "Visual Studio Code" 0 0 0 1920 1080
+
+# List all windows
+winpos *
+
+# Get screen count
+winpos -c
+
+# Which physical monitor is screen 0, 1, 2...: id, name, position, mode
+winpos -screens
+
+# Save the monitor arrangement, and put it back after Windows reverts it
+winpos -screens save
+winpos -screens restore
+
+# Debug mode
+winpos -d "Firefox" 0 0 1
+```
+
+### Pattern Matching
+
+- **Exact match**: `winpos "Notepad" 0 0 0`
+- **Prefix match**: `winpos "Chrome*" 0 0 0`
+- **Regex match**: `winpos "/Visual.*Code/" 0 0 0`
+
+### As a Library
+
+```typescript
+import { run } from '@bobfrankston/winpos';
+
+// Move a window programmatically
+run(['Chrome*', '0', '0', '1', '1920', '1080']);
+```
+
+## Screen Numbering
+
+Screens are numbered starting from 0, sorted by position:
+
+```
+  +---+---+
+  | 2 | 3 |
+  +---+---+
+  | 0 | 1 |
+  +---+---+
+```
+
+- 0: Lower right (primary)
+- 1: Lower left
+- 2: Upper left
+- 3: Upper right
+
+## Options
+
+- `-d` - Debug mode
+- `-dbg` - Verbose debug output
+- `-c` - Return screen count
+- `-v` / `-version` - Show version
+- `-title <name>` - Window title/pattern (alternative to positional)
+- `-pos x,y[,screen]` - Position (comma-separated, screen optional)
+- `-size w,h` - Window size (width,height)
+- `-numsize <inches>` - Physical size of the screen-number overlays (default 2)
+- `-min` - Minimize window
+- `-max` - Maximize window
+- `-load <file>` - Load config from JSON file
+- `-save <file>` - Save config to JSON file (merges if exists)
+- `-screens [list | save [name] | restore [name] | layouts | watch [name]]` - Monitor arrangement (see below)
+- `*` - List all windows
+- `**` - List all windows including ignored
+
+## Identifying Screens
+
+`winpos` with no arguments, and `winpos *` (or `**`), flash each screen's number
+in the middle of that screen for 5 seconds - the same idea as the Identify
+button in Windows display settings, so you can see which physical monitor is
+screen 0, 1, 2 ... before positioning anything there. With no arguments the
+numbers come up alongside the usage text and its screen table.
+
+The numbers are drawn with [msger](https://www.npmjs.com/package/@bobfrankston/msger)
+and all appear at once. They close themselves; winpos returns immediately
+without waiting for them. If msger is unavailable the listing still works, just
+without the numbers.
+
+Each overlay is 2 inches square **on the glass**, not 2 inches' worth of pixels
+- `-numsize <inches>` changes that. Sizing anything in pixels (or in CSS
+inches, which are just 96 pixels) comes out a different physical size on every
+monitor, because Windows' scale factor is a preference rather than a
+measurement: a 28" 4K panel left at 100% claims 96 DPI while really being 160.
+winpos asks the display driver for the panel's physical millimetres (EDID, via
+a GDI display DC) and works out each screen's true DPI, so the same square of
+glass lights up on every monitor. Drivers that report nothing fall back to the
+old pixel sizing.
+
+```typescript
+import { showScreenNumbers, enumerateScreens, sortScreens, screenDpi } from '@bobfrankston/winpos';
+
+const screens = sortScreens(enumerateScreens());
+await showScreenNumbers(screens, 5, 2);     // 5 seconds, 2 inches
+console.log(screens.map(screenDpi));        // True DPI per screen
+```
+
+## Monitor Arrangement
+
+Screen numbers are the monitors sorted by position, and saved window layouts
+address screens by that number. When Windows rearranges the monitors, every
+number changes and every layout puts its windows on the wrong panel. So winpos
+can save the monitor arrangement and put it back - before the windows, in the
+same command.
+
+Windows keeps one arrangement per *exact set* of connected monitors. A
+DisplayPort monitor that powers off or deep-sleeps drops off the bus, the set
+changes, and a set Windows has never seen gets the default left-to-right line.
+That is the "my monitors keep reverting" problem this solves.
+
+```
+winpos -screens                  list monitors: screen number, device, id, name, position, mode, primary
+winpos -screens save [name]      save the current arrangement
+winpos -screens restore [name]   put the saved arrangement back, then read it back and verify
+winpos -screens layouts          list the layouts saved for this machine
+winpos -screens watch [name]     stay resident and restore whenever Windows moves a saved monitor
+```
+
+Monitors are identified by EDID id and serial number (`GSM7721:106NTKF55597`),
+read from the monitor's EDID in the registry - never by `\\.\DISPLAYn`, which
+renumbers whenever a monitor comes or goes. A machine normally has one standard
+arrangement, so the name is optional: without one, every command uses the
+layout called `default`. Give a name only for an alternate setup (a travel
+layout, a single-monitor layout).
+
+Layouts are kept per machine in `winpos-screens.json` in the user config
+directory (`@bobfrankston/userconfig`). The file has the same shape as the
+older `displays.ps1` tool's `displays.json`, so a layout copies between them.
+
+`restore` applies the layout to whichever of its monitors are connected, and
+says so: a saved monitor that is absent is reported and skipped, a connected
+monitor the layout does not mention is left where Windows put it. It then
+waits for Windows to settle, reads the arrangement back, and reports what
+Windows actually did - Windows closes gaps when a monitor is missing, so the
+result can differ from the request. Exit code 1 if anything did not land where
+asked, or if the layout does not exist.
+
+`watch` polls the arrangement every few seconds (no message loop, no
+callbacks) and, once a change has settled, re-applies the layout if any saved
+monitor is out of place. It ignores the change its own apply causes, and if an
+apply changes nothing it stops retrying until the set of monitors changes
+again, so it cannot loop. Run it from a logon task if you want it always on.
+
+A window layout file can restore the monitors first by using the wrapped form:
+
+```json
+{
+  "screens": "default",
+  "windows": [
+    { "name": "Notepad", "pos": { "x": 100, "y": 100, "screen": 0 } }
+  ]
+}
+```
+
+`screens` is a saved layout name, or an inline layout (the `monitors` array as
+saved). Files without `screens` behave exactly as before.
+
+```typescript
+import { enumerateMonitors, saveLayout, getLayout, restoreLayout, formatMonitors } from '@bobfrankston/winpos';
+
+console.log(formatMonitors(enumerateMonitors()).join('\n'));
+saveLayout();                                  // the machine's standard layout
+const result = await restoreLayout(getLayout());
+console.log(result.ok, result.absent, result.mismatches);
+```
+
+## Parameters
+
+### Positional (legacy)
+```
+winpos <title> <x> <y> <screen> [<width> <height>]
+```
+
+### Flag-based (new)
+```
+winpos <title> -pos x,y[,screen] [-size w,h]
+winpos -title <name> -pos x,y,screen -size w,h
+winpos <title> -min
+```
+
+### JSON Config
+```
+winpos layout.json
+winpos -load layout.json [-save output.json]
+```
+
+## JSON Config Format
+
+Single window:
+```json
+{
+  "name": "Notepad",
+  "pos": { "x": 100, "y": 100, "screen": 0 },
+  "size": { "w": 800, "h": 600 }
+}
+```
+
+Multiple windows:
+```json
+[
+  { "name": "app1", "pos": { "x": 0, "y": 0, "screen": 0 } },
+  { "name": "app2*", "pos": { "x": 100, "y": 100, "screen": 1 } },
+  { "name": "pattern", "regex": true, "pos": { "x": 0, "y": 0, "screen": 2 } },
+  { "name": "minimize-me", "minimize": true }
+]
+```
+
+- `name` - Window title (exact match, prefix with `*`, or regex if `regex: true`)
+- `regex` - If true, `name` is treated as a regex pattern
+- `pos` - Position with x, y, and optional screen index
+- `size` - Size with w (width) and h (height)
+- `minimize` / `maximize` - Window state
+
+Wrapped form, monitors first then windows (see Monitor Arrangement):
+```json
+{ "screens": "default", "windows": [ { "name": "app1", "pos": { "x": 0, "y": 0, "screen": 0 } } ] }
+```
+
+## Known Issues
+
+### Windows batch file working directory
+
+When calling `winpos` from a batch file without `call`, the working directory may not be inherited correctly due to a Windows cmd.exe quirk.
+
+**Workarounds:**
+- Use `call winpos` instead of `winpos` in batch files
+- Use `winpos.ps1` instead of `winpos`
+- Use absolute paths for config files: `winpos "%~dp0config.json"`
+
+## Requirements
+
+- Windows OS
+- Node.js 24+ or Bun 1.0+
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run watch
+```
+
+## License
+
+MIT
+
+## Author
+
+Bob Frankston

package/ffi-wrapper.d.ts

@@ -30,6 +30,41 @@ export interface MONITORINFO {
 }
 export declare const MONITORINFOF_PRIMARY = 1;
 export declare const DEFAULT_SCALE_PERCENT = 100;
+export declare const DISPLAY_DEVICE_ATTACHED_TO_DESKTOP = 1;
+export declare const DISPLAY_DEVICE_PRIMARY_DEVICE = 4;
+export declare const DISPLAY_DEVICE_MIRRORING_DRIVER = 8;
+export declare const EDD_GET_DEVICE_INTERFACE_NAME = 1;
+/** ChangeDisplaySettingsExW return codes */
+export declare const DISP_CHANGE_SUCCESSFUL = 0;
+export declare const DISP_CHANGE_RESTART = 1;
+export declare const DISP_CHANGE_FAILED = -1;
+export declare const DISP_CHANGE_BADMODE = -2;
+export declare const DISP_CHANGE_NOTUPDATED = -3;
+export declare const DISP_CHANGE_BADFLAGS = -4;
+export declare const DISP_CHANGE_BADPARAM = -5;
+export declare const DISP_CHANGE_BADDUALVIEW = -6;
+/** One entry from EnumDisplayDevicesW: a display adapter, or the monitor on one */
+export interface DisplayDevice {
+    /** Adapter: \\.\DISPLAY1. Monitor: \\.\DISPLAY1\Monitor0 */
+    deviceName: string;
+    /** Driver's description: adapter model, or "Generic PnP Monitor"-style monitor text */
+    deviceString: string;
+    /** DISPLAY_DEVICE_* bits */
+    stateFlags: number;
+    /** Monitor with EDD_GET_DEVICE_INTERFACE_NAME: \\?\DISPLAY#GSM7721#4&11d6709e&0&UID53318#{guid} */
+    deviceID: string;
+    deviceKey: string;
+}
+/** An adapter's current mode from EnumDisplaySettingsW */
+export interface DisplayMode {
+    /** Desktop position of the top-left corner, in pixels; the primary is 0,0 */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Refresh rate in Hz */
+    hz: number;
+}
 export interface WindowsAPI {
     EnumWindows: (callback: (hwnd: bigint, lParam: bigint) => boolean, lParam: bigint) => boolean;
     GetWindowTextW: (hwnd: bigint, text: any, maxCount: number) => number;
@@ -49,6 +84,20 @@ export interface WindowsAPI {
         width: number;
         height: number;
     } | null;
+    /** Adapter iDevNum (device null), or the monitor on an adapter (device = its name, iDevNum 0). Null past the end. */
+    EnumDisplayDevicesW?: (device: string, iDevNum: number, flags: number) => DisplayDevice;
+    /** Current mode of an adapter. Null when the adapter has none (not attached to the desktop). */
+    EnumDisplaySettingsW?: (device: string) => DisplayMode;
+    /**
+     * Stage a new desktop position for one adapter: written to the registry,
+     * not applied yet. Apply all staged positions with ApplyDisplayChanges.
+     * Returns a DISP_CHANGE_* code.
+     */
+    StageDisplayPosition?: (device: string, x: number, y: number, primary: boolean) => number;
+    /** Apply every position staged with StageDisplayPosition. Returns a DISP_CHANGE_* code. */
+    ApplyDisplayChanges?: () => number;
+    /** A REG_BINARY value under HKEY_LOCAL_MACHINE. Null when the key or value is absent or unreadable. */
+    RegGetBinaryHKLM?: (subKey: string, valueName: string) => Buffer;
 }
 declare const user32: WindowsAPI;
 export { user32, isBun };