From a3d82000231b8a8e3709e1a6708dbbdaf81412dc Mon Sep 17 00:00:00 2001
From: Ariver <shanghai3168@gmail.com>
Date: Sat, 20 Jun 2026 12:32:28 +0800
Subject: [PATCH] Add progressive window shortcut filtering

---
 C3.tools/round1-horizontal-waterfall-fixture-qa.sh |  295 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 291 insertions(+), 4 deletions(-)

diff --git a/C3.tools/round1-horizontal-waterfall-fixture-qa.sh b/C3.tools/round1-horizontal-waterfall-fixture-qa.sh
index 05361bb..c25b508 100755
--- a/C3.tools/round1-horizontal-waterfall-fixture-qa.sh
+++ b/C3.tools/round1-horizontal-waterfall-fixture-qa.sh
@@ -11,19 +11,33 @@
 # shellcheck source=build-output-paths.sh
 source "$SCRIPT_DIR/build-output-paths.sh"
 APP="$BUILD_CURRENT_APP"
+DOMAIN="com.ar.Aligner"
+THEME_KEY="com.ar.Aligner.preferences.appearance.theme"
 LAYOUT_REPORT="$BUILD_REPORT_ROOT/round01-horizontal-waterfall-layout-report.json"
 KEYBOARD_REPORT="$BUILD_REPORT_ROOT/round01-horizontal-waterfall-keyboard-report.json"
 APP_ENTER_REPORT="$BUILD_REPORT_ROOT/round01-horizontal-waterfall-app-enter-report.json"
+LETTER_INDEX_REPORT="$BUILD_REPORT_ROOT/round01-horizontal-waterfall-letter-index-report.json"
+WINDOW_SHORTCUT_REPORT="$BUILD_REPORT_ROOT/round01-horizontal-waterfall-window-shortcut-report.json"
+OVERFLOW_APP_REPORT="$BUILD_REPORT_ROOT/round01-horizontal-waterfall-window-shortcut-overflow-app-report.json"
+OVERFLOW_WINDOW_REPORT="$BUILD_REPORT_ROOT/round01-horizontal-waterfall-window-shortcut-overflow-window-report.json"
 ARROW_WRAP_REPORT="$BUILD_REPORT_ROOT/round01-horizontal-waterfall-arrow-wrap-report.json"
 FILTER_REPORT="$BUILD_REPORT_ROOT/round01-horizontal-waterfall-filter-report.json"
 FIXTURE_APP_COUNT="${ALIGNER_ROUND1_HORIZONTAL_WATERFALL_FIXTURE_APP_COUNT:-8}"
 FIXTURE_WINDOWS_PER_APP="${ALIGNER_ROUND1_HORIZONTAL_WATERFALL_FIXTURE_WINDOWS_PER_APP:-6}"
 HOVER_APP_INDEX="${ALIGNER_ROUND1_HORIZONTAL_WATERFALL_HOVER_APP_INDEX:-7}"
 KEY_SEQUENCE="${ALIGNER_ROUND1_HORIZONTAL_WATERFALL_KEY_SEQUENCE:-tab}"
-APP_ENTER_KEY_SEQUENCE="${ALIGNER_ROUND1_HORIZONTAL_WATERFALL_APP_ENTER_KEY_SEQUENCE:-app:3,enter}"
+APP_ENTER_KEY_SEQUENCE="${ALIGNER_ROUND1_HORIZONTAL_WATERFALL_APP_ENTER_KEY_SEQUENCE:-physical-index:3,enter}"
 APP_ENTER_TARGET_APP_INDEX="${ALIGNER_ROUND1_HORIZONTAL_WATERFALL_APP_ENTER_TARGET_APP_INDEX:-2}"
