ci.sh

#!/usr/bin/env bash
# ci.sh — full aether_ui test pipeline as a CI job would run it.
#
# The AetherUIDriver control server is OUT of app builds by default (a listening
# socket must not ship in release binaries); the spec/CI pipeline opts in so the
# HTTP-driven tests work. This MUST be exported before any `aeb` build below.
export AETHER_UI_WITH_DRIVER=1
#
# Phases:
#   1. Build every example (catches C/Aether compile regressions).
#   2. Smoke-launch the non-driver examples to catch runtime crashes the
#      HTTP-driven tests can't reach (widget wiring, reactive state init,
#      platform-backend regressions). Each binary is launched, given 1.5s
#      to render, then killed; still-alive = pass.
#   3. Launch example_calculator with the AetherUIDriver test server and
#      run test_calculator.sh (11 assertions).
#   4. Launch example_testable and run test_automation.sh (17 assertions).
#
#   Alongside those, Phase 1c3 runs the headless UI-logic tests under
#   tests/<name>/: .ae programs that assert against ui/module.ae and exit
#   non-zero, with no window and no driver. Everything else here needs a real
#   window, so they are the only invariants a display-less box can check.
#
# Platform handling:
#   macOS    — runs directly (AppKit).
#   Linux    — runs directly if $DISPLAY or $WAYLAND_DISPLAY is set; otherwise
#              auto-wraps with xvfb-run when available. Falls back to build-only.
#   Windows  — native Win32 backend. Aether-level examples are skipped (the
#              DSL has a separate module-resolution issue on MINGW that
#              blocks `ae build`). The C-level backend test suite
#              (tests/test_widgets.c) and the HTTP driver test
#              (tests/test_driver.sh) run instead — invoked via
#              `make contrib-aether-ui-check`.
#
# Exits non-zero only when an implemented platform fails. Leaves no
# background processes.
#
# Usage: ./ci.sh [port]

set -u

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
ROOT="$SCRIPT_DIR"
# The driver port: $1, else $AETHER_UI_TEST_PORT, else 9222 (a box whose 9222
# is taken -- an `adb forward tcp:9222` to a phone -- picks another). Apps
# bind the AETHER_UI_TEST_PORT they are launched with, whatever port they
# pass enable_test_server (aether_ui_test_server_start), and the specs talk
# to it (run_spec.sh exports its numeric $1 for tests/lib/uidriver.ae).
PORT="${1:-${AETHER_UI_TEST_PORT:-9222}}"

cd "$ROOT"
mkdir -p build

# --- Aether toolchain resolution guard -----------------------------------
# aeb resolves the SDK include AND lib dirs relative to `dirname(command -v ae)`
# WITHOUT dereferencing symlinks. If `ae` is a symlinked shim beside a stale/
# partial ~/.local tree, aeb links the wrong libaether.a (an old one with no
# std.audio/std.worker → `undefined reference to aether_audio_*`) and/or misses
# the nested headers (`fatal error: aether_panic.h`). Point $AETHER at the
# *dereferenced* real binary so aeb's dir resolution lands on the actual
# versioned install for both halves; also pin $AETHER_INCLUDE (which aeb honors
# first) as a backstop. No-op on a canonical /usr/local install where `ae` is
# not a symlink; only applied when the resolved tree is real (has runtime/).
_ae_bin="$(command -v "${AETHER:-ae}" 2>/dev/null || true)"
if [ -n "$_ae_bin" ]; then
    _ae_real="$(readlink -f "$_ae_bin" 2>/dev/null || true)"
    [ -n "$_ae_real" ] || _ae_real="$_ae_bin"   # BSD readlink lacks -f
    _ae_root="$(dirname "$(dirname "$_ae_real")")"
    if [ -x "$_ae_real" ] && [ -d "$_ae_root/include/aether/runtime" ]; then
        [ -z "${AETHER:-}" ]         && export AETHER="$_ae_real"
        [ -z "${AETHER_INCLUDE:-}" ] && export AETHER_INCLUDE="$_ae_root/include/aether"
        echo "  aeb toolchain pinned: AETHER=$AETHER"
    fi
fi
# -------------------------------------------------------------------------

# All examples that must compile in Phase 1.
EXAMPLES=(aecs_dark_demo disclosure_demo icons_demo pills_demo textpath_demo counter form picker styled system canvas testable calculator context_menu overlay_demo vg_tooltip each_demo rebuild_demo fileicon_demo scrollbg_demo scrollwide_demo keyhandler_demo imagefill_demo filedrop_demo barfill_demo listbox_demo table_demo transitions_demo split_demo bindings_demo tabs_demo scrollbar_demo secondary_demo typography_demo menu rbind_demo typo_demo multiselect_demo selmode_demo dblclick_demo tree_demo tabledeleg_demo weightclamp_demo flexround_demo shortcut_demo polish_demo vlist_demo wshortcut_demo multiwindow_demo timer_demo frametick_demo background_demo canvasscroll_demo canvasclip_demo canvasresetclip_demo styledbg_demo gpuview_demo gpuanim_demo native_view_demo panelcanvas_demo resizecb_demo quit_demo panelsize_demo pinsize_demo cssbatch_demo insets_demo blitborrow_demo groupalpha_demo hoverpaint_demo gradspread_demo placeholder_demo multikey_demo sheet_demo winmenu_demo reorder_demo reorderable_demo overlaytr_demo a11y_demo material_demo themes_demo csssem_demo zen_demo states_demo undo_demo roles_demo command_demo clipboard window_title openurl_demo prompt_demo)
# Examples without a test server — Phase 2 smoke-launches each.
# calculator and testable are exercised through their HTTP drivers in
# Phases 3-4, so they are not smoke-tested here.
SMOKE_EXAMPLES=(disclosure_demo icons_demo pills_demo textpath_demo counter form picker styled system canvas)
FAIL=0

OS="$(uname -s)"
case "$OS" in
    Darwin)  PLATFORM=macos ;;
    Linux)   PLATFORM=linux ;;
    # The GTK4 backend on FreeBSD (ghostbsd): the Linux path, run under an
    # Xvfb the caller starts (FreeBSD's Xvfb ships without xvfb-run).
    FreeBSD) PLATFORM=linux ;;
    MINGW*|MSYS*|CYGWIN*) PLATFORM=windows ;;
    *)       PLATFORM=unknown ;;
esac
# The host C compiler for the unit tests' links: $CC when set, else gcc
# (Linux CI, macOS's clang shim), else cc (FreeBSD has cc, not gcc).
HOST_CC="${CC:-gcc}"
command -v "$HOST_CC" >/dev/null 2>&1 || HOST_CC=cc
echo "=== aether_ui CI on $OS ($PLATFORM) ==="

# A crashing driver app leaves no explanation in its own output. Allow cores so
# a failing spec can print the faulting frame instead of a list of POSTs that
# stopped being answered. Each workflow step is a fresh shell, so this has to
# be set here rather than beside the core_pattern in the workflow.
if [ "$PLATFORM" = "linux" ]; then ulimit -c unlimited 2>/dev/null || true; fi

if [ "$PLATFORM" = "windows" ]; then
    echo "NOTICE: Windows backend uses a separate test flow."
    echo "        Run: make contrib-aether-ui-check"
    echo "        (headless widget suite + HTTP driver integration test)"
    exit 0
fi
if [ "$PLATFORM" = "unknown" ]; then
    echo "ERROR: unrecognized platform '$OS'."
    exit 1
fi

# Decide how to launch GUI binaries. On Linux CI runners without a display,
# wrap with xvfb-run so GTK4 has a framebuffer. The screen must be big enough
# that Xvfb's pointer (parked at screen centre) starts OUTSIDE the app
# window: GTK synthesizes crossing/motion events at the pointer position on
# every relayout, and a pointer sitting over the canvas fires the app's hover
# handler between test steps — rewriting the status line the assertions read.
launch_xvfb() { xvfb-run -a -s "-screen 0 3200x2000x24" "$@"; }
# Kill a launched app and everything under it. Through launch_xvfb, $! is the
# subshell running the function, so a plain kill left xvfb-run, its Xvfb and
# the app itself running: every smoke and driver phase leaked one app, and a
# full run's leftovers ran a 2 GB container out of memory (cc1 killed in the
# next build). pgrep -P is on Linux, macOS and MSYS2 alike.
tree_pids() {
    local p="$1" c
    for c in $(pgrep -P "$p" 2>/dev/null); do tree_pids "$c"; done
    echo "$p"
}
# TERM first, then KILL what is left: an app that outlives TERM keeps
# xvfb-run (a /bin/sh script, which cannot act on TERM while it waits on
# that app) and its Xvfb alive too -- ae-x64 kept one of each per smoke app
# per run until this. Once the app is gone, xvfb-run reaps its own Xvfb.
kill_tree() {
    local pids
    pids="$(tree_pids "$1")"
    kill $pids 2>/dev/null
    sleep 0.3
    kill -9 $pids 2>/dev/null
    return 0
}
LAUNCH_PREFIX=""
if [ "$PLATFORM" = "linux" ]; then
    if [ -z "${DISPLAY:-}" ] && [ -z "${WAYLAND_DISPLAY:-}" ]; then
        if command -v xvfb-run > /dev/null 2>&1; then
            LAUNCH_PREFIX="launch_xvfb"
            echo "no display detected — wrapping GUI launches with xvfb-run"
        else
            echo "NOTICE: no display and xvfb-run missing — will build-only."
            LAUNCH_PREFIX="SKIP_RUNTIME"
        fi
    fi
fi

# Run a binary that is expected to END ITSELF, and report its exit status.
#
# Neither `timeout` nor a bare launch works across this matrix: macOS ships no
# `timeout`, and GTK4 needs a framebuffer even in headless mode, so Linux has
# to go through $LAUNCH_PREFIX like every other phase. This waits on the
# process and only kills it if it overruns, so "never quit" is reported as 124
# the way `timeout` would have.
run_self_quitting() {
    local bin="$1" name="$2" limit="${3:-30}"
    local log="/tmp/ci_${name}.selfquit.log"
    # Headless ONLY when there is no display to use. GTK4's headless path
    # realizes without mapping, so nothing is ever allocated and get_width
    # answers 0 — which is exactly what this reported on Linux. Under xvfb
    # ($LAUNCH_PREFIX set) the window maps and the allocation is real. On
    # macOS there is no xvfb, and headless is what keeps a local run from
    # popping windows; allocation works there either way.
    # A GTK box with a display of its own (DISPLAY already set, as on the
    # FreeBSD lane, which starts its own Xvfb) maps the window too; headless
    # there read every width as 0 (panelsize_demo, insets_demo).
    if [ -n "${LAUNCH_PREFIX:-}" ]; then
        $LAUNCH_PREFIX "$bin" > "$log" 2>&1 &
    elif [ "$PLATFORM" = linux ] && [ -n "${DISPLAY:-}${WAYLAND_DISPLAY:-}" ]; then
        "$bin" > "$log" 2>&1 &
    else
        AETHER_UI_HEADLESS=1 "$bin" > "$log" 2>&1 &
    fi
    local pid=$!
    local ticks=0
    while kill -0 "$pid" 2>/dev/null; do
        if [ "$ticks" -ge "$((limit * 10))" ]; then
            kill_tree "$pid"
            wait "$pid" 2>/dev/null
            return 124
        fi
        sleep 0.1
        ticks=$((ticks + 1))
    done
    wait "$pid"
}

run_server_test() {
    # Launch a binary with AETHER_UI_TEST_PORT set, wait for the test server,
    # run the given test script against it, kill the binary, propagate status.
    local bin="$1" script="$2" name="$3"
    echo "--- launching $bin ---"
    # Refuse to launch into a squatted port: a stray app from an earlier
    # run answers the spec's requests and every assertion interrogates the
    # WRONG process (stale binary, mutated state) — seen as inexplicable
    # geometry failures. Fail loudly instead.
    if curl -sf -o /dev/null "http://127.0.0.1:$PORT/widgets" 2>/dev/null; then
        echo "  FAIL: $name — port $PORT already answering (stray app?)"
        return 1
    fi
    AETHER_UI_TEST_PORT="$PORT" $LAUNCH_PREFIX "$bin" > "/tmp/ci_${name}.app.log" 2>&1 &
    local pid=$!

    # Wait up to 6s for the server to come up.
    local up=0
    for _ in $(seq 1 30); do
        if curl -sf -o /dev/null "http://127.0.0.1:$PORT/widgets"; then up=1; break; fi
        sleep 0.2
    done
    if [ "$up" -ne 1 ]; then
        echo "  FAIL: $name test server never responded"
        kill_tree "$pid"; wait "$pid" 2>/dev/null
        tail -20 "/tmp/ci_${name}.app.log" | sed 's/^/       /'
        return 1
    fi

    "$script" "$PORT"
    local rc=$?
    # Close the app PROPERLY: ask the driver to shut down (the app exits by
    # the same path as the user closing the window). Signal-killing the
    # xvfb-run wrapper is only a fallback — it can leave the app child alive
    # and HOLDING THE PORT, and the next phase then interrogates the wrong
    # app (a whole family of "impossible" test failures traced back to this).
    curl -sf -m 2 -X POST "http://127.0.0.1:$PORT/shutdown" > /dev/null 2>&1
    local freed=0
    for _ in $(seq 1 25); do
        if ! curl -sf -o /dev/null "http://127.0.0.1:$PORT/widgets"; then freed=1; break; fi
        sleep 0.2
    done
    kill_tree "$pid"; wait "$pid" 2>/dev/null
    if [ "$freed" -ne 1 ]; then
        pkill -f "$bin" 2>/dev/null
        for _ in $(seq 1 25); do
            curl -sf -o /dev/null "http://127.0.0.1:$PORT/widgets" || break
            sleep 0.2
        done
    fi
    # A spec that fails AFTER the server answered leaves its diagnosis in the
    # app's own output, which was printed only on the never-responded path.
    # Without this, a mid-run crash reads as a list of "was not 2xx" lines
    # with nothing saying the process had died.
    if [ "$rc" -ne 0 ] && [ -s "/tmp/ci_${name}.app.log" ]; then
        echo "       --- $name app output (last 30 lines) ---"
        tail -30 "/tmp/ci_${name}.app.log" | sed 's/^/       /'
    fi
    # A crash (SIGBUS/SIGSEGV) leaves nothing useful in the app's own output:
    # the process is gone before it can say anything, and the spec only sees
    # POSTs that stopped being answered. macOS files a report naming the
    # faulting frame, so surface it here rather than leaving the next reader
    # to guess from "was not 2xx".
    if [ "$rc" -ne 0 ] && [ "$PLATFORM" = "linux" ] && command -v gdb > /dev/null 2>&1; then
        local core
        core="$(ls -t /tmp/core."$(basename "$bin")".* 2>/dev/null | head -1)"
        if [ -n "$core" ]; then
            echo "       --- $name backtrace from $core ---"
            gdb -batch -ex 'thread apply all bt' "$bin" "$core" 2>/dev/null \
                | head -60 | sed 's/^/       /'
            rm -f "$core"
        fi
    fi
    if [ "$rc" -ne 0 ] && [ "$PLATFORM" = "macos" ]; then
        local base report
        base="$(basename "$bin")"
        report="$(ls -t "$HOME/Library/Logs/DiagnosticReports/${base}"*.ips 2>/dev/null | head -1)"
        if [ -n "$report" ]; then
            echo "       --- $name crash report: $(basename "$report") ---"
            sed -n '1,80p' "$report" | sed 's/^/       /'
        fi
    fi
    return $rc
}

