Metadata-Version: 2.4
Name: alphawindow
Version: 0.1.2
Summary: Windows-first window automation abstractions with pluggable input and output modes.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pluggy>=1.5
Provides-Extra: image
Requires-Dist: numpy>=1.24; extra == "image"
Requires-Dist: Pillow>=10; extra == "image"
Provides-Extra: native
Requires-Dist: pywin32>=306; platform_system == "Windows" and extra == "native"
Requires-Dist: pynput>=1.7.6; platform_system == "Windows" and extra == "native"
Requires-Dist: winrt-Windows.Foundation>=3.2.1; platform_system == "Windows" and extra == "native"
Requires-Dist: winrt-Windows.Graphics>=3.2.1; platform_system == "Windows" and extra == "native"
Requires-Dist: winrt-Windows.Graphics.Capture>=3.2.1; platform_system == "Windows" and extra == "native"
Requires-Dist: winrt-Windows.Graphics.Capture.Interop>=3.2.1; platform_system == "Windows" and extra == "native"
Requires-Dist: winrt-Windows.Graphics.DirectX>=3.2.1; platform_system == "Windows" and extra == "native"
Requires-Dist: winrt-Windows.Graphics.DirectX.Direct3D11>=3.2.1; platform_system == "Windows" and extra == "native"
Requires-Dist: winrt-Windows.Graphics.DirectX.Direct3D11.Interop>=3.2.1; platform_system == "Windows" and extra == "native"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: numpy>=1.24; extra == "test"
Requires-Dist: Pillow>=10; extra == "test"

# AlphaWindow

[简体中文](README.zh-CN.md)

AlphaWindow is a Windows-first automation abstraction layer. It exposes one session API for window operations while allowing callers to choose different input and output modes.

AlphaWindow is meant to model target-window automation, not global "computer use" control. The same high-level operations can be backed by no-op inspection, window messages, UI Automation, foreground input, guarded foreground input, or optional hook-assisted virtual input.

## Scope

AlphaWindow separates four concerns:

- Window discovery and state: `WindowResolver`, `WindowSelector`, and `WindowSnapshot`.
- Output: state inspection, direct window capture, explicit monitor capture, desktop-region capture, hook telemetry, or no output.
- Input: dry-run, window messages, UIA, global foreground input, guarded foreground input, isolated hook input, or virtualized hook input.
- Safety contracts: profile compatibility, explicit fallback modes, hook requirements, prefetch TTL, and fake backends for deterministic tests.

The project currently focuses on the abstraction and compatibility layer. Native pynput, UIA, and hook implementations are intentionally kept behind protocols so callers can plug in their own adapters without changing automation code. The exceptions are an experimental PyWinRT-backed Windows Graphics Capture path and classic Win32/GDI window capture paths. WGC can capture a native Direct3D surface, read it back to CPU memory, or keep a persistent frame cache for low-latency repeated screenshots. Win32/GDI capture can use `PrintWindow` or `BitBlt` against a target `HWND`.

## Supported Today

