From 8fec0d26e8637a1c96dbcac841417fdd176d480a Mon Sep 17 00:00:00 2001
From: Ariver <shanghai3168@gmail.com>
Date: Sun, 07 Jun 2026 01:28:37 +0800
Subject: [PATCH] docs: add App Store Connect filling guide

---
 Scripts/window_logic_qa.sh |  382 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 files changed, 357 insertions(+), 25 deletions(-)

diff --git a/Scripts/window_logic_qa.sh b/Scripts/window_logic_qa.sh
index f93b3f2..d30af67 100755
--- a/Scripts/window_logic_qa.sh
+++ b/Scripts/window_logic_qa.sh
@@ -97,6 +97,22 @@
   osascript -e 'tell application "System Events" to keystroke space using {option down, shift down}'
 }
 
+send_quick_search_hotkey() {
+  swift - <<'SWIFT' >/dev/null 2>&1
+import CoreGraphics
+import Foundation
+
+let source = CGEventSource(stateID: .hidSystemState)
+let down = CGEvent(keyboardEventSource: source, virtualKey: 49, keyDown: true)!
+down.flags = [.maskSecondaryFn]
+down.post(tap: .cghidEventTap)
+usleep(80_000)
+let up = CGEvent(keyboardEventSource: source, virtualKey: 49, keyDown: false)!
+up.flags = [.maskSecondaryFn]
+up.post(tap: .cghidEventTap)
+SWIFT
+}
+
 send_cmd_comma() {
   osascript -e 'tell application "System Events" to keystroke "," using {command down}'
 }
@@ -278,6 +294,75 @@
   log "PASS Dock tile count: $names"
 }
 
+assert_no_dock_tile() {
+  local output count names
+  output="$(osascript <<'OSA'
+tell application "System Events"
+  tell process "Dock"
+    set tagCount to 0
+    set tagNames to {}
+    repeat with itemRef in UI elements of list 1
+      try
+        set itemName to name of itemRef as text
+        if itemName is "TagLauncher" then
+          set tagCount to tagCount + 1
+          set end of tagNames to itemName
+        end if
+      end try
+    end repeat
+    return (tagCount as text) & "|" & (tagNames as text)
+  end tell
+end tell
+OSA
+)"
+  count="${output%%|*}"
+  names="${output#*|}"
+  if [[ "$count" != "0" ]]; then
+    echo "FAIL: expected no TagLauncher Dock tile, got $count ($names)" >&2
+    return 1
+  fi
+  log "PASS no TagLauncher Dock tile"
+}
+
+click_taglauncher_dock_tile() {
+  local coords x y
+  coords="$(osascript <<'OSA'
+tell application "System Events"
+  tell process "Dock"
+    repeat with itemRef in UI elements of list 1
+      try
+        if (name of itemRef as text) is "TagLauncher" then
+          set itemPosition to position of itemRef
+          set itemSize to size of itemRef
+          set centerX to (item 1 of itemPosition) + ((item 1 of itemSize) / 2)
+          set centerY to (item 2 of itemPosition) + ((item 2 of itemSize) / 2)
+          return (centerX as integer as text) & " " & (centerY as integer as text)
+        end if
+      end try
+    end repeat
+    error "TagLauncher Dock tile not found"
+  end tell
+end tell
+OSA
+)"
+  read -r x y <<<"$coords"
+  click_xy "$x" "$y"
+}
+
+open_overlay_from_dock_with_retry() {
+  local output=""
+  for _ in {1..3}; do
+    click_taglauncher_dock_tile
+    sleep 0.8
+    if output="$(wait_swift_assert overlay 2>&1)"; then
+      printf '%s\n' "$output"
+      return 0
+    fi
+  done
+  printf '%s\n' "$output" >&2
+  return 1
+}
+
 assert_frontmost_taglauncher() {
   local frontmost
   frontmost="$(osascript -e 'tell application "System Events" to get name of first application process whose frontmost is true')"
@@ -381,6 +466,39 @@
     }
 }
 