run_smoke_test() {
    # Launch a GUI binary, give it 1.5s to open its window, then kill it.
    # Pass iff the process is still alive at the deadline. A process that
    # exited early is a crash (missing widget impl, null deref on init,
    # backend API mismatch) — propagate non-zero and dump the tail.
    local bin="$1" name="$2"
    $LAUNCH_PREFIX "$bin" > "/tmp/ci_smoke_${name}.log" 2>&1 &
    local pid=$!
    sleep 1.5
    if kill -0 "$pid" 2>/dev/null; then
        echo "  OK   $name (alive 1.5s)"
        kill_tree "$pid"; wait "$pid" 2>/dev/null
        return 0
    fi
    wait "$pid" 2>/dev/null; local rc=$?
    echo "  FAIL $name (exited early, rc=$rc)"
    tail -15 "/tmp/ci_smoke_${name}.log" | sed 's/^/       /'
    return 1
}

# AeVG port unit tests — pure Aether (no GTK/display), so they run even
# under SKIP_RUNTIME. Each is a self-contained `main()` that exits non-zero
# on the first failed assertion. Append new modules' tests here as they land.
AEVG_TESTS=(test_font test_text_path test_transform test_normalizer test_easing test_parser test_bbox test_region test_blur test_rasterize test_grammar_utils test_chrome test_grammar_context test_grammar_element test_grammar_rendering test_grammar_style test_grammar_shapes test_grammar_factories test_grammar_animations test_loader test_grammar_defs test_grammar_text test_grammar_css test_grammar_events test_path_builder test_polypath test_vg3d test_render_as_raster test_grammar_bind test_grammar_reactive test_gradient_transform test_font_family test_refresh test_reactive_bindpos test_backend_dispatch test_raster_roundtrip test_filter_routing test_gradient_fill test_vg test_transpiler test_grammar_interaction test_vg_interactive test_vg_when test_vg_bindto test_vg_bindpos test_vg_clock test_vg_hidpi test_vg_anim test_live_region test_effects test_behavior test_base64 test_vg_image test_vg_live_paint)
# Tests that exercise the REAL cairo text metrics — linked against the GTK4
# backend (the pure-Aether AEVG_TESTS link with $(ae cflags) only).
AEVG_GTK_TESTS=(test_text_metrics test_group_pixels)
# test_group_pixels rasterizes through the GTK backend, so it needs a display;
# test_text_metrics only measures text and does not. Running the display-bound
# one bare is what failed a headless runner with "Failed to open display" even
# though the workflow installs xvfb.
AEVG_GTK_NEEDS_DISPLAY=" test_group_pixels "

# `ae cflags --libs` emits the transitive deps that libaether.a was
# built with (PCRE2 / OpenSSL / zlib / nghttp2 — see Aether CHANGELOG
# [current], the cmd_cflags fix). So `$(ae cflags)` alone is enough
# for any module that imports std.regex / std.cryptography / std.http
# / std.zlib. The earlier per-dep workaround is no longer needed.

# ---------------------------------------------------------------------------
# Guard: every spec must RETURN its run_summary verdict.
#
# Since aether v0.613.0, run_summary returns the verdict (0 green / 1 failed)
# rather than exit()-ing, so that cleanup after a run -- arena.destroy,
# server_stop, sqlite.close -- is not skipped on exactly the failing runs where
# a leaked arena or an orphaned listener does the most damage. run_server_test
# below judges a spec purely by its process exit status, and main()'s return
# value IS that status.
#
# So a bare `spec.run_summary(fw)` as the last statement discards the verdict
# and A FAILING SUITE REPORTS GREEN. That is the worst failure mode a test
# harness has: silence that looks like success.
#
# This was already documented in ci.yml, in capitals, directly above the pin.
# A comment did not stop it happening anyway -- 83 specs were converted to the
# bare form in one commit and CI could not have told anyone. Hence a check
# rather than a note.
echo "=== Phase 0a: specs return their run_summary verdict ==="
bare_verdict=$(grep -rn --include='spec_*.ae' -E '^[[:space:]]*spec\.run_summary\(' \
                    "$ROOT/tests" "$ROOT/vg/test" 2>/dev/null || true)
if [ -n "$bare_verdict" ]; then
    echo "  FAIL: these specs drop the verdict, so a failing run would report green:"
    echo "$bare_verdict" | sed 's/^/       /'
    echo "       use: return spec.run_summary(fw)"
    FAIL=$((FAIL + 1))
else
    echo "  OK   every spec returns its verdict"
fi

echo
echo "=== Phase 0: AeVG unit tests (pure Aether) ==="
for t in "${AEVG_TESTS[@]}"; do
    src="vg/test/${t}.ae"
    cfile="build/aevg_${t}.c"
    bin="build/aevg_${t}"
    if ! aetherc --lib "$ROOT" "$src" "$cfile" > "/tmp/ci_aevg_${t}.log" 2>&1; then
        echo "  FAIL $t (compile)"
        tail -15 "/tmp/ci_aevg_${t}.log" | sed 's/^/       /'
        FAIL=$((FAIL + 1))
        continue
    fi
    # vg/module.ae declares the cairo text-metric externs; pure-Aether tests
    # link no GTK backend, so a zero-returning stub resolves those symbols
    # (tests importing vg never call them — test_text_metrics uses the real
    # backend via AEVG_GTK_TESTS below).
    if ! "$HOST_CC" "$cfile" vg/test/text_metrics_stub.c $(ae cflags) -o "$bin" >> "/tmp/ci_aevg_${t}.log" 2>&1; then
        echo "  FAIL $t (link)"
        tail -15 "/tmp/ci_aevg_${t}.log" | sed 's/^/       /'
        FAIL=$((FAIL + 1))
        continue
    fi
    if "$bin" > "/tmp/ci_aevg_${t}_run.log" 2>&1; then
        echo "  OK   $t"
    else
        echo "  FAIL $t (run)"
        tail -15 "/tmp/ci_aevg_${t}_run.log" | sed 's/^/       /'
        FAIL=$((FAIL + 1))
    fi
done

# GTK-backend-linked unit tests: those exercising the real cairo text
# metrics (aether_ui_text_measure etc.) need the GTK4 backend + gtk4 libs
# linked, unlike the pure-Aether tests above. Skipped when GTK is absent
# (e.g. build-only runners); pure metrics have no display dependency, so
# they run even under SKIP_RUNTIME as long as gtk4 dev libs are present.
if pkg-config --exists gtk4 2>/dev/null; then
    for t in "${AEVG_GTK_TESTS[@]}"; do
        src="vg/test/${t}.ae"; cfile="build/aevg_${t}.c"; bin="build/aevg_${t}"
        if ! aetherc --lib "$ROOT" "$src" "$cfile" > "/tmp/ci_aevg_${t}.log" 2>&1; then
            echo "  FAIL $t (compile)"; tail -15 "/tmp/ci_aevg_${t}.log" | sed 's/^/       /'; FAIL=$((FAIL + 1)); continue
        fi
        # epoxy explicitly: gpuview (#92) calls GL from the GTK4 backend, and
        # gtk4.pc exposes neither epoxy's headers nor its library.
        if ! "$HOST_CC" $(pkg-config --cflags gtk4) $(pkg-config --cflags epoxy) "$cfile" \
                backend/aether_ui_gtk4.c backend/aether_ui_system_extras.c backend/aether_ui_sni.c \
                backend/aether_ui_test_server.c \
                $(ae cflags) -pthread -lm $(pkg-config --libs gtk4) $(pkg-config --libs epoxy) -o "$bin" >> "/tmp/ci_aevg_${t}.log" 2>&1; then
            echo "  FAIL $t (link)"; tail -15 "/tmp/ci_aevg_${t}.log" | sed 's/^/       /'; FAIL=$((FAIL + 1)); continue
        fi
        runner=""
        case "$AEVG_GTK_NEEDS_DISPLAY" in
            *" $t "*)
                if [ "$LAUNCH_PREFIX" = "SKIP_RUNTIME" ]; then
                    echo "  SKIP $t (needs a display; none available and no xvfb-run)"
                    continue
                fi
                runner="$LAUNCH_PREFIX"
                # Xvfb runs need the cairo renderer (GTK's NGL on llvmpipe
                # churns memory), the same reason the GUI spec phases set it.
                case "$runner" in *xvfb*) export GSK_RENDERER=cairo ;; esac
                ;;
        esac
        if $runner "$bin" > "/tmp/ci_aevg_${t}_run.log" 2>&1; then
            echo "  OK   $t (gtk-linked)"
        else
            echo "  FAIL $t (run)"; tail -15 "/tmp/ci_aevg_${t}_run.log" | sed 's/^/       /'; FAIL=$((FAIL + 1))
        fi
        unset GSK_RENDERER
    done
else
    echo "  SKIP AEVG_GTK_TESTS (gtk4 dev libs absent)"
fi

# vg/chart (the Chartist port) unit tests: Chartist's own specs ported with
# their expected values, pure Aether like the AeVG tests above (they draw
# through vg only onto the recording backend, so the same text-metrics stub
# links them). They live beside the module in vg/chart/test.
CHART_TESTS=(test_chart_core test_chart_path test_chart_charts test_chart_render)
echo
echo "=== Phase 0: vg/chart unit tests (Chartist's specs, ported) ==="
for t in "${CHART_TESTS[@]}"; do
    src="vg/chart/test/${t}.ae"; cfile="build/chart_${t}.c"; bin="build/chart_${t}"
    if ! aetherc --lib "$ROOT" "$src" "$cfile" > "/tmp/ci_chart_${t}.log" 2>&1; then
        echo "  FAIL $t (compile)"; tail -15 "/tmp/ci_chart_${t}.log" | sed 's/^/       /'; FAIL=$((FAIL + 1)); continue
    fi
    if ! "$HOST_CC" "$cfile" vg/test/text_metrics_stub.c $(ae cflags) -o "$bin" >> "/tmp/ci_chart_${t}.log" 2>&1; then
        echo "  FAIL $t (link)"; tail -15 "/tmp/ci_chart_${t}.log" | sed 's/^/       /'; FAIL=$((FAIL + 1)); continue
    fi
    if "$bin" > "/tmp/ci_chart_${t}_run.log" 2>&1; then
        echo "  OK   $t ($(tail -1 "/tmp/ci_chart_${t}_run.log" | sed 's/^[^:]*: //'))"
    else
        echo "  FAIL $t (run)"; grep "FAIL" "/tmp/ci_chart_${t}_run.log" | head -15 | sed 's/^/       /'; FAIL=$((FAIL + 1))
    fi
done

# App-level pure engine tests — game logic factored out of an app with NO UI
# or vg dependency, so it's unit-testable in isolation (the svg_tetris engine:
# collision, rotation, line-clear, ghost, scoring, game-over). Compiled with
# the app's own dir on the lib path so `import <engine>` resolves; links
# libaether only (no backend, no text-metrics stub — nothing imports vg).
ENGINE_TESTS=("svg_tetris:test_tetris_engine" "falling_blocks:test_fb_engine" "rubiks_cube:test_cube_engine" "font_picker:test_picker_engine" "maerkdown:test_mdown")
for spec in "${ENGINE_TESTS[@]}"; do
    app="${spec%%:*}"; t="${spec##*:}"
    src="apps/${app}/${t}.ae"; cfile="build/eng_${t}.c"; bin="build/eng_${t}"
    if ! aetherc --lib "apps/${app}" "$src" "$cfile" > "/tmp/ci_eng_${t}.log" 2>&1; then
        echo "  FAIL $t (compile)"; tail -15 "/tmp/ci_eng_${t}.log" | sed 's/^/       /'; FAIL=$((FAIL + 1)); continue
    fi
    if ! "$HOST_CC" "$cfile" $(ae cflags) -o "$bin" >> "/tmp/ci_eng_${t}.log" 2>&1; then
        echo "  FAIL $t (link)"; tail -15 "/tmp/ci_eng_${t}.log" | sed 's/^/       /'; FAIL=$((FAIL + 1)); continue
    fi
    if "$bin" > "/tmp/ci_eng_${t}_run.log" 2>&1; then
        echo "  OK   $t"
    else
        echo "  FAIL $t (run)"; tail -15 "/tmp/ci_eng_${t}_run.log" | sed 's/^/       /'; FAIL=$((FAIL + 1))
    fi
done
echo

echo "=== Phase 1: build all aether_ui examples (aeb fan-out) ==="
# Each example is a per-app .build.ae node under examples/<app>/; the root
# .all.ae scans + deps them, so this one command builds all 11 (cached,
# parallel). Binaries land at target/build/examples/<app>/bin/<app>; EX_BIN
# resolves that for the smoke/driver phases below.
EX_BIN() { echo "$ROOT/target/build/examples/$1/bin/$1"; }
if ( cd "$ROOT" && aeb .all.ae ) > /tmp/ci_build_all.log 2>&1; then
    for ex in "${EXAMPLES[@]}"; do
        if [ -x "$(EX_BIN "$ex")" ]; then echo "  OK   $ex"; else
            echo "  FAIL $ex (no binary)"; FAIL=$((FAIL + 1)); fi
    done
