Skip to content

Keep the harness prop where the sprite can see it - #89

Merged
omesser merged 1 commit into
mainfrom
fix/harness-prop-stays-visible
Aug 30, 2026
Merged

omesser merged 1 commit into
mainfrom
fix/harness-prop-stays-visible

Conversation

@omesser

@omesser omesser commented Aug 30, 2026

Copy link
Copy Markdown
Owner

main fails its own verification harness as of 2de74ec. The fault is in the harness.

What happens

Three frame-loop checks fail, reproducibly:

FAIL  it comes to rest on a real window's top edge  window top y=743
FAIL  the prop window stepped down while the sprite was perched
FAIL  a window that closes drops the sprite within about one poll interval  never dropped

The sprite falls straight past the prop's edge at 743 and lands on the floor.

Why

scripts/perch-window.swift opens its prop as an accessory app's window, calls orderFrontRegardless() once, and never says it again. Anything that takes focus during the run buries it. A window list traced at the tick the sprite passes the edge:

0: x=   0 y= 30 w=1920 h=953   iTerm, maximized
1: x= 760 y=743 w= 400 h=240   the prop

#86 refuses an edge covered by a window in front of it, because a sprite standing there is drawn floating in the middle of a window nobody can see through. iTerm's maximized rect contains every point on that display, so the edge is refused and the sprite falls through.

#86 is right, and the harness was asserting the wrong thing. Opening the prop alone leaves it at index 0 and visible; running open -a iTerm puts it at index 1, and a screencapture of that display shows the prop is then completely gone behind iTerm. So the check was demanding the sprite perch on a window that is not on screen — the exact case #86 exists to prevent.

#88 did not break this. It made app startup slower, so the sprite now reaches the edge after the burial instead of before it. On #86's branch alone the harness was 24/24, which is why neither PR caught it: each was green in isolation, and only the merge result is red.

The fix

The prop re-asserts its position every 50ms, on the main run loop the step schedule already uses. Three lines and a constant.

The interval is chosen against the app's ~10Hz window poll, not the step schedule: a burial then cannot span a whole tick. That bound is what matters — one tick reading the prop as buried unperches a resting sprite, and once it has fallen a few points the edge is above it and it never re-perches. At 100ms or more a burial would be visible to a poll about half the time.

Measured, sampling the prop's layer-0 index every 20ms across an open -a iTerm:

result
this branch index 0 → buried 32ms → index 0, front for the remaining 11s
2de74ec index 0 → index 1, never returns

The level argument is untouched, so the level-20 pose that a window above the application level is not a Perch depends on still works.

Verify

./scripts/verify-overlay.sh — all checks pass, twice in a row, on the merged main this branch sits on.

cargo test --workspace 156 + 18, clippy -D warnings and cargo fmt --all --check clean. Only a Swift file changed.

One hole left open

The frame-loop checks never assert the prop was actually frontmost when the sprite landed; they infer a perch from the traced position matching the prop's y. That is the hole this bug fell into, and it is why the harness passed for months while asserting something it could not see. Filed rather than fixed here, because it changes the harness's contract rather than repairing the reported fault.

🤖 Generated with Claude Code

An accessory app's window is buried by anything that activates, and a
covered top edge is not a Perch (#86), so the sprite fell through the prop
the frame-loop checks were about to assert on. Re-assert the window's place
at 20Hz, faster than the app's ~10Hz window poll.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@omesser
omesser force-pushed the fix/harness-prop-stays-visible branch from 691a3ba to 4e4352a Compare August 30, 2026 13:24
@omesser
omesser merged commit c5a10d1 into main Aug 30, 2026
2 checks passed
@omesser
omesser deleted the fix/harness-prop-stays-visible branch September 4, 2026 01:48
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.

1 participant