+LETTER_INDEX_FIXTURE_APP_COUNT="${ALIGNER_ROUND1_HORIZONTAL_WATERFALL_LETTER_INDEX_FIXTURE_APP_COUNT:-12}"
+LETTER_INDEX_KEY_SEQUENCE="${ALIGNER_ROUND1_HORIZONTAL_WATERFALL_LETTER_INDEX_KEY_SEQUENCE:-physical-index:A}"
+LETTER_INDEX_TARGET_APP_INDEX="${ALIGNER_ROUND1_HORIZONTAL_WATERFALL_LETTER_INDEX_TARGET_APP_INDEX:-10}"
+WINDOW_SHORTCUT_KEY_SEQUENCE="${ALIGNER_ROUND1_HORIZONTAL_WATERFALL_WINDOW_SHORTCUT_KEY_SEQUENCE:-physical-index:3,physical-index:6}"
+WINDOW_SHORTCUT_TARGET_APP_INDEX="${ALIGNER_ROUND1_HORIZONTAL_WATERFALL_WINDOW_SHORTCUT_TARGET_APP_INDEX:-2}"
+WINDOW_SHORTCUT_TARGET_WINDOW_INDEX="${ALIGNER_ROUND1_HORIZONTAL_WATERFALL_WINDOW_SHORTCUT_TARGET_WINDOW_INDEX:-5}"
 ARROW_WRAP_KEY_SEQUENCE="${ALIGNER_ROUND1_HORIZONTAL_WATERFALL_ARROW_WRAP_KEY_SEQUENCE:-app:1,down,up,left,down,enter}"
 REPORT_WAIT="${ALIGNER_ROUND1_HORIZONTAL_WATERFALL_REPORT_WAIT:-6.0}"
