Ariver
2026-06-28 8fbe7d9123cdb618de5ecf3cd1b0fb81199a2dac
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
#!/bin/bash
# Round01 App Shelf fixture QA. It uses a deterministic Quick Switch snapshot
# with many apps so compression, two-row layout, scrolling, and hover visuals
# are covered without relying on the current desktop state.
 
set -euo pipefail
 
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
OUTPUT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
# 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"
REPORT="$BUILD_REPORT_ROOT/round01-app-shelf-fixture-report.json"
NARROW_REPORT="$BUILD_REPORT_ROOT/round01-app-shelf-narrow-fixture-report.json"
DARK_REPORT="$BUILD_REPORT_ROOT/round01-app-shelf-dark-fixture-report.json"
HORIZONTAL_REPORT="$BUILD_REPORT_ROOT/round01-app-shelf-horizontal-fixture-report.json"
PERSIST_VERTICAL_REPORT="$BUILD_REPORT_ROOT/round01-app-shelf-hover-persist-vertical-report.json"
PERSIST_HORIZONTAL_REPORT="$BUILD_REPORT_ROOT/round01-app-shelf-hover-persist-horizontal-report.json"
FIXTURE_APP_COUNT="${ALIGNER_ROUND1_APP_SHELF_FIXTURE_COUNT:-60}"
HOVER_INDEX="${ALIGNER_ROUND1_APP_SHELF_HOVER_INDEX:-5}"
NARROW_FIXTURE_APP_COUNT="${ALIGNER_ROUND1_APP_SHELF_NARROW_FIXTURE_COUNT:-10}"
NARROW_HOVER_INDEX="${ALIGNER_ROUND1_APP_SHELF_NARROW_HOVER_INDEX:-5}"
NARROW_OVERLAY_WIDTH="${ALIGNER_ROUND1_APP_SHELF_NARROW_OVERLAY_WIDTH:-780}"
REPORT_WAIT="${ALIGNER_ROUND1_APP_SHELF_REPORT_WAIT:-6.0}"
OLD_THEME_SET=0
OLD_THEME=""
 
fail() {
  echo "Round01 App Shelf fixture QA failed: $*" >&2
  exit 1
}
 
aligner_pids_for_current_app() {
  ps -axo pid=,args= | while read -r pid command; do
    case "$command" in
      "$APP/Contents/MacOS/Aligner"*) echo "$pid" ;;
    esac
  done
}
 
stop_current_aligner() {
  for pid in $(aligner_pids_for_current_app); do
    kill "$pid" 2>/dev/null || true
  done
 
  for _ in {1..30}; do
    [ -z "$(aligner_pids_for_current_app)" ] && return
    sleep 0.1
  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() {
  local report="$1"
  /usr/bin/python3 - "$report" "$REPORT_WAIT" <<'PY'
import json
import sys
import time
 
path = sys.argv[1]
timeout = float(sys.argv[2])
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
        if report.get("snapshotLoaded") is True:
            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"snapshot report did not become loaded within {timeout:.1f}s", file=sys.stderr)
sys.exit(1)
PY
}
 
