Skip to content

The sprite comes to rest behind the Dock, not on it #39

Closed

Description

@omesser

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, and main.rs already enumerates monitors and reads
    position()/size()/scale_factor(). Windows gets SPI_GETWORKAREA
    through the same field, so the taskbar is handled when Windows lands rather
    than needing its own concept.

Alternatives, and why not:

  1. Dock as a Perch — impossible on the reported geometry, as above.
  2. Dock as the floor, read from the window list — same missing input.
  3. Clamp the floor in the Engine — smallest diff, but the Engine would have
    to be told about screen furniture, and docs/SPEC.md keeps 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 into Falling — 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_eligible is 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.swift reports displays from CGDisplayBounds only
    and has no visibleFrame, 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 :254 is 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 :141 goes 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

  1. omesser commented on Aug 29, 2026

    @omesser
    OwnerAuthor

    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, which floor_under, ceiling_over and wall_reached all derive from.

  2. added this to the V1 milestone on Sep 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions