Freeze 0.1.12 local QA baseline

Ariver

2026-06-28 9ba7cd3b47fb91eaaa8d0c3df8b7286a89be1756

 C3.tools/round1-app-shelf-fixture-qa.sh

@@ -10,14 +10,22 @@
# 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
@@ -43,6 +51,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() {
@@ -84,7 +109,9 @@
  local expected_rows="$4"
  local expected_icon_size="$5"
  local expected_scrollable="$6"
  /usr/bin/python3 - "$report" "$fixture_app_count" "$hover_index" "$expected_rows" "$expected_icon_size" "$expected_scrollable" <<'PY'
  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

@@ -94,6 +121,8 @@
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)
@@ -117,7 +146,9 @@
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")
@@ -126,6 +157,12 @@
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")
@@ -135,17 +172,58 @@
    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")
require(sum(1 for item in items if item.get("isSelected") is True) == 1, "App Shelf must expose one selected app")
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[0].get("isSelected") is True, "fixture first app should be selected")
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")
require("selectedVisualSuppressed" in items[0].get("visualStates", []), "non-hovered selected app must suppress selected visual state")
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")
require(items[0].get("iconFrame", {}).get("width") == expected_icon_size, "non-hovered selected app icon must match normal fixture icon size")
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", {})
@@ -156,11 +234,16 @@
    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")]
require(not is_legacy_blue(hovered_header_color), "hovered column header must no longer use the previous blue fill")
require(max(hovered_header_channels) - min(hovered_header_channels) <= 0.035, "hovered column header must use a neutral gray fill")
require(0.16 <= hovered_header_color.get("alpha", 0) <= 0.30, "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")
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")
@@ -182,7 +265,15 @@
    if item.get("isSelected") is not True and item.get("isHovered") is not True
]
require(normal_items, "fixture must include normal app items")
require(all(item.get("iconFrame", {}).get("width") == expected_icon_size for item in normal_items), "normal app icons must match expected fixture icon size")
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")
@@ -196,19 +287,27 @@
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[0].get("zPosition", 0)
selected_z = items[selected_index].get("zPosition", 0)
hover_z = items[hover_index].get("zPosition", 0)
normal_z = normal_items[0].get("zPosition", 0)
require(selected_z == normal_z, "non-hovered selected App Shelf item must not float above normal items")
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"),
    "selectedIcon": items[0].get("iconFrame"),
    "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,
@@ -232,16 +331,19 @@
  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=vertical
    --round01-waterfall-view-mode="$waterfall_mode"
    --round01-debug-hover-app-index="$hover_index"
    --round01-quick-switch-report="$report"
  )
@@ -256,12 +358,98 @@
    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" "$app_count" "$hover_index" "$expected_rows" "$expected_icon_size" "$expected_scrollable"
  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
@@ -272,6 +460,14 @@
}

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
run_fixture "$NARROW_REPORT" "$NARROW_FIXTURE_APP_COUNT" "$NARROW_HOVER_INDEX" "$NARROW_OVERLAY_WIDTH" 2 56 false
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