From 6f2856fa70722dad7f7c69a3addaa05ea9fd6e94 Mon Sep 17 00:00:00 2001
From: Ariver <shanghai3168@gmail.com>
Date: Fri, 19 Jun 2026 22:36:43 +0800
Subject: [PATCH] Add two-key window shortcut codes
---
C3.tools/round1-screenshot-session-qa.sh | 48 ++++-
C3.tools/round1-vertical-keyboard-app-focus-fixture-qa.sh | 148 ++++++++++++++++
C3.tools/round1-horizontal-waterfall-fixture-qa.sh | 149 ++++++++++++++++
C1.source/Sources/Aligner/QuickSwitchRootView.swift | 180 +++++++++++++++++++
C1.source/Resources/Aligner-Info.plist | 4
5 files changed, 511 insertions(+), 18 deletions(-)
diff --git a/C1.source/Resources/Aligner-Info.plist b/C1.source/Resources/Aligner-Info.plist
index 281756c..3eafe28 100644
--- a/C1.source/Resources/Aligner-Info.plist
+++ b/C1.source/Resources/Aligner-Info.plist
@@ -17,9 +17,9 @@
<key>CFBundlePackageType</key>
<string>APPL</string>
<key>CFBundleShortVersionString</key>
- <string>0.0.76</string>
+ <string>0.0.77</string>
<key>CFBundleVersion</key>
- <string>20260619.1947</string>
+ <string>20260619.2234</string>
<key>LSMinimumSystemVersion</key>
<string>26.0</string>
<key>NSHighResolutionCapable</key>
diff --git a/C1.source/Sources/Aligner/QuickSwitchRootView.swift b/C1.source/Sources/Aligner/QuickSwitchRootView.swift
index 99608f9..5fff479 100644
--- a/C1.source/Sources/Aligner/QuickSwitchRootView.swift
+++ b/C1.source/Sources/Aligner/QuickSwitchRootView.swift
@@ -11,6 +11,7 @@
@MainActor
final class QuickSwitchRootView: NSView {
private static let appShelfIndexSymbols = Array("1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ").map(String.init)
+ private static let windowIndexKeyPendingInterval: CFTimeInterval = 0.8
private static let appShelfIndexKeyCodes: [String: UInt16] = [
"1": 18, "2": 19, "3": 20, "4": 21, "5": 23,
"6": 22, "7": 26, "8": 28, "9": 25, "0": 29,
@@ -85,6 +86,10 @@
private var lastKeyboardAppIndexCommand: String?
private var appShelfIndexKeyDownCount = 0
private var lastAppShelfIndexKeySymbol: String?
+ private var windowIndexKeyPending: WindowIndexKeyPending?
+ private var windowIndexKeyPendingClearTask: Task<Void, Never>?
+ private var lastWindowIndexKeyCommand: String?
+ private var lastWindowIndexKeyCommitCode: String?
private var lastBoundaryBounceAxis: String?
private var lastBoundaryBounceDirection: String?
private var boundaryBounceCount = 0
@@ -324,6 +329,12 @@
let closeButton: CloseButtonLayers
}
+ private struct WindowIndexKeyPending {
+ let appSymbol: String
+ let appGroupIndex: Int
+ let startedAt: CFTimeInterval
+ }
+
private struct ProjectionLayerSnapshot {
let layer: CALayer
let frame: CGRect
@@ -505,6 +516,7 @@
}
override func scrollWheel(with event: NSEvent) {
+ clearWindowIndexKeyPending()
refreshHoverTarget(at: event.locationInWindow)
let dominantDelta = abs(event.scrollingDeltaX) >= abs(event.scrollingDeltaY)
@@ -560,6 +572,7 @@
override func mouseMoved(with event: NSEvent) {
guard debugHoveredAppGroupIndex == nil else { return }
+ clearWindowIndexKeyPending()
let toggleHovered = viewModeToggleButtonContains(windowLocation: event.locationInWindow)
if !toggleHovered {
@@ -586,6 +599,7 @@
override func mouseExited(with event: NSEvent) {
guard debugHoveredAppGroupIndex == nil else { return }
+ clearWindowIndexKeyPending()
isViewModeToggleButtonHovered = false
suppressViewModeToggleHoverPreview = false
hoveredCloseTarget = nil
@@ -601,6 +615,7 @@
])
return
}
+ clearWindowIndexKeyPending()
if handleCloseConfirmationMouseDown(at: event.locationInWindow) {
return
@@ -920,6 +935,11 @@
keyboardCommandsApplied = []
lastKeyboardCommand = nil
lastKeyboardAppIndexCommand = nil
+ appShelfIndexKeyDownCount = 0
+ lastAppShelfIndexKeySymbol = nil
+ clearWindowIndexKeyPending()
+ lastWindowIndexKeyCommand = nil
+ lastWindowIndexKeyCommitCode = nil
lastBoundaryBounceAxis = nil
lastBoundaryBounceDirection = nil
boundaryBounceCount = 0
@@ -1350,6 +1370,10 @@
"lastKeyboardAppIndexCommand": lastKeyboardAppIndexCommand ?? NSNull(),
"appShelfIndexKeyDownCount": appShelfIndexKeyDownCount,
"lastAppShelfIndexKeySymbol": lastAppShelfIndexKeySymbol ?? NSNull(),
+ "windowIndexKeyPendingAppGroupIndex": windowIndexKeyPending?.appGroupIndex ?? NSNull(),
+ "windowIndexKeyPendingAppSymbol": windowIndexKeyPending?.appSymbol ?? NSNull(),
+ "lastWindowIndexKeyCommand": lastWindowIndexKeyCommand ?? NSNull(),
+ "lastWindowIndexKeyCommitCode": lastWindowIndexKeyCommitCode ?? NSNull(),
"lastBoundaryBounceAxis": lastBoundaryBounceAxis ?? NSNull(),
"lastBoundaryBounceDirection": lastBoundaryBounceDirection ?? NSNull(),
"boundaryBounceCount": boundaryBounceCount,
@@ -1429,6 +1453,7 @@
if let indexSymbol = appShelfIndexSymbol(fromKeyboardCommand: command) {
let recordedCommand = "app:\(indexSymbol)"
recordKeyboardCommand(recordedCommand)
+ clearWindowIndexKeyPending()
if !focusAppShelfItemForKeyboard(indexSymbol: indexSymbol, commandLabel: recordedCommand) {
selectionChangedByLastCommand = false
}
@@ -1437,6 +1462,7 @@
switch command {
case "left":
+ clearWindowIndexKeyPending()
recordKeyboardCommand("left")
if isHorizontalMasonryMode {
moveSelection(.left)
@@ -1444,6 +1470,7 @@
selectionChangedByLastCommand = false
}
case "right":
+ clearWindowIndexKeyPending()
recordKeyboardCommand("right")
if isHorizontalMasonryMode {
moveSelection(.right)
@@ -1451,6 +1478,7 @@
selectionChangedByLastCommand = false
}
case "up":
+ clearWindowIndexKeyPending()
recordKeyboardCommand("up")
if isHorizontalMasonryMode {
moveSelection(.up)
@@ -1458,6 +1486,7 @@
moveVerticalSelectionWithinFocusedColumn(.up)
}
case "down":
+ clearWindowIndexKeyPending()
recordKeyboardCommand("down")
if isHorizontalMasonryMode {
moveSelection(.down)
@@ -1465,10 +1494,12 @@
moveVerticalSelectionWithinFocusedColumn(.down)
}
case "enter", "return", "commit":
+ clearWindowIndexKeyPending()
recordKeyboardCommand("enter")
selectionChangedByLastCommand = false
commitCurrentSelection()
case "tab":
+ clearWindowIndexKeyPending()
if isHorizontalMasonryMode {
recordKeyboardCommand("tab")
moveHorizontalMasonryTabSelection()
@@ -1478,6 +1509,7 @@
selectionChangedByLastCommand = false
}
default:
+ clearWindowIndexKeyPending()
recordKeyboardCommand("unknown:\(command)")
selectionChangedByLastCommand = false
}
@@ -1499,7 +1531,51 @@
appShelfIndexKeyDownCount += 1
lastAppShelfIndexKeySymbol = symbol
+ if flags.contains(.option), handleWindowIndexKey(symbol: symbol) {
+ return true
+ }
+ clearWindowIndexKeyPending()
performKeyboardCommand(symbol)
+ return true
+ }
+
+ private func handleWindowIndexKey(symbol: String) -> Bool {
+ let now = CACurrentMediaTime()
+ if let pending = validWindowIndexKeyPending(now: now) {
+ let code = "\(pending.appSymbol)\(symbol)"
+ if let card = waterfallCard(appGroupIndex: pending.appGroupIndex, windowIndexSymbol: symbol) {
+ recordKeyboardCommand("window:\(code)")
+ lastWindowIndexKeyCommand = "window:\(code)"
+ lastWindowIndexKeyCommitCode = code
+ clearWindowIndexKeyPending()
+ commitKeyboardWindowCard(card, trigger: "windowIndexKey")
+ return true
+ }
+
+ recordKeyboardCommand("windowInvalid:\(code)")
+ lastWindowIndexKeyCommand = "windowInvalid:\(code)"
+ lastWindowIndexKeyCommitCode = nil
+ selectionChangedByLastCommand = false
+ clearWindowIndexKeyPending()
+ return true
+ }
+
+ let recordedCommand = "app:\(symbol)"
+ recordKeyboardCommand(recordedCommand)
+ lastWindowIndexKeyCommand = nil
+ lastWindowIndexKeyCommitCode = nil
+ if focusAppShelfItemForKeyboard(indexSymbol: symbol, commandLabel: recordedCommand),
+ let ordinal = Self.appShelfIndexSymbols.firstIndex(of: symbol),
+ ordinal < appShelfItems.count {
+ setWindowIndexKeyPending(
+ appSymbol: symbol,
+ appGroupIndex: appShelfItems[ordinal].item.appGroupIndex,
+ startedAt: now
+ )
+ } else {
+ selectionChangedByLastCommand = false
+ clearWindowIndexKeyPending()
+ }
return true
}
@@ -1528,6 +1604,47 @@
appGroupIndex: appShelfItems[ordinal].item.appGroupIndex,
appIndexCommand: commandLabel
)
+ }
+
+ private func validWindowIndexKeyPending(now: CFTimeInterval) -> WindowIndexKeyPending? {
+ guard let pending = windowIndexKeyPending else { return nil }
+ guard now - pending.startedAt <= Self.windowIndexKeyPendingInterval else {
+ clearWindowIndexKeyPending()
+ return nil
+ }
+ return pending
+ }
+
+ private func setWindowIndexKeyPending(appSymbol: String, appGroupIndex: Int, startedAt: CFTimeInterval) {
+ windowIndexKeyPendingClearTask?.cancel()
+ windowIndexKeyPending = WindowIndexKeyPending(
+ appSymbol: appSymbol,
+ appGroupIndex: appGroupIndex,
+ startedAt: startedAt
+ )
+ windowIndexKeyPendingClearTask = Task { @MainActor [weak self] in
+ do {
+ try await Task.sleep(nanoseconds: UInt64(Self.windowIndexKeyPendingInterval * 1_000_000_000))
+ } catch {
+ return
+ }
+ guard let self,
+ let pending = self.windowIndexKeyPending,
+ pending.appSymbol == appSymbol,
+ pending.appGroupIndex == appGroupIndex,
+ pending.startedAt == startedAt
+ else {
+ return
+ }
+ self.windowIndexKeyPending = nil
+ self.windowIndexKeyPendingClearTask = nil
+ }
+ }
+
+ private func clearWindowIndexKeyPending() {
+ windowIndexKeyPendingClearTask?.cancel()
+ windowIndexKeyPendingClearTask = nil
+ windowIndexKeyPending = nil
}
@discardableResult
@@ -1770,6 +1887,7 @@
.trimmingCharacters(in: .whitespacesAndNewlines)
.lowercased()
guard !command.isEmpty else { return }
+ clearWindowIndexKeyPending()
let parts = command.split(separator: ":").map(String.init)
switch parts.first {
@@ -2078,6 +2196,34 @@
private func clickWindowCard(_ card: WaterfallCardLayers) {
hoverWindowCard(card)
commitWindowCard(card, trigger: "windowCard")
+ }
+
+ private func commitKeyboardWindowCard(_ card: WaterfallCardLayers, trigger: String) {
+ let selection = QuickSwitchSelection(
+ appGroupIndex: card.item.appGroupIndex,
+ windowIndex: card.item.windowIndex,
+ windowID: card.item.window.id
+ )
+ DevelopmentDiagnostics.log("quickSwitch.view.commitKeyboardWindow", [
+ "trigger": trigger,
+ "appGroupIndex": selection.appGroupIndex,
+ "windowIndex": selection.windowIndex,
+ "windowID": selection.windowID,
+ "appName": card.item.window.app.name,
+ "appPID": card.item.window.app.processIdentifier,
+ "titleHash": DevelopmentDiagnostics.stableFingerprint(card.item.window.title),
+ "titleLength": card.item.window.title.count,
+ "titleIsEmpty": card.item.window.title.isEmpty,
+ "isMinimized": card.item.window.isMinimized,
+ "isFullscreen": card.item.window.isFullscreen,
+ "identifierSource": String(describing: card.item.window.identifierSource)
+ ])
+ currentSelection = selection
+ columnSelectionHistory[selection.appGroupIndex] = selection.windowIndex
+ lastCommittedSelection = selection
+ lastCommitSource = .keyboard
+ ensureCurrentSelectionVisible()
+ onCommitSelection?(selection, .keyboard)
}
private func commitWindowCard(_ card: WaterfallCardLayers, trigger: String) {
@@ -3305,7 +3451,8 @@
string: waterfallMetaText(for: window),
fontSize: 10,
weight: .regular,
- color: .secondaryLabelColor
+ color: .secondaryLabelColor,
+ alignment: .right
)
let appIcon = CALayer()
appIcon.contentsGravity = .resizeAspect
@@ -4101,6 +4248,15 @@
.first(where: { $0.column.appGroupIndex == appGroupIndex })?
.cards
.first(where: { $0.item.windowIndex == windowIndex })
+ }
+
+ private func waterfallCard(appGroupIndex: Int, windowIndexSymbol: String) -> WaterfallCardLayers? {
+ guard let ordinal = Self.appShelfIndexSymbols.firstIndex(of: windowIndexSymbol),
+ ordinal < Self.appShelfIndexSymbols.count
+ else {
+ return nil
+ }
+ return waterfallCard(appGroupIndex: appGroupIndex, windowIndex: ordinal)
}
private func waterfallCard(windowID: UInt32) -> WaterfallCardLayers? {
@@ -5658,7 +5814,26 @@
}
private func waterfallMetaText(for card: QuickSwitchWindowCardViewModel) -> String {
- card.primarySpaceLabel ?? "No Space"
+ windowShortcutCode(for: card) ?? ""
+ }
+
+ private func windowShortcutCode(for card: QuickSwitchWindowCardViewModel) -> String? {
+ guard let appOrdinal = appShelfItems.firstIndex(where: { $0.item.appGroupIndex == card.appGroupIndex }),
+ let appSymbol = singleIndexSymbol(forOrdinal: appOrdinal),
+ let windowSymbol = singleIndexSymbol(forOrdinal: card.windowIndex)
+ else {
+ return nil
+ }
+ return "\(appSymbol)\(windowSymbol)"
+ }
+
+ private func singleIndexSymbol(forOrdinal ordinal: Int) -> String? {
+ guard ordinal >= 0,
+ ordinal < Self.appShelfIndexSymbols.count
+ else {
+ return nil
+ }
+ return Self.appShelfIndexSymbols[ordinal]
}
private func waterfallStateText(for card: QuickSwitchWindowCardViewModel) -> String {
@@ -6178,6 +6353,7 @@
"titleIsEmpty": card.item.window.title.isEmpty,
"primarySpaceID": card.item.primarySpaceID ?? NSNull(),
"primarySpaceLabel": card.item.primarySpaceLabel ?? NSNull(),
+ "windowShortcutCode": waterfallMetaText(for: card.item),
"isMinimized": card.item.window.isMinimized,
"isFullscreen": card.item.window.isFullscreen,
"identifierSource": "\(card.item.window.identifierSource)",
diff --git a/C3.tools/round1-horizontal-waterfall-fixture-qa.sh b/C3.tools/round1-horizontal-waterfall-fixture-qa.sh
index 9a00a50..3f8ec00 100755
--- a/C3.tools/round1-horizontal-waterfall-fixture-qa.sh
+++ b/C3.tools/round1-horizontal-waterfall-fixture-qa.sh
@@ -15,6 +15,9 @@
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}"
@@ -26,6 +29,9 @@
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}"
@@ -406,6 +412,118 @@
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
+}
+
assert_arrow_wrap_report() {
/usr/bin/python3 - "$ARROW_WRAP_REPORT" "$ARROW_WRAP_KEY_SEQUENCE" "$FIXTURE_APP_COUNT" <<'PY'
import json
@@ -511,12 +629,21 @@
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="$app_count" \
- --round01-fixture-windows-per-app="$FIXTURE_WINDOWS_PER_APP" \
+ --round01-fixture-windows-per-app="$windows_per_app" \
--round01-disable-screenshot-refresh \
--round01-waterfall-view-mode=horizontal \
--round01-quick-switch-report="$report" \
@@ -592,6 +719,26 @@
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
diff --git a/C3.tools/round1-screenshot-session-qa.sh b/C3.tools/round1-screenshot-session-qa.sh
index 6903a30..56700f8 100755
--- a/C3.tools/round1-screenshot-session-qa.sh
+++ b/C3.tools/round1-screenshot-session-qa.sh
@@ -118,6 +118,41 @@
PY
}
+assert_overlay_frame() {
+ local attempt
+ for attempt in {1..8}; do
+ if [ "$SKIP_OVERLAY_FRAME_CHECK" = "1" ]; then
+ if swift "$SCRIPT_DIR/window-logic-qa.swift" \
+ --expect-quick-switch \
+ --expect-single-aligner-overlay; then
+ return
+ fi
+ else
+ if swift "$SCRIPT_DIR/window-logic-qa.swift" \
+ --expect-quick-switch \
+ --expect-single-aligner-overlay \
+ --expect-overlay-on-mouse-screen \
+ --expect-overlay-uses-screen-frame; then
+ return
+ fi
+ fi
+
+ sleep 0.4
+ done
+
+ if [ "$SKIP_OVERLAY_FRAME_CHECK" = "1" ]; then
+ swift "$SCRIPT_DIR/window-logic-qa.swift" \
+ --expect-quick-switch \
+ --expect-single-aligner-overlay
+ else
+ swift "$SCRIPT_DIR/window-logic-qa.swift" \
+ --expect-quick-switch \
+ --expect-single-aligner-overlay \
+ --expect-overlay-on-mouse-screen \
+ --expect-overlay-uses-screen-frame
+ fi
+}
+
assert_report() {
/usr/bin/python3 - "$REPORT" "$REQUIRE_REAL_SCREENSHOT" <<'PY'
import json
@@ -233,18 +268,7 @@
sleep "$OPEN_WAIT"
wait_for_loaded_report
-
-if [ "$SKIP_OVERLAY_FRAME_CHECK" = "1" ]; then
- swift "$SCRIPT_DIR/window-logic-qa.swift" \
- --expect-quick-switch \
- --expect-single-aligner-overlay
-else
- swift "$SCRIPT_DIR/window-logic-qa.swift" \
- --expect-quick-switch \
- --expect-single-aligner-overlay \
- --expect-overlay-on-mouse-screen \
- --expect-overlay-uses-screen-frame
-fi
+assert_overlay_frame
wait_for_screenshots
assert_report
diff --git a/C3.tools/round1-vertical-keyboard-app-focus-fixture-qa.sh b/C3.tools/round1-vertical-keyboard-app-focus-fixture-qa.sh
index 2520ff9..9a3b1a2 100755
--- a/C3.tools/round1-vertical-keyboard-app-focus-fixture-qa.sh
+++ b/C3.tools/round1-vertical-keyboard-app-focus-fixture-qa.sh
@@ -14,7 +14,7 @@
REPORT_DIR="$BUILD_REPORT_ROOT"
FIXTURE_APP_COUNT="${ALIGNER_ROUND1_VERTICAL_KEYBOARD_APP_COUNT:-12}"
FIXTURE_WINDOWS_PER_APP="${ALIGNER_ROUND1_VERTICAL_KEYBOARD_WINDOWS_PER_APP:-8}"
-REPORT_WAIT="${ALIGNER_ROUND1_VERTICAL_KEYBOARD_REPORT_WAIT:-6.0}"
+REPORT_WAIT="${ALIGNER_ROUND1_VERTICAL_KEYBOARD_REPORT_WAIT:-12.0}"
APP_PID=""
fail() {
@@ -114,6 +114,45 @@
if last_report is not None:
print(json.dumps(last_report, indent=2, ensure_ascii=False), file=sys.stderr)
print(f"vertical keyboard report did not reach expected commands within {timeout:.1f}s", file=sys.stderr)
+sys.exit(1)
+PY
+}
+
+wait_for_committed_report() {
+ local report="$1"
+ local expected_sequence="$2"
+
+ /usr/bin/python3 - "$report" "$REPORT_WAIT" "$expected_sequence" <<'PY'
+import json
+import sys
+import time
+
+path = sys.argv[1]
+timeout = float(sys.argv[2])
+expected_sequence = [part for part in sys.argv[3].split(",") if part]
+deadline = time.monotonic() + timeout
+last_report = None
+
+while time.monotonic() < deadline:
+ try:
+ with open(path, "r", encoding="utf-8") as file:
+ report = json.load(file)
+ last_report = report
+ root = report.get("rootView", {})
+ if (
+ report.get("snapshotLoaded") is True
+ and root.get("keyboardCommandsApplied") == expected_sequence
+ ):
+ sys.exit(0)
+ except FileNotFoundError:
+ pass
+ except json.JSONDecodeError:
+ pass
+ time.sleep(0.2)
+
+if last_report is not None:
+ print(json.dumps(last_report, indent=2, ensure_ascii=False), file=sys.stderr)
+print(f"vertical keyboard committed report did not reach expected commands within {timeout:.1f}s", file=sys.stderr)
sys.exit(1)
PY
}
@@ -239,6 +278,82 @@
PY
}
+assert_window_shortcut_report() {
+ local report="$1"
+ local expected_sequence="$2"
+ local target_app_index="$3"
+ local target_window_index="$4"
+ local expected_code="$5"
+
+ /usr/bin/python3 - \
+ "$report" \
+ "$expected_sequence" \
+ "$target_app_index" \
+ "$target_window_index" \
+ "$expected_code" \
+ "$FIXTURE_APP_COUNT" \
+ "$FIXTURE_WINDOWS_PER_APP" <<'PY'
+import json
+import sys
+
+path = sys.argv[1]
+expected_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])
+expected_code = sys.argv[5]
+fixture_app_count = int(sys.argv[6])
+fixture_windows_per_app = int(sys.argv[7])
+
+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)
+
+root = report.get("rootView", {})
+columns = root.get("waterfallColumns", [])
+require(report.get("snapshotLoaded") is True, "snapshotLoaded must be true")
+require(report.get("appCount") == fixture_app_count, "fixture appCount must match")
+require(report.get("windowCount") == fixture_app_count * fixture_windows_per_app, "fixture windowCount must match")
+require(root.get("waterfallViewMode") == "verticalColumns", "window shortcut fixture must run in vertical Waterfall")
+require(root.get("keyboardCommandsApplied") == expected_sequence, "two-key window shortcut commands must match")
+require(root.get("appShelfIndexKeyDownCount") == 2, "two-key window shortcut must exercise two physical keyDown events")
+require(root.get("lastAppShelfIndexKeySymbol") == expected_code[-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 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
+}
+
run_case() {
local name="$1"
local sequence="$2"
@@ -287,6 +402,36 @@
swift "$SCRIPT_DIR/window-logic-qa.swift" --expect-no-quick-switch >&2
}
+run_window_shortcut_case() {
+ local name="window-shortcut"
+ local sequence="physical-index:3,physical-index:6"
+ local expected_sequence="app:3,window:36"
+ local report="$REPORT_DIR/round01-vertical-keyboard-$name-report.json"
+
+ stop_current_aligner
+ rm -f "$report"
+
+ "$APP/Contents/MacOS/Aligner" \
+ --round0-skip-permissions \
+ --round01-open-quick-switch \
+ --round01-waterfall-view-mode=vertical \
+ --round01-fixture-app-count="$FIXTURE_APP_COUNT" \
+ --round01-fixture-windows-per-app="$FIXTURE_WINDOWS_PER_APP" \
+ --round01-disable-screenshot-refresh \
+ --round01-debug-key-sequence="$sequence" \
+ --round01-quick-switch-report="$report" &
+
+ APP_PID=$!
+ wait_for_committed_report "$report" "$expected_sequence"
+ assert_window_shortcut_report "$report" "$expected_sequence" 2 5 "36"
+
+ kill "$APP_PID" 2>/dev/null || true
+ wait "$APP_PID" 2>/dev/null || true
+ APP_PID=""
+ sleep 0.3
+ swift "$SCRIPT_DIR/window-logic-qa.swift" --expect-no-quick-switch >&2
+}
+
if [ "$FIXTURE_APP_COUNT" -lt 12 ]; then
fail "fixture app count must be at least 12"
fi
@@ -310,6 +455,7 @@
run_case "right-wrap-to-first" "$LAST_APP_SYMBOL,right" 0 0 0 0 "none" "false" "false"
run_case "bottom-boundary" "3,down,down,down,down,down,down,down,down,down" 2 2 7 1 "down" "false" "true"
run_case "top-boundary" "4,down,up" 3 3 0 1 "up" "false" "true"
+run_window_shortcut_case
trap - EXIT
cleanup
--
Gitblit v1.9.3