Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 12 additions & 6 deletions scripts/inspect-window.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions src-tauri/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

28 changes: 28 additions & 0 deletions src-tauri/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
]}
1 change: 1 addition & 0 deletions src-tauri/src/lib.rs
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
pub mod overlay;
pub mod window_source;
208 changes: 208 additions & 0 deletions src-tauri/src/window_source.rs
Original file line number Diff line number Diff line change
@@ -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<Rect>,
/// Visible windows in descending z-order: frontmost first.
pub windows: Vec<WindowRect>,
}

/// 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"]);
}
}
Loading