diff --git a/scripts/inspect-window.swift b/scripts/inspect-window.swift index afb48d5fe..a8bba1cc1 100644 --- a/scripts/inspect-window.swift +++ b/scripts/inspect-window.swift @@ -6,12 +6,18 @@ // cannot see a non-activating panel that is excluded from the switcher, nor // report a window level at all. // -// Why Swift and not Rust, in a Rust repository: CGWindowList lives in -// CoreGraphics, which would mean adding a dependency purely for a dev tool. -// Xcode is already required to build a Tauri app on macOS, so `swift` is -// already installed and costs nothing. It also keeps the observer independent -// of the app it observes, which is the point — the display-union bug was caught -// precisely because this asks the window server, not the app. +// Why Swift and not Rust, in a Rust repository: the crate's own WindowSource +// now reads these same CoreGraphics calls, so the bindings are no longer the +// obstacle. It cannot stand in for this, though — WindowSource is deliberately +// blind to our own process, because the overlay spans every display and a +// Character able to see it would find a Perch across the whole desktop and +// never fall again. This script exists to observe precisely that window, so the +// two want opposite things. +// +// Xcode is already required to build a Tauri app on macOS, so `swift` costs +// nothing to run. Keeping the observer outside the app's own toolchain is worth +// something on its own: the display-union bug was caught because this asks the +// window server rather than asking the app what it believes. // // Uses CGWindowListCopyWindowInfo, which returns window bounds, owner and layer // with no permission prompt — the same call docs/SPEC.md specifies for diff --git a/src-tauri/Cargo.lock b/src-tauri/Cargo.lock index 784b633b4..e28b9ed84 100644 --- a/src-tauri/Cargo.lock +++ b/src-tauri/Cargo.lock @@ -23,6 +23,9 @@ version = "0.1.0" dependencies = [ "objc2", "objc2-app-kit", + "objc2-core-foundation", + "objc2-core-graphics", + "objc2-foundation", "png 0.18.1", "serde", "tauri", diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml index 604717572..6722d28e3 100644 --- a/src-tauri/Cargo.toml +++ b/src-tauri/Cargo.toml @@ -30,3 +30,31 @@ objc2-app-kit = {version = "0.3", features = [ "NSResponder", "NSApplication" ]} +# The window list and the display list. Both crates are already compiled as +# dependencies of objc2-app-kit; naming them here declares what we call +# directly rather than pulling anything new in. The alternative is hand-written +# `extern "C"` declarations of the same CoreGraphics symbols. +# +# `default-features = false` throughout: these crates default to binding whole +# frameworks, which drags in Metal for a window list. +objc2-core-foundation = {version = "0.3", default-features = false, features = [ + "std", + "CFCGTypes", + "CFDictionary" +]} +objc2-core-graphics = {version = "0.3", default-features = false, features = [ + "std", + "objc2", + "CGDirectDisplay", + "CGError", + "CGGeometry", + "CGWindow" +]} +objc2-foundation = {version = "0.3", default-features = false, features = [ + "std", + "NSArray", + "NSDictionary", + "NSEnumerator", + "NSString", + "NSValue" +]} diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs index 2b55280ec..6ab370767 100644 --- a/src-tauri/src/lib.rs +++ b/src-tauri/src/lib.rs @@ -1 +1,2 @@ pub mod overlay; +pub mod window_source; diff --git a/src-tauri/src/window_source.rs b/src-tauri/src/window_source.rs new file mode 100644 index 000000000..2cc7184f0 --- /dev/null +++ b/src-tauri/src/window_source.rs @@ -0,0 +1,208 @@ +//! Where the windows are. +//! +//! The Spatial Layer needs window geometry before the user has granted +//! anything, so this layer is deliberately built out of what the operating +//! system hands over for free. Everything a permission prompt would buy — +//! window titles above all — is absent by construction rather than by policy. + +use std::time::Duration; + +#[cfg(target_os = "macos")] +mod macos; + +#[cfg(target_os = "macos")] +pub use macos::MacosWindowSource; + +/// How often the Shell should read the source: approximately 10Hz. +/// +/// Windows move at human speed, and the Engine interpolates between reads, so +/// smoothness is the renderer's problem rather than a reason to poll faster. +/// Ten times a second is what keeps a full window-list enumeration off the +/// frame loop and out of the battery budget. +pub const POLL_INTERVAL: Duration = Duration::from_millis(100); + +/// What a platform can actually tell us about the desktop. +/// +/// Declared, never assumed. Under Wayland both of these are unavailable and the +/// Spatial Layer degrades to screen-edge physics, which is a supported mode +/// rather than an error state. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub struct Capabilities { + /// Whether the platform reports the rectangles of other applications' + /// windows. Without it there are no Perches. + pub window_geometry: bool, + /// Whether a window can be placed at chosen coordinates. Without it the + /// overlay goes wherever the compositor puts it. + pub absolute_positioning: bool, +} + +/// A rectangle in the global display coordinate space, in points. +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct Rect { + pub x: f64, + pub y: f64, + pub width: f64, + pub height: f64, +} + +/// One visible window: where it is, who owns it, and how high it stacks. +/// +/// No title. Titles need Screen Recording consent, and v1 asks for nothing. +#[derive(Clone, Debug, PartialEq)] +pub struct WindowRect { + pub bounds: Rect, + /// The owning application's name, as the window server reports it. + pub owner: String, + /// The window server's level: 0 for ordinary application windows, higher + /// for menus, docks and other overlays. The Engine decides what is a Perch. + pub layer: i32, +} + +/// The geometry half of a `WorldSnapshot`. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct WorldGeometry { + /// Every active display's frame, in the same coordinate space as `windows`. + pub display_frames: Vec, + /// Visible windows in descending z-order: frontmost first. + pub windows: Vec, +} + +/// A platform's view of the desktop. +pub trait WindowSource { + fn capabilities(&self) -> Capabilities; + + /// Read whatever the platform will report right now. An implementation + /// reports what it can see; honouring the declared capabilities is + /// `snapshot`'s job, not each platform's. + fn read(&self) -> WorldGeometry; + + /// The seam the Engine reads from. + /// + /// Window rectangles are dropped unless the platform declares + /// `window_geometry`, so a degraded platform yields display frames and + /// nothing else. Without this, a platform that can see some windows some of + /// the time would feed the physics half a desktop, and the sprite would + /// perch on Perches that are not there. + fn snapshot(&self) -> WorldGeometry { + let mut geometry = self.read(); + if !self.capabilities().window_geometry { + geometry.windows.clear(); + } + geometry + } +} + +/// Every other platform for now. Windows is stubbed deliberately: `docs/SPEC.md` +/// puts it out of scope for v1, and the interface exists so that the Spatial +/// Layer meets a platform that declares nothing and degrades, rather than a +/// platform that is missing. +#[cfg(not(target_os = "macos"))] +pub struct StubWindowSource; + +#[cfg(not(target_os = "macos"))] +impl WindowSource for StubWindowSource { + fn capabilities(&self) -> Capabilities { + Capabilities::default() + } + + fn read(&self) -> WorldGeometry { + WorldGeometry::default() + } +} + +/// Hand-written fake for Engine tests: it reports exactly what it was built +/// with, so a test can describe a desktop as a literal. +#[cfg(test)] +pub struct FakeWindowSource { + pub capabilities: Capabilities, + pub geometry: WorldGeometry, +} + +#[cfg(test)] +impl WindowSource for FakeWindowSource { + fn capabilities(&self) -> Capabilities { + self.capabilities + } + + fn read(&self) -> WorldGeometry { + self.geometry.clone() + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn rect(x: f64, y: f64, width: f64, height: f64) -> Rect { + Rect { + x, + y, + width, + height, + } + } + + fn window(owner: &str, bounds: Rect) -> WindowRect { + WindowRect { + bounds, + owner: owner.to_string(), + layer: 0, + } + } + + /// The Wayland case: displays are known, windows are not. + #[test] + fn a_platform_without_window_geometry_yields_display_frames_and_no_windows() { + let source = FakeWindowSource { + capabilities: Capabilities { + window_geometry: false, + absolute_positioning: false, + }, + geometry: WorldGeometry { + display_frames: vec![rect(0.0, 0.0, 1920.0, 1080.0)], + windows: vec![window("Terminal", rect(10.0, 20.0, 800.0, 600.0))], + }, + }; + + let snapshot = source.snapshot(); + + assert_eq!( + snapshot.display_frames, + vec![rect(0.0, 0.0, 1920.0, 1080.0)] + ); + assert!( + snapshot.windows.is_empty(), + "no window_geometry capability means no rectangles: {:?}", + snapshot.windows + ); + } + + /// The macOS case: the guard above must not swallow the windows of a + /// platform that can see them, and must not reshuffle them — the Engine + /// reads z-order out of the order alone. + #[test] + fn a_platform_with_window_geometry_yields_its_windows_frontmost_first() { + let source = FakeWindowSource { + capabilities: Capabilities { + window_geometry: true, + absolute_positioning: true, + }, + geometry: WorldGeometry { + display_frames: vec![rect(0.0, 0.0, 1920.0, 1080.0)], + windows: vec![ + window("Terminal", rect(10.0, 20.0, 800.0, 600.0)), + window("Finder", rect(30.0, 40.0, 500.0, 400.0)), + ], + }, + }; + + let owners: Vec<_> = source + .snapshot() + .windows + .iter() + .map(|w| w.owner.clone()) + .collect(); + + assert_eq!(owners, vec!["Terminal", "Finder"]); + } +} diff --git a/src-tauri/src/window_source/macos.rs b/src-tauri/src/window_source/macos.rs new file mode 100644 index 000000000..93814010a --- /dev/null +++ b/src-tauri/src/window_source/macos.rs @@ -0,0 +1,233 @@ +//! Window geometry from the macOS window server, without consent. +//! +//! `CGWindowListCopyWindowInfo` is the one macOS API that hands over the shape +//! of the desktop for free. It reports bounds, owning application and window +//! level to any process; only `kCGWindowName` — the title — is withheld until +//! Screen Recording is granted, and this module never asks for it. That is what +//! makes the Spatial Layer work on first run, before the user has agreed to +//! anything. + +use objc2::runtime::AnyObject; +use objc2_core_foundation::{CFDictionary, CGRect}; +use objc2_core_graphics::{ + CGDisplayBounds, CGError, CGGetActiveDisplayList, CGRectMakeWithDictionaryRepresentation, + CGWindowListCopyWindowInfo, CGWindowListOption, +}; +use objc2_foundation::{ns_string, NSArray, NSDictionary, NSNumber, NSString}; + +use super::{Capabilities, Rect, WindowRect, WindowSource, WorldGeometry}; + +/// ponytail: a fixed sixteen displays, because `CGGetActiveDisplayList` +/// truncates rather than failing and the seventeenth display would silently go +/// missing from the physics. Call it twice — once with a null buffer for the +/// count — if anyone ever plugs in more. +const MAX_DISPLAYS: u32 = 16; + +/// The macOS window server's view of the desktop. +pub struct MacosWindowSource { + /// Our own process. Its windows are excluded from every read: the overlay + /// spans every display, so a sprite allowed to see it would find a Perch + /// stretching across the whole desktop and never fall again. + own_pid: i32, +} + +impl MacosWindowSource { + pub fn new() -> Self { + Self { + own_pid: std::process::id() as i32, + } + } +} + +impl Default for MacosWindowSource { + fn default() -> Self { + Self::new() + } +} + +impl WindowSource for MacosWindowSource { + fn capabilities(&self) -> Capabilities { + Capabilities { + window_geometry: true, + absolute_positioning: true, + } + } + + fn read(&self) -> WorldGeometry { + WorldGeometry { + display_frames: display_frames(), + windows: visible_windows(self.own_pid), + } + } +} + +/// Every active display's frame, in the global display coordinate space. +/// +/// `CGDisplayBounds` is in points with the origin at the top-left of the main +/// display, which is the same space `kCGWindowBounds` uses. Asking AppKit +/// instead would mean converting out of its bottom-left, per-screen space for +/// no gain. +fn display_frames() -> Vec { + let mut ids = [0u32; MAX_DISPLAYS as usize]; + let mut count = 0u32; + + // SAFETY: both pointers address local storage, and `MAX_DISPLAYS` is the + // true capacity of `ids`. + let status = unsafe { CGGetActiveDisplayList(MAX_DISPLAYS, ids.as_mut_ptr(), &mut count) }; + if status != CGError::Success { + return Vec::new(); + } + + ids[..count as usize] + .iter() + .map(|&id| rect(CGDisplayBounds(id))) + .collect() +} + +/// Visible windows, frontmost first. +/// +/// `OnScreenOnly` already returns the list in front-to-back order, which is the +/// descending z-order the Engine wants, and `ExcludeDesktopElements` drops the +/// desktop image and its icons — a sprite should stand on the desktop, not on a +/// window covering it. +fn visible_windows(own_pid: i32) -> Vec { + let options = + CGWindowListOption::OptionOnScreenOnly | CGWindowListOption::ExcludeDesktopElements; + let Some(list) = CGWindowListCopyWindowInfo(options, 0) else { + return Vec::new(); + }; + + // SAFETY: CFArray is toll-free bridged to NSArray, and this call's contract + // is that every element is a CFDictionary keyed by CFString — bridged to + // NSDictionary and NSString. Reading through the bridge costs nothing and + // buys safe iteration and safe downcasts. + let entries: &NSArray> = + unsafe { &*std::ptr::from_ref(&*list).cast() }; + + entries.iter().filter_map(|e| window(&e, own_pid)).collect() +} + +/// One window-list entry, or `None` for entries we cannot or should not use. +/// +/// The keys are spelled as literals because their `kCGWindow*` constants are +/// defined as exactly these strings, and a bridged dictionary compares string +/// keys by value. +fn window(entry: &NSDictionary, own_pid: i32) -> Option { + if number(entry, ns_string!("kCGWindowOwnerPID"))?.as_i32() == own_pid { + return None; + } + + let bounds = entry.objectForKey(ns_string!("kCGWindowBounds"))?; + let mut cg_rect = CGRect::ZERO; + // SAFETY: `kCGWindowBounds` is documented to be a rectangle in the + // dictionary representation this function decodes, and NSDictionary is + // toll-free bridged to the CFDictionary it expects. + let decoded = unsafe { + CGRectMakeWithDictionaryRepresentation( + Some(&*std::ptr::from_ref(&*bounds).cast::()), + &mut cg_rect, + ) + }; + if !decoded { + return None; + } + + Some(WindowRect { + bounds: rect(cg_rect), + owner: entry + .objectForKey(ns_string!("kCGWindowOwnerName"))? + .downcast::() + .ok()? + .to_string(), + layer: number(entry, ns_string!("kCGWindowLayer"))?.as_i32(), + }) +} + +fn number( + entry: &NSDictionary, + key: &NSString, +) -> Option> { + entry.objectForKey(key)?.downcast::().ok() +} + +fn rect(cg_rect: CGRect) -> Rect { + Rect { + x: cg_rect.origin.x, + y: cg_rect.origin.y, + width: cg_rect.size.width, + height: cg_rect.size.height, + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// Hand verification, deliberately not part of the suite: it needs a real + /// window server and it reads a clock, both of which `docs/SPEC.md` rules + /// out for `cargo test`. `#[ignore]` keeps the suite pure and fast. + /// + /// Run it with: + /// + /// ```text + /// cargo test --manifest-path src-tauri/Cargo.toml \ + /// window_source -- --ignored --nocapture + /// ``` + /// + /// It prints the desktop as this module sees it, once per poll, whenever + /// the geometry changes — so move, resize, open and close windows while it + /// runs and watch the numbers follow. What no assertion can check is the + /// thing the issue cares about most: that no permission dialog appeared. + #[test] + #[ignore = "needs a real desktop; run by hand"] + fn live_desktop_geometry_follows_the_real_windows() { + let source = MacosWindowSource::new(); + let start = std::time::Instant::now(); + let deadline = start + std::time::Duration::from_secs(5); + let mut previous = None; + let mut polls = 0u32; + let mut spent = std::time::Duration::ZERO; + + while std::time::Instant::now() < deadline { + let started = std::time::Instant::now(); + let geometry = source.snapshot(); + spent += started.elapsed(); + polls += 1; + + assert!( + !geometry.display_frames.is_empty(), + "a real desktop has at least one display" + ); + assert!( + !geometry.windows.is_empty(), + "a real desktop has at least one window" + ); + + if previous.as_ref() != Some(&geometry) { + println!( + "\nt+{:.1}s displays: {:?}", + start.elapsed().as_secs_f64(), + geometry.display_frames + ); + for w in &geometry.windows { + println!( + " layer {:>3} {:>7.0},{:<7.0} {:>6.0}x{:<6.0} {}", + w.layer, w.bounds.x, w.bounds.y, w.bounds.width, w.bounds.height, w.owner + ); + } + previous = Some(geometry); + } + + std::thread::sleep(crate::window_source::POLL_INTERVAL); + } + + // Wall time, most of it spent blocked on the window server rather than + // on a CPU. Measure the process, not this number, when the question is + // whether polling costs anything. + println!( + "\n{polls} polls, {:?} waiting on reads, {:?} each", + spent, + spent / polls + ); + } +}