else
    echo "  FAIL: aeb .all.ae fan-out build failed"
    # The fan-out prints one progress line per app, so a plain tail is all
    # progress and no diagnostic. A bare grep is not enough either: a linker
    # error names the missing symbol on the lines AFTER the match, so print
    # trailing context or the actual cause is lost (that is how an undefined
    # symbol reached CI as four unattributed line numbers).
    #
    # And not make's own lines: under the parallel scheduler every node that
    # fails costs one `make: *** [bldr.mk:N: label] Error 1`, printed BEFORE
    # aeb's per-node "FAILED (see <log>)" dump, so a change that breaks every
    # node (a compiler bump) filled the 60 lines with 60 make lines and the
    # actual diagnostic never reached the CI log (#147).
    grep -nEi -A6 "error|failed|undefined|cannot |no such file" /tmp/ci_build_all.log \
        | grep -viE "^[0-9]+[:-] *build: |make: \*\*\*" | head -60 | sed 's/^/       /'
    echo "       --- last 60 lines ---"
    tail -60 /tmp/ci_build_all.log | sed 's/^/       /'
    FAIL=$((FAIL + 1))
fi

# Contrib-dependent apps are deliberately outside the .all.ae fan-out: they link
# archives (libaether_sqlite, libaether_avcodec) that a clean checkout does not
# have, so including them would make every fresh clone and every CI run red for
# a missing optional dependency. Build them only when the archive is actually
# present, and say plainly when they are skipped rather than passing silently.
CONTRIB_LIB_DIR="$(ae cflags --libs 2>/dev/null | tr ' ' '\n' | grep -E '^-L' | head -1 | sed 's/^-L//')"
LISMUSIC_BUILT=0
echo "=== Phase 1b: contrib apps (built only when their archives exist) ==="
contrib_app() {
    app="$1"; archive="$2"
    if [ -n "$CONTRIB_LIB_DIR" ] && [ -f "$CONTRIB_LIB_DIR/lib$archive.a" ]; then
        if ( cd "$ROOT" && aeb "apps/$app/.build.contrib.ae" ) > "/tmp/ci_contrib_$app.log" 2>&1; then
            echo "  OK   $app"
            return 0
        fi
        echo "  FAIL $app (lib$archive.a present but the build failed)"
        tail -30 "/tmp/ci_contrib_$app.log" | sed 's/^/       /'
        FAIL=$((FAIL + 1))
        return 1
    fi
    echo "  SKIP $app (lib$archive.a not installed; see roadmap.md for its manual build)"
    return 1
}
contrib_app LisMusic    aether_sqlite  && LISMUSIC_BUILT=1
contrib_app video_frame aether_avcodec || true

# Phase 1.5: RUN the headless AeVG renderers (build was done by the .all.ae
# fan-out in Phase 1 — every vg app is a apps/<name>/ node now). The
# value here is RUNTIME coverage the build-only fan-out can't give: each writes
# a PNG, exercising the raster-blit + draw-region compose path. Linux/GTK only.
AEVG_BIN() { echo "$ROOT/target/build/apps/$1/bin/$1"; }
if [ "$PLATFORM" = "linux" ]; then
    echo "  --- AeVG headless renderers (run → PNG) ---"
    run_png() {  # $1=app $2=desc
        local bin; bin="$(AEVG_BIN "$1")"
        # HONOUR $LAUNCH_PREFIX like every other runtime phase. "Headless
        # renderer" means no WINDOW -- GTK still needs a display connection to
        # initialise, so on a DISPLAY-less box these died with
        # "Gtk-WARNING: cannot open display" while every other phase was
        # correctly wrapped in xvfb-run. Found by the first fresh-box run
        # (asks/ci-sh-on-a-fresh-headless-box.md).
        if [ "$LAUNCH_PREFIX" = "SKIP_RUNTIME" ]; then
            echo "  SKIP $1 ($2 — no display, no xvfb-run)"
            return
        fi
        if [ -x "$bin" ] \
                && AEVG_OUT="/tmp/ci_$1.png" $LAUNCH_PREFIX "$bin" > "/tmp/ci_run_$1.log" 2>&1 \
                && [ -f "/tmp/ci_$1.png" ]; then
            echo "  OK   $1 ($2)"
        else
            echo "  FAIL $1"
            tail -15 "/tmp/ci_run_$1.log" 2>/dev/null | sed 's/^/       /'
            FAIL=$((FAIL + 1))
        fi
    }
    run_png aevg_live_png   "live raster + draw region composite"
    run_png aevg_video_png  "raw-RGBA clip in a live region"
    run_png analog_clock_png "one-frame clock render"
fi

if [ "$FAIL" -gt 0 ]; then
    echo
    echo "=== CI result: $FAIL build failure(s) — skipping runtime phases ==="
    exit 1
fi

if [ "$LAUNCH_PREFIX" = "SKIP_RUNTIME" ]; then
    echo
    echo "=== CI result: builds passed; runtime phases skipped (no display) ==="
    exit 0
fi

echo
echo "=== Phase 1c: C-level widget suite (tests/test_widgets.c) ==="
# Nothing in this repo built this file, so it rotted unnoticed: a stale
# ../aether_ui_backend.h include (the header moved into backend/) and a 6-arg
# call to an 8-arg canvas_stroke ABI meant it had not compiled for a long
# while. Building it here is what keeps it honest. It links the same backend
# as any app, via build.sh, and runs headless.
if ./build.sh tests/test_widgets.c test_widgets > /tmp/ci_test_widgets_build.log 2>&1; then
    # $LAUNCH_PREFIX, same as every other runtime phase. The suite sets
    # AETHER_UI_HEADLESS itself, which keeps every modal from blocking, but
    # GTK still needs a display to OPEN, so on Linux this goes through xvfb
    # exactly like the smoke launches do.
    if $LAUNCH_PREFIX ./build/test_widgets > /tmp/ci_test_widgets.log 2>&1; then
        echo "  OK   $(tail -1 /tmp/ci_test_widgets.log)"
    else
        echo "  FAIL test_widgets"
        tail -20 /tmp/ci_test_widgets.log | sed 's/^/       /'
        FAIL=$((FAIL + 1))
    fi
else
    echo "  FAIL test_widgets (build)"
    tail -20 /tmp/ci_test_widgets_build.log | sed 's/^/       /'
    FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 1c3: headless UI-logic tests (tests/<name>/) ==="
# An .ae program that asserts against ui/module.ae and exits non-zero, with no
# window and no driver. Every other runtime phase needs a window: the driver
# specs serve their HTTP endpoint from a real one, so none of them can run on a
# display-less box, and none can run at all on a developer machine without
# opening one. A toolkit invariant that holds in pure Aether belongs here.
#
# Built by the .all.ae fan-out (it scans tests/**/.build.ae), so a compile
# failure has already been reported by Phase 1. This phase RUNS them.
UI_TESTS=(derived_views selection_survives tree_selection list_invariants platform_claims sort_keeps_model headless_canvas string_ownership undo_stack undo_group style_release ctxmenu_rebuild no_echo roundtrip keymap docs_snippets min_size state_batch background_for style_churn reorderable)
UT_BIN() { echo "$ROOT/target/build/tests/$1/bin/$1"; }
for ut in "${UI_TESTS[@]}"; do
    bin="$(UT_BIN "$ut")"
    if [ ! -x "$bin" ]; then
        echo "  FAIL $ut (not built)"
        FAIL=$((FAIL + 1))
        continue
    fi
    # Headless explicitly, like Phase 1c: no window is wanted, but GTK still
    # needs a display to initialise, so $LAUNCH_PREFIX stays.
    if AETHER_UI_HEADLESS=1 $LAUNCH_PREFIX "$bin" > "/tmp/ci_uitest_${ut}.log" 2>&1; then
        echo "  OK   $ut ($(tail -1 "/tmp/ci_uitest_${ut}.log"))"
    else
        echo "  FAIL $ut"
        tail -20 "/tmp/ci_uitest_${ut}.log" | sed 's/^/       /'
        FAIL=$((FAIL + 1))
    fi
done

echo
echo "=== Phase 1d: Win32 backend cross-compile check ==="
# The Win32 backend is the one nobody here can run: there is no Windows leg in
# CI, so its sources were edited and shipped WITHOUT EVER BEING COMPILED. Eight
# commits touched aether_ui_win32.c in two days that way. A mingw-w64
# cross-compiler checks them for the price of an apt package and about a
# second, which is not a substitute for running the thing, but it is the
# difference between "mirrors the other backends" and "is known to build".
#
# -Wall -Werror. The gate deliberately ran at the default level while there
# was a backlog of pre-existing warnings, because failing a change for six
# warnings it did not introduce teaches people to ignore the gate. The backlog
# is zero now, so the ratchet closes: this is the one backend nobody here can
# run, and -Wall is the only reader it gets. It already earned its keep --
# -Wmisleading-indentation is what surfaced a gradient-stop path that clamped
# alpha and packed the other three components unclamped.
W32_CC=""
for cc in x86_64-w64-mingw32-gcc i686-w64-mingw32-gcc; do
    command -v "$cc" > /dev/null 2>&1 && { W32_CC="$cc"; break; }
done
if [ -n "$W32_CC" ]; then
    w32_fail=0
    for src in backend/aether_ui_win32.c \
               backend/aether_ui_test_server.c \
               backend/aether_ui_system_extras.c; do
        if "$W32_CC" -fsyntax-only -Wall -Werror -Ibackend "$ROOT/$src" \
                > "/tmp/ci_w32_$(basename "$src").log" 2>&1; then
            echo "  OK   $(basename "$src")"
        else
            echo "  FAIL $(basename "$src")"
            grep -E ": (error|warning):" "/tmp/ci_w32_$(basename "$src").log" | head -10 | sed 's/^/       /'
            w32_fail=1
        fi
    done
    # Syntax is not the whole story. A Windows API declared in a header whose
    # IMPORT LIBRARY is missing compiles perfectly and fails at link, which is
    # invisible to everyone who cannot build on Windows. Proven, not assumed:
    # dropping -lole32 leaves the syntax check at 0 errors while the link
    # reports __imp_CoCreateInstance and three more.
    #
    # The only thing between this and a real binary is the libaether runtime,
    # which has no Windows build here; tests/win32/win32_runtime_test.c
    # supplies it and says what to do when it stops being enough. That file is
    # also the binary CI runs under Wine, so this link uses the same sources
    # the runtime check does rather than a second stub that could drift.
    if [ "$w32_fail" -eq 0 ]; then
        if "$W32_CC" -o /tmp/ci_w32_link.exe \
                "$ROOT/tests/win32/win32_runtime_test.c" \
                "$ROOT/backend/aether_ui_win32.c" \
                "$ROOT/backend/aether_ui_test_server.c" \
                "$ROOT/backend/aether_ui_system_extras.c" \
                -I"$ROOT/backend" \
                -luser32 -lgdi32 -lgdiplus -lmsimg32 -lcomctl32 -lcomdlg32 \
                -lshell32 -lole32 -loleaut32 -luuid -loleacc -ldwmapi \
                -luxtheme -lws2_32 -lbcrypt > /tmp/ci_w32_link.log 2>&1; then
            echo "  OK   links against the Windows import libraries"
        else
            echo "  FAIL link"
            grep -E "undefined reference|error:" /tmp/ci_w32_link.log \
                | head -10 | sed 's/^/       /'
            w32_fail=1
        fi
    fi
    [ "$w32_fail" -eq 0 ] || FAIL=$((FAIL + 1))
else
    # Say so rather than passing quietly: a skipped gate that looks like a
    # green one is how the Win32 sources drifted in the first place.
    echo "  SKIP no mingw-w64 cross-compiler (install gcc-mingw-w64-x86-64 to enable)"
fi

echo
echo "=== Phase 1c2: backend ABI parity across all five backends ==="
# Compiling and linking a backend proves it builds; it proves nothing about
# what it OMITS. A missing entry point is invisible to every other phase,
# because nothing here calls it: the iOS lane links against a stub, and the
# Win32 lane only cross-compiles. Seven functions had drifted onto three
# backends and not the fourth before this existed, so an iOS app calling any
# of them would have failed at link with no earlier warning.
if python3 "$SCRIPT_DIR/tests/scripts/check_backend_parity.py"; then
    echo "  OK   backend ABI parity"
else
    echo "  FAIL backend ABI parity"
    FAIL=$((FAIL + 1))
fi

echo "=== Phase 1e: iOS/iPadOS (UIKit) backend compile+link check ==="
# The UIKit backend is, like Win32, one nobody here can RUN: there is no iOS leg
# in CI and no iOS build of libaether. But the iOS SDK ships with Xcode, so its
# sources can be COMPILED and LINKED against the real UIKit frameworks in a few
# seconds — the difference between "mirrors the other backends" and "is known to
# build". -Wall -Werror, the same ratchet Phase 1d holds the Win32 backend to.
# The shared driver/system sources are checked here too, since they must compile
# for iOS (BSD sockets + POSIX; no AppKit) just as they do for Windows.
IOS_SDK="$(xcrun --sdk iphonesimulator --show-sdk-path 2>/dev/null)"
if [ -n "$IOS_SDK" ] && [ -d "$IOS_SDK" ]; then
    IOS_CLANG="$(xcrun --sdk iphonesimulator -f clang 2>/dev/null)"
    IOS_TGT="arm64-apple-ios17.0-simulator"
    ios_fail=0
    for src in backend/aether_ui_uikit.m \
               backend/aether_ui_test_server.c \
               backend/aether_ui_system_extras.c; do
        if "$IOS_CLANG" -fobjc-arc -fsyntax-only -Wall -Werror \
                -target "$IOS_TGT" -isysroot "$IOS_SDK" -Ibackend "$ROOT/$src" \
                > "/tmp/ci_ios_$(basename "$src").log" 2>&1; then
            echo "  OK   $(basename "$src")"
        else
            echo "  FAIL $(basename "$src")"
            grep -E ": (error|warning):" "/tmp/ci_ios_$(basename "$src").log" \
                | head -10 | sed 's/^/       /'
            ios_fail=1
        fi
    done
    # Syntax is not the whole story (Phase 1d's lesson): a framework whose symbols
    # are missing compiles fine and fails at link. tests/ios/link_stub.c supplies
    # the handful of libaether symbols the backend reads (there is no iOS build of
    # libaether here) plus a main(), so the link proves every -framework resolves.
    if [ "$ios_fail" -eq 0 ]; then
        if "$IOS_CLANG" -fobjc-arc -target "$IOS_TGT" -isysroot "$IOS_SDK" -Ibackend \
                "$ROOT/backend/aether_ui_uikit.m" \
                "$ROOT/backend/aether_ui_test_server.c" \
                "$ROOT/backend/aether_ui_system_extras.c" \
                "$ROOT/tests/ios/link_stub.c" \
                -framework UIKit -framework Foundation -framework QuartzCore \
                -framework CoreGraphics -framework CoreText -framework ImageIO -framework UserNotifications \
                -o /tmp/ci_ios_link > /tmp/ci_ios_link.log 2>&1; then
            echo "  OK   links against the UIKit frameworks"
        else
            echo "  FAIL link"
            grep -iE "undefined|error:" /tmp/ci_ios_link.log | head -10 | sed 's/^/       /'
            ios_fail=1
        fi
    fi
    # Compiling and linking prove it builds; they prove nothing about the
    # pixels. UIKit runs natively on macOS via Mac Catalyst, so drive the REAL
    # canvas ABI (aether_ui_uikit.m's Core Graphics executor), read the pixels
    # back with canvas_read_pixel and assert the colours — no simulator, device
    # or iOS build of libaether. This is what turns "is known to build" into "is
    # known to render". See tests/ios/render_probe.m. (macOS-host only.)
    if [ "$ios_fail" -eq 0 ]; then
        MAC_SDK="$(xcrun --sdk macosx --show-sdk-path 2>/dev/null)"
        CAT_FW="$MAC_SDK/System/iOSSupport/System/Library/Frameworks"
        MAC_CLANG="$(xcrun --sdk macosx -f clang 2>/dev/null)"
        if [ -n "$MAC_SDK" ] && [ -d "$CAT_FW" ]; then
            if "$MAC_CLANG" -fobjc-arc -target "$(uname -m)-apple-ios15.0-macabi" \
                    -isysroot "$MAC_SDK" -iframework "$CAT_FW" -Ibackend \
                    "$ROOT/tests/ios/render_probe.m" \
                    "$ROOT/backend/aether_ui_uikit.m" \
                    "$ROOT/backend/aether_ui_test_server.c" \
                    "$ROOT/backend/aether_ui_system_extras.c" \
                    -framework UIKit -framework Foundation -framework QuartzCore \
                    -framework CoreGraphics -framework CoreText -framework ImageIO -framework UserNotifications \
                    -o /tmp/ci_ios_render > /tmp/ci_ios_render.log 2>&1 \
               && AETHER_UI_RENDER_PROBE_PNG=/tmp/ci_ios_render.png \
                    /tmp/ci_ios_render >> /tmp/ci_ios_render.log 2>&1; then
                echo "  OK   canvas renders (pixels checked via Mac Catalyst)"
            else
                echo "  FAIL render probe"
                grep -iE "FAIL|error:|undefined" /tmp/ci_ios_render.log \
                    | head -10 | sed 's/^/       /'
                ios_fail=1
            fi
        else
            echo "  SKIP render probe (no Mac Catalyst SDK on this host)"
        fi
    fi
    [ "$ios_fail" -eq 0 ] || FAIL=$((FAIL + 1))
