re: the transition is overlap, not ramp-then-hold -- and the fade-in was 5x wrong

screen-transitions.md carried a 14-unit "black hold" that the page itself
flagged as arithmetic rather than measurement. Measured it against the running
game; the guess was wrong, and finding the instrument to measure it turned up a
second, larger error in the same page.

1. fade_quads.py was STALE. It read each pose's time from blk+36 -- the next
record's time word -- the association the keyframe record-layout fix retired in
the crate. sylpheed-cli was rebuilt at the time; the Python helper was never
swept with it. Signature: it cannot time a group's last pose, so it printed a
trailing `t=-`. Fixed, controlled against the rebuilt `screen info` ([0 12 70
80] for build 5's pteff00.prm).

2. Through it, the page labelled the quad's CLEAR-hold as its fade-in and
published 0.87 s / 0.97 s / 4.08 s for a ramp that is 0.20 s / 0.20 s / 0.27 s.
A port pacing its menu fade-in off that would run it 5x too slow.

3. The measurement. fade_decompose.sh boots to the main menu, arms the UI draw
capture there, then presses (B), so one 260-frame window holds the whole screen
change. The fade quad is identified rather than guessed: a .prm carries no
tex[base=] and paints last, so it is the last full-screen untextured quad of a
frame. Control first -- the quad's ramp is decoded at 10 units = 5 frames, and
measures 4 submitted-frame steps with one unlogged frame in the span.

Result: content elements begin fading at frame 34; the black quad first appears
at 40 and is opaque by 43; the menu's last frame is 45; frame 46 has 6 draws
against 12. So the ~14 extra units are the content's own fade-outs OVERLAPPING
the quad's ramp, not a hold after it, and the inter-screen black is one frame.

Refutation attempted: sylpheed-port's entries 13/14 twins. Re-derived off the
disc -- 3.06 / 4.33 / 47.91, identical to two decimals. Recorded as confirming
their addressing and arithmetic, NOT as independent support: same renderer,
same disc, which is their own rule.

Reach: one transition, one run; the frame axis has gaps (232 headers over frames
3..260), so every span is +-1 frame.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Wuu56cE8vJGTBtn1ppsk8v

tools/re-capture/fade_decompose.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Decompose a screen transition's ~0.4 s fade-out into RAMP + HOLD, at the
+# emulator's own frame granularity.
+#
+# docs/re/screen-transitions.md measures the fade-out as ~0.4 s (~24 units) while
+# `pteff00.prm`'s final declared ramp is 70->80 = 10 units. The remainder is
+# currently ARITHMETIC THAT FITS -- "the other 14 units must be the black hold"
+# -- and that page says so itself. This measures it instead.
+#
+# The design point: arm the UI draw capture ON THE MAIN MENU, then press (B).
+# One capture window then contains
+#   * the menu's fade-OUT   -- the unknown, and
+#   * the title's fade-IN   -- whose ramp IS decoded from the file (build 4's
+#                              pteff00.prm, t=16 a=255 -> t=261 a=0, 245 units),
+# so the run carries its own control: an instrument that cannot reproduce the
+# known fade-in cannot be trusted on the unknown fade-out.
+#
+# Traps inherited from menu_draw_capture.sh, both already paid for:
+#   * F10 arms the capture AND opens the emulator menu bar; any Xenia UI makes
+#     IsUIActive() true and every later guest keystroke is swallowed. Click the
+#     game surface to dismiss before touching the pad.
+#   * a 0.12 s tap gets missed; hold (B) 0.5 s and confirm [RE-INPUT] delivery.
+#
+# Usage: fade_decompose.sh [out_dir]
+set -u
+export HOME=/sylph-home/re SDL_AUDIODRIVER=dummy DISPLAY=:98
+SD="$(cd "$(dirname "$0")" && pwd)"
+OUT="${1:-/sylph-home/re/fadecap}"
+mkdir -p "$OUT"; rm -f "$OUT"/xenia_re_ui_draws_*.log
+alive(){ ps -o pid=,stat= -C xenia_canary 2>/dev/null | awk '$2 !~ /^Z/ {print $1}'; }
+shot(){ screenshot "$1" >/dev/null 2>&1; }
+screen(){ shot /tmp/fdc.png; python3 "$SD/screen_id.py" /tmp/fdc.png | awk '{print $1}'; }
+
+( cd "$OUT" && nohup run-canary --mem_watch=false --log_ui_draws=true \
+    --ui_draw_capture_frames="${FRAMES:-260}" \
+    --ui_draw_capture_max="${MAXDRAWS:-400000}" \
+    --logged_profile_slot_0_xuid=B13EBABEBABEBABE \
+    >"$OUT/canary.stdout" 2>"$OUT/canary.stderr" & )
+sleep 8
+until xdotool search --name "Xenia-canary" >/dev/null 2>&1; do
+  [ -n "$(alive)" ] || { echo "EMULATOR GONE"; exit 4; }; sleep 1
+done
+win="$(xdotool search --name "Xenia-canary" | tail -1)"
+
+# 1. wait for the boot title; do not tap through the intro (a run that tapped
+#    every 4 s delivered 88 presses and ended on a black screen).
+deadline=$(( SECONDS + 420 )); s=""
+while [ $SECONDS -lt $deadline ]; do
+  s="$(screen)"; echo "t=${SECONDS}s $s"
+  [ "$s" = "title" ] && break
+  sleep 4
+done
+[ "$s" = "title" ] || { echo "NEVER REACHED THE TITLE"; exit 1; }
+
+# 2. one (A) on the boot title -> main menu
+python3 "$SD/pad.py" tap A 0.5
+for _ in 1 2 3 4 5 6; do
+  sleep 4; s="$(screen)"; echo "  after A: $s"
+  [ "$s" = "menu" ] && break
+done
+[ "$s" = "menu" ] || { echo "NO MENU (screen=$s)"; exit 2; }
+shot "$OUT/menu.png"
+
+# 3. arm the capture, dismiss the menu bar F10 opened, then press (B).
+#    Everything between F10 and (B) is spent inside the capture window, so keep
+#    it short: the window is FRAMES submitted frames, not seconds.
+xdotool windowactivate --sync "$win"; sleep 1
+xdotool key F10; sleep 0.6
+xdotool mousemove 900 400 click 1; sleep 0.6
+echo "-- (B) at $(date +%S.%N) --"
+python3 "$SD/pad.py" tap B 0.5
+sleep 12
+shot "$OUT/after-b.png"; echo "screen after B: $(screen)"
+
+grep -c "RE-INPUT" "$OUT/canary.stdout" 2>/dev/null | sed 's/^/[RE-INPUT] lines: /'
+ls -l "$OUT"/xenia_re_ui_draws_*.log 2>/dev/null || echo "NO CAPTURE LOG"
+grep -i "UI-CAP" "$OUT/canary.stdout" | tail -3
+echo "FADE CAPTURE DONE (emulator left running)"

tools/re-capture/fade_envelope.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Per-frame alpha of the fade quad (`pteff00.prm`), from a `log_ui_draws` capture.
+
+`screen-transitions.md` measures a screen change's fade-out as a ~0.4 s lump and
+then SPLITS it by arithmetic -- the declared ramp is 10 units, 0.4 s is ~24, "so
+the other ~14 must be the black hold". That page flags the split as a fit, not a
+measurement. This measures it.
+
+Identifying the quad, rather than guessing at it: the fade quad is a `.prm`
+PRIMITIVE, so its draw carries NO `tex[base=...]`, and it is its screen's
+last-painting element (structures/ui-paint-order-key.md). So: per frame, the LAST
+full-screen draw with no bound texture. Taking merely the last full-screen quad
+picks up textured backdrops and gets a different answer.
+
+⚠️ The frame axis has gaps. A 260-frame window produced 232 `--- frame` headers,
+so ~10 % of submitted frames carry no UI draw at all. A duration in frames is
+therefore +-1 frame per gap it spans, and this prints the gaps so a reader can
+see which spans are affected.
+
+    fade_envelope.py <capture.log>
+"""
+import re
+import sys
+sys.path.insert(0, __file__.rsplit("/", 1)[0])
+
+W, H = 1280, 720
+VERT = re.compile(r"col=([0-9A-F]{8})")
+
+
+def envelope(log):
+    """Yield (frame, alpha|None) -- alpha of the last untextured full-screen quad."""
+    frame, pending_untex = None, None
+    last = {}
+    seen = []
+    for line in open(log):
+        if line.startswith("--- frame"):
+            if frame is not None:
+                seen.append(frame)
+            frame = int(line.split()[2])
+            continue
+        m = re.match(r"\s*(\d+) prim=(\d+) indices=(\d+)", line)
+        if m:
+            # a primitive draw has no bound texture
+            pending_untex = ("tex[base=" not in line) and m.group(2) == "13"
+            continue
+        if "vb=0x" in line and pending_untex:
+            cols = VERT.findall(line)
+            # full-screen NDC quad: every vertex at +-1
+            if cols and line.count("[-1.00,1.00,") >= 1:
+                last[frame] = int(cols[-1][:2], 16)
+            pending_untex = None
+    if frame is not None:
+        seen.append(frame)
+    return last, seen
+
+
+def main():
+    last, seen = envelope(sys.argv[1])
+    gaps = [(a, b) for a, b in zip(seen, seen[1:]) if b != a + 1]
+    print(f"# {len(seen)} frame headers, {seen[0]}..{seen[-1]}; "
+          f"{sum(b-a-1 for a,b in gaps)} submitted frames carry no UI draw")
+    print("# gaps: " + " ".join(f"{a}->{b}" for a, b in gaps))
+    print("frame  alpha")
+    for f in seen:
+        a = last.get(f)
+        print(f"{f:6d}  {'-' if a is None else a:>5}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/re-capture/fade_quads.py

@@ -34,7 +34,13 @@ def parse(bundle):
             if blk+36 > len(bundle) or blk+36 > end: break
             g.append(dict(fade=be32(bundle,blk), sx=be32(bundle,blk+16), sy=be32(bundle,blk+20),
                           x=struct.unpack_from(">i",bundle,blk+28)[0], y=struct.unpack_from(">i",bundle,blk+32)[0],
-                          t=(be32(bundle,blk+36) if blk+40<=end else None)))
+                          # A POSE'S TIME PRECEDES IT (ui-keyframe-record-layout.md).
+                          # This read `blk+36` -- the NEXT record's time word --
+                          # which shifted every time by one slot and left the
+                          # last pose untimed. That stale association is what
+                          # made screen-transitions.md print a 0.87-4.08 s
+                          # fade-in and an untimed fade-out. Corrected 2026-08-30.
+                          t=be32(bundle,blk-4)))
         groups[idx]=g; pos=end
     return names, groups