- Built-in I/O profiles for every declared input and output mode, including `inspect`, `observe`, `desktop_observe`, `monitor_observe`, `dry_run`, `win32_message`, `message_only`, `uia_control`, `uia_visual`, `global_input`, `foreground_visual`, `guarded_input`, `guarded_desktop`, `isolated_observe`, `isolated_telemetry`, `virtual_window`, `virtual_telemetry`, and `virtual_input_only`.
- A `WindowSession` API for `prefetch`, `capture`, `observe`, `click`, `key_down`, `key_up`, and `type_text`.
- Generic delegation backends for message, UIA, foreground, guarded foreground, state, desktop-region, hook-telemetry, and no-output modes.
- Compatibility checks so a backend cannot silently fall back to a broader side-effect mode.
- Hook-aware `isolated` and `virtualized` input backends that accept pluggable hook managers and virtual input transports.
- Pluggy-based plugin registry for installed packages to register additional capture and mouse/keyboard input methods without adding hardware SDKs to core.
- Deterministic prefetch behavior: snapshots are reused within `prefetch_ttl_seconds`, rejected when stale, and revalidated through a resolver `is_valid` hook when provided.
- DPI-aware snapshots and capture requests: `WindowSnapshot.dpi` is carried into operation normalization and DirectX capture requests.
- Relative point normalization: `session.click(0.5, 0.5)` resolves against the current target window rectangle.
- HDR-aware DirectX/Windows Graphics Capture model: `DirectXCaptureOutputBackend` builds capture requests for an injected `DirectXCapturePipeline`, selects FP16/scRGB for HDR targets, selects BGRA8/sRGB for SDR, and preserves frame DPI and SDR white-level metadata.
- CPU frame conversion: `CpuFrame` supports FP16/scRGB to SDR BGRA8 tone mapping, pure-Python PNG export, and optional Pillow / numpy output formats selected by `CaptureOutputFormat`.
- Experimental native WGC pipeline: `WinrtWgcCapturePipeline` uses PyWinRT, creates a Direct3D11 device, creates a window or monitor `GraphicsCaptureItem`, starts a free-threaded WGC frame pool, returns a `CaptureFrame` containing the native `IDirect3DSurface`, and can read it back with `capture_cpu()`.
- Explicit monitor capture requests: `MonitorSnapshot`, `CaptureTargetKind.MONITOR`, and `DirectXCaptureConfig.create_monitor_request()` model WGC display capture through `create_for_monitor`, including HDR/scRGB and DPI metadata for the selected monitor.
- Persistent native WGC frame cache: `WinrtWgcFrameCache` keeps the WGC session and D3D11 device alive, tracks the newest frame, can wait for a bounded fresh frame, and can run a `before_readback` hook while holding that frame so external labels can be sampled against the same image moment.
- Classic native Win32 window capture: `Win32WindowCaptureBackend` supports explicit `win32_print_window` and `win32_bitblt_window` methods, returning `CpuFrame` without falling back to global screenshots.
- A Windows-only `alphawindow` desktop test tool that starts from the current working directory, lets a user click-to-attach a target window handle, previews WGC captures, switches between cached, single-shot, and attached-window monitor capture, selects 1 Hz, 30 Hz, or 120 Hz refresh, and reports the last capture time plus the average of the latest 30 captures.
- PyPI packaging for `pip install alphawindow` and typed package data via `py.typed`.
- Tests that cover profile coverage, compatibility failures, prefetch reuse/refresh behavior, hook backend contracts, DirectX/HDR capture contracts, native WGC dependency behavior, generic backends, CLI preview controller behavior, packaging import behavior, and the publish workflow.

## Screenshot Support Matrix

AlphaWindow treats screenshot mode as an explicit choice. It does not silently fall back from one capture path to another.

### Window Targets

| Mode | Target | Entry points | Current status | Best fit | Limits |
| --- | --- | --- | --- | --- | --- |
| WGC cached window capture | `HWND` / `WindowSnapshot` | `wgc_window_cached`, `WinrtWgcFrameCache.start_for(window, request)` | Supported as experimental native PyWinRT capture | Repeated screenshots of a normal window, borderless window, or compositor-visible app | Depends on Windows Graphics Capture allowing that window; fails closed on WGC/readback/tone-map errors. |
| WGC single-shot window capture | `HWND` / `WindowSnapshot` | `wgc_window_single`, `WinrtWgcCapturePipeline.capture_cpu(window, request)` | Supported as experimental native PyWinRT capture | One-off validation screenshots or simple tooling | Recreates the WGC session per capture, so it is not the preferred high-frequency path. |
| DirectX capture model | `WindowSnapshot` | `DirectXCaptureConfig.create_request()`, `DirectXCaptureOutputBackend` with an injected pipeline | Supported as an abstraction and contract | External adapters that want AlphaWindow's HDR/DPI/request normalization | The injected pipeline must provide the real capture implementation. |
| Desktop-region output mode | Window rectangle in desktop coordinates | `desktop_observe`, `OutputMode.DESKTOP_REGION` | Mode and compatibility contract are supported | Foreground/compositor-visible targets when an external adapter supplies desktop-region capture | Core package does not yet ship a native desktop-region screenshot adapter. |
| Win32 PrintWindow capture | `HWND` / `WindowSnapshot` | `win32_print_window`, `Win32WindowCaptureBackend(method="win32_print_window")` | Supported through pywin32/GDI | Legacy Win32 apps, dialogs, or apps where WGC is not desired | Uses `PrintWindow(hwnd, hdc, 2)`; many GPU/game surfaces may return black, stale, or incomplete pixels. |
| Win32 BitBlt window capture | `HWND` / `WindowSnapshot` | `win32_bitblt_window`, `Win32WindowCaptureBackend(method="win32_bitblt_window")` | Supported through pywin32/GDI | Visible windows and direct window DC copying | Uses `GetWindowDC` + `BitBlt(..., SRCCOPY)`; occlusion/compositor/GPU behavior can limit results. |

