Module offscreen 

Off-screen launch for recording scenarios (launch_offscreen).

The driven window is placed outside the union of ALL displays while staying visible (never hidden, never minimized), so the window server keeps compositing it and a recorder can capture it without anything appearing on a user’s screen.

Two halves:

• In-process (the driven app, embedded path): the app calls [start_from_env] / [start_for_window] at startup, before its window is first ordered, when it was launched with RIGHTKIT_OFFSCREEN=1. macOS: class-scoped constrainFrameRect:toScreen: override, NSProcessInfo activity held for the session (App Nap defence), and (cargo feature offscreen-private-spi, default off) the private WKWebView _setWindowOcclusionDetectionEnabled:NO. Windows: SetWindowPos to off-monitor coordinates and an EcoQoS (execution-speed throttling) opt-out.
• Controller side: launch_offscreen spawns the app with that env, waits for the app’s session report, and returns a session with PID and native window identity. OffscreenLaunch::end kills the process it started.

offscreen_qualification re-reads the live window and verifies it is off all displays, visible, not miniaturized and (macOS) that the occlusion SPI responded.

Structs

Check

LaunchSpec

What to launch. program is the app’s executable (spawned directly so this process owns the PID; no open/LaunchServices indirection).

OffscreenLaunch

A launched off-screen app. Dropping it kills the process it started.

Placement

Where the window was and where it is now.

QualificationReport

Rect

A rectangle in the platform’s global desktop coordinates (AppKit bottom-left on macOS, virtual-screen top-left on Windows). The placement math only uses x extents and the lowest y, so it is axis-convention agnostic.

SessionReport

Native identity and placement of the driven window.

WindowState

Live window facts the qualification checks run on.

Enums

OffscreenError

Platform

SpiStatus

Constants

ENV_OFFSCREEN

Env flag the controller sets and the app reads.

ENV_REPORT

Env path where the app writes its session report (JSON, atomic rename).

OFFSCREEN_GAP

Distance past the right edge of the display union.

PLACEMENT_TOLERANCE

Placement read-back tolerance in points/pixels.

Traits

WindowOps

Window operations the placement logic needs. Implemented by the native windows and by fakes in tests.

Functions

active_report

Report of the active in-process session, if any.

display_union

Bounding box of all displays.

end_active

End the active session on the main thread: restore the window and release the process activity / throttling opt-out.

launch_offscreen

Spawn the app with off-screen mode requested and wait for its session report. Verifies the reported PID is the spawned child and (macOS) that the reported window id exists and belongs to that PID.

launch_offscreen_gated

launch_offscreen admitted through an crate::admission::EffectGate (EFF-001). The gate’s error channel is string-typed; use the ungated function for typed errors.

offscreen_frame

Frame for a size window placed OFFSCREEN_GAP right of the union of ALL displays (not just the primary one), aligned to the union’s lowest y. The result intersects neither any display nor the union bounding box.

offscreen_qualification

Per-OS qualification of the active in-process session: re-reads the live window. Must run on the main thread.

offscreen_requested

True when this process was launched with RIGHTKIT_OFFSCREEN=1.

place

Move w off all displays, make it visible, and read the frame and scale back. Verifies the read-back frame equals the request; the caller still runs qualify for visibility and display checks.

qualify

Per-OS qualification over a window snapshot.

restore

Hide, move back to the original frame and verify.

snapshot

Snapshot a window for qualify.

start_native^⚠

Start off-screen mode on a native window. macOS: ns_window is the NSWindow* and wk_webview the WKWebView*. Windows: ns_window carries the HWND value and wk_webview is ignored. Main thread only, before the window is first ordered.

write_report

Write the report (or an {"error":..} body) atomically to ENV_REPORT, if set.