assert_report() {
  local report="$1"
  local fixture_app_count="$2"
  local hover_index="$3"
  local expected_rows="$4"
  local expected_icon_size="$5"
  local expected_scrollable="$6"
  local expected_theme="$7"
  local expected_mode="$8"
  /usr/bin/python3 - "$report" "$fixture_app_count" "$hover_index" "$expected_rows" "$expected_icon_size" "$expected_scrollable" "$expected_theme" "$expected_mode" <<'PY'
import json
import sys
 
path = sys.argv[1]
fixture_app_count = int(sys.argv[2])
hover_index = int(sys.argv[3])
expected_rows = int(sys.argv[4])
expected_icon_size = int(sys.argv[5])
expected_scrollable = sys.argv[6].lower() == "true"
expected_theme = sys.argv[7]
expected_mode = sys.argv[8]
 
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 expected_index_text(index):
    symbols = list("1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ")
    if index < len(symbols):
        return symbols[index]
    overflow = index - len(symbols)
    return symbols[10 + (overflow // 26) % 26] + symbols[10 + overflow % 26]
 
root = report.get("rootView", {})
items = root.get("appShelfItems", [])
columns = root.get("waterfallColumns", [])
segments = root.get("spaceLaneSegments", [])
 
require(report.get("snapshotLoaded") is True, "snapshotLoaded must be true")
require(report.get("resolvedQuickSwitchTheme") == expected_theme, "fixture Quick Switch theme must match the deterministic QA theme")
require(report.get("appCount") == fixture_app_count, "fixture appCount must match requested count")
require(root.get("waterfallViewMode") == expected_mode, "fixture Waterfall mode must match expected mode")
require(root.get("appShelfItemCount") == fixture_app_count, "App Shelf item count must match fixture count")
require(len(items) == fixture_app_count, "App Shelf item reports must match fixture count")
require(root.get("appShelfRows") == expected_rows, "fixture App Shelf row count must match expected rows")
require(root.get("appShelfMaxRows") == 2, "App Shelf max rows must be two")
require(root.get("appShelfIconSize") == expected_icon_size, "fixture App Shelf icon size must match expected size")
require(root.get("appShelfMinIconSize") == 36, "App Shelf min icon size must be 36pt")
require(root.get("appShelfSelectedIconSize") == 68, "App Shelf selected icon size must be 68pt")
require(root.get("appShelfHoverIconSize") == 68, "App Shelf hover icon size must be 68pt")
require(root.get("appShelfMagneticFirstNeighborInfluence") == 0, "App Shelf first neighbor must not visually follow hovered App")
require(root.get("appShelfMagneticSecondNeighborInfluence") == 0, "App Shelf second neighbor must not visually follow hovered App")
require(root.get("appShelfMagneticHoverLift") == 4, "App Shelf magnetic hover lift must be 4pt")
require(root.get("appShelfMagneticFirstNeighborLift") == 0, "App Shelf first neighbor lift must be disabled")
require(root.get("appShelfMagneticSecondNeighborLift") == 0, "App Shelf second neighbor lift must be disabled")
require(root.get("appShelfMagneticAnimationDurationMilliseconds") == 160, "App Shelf magnetic animation duration must stay short and native-feeling")
require(root.get("appShelfScrollable") is expected_scrollable, "fixture App Shelf scrollable state must match expected")
if expected_scrollable:
    require(root.get("appShelfContentWidth", 0) > root.get("appShelfVisibleWidth", 0), "scrollable fixture App Shelf content must overflow visible width")
    require(root.get("appShelfMaxScrollOffset", 0) > 0, "scrollable fixture App Shelf must expose positive max scroll offset")
else:
    require(root.get("appShelfContentWidth", 0) <= root.get("appShelfVisibleWidth", 0), "non-scrollable fixture App Shelf content must fit visible width")
    require(root.get("appShelfMaxScrollOffset", 0) == 0, "non-scrollable fixture App Shelf must expose zero max scroll offset")
require(root.get("appShelfHoveredIndex") == hover_index, "fixture App Shelf must expose requested hovered index")
require(len(columns) == fixture_app_count, "Waterfall column reports must match fixture count")
selected_indexes = [index for index, item in enumerate(items) if item.get("isSelected") is True]
require(len(selected_indexes) == 1, "App Shelf must expose one selected app")
selected_index = selected_indexes[0]
require(sum(1 for item in items if item.get("isHovered") is True) == 1, "App Shelf must expose one hovered app")
require(sum(1 for column in columns if column.get("isHovered") is True) == 1, "Waterfall must expose one hovered column")
require(items[hover_index].get("isHovered") is True, "fixture requested app should be hovered")
require(columns[hover_index].get("isHovered") is True, "fixture requested app column should be hovered")
if selected_index != hover_index:
    require("selectedVisualSuppressed" in items[selected_index].get("visualStates", []), "non-hovered selected app must suppress selected visual state")
require("hover" in items[hover_index].get("visualStates", []), "hovered app must expose hover visual state")
require("hover" in columns[hover_index].get("visualStates", []), "hovered column must expose hover visual state")
if selected_index != hover_index:
    require(items[selected_index].get("iconFrame", {}).get("width") == expected_icon_size, "non-hovered selected app icon must match normal fixture icon size")
require(items[hover_index].get("iconFrame", {}).get("width") == 68, "hovered app icon must be 68pt")
require(items[hover_index].get("magneticInfluence") == 1, "hovered app must expose full magnetic influence")
require(items[hover_index].get("magneticLift") == 4, "hovered app must lift by 4pt")
require(items[hover_index].get("backgroundColor", {}).get("alpha", 1) == 0, "hovered App icon must not draw a blue background rectangle")
require(items[hover_index].get("backgroundBorderWidth", -1) == 0, "hovered App icon background border must be removed")
require(items[hover_index].get("backgroundShadowOpacity", -1) == 0, "hovered App icon background shadow must be removed")
require(items[hover_index].get("containerBorderWidth", -1) == 0, "hovered App item container border must be removed")
require(items[hover_index].get("iconBorderWidth", -1) == 0, "hovered App icon layer border must be removed")
require(all(item.get("backgroundBorderWidth", -1) == 0 for item in items), "App Shelf background borders must be removed in every view mode")
require(all(item.get("containerBorderWidth", -1) == 0 for item in items), "App Shelf container borders must be removed in every view mode")
require(all(item.get("iconBorderWidth", -1) == 0 for item in items), "App Shelf icon borders must be removed in every view mode")
require(all(item.get("backgroundColor", {}).get("alpha", 0) == 0 for item in items if item.get("isSpaceFocused") is not True), "App Shelf non-space-focused items must not draw blue background rectangles")
 
magnetic_enabled = root.get("appShelfMagneticHoverEnabled") is True
neighbor_indexes = {
    index
    for index in (hover_index - 2, hover_index - 1, hover_index + 1, hover_index + 2)
    if 0 <= index < len(items)
}
first_neighbor_indexes = {
    index
    for index in (hover_index - 1, hover_index + 1)
    if 0 <= index < len(items)
}
second_neighbor_indexes = {
    index
    for index in (hover_index - 2, hover_index + 2)
    if 0 <= index < len(items)
}
 
require(neighbor_indexes, "fixture must include App Shelf neighbors")
require(all(items[index].get("iconFrame", {}).get("width") == expected_icon_size for index in neighbor_indexes), "neighbor App icons must not grow or visually follow hover")
require(all(items[index].get("iconFrame", {}).get("height") == expected_icon_size for index in neighbor_indexes), "neighbor App icons must keep normal height")
require(all(items[index].get("magneticInfluence") == 0 for index in neighbor_indexes), "neighbor App icons must expose zero magnetic influence")
require(all(items[index].get("magneticLift") == 0 for index in neighbor_indexes), "neighbor App icons must expose zero lift")
require(all(items[index].get("isHovered") is False for index in neighbor_indexes), "neighbors must not gain hover semantics")
require(all("hover" not in items[index].get("visualStates", []) for index in neighbor_indexes), "neighbors must not expose hover visual state")
require(all("magneticNeighbor" not in items[index].get("visualStates", []) for index in neighbor_indexes), "neighbors must not expose magnetic neighbor state")
require(all(items[index].get("closeButtonVisible") is False for index in neighbor_indexes), "neighbors must not show App close buttons")
 
legacy_blue_reference = {"red": 135 / 255, "green": 200 / 255, "blue": 1.0, "alpha": 1.0}
hovered_title_color = columns[hover_index].get("appNameColor", {})
hovered_header_color = columns[hover_index].get("headerBackgroundColor", {})
hovered_count_color = columns[hover_index].get("countColor", {})
 
def is_legacy_blue(color):
    return all(abs(color.get(channel, -1) - legacy_blue_reference[channel]) <= 0.01 for channel in ("red", "green", "blue"))
 
hovered_header_channels = [hovered_header_color.get(channel, -1) for channel in ("red", "green", "blue")]
if expected_mode == "verticalColumns":
    require(not is_legacy_blue(hovered_header_color), "hovered column header must no longer use the previous blue fill")
    if expected_theme == "light":
        require(max(hovered_header_channels) - min(hovered_header_channels) <= 0.035, "light hovered column header must use a neutral gray fill")
    else:
        require(max(hovered_header_channels) - min(hovered_header_channels) <= 0.08, "dark hovered column header must stay near-neutral and readable")
    max_header_alpha = 0.34 if expected_theme == "dark" else 0.30
    require(0.16 <= hovered_header_color.get("alpha", 0) <= max_header_alpha, "hovered column header gray fill must stay lightweight")
    require(hovered_title_color.get("alpha", 0) >= 0.8, "hovered column title must remain readable")
    require(hovered_count_color.get("alpha", 0) >= 0.45, "hovered column count must remain readable")
hovered_cards = columns[hover_index].get("cards", [])
require(hovered_cards, "hovered column must include at least one card")
require("appLinked" in hovered_cards[0].get("visualStates", []), "hovered App column first card must expose appLinked visual state")
require(hovered_cards[0].get("closeButtonVisible") is False, "App-linked first card must not show close button unless directly hovered")
require(hovered_cards[0].get("shadowOpacity", 0) > 0, "App-linked first card must lift with a shadow")
require(hovered_cards[0].get("titleBarBackgroundColor", {}).get("alpha", 0) > 0.10, "App-linked first card title bar must expose a visible highlight")
require(all("appLinked" not in card.get("visualStates", []) for card in hovered_cards[1:]), "only the first vertical card in the hovered App column should expose appLinked")
for index, column in enumerate(columns):
    if index == hover_index:
        continue
    require(column.get("isHovered") is False, "non-hovered columns must not be marked hovered")
    require("hover" not in column.get("visualStates", []), "non-hovered columns must not expose hover visual state")
    normal_header = column.get("headerBackgroundColor", {})
    require(not is_legacy_blue(normal_header), "non-hovered column headers must not use the previous blue fill")
    require(all("appLinked" not in card.get("visualStates", []) for card in column.get("cards", [])), "non-hovered columns must not expose appLinked cards")
 
normal_items = [
    item for item in items
    if item.get("isSelected") is not True and item.get("isHovered") is not True
]
require(normal_items, "fixture must include normal app items")
neutral_items = [
    item for index, item in enumerate(items)
    if item.get("isSelected") is not True
    and item.get("isHovered") is not True
    and index not in neighbor_indexes
]
require(neutral_items, "fixture must include neutral app items outside the magnetic range")
require(all(item.get("iconFrame", {}).get("width") == expected_icon_size for item in neutral_items), "neutral app icons outside the magnetic range must match expected fixture icon size")
require(all(item.get("closeButtonVisible") is False for item in items if item.get("isHovered") is not True), "only the actual hovered App may show an App close button")
require(all(item.get("labelTruncationMode") == "middle" for item in items), "all App Shelf labels must use middle truncation")
require(all(item.get("indexVisible") is True for item in items), "all App Shelf items must expose a visible hand-written index marker")
require(all(item.get("indexText") == expected_index_text(index) for index, item in enumerate(items)), "App Shelf index markers must follow 1234567890ABCDEFG order")
require(all(item.get("indexFontSize", 0) >= 14 for item in items), "App Shelf index markers must keep readable font size")
require(all(0.38 <= item.get("indexColor", {}).get("alpha", 0) <= 0.62 for item in items), "App Shelf index markers must stay low-noise but fully readable")
require(all(item.get("indexOpacity", 0) == 1 for item in items), "App Shelf index markers must avoid double alpha fading")
require(all(item.get("indexFrame", {}).get("width", 0) >= 16 for item in items), "App Shelf index markers must reserve enough width")
require(all(item.get("indexFrame", {}).get("height", 0) >= 22 for item in items), "App Shelf index markers must reserve enough height to avoid bottom clipping")
require(all(item.get("indexFrame", {}).get("x", 99) < item.get("iconFrame", {}).get("x", -99) for item in items), "App Shelf index markers must sit beside the icon, not over the icon center")
 
row_y_values = {round(item.get("frame", {}).get("y", 0), 2) for item in items}
require(len(row_y_values) == expected_rows, "fixture App Shelf visible rows must match expected rows")
require([item.get("name") for item in items] == root.get("appShelfNames", []), "App Shelf item reports must follow App Shelf order")
selected_z = items[selected_index].get("zPosition", 0)
hover_z = items[hover_index].get("zPosition", 0)
normal_z = normal_items[0].get("zPosition", 0)
if selected_index != hover_index:
    require(selected_z == normal_z, "non-hovered selected App Shelf item must not float above normal items")
require(hover_z > normal_z, "hover App Shelf item must stay above normal items")
 
print(json.dumps({
    "mode": root.get("waterfallViewMode"),
    "appCount": report.get("appCount"),
    "rows": root.get("appShelfRows"),
    "iconSize": root.get("appShelfIconSize"),
    "selectedIndex": selected_index,
    "selectedIcon": items[selected_index].get("iconFrame"),
    "hoveredIndex": root.get("appShelfHoveredIndex"),
    "hoveredIcon": items[hover_index].get("iconFrame"),
    "magneticEnabled": magnetic_enabled,
    "neighborIcons": [
        items[index].get("iconFrame") for index in sorted(neighbor_indexes)
    ],
    "hoveredBackgroundColor": items[hover_index].get("backgroundColor"),
    "hoveredColumnHeaderColor": hovered_header_color,
    "hoveredColumnTitleColor": hovered_title_color,
    "hoveredColumnCountColor": hovered_count_color,
    "legacyBlueReference": legacy_blue_reference,
    "hoveredFirstCardStates": hovered_cards[0].get("visualStates"),
    "hoveredFirstCardTitleBarColor": hovered_cards[0].get("titleBarBackgroundColor"),
    "firstIndexes": [item.get("indexText") for item in items[:min(12, len(items))]],
    "selectedZ": selected_z,
    "hoverZ": hover_z,
    "scrollable": root.get("appShelfScrollable"),
    "maxScrollOffset": root.get("appShelfMaxScrollOffset")
}, indent=2, ensure_ascii=False))
PY
}
 
run_fixture() {
  local report="$1"
  local app_count="$2"
  local hover_index="$3"
  local overlay_width="$4"
  local expected_rows="$5"
  local expected_icon_size="$6"
  local expected_scrollable="$7"
  local expected_theme="${8:-light}"
  local waterfall_mode="${9:-vertical}"
 
  stop_current_aligner
  rm -f "$report"
  /usr/bin/defaults write "$DOMAIN" "$THEME_KEY" -string "$expected_theme"
 
  local args=(
    --round0-skip-permissions
    --round01-open-quick-switch
    --round01-fixture-app-count="$app_count"
    --round01-disable-screenshot-refresh
    --round01-waterfall-view-mode="$waterfall_mode"
    --round01-debug-hover-app-index="$hover_index"
    --round01-quick-switch-report="$report"
  )
  if [ -n "$overlay_width" ]; then
    args+=(--round01-debug-overlay-width="$overlay_width")
  fi
 
  "$APP/Contents/MacOS/Aligner" "${args[@]}" &
  APP_PID=$!
 
  cleanup() {
    kill "$APP_PID" 2>/dev/null || true
    wait "$APP_PID" 2>/dev/null || true
    stop_current_aligner
    restore_user_theme
  }
  trap cleanup EXIT
 
  wait_for_loaded_report "$report"
  swift "$SCRIPT_DIR/window-logic-qa.swift" --expect-quick-switch >&2
  local expected_mode="verticalColumns"
  if [ "$waterfall_mode" = "horizontal" ] || [ "$waterfall_mode" = "horizontalMasonry" ]; then
    expected_mode="horizontalMasonry"
  fi
  assert_report "$report" "$app_count" "$hover_index" "$expected_rows" "$expected_icon_size" "$expected_scrollable" "$expected_theme" "$expected_mode"
 
  kill "$APP_PID" 2>/dev/null || true
  wait "$APP_PID" 2>/dev/null || true
  sleep 0.5
  swift "$SCRIPT_DIR/window-logic-qa.swift" --expect-no-quick-switch >&2
  trap - EXIT
  stop_current_aligner
}
 
run_hover_persist_fixture() {
  local report="$1"
  local waterfall_mode="$2"
  local expected_mode="verticalColumns"
  if [ "$waterfall_mode" = "horizontal" ] || [ "$waterfall_mode" = "horizontalMasonry" ]; then
    expected_mode="horizontalMasonry"
  fi
 
  stop_current_aligner
  rm -f "$report"
  /usr/bin/defaults write "$DOMAIN" "$THEME_KEY" -string "light"
 
  "$APP/Contents/MacOS/Aligner" \
    --round0-skip-permissions \
    --round01-open-quick-switch \
    --round01-fixture-app-count="$NARROW_FIXTURE_APP_COUNT" \
    --round01-disable-screenshot-refresh \
    --round01-waterfall-view-mode="$waterfall_mode" \
    --round01-debug-overlay-width="$NARROW_OVERLAY_WIDTH" \
    --round01-debug-mouse-sequence="hover-app:$NARROW_HOVER_INDEX,reapply-view-model" \
    --round01-quick-switch-report="$report" &
  APP_PID=$!
 
  cleanup() {
    kill "$APP_PID" 2>/dev/null || true
    wait "$APP_PID" 2>/dev/null || true
    stop_current_aligner
    restore_user_theme
  }
  trap cleanup EXIT
 
  wait_for_loaded_report "$report"
  swift "$SCRIPT_DIR/window-logic-qa.swift" --expect-quick-switch >&2
  assert_report "$report" "$NARROW_FIXTURE_APP_COUNT" "$NARROW_HOVER_INDEX" 2 56 false light "$expected_mode"
 
  /usr/bin/python3 - "$report" "$NARROW_HOVER_INDEX" <<'PY'
import json
import sys
 
path = sys.argv[1]
hover_index = int(sys.argv[2])
with open(path, "r", encoding="utf-8") as file:
    report = json.load(file)
 
root = report.get("rootView", {})
commands = root.get("mouseCommandsApplied", [])
last_command = root.get("lastMouseCommand")
items = root.get("appShelfItems", [])
 
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)
 
require(last_command == "reapply-view-model" or "reapply-view-model" in commands, "fixture must simulate view-model rebuild after hover")
require(root.get("hoverTargetKind") == "app", "hover target must remain app after view-model rebuild")
require(root.get("appShelfHoveredIndex") == hover_index, "hovered App must persist after view-model rebuild")
require(items[hover_index].get("isHovered") is True, "hovered App item must stay hovered after view-model rebuild")
require(items[hover_index].get("iconFrame", {}).get("width") == 68, "hovered App icon must stay enlarged after view-model rebuild")
require(items[hover_index].get("magneticLift") == 4, "hovered App icon must keep lift after view-model rebuild")
 
print(json.dumps({
    "mode": root.get("waterfallViewMode"),
    "commands": commands,
    "lastCommand": last_command,
    "hoverTargetKind": root.get("hoverTargetKind"),
    "hoveredIndex": root.get("appShelfHoveredIndex"),
    "hoveredIcon": items[hover_index].get("iconFrame"),
    "hoveredLift": items[hover_index].get("magneticLift")
}, indent=2, ensure_ascii=False))
PY
 
  kill "$APP_PID" 2>/dev/null || true
  wait "$APP_PID" 2>/dev/null || true
  sleep 0.5
  swift "$SCRIPT_DIR/window-logic-qa.swift" --expect-no-quick-switch >&2
  trap - EXIT
  stop_current_aligner
}
 
stop_current_aligner
preserve_user_theme
trap 'stop_current_aligner || true; restore_user_theme' EXIT
"$SCRIPT_DIR/package-app.sh" >&2
run_fixture "$REPORT" "$FIXTURE_APP_COUNT" "$HOVER_INDEX" "" 2 36 true light
run_fixture "$HORIZONTAL_REPORT" "$FIXTURE_APP_COUNT" "$HOVER_INDEX" "" 2 36 true light horizontal
run_fixture "$NARROW_REPORT" "$NARROW_FIXTURE_APP_COUNT" "$NARROW_HOVER_INDEX" "$NARROW_OVERLAY_WIDTH" 2 56 false light
run_fixture "$DARK_REPORT" "$NARROW_FIXTURE_APP_COUNT" "$NARROW_HOVER_INDEX" "$NARROW_OVERLAY_WIDTH" 2 56 false dark
run_hover_persist_fixture "$PERSIST_VERTICAL_REPORT" vertical
run_hover_persist_fixture "$PERSIST_HORIZONTAL_REPORT" horizontal
restore_user_theme
trap - EXIT