Repository navigation
macOS WindowSource and platform capabilities - #20
Merged
Merged
Conversation
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>
This was referenced Aug 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #2.
What changed
WindowSource, the trait that produces the geometry half of aWorldSnapshot,plus the macOS implementation that reads it.
src-tauri/src/window_source.rs— the trait,Capabilities,Rect,WindowRect,WorldGeometry,POLL_INTERVAL, aStubWindowSourcefornon-macOS, and a
FakeWindowSourcefor Engine tests.src-tauri/src/window_source/macos.rs—CGWindowListCopyWindowInfoforvisible windows and
CGGetActiveDisplayList/CGDisplayBoundsfor displayframes. Bounds, owning application name and window level, frontmost first.
No titles.
objc2-*crates named inCargo.toml. All three were already in thelock file as dependencies of
objc2-app-kit; naming them declares what thiscrate calls directly.
default-features = falsekeeps a window list fromdragging in Metal.
The branch also carries a documentation-only commit on
scripts/inspect-window.swift. Its header used to argue that readingCGWindowList 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:
WindowSourceis deliberately blindto 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.
readreports whatever a platform can see;snapshotis a defaultmethod that clears
windowsunlesswindow_geometryis declared. Putting theguard 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.
CGDisplayBoundsandkCGWindowBoundsare 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-foundationis free at runtime and buys safe iteration insteadof raw
CFArrayGetValueAtIndexpointer 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 warningsObserved on a fresh worktree of this branch:
Two of the eight are new and cover the capability guard in both directions:
a_platform_without_window_geometry_yields_display_frames_and_no_windowsanda_platform_with_window_geometry_yields_its_windows_frontmost_first. Clippywith
-D warningsfinished 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, anddocs/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 --nocaptureIt 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_INTERVALexists and is documented, but the only caller is theignored test. Wiring
MacosWindowSourceinto the running app was deliberatelyleft 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,CGGetActiveDisplayListorCGDisplayBoundsis TCC-gated, andkCGWindowNameis 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:inmacos.rs:MAX_DISPLAYSis a fixed 16.CGGetActiveDisplayListtruncates rather than failing, so a seventeenthdisplay 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;
StubWindowSourceiscfg(not(target_os = "macos")), so itcovers 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