else
    # Say so rather than passing quietly, exactly as Phase 1d does for mingw.
    echo "  SKIP no iOS SDK (install Xcode + the iOS platform to enable)"
fi

echo
echo "=== Phase 1e2: iOS simulator run (listbox_demo through the driver) ==="
# Compiling, linking and a Catalyst render prove the backend builds and
# paints; they say nothing about an app RUNNING on iOS. `ae build
# --target=<arch>-ios-simulator --emit=staticlib` (aether 0.6xx, the
# prerequisite #22 named) builds the Aether runtime for the simulator, so an
# example can now be linked for real -- its portable C from aetherc, the
# UIKit backend, the driver -- wrapped in a bundle (tests/ios/Info.plist),
# installed in a booted simulator and driven over the same AetherUIDriver
# port every other backend answers: tests/listbox_demo's spec runs against
# it unchanged. Rows rendered by UIKit, a tap selecting one through the
# DSL's closure, selection surviving an update: that is #22's acceptance,
# on every push.
#
# The simulator shares the host's loopback, so the spec talks to 127.0.0.1
# as usual. Environment reaches the app through SIMCTL_CHILD_*.
IOS_SIM_UDID=""
ios_sim_pick() {
    # An available iPhone, booted if one already is (a stale boot is fine to
    # reuse), else the first listed. Prints the UDID.
    xcrun simctl list devices available -j 2>/dev/null | jq -r '
        [.devices | to_entries[]
         | select(.key | contains("iOS"))
         | .value[] | select(.name | startswith("iPhone"))]
        | (map(select(.state == "Booted")) + .) | .[0].udid // empty'
}
# What the simulator knows when the app did not answer: is the process
# alive (a simulator app is a host process), what it logged, and whether it
# left a crash report -- the exception and the thread that raised it are in
# the report's first lines.
ios_sim_diagnose() {
    echo "       -- process:"
    pgrep -fl AetherUIProbe 2>/dev/null | sed 's/^/       /' || echo "       (not running)"
    echo "       -- app stdout/stderr:"
    tail -20 /tmp/ci_ios_sim.app.log /tmp/ci_ios_sim.app.err 2>/dev/null | sed 's/^/       /'
    echo "       -- unified log (last 2 minutes, the app's process):"
    xcrun simctl spawn "$IOS_SIM_UDID" log show --last 2m --style compact \
        --predicate 'process == "AetherUIProbe"' 2>/dev/null | tail -40 | sed 's/^/       /'
    echo "       -- crash reports:"
    local rep
    rep="$(ls -t ~/Library/Logs/DiagnosticReports/AetherUIProbe* 2>/dev/null | head -1)"
    if [ -n "$rep" ]; then
        echo "       $rep"
        # .ips: a JSON header line, then the JSON report. The exception, the
        # uncaught NSException's own message and backtrace if there was
        # one (that is where an out-of-range index was raised), and the
        # faulting thread's frames, each with its image.
        python3 - "$rep" <<'PY' 2>&1 | sed 's/^/       /'
import json, sys
raw = open(sys.argv[1]).read().split('\n', 1)[1]
r = json.loads(raw)
imgs = r.get('usedImages', [])
def frame(f):
    i = f.get('imageIndex', -1)
    img = imgs[i].get('name', '?') if 0 <= i < len(imgs) else '?'
    return '%-28s %s %s%s' % (img, f.get('symbol', '+%d' % f.get('imageOffset', 0)),
                              f.get('sourceFile', ''), (':%d' % f['sourceLine']) if 'sourceLine' in f else '')
print('exception:', json.dumps(r.get('exception')))
print('termination:', json.dumps(r.get('termination')))
for k in ('asi', 'ktriageinfo'):
    if r.get(k): print(k + ':', json.dumps(r[k])[:600])
leb = r.get('lastExceptionBacktrace')
if leb:
    print('last exception backtrace:')
    for f in leb[:25]: print('   ', frame(f))
ft = r.get('faultingThread', 0)
threads = r.get('threads', [])
if ft < len(threads):
    t = threads[ft]
    print('faulting thread %d %s %s:' % (ft, t.get('name', ''), t.get('queue', '')))
    for f in t.get('frames', [])[:25]: print('   ', frame(f))
PY
    else
        echo "       (none)"
    fi
}
ios_sim_cleanup() {
    [ -n "$IOS_SIM_UDID" ] || return 0
    xcrun simctl terminate "$IOS_SIM_UDID" dev.aether.ui.simprobe > /dev/null 2>&1 || true
    xcrun simctl uninstall "$IOS_SIM_UDID" dev.aether.ui.simprobe > /dev/null 2>&1 || true
    xcrun simctl shutdown "$IOS_SIM_UDID" > /dev/null 2>&1 || true
}
if [ "$PLATFORM" != "macos" ] || [ -z "$IOS_SDK" ] || [ ! -d "$IOS_SDK" ]; then
    echo "  SKIP needs a Mac with the iOS simulator SDK"
elif [ "$ios_fail" -ne 0 ]; then
    echo "  SKIP Phase 1e failed"
elif ! ae build --help 2>&1 | grep -q "ios-simulator"; then
    echo "  SKIP this ae has no iOS target (aether #1385)"
else
    sim_fail=0
    SIM_DIR="$ROOT/build/ios"
    SIM_APP="$SIM_DIR/AetherUIProbe.app"
    rm -rf "$SIM_DIR"; mkdir -p "$SIM_APP"
    case "$(uname -m)" in
        arm64)  SIM_AE_TARGET="aarch64-ios-simulator"; SIM_CLANG_TGT="arm64-apple-ios17.0-simulator" ;;
        *)      SIM_AE_TARGET="x86_64-ios-simulator";  SIM_CLANG_TGT="x86_64-apple-ios17.0-simulator" ;;
    esac
    # 1. The runtime, compiled for the simulator (see tests/ios/runtime_seed.ae).
    if ! AETHER_IOS_MIN=17.0 ae build --target="$SIM_AE_TARGET" --emit=staticlib \
            "$ROOT/tests/ios/runtime_seed.ae" -o "$SIM_DIR/libaether_sim.a" \
            > /tmp/ci_ios_sim_runtime.log 2>&1; then
        echo "  FAIL runtime archive for $SIM_AE_TARGET"
        tail -15 /tmp/ci_ios_sim_runtime.log | sed 's/^/       /'
        sim_fail=1
    else
        echo "  OK   runtime archive for $SIM_AE_TARGET"
    fi
    # 2-5 for each example: listbox_demo (#22's acceptance: rows rendered by
    # UIKit, a tap selecting one, selection surviving an update), then
    # frametick_demo (the frame clock on CADisplayLink, pinned so a silent
    # fallback to the timer fails, and timer_once), vg_image_demo and
    # vgpaint_demo (vg's live paint and the right/double-click hooks on UIKit),
    # spacercanvas_demo (spacers take a stack's slack before a canvas does),
    # pixelated_demo (image_rendering "pixelated": CoreGraphics nearest),
    # submit_demo (on_submit: Return in a field), datagrid_demo (the
    # virtualised grid, with a vslider: a rotated UISlider in a box),
    # a11y_demo (roles, names, and a11y_announce through UIAccessibility),
    # vg_chart_demo (vg/chart's charts on UIKit's vg scenes).
    for SIM_EX in listbox_demo frametick_demo vg_image_demo vgpaint_demo spacercanvas_demo pixelated_demo submit_demo datagrid_demo a11y_demo vg_chart_demo scrollbar_demo secondary_demo typography_demo; do
        [ "$sim_fail" -eq 0 ] || break
        SIM_FRAME_SOURCE=""
        if [ "$SIM_EX" = frametick_demo ]; then SIM_FRAME_SOURCE=cadisplaylink; fi
        rm -f "$SIM_APP/AetherUIProbe"
        # 2. The example's portable C, exactly as build.sh emits it for the host.
        if [ "$sim_fail" -eq 0 ] && ! aetherc "$ROOT/examples/$SIM_EX/$SIM_EX.ae" \
                "$SIM_DIR/$SIM_EX.c" > /tmp/ci_ios_sim_aetherc.log 2>&1; then
            echo "  FAIL aetherc $SIM_EX"
            tail -15 /tmp/ci_ios_sim_aetherc.log | sed 's/^/       /'
            sim_fail=1
        fi
        # 3. Link it for the simulator: the app, the UIKit backend, the driver, the
        #    runtime archive, the frameworks. The same clang line as Phase 1e's
        #    link check, with the real runtime where tests/ios/link_stub.c stood.
        if [ "$sim_fail" -eq 0 ]; then
            if "$IOS_CLANG" -fobjc-arc -target "$SIM_CLANG_TGT" -isysroot "$IOS_SDK" \
                    $(ae cflags | tr ' ' '\n' | awk 'p{print;p=0;next} /^-idirafter$/{print;p=1;next} /^-I/{print}' | tr '\n' ' ') -Ibackend \
                    "$SIM_DIR/$SIM_EX.c" \
                    "$ROOT/backend/aether_ui_uikit.m" \
                    "$ROOT/backend/aether_ui_test_server.c" \
                    "$ROOT/backend/aether_ui_system_extras.c" \
                    "$SIM_DIR/libaether_sim.a" \
                    -framework UIKit -framework Foundation -framework QuartzCore \
                    -framework CoreGraphics -framework CoreText -framework ImageIO \
                    -framework UserNotifications -lpthread -lm \
                    -o "$SIM_APP/AetherUIProbe" > /tmp/ci_ios_sim_link.log 2>&1; then
                echo "  OK   $SIM_EX links against the simulator runtime"
            else
                echo "  FAIL link $SIM_EX for the simulator"
                grep -iE "undefined|error:" /tmp/ci_ios_sim_link.log | head -15 | sed 's/^/       /'
                sim_fail=1
            fi
        fi
        # 4. The bundle, and a simulator to put it in.
        if [ "$sim_fail" -eq 0 ]; then
            cp "$ROOT/tests/ios/Info.plist" "$SIM_APP/Info.plist"
            [ -n "$IOS_SIM_UDID" ] || IOS_SIM_UDID="$(ios_sim_pick)"
            if [ -z "$IOS_SIM_UDID" ]; then
                echo "  FAIL no available iPhone simulator on this host"
                xcrun simctl list devices available 2>&1 | head -20 | sed 's/^/       /'
                sim_fail=1
            fi
        fi
        if [ "$sim_fail" -eq 0 ]; then
            xcrun simctl boot "$IOS_SIM_UDID" > /tmp/ci_ios_sim_boot.log 2>&1 || true
            if ! xcrun simctl bootstatus "$IOS_SIM_UDID" -b >> /tmp/ci_ios_sim_boot.log 2>&1; then
                echo "  FAIL simulator $IOS_SIM_UDID did not boot"
                tail -10 /tmp/ci_ios_sim_boot.log | sed 's/^/       /'
                sim_fail=1
            elif ! xcrun simctl install "$IOS_SIM_UDID" "$SIM_APP" > /tmp/ci_ios_sim_install.log 2>&1; then
                echo "  FAIL install into the simulator"
                tail -10 /tmp/ci_ios_sim_install.log | sed 's/^/       /'
                sim_fail=1
            else
                echo "  OK   booted $IOS_SIM_UDID and installed the bundle"
            fi
        fi
        # 5. Launch with the driver armed, then run the listbox spec against it as
        #    Phase 5f does on the desktop.
        if [ "$sim_fail" -eq 0 ]; then
            if curl -sf -o /dev/null "http://127.0.0.1:$PORT/widgets" 2>/dev/null; then
                echo "  FAIL port $PORT already answering (stray app?)"
                sim_fail=1
            elif ! SIMCTL_CHILD_AETHER_UI_TEST_PORT="$PORT" \
                    SIMCTL_CHILD_AETHER_UI_NO_ANIMATION=1 \
                    xcrun simctl launch --stdout=/tmp/ci_ios_sim.app.log --stderr=/tmp/ci_ios_sim.app.err \
                        "$IOS_SIM_UDID" dev.aether.ui.simprobe > /tmp/ci_ios_sim_launch.log 2>&1; then
                echo "  FAIL launch"
                tail -10 /tmp/ci_ios_sim_launch.log | sed 's/^/       /'
                sim_fail=1
            else
                up=0
                for _ in $(seq 1 200); do
                    if curl -sf -o /dev/null "http://127.0.0.1:$PORT/widgets"; then up=1; break; fi
                    sleep 0.2
                done
                if [ "$up" -ne 1 ]; then
                    echo "  FAIL the app's driver server never answered from the simulator"
                    ios_sim_diagnose
                    sim_fail=1
                elif AETHER_UI_EXPECT_FRAME_SOURCE="$SIM_FRAME_SOURCE" \
                        UI_SPEC="$SIM_EX/spec_$SIM_EX" "$SCRIPT_DIR/tests/run_spec.sh" "$PORT"; then
                    echo "  OK   $SIM_EX spec passes on the iOS simulator"
                else
                    echo "  FAIL $SIM_EX spec on the iOS simulator"
                    ios_sim_diagnose
                    sim_fail=1
                fi
                curl -sf -m 2 -X POST "http://127.0.0.1:$PORT/shutdown" > /dev/null 2>&1 || true
                xcrun simctl terminate "$IOS_SIM_UDID" dev.aether.ui.simprobe > /dev/null 2>&1 || true
                # The driver must be gone before the next example binds the port.
                for _ in $(seq 1 25); do
                    curl -sf -o /dev/null "http://127.0.0.1:$PORT/widgets" 2>/dev/null || break
                    sleep 0.2
                done
            fi
        fi
    done
    ios_sim_cleanup
    [ "$sim_fail" -eq 0 ] || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 1e3: Android backend (examples/counter as libapp.so) ==="
