Skip to content

automatic-focus.md

Latest commit

 

History

History
23 lines (16 loc) · 2.87 KB

automatic-focus.md

File metadata and controls

23 lines (16 loc) · 2.87 KB
Raw

Automatic focus implementation

Window snapshots preserve front-to-back CGWindowList order and owner PID before the capture overlays appear. Hit tests target the underlying application explicitly, so the capture overlay does not become the focused component. AX results are converted from top-left display coordinates into Cocoa global coordinates, clipped to the captured window and current display, and arranged from the hit element to its containing regions.

Queries run on a serial actor with per-element messaging timeouts and bounded ancestor traversal. Mouse movement debounces requests by 45 ms. Generation checks, task cancellation, visibility, and selection-state checks reject obsolete results. No AX actions or target application content are modified.

Apple API references:

Manual acceptance checks (requires granting Accessibility to the built Snapok app):

  1. Start capture over a native application. Move between toolbar buttons, content, and sidebar: the highlighted bounds should follow the accessible component.
  2. Scroll up through parent regions to the window; scroll down to return. Hold Option to force the full window, release to resume component detection.
  3. Click to lock a region; subsequent movement must not change it. Drag from the initial preview to create a custom selection. Right-click to reselect.
  4. Move between overlapping applications and displays (including displays left/above the primary display); no stale result may replace the current preview.
  5. Without permission, or on unsupported/custom-drawn content, whole-window selection and manual dragging remain usable.
  6. Cancel while a slow app is being queried; no delayed selection may appear after cancelling or in a subsequent capture.

Automated geometry checks: run ./scripts/test-focus.sh. This uses a standalone Swift test executable and does not require XCTest or a full Xcode installation.

System UI targets include the menu bar, status items, and the visible Dock. Menu-bar hit tests use the application that was frontmost before capture. Status items keep the full bar as their parent selection. Dock geometry comes from its AXList rather than the potentially full-screen compositor window. Hidden/offscreen Dock strips and desktop/wallpaper surfaces are rejected. Dock geometry on macOS versions exposing a full-screen compositor surface requires Accessibility permission.

Additional checks: hover Dock icons and menu/status items, scroll to select their entire container, and hold Option for the whole Dock/menu bar. Check bottom/left/right Dock placement and secondary displays. ./scripts/test-focus.sh --live inspects visible system targets and AX components (requires a visible Dock and Accessibility permission).