+OLD_THEME_SET=0
+OLD_THEME=""
 
 fail() {
   echo "Round01.1 horizontal Waterfall fixture QA failed: $*" >&2
@@ -49,6 +63,23 @@
   done
 
   fail "current Aligner app did not exit before QA"
+}
+
+preserve_user_theme() {
+  if OLD_THEME="$(/usr/bin/defaults read "$DOMAIN" "$THEME_KEY" 2>/dev/null)"; then
+    OLD_THEME_SET=1
+  else
+    OLD_THEME_SET=0
+    OLD_THEME=""
+  fi
+}
+
+restore_user_theme() {
+  if [ "$OLD_THEME_SET" -eq 1 ]; then
+    /usr/bin/defaults write "$DOMAIN" "$THEME_KEY" -string "$OLD_THEME"
+  else
+    /usr/bin/defaults delete "$DOMAIN" "$THEME_KEY" >/dev/null 2>&1 || true
+  fi
 }
 
 wait_for_loaded_report() {
@@ -267,11 +298,31 @@
 import sys
 
 path = sys.argv[1]
-key_sequence = [part for part in sys.argv[2].split(",") if part]
+raw_key_sequence = [part for part in sys.argv[2].split(",") if part]
 target_app_index = int(sys.argv[3])
 
 with open(path, "r", encoding="utf-8") as file:
     report = json.load(file)
+
+def normalize_key_sequence(sequence):
+    normalized = []
+    physical_symbols = []
+    for part in sequence:
+        lowered = part.lower()
+        matched_prefix = None
+        for prefix in ("physical-index:", "physical-index-", "keydown:", "keydown-"):
+            if lowered.startswith(prefix):
+                matched_prefix = prefix
+                break
+        if matched_prefix is None:
+            normalized.append(part)
+            continue
+        symbol = part[len(matched_prefix):].strip().upper()
+        physical_symbols.append(symbol)
+        normalized.append(f"app:{symbol}")
+    return normalized, physical_symbols
+
+key_sequence, physical_symbols = normalize_key_sequence(raw_key_sequence)
 
 def require(condition, message):
     if not condition:
@@ -284,6 +335,9 @@
 require(report.get("snapshotLoaded") is True, "snapshotLoaded must be true")
 require(root.get("waterfallViewMode") == "horizontalMasonry", "App Enter run must use horizontalMasonry")
 require(root.get("keyboardCommandsApplied") == key_sequence, "App Enter keyboard commands must be applied")
+require(root.get("appShelfIndexKeyDownCount") == len(physical_symbols), "physical App index keyDown path must be exercised")
+if physical_symbols:
+    require(root.get("lastAppShelfIndexKeySymbol") == physical_symbols[-1], "last physical App index symbol must be reported")
 require(target_app_index < len(columns), "target App index must exist")
 target_card = columns[target_app_index].get("cards", [])[0]
 require(root.get("hoverTargetKind") == "app", "App index focus must leave hover target on the App icon")
@@ -305,6 +359,188 @@
     "hoverTargetKind": root.get("hoverTargetKind"),
     "targetAppGroupIndex": target_app_index,
     "lastCommittedWindowID": root.get("lastCommittedWindowID")
+}, indent=2, ensure_ascii=False))
+PY
+}
+
+assert_letter_index_report() {
+  /usr/bin/python3 - "$LETTER_INDEX_REPORT" "$LETTER_INDEX_KEY_SEQUENCE" "$LETTER_INDEX_TARGET_APP_INDEX" <<'PY'
+import json
+import sys
+
+path = sys.argv[1]
+raw_key_sequence = [part for part in sys.argv[2].split(",") if part]
+target_app_index = int(sys.argv[3])
+
+with open(path, "r", encoding="utf-8") as file:
+    report = json.load(file)
+
+def require(condition, message):
+    if not condition:
+        print(message, file=sys.stderr)
+        print(json.dumps(report, indent=2, ensure_ascii=False), file=sys.stderr)
+        sys.exit(1)
+
+def normalize_key_sequence(sequence):
+    normalized = []
+    physical_symbols = []
+    for part in sequence:
+        lowered = part.lower()
+        matched_prefix = None
+        for prefix in ("physical-index:", "physical-index-", "keydown:", "keydown-"):
+            if lowered.startswith(prefix):
+                matched_prefix = prefix
+                break
+        if matched_prefix is None:
+            normalized.append(part)
+            continue
+        symbol = part[len(matched_prefix):].strip().upper()
+        physical_symbols.append(symbol)
+        normalized.append(f"app:{symbol}")
+    return normalized, physical_symbols
+
+key_sequence, physical_symbols = normalize_key_sequence(raw_key_sequence)
+root = report.get("rootView", {})
+columns = root.get("waterfallColumns", [])
+require(report.get("snapshotLoaded") is True, "snapshotLoaded must be true")
+require(root.get("waterfallViewMode") == "horizontalMasonry", "letter App index run must use horizontalMasonry")
+require(root.get("keyboardCommandsApplied") == key_sequence, "letter App index keyboard commands must be applied")
+require(root.get("appShelfIndexKeyDownCount") == len(physical_symbols), "letter App index must exercise physical keyDown path")
+require(physical_symbols, "letter App index test must contain a physical key")
+require(root.get("lastAppShelfIndexKeySymbol") == physical_symbols[-1], "last letter App index symbol must be reported")
+require(target_app_index < len(columns), "target letter App index must exist")
+target_card = columns[target_app_index].get("cards", [])[0]
+require(root.get("hoverTargetKind") == "app", "letter App index focus must leave hover target on App icon")
+require(root.get("hoverTargetSource") == "keyboard", "letter App index focus must report keyboard source")
+require(root.get("keyboardFocusedAppGroupIndex") == target_app_index, "letter App index must focus the expected App")
+require(root.get("keyboardFocusedWindowID") is None, "letter App icon focus must not keep stale window keyboard focus")
+require(root.get("selectedAppGroupIndex") == target_app_index, "letter App icon focus must select the target App")
+require(root.get("selectedWindowIndex") == 0, "letter App icon focus must select the first window")
+require(root.get("horizontalAppDefaultWindowID") == target_card.get("windowID"), "letter App default window must match the first card")
+require(root.get("lastCommittedWindowID") is None, "letter App index focus without Enter must not commit")
+require(root.get("lastCommitSource") is None, "letter App index focus without Enter must not report commit source")
+require(target_card.get("isHorizontalAppDefault") is True, "letter target first card must report app default state")
+require("appDefault" in target_card.get("visualStates", []), "letter target first card must expose appDefault visual state")
+require("selected" in target_card.get("visualStates", []), "letter target first card must expose selected visual state")
+
+print(json.dumps({
+    "commands": root.get("keyboardCommandsApplied"),
+    "physicalKeyDownCount": root.get("appShelfIndexKeyDownCount"),
+    "lastSymbol": root.get("lastAppShelfIndexKeySymbol"),
+    "targetAppGroupIndex": target_app_index,
+    "defaultWindowID": root.get("horizontalAppDefaultWindowID")
+}, indent=2, ensure_ascii=False))
+PY
+}
+
+assert_window_shortcut_report() {
+  /usr/bin/python3 - "$WINDOW_SHORTCUT_REPORT" "$WINDOW_SHORTCUT_KEY_SEQUENCE" "$WINDOW_SHORTCUT_TARGET_APP_INDEX" "$WINDOW_SHORTCUT_TARGET_WINDOW_INDEX" <<'PY'
+import json
+import sys
+
+path = sys.argv[1]
+raw_key_sequence = [part for part in sys.argv[2].split(",") if part]
+target_app_index = int(sys.argv[3])
+target_window_index = int(sys.argv[4])
+
+with open(path, "r", encoding="utf-8") as file:
+    report = json.load(file)
+
+def require(condition, message):
+    if not condition:
+        print(message, file=sys.stderr)
+        print(json.dumps(report, indent=2, ensure_ascii=False), file=sys.stderr)
+        sys.exit(1)
+
+def physical_symbol(part):
+    lowered = part.lower()
+    for prefix in ("physical-index:", "physical-index-", "keydown:", "keydown-"):
+        if lowered.startswith(prefix):
+            return part[len(prefix):].strip().upper()
+    return None
+
+physical_symbols = [symbol for part in raw_key_sequence if (symbol := physical_symbol(part))]
+require(len(physical_symbols) == 2, "window shortcut test must use two physical symbols")
+expected_code = "".join(physical_symbols)
+expected_sequence = [f"app:{physical_symbols[0]}", f"window:{expected_code}"]
+
+root = report.get("rootView", {})
+columns = root.get("waterfallColumns", [])
+require(report.get("snapshotLoaded") is True, "snapshotLoaded must be true")
+require(root.get("waterfallViewMode") == "horizontalMasonry", "window shortcut run must use horizontalMasonry")
+require(root.get("keyboardCommandsApplied") == expected_sequence, "two-key window shortcut commands must be applied")
+require(root.get("appShelfIndexKeyDownCount") == 2, "two-key window shortcut must exercise two physical keyDown events")
+require(root.get("lastAppShelfIndexKeySymbol") == physical_symbols[-1], "last physical symbol must be the window index key")
+require(root.get("lastWindowIndexKeyCommand") == f"window:{expected_code}", "last window shortcut command must be reported")
+require(root.get("lastWindowIndexKeyCommitCode") == expected_code, "last window shortcut commit code must be reported")
+require(root.get("windowIndexKeyPendingAppGroupIndex") is None, "two-key commit must clear pending App")
+require(root.get("windowIndexKeyPendingAppSymbol") is None, "two-key commit must clear pending App symbol")
+require(target_app_index < len(columns), "target App index must exist")
+target_column = columns[target_app_index]
+cards = target_column.get("cards", [])
+require(target_window_index < len(cards), "target window index must exist")
+target_card = cards[target_window_index]
+require(target_card.get("windowShortcutCode") == expected_code, "target card must expose the expected two-character shortcut code")
+require(target_card.get("primarySpaceLabel") != target_card.get("windowShortcutCode"), "shortcut code must replace the old Space label in the UI meta slot")
+require(root.get("lastCommittedAppGroupIndex") == target_app_index, "two-key shortcut must commit target App")
+require(root.get("lastCommittedWindowIndex") == target_window_index, "two-key shortcut must commit target window")
+require(root.get("lastCommittedWindowID") == target_card.get("windowID"), "two-key shortcut must commit target window ID")
+require(root.get("lastCommitSource") == "keyboard", "two-key shortcut commit must be keyboard sourced")
+require(root.get("selectedAppGroupIndex") == target_app_index, "two-key shortcut must select target App")
+require(root.get("selectedWindowIndex") == target_window_index, "two-key shortcut must select target window")
+require(root.get("selectedWindowID") == target_card.get("windowID"), "two-key shortcut selection ID must match target window")
+
+for column in columns:
+    for card in column.get("cards", []):
+        code = card.get("windowShortcutCode")
+        require(code != "No Space" and code != "N...", "window shortcut code must not expose the old No Space label")
+
+print(json.dumps({
+    "commands": root.get("keyboardCommandsApplied"),
+    "code": expected_code,
+    "lastCommittedWindowID": root.get("lastCommittedWindowID")
+}, indent=2, ensure_ascii=False))
+PY
+}
+
+assert_window_shortcut_overflow_report() {
+  /usr/bin/python3 - "$OVERFLOW_APP_REPORT" "$OVERFLOW_WINDOW_REPORT" <<'PY'
+import json
+import sys
+
+app_path = sys.argv[1]
+window_path = sys.argv[2]
+
+with open(app_path, "r", encoding="utf-8") as file:
+    app_report = json.load(file)
+with open(window_path, "r", encoding="utf-8") as file:
+    window_report = json.load(file)
+
+def require(report, condition, message):
+    if not condition:
+        print(message, file=sys.stderr)
+        print(json.dumps(report, indent=2, ensure_ascii=False), file=sys.stderr)
+        sys.exit(1)
+
+app_root = app_report.get("rootView", {})
+app_columns = app_root.get("waterfallColumns", [])
+require(app_report, app_report.get("snapshotLoaded") is True, "App overflow report must be loaded")
+require(app_report, len(app_columns) == 37, "App overflow fixture must expose 37 columns")
+require(app_report, app_columns[35].get("cards", [])[0].get("windowShortcutCode") == "Z1", "36th App must still expose a shortcut code")
+require(app_report, app_columns[36].get("cards", [])[0].get("windowShortcutCode") == "", "37th App must not expose a two-key shortcut code")
+
+window_root = window_report.get("rootView", {})
+window_columns = window_root.get("waterfallColumns", [])
+require(window_report, window_report.get("snapshotLoaded") is True, "Window overflow report must be loaded")
+require(window_report, len(window_columns) == 1, "Window overflow fixture must expose one column")
+cards = window_columns[0].get("cards", [])
+require(window_report, len(cards) == 37, "Window overflow fixture must expose 37 windows")
+require(window_report, cards[35].get("windowShortcutCode") == "1Z", "36th window must still expose a shortcut code")
+require(window_report, cards[36].get("windowShortcutCode") == "", "37th window must not expose a two-key shortcut code")
+
+print(json.dumps({
+    "appOverflowCode": app_columns[36].get("cards", [])[0].get("windowShortcutCode"),
+    "windowOverflowCode": cards[36].get("windowShortcutCode")
 }, indent=2, ensure_ascii=False))
 PY
 }