### Fullscreen And Exclusive Targets

| Scenario | Recommended mode | Current status | What it can capture | What it cannot guarantee |
| --- | --- | --- | --- | --- |
| Borderless fullscreen / fullscreen windowed game visible in the compositor | `wgc_monitor_cached` / `WinrtWgcFrameCache.start_for(monitor, request)` | Supported as experimental native monitor WGC capture | The whole monitor containing the attached window, including compositor-visible fullscreen output | It captures unrelated pixels on that monitor and is not target-window isolated. |
| Fullscreen app where window-target WGC is the wrong abstraction | `wgc_monitor_cached` | Supported as explicit monitor capture, not fallback | Display output if Windows Graphics Capture exposes the monitor frame | Protected, blocked, or non-composited content can still fail or return unusable frames. |
| True exclusive fullscreen swap chain | None | Not supported as a guaranteed mode | No guaranteed capture path in AlphaWindow today | AlphaWindow does not bypass exclusive fullscreen restrictions, driver behavior, anti-cheat policy, or protected content. |
| Secure desktop, protected video, anti-cheat blocked content, or protected process | None | Not supported | Nothing guaranteed | No kernel driver, privilege escalation, protected-process bypass, or anti-cheat bypass is provided. |

## Input Support Matrix

AlphaWindow uses the same high-level operations for mouse and keyboard input: `click`, `key_down`, `key_up`, and `type_text`. The selected input backend decides whether those operations become window messages, UI Automation actions, global foreground input, or hook-assisted virtual input.

### Mouse And Keyboard Modes

| Mode | Entry points / profiles | Mouse behavior | Keyboard behavior | Main device impact | Current status and limits |
| --- | --- | --- | --- | --- | --- |
| Dry run | `dry_run`, `inspect`, `observe`, `desktop_observe`, `monitor_observe` | Records the requested mouse operation without executing it. | Records the requested keyboard operation without executing it. | None. | Built in through `DryRunInputBackend`; useful for tests and planning. |
| Window message input | `win32_message`, `message_only`, `InputMode.MESSAGE` | External backend can translate clicks/moves to `PostMessage`/`SendMessage` style mouse messages for a target `HWND`. | External backend can translate key events/text to window messages. | Does not need to move the primary cursor when the target accepts messages. | Protocol and compatibility slot are built in; native `PostMessage`/`SendMessage` adapter is not shipped yet, and many games/custom renderers ignore these messages. |
| UI Automation input | `uia_control`, `uia_visual`, `InputMode.UIA` | External UIA adapter can invoke standard controls or patterns instead of physical mouse movement. | External UIA adapter can set text or invoke standard control patterns. | Usually avoids primary mouse/keyboard takeover. | Protocol slot is built in; native UIA adapter is not shipped yet and this is not a general game input path. |
| Foreground global input | `global_input`, `foreground_visual`, `InputMode.FOREGROUND` | External backend can use `pynput`, `SendInput`, or another global input library against the foreground target. | External backend can emit global key events/text through `pynput`, `SendInput`, or equivalent. | Affects the active desktop and primary mouse/keyboard stream. | Compatibility slot is built in; native foreground input adapter is planned, not shipped. Requires focus/foreground correctness. |
| Guarded foreground input | `guarded_input`, `guarded_desktop`, `InputMode.GUARDED_FOREGROUND` | Same class of global mouse input as foreground mode, with an adapter responsible for focus/cursor save and restore. | Same class of global keyboard input as foreground mode, with cleanup around focus/key state. | Still affects the primary input stream while the operation is running. | Compatibility slot is built in; guard implementation is adapter-provided. It reduces cleanup risk but is not input isolation. |
| Isolated hook input | `isolated_observe`, `isolated_telemetry`, `InputMode.ISOLATED`, `IsolatedInputBackend` | Hook manager can windowize or suppress real mouse input for the target before optionally delegating to another backend. | Hook manager can windowize or suppress target-local keyboard input before optional delegation. | Intended to reduce or prevent target impact from the user's primary devices, depending on hook implementation. | Hook-aware backend contract is built in; production hook manager/DLL injection is not shipped. Fails closed without hook capability. |
| Virtualized hook input | `virtual_window`, `virtual_telemetry`, `virtual_input_only`, `InputMode.VIRTUALIZED`, `VirtualizedInputBackend` | Sends target-local virtual mouse operations through a `VirtualInputTransport` after hook injection. | Sends target-local virtual keyboard operations through a `VirtualInputTransport` after hook injection. | Designed for multi-window automation without taking over the primary mouse/keyboard, if the hook and transport support it. | Backend contract is built in; requires both hook manager and transport. Ready-made IPC transport is not shipped yet. |
| Custom delegated input | `DelegatingInputBackend` with `message`, `uia`, `foreground`, or `guarded_foreground` mode | Caller supplies the concrete mouse implementation. | Caller supplies the concrete keyboard implementation. | Depends on the chosen custom backend. | Supported extension point for pywin32, pynput, SendInput, UIA, app-specific IPC, or test doubles. Hook modes must use the dedicated hook-aware backends. |

