Repository navigation
Description
Why
Run the app and let the sprite settle. On a display with a Dock it comes to rest
at y = 1080 — the display's bottom edge, which is behind the Dock. The Dock
is at window level 20 and the overlay is at level 3, so the Dock composites on
top: roughly three quarters of the 128-point sprite disappears behind it.
Measured on a 1920x1080 display with a 98-point Dock inset:
frame: ... Grounded pos(960,1080) sprite(896,989) idle#0
NSScreen frame 0,0 1920x1080 visibleFrame 0,98 1920x952
The art occupies screen y 952-1080. The Dock owns y 982-1080.
This is already known and worked around rather than fixed.
scripts/verify-overlay.sh:141
says so outright — "where it ends up at rest is the bottom of the screen, and
the Dock sits at a higher window level than the overlay and covers it there" —
and takes its sprite screenshot mid-run to dodge it.
The same defect exists at the other end. ceiling_over ends a climb at
display.y, which is behind the 30-point menu bar. Nobody has hit it because
the furniture at the top is only met by a climb, never by a fall.
A companion that vanishes into the taskbar is not resting; it looks broken. In
either OS the sprite should stay where it can be seen.
What is actually true
The Dock's real dimensions are readable. They are just not in the window list,
which is where every rectangle the Engine sees comes from today.
Measured live on this machine, from NSScreen:
display 1: frame 0,0 1920x1080 visibleFrame 0,98 1920x952
display 2: frame 1920,-37 1728x1117 visibleFrame 1920,-37 1728x1085
A 98-point bottom inset on display 1 — the Dock, tilesize 72, autohide 0 —
and a 30-point top inset for the menu bar. Display 2 has no Dock and no inset.
The operating system already computes this and will hand it over; nothing has to
be inferred, hunted for, or measured from pixels.
What cannot answer it is the window list. That matters because it rules out the
change a reader reaches for first.
The Dock is excluded from Perches by one filter,
snapshot.rs:113:
fn perch_eligible(layer: i32) -> bool {
layer == 0
}Relaxing it to admit layer 20 fails on the input: the Dock's reported
kCGWindowBounds is the whole display, 0,0 1920x1080, not the Dock strip.
Its "top edge" is y = 0, so the sprite would perch under the menu bar and
never fall again — which is exactly bug 3 of the four in docs/SPEC.md that
earned the level filter, and is regression-tested by
only_ordinary_application_windows_reach_the_engine. The window list cannot
say where the Dock's top edge is, at any layer filter.
So the fix is not to teach the window list about the Dock. It is to stop asking
the window list, and shrink the display rectangle instead.
So the geometry has to come from somewhere else.
The decision
Report the usable display frame rather than the hardware frame — the
recommendation. WorldGeometry.display_frames becomes the area a sprite may
occupy, and the Engine's floor and ceiling both derive from it already
(floor_under, ceiling_over). Nothing learns what a Dock is: the Engine stays
pure, perch_eligible is untouched, and the menu-bar ceiling fixes itself.
- macOS:
NSScreen.visibleFrame. Handles a Dock on the left or right, and
auto-hide for free — an auto-hidden Dock reclaims the space, so the sprite
correctly returns to the true bottom. Costs one conversion out of AppKit's
bottom-left, per-screen space, which
window_source.rs:64
declined for no gain; there is now a gain. - Cross-platform:
tauri::Monitor::work_area()exists in the locked tauri
2.11.5, andmain.rsalready enumerates monitors and reads
position()/size()/scale_factor(). Windows getsSPI_GETWORKAREA
through the same field, so the taskbar is handled when Windows lands rather
than needing its own concept.
Alternatives, and why not:
- Dock as a Perch — impossible on the reported geometry, as above.
- Dock as the floor, read from the window list — same missing input.
- Clamp the floor in the Engine — smallest diff, but the Engine would have
to be told about screen furniture, anddocs/SPEC.mdkeeps window levels in
the Shell.
Two things the implementation has to decide, since the geometry does not imply
either:
- Whether a Grabbed sprite may be dropped below the usable floor. It follows
the raw cursor today, and the user can put the cursor over the Dock.
What needs no decision, because it falls out of the same change: a Dock on the
left or right edge. wall_reached takes the leftmost and rightmost edges from
snapshot.displays, so a usable frame inset on one side makes the Dock's inner
edge the wall, and the sprite climbs that instead of the screen edge. The
menu-bar ceiling fixes itself the same way through ceiling_over. One narrower
rectangle corrects the floor, both walls, and the ceiling at once — which is the
argument for changing the rectangle rather than special-casing the floor.
- What happens when the Dock auto-hides or a work area changes while the sprite
rests on it. The resting y stops being a support, which already drops the
sprite intoFalling— so nothing new is needed, but it should be asserted.
Vocabulary
Whatever the sprite rests on is not a Perch. CONTEXT.md defines a Perch as
a window's top edge, and the Dock's top edge is not one — the floor moved up.
Calling it the floor keeps State::Grounded and the idle animation, and
leaves the Perch definition intact.
Acceptance criteria
- The sprite at rest is fully visible: on a display with a Dock it stops on the
Dock's top edge, not the display's bottom edge. - An auto-hidden Dock gives the space back, and the sprite falls to the true
bottom. - A Dock on the left or right edge is handled, not only the bottom.
- A climb ends below the menu bar rather than behind it.
- A display with no Dock is unchanged.
- The Engine still never sees a window level, and
perch_eligibleis unchanged.
Tests
Floor and ceiling selection are pure and unit tested in crates/core, beside
a_sprite_dropped_at_the_top_of_a_display_falls_past_the_menu_bar, with a
fixture whose usable frame is inset from its hardware frame. A bug in pure logic
earns a test before the fix ships, per docs/SPEC.md.
scripts/verify-overlay.sh currently encodes the present behavior and needs
three changes:
scripts/inspect-window.swiftreports displays fromCGDisplayBoundsonly
and has novisibleFrame, so the harness cannot presently see where the
Dock's top edge is. That is the prerequisite for any new assertion.- The resting check at
:254is an inequality against the display bottom, so it
passes either way and would not notice the fix. It becomes an equality against
the usable bottom. - The mid-run screenshot workaround at
:141goes away, and a crop taken at
rest becomes the proof.
The layer-filter assertions at :81 and :259 stay exactly as they are. They
should keep passing — if a change makes them fail, it is one of the rejected
options above.
Spec: docs/SPEC.md
Activity
omesser commentedon Aug 29, 2026
Overlaps with #4, and the two must agree — cross-referenced there.
#4 changes how physics clamps (the union of display frames rather than their outer bounds). This
issue changes what that rectangle is (the usable frame rather than the hardware frame). Both act
on
snapshot.displays, whichfloor_under,ceiling_overandwall_reachedall derive from.Restrict edge correction to standing states only
Merge main and fix window() test helper