@@ -406,12 +642,29 @@
   local report="$1"
   shift
 
+  run_fixture_with_app_count "$report" "$FIXTURE_APP_COUNT" "$@"
+}
+
+run_fixture_with_app_count() {
+  local report="$1"
+  local app_count="$2"
+  shift 2
+
+  run_fixture_with_shape "$report" "$app_count" "$FIXTURE_WINDOWS_PER_APP" "$@"
+}
+
+run_fixture_with_shape() {
+  local report="$1"
+  local app_count="$2"
+  local windows_per_app="$3"
+  shift 3
+
   rm -f "$report"
   "$APP/Contents/MacOS/Aligner" \
     --round0-skip-permissions \
     --round01-open-quick-switch \
-    --round01-fixture-app-count="$FIXTURE_APP_COUNT" \
-    --round01-fixture-windows-per-app="$FIXTURE_WINDOWS_PER_APP" \
+    --round01-fixture-app-count="$app_count" \
+    --round01-fixture-windows-per-app="$windows_per_app" \
     --round01-disable-screenshot-refresh \
     --round01-waterfall-view-mode=horizontal \
     --round01-quick-switch-report="$report" \
@@ -439,6 +692,9 @@
 if [ "$FIXTURE_APP_COUNT" -le "$HOVER_APP_INDEX" ]; then
   fail "hover App index must be inside fixture app count"
 fi
+if [ "$LETTER_INDEX_FIXTURE_APP_COUNT" -le "$LETTER_INDEX_TARGET_APP_INDEX" ]; then
+  fail "letter index target App must be inside letter fixture app count"
+fi
 if [ "$FIXTURE_WINDOWS_PER_APP" -lt 2 ]; then
   fail "fixture must include at least two windows per App for Tab navigation"
 fi
@@ -453,8 +709,11 @@
     wait "$APP_PID" 2>/dev/null || true
   fi
   stop_current_aligner
+  restore_user_theme
 }
 trap cleanup EXIT