# The Android backend (docs/design/android-backend.md) is, like UIKit, one no
# CI box RUNS: that takes a device or an emulator. What any box with the
# toolchain CAN check is the rest of the chain: the backend and the shared
# driver/system sources compile -Wall -Werror for bionic, examples/counter
# builds as the shared library an APK carries (`ae build
# --target=aarch64-linux-android --emit=lib`, via tools/android-apk.sh), and
# that library exports what AetherActivity binds (JNI_OnLoad) and calls (the
# renamed main). Running it on a phone is tools/android-install.sh, then
# `adb forward tcp:<host port> tcp:9222` and tests/counter/spec_counter.ae with
# AETHER_UI_TEST_PORT=<host port> -- a host port other than 9222, so desktop
# runs on this box keep theirs.
# Opt-in: AETHER_ANDROID_SYSROOT=<aether-crossbuild bases/aarch64-android29>.
if [ -z "${AETHER_ANDROID_SYSROOT:-}" ] || [ ! -f "$AETHER_ANDROID_SYSROOT/usr/include/jni.h" ]; then
    echo "  SKIP set AETHER_ANDROID_SYSROOT to an Android sysroot (aether-crossbuild fetch-android-sysroot.sh) to enable"
elif ! command -v zig > /dev/null 2>&1; then
    echo "  SKIP no zig on PATH (ae's cross-compiler)"
elif ! ae build --help 2>&1 | grep -q "linux-android"; then
    echo "  SKIP this ae has no Android target"
else
    android_fail=0
    ANDROID_API_DIR="$(ls -d "$AETHER_ANDROID_SYSROOT"/usr/lib/aarch64-linux-android/[0-9]* | sort -V | head -1)"
    ANDROID_LIBC_FILE="/tmp/ci_android_zig_libc.txt"
    printf 'include_dir=%s/usr/include\nsys_include_dir=%s/usr/include/aarch64-linux-android\ncrt_dir=%s\nmsvc_lib_dir=\nkernel32_lib_dir=\ngcc_dir=\n' \
        "$AETHER_ANDROID_SYSROOT" "$AETHER_ANDROID_SYSROOT" "$ANDROID_API_DIR" > "$ANDROID_LIBC_FILE"
    for src in backend/aether_ui_android.c \
               backend/aether_ui_test_server.c \
               backend/aether_ui_system_extras.c; do
        if ZIG_LIBC="$ANDROID_LIBC_FILE" zig cc -target "aarch64-linux-android.$(basename "$ANDROID_API_DIR")" \
                -c -o /dev/null -Wall -Wextra -Wno-unused-parameter -Werror -Ibackend "$ROOT/$src" \
                > "/tmp/ci_android_$(basename "$src").log" 2>&1; then
            echo "  OK   $(basename "$src")"
        else
            echo "  FAIL $(basename "$src")"
            grep -E "(error|warning):" "/tmp/ci_android_$(basename "$src").log" | head -10 | sed 's/^/       /'
            android_fail=1
        fi
    done
    if [ "$android_fail" -eq 0 ]; then
        if AETHER_SYSROOT="$AETHER_ANDROID_SYSROOT" ANDROID_LIB_ONLY=1 AETHER_UI_WITH_DRIVER=1 \
                "$ROOT/tools/android-apk.sh" "$ROOT/examples/counter/counter.ae" \
                > /tmp/ci_android_build.log 2>&1; then
            ANDROID_SO="$ROOT/target/android/counter/stage/lib/arm64-v8a/libapp.so"
            exports="$(nm -D --defined-only "$ANDROID_SO" 2>/dev/null)"
            if echo "$exports" | grep -q ' JNI_OnLoad$' \
               && echo "$exports" | grep -q ' aether_main$'; then
                # aether_main is the --emit=lib entry the shim starts the app
                # through since the 0.791 move (aether#2489); the old
                # aether_aeui_app_main rename is only a weak fallback now.
                echo "  OK   counter builds as libapp.so (JNI_OnLoad + aether_main exported)"
            elif [ -z "$exports" ]; then
                echo "  OK   counter builds as libapp.so (no ELF-capable nm here to check its exports)"
            else
                echo "  FAIL libapp.so is missing JNI_OnLoad or aether_main"
                android_fail=1
            fi
        else
            echo "  FAIL counter as libapp.so"
            tail -15 /tmp/ci_android_build.log | sed 's/^/       /'
            android_fail=1
        fi
    fi
    [ "$android_fail" -eq 0 ] || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 1f: AppKit label retention across list rebuilds (#139) ==="
# tests/appkit_retention/retention_probe.ae rebuilds a 400-row listbox on a
# timer and then sits still, and `heap` (Xcode's, in /usr/bin) counts the
# NSTextField instances alive in it from outside. Rows a rebuild retires are
# supposed to be freed with it, so the count is a steady state, and a count
# that tracks the rows ever rendered is the leak #139 describes. The
# assertion is growth, not a level: the same probe after 10 rebuilds and
# after 20, with the run loop idle between rebuilds (the shape of an app
# refreshing a list), may differ by one generation of rows at most -- the
# 400 the last rebuild retired and the next run-loop turn frees. Ten
# rebuilds that freed nothing would add 4 000. Two more runs are reported
# for the record and not asserted: the loop saturated by a period shorter
# than a rebuild, the shape #139 was measured in; and headless, where no
# window is ever laid out.
# heap(1) and leaks(1) attach to the probe as a debugger does, and on a box
# where that attach wedges (seen on a macOS beta, 2026-10-16: `heap` hung on
# ANY pid, even a shell) they never return: one call held this phase, and
# the family's shared test lock, for over an hour. So every call is bounded
# (bounded SECS CMD..., no timeout(1) on macOS; the command's stderr is
# dropped, the bound's own note is not), and after the first one
# that times out the rest are skipped, so a wedged attach costs one bound,
# not one per run. The marker is a file because retention_run runs in $(...).
HEAP_HUNG="/tmp/ci_heap_hung.$$"
rm -f "$HEAP_HUNG"
bounded() {
    local secs="$1" p w rc; shift
    [ -e "$HEAP_HUNG" ] && return 124
    "$@" 2> /dev/null &
    p=$!
    # The watcher's output goes nowhere, so it never holds a pipe open.
    ( sleep "$secs"; touch "$HEAP_HUNG"; kill_tree "$p" ) > /dev/null 2>&1 &
    w=$!
    wait "$p"; rc=$?
    kill_tree "$w" > /dev/null 2>&1
    if [ -e "$HEAP_HUNG" ]; then
        echo "  NOTE $1 did not return in ${secs}s (debugger attach wedged?); skipping the rest" >&2
        return 124
    fi
    return "$rc"
}
retention_count() {
    # The live NSTextField line of `heap`: COUNT BYTES AVG CLASS_NAME ...
    bounded 120 heap "$1" | awk '$4 == "NSTextField" { print $1; exit }'
}
retention_run() {
    # $1 = rebuild period (ms), $2 = rebuilds, $3 = label for the log,
    # $4 = 1 for headless. Prints the count on stdout (the caller captures
    # it) and any complaint on stderr.
    local period="$1" rounds="$2" tag="$3" headless="${4:-0}"
    local log="/tmp/ci_retention_${3}.log" pid n i
    AETHER_PROBE_PERIOD_MS="$period" AETHER_PROBE_ROUNDS="$rounds" \
        AETHER_UI_HEADLESS="$headless" \
        ./build/retention_probe > "$log" 2>&1 &
    pid=$!
    for i in $(seq 1 240); do
        grep -q "RETENTION_PROBE:" "$log" 2>/dev/null && break
        kill -0 "$pid" 2>/dev/null || break
        sleep 0.5
    done
    if ! grep -q "RETENTION_PROBE:" "$log" 2>/dev/null; then
        echo "  FAIL retention probe ($tag) never finished its rebuilds" >&2
        tail -10 "$log" | sed 's/^/       /' >&2
        kill_tree "$pid"; wait "$pid" 2>/dev/null
        return 1
    fi
    n="$(retention_count "$pid")"
    # Who holds them: for the longest run, the root paths (`leaks --trace`)
    # to a sample of the live labels, spread through the address list. With
    # 400 rows on screen and more than that alive, most samples are retired
    # labels, and the path says what keeps a retired label alive. Reported
    # to stderr, which the phase shows; not asserted.
    if [ "$tag" = "idle40" ] && command -v leaks > /dev/null 2>&1; then
        {
            echo "  -- $tag: live view classes"
            bounded 120 heap "$pid" | awk '$4 ~ /^(NSTextField|AetherStackView|NSTextFieldCell|_NSViewLayoutAux)$/ { print "     " $1, $4 }'
            echo "  -- $tag: root paths to a sample of live NSTextField"
            local addrs
            addrs="$(bounded 120 heap "$pid" --addresses=NSTextField | awk '/^ *0x/ { a=$1; sub(/:$/, "", a); print a }')"
            local total
            total="$(printf '%s\n' "$addrs" | grep -c . || true)"
            if [ "$total" -gt 0 ]; then
                local step=$(( total / 6 + 1 )) k=0
                printf '%s\n' "$addrs" | awk -v s="$step" 'NR % s == 1' | head -6 | while read -r a; do
                    echo "     -- $a"
                    bounded 120 leaks "$pid" --trace="$a" | grep -vE '^(Process|Load Address|Identifier|Version|Code Type|Platform|Parent Process|Date/Time|Launch Time|OS Version|Report Version|Analysis Tool|Physical footprint|----|$)' | head -30 | sed 's/^/       /'
                done
            fi
        } >&2
    fi
    kill_tree "$pid"; wait "$pid" 2>/dev/null
    if [ -z "$n" ]; then
        echo "  FAIL heap gave no NSTextField count for the $tag run" >&2
        return 1
    fi
    echo "$n"
}
if [ "$PLATFORM" = "macos" ]; then
    if ! command -v heap > /dev/null 2>&1; then
        echo "  SKIP no heap(1) on this host (it ships with Xcode)"
    elif ! ./build.sh tests/appkit_retention/retention_probe.ae retention_probe             > /tmp/ci_retention_build.log 2>&1; then
        echo "  FAIL retention probe (build)"
        tail -20 /tmp/ci_retention_build.log | sed 's/^/       /'
        FAIL=$((FAIL + 1))
    else
        # Three points, so a slow drift shows as a slope rather than hiding
        # inside one generation's slack: 10, 20 and 40 rebuilds.
        ten="$(retention_run 500 10 idle10)"; ten_rc=$?
        twenty="$(retention_run 500 20 idle20)"; twenty_rc=$?
        forty="$(retention_run 500 40 idle40)"; forty_rc=$?
        if [ "$ten_rc" -ne 0 ] || [ "$twenty_rc" -ne 0 ] || [ "$forty_rc" -ne 0 ]; then
            FAIL=$((FAIL + 1))
        elif [ $((twenty - ten)) -le 400 ] && [ $((forty - twenty)) -le 400 ]; then
            echo "  OK   NSTextField alive: $ten after 10 rebuilds, $twenty after 20, $forty after 40 (run loop idle between; growth bound 400 per step)"
        else
            echo "  FAIL NSTextField alive: $ten after 10 rebuilds, $twenty after 20, $forty after 40 of 400 rows, run loop idle between (growth bound 400 per step)"
            FAIL=$((FAIL + 1))
        fi
        saturated="$(retention_run 10 20 saturated)" || true
        [ -n "$saturated" ] && echo "  INFO $saturated alive after 20 rebuilds, run loop saturated (not asserted)"
        headless="$(retention_run 500 20 headless 1)" || true
        [ -n "$headless" ] && echo "  INFO $headless alive after 20 rebuilds, headless (not asserted)"
        # The rows dimension: the drift at 100 rows against the one at 400
        # says whether it is a fraction of the rows or a count per rebuild.
        r100a="$(AETHER_PROBE_ROWS=100 retention_run 500 20 rows100_20)" || true
        r100b="$(AETHER_PROBE_ROWS=100 retention_run 500 40 rows100_40)" || true
        [ -n "$r100a" ] && [ -n "$r100b" ] && echo "  INFO $r100a / $r100b alive after 20 / 40 rebuilds of 100 rows (not asserted)"
    fi
else
    echo "  SKIP AppKit only"
fi

echo
echo "=== Phase 2: smoke-launch non-driver examples ==="
for ex in "${SMOKE_EXAMPLES[@]}"; do
    run_smoke_test "$(EX_BIN "$ex")" "$ex" || FAIL=$((FAIL + 1))
done

# Phases 3-6 are driver specs (tests/<app>/spec_*.ae — Aether programs on
# the shared tests/lib/uidriver.ae client; tests/run_spec.sh is launcher
# glue).
#
# They used to need an aeocha CHECKOUT, resolved from ~/scm/aeocha or a
# sibling directory, with a hard FAIL when absent. That requirement is gone:
# aeocha's core was absorbed into the stdlib as `std.spec` (ae 0.539) and its
# HTTP matchers as `std.http.client.httptest`, so the framework now ships with
# the toolchain. Nothing to clone, nothing to locate, and no way for a fresh
# box to fail these phases for want of a repo.
#
# SPEC_OK is kept (rather than deleting ~10 guards) so the phase structure is
# unchanged; it is simply always satisfied now.
SPEC_OK=1

# Implicit transitions (item 6) exist now: every DRIVER phase runs with
# animations OFF so specs assert end states deterministically (house rule).
# Phase 5h is the exception — it PROVES the tween, so it unsets this.
export AETHER_UI_NO_ANIMATION=1

echo
echo "=== Phase 3: AetherUIDriver calculator spec ==="
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=calculator/spec_calculator \
    run_server_test "$(EX_BIN calculator)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" calculator || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 3b: AetherUIDriver text-metrics spec ==="
# App-agnostic: exercises the GET /text_extent route against the calculator
# binary (any driver-armed app exposes it). Verifies the cairo text metrics
# behave over the real HTTP surface (roadmap item 2).
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=text_metrics/spec_text_metrics \
    run_server_test "$(EX_BIN calculator)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" text_metrics || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 4: AetherUIDriver testable spec ==="
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=testable/spec_testable \
    run_server_test "$(EX_BIN testable)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" testable || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 4a: AetherUIDriver counter spec ==="
# The Android backend's stage-1 acceptance spec (tests/counter), held green on
# the desktop too so it stays a spec every backend passes, not an Android one.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=counter/spec_counter \
    run_server_test "$(EX_BIN counter)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" counter || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5: AetherUIDriver context-menu spec ==="
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=context_menu/spec_context_menu \
    run_server_test "$(EX_BIN context_menu)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" context_menu || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5b: AetherUIDriver overlay-layer spec ==="
# In-window overlay layer (roadmap item 1): toast open + auto-dismiss, modal
# scrim proven by a real /window/pick hit-test (the glass pane resolves ahead
# of the button beneath it), dismiss restores access.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=overlay_demo/spec_overlay_demo \
    run_server_test "$(EX_BIN overlay_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" overlay_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5c: AetherUIDriver vg drawn-tooltip spec ==="
# The drawn-tooltip half of the overlay layer: a vg shape's tooltip() opens a
# label overlay near the pointer (forced on via AETHER_UI_TOOLTIP=drawn) —
# hover a shape → tooltip appears; off it → gone. Driven via /canvas/1/move.
if [ "$SPEC_OK" -eq 1 ]; then
    AETHER_UI_TOOLTIP=drawn \
    UI_SPEC=vg_tooltip/spec_vg_tooltip \
    run_server_test "$(EX_BIN vg_tooltip)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" vg_tooltip || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5d: AetherUIDriver picker ABI spec (drawn surface) ==="
# Picker ABI parity: the same select/read-back assertions pass on the drawn
# dropdown (a button + in-window overlay list) as on the native GtkDropDown.
# Run here under the DRAWN surface — the native surface is the everyday path
# and is smoke-launched in Phase 2.
if [ "$SPEC_OK" -eq 1 ]; then
    AETHER_UI_PICKER=drawn \
    UI_SPEC=picker/spec_picker \
    run_server_test "$(EX_BIN picker)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" picker || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e: AetherUIDriver each (dynamic children) spec ==="
# each (roadmap item 3): Add/Remove/Reset drive each_update; the spec asserts
# group children appear/disappear in /widgets and per-item closures fire with
# the RIGHT item (needs aether >= 0.390 closure-capture fixes).
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=each_demo/spec_each_demo \
    run_server_test "$(EX_BIN each_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" each_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e2: AetherUIDriver clear_children / remove_child spec ==="
# Issue #1: removing a widget must also remove it from the driver registry,
# or automation keeps seeing (and clicking) cells that left the screen. Covers
# a grid AND a stack because the backends route the two shapes differently.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=rebuild_demo/spec_rebuild_demo \
    run_server_test "$(EX_BIN rebuild_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" rebuild_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e3: AetherUIDriver file-icon spec ==="
# Issue #4: the icon the OS uses for a KIND of file, which is a different
# question from image(path). The driver can see whether an image widget
# actually carries a picture, which is what tells a real platform icon from
# an empty box.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=fileicon_demo/spec_fileicon_demo \
    run_server_test "$(EX_BIN fileicon_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" fileicon_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e4: AetherUIDriver scroll-area geometry + theming spec ==="
# Issue #6: content smaller than the viewport must be VISIBLE inside the
# scroll area, and the area must be themable. Both failures are invisible to
# a widget census (the widgets exist and answer) so the spec reads geometry.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=scrollbg_demo/spec_scrollbg_demo \
    run_server_test "$(EX_BIN scrollbg_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" scrollbg_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e4a: a scrollview's content is held to its width (no row sets the page's) ==="
