@bobfrankston/winpos 2.0.49 → 2.0.51

package/README.md

@@ -96,6 +96,25 @@ Screens are numbered starting from 0, sorted by position:
 - `*` - 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.
+
+```typescript
+import { showScreenNumbers, enumerateScreens, sortScreens } from '@bobfrankston/winpos';
+
+await showScreenNumbers(sortScreens(enumerateScreens()), 5);
+```
+
 ## Parameters
 
 ### Positional (legacy)

package/ffi-wrapper.d.ts

@@ -27,6 +27,7 @@ export interface MONITORINFO {
     dwFlags: number;
 }
 export declare const MONITORINFOF_PRIMARY = 1;
+export declare const DEFAULT_SCALE_PERCENT = 100;
 export interface WindowsAPI {
     EnumWindows: (callback: (hwnd: bigint, lParam: bigint) => boolean, lParam: bigint) => boolean;
     GetWindowTextW: (hwnd: bigint, text: any, maxCount: number) => number;
@@ -39,6 +40,8 @@ export interface WindowsAPI {
     GetWindowPlacement: (hwnd: bigint, placement: any) => boolean;
     EnumDisplayMonitors: (callback: (hMonitor: bigint, hdcMonitor: bigint, lprcMonitor: any, dwData: bigint) => boolean, dwData: bigint) => boolean;
     GetMonitorInfoW: (hMonitor: bigint, lpmi: any) => boolean;
+    /** Monitor scale factor as a percent (100, 125, 150...). 100 when unavailable. */
+    GetScaleFactorForMonitor?: (hMonitor: bigint) => number;
 }
 declare const user32: WindowsAPI;
 export { user32, isBun };

package/ffi-wrapper.js

@@ -17,6 +17,8 @@ export const SW_SHOWMINNOACTIVE = 7;
 export const SW_SHOWNA = 8;
 export const SW_RESTORE = 9;
 export const MONITORINFOF_PRIMARY = 1;
+// Monitor scale factor as a percentage (100 = no scaling, 125 = 125%)
+export const DEFAULT_SCALE_PERCENT = 100;
 async function initializeFFI() {
     if (isBun) {
         // @ts-ignore - bun:ffi is only available in Bun
@@ -95,6 +97,19 @@ async function initializeFFI() {
     const MonitorEnumProc = koffi.proto('bool __stdcall MonitorEnumProc(void *hMonitor, void *hdcMonitor, RECT *lprcMonitor, void *dwData)');
     const EnumDisplayMonitors = lib.func('bool __stdcall EnumDisplayMonitors(void *hdc, RECT *lprcClip, MonitorEnumProc *lpfnEnum, void *dwData)');
     const GetMonitorInfoW = lib.func('bool __stdcall GetMonitorInfoW(void *hMonitor, void *lpmi)');
+    // Per-monitor scaling lives in shcore.dll (Windows 8.1+). Optional: a
+    // missing shcore just means every monitor reports 100%.
+    // GetScaleFactorForMonitor, not GetDpiForMonitor: the DPI call reports the
+    // DPI *as the calling process sees it*, and winpos is DPI-unaware, so it
+    // always answers 96. This one reports the monitor's real scale factor.
+    let GetScaleFactorForMonitorRaw = null;
+    try {
+        const shcore = koffi.load('shcore.dll');
+        GetScaleFactorForMonitorRaw = shcore.func('int __stdcall GetScaleFactorForMonitor(void *hMonitor, void *pScale)');
+    }
+    catch {
+        // Leave null - callers fall back to 100%
+    }
     // Keep references to registered callbacks to prevent garbage collection
     // These must persist for the entire duration of the native callback invocation
     const __callbackRefs = [];
@@ -166,6 +181,13 @@ async function initializeFFI() {
             }
             return result;
         },
+        GetScaleFactorForMonitor: (hMonitor) => {
+            if (!GetScaleFactorForMonitorRaw)
+                return DEFAULT_SCALE_PERCENT;
+            const scale = Buffer.alloc(4);
+            const hr = GetScaleFactorForMonitorRaw(hMonitor, scale);
+            return hr === 0 ? (scale.readUInt32LE(0) || DEFAULT_SCALE_PERCENT) : DEFAULT_SCALE_PERCENT;
+        },
     };
 }
 const user32 = await initializeFFI();

package/ignores.txt

@@ -68,6 +68,7 @@ ViewDeferd*
 W
 Widgets
 Windows*
+winpos screen *
 WinUI*
 WISPTIS
 WMS*

package/index.d.ts

@@ -7,6 +7,7 @@ import { user32, RECT } from './ffi-wrapper.js';
 import { enumerateScreens, sortScreens, 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';
 export interface WindowConfig {
     name: string;
     regex?: boolean;
@@ -23,7 +24,7 @@ export interface WindowConfig {
     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, user32 };
+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 };
 /**
  * Convert screen-relative coordinates to global coordinates
  * @param x - X coordinate relative to screen

package/index.js

@@ -7,12 +7,13 @@ import { user32 } from './ffi-wrapper.js';
 import { enumerateScreens, sortScreens } 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 { 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' };
 // 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, user32 };
+export { WindowState, enumerateScreens, sortScreens, enumerateWindows, findWindowsByPattern, getWindowState, setWindowState, isMinimized, isMaximized, isNormal, minimizeWindow, maximizeWindow, restoreWindow, enumerateTabs, mightHaveTabs, TAB_ENUMERATION_NOTE, showScreenNumbers, user32 };
 // WindowConfig and ConfigFile types are exported from interface definitions above
 // Note: screenPosToPos is exported separately below (after the function definition)
 /**
@@ -447,8 +448,19 @@ function listAllWindows(includeIgnored = false) {
     }
     console.log();
     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);
 }
 function usage(msg = '') {
+    printUsage(msg);
+    process.exit(1);
+}
+/**
+ * The usage text on its own - no exit, so the no-argument case can print it
+ * while the screen-number overlays are still being launched.
+ */
+function printUsage(msg = '') {
     if (msg)
         console.log(msg);
     console.log('Usage: winpos [options] <title> <x> <y> <screen> [<width> <height>]');
@@ -474,6 +486,8 @@ function usage(msg = '') {
     console.log('Position/size values can be pixels or percentages (e.g. 50%)');
     console.log('Title can be regex (/pattern/) or prefix (title*)');
     console.log('* = list windows, ** = list all including ignored');
+    console.log(`  (both, like winpos with no arguments, also flash each screen's`);
+    console.log(`   number on that screen for ${OVERLAY_SECONDS} seconds)`);
     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: [{...}, {...}]');
@@ -484,7 +498,6 @@ function usage(msg = '') {
         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)}`);
     }
-    process.exit(1);
 }
 export function run(args) {
     // Initialize screens
@@ -596,6 +609,17 @@ export function run(args) {
         showWindowInfo(posArgs[0]);
         return;
     }
+    // Nothing to act on (bare winpos, or -help): flash each screen's number on
+    // that screen while the usage text - screen table and all - prints, so the
+    // table has something to point at. The overlays time out and close
+    // 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);
+        printUsage();
+        void overlays.finally(() => process.exit(1));
+        return;
+    }
     if (posArgs.length < 4) {
         usage();
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/winpos",
-  "version": "2.0.49",
+  "version": "2.0.51",
   "description": "TypeScript implementation of winpos - Windows window positioning utility",
   "type": "module",
   "main": "index.js",
@@ -32,6 +32,7 @@
     "@types/node": "^25.3.0"
   },
   "dependencies": {
+    "@bobfrankston/msger": "^0.1.424",
     "jsonc-parser": "^3.3.1",
     "koffi": "^2.9.2"
   },
@@ -45,5 +46,17 @@
   "bugs": {
     "url": "https://github.com/BobFrankston/winpos/issues"
   },
-  "homepage": "https://github.com/BobFrankston/winpos#readme"
+  "homepage": "https://github.com/BobFrankston/winpos#readme",
+  ".dependencies": {
+    "@bobfrankston/msger": "file:../msgx/msger",
+    "jsonc-parser": "^3.3.1",
+    "koffi": "^2.9.2"
+  },
+  ".transformedSnapshot": {
+    "dependencies": {
+      "@bobfrankston/msger": "^0.1.424",
+      "jsonc-parser": "^3.3.1",
+      "koffi": "^2.9.2"
+    }
+  }
 }

package/screennums.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Screen number overlay - briefly flashes each screen's winpos index in the
+ * middle of that screen, so you can see which physical display is screen 0,
+ * screen 1, ... without counting corners.
+ *
+ * Rendered with msger (@bobfrankston/msger). The overlays are detached and
+ * self-closing, so winpos exits immediately and leaves them up.
+ */
+import { type ScreenInfo } from './screens.js';
+export declare const OVERLAY_SECONDS = 5;
+/**
+ * Show the index of every screen in the middle of that screen.
+ *
+ * Never throws: the overlay is a convenience, so a missing or unhappy msger
+ * must not break the window listing it accompanies.
+ *
+ * @param screens - Screens in winpos order (the index shown is the array index)
+ * @param seconds - How long each overlay stays up
+ */
+export declare function showScreenNumbers(screens: ScreenInfo[], seconds?: number): Promise<void>;
+//# sourceMappingURL=screennums.d.ts.map

package/screennums.js

@@ -0,0 +1,102 @@
+/**
+ * Screen number overlay - briefly flashes each screen's winpos index in the
+ * middle of that screen, so you can see which physical display is screen 0,
+ * screen 1, ... without counting corners.
+ *
+ * Rendered with msger (@bobfrankston/msger). The overlays are detached and
+ * self-closing, so winpos exits immediately and leaves them up.
+ */
+import { screenScale } from './screens.js';
+const CARD = 260; // Overlay content size in pixels (square)
+const FRAME_W = 16; // Window border added around that content
+const FRAME_H = 46; // Border + title bar
+export const OVERLAY_SECONDS = 5;
+/**
+ * Full page for one overlay - big number, no msger template or buttons.
+ */
+function overlayHtml(index, screen, seconds) {
+    const b = screen.bounds;
+    // Size in winpos's own coordinates - the numbers you'd type at it - plus
+    // the scaling, since that's why they don't match the monitor's spec sheet.
+    const label = [
+        `${b.Width} x ${b.Height}`,
+        screen.scalePercent !== 100 ? `${screen.scalePercent}%` : '',
+        screen.primary ? 'primary' : ''
+    ].filter(Boolean).join(' - ');
+    return `<!doctype html>
+<html><head><meta charset="utf-8"><title>winpos screen ${index}</title>
+<style>
+  html, body { height: 100%; margin: 0; }
+  body {
+    display: flex; flex-direction: column;
+    align-items: center; justify-content: center;
+    background: #1e1e1e; color: #f0f0f0;
+    font-family: "Segoe UI", system-ui, sans-serif;
+    user-select: none;
+  }
+  .num { font-size: 160px; font-weight: 700; line-height: 1; }
+  .label { font-size: 16px; opacity: 0.65; margin-top: 12px; }
+</style></head>
+<body><div class="num">${index}</div><div class="label">${label}</div>
+<script>
+  // The page dismisses itself: msger's own timeout is only checked when the
+  // window sees an event, so an overlay nobody touches sits there forever.
+  // Posting a result over the IPC bridge is what the msger template does for
+  // a button click - it wakes the host, which then exits.
+  setTimeout(() => {
+    if (window.ipc && window.ipc.postMessage)
+      window.ipc.postMessage(JSON.stringify({ button: 'timeout', timeout: true }));
+    else
+      window.close();
+  }, ${Math.round(seconds * 1000)});
+</script>
+</body></html>`;
+}
+/**
+ * Show the index of every screen in the middle of that screen.
+ *
+ * Never throws: the overlay is a convenience, so a missing or unhappy msger
+ * must not break the window listing it accompanies.
+ *
+ * @param screens - Screens in winpos order (the index shown is the array index)
+ * @param seconds - How long each overlay stays up
+ */
+export async function showScreenNumbers(screens, seconds = OVERLAY_SECONDS) {
+    let showMessageBox;
+    try {
+        ({ showMessageBox } = await import('@bobfrankston/msger'));
+    }
+    catch {
+        return; // msger not installed - skip the overlay silently
+    }
+    // All of them are launched at once so the numbers appear together.
+    await Promise.all(screens.map((screen, i) => {
+        const b = screen.bounds;
+        // msger takes its position in device-independent pixels, which it then
+        // scales by the target monitor's DPI. winpos's own coordinates are
+        // already DIPs *within* a monitor, but each monitor's origin is in
+        // physical pixels - so only the origin needs dividing by the scale.
+        // Without this, the overlay on a 125% monitor whose origin is a few
+        // thousand pixels out lands far right of center (5K screen, 768px off).
+        const scale = screenScale(screen);
+        const x = b.Left / scale + (b.Width - CARD - FRAME_W) / 2;
+        const y = b.Top / scale + (b.Height - CARD - FRAME_H) / 2;
+        return showMessageBox({
+            title: `winpos screen ${i}`,
+            html: overlayHtml(i, screen, seconds),
+            rawHtml: true, // No msger template, no OK button
+            size: { width: CARD, height: CARD },
+            pos: { x: Math.round(x), y: Math.round(y) },
+            timeout: seconds + 5, // Backstop if the page never runs
+            alwaysOnTop: true,
+            detach: true, // Outlives winpos itself
+            // Own WebView2 profile per overlay: msger windows sharing one
+            // user-data dir also share a browser process, and starting all of
+            // them at once made that shared process fall over - overlays came
+            // up one at a time and some died early. Separate profiles start in
+            // parallel and are independent.
+            profile: `winpos-screen-${i}`
+        }).catch(() => { });
+    }));
+}
+//# sourceMappingURL=screennums.js.map

package/screens.d.ts

@@ -12,7 +12,11 @@ export interface ScreenInfo {
         Height: number;
     };
     primary: boolean;
+    /** Display scaling of this monitor as a percent: 100, 125, 150... */
+    scalePercent: number;
 }
+/** Display scaling of a screen as a factor (1.25 for a 125% display) */
+export declare function screenScale(screen: ScreenInfo): number;
 export declare function enumerateScreens(): ScreenInfo[];
 export declare function sortScreens(screens: ScreenInfo[]): ScreenInfo[];
 //# sourceMappingURL=screens.d.ts.map

package/screens.js

@@ -1,7 +1,11 @@
 /**
  * Screen management - enumerate and sort displays
  */
-import { user32, isBun, MONITORINFOF_PRIMARY } from './ffi-wrapper.js';
+import { user32, isBun, MONITORINFOF_PRIMARY, DEFAULT_SCALE_PERCENT } from './ffi-wrapper.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;
+}
 export function enumerateScreens() {
     const screens = [];
     let monitorIndex = 0;
@@ -27,6 +31,7 @@ export function enumerateScreens() {
                             Height: rcMonitor.Bottom - rcMonitor.Top,
                         },
                         primary: (monitorInfo.dwFlags & MONITORINFOF_PRIMARY) !== 0,
+                        scalePercent: user32.GetScaleFactorForMonitor?.(hMonitor) ?? DEFAULT_SCALE_PERCENT,
                     });
                     monitorIndex++;
                 }
@@ -53,6 +58,7 @@ export function enumerateScreens() {
                 Height: 1080,
             },
             primary: true,
+            scalePercent: DEFAULT_SCALE_PERCENT,
         });
     }
     // If no screens were found, add a default one
@@ -68,14 +74,17 @@ export function enumerateScreens() {
                 Height: 1080,
             },
             primary: true,
+            scalePercent: DEFAULT_SCALE_PERCENT,
         });
     }
     return screens;
 }
+// Tops within this many pixels are treated as the same row (DPI/rounding noise).
+const ROW_TOLERANCE = 100;
 export function sortScreens(screens) {
-    // Sort by top (descending), then by left (ascending)
+    // Sort by top (descending), then by left (ascending), with tolerance for rounding
     return screens.sort((a, b) => {
-        if (a.bounds.Top === b.bounds.Top)
+        if (Math.abs(a.bounds.Top - b.bounds.Top) <= ROW_TOLERANCE)
             return a.bounds.Left - b.bounds.Left;
         return b.bounds.Top - a.bounds.Top;
     });