+preserve_user_theme
+/usr/bin/defaults write "$DOMAIN" "$THEME_KEY" -string "light"
 
 run_fixture "$LAYOUT_REPORT" --round01-debug-mouse-sequence="hover-app:$HOVER_APP_INDEX"
 wait_for_loaded_report "$LAYOUT_REPORT"
@@ -477,6 +736,33 @@
 wait "$APP_PID" 2>/dev/null || true
 stop_current_aligner
 
+run_fixture_with_app_count "$LETTER_INDEX_REPORT" "$LETTER_INDEX_FIXTURE_APP_COUNT" --round01-debug-key-sequence="$LETTER_INDEX_KEY_SEQUENCE"
+wait_for_loaded_report "$LETTER_INDEX_REPORT"
+assert_letter_index_report
+kill "$APP_PID" 2>/dev/null || true
+wait "$APP_PID" 2>/dev/null || true
+stop_current_aligner
+
+run_fixture "$WINDOW_SHORTCUT_REPORT" --round01-debug-key-sequence="$WINDOW_SHORTCUT_KEY_SEQUENCE"
+wait_for_loaded_report "$WINDOW_SHORTCUT_REPORT"
+assert_window_shortcut_report
+kill "$APP_PID" 2>/dev/null || true
+wait "$APP_PID" 2>/dev/null || true
+stop_current_aligner
+
+run_fixture_with_shape "$OVERFLOW_APP_REPORT" 37 1
+wait_for_loaded_report "$OVERFLOW_APP_REPORT"
+kill "$APP_PID" 2>/dev/null || true
+wait "$APP_PID" 2>/dev/null || true
+stop_current_aligner
+
+run_fixture_with_shape "$OVERFLOW_WINDOW_REPORT" 1 37
+wait_for_loaded_report "$OVERFLOW_WINDOW_REPORT"
+assert_window_shortcut_overflow_report
+kill "$APP_PID" 2>/dev/null || true
+wait "$APP_PID" 2>/dev/null || true
+stop_current_aligner
+
 run_fixture "$ARROW_WRAP_REPORT" --round01-debug-key-sequence="$ARROW_WRAP_KEY_SEQUENCE"
 wait_for_loaded_report "$ARROW_WRAP_REPORT"
 assert_arrow_wrap_report
@@ -492,4 +778,5 @@
 
 trap - EXIT
 stop_current_aligner
+restore_user_theme
 echo "Round01.1 horizontal Waterfall fixture QA passed"

--
Gitblit v1.9.3