taskbargap 0.1.0__tar.gz

taskbargap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 paone9
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

taskbargap-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: taskbargap
+Version: 0.1.0
+Summary: Find the empty gap in the Windows taskbar and place a top-most window in it, across monitors and DPI.
+Author: paone9
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/paone9/taskbargap
+Project-URL: Issues, https://github.com/paone9/taskbargap/issues
+Project-URL: Changelog, https://github.com/paone9/taskbargap/blob/main/CHANGELOG.md
+Keywords: windows,taskbar,win32,topmost,dpi,widget,taskbar-gap,shell
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Desktop Environment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: ruff==0.16.1; extra == "dev"
+Requires-Dist: bandit==1.9.4; extra == "dev"
+Requires-Dist: pytest==9.1.1; extra == "dev"
+Dynamic: license-file
+
+# taskbargap
+
+[![Platform: Windows 10/11](https://img.shields.io/badge/platform-Windows%2010%20%7C%2011-0078d6)](#honest-limitations)
+[![PyPI](https://img.shields.io/pypi/v/taskbargap)](https://pypi.org/project/taskbargap/)
+[![CI](https://github.com/paone9/taskbargap/actions/workflows/ci.yml/badge.svg)](https://github.com/paone9/taskbargap/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/paone9/taskbargap/actions/workflows/codeql.yml/badge.svg)](https://github.com/paone9/taskbargap/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/paone9/taskbargap/badge)](https://scorecard.dev/viewer/?uri=github.com/paone9/taskbargap)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Find the empty stretch of the Windows taskbar, the gap between your app buttons
+and the system tray, and put a top-most window in it. Correctly, across multiple
+monitors and per-monitor DPI scaling.
+
+Windows leaves that strip unused, so a small always-on widget there costs you no
+screen space. Doing it properly turns out to be fiddly. You have to detect the gap
+across two generations of taskbar internals, handle per-monitor DPI and the
+difference between physical and logical pixels, keep the window fitted as apps
+open and close, and end up with a top-most tool window that owns its input without
+grabbing a taskbar button of its own. This library does that, and nothing else.
+
+> **Windows 10/11 only.** It is built on Win32 APIs, and there is no macOS or Linux
+> build. The package imports anywhere, but calling into it off Windows raises
+> `NotWindowsError`.
+
+## Install
+
+```
+pip install taskbargap
+```
+
+The only dependency is the standard library (`ctypes`). It writes nothing at all:
+no files, no registry keys, no config, no logs. It makes no network calls. See
+[SECURITY.md](SECURITY.md) for the complete list of Win32 calls it makes.
+
+This is an alpha, and it says so on the tin. Before you rely on it, read [what
+has and hasn't been validated](DESIGN.md), which is specific about the
+configurations it has never run on.
+
+## Quickstart
+
+```python
+import taskbargap
+
+taskbargap.enable_dpi_awareness()          # call once, before creating windows
+
+gap = taskbargap.find_gap()                # -> Gap | None
+if gap:
+    print(gap.left, gap.right, gap.width, gap.scale)
+
+# Place a window (by HWND) into the gap, right-aligned near the tray:
+taskbargap.place(my_hwnd, align="right", margin=12)
+```
+
+To keep it fitted as the taskbar changes, when apps open and close, when Explorer
+restarts, when the resolution changes:
+
+```python
+watcher = taskbargap.GapWatcher(my_hwnd, align="right")
+watcher.start()          # places it now, then re-fits on change and re-asserts top-most
+# ...
+watcher.stop()
+```
+
+`start()` places the window immediately, on your thread, and returns. The polling
+happens on a daemon thread afterwards. Pass `on_change=fn` if you want to be told
+when the gap moves, including when it gets too narrow to fit, which is usually
+when an app wants to get out of the way.
+
+## API
+
+| Object | Purpose |
+|--------|---------|
+| `find_gap() -> Gap \| None` | Detect the empty taskbar gap on the primary monitor. `None` if there isn't a usable one. |
+| `place(hwnd, *, align="right", margin=12, min_width=160, width=None, height=None, gap=None, nonblocking=False) -> bool` | Size and position an existing window inside the gap as a top-most tool window. `width` defaults to filling the gap, `height` to the taskbar's own height. False means it did nothing: no gap, `min_width` didn't fit, or Windows refused the move. |
+| `GapWatcher(hwnd, *, align, margin, min_width, width, height, interval=1.0, on_change=None)` | Background watcher that keeps the window fitted and top-most as the taskbar changes. `.start()` / `.stop() -> bool`, or use it as a context manager. |
+| `enable_dpi_awareness() -> bool` | Opt into per-monitor-v2 DPI awareness. Falls back gracefully on old Windows. |
+| `Gap` | Frozen dataclass: `left, right, top, bottom` (physical px), `scale` (DPI factor), `monitor` (HMONITOR), `measured`, plus `width` / `height`. |
+| `NotWindowsError` | Raised by any Win32 call when you're not on Windows. |
+
+### Units, and the DPI contract
+
+Every coordinate you get back is a **physical pixel** in the coordinate space your
+process actually sees. `Gap.scale` is the divisor for toolkits that scale window
+position by DPI, such as pywebview and WinForms:
+
+```python
+x_logical = round(gap.left / gap.scale)
+```
+
+Call `enable_dpi_awareness()` before you create any window. Without it Windows
+virtualises coordinates (a 3840px screen at 175% looks 2194px wide) and a window
+aimed at the gap lands somewhere else.
+
+Whatever you do, `scale` describes the space your process addresses windows in,
+rather than the monitor's spec sheet. That means `1.0` for a DPI-unaware process,
+the system DPI for a system-aware one, and the taskbar monitor's own factor only
+for a per-monitor-aware one. The distinction is not academic: `GetDpiForWindow`
+will happily report the taskbar's real 175% to an unaware caller that sees a
+2194px desktop, and dividing by that number puts the window a third of the screen
+away from where it belongs. The library stays self-consistent in every mode. It is
+only in per-monitor mode that you get real screen pixels and an unscaled window.
+
+## What it deliberately does not do
+
+- No metrics, rendering, or UI. You bring the window, it does the placement.
+- No decision about *whether* to be visible. Fullscreen-hide and yielding to a
+  crowded taskbar are app policy, and `find_gap()` gives you the facts to decide.
+- No cross-platform panels. Windows taskbar only.
+
+## Honest limitations
+
+- **When the button strip can't be measured.** The app-button edge is read from the
+  taskbar's own `ReBarWindow32` and `MSTaskListWClass` windows. On stock Windows 11
+  (build 26200) those exist and track the buttons in both left-aligned and centred
+  layouts, measured here both ways, so the common cases are the measured ones.
+  Where a shell doesn't host them, `find_gap()` falls back to assuming the buttons
+  end 30% across the bar, and sets `measured=False`. Be clear-eyed about that
+  fallback. It is a guess inherited from the app this code was extracted from, it
+  has never run on a real machine, and it can name a left edge that still has
+  buttons on it. Check `Gap.measured` if covering a button would matter to you.
+- **Rects are sanity-checked, so detection degrades rather than lies.** A taskbar
+  child reporting a dead or off-bar rectangle, which happens while Explorer is
+  restarting, is ignored rather than believed, and you get the heuristic with
+  `measured=False`. A plausible edge that leaves no room is respected: a genuinely
+  full taskbar returns `None`, because inventing a gap there would cover buttons.
+- **Primary taskbar only.** Secondary monitors get their own
+  `Shell_SecondaryTrayWnd` bars, and v0.1 reads the primary `Shell_TrayWnd`. The
+  gap you get is on whichever monitor that taskbar is on, at that monitor's DPI.
+- **Horizontal taskbars only.** A taskbar docked left or right, which Windows 10
+  allows, has no horizontal gap worth speaking of, so `find_gap()` returns `None`
+  rather than guess.
+- **The watcher needs your app to pump messages.** It posts its moves rather than
+  sending them, so a busy UI thread can never block it. The flip side is that a
+  re-fit only lands the next time your app processes messages. Normal GUI apps do
+  that constantly, but a wedged one won't move.
+- **Auto-hide taskbars** are not special-cased. You get the gap of the bar wherever
+  it currently is, mid-slide included.
+
+## License
+
+MIT.

taskbargap-0.1.0/README.md

@@ -0,0 +1,141 @@
+# taskbargap
+
+[![Platform: Windows 10/11](https://img.shields.io/badge/platform-Windows%2010%20%7C%2011-0078d6)](#honest-limitations)
+[![PyPI](https://img.shields.io/pypi/v/taskbargap)](https://pypi.org/project/taskbargap/)
+[![CI](https://github.com/paone9/taskbargap/actions/workflows/ci.yml/badge.svg)](https://github.com/paone9/taskbargap/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/paone9/taskbargap/actions/workflows/codeql.yml/badge.svg)](https://github.com/paone9/taskbargap/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/paone9/taskbargap/badge)](https://scorecard.dev/viewer/?uri=github.com/paone9/taskbargap)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Find the empty stretch of the Windows taskbar, the gap between your app buttons
+and the system tray, and put a top-most window in it. Correctly, across multiple
+monitors and per-monitor DPI scaling.
+
+Windows leaves that strip unused, so a small always-on widget there costs you no
+screen space. Doing it properly turns out to be fiddly. You have to detect the gap
+across two generations of taskbar internals, handle per-monitor DPI and the
+difference between physical and logical pixels, keep the window fitted as apps
+open and close, and end up with a top-most tool window that owns its input without
+grabbing a taskbar button of its own. This library does that, and nothing else.
+
+> **Windows 10/11 only.** It is built on Win32 APIs, and there is no macOS or Linux
+> build. The package imports anywhere, but calling into it off Windows raises
+> `NotWindowsError`.
+
+## Install
+
+```
+pip install taskbargap
+```
+
+The only dependency is the standard library (`ctypes`). It writes nothing at all:
+no files, no registry keys, no config, no logs. It makes no network calls. See
+[SECURITY.md](SECURITY.md) for the complete list of Win32 calls it makes.
+
+This is an alpha, and it says so on the tin. Before you rely on it, read [what
+has and hasn't been validated](DESIGN.md), which is specific about the
+configurations it has never run on.
+
+## Quickstart
+
+```python
+import taskbargap
+
+taskbargap.enable_dpi_awareness()          # call once, before creating windows
+
+gap = taskbargap.find_gap()                # -> Gap | None
+if gap:
+    print(gap.left, gap.right, gap.width, gap.scale)
+
+# Place a window (by HWND) into the gap, right-aligned near the tray:
+taskbargap.place(my_hwnd, align="right", margin=12)
+```
+
+To keep it fitted as the taskbar changes, when apps open and close, when Explorer
+restarts, when the resolution changes:
+
+```python
+watcher = taskbargap.GapWatcher(my_hwnd, align="right")
+watcher.start()          # places it now, then re-fits on change and re-asserts top-most
+# ...
+watcher.stop()
+```
+
+`start()` places the window immediately, on your thread, and returns. The polling
+happens on a daemon thread afterwards. Pass `on_change=fn` if you want to be told
+when the gap moves, including when it gets too narrow to fit, which is usually
+when an app wants to get out of the way.
+
+## API
+
+| Object | Purpose |
+|--------|---------|
+| `find_gap() -> Gap \| None` | Detect the empty taskbar gap on the primary monitor. `None` if there isn't a usable one. |
+| `place(hwnd, *, align="right", margin=12, min_width=160, width=None, height=None, gap=None, nonblocking=False) -> bool` | Size and position an existing window inside the gap as a top-most tool window. `width` defaults to filling the gap, `height` to the taskbar's own height. False means it did nothing: no gap, `min_width` didn't fit, or Windows refused the move. |
+| `GapWatcher(hwnd, *, align, margin, min_width, width, height, interval=1.0, on_change=None)` | Background watcher that keeps the window fitted and top-most as the taskbar changes. `.start()` / `.stop() -> bool`, or use it as a context manager. |
+| `enable_dpi_awareness() -> bool` | Opt into per-monitor-v2 DPI awareness. Falls back gracefully on old Windows. |
+| `Gap` | Frozen dataclass: `left, right, top, bottom` (physical px), `scale` (DPI factor), `monitor` (HMONITOR), `measured`, plus `width` / `height`. |
+| `NotWindowsError` | Raised by any Win32 call when you're not on Windows. |
+
+### Units, and the DPI contract
+
+Every coordinate you get back is a **physical pixel** in the coordinate space your
+process actually sees. `Gap.scale` is the divisor for toolkits that scale window
+position by DPI, such as pywebview and WinForms:
+
+```python
+x_logical = round(gap.left / gap.scale)
+```
+
+Call `enable_dpi_awareness()` before you create any window. Without it Windows
+virtualises coordinates (a 3840px screen at 175% looks 2194px wide) and a window
+aimed at the gap lands somewhere else.
+
+Whatever you do, `scale` describes the space your process addresses windows in,
+rather than the monitor's spec sheet. That means `1.0` for a DPI-unaware process,
+the system DPI for a system-aware one, and the taskbar monitor's own factor only
+for a per-monitor-aware one. The distinction is not academic: `GetDpiForWindow`
+will happily report the taskbar's real 175% to an unaware caller that sees a
+2194px desktop, and dividing by that number puts the window a third of the screen
+away from where it belongs. The library stays self-consistent in every mode. It is
+only in per-monitor mode that you get real screen pixels and an unscaled window.
+
+## What it deliberately does not do
+
+- No metrics, rendering, or UI. You bring the window, it does the placement.
+- No decision about *whether* to be visible. Fullscreen-hide and yielding to a
+  crowded taskbar are app policy, and `find_gap()` gives you the facts to decide.
+- No cross-platform panels. Windows taskbar only.
+
+## Honest limitations
+
+- **When the button strip can't be measured.** The app-button edge is read from the
+  taskbar's own `ReBarWindow32` and `MSTaskListWClass` windows. On stock Windows 11
+  (build 26200) those exist and track the buttons in both left-aligned and centred
+  layouts, measured here both ways, so the common cases are the measured ones.
+  Where a shell doesn't host them, `find_gap()` falls back to assuming the buttons
+  end 30% across the bar, and sets `measured=False`. Be clear-eyed about that
+  fallback. It is a guess inherited from the app this code was extracted from, it
+  has never run on a real machine, and it can name a left edge that still has
+  buttons on it. Check `Gap.measured` if covering a button would matter to you.
+- **Rects are sanity-checked, so detection degrades rather than lies.** A taskbar
+  child reporting a dead or off-bar rectangle, which happens while Explorer is
+  restarting, is ignored rather than believed, and you get the heuristic with
+  `measured=False`. A plausible edge that leaves no room is respected: a genuinely
+  full taskbar returns `None`, because inventing a gap there would cover buttons.
+- **Primary taskbar only.** Secondary monitors get their own
+  `Shell_SecondaryTrayWnd` bars, and v0.1 reads the primary `Shell_TrayWnd`. The
+  gap you get is on whichever monitor that taskbar is on, at that monitor's DPI.
+- **Horizontal taskbars only.** A taskbar docked left or right, which Windows 10
+  allows, has no horizontal gap worth speaking of, so `find_gap()` returns `None`
+  rather than guess.
+- **The watcher needs your app to pump messages.** It posts its moves rather than
+  sending them, so a busy UI thread can never block it. The flip side is that a
+  re-fit only lands the next time your app processes messages. Normal GUI apps do
+  that constantly, but a wedged one won't move.
+- **Auto-hide taskbars** are not special-cased. You get the gap of the bar wherever
+  it currently is, mid-slide included.
+
+## License
+
+MIT.

taskbargap-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "taskbargap"
+version = "0.1.0"
+description = "Find the empty gap in the Windows taskbar and place a top-most window in it, across monitors and DPI."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "paone9" }]
+keywords = ["windows", "taskbar", "win32", "topmost", "dpi", "widget", "taskbar-gap", "shell"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Win32 (MS Windows)",
+    "Intended Audience :: Developers",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Desktop Environment",
+]
+dependencies = []
+
+# Dev + CI tools, pinned to the tested versions. One dependency source for the
+# whole project: `pip install .[dev]`, no separate requirements files.
+[project.optional-dependencies]
+dev = [
+    "ruff==0.16.1",
+    "bandit==1.9.4",
+    "pytest==9.1.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/paone9/taskbargap"
+Issues = "https://github.com/paone9/taskbargap/issues"
+Changelog = "https://github.com/paone9/taskbargap/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# PEP 561: the package is fully annotated, so say so - without the marker every
+# consumer's type checker treats the whole API as untyped.
+[tool.setuptools.package-data]
+taskbargap = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

taskbargap-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

taskbargap-0.1.0/src/taskbargap/__init__.py

@@ -0,0 +1,26 @@
+"""taskbargap - place a top-most window in the empty Windows taskbar gap.
+
+Windows 10/11 only. See README.md for usage and DESIGN.md for how it works.
+Every coordinate a caller sees is in physical pixels; `Gap.scale` is the taskbar
+monitor's DPI factor, for toolkits that want logical ones.
+
+    import taskbargap
+
+    taskbargap.enable_dpi_awareness()      # once, before creating windows
+    gap = taskbargap.find_gap()            # -> Gap | None
+    taskbargap.place(my_hwnd, align="right")
+"""
+from ._detect import Gap, find_gap
+from ._place import place
+from ._win32 import NotWindowsError, enable_dpi_awareness
+from .watcher import GapWatcher
+
+__version__ = "0.1.0"
+__all__ = [
+    "Gap",
+    "GapWatcher",
+    "NotWindowsError",
+    "enable_dpi_awareness",
+    "find_gap",
+    "place",
+]

taskbargap-0.1.0/src/taskbargap/_detect.py

@@ -0,0 +1,111 @@
+"""Find the empty span of the taskbar: `Shell_TrayWnd` -> tray edge, button edge."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from . import _win32
+from ._geometry import BUTTON_FRACTION, gap_span, is_on_taskbar
+
+#: The taskbar itself. (Secondary monitors get `Shell_SecondaryTrayWnd`; v0.1
+#: reads the primary taskbar only. See DESIGN.md.)
+TRAY_CLASS = "Shell_TrayWnd"
+#: The notification/clock cluster on the right: the gap's right bound.
+NOTIFY_CLASS = "TrayNotifyWnd"
+#: The app-button strip: the gap's left bound. `ReBarWindow32` hosts it on both
+#: Win10 and stock Win11; `MSTaskListWClass` is the button list itself, checked
+#: as a fallback because some shells (and secondary taskbars, which use
+#: `WorkerW`) host it elsewhere.
+BUTTON_CLASSES = ("ReBarWindow32", "MSTaskListWClass")
+
+
+@dataclass(frozen=True)
+class Gap:
+    """The empty span of the taskbar, in physical pixels.
+
+    `scale` is the DPI factor of the taskbar's monitor, exposed because toolkits
+    that scale window *position* by DPI (pywebview, WinForms) need the logical
+    value: `x_logical = round(gap.left / gap.scale)`.
+
+    `measured` is True when the app-button edge was read from a real window, and
+    False when it came from the fallback heuristic. Check it before trusting the
+    left edge not to sit on top of the buttons.
+    """
+    left: int
+    right: int
+    top: int
+    bottom: int
+    scale: float          # DPI factor of the taskbar's monitor
+    monitor: int          # HMONITOR
+    measured: bool        # True if the button edge came from a real window
+
+    @property
+    def width(self) -> int:
+        return self.right - self.left
+
+    @property
+    def height(self) -> int:
+        return self.bottom - self.top
+
+
+def _button_edge(tray: int, tray_rect: tuple[int, int, int, int]) -> int | None:
+    """Right edge of the app-button strip, or None if nothing measurable exists.
+
+    Every candidate is sanity-checked against the taskbar's own rect rather than
+    trusted on sight: the shell keeps stale and hidden button windows around
+    (this machine has an invisible `MSTaskListWClass`), and during an Explorer
+    restart a live handle can still report a zero rect. Candidates that don't
+    check out are skipped, so a good window later in the list still wins.
+
+    None means "no shell window would tell us", which sends the caller to the
+    heuristic. Stock Windows 11 (26200) does host these windows and moves them
+    with the buttons in both left and centred layouts, so on it the answer is
+    measured either way.
+    """
+    for cls in BUTTON_CLASSES:
+        hwnd = _win32.find_child(tray, cls) or _win32.find_descendant(tray, cls)
+        if not hwnd:
+            continue
+        rect = _win32.window_rect(hwnd)
+        if is_on_taskbar(rect, tray_rect):
+            return rect[2]
+    return None
+
+
+def find_gap(fraction: float = BUTTON_FRACTION) -> Gap | None:
+    """Detect the empty taskbar gap. Returns a `Gap`, or `None` if there isn't one.
+
+    `None` covers every "no gap right now" state: no taskbar (Explorer
+    restarting), no measurable span, an auto-hidden bar mid-slide. Callers
+    can treat it as normal rather than exceptional. It does not swallow bugs:
+    on a non-Windows platform this raises `NotWindowsError`.
+
+    `fraction` overrides the fallback button-edge heuristic used when the button
+    strip can't be measured (native Windows 11).
+    """
+    tray = _win32.find_window(TRAY_CLASS)
+    if not tray:
+        return None
+    rect = _win32.window_rect(tray)
+    if not rect:
+        return None
+    tray_l, tray_t, tray_r, tray_b = rect
+    if tray_r <= tray_l or tray_b <= tray_t:
+        return None      # Explorer restarting: a live handle with a dead rect
+    if (tray_b - tray_t) > (tray_r - tray_l):
+        return None      # docked left/right (Win10): there is no horizontal gap
+
+    notify_rect = _win32.window_rect(_win32.find_child(tray, NOTIFY_CLASS))
+    # The tray cluster's *left* edge is the gap's right bound - and it gets the
+    # same sanity check, so a dead tray rect can't push the gap over the clock.
+    notify_left = notify_rect[0] if is_on_taskbar(notify_rect, rect) else None
+
+    span = gap_span(tray_l, tray_r, notify_left, _button_edge(tray, rect), fraction)
+    if span is None:
+        return None
+    left, right, measured = span
+    return Gap(
+        left=left, right=right, top=tray_t, bottom=tray_b,
+        scale=_win32.window_scale(tray),
+        monitor=_win32.monitor_from_window(tray),
+        measured=measured,
+    )

taskbargap-0.1.0/src/taskbargap/_geometry.py

@@ -0,0 +1,126 @@
+"""Pure placement geometry: plain ints in, plain ints out, no Windows.
+
+Deliberately free of ctypes so the arithmetic that decides *where the window
+goes* can be unit-tested on any OS. The Win32 half (`_detect`, `_place`) reads
+rects from the shell and hands them to these functions.
+
+All coordinates are physical pixels.
+"""
+from __future__ import annotations
+
+#: Fallback for the app-button edge when a shell hosts no measurable button
+#: window: assume the buttons end 30% of the way across the taskbar. Inherited
+#: from the app this code came from, where it shipped. Stock Windows 11 (26200)
+#: does host those windows, in both left and centred layouts, so this is a
+#: rarely-taken and unvalidated path. `Gap.measured` is False whenever it is used.
+BUTTON_FRACTION = 0.30
+
+ALIGNMENTS = ("left", "center", "right")
+
+
+def is_on_taskbar(
+    rect: tuple[int, int, int, int] | None,
+    tray_rect: tuple[int, int, int, int],
+) -> bool:
+    """Is `rect` a live window rect that actually sits on this taskbar?
+
+    A window handle existing is not evidence that its rect means anything. The
+    shell keeps taskbar children around that are hidden or mid-teardown, and during
+    an Explorer restart `GetWindowRect` happily returns `(0, 0, 0, 0)`. A
+    zero rect read as a button edge puts the gap's left bound at the far left of
+    the screen, i.e. straight over the Start button and every app button.
+
+    So a candidate must be a non-empty rect that overlaps the taskbar's own.
+    Failing this means "couldn't measure", which sends `find_gap()` to its
+    heuristic, which is the honest answer. It deliberately does not reject a plausible
+    edge that leaves no room: a genuinely full taskbar has no gap, and inventing
+    one there would cover real buttons.
+    """
+    if rect is None:
+        return False
+    left, top, right, bottom = rect
+    if right <= left or bottom <= top:
+        return False                                 # degenerate: not a live window
+    tray_left, tray_top, tray_right, tray_bottom = tray_rect
+    if right <= tray_left or left >= tray_right:
+        return False                                 # not horizontally on this bar
+    return not (bottom <= tray_top or top >= tray_bottom)
+
+
+def gap_span(
+    tray_left: int,
+    tray_right: int,
+    notify_left: int | None = None,
+    button_right: int | None = None,
+    fraction: float = BUTTON_FRACTION,
+) -> tuple[int, int, bool] | None:
+    """Compute the empty horizontal span of the taskbar.
+
+    `tray_left`/`tray_right` bound the whole taskbar. `notify_left` is the left
+    edge of the notification/clock cluster (the gap's right bound); `None` means
+    it wasn't found, so the taskbar's own right edge is used. `button_right` is
+    the right edge of the app-button strip (the gap's left bound); `None` means
+    it couldn't be measured, so `fraction` of the taskbar width is assumed.
+
+    Returns `(left, right, measured)` where `measured` is True only when the
+    button edge came from a real window, or `None` when there is no usable span.
+    """
+    if tray_right <= tray_left:
+        return None
+    if button_right is None:
+        left = tray_left + int((tray_right - tray_left) * fraction)
+        measured = False
+    else:
+        left = button_right
+        measured = True
+    right = tray_right if notify_left is None else notify_left
+    # Clamp into the taskbar: a stale or bogus child rect must not produce a
+    # span that reaches off the bar.
+    left = min(max(left, tray_left), tray_right)
+    right = min(max(right, tray_left), tray_right)
+    if right - left <= 0:
+        return None
+    return left, right, measured
+
+
+def fit(
+    gap_left: int,
+    gap_right: int,
+    *,
+    align: str = "right",
+    margin: int = 12,
+    min_width: int = 160,
+    width: int | None = None,
+) -> tuple[int, int] | None:
+    """Compute `(x, width)` for a window inside the span `[gap_left, gap_right)`.
+
+    A `margin` of clear space is kept at each end. `width` is the desired width;
+    `None` means "fill the gap". The result never widens past the gap, so it can
+    never overlap the app buttons or the tray.
+
+    Returns `None` when `min_width` doesn't fit, leaving the caller to decide
+    what that means (hide, shrink, do nothing), because that is policy rather
+    than placement.
+    """
+    if align not in ALIGNMENTS:
+        raise ValueError(f"align must be one of {ALIGNMENTS!r}, got {align!r}")
+    if margin < 0:
+        raise ValueError(f"margin must be >= 0, got {margin!r}")
+    if min_width < 0:
+        raise ValueError(f"min_width must be >= 0, got {min_width!r}")
+    if width is not None and width <= 0:
+        raise ValueError(f"width must be > 0 or None, got {width!r}")
+
+    span = gap_right - gap_left
+    avail = span - 2 * margin
+    if avail < min_width or avail <= 0:
+        return None
+    w = avail if width is None else min(width, avail)
+    w = max(w, min_width)      # avail >= min_width here, so w <= avail always
+    if align == "left":
+        x = gap_left + margin
+    elif align == "center":
+        x = gap_left + (span - w) // 2
+    else:
+        x = gap_right - margin - w
+    return x, w