@bobfrankston/winpos 2.0.52 → 2.0.53

package/monitors.js

@@ -0,0 +1,146 @@
+/**
+ * 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.
+ */
+import { user32, isBun, DISPLAY_DEVICE_ATTACHED_TO_DESKTOP, DISPLAY_DEVICE_PRIMARY_DEVICE, DISPLAY_DEVICE_MIRRORING_DRIVER, EDD_GET_DEVICE_INTERFACE_NAME, DISP_CHANGE_SUCCESSFUL, DISP_CHANGE_RESTART, DISP_CHANGE_FAILED, DISP_CHANGE_BADMODE, DISP_CHANGE_NOTUPDATED, DISP_CHANGE_BADFLAGS, DISP_CHANGE_BADPARAM, DISP_CHANGE_BADDUALVIEW } from './ffi-wrapper.js';
+/** The identity string a layout is keyed by */
+export function monitorId(edidId, serial) {
+    return `${edidId}:${serial}`;
+}
+// EDID base block: the four 18-byte descriptors, and how a display descriptor
+// (as opposed to a detailed timing) announces itself - zero pixel clock,
+// zero, then the tag byte. Text descriptors carry 13 chars from byte 5,
+// terminated by a newline and padded with spaces.
+const EDID_DESCRIPTOR_OFFSETS = [54, 72, 90, 108];
+const EDID_DESCRIPTOR_LENGTH = 18;
+const EDID_DESCRIPTOR_TAG = 3;
+const EDID_DESCRIPTOR_TEXT = 5;
+const EDID_TAG_SERIAL = 0xff;
+const EDID_TAG_NAME = 0xfc;
+// The 32-bit numeric serial in the vendor block - the fallback identity for a
+// panel that ships no serial descriptor.
+const EDID_NUMERIC_SERIAL = 12;
+/** The text of the display descriptor carrying `tag`, or '' when the EDID has none */
+export function edidDescriptor(edid, tag) {
+    for (const offset of EDID_DESCRIPTOR_OFFSETS) {
+        if (offset + EDID_DESCRIPTOR_LENGTH > edid.length)
+            break;
+        if (edid.readUInt16LE(offset) !== 0 || edid[offset + 2] !== 0 || edid[offset + EDID_DESCRIPTOR_TAG] !== tag)
+            continue;
+        const text = edid.toString('latin1', offset + EDID_DESCRIPTOR_TEXT, offset + EDID_DESCRIPTOR_LENGTH);
+        const end = text.indexOf('\n');
+        return (end >= 0 ? text.substring(0, end) : text).trim();
+    }
+    return '';
+}
+/**
+ * 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 function edidSerial(edid) {
+    const text = edidDescriptor(edid, EDID_TAG_SERIAL);
+    if (text)
+        return text;
+    if (edid.length < EDID_NUMERIC_SERIAL + 4)
+        return '';
+    const numeric = edid.readUInt32LE(EDID_NUMERIC_SERIAL);
+    return numeric ? String(numeric) : '';
+}
+/**
+ * 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 function readEdid(edidId, instance) {
+    if (!edidId || !instance || !user32.RegGetBinaryHKLM)
+        return null;
+    return user32.RegGetBinaryHKLM(`SYSTEM\\CurrentControlSet\\Enum\\DISPLAY\\${edidId}\\${instance}\\Device Parameters`, 'EDID');
+}
+/**
+ * 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 function enumerateMonitors() {
+    if (isBun || !user32.EnumDisplayDevicesW)
+        throw new Error('Monitor arrangement needs Node.js with koffi; it is not available under Bun.');
+    const monitors = [];
+    for (let i = 0;; i++) {
+        const adapter = user32.EnumDisplayDevicesW(null, i, 0);
+        if (!adapter)
+            break;
+        if (!(adapter.stateFlags & DISPLAY_DEVICE_ATTACHED_TO_DESKTOP))
+            continue;
+        if (adapter.stateFlags & DISPLAY_DEVICE_MIRRORING_DRIVER)
+            continue;
+        // An attached adapter always has a current mode; if the call fails
+        // anyway the monitor is still listed, with a 0x0@0 mode that is
+        // visibly wrong rather than silently missing.
+        const mode = user32.EnumDisplaySettingsW(adapter.deviceName) ?? { x: 0, y: 0, width: 0, height: 0, hz: 0 };
+        // The monitor on the adapter. Its interface path is
+        // \\?\DISPLAY#<EdidId>#<instance>#{guid}; the middle two name the
+        // registry key that holds its EDID.
+        const monitor = user32.EnumDisplayDevicesW(adapter.deviceName, 0, EDD_GET_DEVICE_INTERFACE_NAME);
+        const pathParts = (monitor?.deviceID ?? '').split('#');
+        const edidId = pathParts[1] ?? '';
+        const instance = pathParts[2] ?? '';
+        const edid = readEdid(edidId, instance);
+        const serial = edid ? edidSerial(edid) : '';
+        const name = (edid && edidDescriptor(edid, EDID_TAG_NAME)) || monitor?.deviceString || adapter.deviceString;
+        monitors.push({
+            device: adapter.deviceName,
+            edidId,
+            serial,
+            id: monitorId(edidId, serial),
+            name,
+            x: mode.x,
+            y: mode.y,
+            width: mode.width,
+            height: mode.height,
+            hz: mode.hz,
+            primary: (adapter.stateFlags & DISPLAY_DEVICE_PRIMARY_DEVICE) !== 0,
+        });
+    }
+    return monitors;
+}
+/**
+ * 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 function stageMonitorPosition(device, x, y, primary) {
+    if (!user32.StageDisplayPosition)
+        return DISP_CHANGE_FAILED;
+    return user32.StageDisplayPosition(device, x, y, primary);
+}
+/** Apply every staged position. Returns a DISP_CHANGE_* code. */
+export function applyMonitorPositions() {
+    if (!user32.ApplyDisplayChanges)
+        return DISP_CHANGE_FAILED;
+    return user32.ApplyDisplayChanges();
+}
+/** Human text for a ChangeDisplaySettingsExW return code */
+export function dispChangeText(code) {
+    switch (code) {
+        case DISP_CHANGE_SUCCESSFUL: return 'success';
+        case DISP_CHANGE_RESTART: return 'needs a restart';
+        case DISP_CHANGE_FAILED: return 'the display driver failed the mode';
+        case DISP_CHANGE_BADMODE: return 'mode not supported';
+        case DISP_CHANGE_NOTUPDATED: return 'unable to write to the registry';
+        case DISP_CHANGE_BADFLAGS: return 'invalid flags';
+        case DISP_CHANGE_BADPARAM: return 'invalid parameter';
+        case DISP_CHANGE_BADDUALVIEW: return 'DualView not supported';
+        default: return `unknown code ${code}`;
+    }
+}
+//# sourceMappingURL=monitors.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/winpos",
-  "version": "2.0.52",
+  "version": "2.0.53",
   "description": "TypeScript implementation of winpos - Windows window positioning utility",
   "type": "module",
   "main": "index.js",
