@bobfrankston/winpos 2.0.52 → 2.0.53

package/ffi-wrapper.js

@@ -22,6 +22,61 @@ 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
@@ -128,6 +183,29 @@ async function initializeFFI() {
     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 = [];
@@ -239,6 +317,61 @@ async function initializeFFI() {
                 }
             }
         },
+        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

@@ -8,6 +8,8 @@ import { enumerateScreens, sortScreens, screenScale, screenDpi, ScreenInfo } fro
 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, 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, screenScale, screenDpi, enumerateWindows, findWindowsByPattern, getWindowState, setWindowState, isMinimized, isMaximized, isNormal, minimizeWindow, maximizeWindow, restoreWindow, enumerateTabs, mightHaveTabs, TAB_ENUMERATION_NOTE, showScreenNumbers, OVERLAY_INCHES, OVERLAY_SECONDS, 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

@@ -8,12 +8,18 @@ import { enumerateScreens, sortScreens, screenScale, screenDpi } from './screens
 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, 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, screenScale, screenDpi, enumerateWindows, findWindowsByPattern, getWindowState, setWindowState, isMinimized, isMaximized, isNormal, minimizeWindow, maximizeWindow, restoreWindow, enumerateTabs, mightHaveTabs, TAB_ENUMERATION_NOTE, showScreenNumbers, OVERLAY_INCHES, OVERLAY_SECONDS, 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
@@ -195,6 +209,26 @@ function parseArgs(args) {
                 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
@@ -438,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));
@@ -480,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');
@@ -494,6 +529,9 @@ function printUsage(msg = '') {
     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*)');
@@ -503,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) {
@@ -542,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) {

package/monitors.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Monitors as the display driver sees them: which adapter, what mode, where
+ * on the desktop, and - the part EnumDisplayMonitors cannot give - WHO they
+ * are. Identity is the EDID manufacturer/product id plus the panel's serial
+ * number, read from the EDID Windows keeps in the registry. \\.\DISPLAYn is
+ * not an identity: it renumbers whenever a monitor drops off the bus.
+ *
+ * 2026-09-24 - Claude Code (Fable 5.1), at Bob's direction. Ported from
+ * %OneDrive%\xfer\bin\displays.ps1 so winpos can put the monitors back before
+ * it puts the windows back. Why and how: .llm/screens-restore.md.
+ */
+/** One connected monitor: its adapter, identity, and current placement */
+export interface MonitorInfo {
+    /** Adapter name, \\.\DISPLAY1 - what the Win32 calls take, and what ScreenInfo.deviceName holds */
+    device: string;
+    /** Manufacturer + product code from the device path, e.g. GSM7721 */
+    edidId: string;
+    /** Serial number from the EDID; '' when the panel carries none or the EDID is unreadable */
+    serial: string;
+    /** `${edidId}:${serial}` - the stable identity a layout is keyed by */
+    id: string;
+    /** Friendly name from the EDID (e.g. "LG HDR 5K"), else the driver's description */
+    name: string;
+    /** Desktop position of the top-left corner; the primary monitor is at 0,0 */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Refresh rate in Hz */
+    hz: number;
+    primary: boolean;
+}
+/** The identity string a layout is keyed by */
+export declare function monitorId(edidId: string, serial: string): string;
+/** The text of the display descriptor carrying `tag`, or '' when the EDID has none */
+export declare function edidDescriptor(edid: Buffer, tag: number): string;
+/**
+ * The panel's serial number: the serial descriptor when there is one,
+ * otherwise the numeric serial from the vendor block (as decimal text, the
+ * way WMI's WmiMonitorID reports it), otherwise ''.
+ */
+export declare function edidSerial(edid: Buffer): string;
+/**
+ * The EDID Windows recorded for a monitor, from
+ * HKLM\SYSTEM\CurrentControlSet\Enum\DISPLAY\<EdidId>\<instance>\Device Parameters.
+ * Readable without elevation (checked on RMF39, 2026-09-24). Null when absent.
+ */
+export declare function readEdid(edidId: string, instance: string): Buffer;
+/**
+ * Every monitor attached to the desktop, in adapter order.
+ *
+ * Throws where the Win32 path is unavailable (Bun) - the caller decides
+ * whether that is fatal. The window half of winpos treats identity as
+ * optional; the -screens commands do not.
+ */
+export declare function enumerateMonitors(): MonitorInfo[];
+/**
+ * Stage a desktop position for one monitor's adapter. Nothing moves until
+ * applyMonitorPositions(); staging all of them first is what lets Windows
+ * treat the arrangement as one change. Returns a DISP_CHANGE_* code.
+ */
+export declare function stageMonitorPosition(device: string, x: number, y: number, primary: boolean): number;
+/** Apply every staged position. Returns a DISP_CHANGE_* code. */
+export declare function applyMonitorPositions(): number;
+/** Human text for a ChangeDisplaySettingsExW return code */
+export declare function dispChangeText(code: number): string;
+//# sourceMappingURL=monitors.d.ts.map