+func rect(_ window: WindowInfo) -> CGRect {
+    CGRect(
+        x: dimension(window.bounds, "X"),
+        y: dimension(window.bounds, "Y"),
+        width: dimension(window.bounds, "Width"),
+        height: dimension(window.bounds, "Height")
+    )
+}
+
+func isOverlayWindow(_ window: WindowInfo) -> Bool {
+    guard window.name.isEmpty else { return false }
+    let windowFrame = rect(window)
+    return NSScreen.screens.contains { screen in
+        let screenFrame = screen.frame
+        return abs(windowFrame.width - screenFrame.width) <= 12
+            && windowFrame.height >= screenFrame.height * 0.75
+            && abs(windowFrame.midX - screenFrame.midX) <= 12
+    }
+}
+
+func isQuickSearchWindow(_ window: WindowInfo) -> Bool {
+    guard window.name.isEmpty, !isOverlayWindow(window) else { return false }
+    let windowFrame = rect(window)
+    return windowFrame.width >= 500
+        && windowFrame.width <= 900
+        && windowFrame.height >= 120
+        && windowFrame.height <= 850
+}
+
+func isSettingsLikeWindow(_ window: WindowInfo) -> Bool {
+    !window.name.isEmpty
+}
+
 func assertTagLayer(_ tag: [WindowInfo]) {
     for window in tag where window.layer != 23 {
         fail("TagLauncher window has unexpected layer \(window.layer); expected 23")
@@ -395,16 +513,32 @@
 case "overlay":
     guard tag.count == 1 else { fail("overlay expected 1 TagLauncher window, got \(tag.count)") }
     assertTagLayer(tag)
+    guard isOverlayWindow(tag[0]) else { fail("overlay window was not full-screen sized: \(tag[0].bounds)") }
     let menubarLayer = windows.first { $0.owner == "Window Server" && $0.name == "Menubar" }?.layer
     guard menubarLayer == 24 else { fail("menubar layer expected 24, got \(String(describing: menubarLayer))") }
     let dockWindows = windows.filter { $0.owner == "Dock" }
     guard dockWindows.isEmpty else { fail("Dock should be hidden while overlay is visible; found \(dockWindows.count) Dock windows") }
     print("PASS overlay: tagLayer=\(tag[0].layer) menubarLayer=24 dockWindows=0")
 
+case "quick-search":
+    guard tag.count == 2 else { fail("quick search expected overlay plus panel, got \(tag.count)") }
+    assertTagLayer(tag)
+    let overlays = tag.filter(isOverlayWindow)
+    let quickSearch = tag.filter(isQuickSearchWindow)
+    guard overlays.count == 1, quickSearch.count == 1 else {
+        fail("quick search stack wrong: names=\(tag.map(\.name)) bounds=\(tag.map(\.bounds))")
+    }
+    print("PASS quick search stack: tagLayers=\(tag.map(\.layer))")
+
 case "settings":
     guard tag.count == 2 else { fail("settings expected 2 TagLauncher windows, got \(tag.count)") }
     assertTagLayer(tag)
-    guard !tag[0].name.isEmpty, tag[1].name.isEmpty else {
+    let overlays = tag.filter(isOverlayWindow)
+    let settings = tag.filter(isSettingsLikeWindow)
+    guard overlays.count == 1, settings.count == 1 else {
+        fail("settings stack wrong: names=\(tag.map(\.name)) bounds=\(tag.map(\.bounds))")
+    }
+    guard !tag[0].name.isEmpty else {
         fail("settings order wrong: \(tag.map(\.name))")
     }
     print("PASS settings over overlay: order=\(tag.map(\.name))")
@@ -451,26 +585,33 @@
     print("PASS fullscreen target: layer=\(target.layer) bounds=\(target.bounds)")
 
 case "fullscreen-overlay":
-    guard tag.count == 1 else { fail("fullscreen overlay expected 1 TagLauncher window, got \(tag.count)") }
+    guard tag.count == 1 || tag.count == 2 else { fail("fullscreen overlay expected 1 or 2 TagLauncher windows, got \(tag.count)") }
     assertTagLayer(tag)
     guard let target = windows.first(where: { $0.name == "TagLauncherFullscreenQATargetFullscreen" }) else {
         fail("fullscreen target disappeared; TagLauncher likely switched to another Space")
     }
-    let overlayWidth = dimension(tag[0].bounds, "Width")
-    let overlayHeight = dimension(tag[0].bounds, "Height")
-    let overlayMidX = dimension(tag[0].bounds, "X") + overlayWidth / 2
+    guard let overlay = tag.first(where: isOverlayWindow) else {
+        fail("fullscreen overlay TagLauncher window not found: \(tag.map(\.bounds))")
+    }
+    let quickSearch = tag.filter(isQuickSearchWindow)
+    guard quickSearch.count == tag.count - 1 else {
+        fail("fullscreen overlay stack has unexpected windows: \(tag.map(\.bounds))")
+    }
+    let overlayWidth = dimension(overlay.bounds, "Width")
+    let overlayHeight = dimension(overlay.bounds, "Height")
+    let overlayMidX = dimension(overlay.bounds, "X") + overlayWidth / 2
     let targetWidth = dimension(target.bounds, "Width")
     let targetHeight = dimension(target.bounds, "Height")
     let targetMidX = dimension(target.bounds, "X") + targetWidth / 2
     guard abs(overlayWidth - targetWidth) <= 12,
           overlayHeight >= targetHeight * 0.88,
           abs(overlayMidX - targetMidX) <= 12 else {
-        fail("fullscreen overlay is not on the target fullscreen display: overlay=\(tag[0].bounds) target=\(target.bounds)")
+        fail("fullscreen overlay is not on the target fullscreen display: overlay=\(overlay.bounds) target=\(target.bounds)")
     }
-    guard tag[0].layer > target.layer else {
-        fail("TagLauncher layer \(tag[0].layer) is not above fullscreen target layer \(target.layer)")
+    guard tag.allSatisfy({ $0.layer > target.layer }) else {
+        fail("TagLauncher stack is not above fullscreen target")
     }
-    print("PASS fullscreen overlay above target: overlayLayer=\(tag[0].layer) targetLayer=\(target.layer)")
+    print("PASS fullscreen overlay above target: tagLayers=\(tag.map(\.layer)) targetLayer=\(target.layer)")
 
 case "fullscreen-settings":
     guard tag.count == 2 else { fail("fullscreen settings expected 2 TagLauncher windows, got \(tag.count)") }
@@ -478,7 +619,12 @@
     guard let target = windows.first(where: { $0.name == "TagLauncherFullscreenQATargetFullscreen" }) else {
         fail("fullscreen target disappeared after opening settings; TagLauncher likely switched to another Space")
     }
-    guard !tag[0].name.isEmpty, tag[1].name.isEmpty else {
+    let overlays = tag.filter(isOverlayWindow)
+    let settings = tag.filter(isSettingsLikeWindow)
+    guard overlays.count == 1, settings.count == 1 else {
+        fail("fullscreen settings stack wrong: names=\(tag.map(\.name)) bounds=\(tag.map(\.bounds))")
+    }
+    guard !tag[0].name.isEmpty else {
         fail("fullscreen settings order wrong: \(tag.map(\.name))")
     }
     guard tag.allSatisfy({ $0.layer > target.layer }) else {
@@ -634,6 +780,42 @@
     let overlayX = dimension(overlayBounds, "X")
     let overlayY = dimension(overlayBounds, "Y")
     print("\(Int(round(overlayX + 120))) \(Int(round(overlayY + 160)))")
+case "overlay-center":
+    guard let overlay = tag.max(by: { lhs, rhs in
+        let lhsBounds = lhs[kCGWindowBounds as String] as? NSDictionary ?? [:]
+        let rhsBounds = rhs[kCGWindowBounds as String] as? NSDictionary ?? [:]
+        let lhsArea = dimension(lhsBounds, "Width") * dimension(lhsBounds, "Height")
+        let rhsArea = dimension(rhsBounds, "Width") * dimension(rhsBounds, "Height")
+        return lhsArea < rhsArea
+    }), let overlayBounds = overlay[kCGWindowBounds as String] as? NSDictionary else {
+        let screen = NSScreen.screens.first?.frame ?? CGRect(x: 0, y: 0, width: 1200, height: 800)
+        print("\(Int(round(screen.midX))) \(Int(round(screen.midY)))")
+        exit(0)
+    }
+    let overlayX = dimension(overlayBounds, "X")
+    let overlayY = dimension(overlayBounds, "Y")
+    let overlayWidth = dimension(overlayBounds, "Width")
+    let overlayHeight = dimension(overlayBounds, "Height")
+    print("\(Int(round(overlayX + overlayWidth / 2))) \(Int(round(overlayY + overlayHeight / 2)))")
+case "quick-search-result":
+    guard let quickSearch = tag.first(where: { window in
+        let name = (window[kCGWindowName as String] as? String) ?? ""
+        let bounds = window[kCGWindowBounds as String] as? NSDictionary ?? [:]
+        let width = dimension(bounds, "Width")
+        let height = dimension(bounds, "Height")
+        return name.isEmpty
+            && width >= 500
+            && width <= 900
+            && height >= 120
+            && height <= 850
+    }), let bounds = quickSearch[kCGWindowBounds as String] as? NSDictionary else {
+        fputs("FAIL: could not find quick search result-list bounds\n", stderr)
+        exit(1)
+    }
+    let x = dimension(bounds, "X")
+    let y = dimension(bounds, "Y")
+    let width = dimension(bounds, "Width")
+    print("\(Int(round(x + width * 0.35))) \(Int(round(y + 190)))")
 case "fullscreen-target-center":
     guard let target = raw.first(where: { ($0[kCGWindowName as String] as? String) == "TagLauncherFullscreenQATargetFullscreen" }),
           let bounds = target[kCGWindowBounds as String] as? NSDictionary else {
@@ -847,16 +1029,51 @@
   return 1
 }
 
+open_quick_search_with_retry() {
+  local output=""
+  for _ in {1..3}; do
+    send_quick_search_hotkey
+    sleep 0.8
+    if output="$(wait_swift_assert quick-search 2>&1)"; then
+      printf '%s\n' "$output"
+      return 0
+    fi
+  done
+  printf '%s\n' "$output" >&2
+  return 1
+}
+
+open_appgrid_quick_search_with_retry() {
+  local output=""
+  for _ in {1..3}; do
+    send_keycode 49
+    sleep 0.4
+    if output="$(wait_swift_assert quick-search 2>&1)"; then
+      printf '%s\n' "$output"
+      return 0
+    fi
+  done
+  printf '%s\n' "$output" >&2
+  return 1
+}
+
 assert_fullscreen_overlay_stable() {
   local output=""
+  local consecutive_successes=0
   for _ in {1..20}; do
-    if ! output="$(swift "$assert_swift" fullscreen-overlay 2>&1)"; then
-      printf '%s\n' "$output" >&2
-      return 1
+    if output="$(swift "$assert_swift" fullscreen-overlay 2>&1)"; then
+      consecutive_successes=$((consecutive_successes + 1))
+      if [[ "$consecutive_successes" -ge 6 ]]; then
+        printf '%s\n' "$output"
+        return 0
+      fi
+    else
+      consecutive_successes=0
     fi
     sleep 0.1
   done
-  printf '%s\n' "$output"
+  printf '%s\n' "$output" >&2
+  return 1
 }
 
 show_overlay() {
@@ -891,6 +1108,58 @@
   coords="$(swift "$coords_swift" overlay-outside)"
   read -r x y <<<"$coords"
   click_xy "$x" "$y"
+}
+
+hover_quick_search_results() {
+  local coords x y
+  coords="$(quick_search_result_coords_with_retry)"
+  read -r x y <<<"$coords"
+  for offset in 0 8 16 8 0; do
+    move_xy "$x" "$((y + offset))"
+    sleep 0.08
+  done
+}
+
+click_quick_search_result() {
+  local coords x y
+  coords="$(quick_search_result_coords_with_retry)"
+  read -r x y <<<"$coords"
+  click_xy "$x" "$y"
+}
+
+quick_search_result_coords_with_retry() {
+  local output
+  for _ in {1..8}; do
+    if output="$(swift "$coords_swift" quick-search-result 2>&1)"; then
+      printf '%s\n' "$output"
+      return 0
+    fi
+    sleep 0.15
+  done
+  printf '%s\n' "$output" >&2
+  return 1
+}
+
+page_scroll_appgrid() {
+  local coords
+  coords="$(swift "$coords_swift" overlay-center)"
+  read -r x y <<<"$coords"
+  move_xy "$x" "$y"
+  sleep 0.15
+  swift - <<'SWIFT'
+import CoreGraphics
+if let event = CGEvent(
+    scrollWheelEvent2Source: nil,
+    units: .pixel,
+    wheelCount: 1,
+    wheel1: -900,
+    wheel2: 0,
+    wheel3: 0
+) {
+    event.post(tap: .cghidEventTap)
+}
+SWIFT
+  sleep 0.25
 }
 
 kill_fullscreen_qa_target() {
@@ -954,6 +1223,15 @@
 sleep 1.5
 assert_single_qa_app_instance
 assert_single_dock_tile
+swift_assert no-overlay
+for _ in {1..3}; do
+  "$APP_BUNDLE/Contents/MacOS/TagLauncher" >/dev/null 2>&1 &
+  sleep 0.25
+done
+sleep 2.0
+assert_single_qa_app_instance
+assert_single_dock_tile
+swift_assert no-overlay
 for _ in {1..3}; do
   "$APP_BUNDLE/Contents/MacOS/TagLauncher" --hide >/dev/null 2>&1 &
   sleep 0.25
@@ -961,6 +1239,49 @@
 sleep 2.0
 assert_single_qa_app_instance
 assert_single_dock_tile
+swift_assert no-overlay
+log "==> QA Dock reopen: showDockIcon=true opens App Grid from explicit app reopen"
+open_overlay_from_dock_with_retry
+send_keycode 53
+sleep 0.4
+wait_swift_assert no-overlay
+log "==> QA hidden Dock: main hotkey opens App Grid without showing Dock tile"
+defaults write "$DEFAULTS_DOMAIN" showDockIcon -bool false
+prepare_isolated_app_instance
+assert_no_dock_tile
+send_main_hotkey
+sleep 0.8
+wait_swift_assert overlay
+assert_no_dock_tile
+send_keycode 53
+sleep 0.4
+wait_swift_assert no-overlay
+kill_all_taglauncher_instances
+sleep 0.4
+swift_assert no-overlay
+prepare_isolated_app_instance
+assert_no_dock_tile
+log "==> QA hidden Dock: Fn+Space Quick Search hover does not resurrect App Grid"
+open_quick_search_with_retry
+hover_quick_search_results
+sleep 0.8
+wait_swift_assert quick-search
+assert_no_dock_tile
+send_quick_search_hotkey
+sleep 0.8
+wait_swift_assert no-overlay
+assert_no_dock_tile
+kill_all_taglauncher_instances
+sleep 0.4
+swift_assert no-overlay
+prepare_isolated_app_instance
+assert_no_dock_tile
+log "==> QA hidden Dock: clicking Quick Search result closes without showing App Grid"
+open_quick_search_with_retry
+click_quick_search_result
+sleep 1.4
+wait_swift_assert no-overlay
+assert_no_dock_tile
 kill_all_taglauncher_instances
 sleep 0.4
 swift_assert no-overlay
@@ -979,8 +1300,7 @@
   wait_swift_assert fullscreen-overlay
   assert_fullscreen_overlay_stable
   log "==> QA fullscreen Space: quick search from appgrid does not switch Space"
-  send_keycode 49
-  sleep 0.4
+  open_appgrid_quick_search_with_retry
   assert_fullscreen_overlay_stable
   send_keycode 53
   sleep 0.3
@@ -1012,8 +1332,7 @@
 swift_assert overlay
 
 log "==> QA 1/7 and 4/7: settings floats above appgrid and quick search"
-send_keycode 49
-sleep 0.4
+open_appgrid_quick_search_with_retry
 send_cmd_comma
 sleep 0.7
 swift_assert settings
@@ -1026,14 +1345,13 @@
 swift_assert file-panel
 send_keycode 53
 sleep 0.3
-send_cmd_w
+close_settings_window
 sleep 0.9
 swift_assert overlay
 assert_frontmost_taglauncher
 
 log "==> QA 4/7 and 5/7: appgrid-space quick search and double-Esc behavior"
-send_keycode 49
-sleep 0.4
+open_appgrid_quick_search_with_retry
 send_keycode 53
 sleep 0.4
 swift_assert overlay
@@ -1041,10 +1359,23 @@
 sleep 0.4
 swift_assert no-overlay
 
+log "==> QA 4/7: appgrid scroll keeps Space and Esc keyboard routing"
+show_overlay
+for _ in {1..5}; do
+  page_scroll_appgrid
+  open_appgrid_quick_search_with_retry
+  send_keycode 53
+  sleep 0.25
+  swift_assert overlay
+done
+page_scroll_appgrid
+send_keycode 53
+sleep 0.35
+swift_assert no-overlay
+
 log "==> QA 5/7: clicking outside quick search closes search, not appgrid"
 show_overlay
-send_keycode 49
-sleep 0.4
+open_appgrid_quick_search_with_retry
 click_overlay_outside_quick_search
 sleep 0.4
 swift_assert overlay
@@ -1092,8 +1423,9 @@
 SWIFT
   done < <(swift "$screens_swift")
 else
-  rg -Fq 'screenContainingCurrentPointer() ??' "$ROOT_DIR/Apptag/ApptagApp.swift"
-  rg -Fq 'NSMouseInRect(mousePoint, $0.frame, false)' "$ROOT_DIR/Apptag/ApptagApp.swift"
+  rg -Fq 'statusMenuScreenForNextOverlay = overlayController.screenContainingCurrentPointer()' "$ROOT_DIR/Apptag/ApptagApp.swift"
+  rg -Fq 'screenContainingCurrentPointer() ??' "$ROOT_DIR/Apptag/OverlayWindowController.swift"
+  rg -Fq 'NSMouseInRect(mousePoint, $0.frame, false)' "$ROOT_DIR/Apptag/OverlayWindowController.swift"
   log "PASS screen-following static path: single physical display here; code selects NSScreen under current pointer"
 fi
 

--
Gitblit v1.9.3