# A row wider than the window must not make the page that wide: the field that
# takes the rest of its row fills the window and follows it. GTK's scrolled
# window gave the content the widest row's width.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=scrollwide_demo/spec_scrollwide_demo \
    run_server_test "$(EX_BIN scrollwide_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" scrollwide_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e4a2: a width stated with set_width / canvas_size is the width given ==="
# A text field narrower than GTK's ~150px entry minimum, and a canvas pinned
# below the size it was made at, kept the platform's minimum instead.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=pinsize_demo/spec_pinsize_demo \
    run_server_test "$(EX_BIN pinsize_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" pinsize_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e4a3: restyling a page in one callback is one load of the sheets ==="
# 500 labels (eight properties each) restyled from one handler: the handler returns, and the next
# timer tick runs, in tens of milliseconds, not a sheet reload per rule (GTK4:
# 0.3-3 s, which is what turned a spreadsheet's dark mode into 2.4 s on ae-x64).
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=cssbatch_demo/spec_cssbatch_demo \
    run_server_test "$(EX_BIN cssbatch_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" cssbatch_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e4b: an AeCS dark sheet is DRAWN (pixels, not the report) ==="
# asks/aecs-button-fg-and-field-bg-not-drawn.md: /widgets reported a button's
# fg and a text field's bg as the sheet asked while AppKit drew the label
# dark and the fields white. The test decodes /screenshot and reads the
# pixels inside each widget, so a report that only echoes the sheet fails.
if [ "$SPEC_OK" -eq 1 ]; then
    run_server_test "$(EX_BIN aecs_dark_demo)" \
                    "$SCRIPT_DIR/tests/aecs_dark_demo/test_aecs_dark_drawn.sh" aecs_dark_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e5: AetherUIDriver any-key handler spec ==="
# Issue #18: window_on_key delivers whatever was pressed, which is what
# type-ahead needs and what no number of registered shortcuts can express.
# Also pins accelerator priority: a BOUND combo must not reach it.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=keyhandler_demo/spec_keyhandler_demo \
    run_server_test "$(EX_BIN keyhandler_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" keyhandler_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e6: AetherUIDriver image fill-mode spec ==="
# Issue #16: how a picture fills a box it does not match. Also pins the
# DEFAULT, which the two toolkits disagree about on their own (GtkPicture
# CONTAIN vs NSImageView ProportionallyDown).
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=imagefill_demo/spec_imagefill_demo \
    run_server_test "$(EX_BIN imagefill_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" imagefill_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e7: AetherUIDriver fixed-bar + filling-body layout spec ==="
# Issue #5: a pinned toolbar must keep its height while the body absorbs the
# slack, across a resize. The failure was never a crash, only wrong numbers,
# so the spec resizes the window and reads heights back.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=barfill_demo/spec_barfill_demo \
    run_server_test "$(EX_BIN barfill_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" barfill_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e8: AetherUIDriver window file-drop spec ==="
# Issue #17: files dropped on the window. A real drag cannot be synthesised
# headlessly, so the driver hands the same closure a real drop does. The case
# that matters is a MULTI-file drop staying several paths.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=filedrop_demo/spec_filedrop_demo \
    run_server_test "$(EX_BIN filedrop_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" filedrop_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e9: AetherUIDriver SVG-as-widget spec ==="
# The SVG half of #16: an SVG FILE drawn through vg rather than handed to a
# platform decoder that cannot read it. Geometry is the check, because the
# way this fails is a stretched canvas with the aspect thrown away.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=svgimage_demo/spec_svgimage_demo \
    run_server_test "$(EX_BIN svgimage_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" svgimage_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e9b: AetherUIDriver vg image element spec ==="
# vg.image: a program's RGBA buffer blitted into a scene, fit modes, a
# PNG decoded by the toolkit, opacity and transform, and a click that
# rewrites the buffer in place. Pixels read back through /canvas/{id}/pixel,
# so this checks the BLIT and the decoder on this backend.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=vg_image_demo/spec_vg_image_demo \
    run_server_test "$(EX_BIN vg_image_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" vg_image_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e9c: AetherUIDriver vg live-path paint spec ==="
# What a live vg(...) scene's deferred flush used to drop: gradients from
# defs (lost with the context a resize swapped in), clip_path on shapes and
# groups, css() type/class/id rules, right and double click on shapes, and
# g() opacity composited as one layer. Pixels via /canvas/{id}/pixel.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=vgpaint_demo/spec_vgpaint_demo \
    run_server_test "$(EX_BIN vgpaint_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" vgpaint_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e9c2: AetherUIDriver vg/chart spec (the Chartist port) ==="
# vg/chart's line, stacked bar and donut drawn on live vg scenes: the nodes
# carry Chartist's classes and the theme's paint (/canvas/{id}/nodes), the
# pixels are the series colours (/canvas/{id}/pixel), and a click on a donut
# slice recolours it through the draw hook.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=vg_chart_demo/spec_vg_chart_demo \
    run_server_test "$(EX_BIN vg_chart_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" vg_chart_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e9d: AetherUIDriver spacers-before-canvas spec ==="
# spacer() takes a stack's slack before a canvas does, so spacer/canvas/spacer
# keeps the canvas at its size, centred; a canvas alone still fills. GTK4
# split the slack three ways, Win32 and UIKit gave it all to the canvas, and
# AppKit gave it all to the first spacer (sae's corpus pages).
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=spacercanvas_demo/spec_spacercanvas_demo \
    run_server_test "$(EX_BIN spacercanvas_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" spacercanvas_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e9e: AetherUIDriver image_rendering spec ==="
# vg image_rendering("pixelated"): a 2x1 buffer scaled across 200 units is
# pure red right up to the cells' boundary; the default blends there (Win32
# enlarges unsmoothed anyway). canvas_image_smoothing on every backend.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=pixelated_demo/spec_pixelated_demo \
    run_server_test "$(EX_BIN pixelated_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" pixelated_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e9f: AetherUIDriver on_submit spec ==="
# Return in a text or secure field runs on_submit with the field's text;
# POST /widget/{id}/submit takes each platform's own Return path.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=submit_demo/spec_submit_demo \
    run_server_test "$(EX_BIN submit_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" submit_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e9g: AetherUIDriver datagrid spec ==="
# A virtualised grid: 100,000 x 50 from a function, only the shown cells as
# widgets, sliders (a vslider) to scroll, a sticky header and frozen column.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=datagrid_demo/spec_datagrid_demo \
    run_server_test "$(EX_BIN datagrid_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" datagrid_demo || FAIL=$((FAIL + 1))
fi

if [ "$PLATFORM" = "linux" ] && [ "$SPEC_OK" -eq 1 ] && [ "$LAUNCH_PREFIX" != "SKIP_RUNTIME" ]; then
    echo "-- Phase 5e9g2: the datagrid under real X11 input (xdotool) --"
    # The driver's clicks and keys call closures; a person's go through
    # GTK's event dispatch, where a click on a grid once scrolled the page to
    # its far corner and real keys reached no handler. xdotool's are real.
    if [ -n "$LAUNCH_PREFIX" ]; then
        $LAUNCH_PREFIX sh "$SCRIPT_DIR/tests/datagrid_demo/real_input_x11.sh" "$(EX_BIN datagrid_demo)" 9388
    else
        sh "$SCRIPT_DIR/tests/datagrid_demo/real_input_x11.sh" "$(EX_BIN datagrid_demo)" 9388
    fi
    rc=$?
    [ $rc -eq 0 ] || [ $rc -eq 77 ] || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e10: AetherUIDriver sheet spec ==="
# The sheet verbs had NO coverage, in C or over the driver, and two things
# were wrong in that gap: macOS registered the sheet's own contentView and
# threw the handle away (one dead, unaddressable entry per sheet), and no
# backend unregistered the body on dismiss. GTK4 also presented a sheet in
# headless mode, which is why this phase runs headless like the rest.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=sheet_demo/spec_sheet_demo \
    run_server_test "$(EX_BIN sheet_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" sheet_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e11: AetherUIDriver timer spec ==="
# G_DEBUG=fatal-criticals on purpose, and only here. GTK4's timer_cancel used
# to hand the raw GSource id to g_source_remove, so cancelling twice raised a
# GLib CRITICAL where macOS and win32 both no-op. Nothing the driver reports
# changes when that happens, so without making criticals fatal the misuse is
# invisible from a spec. With it, the app aborts and the assertions fail.
if [ "$SPEC_OK" -eq 1 ]; then
    export G_DEBUG=fatal-criticals
    UI_SPEC=timer_demo/spec_timer_demo \
    run_server_test "$(EX_BIN timer_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" timer_demo || FAIL=$((FAIL + 1))
    unset G_DEBUG
fi

echo "=== Phase 5e11a: AetherUIDriver frame clock + timer_once spec ==="
# on_frame is the display-synced tick (GTK4 frame clock, CADisplayLink,
# Choreographer, DwmFlush) and timer_once the one-shot timer. The spec counts
# frames over half a second and checks their timestamps against wall time.
# Pinned on Linux/FreeBSD, so a frame clock that silently fell back to the
# timer fails here: GTK4 under Xvfb is mapped, and its frame clock ticks. Not
# pinned on macOS (the screen's CADisplayLink stops while the display sleeps,
# and an unattended ci.sh can run then) or Windows (an SSH or service session
# has no compositor); the spec prints the source either way.
if [ "$SPEC_OK" -eq 1 ]; then
    case "$(uname -s)" in
        Linux|FreeBSD) export AETHER_UI_EXPECT_FRAME_SOURCE=gtk-frame-clock ;;
    esac
    export G_DEBUG=fatal-criticals
    UI_SPEC=frametick_demo/spec_frametick_demo \
    run_server_test "$(EX_BIN frametick_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" frametick_demo || FAIL=$((FAIL + 1))
    unset G_DEBUG AETHER_UI_EXPECT_FRAME_SOURCE
