zpos-adjuster/README.md

A Node.js wrapper for ZPos Adjuster to control window Z-order (Windows only)

# Zpos-Adjuster

> 🔧 A Node.js wrapper around the native Windows binary `ZPosAdjuster.exe` for adjusting a window's Z-order (Topmost, Bottom, Desktop-widget, etc.).

[![npm version](https://img.shields.io/npm/v/zpos-adjuster.svg)](https://www.npmjs.com/package/zpos-adjuster)
![Platform](https://img.shields.io/badge/platform-windows-blue)

## Features

- Set any window to:
  - Topmost
  - Normal
  - Bottom
  - Desktop-widget mode (safe from Win+D)
- Restore original state
- CLI and API usage
- Works on Windows only

## Installation

```bash
npm install zpos-adjuster
````

> ⚠️ Windows only — this module uses a native `.exe` under the hood.

---

## Usage

### 1. Programmatic (Node.js)

```js
const adjustZPos = require('zpos-adjuster');

adjustZPos({ zpos: -2, title: 'Untitled - Notepad' })
  .then(console.log)
  .catch(console.error);
```

### Parameters

| Parameter |       Type      | Required | Description                            |
| --------: | :-------------: | :------: | :------------------------------------- |
|    `zpos` | Number or `'r'` |     ✅    | Z-position value or `'r'` to reset     |
|   `title` |      String     |     ✅    | Exact window title (e.g. from taskbar) |

#### Z-Position Values

| Value | Description                             |
| ----: | --------------------------------------- |
| `'r'` | Reset to original window style/position |
|   `1` | Topmost                                 |
|   `0` | Normal                                  |
|  `-1` | Bottom                                  |
|  `-2` | Desktop-widget mode (Win+D safe)        |

---

### 2. CLI Usage

```bash
node node_modules/zpos-adjuster/index.js --zpos -1 --t "Untitled - Notepad"
```

---

## Example

```js
// Set a window to desktop widget mode
adjustZPos({ zpos: -2, title: 'My Widget' })
  .then(msg => console.log('✅', msg))
  .catch(err => console.error('❌', err.message));
```

---

## License

[MIT](./LICENSE) © nstechbytes

---

## Author

**nstechbytes**
GitHub: [@nstechbytes](https://github.com/nstechbytes)
Website: [nstechbytes.pages.dev](https://nstechbytes.pages.dev)