### Hook Modes

| Hook path | Required pieces | What it is for | What it is not |
| --- | --- | --- | --- |
| Isolation hook | `HookManager` plus optional delegated input backend | Blocking, rewriting, or observing target-local mouse/keyboard input so real user input can be isolated from the target. | It is not a complete implementation by itself; the package only defines the contract. |
| Virtual input hook | `HookManager` plus `VirtualInputTransport` | Sending per-window or per-process virtual mouse/keyboard operations without relying on the primary cursor or global keyboard stream. | It is not a kernel driver, anti-cheat bypass, or universal game-input solution. |
| Hook telemetry | Hook-capable input profile plus `OutputMode.HOOK_TELEMETRY` | Reading hook-side labels, events, or state that can be paired with capture frames. | It is not OCR/image matching and does not replace screenshot capture. |

### Input Language Utilities

The package also exposes small Windows utilities for keyboard layout and CapsLock state:

| Utility | Purpose | Notes |
| --- | --- | --- |
| `switch_input_language(language="next", hwnd=None)` | Requests a target or foreground window to switch input language through `WM_INPUTLANGCHANGEREQUEST`. | `language` accepts `next`, `previous`, common aliases such as `en-US` / `zh-CN`, or a Windows KLID such as `00000409`. |
| `set_caps_lock(enabled)` | Sets global CapsLock state if it differs from the requested value. | CapsLock is a desktop keyboard toggle, not a target-window-local state. |
| `switch_input_state(language=None, caps_lock=None, toggle_caps_lock=False, hwnd=None)` | Convenience wrapper that can switch language and set/toggle CapsLock in one call. | Exposes `user32` injection for tests or custom wrappers. |

## Plugin API

AlphaWindow uses `pluggy` for optional extension packages. This is the right place for hardware device bridges, proprietary SDK adapters, app-specific capture engines, or experimental input transports that should not become core dependencies. See the formal plugin protocol in [docs/plugin-protocol.zh-CN.md](docs/plugin-protocol.zh-CN.md).

`alphawindow-xxx` is only a recommended package naming convention. AlphaWindow does not auto-import packages by name prefix. Automatic discovery only loads the `alphawindow.plugins` entry point group.

A plugin package exposes methods through the `alphawindow.plugins` entry point group:

```toml
[project.entry-points."alphawindow.plugins"]
my_hardware = "my_hardware_plugin"
```

The plugin module returns method descriptors from hook implementations:

```python
from alphawindow import Capability, InputMode, OutputMode
from alphawindow.plugins import PluginCaptureMethod, PluginInputMethod, hookimpl

class HardwareCaptureBackend:
    mode = OutputMode.WINDOW_CAPTURE
    capabilities = frozenset({Capability.WINDOW_CAPTURE})

    def __init__(self, *, device_id: str):
        self.device_id = device_id

    def capture(self, target):
        ...

    def observe(self, target):
        return target

class HardwareInputBackend:
    mode = InputMode.FOREGROUND
    capabilities = frozenset({Capability.GLOBAL_INPUT})

    def __init__(self, *, device_id: str):
        self.device_id = device_id

    def perform(self, target, operation):
        ...

@hookimpl
def alphawindow_capture_methods():
    return [
        PluginCaptureMethod(
            name="hardware_capture",
            factory=HardwareCaptureBackend,
            mode=OutputMode.WINDOW_CAPTURE,
            capabilities=frozenset({Capability.WINDOW_CAPTURE}),
        )
    ]

@hookimpl
def alphawindow_input_methods():
    return [
        PluginInputMethod(
            name="hardware_input",
            factory=HardwareInputBackend,
            mode=InputMode.FOREGROUND,
            capabilities=frozenset({Capability.GLOBAL_INPUT}),
        )
    ]
```