fi

echo "=== Phase 5e11b: AetherUIDriver background-work spec (std.worker completions land on the UI thread) ==="
# ui.background(work) callback |result| runs work on a pool thread and the
# completion on the UI thread through the backend's std.worker poster. The
# spec asserts all three halves from outside: the click returns before the
# work is done (it is off the UI thread), the timer label keeps ticking while
# it runs (the UI thread was not blocked), and the finished label carries
# work_ui=0 done_ui=1 (each half ran on the thread the contract names).
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=background_demo/spec_background_demo \
    run_server_test "$(EX_BIN background_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" background_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e12: AetherUIDriver canvas-scroll spec ==="
# canvas_on_scroll was GTK4-only and an honest no-op elsewhere, so a shipped
# app's scroll-to-zoom did nothing on macOS or Windows. Now wired on all
# three, each converting its platform's sign to the DSL convention (dy<0 is
# away from the user). The spec asserts the SIGN, because getting it wrong
# never fails loudly, it silently inverts zoom.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=canvasscroll_demo/spec_canvasscroll_demo \
    run_server_test "$(EX_BIN canvasscroll_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" canvasscroll_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e13: AetherUIDriver canvas-clip spec ==="
# canvas_clip_rect was a SILENT NO-OP on win32 (the impl discarded its
# arguments; the paint replay had no case for it), so every AeVG live scene
# drew past its viewport there -- vg/live.ae emits one at scene-flush start to
# enforce SVG overflow:hidden. It survived because the only test for the
# primitive asserted nothing about clipping and was in no run list. This one
# asserts pixels, on both backends CI has.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=canvasclip_demo/spec_canvasclip_demo \
    run_server_test "$(EX_BIN canvasclip_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" canvasclip_demo || FAIL=$((FAIL + 1))

    echo "-- Phase 5e20: canvas_on_resize passes floats like its siblings --"
    UI_SPEC=resizecb_demo/spec_resizecb_demo \
    run_server_test "$(EX_BIN resizecb_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" resizecb_demo || FAIL=$((FAIL + 1))

    # An app that ends itself needs no driver: the whole assertion is that the
    # run loop RETURNS and the process exits 0. Before app_quit the only way
    # to stop one was to kill it, so `timeout` always reported 124 and could
    # not tell finishing from hanging.
    echo "-- Phase 5e21: app_quit stops the run loop --"
    run_self_quitting "$(EX_BIN quit_demo)" quit_demo 30
    quit_rc=$?
    quit_out=$(cat /tmp/ci_quit_demo.selfquit.log 2>/dev/null)
    if [ "$quit_rc" -eq 0 ] \
       && printf '%s' "$quit_out" | grep -q "work done" \
       && printf '%s' "$quit_out" | grep -q "run loop returned"; then
        echo "  OK   quit_demo ended itself (exit 0, loop returned)"
    else
        echo "  FAIL quit_demo: rc=$quit_rc (124 = never quit)"
        printf '%s\n' "$quit_out" | head -5 | sed 's/^/       /'
        FAIL=$((FAIL + 1))
    fi

    # A panel width that HOLDS inside a nested splitview. No driver needed:
    # the app reads its own allocation back through get_width and quits, so
    # the assertion is the number it printed. Asked 240; with nothing but
    # split_set_position the pane took the whole width (1368), because
    # -setPosition: does not survive layout re-deriving a pane from its
    # content. set_width is what holds.
    echo "-- Phase 5e22: set_width holds a panel inside a nested splitview --"
    run_self_quitting "$(EX_BIN panelsize_demo)" panelsize_demo 30
    panel_rc=$?
    panel_out=$(cat /tmp/ci_panelsize_demo.selfquit.log 2>/dev/null)
    if [ "$panel_rc" -eq 0 ] && printf '%s' "$panel_out" | grep -q "left panel width = 240"; then
        echo "  OK   panelsize_demo: left panel held at 240"
    else
        echo "  FAIL panelsize_demo: rc=$panel_rc"
        # The interesting line, not the first four lines of GTK warnings.
        printf '%s\n' "$panel_out" | grep -a "left panel width" | sed 's/^/       /' \
            || echo "       (no width line printed at all)"
        printf '%s\n' "$panel_out" | tail -3 | sed 's/^/       /'
        FAIL=$((FAIL + 1))
    fi

    # A container child must get the same content box as a leaf child. Both
    # read back through get_width, so no driver is needed. The panel is 400
    # wide with 12px side insets: the row must measure 376. Before the fix it
    # measured the full 400, hanging 12px outside the padding every leaf
    # child respected.
    echo "-- Phase 5e23: a container child sits inside the parent's insets --"
    run_self_quitting "$(EX_BIN insets_demo)" insets_demo 30
    ins_rc=$?
    ins_out=$(cat /tmp/ci_insets_demo.selfquit.log 2>/dev/null)
    if [ "$ins_rc" -eq 0 ] && printf '%s' "$ins_out" | grep -q "row_w=376"; then
        echo "  OK   insets_demo: container child inset like a leaf (376)"
    else
        echo "  FAIL insets_demo: rc=$ins_rc"
        printf '%s\n' "$ins_out" | grep -a "row_w" | sed 's/^/       /' \
            || echo "       (no width line printed)"
        FAIL=$((FAIL + 1))
    fi

    # The borrowed blit skips the per-frame copy; it is only worth having if
    # it draws the SAME pixels. The demo blits one image both ways and reads
    # back two of them, so this asserts the picture, not the speed.
    echo "-- Phase 5e24: a borrowed blit draws what the copying blit draws --"
    run_self_quitting "$(EX_BIN blitborrow_demo)" blitborrow_demo 30
    blit_rc=$?
    blit_out=$(cat /tmp/ci_blitborrow_demo.selfquit.log 2>/dev/null)
    if [ "$blit_rc" -eq 0 ] && printf '%s' "$blit_out" | grep -q "^MATCH$"; then
        echo "  OK   blitborrow_demo: borrowed and copied blits agree"
    else
        echo "  FAIL blitborrow_demo: rc=$blit_rc"
        printf '%s\n' "$blit_out" | grep -aE "owned|borrow" | sed 's/^/       /'
        FAIL=$((FAIL + 1))
    fi

    echo "-- Phase 5e21: the GPU viewport actually renders (#92) --"
    UI_SPEC=gpuview_demo/spec_gpuview_demo \
    run_server_test "$(EX_BIN gpuview_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" gpuview_demo || FAIL=$((FAIL + 1))

    echo "-- Phase 5e21b: the native view hands out a usable handle (#193) --"
    UI_SPEC=native_view_demo/spec_native_view_demo \
    run_server_test "$(EX_BIN native_view_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" native_view_demo || FAIL=$((FAIL + 1))

    echo "-- Phase 5e22: and redraws when the app asks it to (#137) --"
    UI_SPEC=gpuanim_demo/spec_gpuanim_demo \
    run_server_test "$(EX_BIN gpuanim_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" gpuanim_demo || FAIL=$((FAIL + 1))

    echo "-- Phase 5e19: canvas_reset_clip widens the clip back --"
    UI_SPEC=canvasresetclip_demo/spec_canvasresetclip_demo \
    run_server_test "$(EX_BIN canvasresetclip_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" canvasresetclip_demo || FAIL=$((FAIL + 1))

    echo "-- Phase 5e20: a sized canvas does not collapse its panel --"
    UI_SPEC=panelcanvas_demo/spec_panelcanvas_demo \
    run_server_test "$(EX_BIN panelcanvas_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" panelcanvas_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e14: AetherUIDriver group-opacity spec ==="
# canvas_group_begin/end were empty stubs on macOS, so an SVG <g opacity>
# rendered fully opaque there -- the same defect the win32 comment records for
# mememe.svg. Two assertions because there are two ways to be wrong: dropping
# the alpha (the stub) and applying it per child (overlaps double-darken).
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=groupalpha_demo/spec_groupalpha_demo \
    run_server_test "$(EX_BIN groupalpha_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" groupalpha_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e15: AetherUIDriver hover/active paint spec ==="
# style_hover recorded a colour on macOS that only the driver readback ever
# looked at -- no draw path used it, so a styled control still "read as dead",
# the exact thing that DSL verb exists to prevent. Asserts WHICH colour, and
# the full round trip: release falls back to hover, leaving restores base.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=hoverpaint_demo/spec_hoverpaint_demo \
    run_server_test "$(EX_BIN hoverpaint_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" hoverpaint_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e16: AetherUIDriver gradient-spread spec ==="
# SVG spreadMethod. CoreGraphics has no reflect/repeat, so macOS dropped the
# argument and rendered every gradient as pad while GTK4 and win32 honoured
# it. Asserted by channel comparison, not exact colours: the exact value at a
# sample depends on antialiasing, and pinning one would test the rasteriser.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=gradspread_demo/spec_gradspread_demo \
    run_server_test "$(EX_BIN gradspread_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" gradspread_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e17: AetherUIDriver field-placeholder spec ==="
# textarea honoured its placeholder on WIN32 ONLY -- macOS discarded the
# argument, GTK4 never referenced it -- so the one platform with no CI was the
# only one where it worked, and nothing reported a placeholder so no spec could
# have caught it. /widgets now carries the field; this asserts all three kinds.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=placeholder_demo/spec_placeholder_demo \
    run_server_test "$(EX_BIN placeholder_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" placeholder_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5e18: AetherUIDriver multi-handler key spec ==="
# window_on_key kept a SINGLE closure: each registration replaced the last, so
# a second one silently disabled the first, and on_key() is built on it. Two
# counters with their own handlers; the previous code left the first at 0.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=multikey_demo/spec_multikey_demo \
    run_server_test "$(EX_BIN multikey_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" multikey_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5f: AetherUIDriver listbox spec ==="
# listbox (item 4 D1): rows are real widgets; the driver clicks a ROW (click
# falls back to gesture handlers on non-buttons), selection reads back via
# the tracked "classes" JSON field; 200-row updates stay driver-visible.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=listbox_demo/spec_listbox_demo \
    run_server_test "$(EX_BIN listbox_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" listbox_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5g: AetherUIDriver table spec ==="
# table (item 4 D2): header buttons fire on_sort with the right column index,
# app-side re-sort re-renders row order (asserted via widget creation order),
# cells render per column, selection delegates to the listbox layer.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=table_demo/spec_table_demo \
    run_server_test "$(EX_BIN table_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" table_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5i: AetherUIDriver splitview spec ==="
# splitview (item 7 D1): panes are real widgets; POST split_position moves
# the splitter and the pane allocations follow; app-side get/set round-trips.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=split_demo/spec_split_demo \
    run_server_test "$(EX_BIN split_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" split_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5j: AetherUIDriver typed-state + bindings spec ==="
# bindings (item 8): typed /state routes (float byte-compatible), one bool
# state flipping enabled/enabled-inverted/hidden, driver + app-side sets.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=bindings_demo/spec_bindings_demo \
    run_server_test "$(EX_BIN bindings_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" bindings_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5k0: AetherUIDriver scrollbar spec ==="
# scrollbar: the windowing slider. Type "scrollbar" with value, range,
# window and steps; set_value and /scroll?by= move it as a person would
# (on_change, clamped to min..max-page); scrollbar_set/_steps from code;
# a scrollbar's thickness across, its run along; snapshots at each step.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=scrollbar_demo/spec_scrollbar_demo \
    run_server_test "$(EX_BIN scrollbar_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" scrollbar_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5k1: AetherUIDriver secondary-click spec ==="
# on_secondary_click: the driver's secondary click fires a widget's closure
# and the menu it pops is recorded (GET /popup); GET /menus lists its items,
# separators and disabled ones; menu_clear rebuilds it afresh each open; a
# vg shape's right click pops its own; the panel around them has another.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=secondary_demo/spec_secondary_demo \
    run_server_test "$(EX_BIN secondary_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" secondary_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5k2: AetherUIDriver typography spec ==="
# style_typography: a double underline, super- and subscript, top and
# bottom, an indent, a rotation: read back in /widgets and DRAWN, measured
# in a /screenshot (tests/typography_demo/ink.py) for where each label's
# ink falls in its box.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=typography_demo/spec_typography_demo \
    run_server_test "$(EX_BIN typography_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" typography_demo || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5k: AetherUIDriver tabs spec ==="
# tabs: type "tabs" with tabSelected/tabCount, each tab() page built, the
# tab_select route + app-side buttons switch pages and fire on_tab_change.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=tabs_demo/spec_tabs_demo \
    run_server_test "$(EX_BIN tabs_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" tabs_demo || FAIL=$((FAIL + 1))
fi

echo "=== Phase 5k2: AetherUIDriver menu-bar spec ==="
# menu: GET /menus lists the bar's menus + item labels; POST
# /menu/{h}/activate fires the item's real closure (native GTK4 GAction /
# NSMenu / win32), with the effect observable in the bound counter.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=menu/spec_menu \
    run_server_test "$(EX_BIN menu)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" menu || FAIL=$((FAIL + 1))
fi

echo "=== Phase 5k3: AetherUIDriver reactive-bindings spec (each_bind + computed) ==="
# rbind: list-typed state drives each_update via each_bind; computed_s recomputes
# a derived state when an input changes. Backend-agnostic (state layer).
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=rbind_demo/spec_rbind_demo \
    run_server_test "$(EX_BIN rbind_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" rbind_demo || FAIL=$((FAIL + 1))
fi

echo "=== Phase 5k4: AetherUIDriver typography / multi-select / double-click specs ==="
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=typo_demo/spec_typo_demo \
    run_server_test "$(EX_BIN typo_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" typo_demo || FAIL=$((FAIL + 1))
    UI_SPEC=multiselect_demo/spec_multiselect_demo \
    run_server_test "$(EX_BIN multiselect_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" multiselect_demo || FAIL=$((FAIL + 1))
    UI_SPEC=selmode_demo/spec_selmode_demo \
    run_server_test "$(EX_BIN selmode_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" selmode_demo || FAIL=$((FAIL + 1))
    UI_SPEC=dblclick_demo/spec_dblclick_demo \
    run_server_test "$(EX_BIN dblclick_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" dblclick_demo || FAIL=$((FAIL + 1))
fi

echo "=== Phase 5k5: AetherUIDriver tree + table-delegate/bind specs ==="
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=tree_demo/spec_tree_demo \
    run_server_test "$(EX_BIN tree_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" tree_demo || FAIL=$((FAIL + 1))
    UI_SPEC=tabledeleg_demo/spec_tabledeleg_demo \
    run_server_test "$(EX_BIN tabledeleg_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" tabledeleg_demo || FAIL=$((FAIL + 1))
