Skip to content

macOS WindowSource and platform capabilities - #20

Merged
omesser merged 3 commits into
mainfrom
feat/2-macos-window-source
Aug 28, 2026
Merged

omesser merged 3 commits into
mainfrom
feat/2-macos-window-source

Conversation

@omesser

@omesser omesser commented Aug 27, 2026

Copy link
Copy Markdown
Owner

Closes #2.

What changed

WindowSource, the trait that produces the geometry half of a WorldSnapshot,
plus the macOS implementation that reads it.

  • src-tauri/src/window_source.rs — the trait, Capabilities, Rect,
    WindowRect, WorldGeometry, POLL_INTERVAL, a StubWindowSource for
    non-macOS, and a FakeWindowSource for Engine tests.
  • src-tauri/src/window_source/macos.rs — CGWindowListCopyWindowInfo for
    visible windows and CGGetActiveDisplayList / CGDisplayBounds for display
    frames. Bounds, owning application name and window level, frontmost first.
    No titles.
  • Three objc2-* crates named in Cargo.toml. All three were already in the
    lock file as dependencies of objc2-app-kit; naming them declares what this
    crate calls directly. default-features = false keeps a window list from
    dragging in Metal.

The branch also carries a documentation-only commit on
scripts/inspect-window.swift. Its header used to argue that reading
CGWindowList from Rust would mean adding a CoreGraphics dependency for a dev
tool — this branch adds exactly that dependency, so the argument no longer
holds. The reason is now the durable one: WindowSource is deliberately blind
to our own process, and the inspector's whole job is observing our own overlay
window, so the two want opposite things.

Why it looks like this

The capability declaration is enforced in the trait, not left to each
platform.
read reports whatever a platform can see; snapshot is a default
method that clears windows unless window_geometry is declared. Putting the
guard in the platform would mean every future platform has to remember it, and
a partially-sighted one that forgot would feed the physics half a desktop —
the sprite perching on Perches that are not there. Under Wayland both
capabilities are false and the Spatial Layer degrades to screen-edge physics,
which is a supported mode.

Our own windows are filtered out by pid. The overlay spans the union of
every display, so a Character permitted to see it would find a single Perch
covering the whole desktop and never fall again.

Points, one coordinate space, no conversion. CGDisplayBounds and
kCGWindowBounds are both already in points against a single top-left origin.
Asking AppKit instead would mean converting out of its bottom-left, per-screen
space for nothing. This is what lets the Engine reason about non-aligned,
mixed-DPI displays without a scale factor anywhere.

The window-list dictionaries are read through the NSDictionary bridge.
CFArray and CFDictionary are toll-free bridged, so iterating and downcasting
through objc2-foundation is free at runtime and buys safe iteration instead
of raw CFArrayGetValueAtIndex pointer work.

How to verify

git worktree add /tmp/pr-2 origin/feat/2-macos-window-source
cargo test --manifest-path /tmp/pr-2/src-tauri/Cargo.toml
cargo clippy --manifest-path /tmp/pr-2/src-tauri/Cargo.toml --all-targets -- -D warnings

Observed on a fresh worktree of this branch:

test result: ok. 8 passed; 0 failed; 1 ignored; 0 measured; 0 filtered out

Two of the eight are new and cover the capability guard in both directions:
a_platform_without_window_geometry_yields_display_frames_and_no_windows and
a_platform_with_window_geometry_yields_its_windows_frontmost_first. Clippy
with -D warnings finished with no warnings.

The one ignored test is
window_source::macos::tests::live_desktop_geometry_follows_the_real_windows.
It is #[ignore]d because it sleeps and polls for five seconds, and
docs/SPEC.md says tests must not sleep, poll, or depend on wall-clock time. Run
it by hand and move, resize, open and close windows while it runs:

cargo test --manifest-path src-tauri/Cargo.toml \
    window_source -- --ignored --nocapture

It prints the desktop whenever the geometry changes, which is the acceptance
criterion about bounds following real windows. It also prints time spent
blocked on reads, which is a weak proxy for the Activity Monitor criterion —
that one wants the process watched, not a number printed by the test.

Known and deferred

Nothing polls. The issue's scope says the source polls at approximately
10Hz. POLL_INTERVAL exists and is documented, but the only caller is the
ignored test. Wiring MacosWindowSource into the running app was deliberately
left out of this branch — there is no Engine to hand snapshots to yet.

"No permission prompt appears on first run" is argued, not observed. It
rests on the choice of APIs: none of CGWindowListCopyWindowInfo,
CGGetActiveDisplayList or CGDisplayBounds is TCC-gated, and kCGWindowName
is never read. It was not confirmed against a clean machine, because this
development machine already holds Screen Recording consent and so cannot show
the difference.

ponytail: in macos.rs: MAX_DISPLAYS is a fixed 16.
CGGetActiveDisplayList truncates rather than failing, so a seventeenth
display would silently go missing from the physics. The fix is to call it twice
— once with a null buffer to learn the count.

The stub is not Windows-specific. The issue asks for Windows stubbed behind
the same trait; StubWindowSource is cfg(not(target_os = "macos")), so it
covers Windows and Linux alike. It declares no capabilities and returns an
empty WorldGeometry, which is the degraded path the trait already handles.

🤖 Generated with Claude Code

omesser and others added 3 commits August 27, 2026 03:15
The Spatial Layer cannot do anything on first run unless it already knows
where the windows are, and on first run nothing has been granted. That rules
out every screen-reading API a user has to consent to, and leaves exactly one:
CGWindowListCopyWindowInfo, which reports bounds, owning application and window
level to any process. Only the window title is withheld until Screen Recording
is granted, and nothing here reads it. Without this module the sprite has no
Perch to stand on; with it built any other way, the user meets a permission
dialog before they have met the Character.

Capabilities are declared rather than assumed, and the declaration is
load-bearing: `snapshot` drops window rectangles from any platform that does
not claim `window_geometry`. Without that guard, a partially-sighted platform
would feed the physics half a desktop and the sprite would land on Perches
that are not there. Wayland, where nothing can be seen, degrades to screen-edge
physics instead of failing.

Our own windows are excluded by process id. The overlay spans every display, so
a sprite permitted to see it would find one Perch covering the whole desktop
and never fall again.

Both coordinate spaces are the same one on purpose: CGDisplayBounds and
kCGWindowBounds are already in points against a single top-left origin, which
is what lets the Engine reason about non-aligned, mixed-DPI displays without
converting anything.

The macOS reader itself is verified by hand — the ignored test in the module
prints the live desktop at the poll rate — because a fake window server would
prove nothing about the real one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The display cap was documented but not marked, so it would not turn up when
someone goes looking for the shortcuts this codebase has taken. A seventeenth
display fails silently — the window list truncates and the physics simply
never learns about that screen — which is exactly the kind of thing the
ponytail marker exists to keep visible.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The note on scripts/inspect-window.swift argued that reading CGWindowList
from Rust would mean adding a CoreGraphics dependency for a dev tool.
This branch adds that dependency, so the argument no longer holds and
the next reader would rightly ask why the Swift is still there.

The durable reason is narrower and better: 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. The inspector exists to observe exactly that window.
Reusing WindowSource would mean deleting the filter that makes it
correct.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@omesser
omesser merged commit b67a0c5 into main Aug 28, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

macOS WindowSource and platform capabilities

1 participant