Callers discover installed plugins and instantiate backends by method name:

```python
from alphawindow import discover_plugins

registry = discover_plugins()
output_backend = registry.create_capture_backend("hardware_capture", device_id="cap0")
input_backend = registry.create_input_backend("hardware_input", device_id="kbd0")
```

Plugin method names must be unique. Backends returned by a plugin are checked against the advertised mode and capabilities before use, so an invalid plugin fails closed instead of being silently accepted.

## Built-in Profiles

| Profile | Input mode | Output mode | Current behavior |
| --- | --- | --- | --- |
| `inspect` | `dry_run` | `state` | Inspect resolver state only. |
| `observe` | `dry_run` | `window_capture` | Observe/capture without input. |
| `desktop_observe` | `dry_run` | `desktop_region` | Observe through desktop-region output. |
| `monitor_observe` | `dry_run` | `monitor_capture` | Observe through explicit monitor capture. |
| `dry_run` | `dry_run` | `none` | Record planned operations without side effects. |
| `win32_message` | `message` | `window_capture` | Adapter slot for window-message input plus window capture. |
| `message_only` | `message` | `none` | Adapter slot for message input without output. |
| `uia_control` | `uia` | `state` | Adapter slot for UIA control operations. |
| `uia_visual` | `uia` | `window_capture` | Adapter slot for UIA input plus visual capture. |
| `global_input` | `foreground` | `desktop_region` | Adapter slot for pynput/SendInput-style foreground input. |
| `foreground_visual` | `foreground` | `window_capture` | Foreground input with target-window output. |
| `guarded_input` | `guarded_foreground` | `window_capture` | Adapter slot for foreground input with focus/cleanup guards. |
| `guarded_desktop` | `guarded_foreground` | `desktop_region` | Guarded foreground input with desktop-region capture. |
| `isolated_observe` | `isolated` | `window_capture` | Requires a hook-capable input backend; can isolate real mouse input before optional delegated input. |
| `isolated_telemetry` | `isolated` | `hook_telemetry` | Requires hook support for isolation and telemetry. |
| `virtual_window` | `virtualized` | `window_capture` | Requires hook support and a virtual input transport. |
| `virtual_telemetry` | `virtualized` | `hook_telemetry` | Requires hook support for virtual input and telemetry. |
| `virtual_input_only` | `virtualized` | `none` | Requires hook support; routes virtual input without output capture. |

## Considered Design Surface

These capabilities are represented in the model and can be supplied by external adapters today:

- Native window resolution by `hwnd`, title, class name, PID, visibility, DPI, and process/thread metadata.
- Direct window output through built-in `PrintWindow` and `BitBlt`, plus extension slots for DWM thumbnails or application-specific capture.
- HDR-aware DirectX/Windows Graphics Capture output with explicit pixel format, color space, buffer count, free-threaded frame-pool preference, DPI, target kind, and SDR white-level metadata.
- Native WGC capture through PyWinRT for callers that want a window or monitor `IDirect3DSurface`, a tone-mapped CPU image, or a persistent latest-frame cache for high-frequency capture loops.
- Monitor-targeted WGC output for cases where the desired image is the visible display containing a target window, including borderless-fullscreen style scenarios where window-target capture is the wrong abstraction.
- Desktop-region output for modes where the target must be foreground or compositor-visible.
- Window-message input for controls that accept `PostMessage`/`SendMessage` style input.
- Windows UI Automation input for standard controls.
- Foreground input through `pynput`, `SendInput`, or equivalent global input libraries.
- Guarded foreground input that restores focus/cursor state after an operation.
- Optional hook-assisted mouse and keyboard windowization, including target-local telemetry.
- Per-window or per-process virtual input transports for multi-window automation without taking over the primary mouse.

## Not Supported Yet

The package still keeps most native adapters out of core. In particular, it does not currently include:

- A built-in pywin32 `WindowResolver`.
- A general-purpose native resolver API in the core session layer; the current Win32 HWND picker exists only for the `alphawindow` test tool.
- Color-managed HDR preview or HDR-preserving image/video encoders.
- Advanced tone-mapping controls beyond the built-in ACES-style SDR conversion.
- Built-in `PostMessage`, UIA, pynput, or SendInput input backends.
- A production DLL injection or hook manager.
- A ready-made virtual input IPC transport.
- OCR, image matching, accessibility tree querying, or high-level wait/retry helpers.
- Non-Windows native backends.
- Guaranteed capture of true exclusive fullscreen swap chains, protected content, anti-cheat blocked content, secure desktops, or other content Windows/WGC refuses to expose.
- Kernel drivers, privilege escalation, protected-process bypasses, anti-cheat bypasses, or game-specific automation logic.

The desktop test tool is intended for manual adapter verification. Its attach action observes the next left-click through `pynput`, so that click may still focus or interact with the target application. The preview is SDR/tone-mapped for Tk display and is not a color-managed HDR viewer.

Window screenshot failures are fail-closed. If WGC frame creation, Win32/GDI capture, readback, or tone mapping fails, AlphaWindow surfaces that exception to the caller/UI instead of falling back to desktop screenshots, PIL `ImageGrab`, or another global capture path.

The `wgc_monitor_cached` mode is an explicit whole-monitor capture mode, not an automatic fallback. It can help test borderless-fullscreen or compositor-visible game output because it captures the monitor that contains the attached window. It can also expose unrelated pixels on that display, and it still cannot bypass exclusive fullscreen, protected content, or anti-cheat restrictions.

Hook-capable profiles fail closed unless the provided backend advertises hook capability. `VirtualizedInputBackend` also requires a `VirtualInputTransport`.

## Planned Features

- pywin32-based resolver and state backend for common window selectors.
- Native capture adapter for desktop-region capture.
- Broader Windows Graphics Capture resize handling.
- HDR-preserving image encoders and richer color-management metadata.
- pynput/SendInput foreground input backend and guarded foreground focus restoration.
- Window-message and UIA adapters for common controls.
- A documented hook manager interface with a sample user-mode hook implementation.
- A sample virtual input transport suitable for target-window mouse/keyboard windowization.
- More examples showing how to share one automation script across dry-run, message, foreground, isolated, and virtualized modes.
- Expanded integration tests for real Windows adapters while keeping unit tests deterministic through fake backends.

## Install

From PyPI:

```powershell
pip install alphawindow
```

From this checkout:

```powershell
pip install .
```

Native Windows adapters are optional:

```powershell
pip install "alphawindow[native]"
```

Pillow and numpy screenshot conversions are optional:

```powershell
pip install "alphawindow[image]"
```

## Command-line Test Tool

```powershell
alphawindow
```

The command opens a small Windows desktop tool using the current working directory as its workspace label. Click `Attach Window`, click a target window, then choose:

- `wgc_window_cached` for a persistent window-target WGC readback loop.
- `wgc_window_single` for one WGC window session per capture.
- `wgc_monitor_cached` for a persistent WGC readback loop against the monitor containing the attached window.
- `win32_print_window` for classic `PrintWindow(hwnd, hdc, 2)` capture.
- `win32_bitblt_window` for classic `GetWindowDC` + `BitBlt(..., SRCCOPY)` capture.
- HDR mode: `auto`, `force`, or `off`.
- Refresh rate: `1`, `30`, or `120` Hz.

The preview refreshes in the app and shows the latest capture time plus the average of the most recent 30 captures. Use `alphawindow --workspace D:\path\to\workspace` to show a different workspace path in the tool.

## Import

```python
import alphawindow

from alphawindow import (
    AutomationConfig,
    CaptureOutputFormat,
    CaptureTargetKind,
    DirectXCaptureConfig,
    MonitorSnapshot,
    WgcFrameReadbackResult,
    Win32WindowCaptureBackend,
    Win32WindowCaptureMethod,
    WinrtWgcCapturePipeline,
    WinrtWgcFrameCache,
    InputMode,
    OutputMode,
    WindowSelector,
    WindowSession,
    get_profile,
    switch_input_state,
)

print(alphawindow.__version__)
print(get_profile("observe").input_mode is InputMode.DRY_RUN)
print(CaptureOutputFormat.NUMPY_BGR.value)
print(DirectXCaptureConfig().hdr_mode.value)
print(CaptureTargetKind.MONITOR.value)
print(MonitorSnapshot.__name__)
print(WgcFrameReadbackResult.__name__)
print(Win32WindowCaptureBackend.__name__)
print(Win32WindowCaptureMethod.PRINT_WINDOW.value)
print(WinrtWgcCapturePipeline.__name__)
print(WinrtWgcFrameCache.__name__)
print(switch_input_state.__name__)
```