fi

echo "=== Phase 5k6: AetherUIDriver weight-clamp + shortcut-scope/chord specs ==="
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=weightclamp_demo/spec_weightclamp_demo \
    run_server_test "$(EX_BIN weightclamp_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" weightclamp_demo || FAIL=$((FAIL + 1))
    UI_SPEC=flexround_demo/spec_flexround_demo \
    run_server_test "$(EX_BIN flexround_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" flexround_demo || FAIL=$((FAIL + 1))
    UI_SPEC=shortcut_demo/spec_shortcut_demo \
    run_server_test "$(EX_BIN shortcut_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" shortcut_demo || FAIL=$((FAIL + 1))
    UI_SPEC=polish_demo/spec_polish_demo \
    run_server_test "$(EX_BIN polish_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" polish_demo || FAIL=$((FAIL + 1))
    AETHER_UI_LIST_DEBUG=1 \
    UI_SPEC=vlist_demo/spec_vlist_demo \
    run_server_test "$(EX_BIN vlist_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" vlist_demo || FAIL=$((FAIL + 1))
    UI_SPEC=wshortcut_demo/spec_wshortcut_demo \
    run_server_test "$(EX_BIN wshortcut_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" wshortcut_demo || FAIL=$((FAIL + 1))
    UI_SPEC=multiwindow_demo/spec_multiwindow_demo \
    run_server_test "$(EX_BIN multiwindow_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" multiwindow_demo || FAIL=$((FAIL + 1))
    UI_SPEC=winmenu_demo/spec_winmenu_demo \
    run_server_test "$(EX_BIN winmenu_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" winmenu_demo || FAIL=$((FAIL + 1))
    UI_SPEC=reorder_demo/spec_reorder_demo \
    run_server_test "$(EX_BIN reorder_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" reorder_demo || FAIL=$((FAIL + 1))
    # reorderable(): a row's children dragged among themselves, with the
    # row's real geometry through the driver's /drag (the stack's gap rule).
    UI_SPEC=reorderable_demo/spec_reorderable_demo \
    run_server_test "$(EX_BIN reorderable_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" reorderable_demo || FAIL=$((FAIL + 1))
    # Overlay entry transitions — the deterministic contract (animation OFF):
    # dismiss removes the entry at once. The exit-tween-observable case runs in
    # its own animation-ON phase below.
    UI_SPEC=overlaytr_demo/spec_overlaytr_demo \
    run_server_test "$(EX_BIN overlaytr_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" overlaytr_demo || FAIL=$((FAIL + 1))
    # Accessibility semantics — role/name/description read back from the real
    # backend accessible state (GtkAccessible / MSAA / NSAccessibility).
    UI_SPEC=a11y_demo/spec_a11y_demo \
    run_server_test "$(EX_BIN a11y_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" a11y_demo || FAIL=$((FAIL + 1))
    # Backdrop material — a blur request degrades to tint on GTK4/win32 (no
    # in-window backdrop blur); the effective material is reported, not silent.
    UI_SPEC=material_demo/spec_material_demo \
    run_server_test "$(EX_BIN material_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" material_demo || FAIL=$((FAIL + 1))
    # Stylesheet/theming layer — element/class cascade + live re-theme,
    # asserted from the backend's fg/bg readback.
    UI_SPEC=themes_demo/spec_themes_demo \
    run_server_test "$(EX_BIN themes_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" themes_demo || FAIL=$((FAIL + 1))

    UI_SPEC=roles_demo/spec_roles_demo \
    run_server_test "$(EX_BIN roles_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" roles_demo || FAIL=$((FAIL + 1))

    UI_SPEC=command_demo/spec_command_demo \
    run_server_test "$(EX_BIN command_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" command_demo || FAIL=$((FAIL + 1))
    # AeCS vs CSS semantics — W3C Selectors/cascade intent + pinned divergences.
    UI_SPEC=csssem_demo/spec_csssem_demo \
    run_server_test "$(EX_BIN csssem_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" csssem_demo || FAIL=$((FAIL + 1))
    # AeCS Zen Garden — one tree, many skins (in-code + .aecs file palettes).
    UI_SPEC=zen_demo/spec_zen_demo \
    run_server_test "$(EX_BIN zen_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" zen_demo || FAIL=$((FAIL + 1))
    # QML-alike states on AeCS + Swing-style undo manager.
    UI_SPEC=states_demo/spec_states_demo \
    run_server_test "$(EX_BIN states_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" states_demo || FAIL=$((FAIL + 1))
    UI_SPEC=undo_demo/spec_undo_demo \
    run_server_test "$(EX_BIN undo_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" undo_demo || FAIL=$((FAIL + 1))
    # The clipboard, HEADLESS: every backend's clipboard is the driver's
    # buffer (GET and POST /clipboard), so the spec checks both halves without
    # touching the clipboard of the machine it runs on.
    AETHER_UI_HEADLESS=1 UI_SPEC=clipboard/spec_clipboard \
    run_server_test "$(EX_BIN clipboard)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" clipboard || FAIL=$((FAIL + 1))
    # open_url, HEADLESS: every backend records the URL instead of handing it
    # to the OS, and GET /opened_urls lists it (toolkit-envy G6). Headless is
    # the point of the spec, so this one app is launched with it set.
    AETHER_UI_HEADLESS=1 UI_SPEC=openurl_demo/spec_openurl_demo \
    run_server_test "$(EX_BIN openurl_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" openurl_demo || FAIL=$((FAIL + 1))
    # Dialogs, HEADLESS: open_file / save_file / pick_folder take the answer
    # a spec queued with POST /prompts/answer (else cancel), and GET /prompts
    # records what was asked (toolkit-envy G6). Headless for the same reason.
    AETHER_UI_HEADLESS=1 UI_SPEC=prompt_demo/spec_prompt_demo \
    run_server_test "$(EX_BIN prompt_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" prompt_demo || FAIL=$((FAIL + 1))
    UI_SPEC=textpath_demo/spec_textpath_demo \
    run_server_test "$(EX_BIN textpath_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" textpath_demo || FAIL=$((FAIL + 1))
    UI_SPEC=pills_demo/spec_pills_demo \
    run_server_test "$(EX_BIN pills_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" pills_demo || FAIL=$((FAIL + 1))
    UI_SPEC=icons_demo/spec_icons_demo \
    run_server_test "$(EX_BIN icons_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" icons_demo || FAIL=$((FAIL + 1))
    UI_SPEC=disclosure_demo/spec_disclosure_demo \
    run_server_test "$(EX_BIN disclosure_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" disclosure_demo || FAIL=$((FAIL + 1))
fi

echo "=== Phase 5l: AetherUIDriver app/demo specs (frames / falling_blocks / svg_tetris / rubiks_cube / tumbling_cube) ==="
# The AeVG games + interactive demos (apps/, not examples/): each drives its
# buttons and canvas through the driver end-to-end, complementing the pure
# engine unit tests in Phase 0. AEVG_BIN resolves target/build/apps/<name>/bin/<name>.
if [ "$SPEC_OK" -eq 1 ]; then
    UI_SPEC=frames_demo/spec_frames_demo \
    run_server_test "$(AEVG_BIN frames_demo)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" frames_demo || FAIL=$((FAIL + 1))
    # This one runs with animations OFF, unlike the transition proofs below.
    # It asserts that a drag produces a CLIPPED paint, and frames_demo never
    # clips while the scene animates (7e1ebd1). It was wired here with
    # animations forced on a day before that gate landed (d4ca5382), so its
    # premise has been false ever since: every paint went full-canvas and the
    # assertion could not pass on any backend. Leaving the global
    # AETHER_UI_NO_ANIMATION=1 in place is what lets the clip path engage.
    run_server_test "$(AEVG_BIN frames_demo)" \
                    "$SCRIPT_DIR/tests/frames_demo/test_stage25_clip_surface.sh" \
                    frames_stage25 || FAIL=$((FAIL + 1))
    UI_SPEC=falling_blocks/spec_falling_blocks \
    run_server_test "$(AEVG_BIN falling_blocks)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" falling_blocks || FAIL=$((FAIL + 1))
    UI_SPEC=svg_tetris/spec_svg_tetris \
    run_server_test "$(AEVG_BIN svg_tetris)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" svg_tetris || FAIL=$((FAIL + 1))
    UI_SPEC=rubiks_cube/spec_rubiks_cube \
    run_server_test "$(AEVG_BIN rubiks_cube)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" rubiks_cube || FAIL=$((FAIL + 1))
    UI_SPEC=tumbling_cube/spec_tumbling_cube AEVG_FREEZE=1 \
    run_server_test "$(AEVG_BIN tumbling_cube)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" tumbling_cube || FAIL=$((FAIL + 1))
    UI_SPEC=font_picker/spec_font_picker \
    run_server_test "$(AEVG_BIN font_picker)" \
                    "$SCRIPT_DIR/tests/run_spec.sh" font_picker || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5h2: overlay entry EXIT transition proof (animations ON) ==="
# With animation on, dismissing a transitioned overlay must play its exit tween
# (exiting:1) BEFORE removal — the spec's anim-on branch asserts that. Same
# binary + spec as the deterministic run above; only the flag differs.
if [ "$SPEC_OK" -eq 1 ]; then
    ( unset AETHER_UI_NO_ANIMATION
      UI_SPEC=overlaytr_demo/spec_overlaytr_demo \
      run_server_test "$(EX_BIN overlaytr_demo)" \
                      "$SCRIPT_DIR/tests/run_spec.sh" overlaytr_demo ) || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 5h: implicit transitions tween proof (animations ON) ==="
# ui.transition must actually TWEEN: screenshot mid-flight differs from
# settled. Shell checks (PNG byte compare — see tests/transitions_demo/).
if true; then
    ( unset AETHER_UI_NO_ANIMATION
      run_server_test "$(EX_BIN transitions_demo)"                       "$SCRIPT_DIR/tests/transitions_demo/test_tween.sh" transitions ) || FAIL=$((FAIL + 1))
    ( unset AETHER_UI_NO_ANIMATION
      run_server_test "$(EX_BIN transitions_demo)"                       "$SCRIPT_DIR/tests/transitions_demo/test_easing_curve.sh" easingcurve ) || FAIL=$((FAIL + 1))
    ( unset AETHER_UI_NO_ANIMATION
      run_server_test "$(EX_BIN transitions_demo)"                       "$SCRIPT_DIR/tests/transitions_demo/test_spring_curve.sh" springcurve ) || FAIL=$((FAIL + 1))
fi

echo
echo "=== Phase 6: AetherUIDriver grand_perspective tests (Aeocha specs) ==="
# One Aeocha spec per app component (tests/grand_perspective/spec_*.ae —
# Aether programs driving the HTTP API via std.http.client; run_spec.sh is
# only include-path glue). Each spec runs against a FRESH app instance
# scanning a FRESH fixture — the fileops spec really trashes a fixture
# file, so isolation is what makes the specs order-independent. The app
# scans $AEVG_DIR on launch; specs assert against the same tree via
# $GP_FIXTURE. Fixture under $HOME: gio trash refuses /tmp on some OSes
# (FreeBSD: "Trashing on system internal mounts is not supported").
# Xvfb runs need the cairo renderer (GTK's NGL on llvmpipe churns memory).
if [ "$SPEC_OK" -eq 1 ]; then
    case "$LAUNCH_PREFIX" in *xvfb*) export GSK_RENDERER=cairo ;; esac
    for gp_spec in scan_and_list map_nav legend fileops hover_and_resize; do
        GP_FIX=$(mktemp -d "$HOME/.gp-ci-XXXXXX")
        mkdir -p "$GP_FIX/sub"
        head -c 400000 /dev/urandom > "$GP_FIX/big.bin"
        head -c 250000 /dev/urandom > "$GP_FIX/mid.bin"
        head -c 200000 /dev/urandom > "$GP_FIX/sub/inner.bin"
        export AEVG_DIR="$GP_FIX" GP_FIXTURE="$GP_FIX" UI_SPEC="grand_perspective/spec_${gp_spec}"
        run_server_test "$ROOT/target/build/apps/grand_perspective/bin/grand_perspective" \
                        "$SCRIPT_DIR/tests/run_spec.sh" "gp_${gp_spec}" || FAIL=$((FAIL + 1))
        unset AEVG_DIR GP_FIXTURE UI_SPEC
        rm -rf "$GP_FIX"
    done
    unset GSK_RENDERER
fi

echo
echo "=== Phase 7: AetherUIDriver LisMusic port spec ==="
# LisMusic (apps/LisMusic): the three-region shell renders, sidebar nav drives
# the right-page tab stack, search populates the each-list, transport wired.
# Real backends: contrib.sqlite (search history, history.db — cleaned per run),
# std.audio (playback; NULL backend under headless CI), std.worker+std.http
# (async search). LIS_OFFLINE=1 forces the deterministic canned search so the
# spec's assertions don't depend on a live network. AETHER_UI_HEADLESS keeps
# std.audio on its silent null backend.
if [ "$SPEC_OK" -eq 1 ] && [ "$LISMUSIC_BUILT" -eq 1 ]; then
    rm -f "$ROOT/history.db"
    export LIS_OFFLINE=1
    # .build.contrib.ae nodes emit under target/build.contrib/ (the node TYPE
    # routes the output tree), so the binary never lands under target/build/.
    # Prefer that tree, fall back to target/build/ for an older aeb — same
    # resolution spec_matrix.sh uses. Without this the launch read the wrong
    # tree and reported "test server never responded" for a binary sitting
    # built in the right one.
    LISMUSIC_BIN="$ROOT/target/build.contrib/apps/LisMusic/bin/LisMusic"
    [ -x "$LISMUSIC_BIN" ] || LISMUSIC_BIN="$ROOT/target/build/apps/LisMusic/bin/LisMusic"
    UI_SPEC=LisMusic/spec_lismusic \
    run_server_test "$LISMUSIC_BIN" \
                    "$SCRIPT_DIR/tests/run_spec.sh" lismusic || FAIL=$((FAIL + 1))
    unset LIS_OFFLINE
    rm -f "$ROOT/history.db"
elif [ "$SPEC_OK" -eq 1 ]; then
    echo "  SKIP lismusic spec (LisMusic was not built; libaether_sqlite absent)"
fi

echo
if [ "$FAIL" -eq 0 ]; then
    echo "=== CI result: all phases passed ==="
    exit 0
else
    echo "=== CI result: $FAIL phase(s) failed ==="
    exit 1
fi