@@ -32,7 +32,8 @@
     "@types/node": "^25.3.0"
   },
   "dependencies": {
-    "@bobfrankston/msger": "^0.1.424",
+    "@bobfrankston/msger": "^0.1.434",
+    "@bobfrankston/userconfig": "^1.0.15",
     "jsonc-parser": "^3.3.1",
     "koffi": "^2.9.2"
   },
@@ -47,14 +48,20 @@
     "url": "https://github.com/BobFrankston/winpos/issues"
   },
   "homepage": "https://github.com/BobFrankston/winpos#readme",
+  "allowScripts": {
+    "file:../../../msgx/msger": true,
+    "koffi": true
+  },
   ".dependencies": {
     "@bobfrankston/msger": "file:../msgx/msger",
+    "@bobfrankston/userconfig": "file:../userconfig",
     "jsonc-parser": "^3.3.1",
     "koffi": "^2.9.2"
   },
   ".transformedSnapshot": {
     "dependencies": {
-      "@bobfrankston/msger": "^0.1.424",
+      "@bobfrankston/msger": "^0.1.434",
+      "@bobfrankston/userconfig": "^1.0.15",
       "jsonc-parser": "^3.3.1",
       "koffi": "^2.9.2"
     }

package/screenlayout.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Monitor arrangement layouts: save the current arrangement, restore a saved
+ * one to whichever of its monitors are present, verify by reading back, and
+ * watch for Windows undoing it.
+ *
+ * Why this is in winpos: winpos's screen numbers are the monitors sorted by
+ * position, and saved window layouts address screens by that number. When
+ * Windows reverts the arrangement (it keeps one layout per exact set of
+ * connected monitors, and a DisplayPort monitor that sleeps leaves the set),
+ * every screen number changes and every window layout lands on the wrong
+ * panel. Restoring the monitors is a precondition for restoring the windows.
+ *
+ * 2026-09-24 - Claude Code (Fable 5.1), at Bob's direction. Ported from
+ * %OneDrive%\xfer\bin\displays.ps1; the file format is the same, so a layout
+ * copies between the two. Background: .llm/screens-restore.md and
+ * %OneDrive%\Documents\AI\displays.md.
+ */
+import { MonitorInfo } from './monitors.js';
+import type { ScreenInfo } from './screens.js';
+/** One monitor as saved in a layout */
+export interface SavedMonitor {
+    /** EdidId:serial, see MonitorInfo.id */
+    id: string;
+    /** Friendly name, for messages only - identity is `id` */
+    name: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    hz: number;
+    primary: boolean;
+}
+/** A saved arrangement */
+export interface ScreenLayout {
+    /** ISO timestamp of the save */
+    saved: string;
+    monitors: SavedMonitor[];
+}
+/** The layouts file: per machine, per layout name. Same shape as displays.json. */
+export type LayoutsFile = Record<string, Record<string, ScreenLayout>>;
+/** The one standard layout per machine; a name is only for an alternate (travel, single-monitor...) */
+export declare const DEFAULT_LAYOUT_NAME = "default";
+/** Where the layouts live: in the user config area, per the UserConfig path rule */
+export declare const layoutsPath: string;
+/**
+ * This machine's key in the layouts file. Upper-cased to match COMPUTERNAME,
+ * which is what displays.json was keyed by, so a layout copies across.
+ */
+export declare const machine: string;
+export declare function readLayouts(): LayoutsFile;
+export declare function writeLayouts(all: LayoutsFile): void;
+/** The layouts saved for this machine, by name */
+export declare function machineLayouts(): Record<string, ScreenLayout>;
+/** A saved layout for this machine, or null */
+export declare function getLayout(name?: string): ScreenLayout;
+/** Save the current arrangement under `name` for this machine */
+export declare function saveLayout(name?: string): ScreenLayout;
+/** A layout given inline (a monitors array, or a full layout) or by saved name, as a ScreenLayout */
+export declare function resolveLayout(spec: string | ScreenLayout | SavedMonitor[]): ScreenLayout;
+/** Whether a present monitor sits where the layout says (position and primary flag) */
+export declare function inPlace(saved: SavedMonitor, actual: MonitorInfo): boolean;
+/** The saved monitors that are present but not where the layout puts them */
+export declare function outOfPlace(layout: ScreenLayout, present: MonitorInfo[]): SavedMonitor[];
+export interface RestoreMismatch {
+    saved: SavedMonitor;
+    /** What Windows actually did; null if the monitor vanished during the apply */
+    actual: MonitorInfo;
+}
+export interface RestoreResult {
+    /** Everything went where it was asked */
+    ok: boolean;
+    /** Saved monitors that were present and positioned */
+    applied: SavedMonitor[];
+    /** Saved monitors not connected, skipped */
+    absent: SavedMonitor[];
+    /** Connected monitors the layout does not mention, left where Windows put them */
+    unknown: MonitorInfo[];
+    /** Applied monitors that did not land where asked */
+    mismatches: RestoreMismatch[];
+    /** The arrangement after the apply and settle - what is actually on the desktop */
+    after: MonitorInfo[];
+}
+/**
+ * Re-apply a layout to whichever of its monitors are present, then read the
+ * arrangement back and report what Windows actually did.
+ *
+ * Throws when nothing can be applied (no saved monitor connected, or the
+ * driver refused) - the caller turns that into stderr + exit 1. Mismatches
+ * are not an exception: they are the round-trip verdict, in the result.
+ */
+export declare function restoreLayout(layout: ScreenLayout, log?: (msg: string) => void): Promise<RestoreResult>;
+/**
+ * The monitor table, one line per monitor plus a header. With `screens` given
+ * (winpos's sorted list) the first column is the winpos screen number, which
+ * is the point: it ties "screen 2" to a physical panel.
+ */
+export declare function formatMonitors(monitors: MonitorInfo[], screens?: ScreenInfo[]): string[];
+/**
+ * Stay resident and re-apply the named layout whenever Windows moves a saved
+ * monitor away from it. Never returns; ctrl-C ends it.
+ *
+ * Traps this is built around: the apply fires a display change of its own
+ * (quiet period); Windows closes gaps when a monitor is absent (the read-back
+ * is logged, not the request); and if an apply changes nothing, Windows has
+ * refused that set, so retrying is a loop - it stops until the set changes.
+ */
+export declare function watchLayout(name?: string, log?: (msg: string) => void): Promise<never>;
+//# sourceMappingURL=screenlayout.d.ts.map

package/screenlayout.js

@@ -0,0 +1,243 @@
+/**
+ * Monitor arrangement layouts: save the current arrangement, restore a saved
+ * one to whichever of its monitors are present, verify by reading back, and
+ * watch for Windows undoing it.
+ *
+ * Why this is in winpos: winpos's screen numbers are the monitors sorted by
+ * position, and saved window layouts address screens by that number. When
+ * Windows reverts the arrangement (it keeps one layout per exact set of
+ * connected monitors, and a DisplayPort monitor that sleeps leaves the set),
+ * every screen number changes and every window layout lands on the wrong
+ * panel. Restoring the monitors is a precondition for restoring the windows.
+ *
+ * 2026-09-24 - Claude Code (Fable 5.1), at Bob's direction. Ported from
+ * %OneDrive%\xfer\bin\displays.ps1; the file format is the same, so a layout
+ * copies between the two. Background: .llm/screens-restore.md and
+ * %OneDrive%\Documents\AI\displays.md.
+ */
+import { hostname } from 'os';
+import { join } from 'path';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { configDir } from '@bobfrankston/userconfig';
+import { enumerateMonitors, stageMonitorPosition, applyMonitorPositions, dispChangeText } from './monitors.js';
+import { DISP_CHANGE_SUCCESSFUL } from './ffi-wrapper.js';
+/** The one standard layout per machine; a name is only for an alternate (travel, single-monitor...) */
+export const DEFAULT_LAYOUT_NAME = 'default';
+/** Where the layouts live: in the user config area, per the UserConfig path rule */
+export const layoutsPath = join(configDir, 'winpos-screens.json');
+/** How long Windows takes to settle after a ChangeDisplaySettingsEx apply before a read-back is meaningful */
+const APPLY_SETTLE_MS = 1500;
+/**
+ * This machine's key in the layouts file. Upper-cased to match COMPUTERNAME,
+ * which is what displays.json was keyed by, so a layout copies across.
+ */
+export const machine = hostname().toUpperCase();
+export function readLayouts() {
+    if (!existsSync(layoutsPath))
+        return {};
+    return JSON.parse(readFileSync(layoutsPath, 'utf-8'));
+}
+export function writeLayouts(all) {
+    mkdirSync(configDir, { recursive: true });
+    writeFileSync(layoutsPath, JSON.stringify(all, null, 2) + '\n', 'utf-8');
+}
+/** The layouts saved for this machine, by name */
+export function machineLayouts() {
+    return readLayouts()[machine] ?? {};
+}
+/** A saved layout for this machine, or null */
+export function getLayout(name = DEFAULT_LAYOUT_NAME) {
+    return machineLayouts()[name] ?? null;
+}
+/** Save the current arrangement under `name` for this machine */
+export function saveLayout(name = DEFAULT_LAYOUT_NAME) {
+    const monitors = enumerateMonitors();
+    const layout = {
+        saved: new Date().toISOString(),
+        monitors: monitors.map(m => ({ id: m.id, name: m.name, x: m.x, y: m.y, width: m.width, height: m.height, hz: m.hz, primary: m.primary })),
+    };
+    const all = readLayouts();
+    all[machine] ??= {};
+    all[machine][name] = layout;
+    writeLayouts(all);
+    return layout;
+}
+/** A layout given inline (a monitors array, or a full layout) or by saved name, as a ScreenLayout */
+export function resolveLayout(spec) {
+    if (typeof spec === 'string')
+        return getLayout(spec);
+    if (Array.isArray(spec))
+        return { saved: '', monitors: spec };
+    return spec;
+}
+/** Whether a present monitor sits where the layout says (position and primary flag) */
+export function inPlace(saved, actual) {
+    return actual.x === saved.x && actual.y === saved.y && actual.primary === saved.primary;
+}
+/** The saved monitors that are present but not where the layout puts them */
+export function outOfPlace(layout, present) {
+    const byId = new Map(present.map(m => [m.id, m]));
+    return layout.monitors.filter(saved => {
+        const actual = byId.get(saved.id);
+        return actual && !inPlace(saved, actual);
+    });
+}
+/**
+ * Re-apply a layout to whichever of its monitors are present, then read the
+ * arrangement back and report what Windows actually did.
+ *
+ * Throws when nothing can be applied (no saved monitor connected, or the
+ * driver refused) - the caller turns that into stderr + exit 1. Mismatches
+ * are not an exception: they are the round-trip verdict, in the result.
+ */
+export async function restoreLayout(layout, log = console.log) {
+    const present = enumerateMonitors();
+    const byId = new Map(present.map(m => [m.id, m]));
+    const applied = [];
+    const absent = [];
+    for (const saved of layout.monitors) {
+        const target = byId.get(saved.id);
+        if (!target) {
+            absent.push(saved);
+            log(`Absent:  ${saved.name} [${saved.id}] is in the layout but not connected; skipped.`);
+            continue;
+        }
+        const rc = stageMonitorPosition(target.device, saved.x, saved.y, saved.primary);
+        if (rc !== DISP_CHANGE_SUCCESSFUL)
+            throw new Error(`ChangeDisplaySettingsEx failed for ${saved.name} (${target.device}): ${dispChangeText(rc)}`);
+        applied.push(saved);
+    }
+    const savedIds = new Set(layout.monitors.map(m => m.id));
+    const unknown = present.filter(m => !savedIds.has(m.id));
+    for (const m of unknown)
+        log(`Unknown: ${m.name} [${m.id}] is connected but not in the layout; left where Windows put it.`);
+    if (applied.length === 0)
+        throw new Error('None of the monitors in the layout are connected; nothing applied.');
+    const rc = applyMonitorPositions();
+    if (rc !== DISP_CHANGE_SUCCESSFUL)
+        throw new Error(`Apply failed: ${dispChangeText(rc)}`);
+    // Round trip: report what Windows did, not what was asked. Windows closes
+    // gaps when a monitor is missing, so the two can differ legitimately.
+    await new Promise(resolve => setTimeout(resolve, APPLY_SETTLE_MS));
+    const after = enumerateMonitors();
+    const afterById = new Map(after.map(m => [m.id, m]));
+    const mismatches = [];
+    for (const saved of applied) {
+        const actual = afterById.get(saved.id);
+        if (!actual || !inPlace(saved, actual)) {
+            mismatches.push({ saved, actual });
+            const got = actual ? `${actual.x},${actual.y} primary=${actual.primary}` : 'gone';
+            log(`Mismatch: ${saved.name} asked ${saved.x},${saved.y} primary=${saved.primary} -> got ${got}`);
+        }
+    }
+    log(`Applied layout: ${applied.length} of ${layout.monitors.length} saved monitors positioned.`);
+    return { ok: mismatches.length === 0, applied, absent, unknown, mismatches, after };
+}
+/**
+ * The monitor table, one line per monitor plus a header. With `screens` given
+ * (winpos's sorted list) the first column is the winpos screen number, which
+ * is the point: it ties "screen 2" to a physical panel.
+ */
+export function formatMonitors(monitors, screens = []) {
+    const indexByDevice = new Map(screens.map((s, i) => [s.deviceName, i]));
+    const rows = monitors.map(m => ({
+        scr: indexByDevice.has(m.device) ? String(indexByDevice.get(m.device)) : '-',
+        device: m.device.replace(/^\\\\\.\\/, ''),
+        id: m.id,
+        name: m.name,
+        position: `${m.x},${m.y}`,
+        mode: `${m.width}x${m.height}@${m.hz}`,
+        primary: m.primary ? '*' : '',
+    }));
+    const order = (scr) => scr === '-' ? Number.MAX_SAFE_INTEGER : Number(scr);
+    rows.sort((a, b) => order(a.scr) - order(b.scr));
+    const header = { scr: 'Scr', device: 'Device', id: 'Id', name: 'Name', position: 'Position', mode: 'Mode', primary: 'Primary' };
+    const columns = ['scr', 'device', 'id', 'name', 'position', 'mode', 'primary'];
+    const widths = Object.fromEntries(columns.map(c => [c, Math.max(header[c].length, ...rows.map(r => r[c].length))]));
+    const line = (r) => columns.map(c => r[c].padEnd(widths[c])).join('  ').trimEnd();
+    return [line(header), columns.map(c => '-'.repeat(widths[c])).join('  '), ...rows.map(line)];
+}
+// Watch: poll rather than a WM_DISPLAYCHANGE window, so there is no message
+// loop and no koffi callback (problem.txt). A poll every few seconds is two
+// cheap user32 calls per monitor.
+const WATCH_POLL_MS = 3000;
+/** Consecutive identical polls before a changed arrangement counts as settled */
+const WATCH_SETTLE_POLLS = 2;
+/** After an apply, ignore what looks like change for this long: the apply itself is one */
+const WATCH_QUIET_MS = 6000;
+/** What matters for "did the arrangement change": who is present and where */
+function arrangementSignature(monitors) {
+    return monitors.map(m => `${m.id}@${m.x},${m.y}${m.primary ? '*' : ''}`).sort().join(' ');
+}
+const stamp = () => new Date().toLocaleTimeString();
+/**
+ * Stay resident and re-apply the named layout whenever Windows moves a saved
+ * monitor away from it. Never returns; ctrl-C ends it.
+ *
+ * Traps this is built around: the apply fires a display change of its own
+ * (quiet period); Windows closes gaps when a monitor is absent (the read-back
+ * is logged, not the request); and if an apply changes nothing, Windows has
+ * refused that set, so retrying is a loop - it stops until the set changes.
+ */
+export async function watchLayout(name = DEFAULT_LAYOUT_NAME, log = console.log) {
+    if (!getLayout(name))
+        throw new Error(`No layout '${name}' saved for ${machine}. Run 'winpos -screens save' first.`);
+    log(`${stamp()} Watching the monitor arrangement against layout '${name}' every ${WATCH_POLL_MS / 1000}s (ctrl-C to stop)`);
+    // The first read is the baseline, not a change - and it counts as settled,
+    // so an arrangement that is already wrong when the watch starts is fixed
+    // on the first poll rather than waiting for Windows to move something.
+    let lastSignature = arrangementSignature(enumerateMonitors());
+    let stablePolls = WATCH_SETTLE_POLLS;
+    let quietUntil = 0;
+    let refusedSignature = ''; // an arrangement Windows would not change; wait for the set to change
+    for (;;) {
+        await new Promise(resolve => setTimeout(resolve, WATCH_POLL_MS));
+        const present = enumerateMonitors();
+        const signature = arrangementSignature(present);
+        if (signature !== lastSignature) {
+            lastSignature = signature;
+            stablePolls = 0;
+            log(`${stamp()} Arrangement changed: ${present.map(m => `${m.name} ${m.x},${m.y}`).join('; ')}`);
+            continue;
+        }
+        if (++stablePolls < WATCH_SETTLE_POLLS)
+            continue;
+        if (Date.now() < quietUntil)
+            continue;
+        if (signature === refusedSignature)
+            continue;
+        // Re-read each time so a fresh 'winpos -screens save' takes effect without a restart.
+        const layout = getLayout(name);
+        if (!layout) {
+            log(`${stamp()} Layout '${name}' has disappeared from ${layoutsPath}; waiting.`);
+            continue;
+        }
+        const moved = outOfPlace(layout, present);
+        if (moved.length === 0)
+            continue;
+        log(`${stamp()} Out of place: ${moved.map(m => m.name).join(', ')}; restoring layout '${name}'`);
+        try {
+            const result = await restoreLayout(layout, log);
+            quietUntil = Date.now() + WATCH_QUIET_MS;
+            const afterSignature = arrangementSignature(result.after);
+            if (afterSignature === signature) {
+                refusedSignature = signature;
+                log(`${stamp()} Windows did not change the arrangement; not retrying until the monitor set changes.`);
+            }
+            else if (!result.ok) {
+                log(`${stamp()} ${result.mismatches.length} monitor(s) did not land where asked; will re-check after the next change.`);
+            }
+            else {
+                log(`${stamp()} Layout '${name}' restored.`);
+            }
+            lastSignature = afterSignature;
+            stablePolls = 0;
+        }
+        catch (error) {
+            quietUntil = Date.now() + WATCH_QUIET_MS;
+            refusedSignature = signature;
+            log(`${stamp()} Restore failed: ${error.message}; not retrying until the monitor set changes.`);
+        }
+    }
+}
+//# sourceMappingURL=screenlayout.js.map

package/screens.d.ts

@@ -3,6 +3,14 @@
  */
 export interface ScreenInfo {
     deviceName: string;
+    /**
+     * Which physical monitor this is: EDID id + serial (e.g. GSM7721:106NTKF55597),
+     * the key monitor layouts use. Undefined when the identity could not be read.
+     * 2026-09-24 - Claude Code (Fable 5.1): added with the -screens commands.
+     */
+    id?: string;
+    /** The monitor's friendly name from its EDID, e.g. "LG HDR 5K" */
+    name?: string;
     bounds: {
         Left: number;
         Top: number;

package/screens.js

@@ -2,6 +2,7 @@
  * Screen management - enumerate and sort displays
  */
 import { user32, isBun, MONITORINFOF_PRIMARY, DEFAULT_SCALE_PERCENT } from './ffi-wrapper.js';
+import { enumerateMonitors } from './monitors.js';
 /** Display scaling of a screen as a factor (1.25 for a 125% display) */
 export function screenScale(screen) {
     return (screen.scalePercent || DEFAULT_SCALE_PERCENT) / 100;
@@ -109,6 +110,26 @@ export function enumerateScreens() {
             scalePercent: DEFAULT_SCALE_PERCENT,
         });
     }
+    // 2026-09-24 - Claude Code (Fable 5.1), at Bob's direction: tag each screen
+    // with the monitor's identity, joined on the adapter name. One identity
+    // mechanism for both halves of winpos: the window layouts and the monitor
+    // layouts name the same panel the same way.
+    try {
+        const byDevice = new Map(enumerateMonitors().map(m => [m.device, m]));
+        for (const screen of screens) {
+            const monitor = byDevice.get(screen.deviceName);
+            if (!monitor)
+                continue;
+            screen.id = monitor.id;
+            screen.name = monitor.name;
+        }
+    }
+    catch (error) {
+        // Justified swallow: identity is decoration here - window positioning
+        // works from bounds alone and always has. The -screens commands call
+        // enumerateMonitors() themselves and report this same error there,
+        // so it is not lost, only deferred to the command that needs it.
+    }
     return screens;
 }
 // Tops within this many pixels are treated as the same row (DPI/rounding noise).