@bobfrankston/winpos 2.0.51 → 2.0.53

package/ffi-wrapper.js

@@ -16,9 +16,67 @@ export const SW_MINIMIZE = 6;
 export const SW_SHOWMINNOACTIVE = 7;
 export const SW_SHOWNA = 8;
 export const SW_RESTORE = 9;
+// GetDeviceCaps indices for the panel's physical size in millimetres
+const HORZSIZE = 4;
+const VERTSIZE = 6;
 export const MONITORINFOF_PRIMARY = 1;
 // Monitor scale factor as a percentage (100 = no scaling, 125 = 125%)
 export const DEFAULT_SCALE_PERCENT = 100;
+// 2026-09-24 - Claude Code (Fable 5.1), at Bob's direction: monitor arrangement
+// save/restore folded in from %OneDrive%\xfer\bin\displays.ps1 (see
+// .llm/screens-restore.md). Everything below down to WindowsAPI is for that.
+// DISPLAY_DEVICEW.StateFlags
+export const DISPLAY_DEVICE_ATTACHED_TO_DESKTOP = 0x1;
+export const DISPLAY_DEVICE_PRIMARY_DEVICE = 0x4;
+export const DISPLAY_DEVICE_MIRRORING_DRIVER = 0x8;
+// EnumDisplayDevicesW dwFlags: DeviceID becomes the device interface path,
+// \\?\DISPLAY#<EdidId>#<instance>#{guid}, which is what names the registry
+// key holding the monitor's EDID.
+export const EDD_GET_DEVICE_INTERFACE_NAME = 0x1;
+// EnumDisplaySettingsW iModeNum
+const ENUM_CURRENT_SETTINGS = -1;
+// DEVMODEW.dmFields: only the position is being set
+const DM_POSITION = 0x20;
+// ChangeDisplaySettingsExW dwflags
+const CDS_UPDATEREGISTRY = 0x1;
+const CDS_SET_PRIMARY = 0x10;
+const CDS_NORESET = 0x10000000;
+/** ChangeDisplaySettingsExW return codes */
+export const DISP_CHANGE_SUCCESSFUL = 0;
+export const DISP_CHANGE_RESTART = 1;
+export const DISP_CHANGE_FAILED = -1;
+export const DISP_CHANGE_BADMODE = -2;
+export const DISP_CHANGE_NOTUPDATED = -3;
+export const DISP_CHANGE_BADFLAGS = -4;
+export const DISP_CHANGE_BADPARAM = -5;
+export const DISP_CHANGE_BADDUALVIEW = -6;
+// Registry: RegGetValueW dwFlags restricting the value type, and the
+// predefined HKLM handle. The SDK defines HKEY_LOCAL_MACHINE as
+// (HKEY)(ULONG_PTR)(LONG)0x80000002, i.e. SIGN-extended on 64-bit, so the
+// value that has to cross the FFI boundary is 0xFFFFFFFF80000002, not
+// 0x80000002.
+const RRF_RT_REG_BINARY = 0x08;
+const HKEY_LOCAL_MACHINE = 0xffffffff80000002n;
+const ERROR_SUCCESS = 0;
+// Largest registry value this reads. EDIDs are 128-512 bytes.
+const REG_VALUE_MAX = 4096;
+/** A fixed-size WCHAR array out of a struct buffer, up to its terminator */
+function wideString(buf, offset, chars) {
+    const text = buf.toString('utf16le', offset, offset + chars * 2);
+    const end = text.indexOf('\0');
+    return end >= 0 ? text.substring(0, end) : text;
+}
+// DISPLAY_DEVICEW: cb DWORD, DeviceName WCHAR[32], DeviceString WCHAR[128],
+// StateFlags DWORD, DeviceID WCHAR[128], DeviceKey WCHAR[128]. 840 bytes.
+const DISPLAY_DEVICEW_SIZE = 840;
+const DD_DEVICENAME = 4, DD_DEVICESTRING = 68, DD_STATEFLAGS = 324, DD_DEVICEID = 328, DD_DEVICEKEY = 584;
+// DEVMODEW (the W layout - the A one has the position at 44): dmDeviceName
+// WCHAR[32] @0, four WORDs @64 (dmSize @68), dmFields @72, then the position
+// union @76, ... dmPelsWidth @172, dmPelsHeight @176, dmDisplayFrequency @184.
+// 220 bytes, and dmSize must say so or the call fails.
+const DEVMODEW_SIZE = 220;
+const DM_SIZE = 68, DM_FIELDS = 72, DM_POSITION_X = 76, DM_POSITION_Y = 80;
+const DM_PELSWIDTH = 172, DM_PELSHEIGHT = 176, DM_DISPLAYFREQUENCY = 184;
 async function initializeFFI() {
     if (isBun) {
         // @ts-ignore - bun:ffi is only available in Bun
@@ -110,6 +168,44 @@ async function initializeFFI() {
     catch {
         // Leave null - callers fall back to 100%
     }
+    // A display DC reports the panel's physical size in millimetres, straight
+    // from the driver's EDID. That is the only measurement of a monitor
+    // available: the scale factor above is a user preference, so a 160 DPI
+    // panel left at 100% claims to be a 96 DPI one. Optional, like shcore -
+    // callers fall back to nominal DPI when this returns null.
+    let CreateDCW = null, GetDeviceCaps = null, DeleteDC = null;
+    try {
+        const gdi32 = koffi.load('gdi32.dll');
+        CreateDCW = gdi32.func('void * __stdcall CreateDCW(const char16_t *pwszDriver, const char16_t *pwszDevice, const char16_t *pszPort, const void *pdm)');
+        GetDeviceCaps = gdi32.func('int __stdcall GetDeviceCaps(void *hdc, int index)');
+        DeleteDC = gdi32.func('bool __stdcall DeleteDC(void *hdc)');
+    }
+    catch {
+        CreateDCW = null;
+    }
+    // Monitor arrangement. These three are in every user32 there is, so no
+    // try around them: a missing one is a broken install, not a variant.
+    const EnumDisplayDevicesWRaw = lib.func('bool __stdcall EnumDisplayDevicesW(const char16_t *lpDevice, uint32_t iDevNum, void *lpDisplayDevice, uint32_t dwFlags)');
+    const EnumDisplaySettingsWRaw = lib.func('bool __stdcall EnumDisplaySettingsW(const char16_t *lpszDeviceName, int iModeNum, void *lpDevMode)');
+    const ChangeDisplaySettingsExWRaw = lib.func('int __stdcall ChangeDisplaySettingsExW(const char16_t *lpszDeviceName, void *lpDevMode, void *hwnd, uint32_t dwflags, void *lParam)');
+    // The monitor's EDID lives in the registry; that is where the serial
+    // number and the friendly name come from. Optional like gdi32: without
+    // it monitors are identified by EDID id alone and the listing shows the
+    // serial column empty, which is visible rather than silent.
+    let RegGetValueWRaw = null;
+    try {
+        const advapi32 = koffi.load('advapi32.dll');
+        RegGetValueWRaw = advapi32.func('int __stdcall RegGetValueW(uintptr_t hkey, const char16_t *lpSubKey, const char16_t *lpValue, uint32_t dwFlags, void *pdwType, void *pvData, void *pcbData)');
+    }
+    catch {
+        RegGetValueWRaw = null; // Justified: RegGetBinaryHKLM below returns null, and monitors.ts reports the missing serial
+    }
+    /** DEVMODEW buffer holding an adapter's current mode, or null when it has none */
+    function currentModeBuffer(device) {
+        const buf = Buffer.alloc(DEVMODEW_SIZE);
+        buf.writeUInt16LE(DEVMODEW_SIZE, DM_SIZE);
+        return EnumDisplaySettingsWRaw(device, ENUM_CURRENT_SETTINGS, buf) ? buf : null;
+    }
     // Keep references to registered callbacks to prevent garbage collection
     // These must persist for the entire duration of the native callback invocation
     const __callbackRefs = [];
@@ -154,14 +250,18 @@ async function initializeFFI() {
             return result;
         },
         GetMonitorInfoW: (hMonitor, lpmi) => {
-            // MONITORINFO structure:
+            // MONITORINFOEXW structure:
             // DWORD cbSize (4 bytes)
             // RECT rcMonitor (16 bytes)
             // RECT rcWork (16 bytes)
             // DWORD dwFlags (4 bytes)
-            // Total: 40 bytes
-            const buffer = Buffer.alloc(40);
-            buffer.writeUInt32LE(40, 0); // cbSize
+            // WCHAR szDevice[32] (64 bytes) - the EX part, and the reason for
+            //   asking: the device name is what gdi32 wants to open a DC on
+            //   this monitor, and the only reliable tie from an HMONITOR to a
+            //   \\.\DISPLAYn. cbSize is what selects EX over plain MONITORINFO.
+            // Total: 104 bytes
+            const buffer = Buffer.alloc(104);
+            buffer.writeUInt32LE(104, 0); // cbSize
             const result = GetMonitorInfoW(hMonitor, buffer);
             if (result) {
                 lpmi.cbSize = buffer.readUInt32LE(0);
@@ -178,6 +278,9 @@ async function initializeFFI() {
                     Bottom: buffer.readInt32LE(32),
                 };
                 lpmi.dwFlags = buffer.readUInt32LE(36);
+                const device = buffer.toString('utf16le', 40, 104);
+                const end = device.indexOf('\0');
+                lpmi.szDevice = end >= 0 ? device.substring(0, end) : device;
             }
             return result;
         },
@@ -188,6 +291,87 @@ async function initializeFFI() {
             const hr = GetScaleFactorForMonitorRaw(hMonitor, scale);
             return hr === 0 ? (scale.readUInt32LE(0) || DEFAULT_SCALE_PERCENT) : DEFAULT_SCALE_PERCENT;
         },
+        GetPhysicalSizeMm: (deviceName) => {
+            if (!CreateDCW || !deviceName)
+                return null;
+            let hdc = null;
+            try {
+                // An information DC would do, but CreateDCW on the DISPLAY
+                // driver is what every monitor exposes; the caps are the same.
+                hdc = CreateDCW('DISPLAY', deviceName, null, null);
+                if (!hdc)
+                    return null;
+                const width = GetDeviceCaps(hdc, HORZSIZE);
+                const height = GetDeviceCaps(hdc, VERTSIZE);
+                return width > 0 && height > 0 ? { width, height } : null;
+            }
+            catch {
+                return null; // Best-effort: no measurement is not an error
+            }
+            finally {
+                if (hdc) {
+                    try {
+                        DeleteDC(hdc);
+                    }
+                    catch { /* nothing useful to do */ }
+                }
+            }
+        },
+        EnumDisplayDevicesW: (device, iDevNum, flags) => {
+            const buf = Buffer.alloc(DISPLAY_DEVICEW_SIZE);
+            buf.writeUInt32LE(DISPLAY_DEVICEW_SIZE, 0); // cb
+            if (!EnumDisplayDevicesWRaw(device, iDevNum, buf, flags))
+                return null;
+            return {
+                deviceName: wideString(buf, DD_DEVICENAME, 32),
+                deviceString: wideString(buf, DD_DEVICESTRING, 128),
+                stateFlags: buf.readUInt32LE(DD_STATEFLAGS),
+                deviceID: wideString(buf, DD_DEVICEID, 128),
+                deviceKey: wideString(buf, DD_DEVICEKEY, 128),
+            };
+        },
+        EnumDisplaySettingsW: (device) => {
+            const buf = currentModeBuffer(device);
+            if (!buf)
+                return null;
+            return {
+                x: buf.readInt32LE(DM_POSITION_X),
+                y: buf.readInt32LE(DM_POSITION_Y),
+                width: buf.readUInt32LE(DM_PELSWIDTH),
+                height: buf.readUInt32LE(DM_PELSHEIGHT),
+                hz: buf.readUInt32LE(DM_DISPLAYFREQUENCY),
+            };
+        },
+        StageDisplayPosition: (device, x, y, primary) => {
+            // Start from the current mode so everything but the position is
+            // what the adapter already has; dmFields says only the position
+            // counts. CDS_NORESET stages it, CDS_UPDATEREGISTRY makes Windows
+            // remember this arrangement for the current set of monitors.
+            const buf = currentModeBuffer(device);
+            if (!buf)
+                return DISP_CHANGE_BADPARAM;
+            buf.writeUInt32LE(DM_POSITION, DM_FIELDS);
+            buf.writeInt32LE(x, DM_POSITION_X);
+            buf.writeInt32LE(y, DM_POSITION_Y);
+            let flags = CDS_UPDATEREGISTRY | CDS_NORESET;
+            if (primary)
+                flags |= CDS_SET_PRIMARY;
+            return ChangeDisplaySettingsExWRaw(device, buf, null, flags >>> 0, null);
+        },
+        ApplyDisplayChanges: () => {
+            return ChangeDisplaySettingsExWRaw(null, null, null, 0, null);
+        },
+        RegGetBinaryHKLM: (subKey, valueName) => {
+            if (!RegGetValueWRaw)
+                return null;
+            const data = Buffer.alloc(REG_VALUE_MAX);
+            const size = Buffer.alloc(4);
+            size.writeUInt32LE(REG_VALUE_MAX, 0);
+            const rc = RegGetValueWRaw(HKEY_LOCAL_MACHINE, subKey, valueName, RRF_RT_REG_BINARY, null, data, size);
+            if (rc !== ERROR_SUCCESS)
+                return null;
+            return data.subarray(0, size.readUInt32LE(0));
+        },
     };
 }
 const user32 = await initializeFFI();

package/index.d.ts

@@ -4,10 +4,12 @@
  * Cross-platform Node.js/Bun implementation with FFI
  */
 import { user32, RECT } from './ffi-wrapper.js';
-import { enumerateScreens, sortScreens, ScreenInfo } from './screens.js';
+import { enumerateScreens, sortScreens, screenScale, screenDpi, ScreenInfo } from './screens.js';
 import { enumerateWindows, findWindowsByPattern, WindowInfo, WindowState, getWindowState, setWindowState, isMinimized, isMaximized, isNormal, minimizeWindow, maximizeWindow, restoreWindow } from './windows.js';
 import { enumerateTabs, TabInfo, mightHaveTabs, TAB_ENUMERATION_NOTE } from './tabs.js';
-import { showScreenNumbers } from './screennums.js';
+import { showScreenNumbers, OVERLAY_SECONDS, OVERLAY_INCHES } from './screennums.js';
+import { MonitorInfo, enumerateMonitors } from './monitors.js';
+import { SavedMonitor, ScreenLayout, RestoreResult, DEFAULT_LAYOUT_NAME, layoutsPath, getLayout, saveLayout, machineLayouts, restoreLayout, watchLayout, formatMonitors } from './screenlayout.js';
 export interface WindowConfig {
     name: string;
     regex?: boolean;
@@ -23,8 +25,17 @@ export interface WindowConfig {
     minimize?: boolean;
     maximize?: boolean;
 }
-export type ConfigFile = WindowConfig | WindowConfig[];
-export { RECT, ScreenInfo, WindowInfo, WindowState, TabInfo, enumerateScreens, sortScreens, enumerateWindows, findWindowsByPattern, getWindowState, setWindowState, isMinimized, isMaximized, isNormal, minimizeWindow, maximizeWindow, restoreWindow, enumerateTabs, mightHaveTabs, TAB_ENUMERATION_NOTE, showScreenNumbers, user32 };
+/**
+ * The wrapped config form: monitors first, then windows. `screens` is the
+ * name of a saved monitor layout, an inline layout, or just its monitors
+ * array. Either key may be omitted.
+ */
+export interface LayoutFile {
+    screens?: string | ScreenLayout | SavedMonitor[];
+    windows?: WindowConfig[];
+}
+export type ConfigFile = WindowConfig | WindowConfig[] | LayoutFile;
+export { RECT, ScreenInfo, WindowInfo, WindowState, TabInfo, enumerateScreens, sortScreens, screenScale, screenDpi, enumerateWindows, findWindowsByPattern, getWindowState, setWindowState, isMinimized, isMaximized, isNormal, minimizeWindow, maximizeWindow, restoreWindow, enumerateTabs, mightHaveTabs, TAB_ENUMERATION_NOTE, showScreenNumbers, OVERLAY_INCHES, OVERLAY_SECONDS, user32, MonitorInfo, SavedMonitor, ScreenLayout, RestoreResult, DEFAULT_LAYOUT_NAME, layoutsPath, enumerateMonitors, getLayout, saveLayout, machineLayouts, restoreLayout, watchLayout, formatMonitors };
 /**
  * Convert screen-relative coordinates to global coordinates
  * @param x - X coordinate relative to screen

package/index.js

@@ -4,16 +4,22 @@
  * Cross-platform Node.js/Bun implementation with FFI
  */
 import { user32 } from './ffi-wrapper.js';
-import { enumerateScreens, sortScreens } from './screens.js';
+import { enumerateScreens, sortScreens, screenScale, screenDpi } from './screens.js';
 import { enumerateWindows, findWindowsByPattern, loadIgnorePatterns, WindowState, getWindowState, setWindowState, isMinimized, isMaximized, isNormal, minimizeWindow, maximizeWindow, restoreWindow } from './windows.js';
 import { enumerateTabs, mightHaveTabs, TAB_ENUMERATION_NOTE } from './tabs.js';
-import { showScreenNumbers, OVERLAY_SECONDS } from './screennums.js';
+import { showScreenNumbers, OVERLAY_SECONDS, OVERLAY_INCHES } from './screennums.js';
+// 2026-09-24 - Claude Code (Fable 5.1), at Bob's direction: monitor arrangement
+// save/restore (-screens), folded in from displays.ps1. See .llm/screens-restore.md.
+import { enumerateMonitors } from './monitors.js';
+import { DEFAULT_LAYOUT_NAME, layoutsPath, machine, getLayout, saveLayout, machineLayouts, resolveLayout, restoreLayout, watchLayout, formatMonitors } from './screenlayout.js';
 import { join, resolve, isAbsolute } from 'path';
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { parse as parseJsonc, printParseErrorCode } from 'jsonc-parser';
 import * as packageJson from './package.json' with { type: 'json' };
+/** The -screens verbs. No verb means list. */
+const SCREEN_VERBS = ['list', 'save', 'restore', 'layouts', 'watch'];
 // Re-export public API for library usage
-export { WindowState, enumerateScreens, sortScreens, enumerateWindows, findWindowsByPattern, getWindowState, setWindowState, isMinimized, isMaximized, isNormal, minimizeWindow, maximizeWindow, restoreWindow, enumerateTabs, mightHaveTabs, TAB_ENUMERATION_NOTE, showScreenNumbers, user32 };
+export { WindowState, enumerateScreens, sortScreens, screenScale, screenDpi, enumerateWindows, findWindowsByPattern, getWindowState, setWindowState, isMinimized, isMaximized, isNormal, minimizeWindow, maximizeWindow, restoreWindow, enumerateTabs, mightHaveTabs, TAB_ENUMERATION_NOTE, showScreenNumbers, OVERLAY_INCHES, OVERLAY_SECONDS, user32, DEFAULT_LAYOUT_NAME, layoutsPath, enumerateMonitors, getLayout, saveLayout, machineLayouts, restoreLayout, watchLayout, formatMonitors };
 // WindowConfig and ConfigFile types are exported from interface definitions above
 // Note: screenPosToPos is exported separately below (after the function definition)
 /**
@@ -37,6 +43,17 @@ function loadConfigFile(filePath) {
     }
     return parsed;
 }
+/** Replace the entry with the same name, or append */
+function mergeWindowConfig(list, config) {
+    const idx = list.findIndex(e => e.name === config.name);
+    if (idx >= 0) {
+        list[idx] = config;
+    }
+    else {
+        list.push(config);
+    }
+    return list;
+}
 /**
  * Save window config to JSON file
  * If file exists and contains array, merge; otherwise create/overwrite
@@ -46,16 +63,13 @@ function saveConfigFile(filePath, config, merge = false) {
     let finalConfig;
     if (merge && existsSync(absPath)) {
         const existing = loadConfigFile(absPath);
-        if (Array.isArray(existing)) {
-            // Find and update existing entry with same name, or append
-            const idx = existing.findIndex(e => e.name === config.name);
-            if (idx >= 0) {
-                existing[idx] = config;
-            }
-            else {
-                existing.push(config);
-            }
-            finalConfig = existing;
+        if (isLayoutFile(existing)) {
+            // 2026-09-24 - Claude Code (Fable 5.1): the wrapped form keeps its
+            // screens section; only the windows list is merged into.
+            finalConfig = { ...existing, windows: mergeWindowConfig(existing.windows ?? [], config) };
+        }
+        else if (Array.isArray(existing)) {
+            finalConfig = mergeWindowConfig(existing, config);
         }
         else {
             // Convert single entry to array
@@ -179,12 +193,42 @@ function parseArgs(args) {
                         opts.windowTitle = args[i];
                     }
                     break;
+                case 'numsize':
+                    i++;
+                    if (i < args.length) {
+                        const inches = parseFloat(args[i]);
+                        if (inches > 0)
+                            opts.numSize = inches;
+                        else
+                            console.log(`Ignoring -numsize ${args[i]}: expected a size in inches`);
+                    }
+                    break;
                 case 'min':
                     opts.minimize = true;
                     break;
                 case 'max':
                     opts.maximize = true;
                     break;
+                case 'screens': {
+                    // -screens [list|save|restore|layouts|watch] [name]. Bare
+                    // -screens lists. The name is optional and only for an
+                    // alternate layout; the machine's standard one needs none.
+                    const next = args[i + 1];
+                    const verb = next?.toLowerCase();
+                    if (next && !next.startsWith('-') && !SCREEN_VERBS.includes(verb)) {
+                        console.error(`Unknown -screens command '${next}'. Expected one of: ${SCREEN_VERBS.join(', ')}`);
+                        process.exit(1);
+                    }
+                    opts.screens = { verb: (SCREEN_VERBS.includes(verb) ? verb : 'list') };
+                    if (opts.screens.verb !== 'list')
+                        i++;
+                    const takesName = opts.screens.verb === 'save' || opts.screens.verb === 'restore' || opts.screens.verb === 'watch';
+                    if (takesName && i + 1 < args.length && !args[i + 1].startsWith('-')) {
+                        i++;
+                        opts.screens.name = args[i];
+                    }
+                    break;
+                }
                 case 'help':
                 case '?':
                     return opts; // Will trigger usage display
@@ -289,6 +333,7 @@ function applyWindowConfig(config, screensInfo) {
 let dbg = false;
 let dbgVerbose = false; // -dbg flag for detailed output
 let screens = [];
+let numSize = OVERLAY_INCHES; // -numsize: screen-number overlay size in inches
 /**
  * Convert screen-relative coordinates to global coordinates
  * @param x - X coordinate relative to screen
@@ -427,7 +472,7 @@ function listAllWindows(includeIgnored = false) {
         const screen = screens[i];
         // console.log(`${i} Screen: ${screen.deviceName} (${screen.bounds.Top}/${screen.bounds.Bottom}x${screen.bounds.Left}/${screen.bounds.Right})`);
         const b = screen.bounds;
-        console.log(`${i} Screen: ${screen.deviceName} ${padn(b.Left)},${padn(b.Top)} (lower right ${padn(b.Right)} ${padn(b.Bottom)})`);
+        console.log(`${i} Screen: ${screen.deviceName} ${padn(b.Left)},${padn(b.Top)} (lower right ${padn(b.Right)} ${padn(b.Bottom)})  ${screen.name ?? ''}`);
     }
     console.log();
     const windows = enumerateWindows(includeIgnored).sort((a, b) => a.title.localeCompare(b.title));
@@ -450,7 +495,7 @@ function listAllWindows(includeIgnored = false) {
     console.log('Command format: tswinpos <title> <x> <y> <screen> [<width> <height>]');
     // Flash each screen's number on that screen - launched last so the overlays
     // can't turn up in the listing above. Detached, so we don't wait for them.
-    void showScreenNumbers(screens);
+    void showScreenNumbers(screens, OVERLAY_SECONDS, numSize);
 }
 function usage(msg = '') {
     printUsage(msg);
@@ -469,6 +514,7 @@ function printUsage(msg = '') {
     console.log('       winpos <title> min | -min');
     console.log('       winpos <config.json|config.jsonc>');
     console.log('       winpos -load <config.json|config.jsonc> [-save <output.json>]');
+    console.log('       winpos -screens [list | save [name] | restore [name] | layouts | watch [name]]');
     console.log();
     console.log('Options:');
     console.log('  -d          Debug mode');
@@ -478,10 +524,14 @@ function printUsage(msg = '') {
     console.log('  -title name Window title/pattern (alternative to positional)');
     console.log('  -pos x,y[,s] Position (x,y with optional screen index)');
     console.log('  -size w,h   Window size (width,height)');
+    console.log(`  -numsize n  Screen-number overlay size in inches (default ${OVERLAY_INCHES})`);
     console.log('  -min        Minimize window');
     console.log('  -max        Maximize window');
     console.log('  -load file  Load config from JSON/JSONC file (comments + trailing commas OK)');
     console.log('  -save file  Save config to JSON file (merges if file exists; comments not preserved)');
+    console.log('  -screens    Monitor arrangement: list (default), save, restore, layouts, watch');
+    console.log(`              A name is only for an alternate layout; the standard one is '${DEFAULT_LAYOUT_NAME}'.`);
+    console.log(`              Layouts are kept per machine in ${layoutsPath}`);
     console.log();
     console.log('Position/size values can be pixels or percentages (e.g. 50%)');
     console.log('Title can be regex (/pattern/) or prefix (title*)');
@@ -491,12 +541,121 @@ function printUsage(msg = '') {
     console.log();
     console.log('JSON format: {"name":"app","regex":false,"pos":{"x":0,"y":0,"screen":0},"size":{"w":800,"h":600}}');
     console.log('  or array: [{...}, {...}]');
+    console.log('  or {"screens":"default","windows":[{...}]} to restore the monitor arrangement first');
     console.log();
-    console.log('Screen |   X     Y   |   W     H   ');
-    console.log('------------------------------------');
+    console.log('Screen |   X     Y   |   W     H   | Monitor');
+    console.log('---------------------------------------------');
     for (let i = 0; i < screens.length; i++) {
         const screen = screens[i];
-        console.log(`${i.toString().padStart(6)} | ${screen.bounds.Left.toString().padStart(5)} ${screen.bounds.Top.toString().padStart(5)} | ${screen.bounds.Width.toString().padStart(5)} ${screen.bounds.Height.toString().padStart(5)}`);
+        console.log(`${i.toString().padStart(6)} | ${screen.bounds.Left.toString().padStart(5)} ${screen.bounds.Top.toString().padStart(5)} | ${screen.bounds.Width.toString().padStart(5)} ${screen.bounds.Height.toString().padStart(5)} | ${screen.name ?? ''}`);
+    }
+}
+/**
+ * The -screens commands. Returns the exit code; throws for failures that
+ * should end with a message on stderr (run() prints it).
+ */
+async function runScreens(cmd) {
+    const name = cmd.name ?? DEFAULT_LAYOUT_NAME;
+    switch (cmd.verb) {
+        case 'list': {
+            for (const line of formatMonitors(enumerateMonitors(), screens))
+                console.log(line);
+            return 0;
+        }
+        case 'layouts': {
+            const all = machineLayouts();
+            const names = Object.keys(all).sort();
+            if (names.length === 0) {
+                console.log(`No monitor layouts saved for ${machine} in ${layoutsPath}`);
+                return 0;
+            }
+            for (const n of names)
+                console.log(`${n.padEnd(16)} saved ${all[n].saved}  [${all[n].monitors.map(m => m.name).join(', ')}]`);
+            return 0;
+        }
+        case 'save': {
+            const layout = saveLayout(name);
+            console.log(`Saved monitor layout '${name}' for ${machine} (${layout.monitors.length} monitors) to ${layoutsPath}`);
+            for (const line of formatMonitors(enumerateMonitors(), screens))
+                console.log(line);
+            return 0;
+        }
+        case 'restore': {
+            const layout = getLayout(name);
+            if (!layout)
+                throw new Error(`No monitor layout '${name}' saved for ${machine}. Run 'winpos -screens layouts' to see what exists.`);
+            const result = await restoreLayout(layout);
+            // Renumber against what is on the desktop now, so the Scr column is current
+            screens = sortScreens(enumerateScreens());
+            for (const line of formatMonitors(result.after, screens))
+                console.log(line);
+            if (!result.ok) {
+                console.log(`${result.mismatches.length} monitor(s) did not land where asked (Windows closes gaps when a monitor is missing).`);
+                return 1;
+            }
+            return 0;
+        }
+        case 'watch':
+            await watchLayout(name); // stays resident; only returns by throwing
+            return 0;
+    }
+}
+/** Whether a parsed config is the wrapped {screens, windows} form */
+function isLayoutFile(config) {
+    return !Array.isArray(config) && !('name' in config) && ('screens' in config || 'windows' in config);
+}
+/**
+ * winpos <config.json> / -load: monitors first when the file has a `screens`
+ * section, then the windows. The screen numbers the window entries use are
+ * derived from the arrangement, so it has to be right before any window moves.
+ */
+async function runConfigFile(opts) {
+    const config = loadConfigFile(opts.loadFile);
+    let wrapped = null;
+    let configs;
+    if (isLayoutFile(config)) {
+        wrapped = config;
+        configs = wrapped.windows ?? [];
+    }
+    else {
+        configs = Array.isArray(config) ? config : [config];
+    }
+    if (wrapped?.screens !== undefined) {
+        const layout = resolveLayout(wrapped.screens);
+        if (!layout)
+            throw new Error(`No monitor layout '${wrapped.screens}' saved for ${machine} in ${layoutsPath}`);
+        const result = await restoreLayout(layout);
+        if (!result.ok) {
+            console.log(`${result.mismatches.length} monitor(s) did not land where asked; continuing with the windows.`);
+            process.exitCode = 1;
+        }
+        screens = sortScreens(enumerateScreens());
+    }
+    // If CLI params specify a window, merge into loaded config
+    if (opts.windowTitle && (opts.pos || opts.size || opts.minimize || opts.maximize)) {
+        const cliConfig = buildConfigFromOptions(opts);
+        if (cliConfig) {
+            // Find matching entry by name and override it
+            const idx = configs.findIndex(c => c.name === cliConfig.name);
+            if (idx >= 0) {
+                configs[idx] = cliConfig;
+            }
+            else {
+                configs.push(cliConfig);
+            }
+        }
+    }
+    // Apply all configs
+    for (const cfg of configs) {
+        applyWindowConfig(cfg, screens);
+    }
+    // Save merged config if requested - in the same form it was read
+    if (opts.saveFile !== undefined) {
+        const savePath = opts.saveFile || opts.loadFile; // Default to loadFile if -save has no arg
+        const absPath = isAbsolute(savePath) ? savePath : resolve(process.cwd(), savePath);
+        const finalConfig = wrapped ? { ...wrapped, windows: configs } : configs.length === 1 ? configs[0] : configs;
+        writeFileSync(absPath, JSON.stringify(finalConfig, null, 2), 'utf-8');
+        console.log(`Config saved to: ${absPath}`);
     }
 }
 export function run(args) {
@@ -519,6 +678,8 @@ export function run(args) {
     // Set debug flags
     dbg = opts.debug;
     dbgVerbose = opts.debugVerbose;
+    if (opts.numSize)
+        numSize = opts.numSize;
     if (dbg)
         console.log('Debug mode enabled.');
     if (dbgVerbose)
@@ -528,43 +689,24 @@ export function run(args) {
         console.log(screens.length);
         process.exit(screens.length);
     }
-    // Handle load file (JSON config)
+    // Handle -screens (monitor arrangement)
+    if (opts.screens) {
+        runScreens(opts.screens)
+            .then(code => process.exit(code))
+            .catch((e) => {
+            console.error(`winpos: ${e.message}`);
+            process.exit(1);
+        });
+        return;
+    }
+    // Handle load file (JSON config). Async since a `screens` section
+    // restores the monitor arrangement first and waits for it to settle.
     if (opts.loadFile) {
-        try {
-            const config = loadConfigFile(opts.loadFile);
-            let configs = Array.isArray(config) ? config : [config];
-            // If CLI params specify a window, merge into loaded config
-            if (opts.windowTitle && (opts.pos || opts.size || opts.minimize || opts.maximize)) {
-                const cliConfig = buildConfigFromOptions(opts);
-                if (cliConfig) {
-                    // Find matching entry by name and override it
-                    const idx = configs.findIndex(c => c.name === cliConfig.name);
-                    if (idx >= 0) {
-                        configs[idx] = cliConfig;
-                    }
-                    else {
-                        configs.push(cliConfig);
-                    }
-                }
-            }
-            // Apply all configs
-            for (const cfg of configs) {
-                applyWindowConfig(cfg, screens);
-            }
-            // Save merged config if requested
-            if (opts.saveFile !== undefined) {
-                const savePath = opts.saveFile || opts.loadFile; // Default to loadFile if -save has no arg
-                const absPath = isAbsolute(savePath) ? savePath : resolve(process.cwd(), savePath);
-                const finalConfig = configs.length === 1 ? configs[0] : configs;
-                writeFileSync(absPath, JSON.stringify(finalConfig, null, 2), 'utf-8');
-                console.log(`Config saved to: ${absPath}`);
-            }
-            return;
-        }
-        catch (e) {
+        runConfigFile(opts).catch((e) => {
             console.error(`Error loading config: ${e.message}`);
             process.exit(1);
-        }
+        });
+        return;
     }
     // Handle new flag-based syntax (-pos, -size, -min, -max)
     if (opts.pos || opts.size || opts.minimize || opts.maximize) {
@@ -615,7 +757,7 @@ export function run(args) {
     // themselves; we only wait for the launch, because process.exit here would
     // kill the spawn in mid-flight and no numbers would ever appear.
     if (posArgs.length === 0) {
-        const overlays = showScreenNumbers(screens);
+        const overlays = showScreenNumbers(screens, OVERLAY_SECONDS, numSize);
         printUsage();
         void overlays.finally(() => process.exit(1));
         return;