## Native WGC Screenshot

```python
from alphawindow import DirectXCaptureConfig, HdrCaptureMode, WindowSnapshot
from alphawindow.native_wgc import WinrtWgcCapturePipeline

target = WindowSnapshot(
    hwnd=123456,
    title="Target",
    rect=(0, 0, 1920, 1080),
    dpi=144,
    metadata={"hdr_enabled": True, "sdr_white_level_nits": 203.0},
)
request = DirectXCaptureConfig(hdr_mode=HdrCaptureMode.AUTO).create_request(target)

pipeline = WinrtWgcCapturePipeline(timeout_seconds=2.0)
frame = pipeline.capture_cpu(target, request, tone_map=True)
frame.save_png("target.png")
pipeline.close()
```

`capture_cpu()` and the Win32 capture backends return `CpuFrame` by default. Callers can choose a higher-level image output format explicitly:

```python
from alphawindow import CaptureOutputFormat

pil_image = frame.to_output(CaptureOutputFormat.PILLOW)      # PIL.Image.Image, RGB
opencv_bgr = frame.to_output(CaptureOutputFormat.NUMPY_BGR)  # numpy uint8, H x W x 3, BGR
numpy_rgb = frame.to_output(CaptureOutputFormat.NUMPY_RGB)   # numpy uint8, H x W x 3, RGB
numpy_bgra = frame.to_output("numpy_bgra")                   # numpy uint8, H x W x 4, BGRA
```

Numpy output is zero-copy by default when the frame is already SDR BGRA8. `numpy_bgra`, `numpy_bgr`, and `numpy_rgb` are views over `CpuFrame.data`; `numpy_bgr` drops alpha through strides, and `numpy_rgb` reverses channels through a negative stride. If a downstream library requires a C-contiguous array, request a copy explicitly:

```python
opencv_bgr = frame.to_output(CaptureOutputFormat.NUMPY_BGR, copy=True)
```

The preview controller exposes the same choice through `CaptureSettings` while still preserving the underlying `CpuFrame`:

```python
from alphawindow import CaptureOutputFormat
from alphawindow.cli_app import CaptureSettings

settings = CaptureSettings(
    output_format=CaptureOutputFormat.NUMPY_BGR,
    output_copy=False,
)
result = controller.capture(target, settings)
frame = result.frame      # CpuFrame
image = result.output     # zero-copy numpy view in the requested format
```

To capture the full monitor containing a target, pass a `MonitorSnapshot` and create a monitor request:

```python
from alphawindow import DirectXCaptureConfig, HdrCaptureMode, MonitorSnapshot
from alphawindow.native_wgc import WinrtWgcCapturePipeline

target = MonitorSnapshot(
    hmonitor=123456,
    device_name="DISPLAY1",
    rect=(0, 0, 3840, 2160),
    work_rect=(0, 0, 3840, 2080),
    dpi=144,
    primary=True,
    metadata={"hdr_enabled": True, "sdr_white_level_nits": 203.0},
)
request = DirectXCaptureConfig(hdr_mode=HdrCaptureMode.AUTO).create_monitor_request(target)

pipeline = WinrtWgcCapturePipeline(timeout_seconds=2.0)
frame = pipeline.capture_cpu(target, request, tone_map=True)
frame.save_png("monitor.png")
pipeline.close()
```

For repeated capture, keep the WGC session alive and read back the latest frame:

```python
from alphawindow.native_wgc import WinrtWgcFrameCache

def sample_labels(frame_info):
    return {"sequence": frame_info["sequence"], "labels": []}

cache = WinrtWgcFrameCache.start_for(target, request, timeout_seconds=2.0)
try:
    result = cache.readback_latest_cpu(
        tone_map=True,
        fresh_max_age_ms=8.0,
        fresh_wait_ms=16.0,
        before_readback=sample_labels,
    )
    result.cpu.save_png("target.png")
    print(result.info["size"], result.info["content_size"], result.hook_result)
finally:
    cache.close()
```
