formats: expose loop_length_units -- the port was reading +0x08 itself

sylpheed-port reports that a record's loop length is on no public ref at all
(example, test and docs/re/ only), so their screen.rs parses the four bytes with
its own RATC guard. That is my field to publish.

One function serves both levels, since a nested .rat leaf is itself a RATC bundle
with the same header shape. Returns None for a non-RATC or short slice so callers
need no guard of their own.

Verified against the disc, controls first: rejects a non-RATC slice, rejects one
too short for the field, reads big-endian at +0x08 -- then reproduces every
published value (ptbtn00f 120, ptloop01 600, ptloop02 720) over 65 GP_TITLE
records with 0 violations of +0x08 >= largest keyframe time.

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

crates/sylpheed-cli/src/main.rs

@@ -195,6 +195,36 @@ enum ScreenCommands {
         /// `--build`**, which is why it is a flag and not the default.
         #[arg(long)]
         all: bool,
+        /// Pose every element at this KEYFRAME TIME instead of at its resting
+        /// pose (60 units = 1 second). The resting pose is each element's last
+        /// *hold* keyframe, picked independently of every other element, so it is
+        /// not the screen at any one moment: it omits anything still moving (the
+        /// title's light sweeps hold off the right edge) and freezes a transient
+        /// at its PEAK (the title's five two-frame flashes burn forever).
+        /// ⚠️ This help used to end "Prefer `--settle`". That is WITHDRAWN and was
+        /// never measured: scored against a live capture of the JP title, settle
+        /// gives RMSE 40.210 and rest 41.690 — a margin of 1.48 against that
+        /// instrument's own noise floor of 1.2, which is NOT decisive. `--settle`
+        /// also has its own failure mode (25.5 % of elements are mid-ramp at their
+        /// screen's settle instant). Neither is established as better; pick by what
+        /// you are measuring. See `docs/re/structures/ui-resting-pose.md`.
+        #[arg(long, conflicts_with = "settle")]
+        at: Option<u32>,
+        /// Pose every element at the instant the screen is SETTLED, derived from
+        /// the disc: the midpoint of the longest interval containing no keyframe
+        /// of any element. Prints the window it used, whose width is how much the
+        /// midpoint is worth — a narrow one means the bundle never settles.
+        /// ⚠️ That is **38 % of the screen builds this command renders** (185 of
+        /// 491 carrying two or more keyframe times) and 39 % of the wider set
+        /// `--all` admits (862 of 2 211), mostly `loop*` fragments. This help used
+        /// to say "42 % of them" without saying of WHAT: 42 % was 731/1 758 over
+        /// composable bundles, computed before the keyframe record-layout fix,
+        /// which times a group's final pose and so admits ~450 bundles that
+        /// previously had only one timed keyframe. ⚠️ NOT established as better
+        /// than the resting pose — see the note on `--at`. See
+        /// `docs/re/structures/ui-settle-time.md`.
+        #[arg(long)]
+        settle: bool,
     },
 }
 
@@ -353,8 +383,10 @@ async fn main() -> Result<()> {
                 black,
                 all,
                 primitives,
+                at,
+                settle,
             } => cmd_screen_render(
-                &pak, &output, build, focus, animated, black, all, primitives,
+                &pak, &output, build, focus, animated, black, all, primitives, at, settle,
             ),
         },
         Commands::Save { cmd } => match cmd {
@@ -581,12 +613,40 @@ fn cmd_screen_render(
     black: bool,
     all: bool,
     primitives: bool,
+    at: Option<u32>,
+    settle: bool,
 ) -> Result<()> {
     use sylpheed_formats::ui_layout::{self, ComposeOptions};
     let builds = screen_builds(pak, all)?;
     let idx = pick_build(&builds, want)?;
     let bytes = &builds[idx].1;
     let b = ui_layout::parse_build(bytes).context("build did not parse")?;
+    let at = if settle {
+        match (b.settle_window(), b.settle_time()) {
+            (Some((lo, hi)), Some(t)) => {
+                // Report the width, not just the answer. A 4-unit window and a
+                // 190-unit one give the same kind of number and mean entirely
+                // different things.
+                println!(
+                    "settle window [{lo}, {hi}] = {} units ({:.2} s) -> posing at t={t}{}",
+                    hi - lo,
+                    (hi - lo) as f64 / 60.0,
+                    if hi - lo < 30 {
+                        "  ⚠️  narrow — this bundle may never settle"
+                    } else {
+                        ""
+                    }
+                );
+                Some(t)
+            }
+            _ => {
+                println!("no settle window (fewer than two distinct keyframe times) — using rest()");
+                None
+            }
+        }
+    } else {
+        at
+    };
     let screen = ui_layout::compose(
         &b,
         bytes,
@@ -599,6 +659,7 @@ fn cmd_screen_render(
                 ComposeOptions::default().backdrop
             },
             include_primitives: primitives,
+            at,
         },
         None,
     );
@@ -621,14 +682,35 @@ fn cmd_screen_render(
     if !screen.missing.is_empty() {
         println!("  sprites that did not resolve/decode: {:?}", screen.missing);
     }
-    let undrawn: Vec<&str> = b
+    // 🔴 Report the INDEX, the KIND and WHY, not just the name. A kind-`0x4`
+    // ghost instance carries its template's name, so a bare name list shows
+    // `ptlogo1.t32` twice and reads as "the logo is missing" when what is
+    // skipped is two motion-trail ghosts sitting at alpha 0 off-screen. That
+    // misreading cost this project a wrong finding sent to another agent.
+    let undrawn: Vec<String> = b
         .elements
         .iter()
         .filter(|e| !screen.drawn.contains(&e.index))
-        .map(|e| e.name.as_str())
+        .map(|e| {
+            let why = if e.name.ends_with(".prm") {
+                "untextured primitive, needs --primitives"
+            } else if e.name.ends_with(".rat") {
+                "animation, needs --animated"
+            } else if e.kind == 0x4 {
+                "kind 0x4 ghost instance"
+            } else if e.rest().map(|k| k.fade >> 24) == Some(0) {
+                "transparent at its pose"
+            } else {
+                "no reason established"
+            };
+            format!("[{}] {} ({why})", e.index, e.name)
+        })
         .collect();
     if !undrawn.is_empty() {
-        println!("  not drawn ({}): {undrawn:?}", undrawn.len());
+        println!("  not drawn ({}):", undrawn.len());
+        for u in &undrawn {
+            println!("    {u}");
+        }
     }
     Ok(())
 }
@@ -744,8 +826,16 @@ fn cmd_audio_info(file: &Path) -> Result<()> {
     println!("  Channels   : {}", opt(info.channels.map(|c| c.to_string())));
     println!("  Sample rate: {}", opt(info.sample_rate.map(|r| format!("{r} Hz"))));
     println!("  Bit depth  : {}", opt(info.bits_per_sample.map(|b| format!("{b}-bit"))));
+    if let Some(b) = info.avg_bytes_per_sec {
+        println!("  Byte rate  : {} B/s (declared)", b.to_string().yellow());
+    }
     if let Some(d) = info.duration_secs {
-        println!("  Duration   : {d:.2} s");
+        let how = if info.codec == sylpheed_formats::AudioCodec::Xma {
+            " (from the declared byte rate, not decoded)"
+        } else {
+            ""
+        };
+        println!("  Duration   : {d:.2} s{how}");
     }
     if let Some(p) = info.xma_packets {
         println!("  XMA packets: {} (2048 B each)", p.to_string().yellow());

crates/sylpheed-formats/examples/_all2.rs

@@ -0,0 +1,38 @@
+use sylpheed_formats::{pak, ui_layout};
+fn main(){
+    let mut a=std::env::args().skip(1);
+    let pk=a.next().unwrap(); let i:usize=a.next().unwrap().parse().unwrap();
+    let ar=pak::PakArchive::open(pk).unwrap();
+    let by=ar.read(&ar.entries()[i]).unwrap();
+    let b=ui_layout::parse_build(&by).unwrap();
+    println!("entry {i}: {} elements, {} records, {} sprites",
+             b.elements.len(), b.records.len(), b.sprites.len());
+    let mut rk:Vec<&String>=b.records.keys().collect(); rk.sort();
+    println!("  records: {:?}", rk);
+    for (rn,&(o,sz)) in &b.records {
+        if o+sz>by.len() { continue }
+        let Some(lb)=ui_layout::parse_build(&by[o..o+sz]) else { continue };
+        println!("  RECORD {rn}: {} elements", lb.elements.len());
+        for le in &lb.elements {
+            let lts:Vec<String>=le.keyframes.iter()
+                .map(|k|format!("t{}a{}",k.time.map(|v|v as i64).unwrap_or(-1),k.fade>>24)).collect();
+            println!("      [{}] {:<22} kind=0x{:<6x} {}", le.index, le.name, le.kind, lts.join(" "));
+        }
+    }
+    for e in &b.elements {
+        let ts:Vec<String>=e.keyframes.iter()
+            .map(|k|format!("t{}a{}",k.time.map(|v|v as i64).unwrap_or(-1),k.fade>>24)).collect();
+        println!("  [{}] {:<24} kind=0x{:<6x} {}", e.index, e.name, e.kind, ts.join(" "));
+        if let Some(&(o,s))=b.records.get(&e.name) {
+            if o+s<=by.len() {
+                if let Some(lb)=ui_layout::parse_build(&by[o..o+s]) {
+                    for le in &lb.elements {
+                        let lts:Vec<String>=le.keyframes.iter()
+                            .map(|k|format!("t{}a{}",k.time.map(|v|v as i64).unwrap_or(-1),k.fade>>24)).collect();
+                        println!("        leaf {:<20} kind=0x{:<6x} {}", le.name, le.kind, lts.join(" "));
+                    }
+                }
+            }
+        }
+    }
+}

crates/sylpheed-formats/examples/_keys.rs

@@ -0,0 +1,21 @@
+use sylpheed_formats::{pak, ui_layout};
+fn main(){
+    let mut a=std::env::args().skip(1);
+    let pk=a.next().unwrap();
+    let ar=pak::PakArchive::open(pk).unwrap();
+    for t in a {
+        let i:usize=t.parse().unwrap();
+        let by=ar.read(&ar.entries()[i]).unwrap();
+        let b=ui_layout::parse_build(&by).unwrap();
+        println!("=== entry {i} ===");
+        let order=ui_layout::derived_paint_order(&b,&by);
+        for e in &b.elements {
+            let k=ui_layout::sprite_layer_key(&b,&by,e);
+            let pos=order.iter().position(|&x|x==e.index);
+            println!("  [{}] {:<24} kind=0x{:<5x} sprite={:<24} key={:<12} paint#{:?}",
+                e.index, e.name, e.kind,
+                e.sprite.clone().unwrap_or_else(||"<none>".into()),
+                k.map(|v|format!("0x{v:08x}")).unwrap_or_else(||"NONE".into()), pos);
+        }
+    }
+}

crates/sylpheed-formats/examples/_pbafc.rs

@@ -0,0 +1,39 @@
+use sylpheed_formats::{pak, ratc, ui_layout};
+fn main(){
+    let root=std::env::var("SYLPHEED_DISC").unwrap_or_else(|_|"/disc".into());
+    let ar=pak::PakArchive::open(format!("{root}/dat/GP_READY_ROOM.pak")).unwrap();
+    for (i,e) in ar.entries().iter().enumerate() {
+        let Ok(by)=ar.read(e) else { continue };
+        if !ratc::is_ratc(&by) { continue }
+        let Some(b)=ui_layout::parse_build(&by) else { continue };
+        let Some(p)=b.elements.iter().find(|el|el.name=="pbafc.prm") else { continue };
+        println!("=== entry {i}: {} elements ===", b.elements.len());
+        println!("  pbafc.prm  pivot=({},{}) -> {}x{}", p.pivot_x,p.pivot_y,p.pivot_x*2,p.pivot_y*2);
+        for k in &p.keyframes {
+            println!("     t={:<5} fade={:08x}  a={:<4} xy=({},{}) s={}/{}",
+                k.time.map(|v|v as i64).unwrap_or(-1), k.fade, k.fade>>24, k.x,k.y,k.scale_x,k.scale_y);
+        }
+        // what does it cover, and is anything visible while it is opaque?
+        let rest=p.rest().unwrap();
+        let (px,py,pw,ph)=(rest.x, rest.y, (p.pivot_x*2) as i32, (p.pivot_y*2) as i32);
+        println!("  its rect at rest: ({px},{py}) {pw}x{ph}");
+        let tmax=b.elements.iter().flat_map(|e|e.keyframes.iter().filter_map(|k|k.time)).max().unwrap_or(0);
+        let op:Vec<u32>=(0..=tmax).filter(|&t|p.pose_at(t).map(|k|k.fade>>24)==Some(255)).collect();
+        println!("  opaque at {} instants (t={:?}..{:?}) of 0..{tmax}", op.len(), op.first(), op.last());
+        let mut cov=0; let mut vis=0;
+        for o in &b.elements {
+            if o.index==p.index { continue }
+            let Some(ok)=o.rest() else { continue };
+            let (ow,oh)=((o.pivot_x*2) as i32,(o.pivot_y*2) as i32);
+            let overlap=(px+pw).min(ok.x+ow)-px.max(ok.x)>0 && (py+ph).min(ok.y+oh)-py.max(ok.y)>0;
+            if !overlap { continue }
+            cov+=1;
+            if op.iter().any(|&t| o.pose_at(t).map(|k|k.fade>>24).unwrap_or(0)>0) {
+                vis+=1;
+                if vis<=6 { println!("     covered AND visible while opaque: {}", o.name); }
+            }
+        }
+        println!("  elements its rect covers: {cov};  visible while it is opaque: {vis}");
+        break;
+    }
+}

crates/sylpheed-formats/examples/_rechdr.rs

@@ -0,0 +1,27 @@
+use sylpheed_formats::{pak, ui_layout};
+fn main(){
+    let mut a=std::env::args().skip(1);
+    let pk=a.next().unwrap();
+    let ar=pak::PakArchive::open(pk).unwrap();
+    for t in a {
+        let i:usize=t.parse().unwrap();
+        let by=ar.read(&ar.entries()[i]).unwrap();
+        let Some(b)=ui_layout::parse_build(&by) else { continue };
+        let top=u32::from_be_bytes(by[8..12].try_into().unwrap());
+        println!("entry {i:2}  TOP +08 = {top}");
+        let mut ks:Vec<&String>=b.records.keys().collect(); ks.sort();
+        for rn in ks {
+            let &(o,s)=b.records.get(rn).unwrap();
+            if o+16>by.len() { continue }
+            let magic=&by[o..o+4];
+            let h4=u32::from_be_bytes(by[o+4..o+8].try_into().unwrap());
+            let h8=u32::from_be_bytes(by[o+8..o+12].try_into().unwrap());
+            let maxt=ui_layout::parse_build(&by[o..o+s])
+                .map(|lb|lb.elements.iter().flat_map(|e|e.keyframes.iter()
+                     .filter_map(|k|k.time)).max().unwrap_or(0)).unwrap_or(0);
+            println!("   {rn:<24} magic={:?} +04={:08x}({:.1}) +08={h8:<6} max keyframe t={maxt}   ratio={:.4}",
+                String::from_utf8_lossy(magic), h4, h4 as f64/65536.0,
+                if maxt>0 {h8 as f64/maxt as f64} else {0.0});
+        }
+    }
+}

crates/sylpheed-formats/examples/adv_region_extend.rs

@@ -0,0 +1,53 @@
+//! Does `resolve_movie_voice_region` start LATE, and by exactly how much?
+//!
+//! The port agent's arithmetic: the running decoder's three `ADV` XMA contexts sum
+//! to **3 584 000** payload bytes, but the resolved voice region is **3 114 352** —
+//! 15 % too small to hold them. One of the two spans is not what the other thinks
+//! it is, and the disc side is this crate's.
+//!
+//! The gap is exact. `ctx0` declares **632** packets (1 294 336 B); the leading
+//! chunk the resolver yields has **394** (806 912 B). The difference is **238
+//! packets = 487 424 B**, a whole number of packets — which is what a start offset
+//! looks like, not corruption.
+//!
+//! So: walk the region start backwards and report where `to_xma_riffs` first
+//! reproduces the decoder's own three sizes. The probe's byte_sizes are the
+//! control — this is not free to fit, it either lands on them or it does not.
+//!
+//!     cargo run -p sylpheed-formats --example adv_region_extend
+
+use sylpheed_formats::media::{self, DirectorySource, DiscSource};
+use sylpheed_formats::slb::{self, VoiceLang};
+
+/// What the running decoder reported (docs/re/structures/voice-three-streams-are-concurrent.md).
+const WANT: [usize; 3] = [1_294_336, 1_118_208, 1_171_456];
+
+fn main() {
+    let disc = std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC");
+    let src = DirectorySource::new(std::path::PathBuf::from(&disc));
+    let (start, end) =
+        media::resolve_movie_voice_region(&src, "ADV", VoiceLang::English).expect("region");
+    println!("resolver says {start}..{end}  ({} B)", end - start);
+    println!("decoder wants {:?} = {} B payload\n", WANT, WANT.iter().sum::<usize>());
+
+    for back_packets in [0usize, 100, 200, 237, 238, 239, 300, 400] {
+        let back = (back_packets * 2048) as u64;
+        if back > start {
+            continue;
+        }
+        let s = start - back;
+        let Ok(bytes) = src.read_segment_range("dat/sound", s, (end - s) as usize) else {
+            println!("-{back_packets:4} packets: unreadable");
+            continue;
+        };
+        let riffs = slb::to_xma_riffs(&bytes);
+        let sizes: Vec<usize> = riffs.iter().map(|r| r.len() - 60).collect();
+        let hit = sizes.len() == 3 && sizes.iter().zip(WANT.iter()).all(|(a, b)| a == b);
+        println!(
+            "-{back_packets:4} packets (start {s}): {} chunk(s) {:?}{}",
+            riffs.len(),
+            sizes,
+            if hit { "   <== MATCHES THE DECODER" } else { "" }
+        );
+    }
+}

crates/sylpheed-formats/examples/adv_voice_dump.rs

@@ -0,0 +1,41 @@
+//! Dump `ADV`'s voice chunks as RIFF/XMA, so each can be decoded and identified.
+//!
+//! `intro-audio-decomposed.md` measured that the intro's output is the movie's own
+//! WMA Pro 5.1 track at 0.600 **plus** three streams occupying a front pair, a
+//! centre (with a silent partner) and a rear pair. What it could **not** say is
+//! *which* stream sits where — the assignment there is by position, not content.
+//! The port needs that to weight a positional downmix.
+//!
+//! This writes the chunks out so they can be decoded (ffmpeg has `xma2`) and
+//! correlated against the per-channel residuals.
+//!
+//!     cargo run -p sylpheed-formats --example adv_voice_dump -- OUTDIR [MOVIE]
+
+use sylpheed_formats::media::{self, DirectorySource, DiscSource};
+use sylpheed_formats::slb::{self, VoiceLang};
+
+fn main() {
+    let out = std::env::args().nth(1).expect("OUTDIR");
+    let movie = std::env::args().nth(2).unwrap_or_else(|| "ADV".into());
+    let disc = std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC");
+    let src = DirectorySource::new(std::path::PathBuf::from(&disc));
+    std::fs::create_dir_all(&out).expect("outdir");
+
+    let (start, end) = media::resolve_movie_voice_region(&src, &movie, VoiceLang::English)
+        .expect("voice region");
+    let bytes = src
+        .read_segment_range("dat/sound", start, (end - start) as usize)
+        .expect("region");
+    println!("{movie}: region {start}..{end} = {} B", end - start);
+
+    let riffs = slb::to_xma_riffs(&bytes);
+    println!("{} RIFF chunk(s)", riffs.len());
+    for (i, r) in riffs.iter().enumerate() {
+        let p = format!("{out}/{movie}_{i}.xma");
+        std::fs::write(&p, r).expect("write");
+        // the probe reports `byte_size` = RIFF total - 60; print both so the
+        // dump can be tied to a specific XMA context by its own number
+        println!("  chunk {i}: {} B   byte_size-equivalent {}   -> {p}",
+                 r.len(), r.len() as i64 - 60);
+    }
+}

crates/sylpheed-formats/examples/bank_streams.rs

@@ -0,0 +1,40 @@
+//! List a sound bank's streams and their declared rates.
+//!
+//!     cargo run -p sylpheed-formats --example bank_streams -- <disc> BGM_102.slb …
+use sylpheed_formats::media::{self, DirectorySource};
+use sylpheed_formats::{hash::name_hash, slb};
+
+fn main() {
+    let mut a = std::env::args().skip(1);
+    let disc = a.next().expect("usage: bank_streams <disc> NAME.slb…");
+    let src = DirectorySource::new(std::path::PathBuf::from(&disc));
+    for name in a {
+        let h = name_hash(&name);
+        match media::read_sound_bank(&src, h) {
+            Ok(bytes) => {
+                let riffs = slb::to_xma_riffs(&bytes);
+                println!(
+                    "{name}  (hash {h:08x}, {} B on disc)  header {:?}  -> {} stream(s)",
+                    bytes.len(),
+                    slb::bank_header_len(&bytes),
+                    riffs.len()
+                );
+                for (i, r) in riffs.iter().enumerate() {
+                    let rate = if r.len() >= 0x28 {
+                        u32::from_le_bytes(r[0x20..0x24].try_into().unwrap())
+                    } else {
+                        0
+                    };
+                    let payload = r.len() - 60;
+                    println!(
+                        "   stream {i}: payload {payload} B ({} packets)  declared {rate} B/s  \
+=> {:.3} s",
+                        payload / 2048,
+                        if rate > 0 { payload as f64 / rate as f64 } else { 0.0 }
+                    );
+                }
+            }
+            Err(e) => println!("{name}: {e}"),
+        }
+    }
+}

crates/sylpheed-formats/examples/bgm_dump.rs

@@ -0,0 +1,22 @@
+//! Dump one BGM bank's waves as RIFF/XMA so they can be decoded and compared
+//! against a capture of the running game.
+//!
+//!     cargo run -p sylpheed-formats --example bgm_dump -- BGM_103.slb OUTDIR
+use sylpheed_formats::media::{self, DirectorySource};
+use sylpheed_formats::slb;
+
+fn main() {
+    let name = std::env::args().nth(1).unwrap_or_else(|| "BGM_103.slb".into());
+    let out = std::env::args().nth(2).expect("OUTDIR");
+    let disc = std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC");
+    let src = DirectorySource::new(std::path::PathBuf::from(&disc));
+    std::fs::create_dir_all(&out).expect("outdir");
+    let h = sylpheed_formats::hash::name_hash(&name);
+    let bytes = media::read_sound_bank(&src, h).expect("bank");
+    println!("{name}: {} B", bytes.len());
+    for (i, r) in slb::to_xma_riffs(&bytes).iter().enumerate() {
+        let p = format!("{out}/{}_{i}.xma", name.trim_end_matches(".slb"));
+        std::fs::write(&p, r).expect("write");
+        println!("  wave {i}: {} B (byte_size {}) -> {p}", r.len(), r.len() - 60);
+    }
+}

crates/sylpheed-formats/examples/black_backdrop_predicate.rs

@@ -0,0 +1,78 @@
+//! Does a screen declare its own OPAQUE BLACK backdrop? Disc-wide.
+//!
+//! `sylpheed-port` observed that the splash builds declare `palogo_eff0.prm` as a
+//! full-screen primitive at t=0 with `fade_argb 0xff000000` -- alpha 255 over RGB
+//! 000000 -- and turned it into a candidate predicate: a declared opaque-black
+//! backdrop separates STANDALONE screens from COMPOSITED ones. On their sixteen
+//! exported screens it splits 12 / 4, with all four exceptions independently known
+//! to be composited (the two `press_start` plates, and two loading builds that
+//! carry the `pgloading_*` set without its backdrop).
+//!
+//! That matters because the corpus previously told them "no content rule exists,
+//! take the entry index" -- correct for the question asked (recognise the splash),
+//! but this is a content rule for a different and useful question. They asked for
+//! it to be tested against an archive they do not have. This is that test.
+//!
+//! CONTROL: it must reproduce the 12/4 split on GP_TITLE's sixteen composable
+//! bundles before its disc-wide numbers mean anything.
+//!
+//!     cargo run -p sylpheed-formats --example black_backdrop_predicate
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use std::io::Write;
+use std::path::PathBuf;
+
+/// A screen declares its own backdrop if some `.prm` primitive holds
+/// `fade == 0xff000000` at t = 0: full alpha over black.
+fn has_black_backdrop(b: &ui_layout::UiBuild) -> Option<String> {
+    for el in &b.elements {
+        if !el.name.ends_with(".prm") { continue }
+        if let Some(k) = el.keyframes.iter().find(|k| k.time == Some(0)) {
+            if k.fade == 0xff00_0000 { return Some(el.name.clone()) }
+        }
+    }
+    None
+}
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+
+    println!("== CONTROL: GP_TITLE's 16 composable bundles (port reports 12 with, 4 without)");
+    let ar = PakArchive::open(root.join("dat/GP_TITLE.pak")).expect("GP_TITLE.pak");
+    let (mut y, mut n) = (0, 0);
+    for e in 0..16usize {
+        let Ok(by) = ar.read(&ar.entries()[e]) else { continue };
+        let Some(b) = ui_layout::parse_build(&by) else { continue };
+        match has_black_backdrop(&b) {
+            Some(nm) => { y += 1; println!("   entry {e:>2}  YES  {nm}") }
+            None => { n += 1; println!("   entry {e:>2}  no") }
+        }
+    }
+    println!("   -> {y} with, {n} without\n");
+
+    println!("== DISC-WIDE, over every screen build");
+    let mut paks: Vec<PathBuf> = std::fs::read_dir(root.join("dat")).expect("dat/")
+        .filter_map(|e| e.ok().map(|e| e.path()))
+        .filter(|p| p.extension().is_some_and(|x| x == "pak")).collect();
+    paks.sort();
+    let (mut tot, mut with) = (0usize, 0usize);
+    for pak in &paks {
+        let Ok(ar) = PakArchive::open(pak) else { continue };
+        let name = pak.file_name().unwrap().to_string_lossy().to_string();
+        let (mut t, mut w) = (0usize, 0usize);
+        for e in ar.entries() {
+            let Ok(by) = ar.read(e) else { continue };
+            if !ui_layout::is_build(&by) { continue }
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            t += 1;
+            if has_black_backdrop(&b).is_some() { w += 1 }
+        }
+        if t > 0 {
+            println!("{name:30} {w:4} / {t:<4} declare a black backdrop");
+            std::io::stdout().flush().ok();
+        }
+        tot += t; with += w;
+    }
+    println!("\n{with} of {tot} screen builds disc-wide declare an opaque-black backdrop \
+              ({:.1} %)", 100.0 * with as f64 / tot as f64);
+    println!("--- END ---");
+}

crates/sylpheed-formats/examples/design_size_fallback.rs

@@ -0,0 +1,63 @@
+//! How often is a screen's design size READ, and how often is it FABRICATED?
+//!
+//! `ui_layout.rs` scans the `.rat` records for a `(w,h)` at `+0x18`/`+0x1c` and,
+//! finding none, falls back to `(DESIGN_W, DESIGN_H)` = 1280x720. Its own comment
+//! says "every screen seen is 1280x720, **which is also the fallback**" -- which
+//! is precisely the problem: the fabricated value equals the expected one, so no
+//! output of the parser can distinguish a read design size from an invented one.
+//! The port sizes its screens off this number.
+//!
+//! This replicates the scan through the public RATC API and counts.
+//!
+//!     cargo run -p sylpheed-formats --example design_size_fallback
+use sylpheed_formats::{pak::PakArchive, ratc, ui_layout};
+use std::io::Write;
+use std::path::PathBuf;
+
+fn be32(b: &[u8], o: usize) -> u32 {
+    if o + 4 > b.len() { return 0 }
+    u32::from_be_bytes([b[o], b[o + 1], b[o + 2], b[o + 3]])
+}
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let mut paks: Vec<PathBuf> = std::fs::read_dir(root.join("dat")).expect("dat/")
+        .filter_map(|e| e.ok().map(|e| e.path()))
+        .filter(|p| p.extension().is_some_and(|x| x == "pak")).collect();
+    paks.sort();
+    let (mut read, mut fell_back, mut nonstd) = (0usize, 0usize, 0usize);
+    for pak in &paks {
+        let Ok(ar) = PakArchive::open(pak) else { continue };
+        let name = pak.file_name().unwrap().to_string_lossy().to_string();
+        let (mut r, mut f) = (0usize, 0usize);
+        for e in ar.entries() {
+            let Ok(by) = ar.read(e) else { continue };
+            if !ui_layout::is_build(&by) { continue }
+            let Some(kids) = ratc::parse(&by) else { continue };
+            // the same predicate ui_layout uses, over the same records
+            // ⚠️ A first version took EVERY RATC child and failed its control:
+            // it reported all 965 builds stating a non-1280x720 size, where
+            // `screen list` prints 1280x720 for every one. `records` in
+            // ui_layout is the `.rat` children only; a T8aD sprite header read
+            // at +0x18 is garbage that passes the range test.
+            let found = kids.iter().filter(|k| k.kind == "RATC" || k.name.ends_with(".rat")).find_map(|k| {
+                let rec = &by[k.offset..(k.offset + k.size).min(by.len())];
+                let (w, h) = (be32(rec, 0x18), be32(rec, 0x1c));
+                (w > 0 && h > 0 && w <= 8192 && h <= 8192).then_some((w, h))
+            });
+            match found {
+                Some((w, h)) => { r += 1; if (w, h) != (1280, 720) { nonstd += 1;
+                    println!("  {name} : a build states a NON-standard design size {w}x{h}"); } }
+                None => f += 1,
+            }
+        }
+        if r + f > 0 {
+            println!("{name:30} {r:5} read   {f:5} FABRICATED");
+            std::io::stdout().flush().ok();
+        }
+        read += r; fell_back += f;
+    }
+    println!("\n{read} builds state a design size, {fell_back} get the 1280x720 FALLBACK");
+    println!("{nonstd} builds state something other than 1280x720");
+    println!("--- END ---");
+}

crates/sylpheed-formats/examples/find_stream_by_size.rs

@@ -0,0 +1,123 @@
+//! Which cue owns an XMA stream of a given payload size?
+//!
+//! A boot with `--xma_param_probe` logs each decoded stream's `byte_size`. Three
+//! of the five on the take-2 `ADV` boot are that movie's own streams; two —
+//! 1 150 976 and 1 269 760 B — belong to something unidentified. The probe gives
+//! a size and nothing else, so the disc has to be asked which cue has a stream
+//! that long.
+//!
+//! Searches every inter-descriptor span of the continuous voice stream, and
+//! every `sound.pak` entry, for a stream whose payload matches.
+//!
+//!     cargo run -p sylpheed-formats --example find_stream_by_size -- <disc> <bytes>…
+use sylpheed_formats::media::{DirectorySource, DiscSource};
+use sylpheed_formats::{slb, PakArchive};
+
+const DESC_MARK: u32 = 0x11;
+const DESC_REPEAT: usize = 0x800;
+const ID_MAX: u32 = 0x1_0000;
+
+fn all_descriptors(buf: &[u8]) -> Vec<(usize, u32)> {
+    let be = |o: usize| u32::from_be_bytes([buf[o], buf[o + 1], buf[o + 2], buf[o + 3]]);
+    let mut out = Vec::new();
+    if buf.len() < DESC_REPEAT + 8 {
+        return out;
+    }
+    let end = buf.len() - (DESC_REPEAT + 4);
+    let mut o = 0;
+    while o <= end {
+        let id = be(o);
+        if id >= 1 && id < ID_MAX && be(o + 4) == DESC_MARK && be(o + DESC_REPEAT) == id {
+            out.push((o, id));
+        }
+        o += 4;
+    }
+    out
+}
+
+fn main() {
+    let mut args = std::env::args().skip(1);
+    let disc = args.next().expect("usage: find_stream_by_size <disc> <bytes>…");
+    let wanted: Vec<usize> = args.filter_map(|a| a.parse().ok()).collect();
+    assert!(!wanted.is_empty(), "give at least one payload size");
+    // A `to_xma_riffs` chunk is the payload plus a 60-byte RIFF wrapper.
+    let want_riff: Vec<usize> = wanted.iter().map(|w| w + 60).collect();
+    println!("looking for payloads {wanted:?} (riff sizes {want_riff:?})\n");
+    let src = DirectorySource::new(std::path::PathBuf::from(&disc));
+
+    // --- 1. the continuous movie-voice stream, span by span
+    let tpak = src.open_pak("dat/tables.pak").expect("tables.pak");
+    let marker = "eng\\Movie\\VOICE_ADV.slb";
+    let registry = tpak
+        .entries()
+        .iter()
+        .find_map(|e| {
+            tpak.read(e)
+                .ok()
+                .filter(|b| b.windows(marker.len()).any(|w| w == marker.as_bytes()))
+        })
+        .expect("registry");
+    let ids = sylpheed_formats::movie_voice::registry_voice_ids(&registry);
+    let name_of: std::collections::HashMap<u32, String> =
+        ids.iter().map(|(n, &i)| (i, n.clone())).collect();
+    let win_start: u64 = 421_739_888 & !3;
+    let buf = src
+        .read_segment_range("dat/sound", win_start, 116_300_000)
+        .expect("window");
+    let descs = all_descriptors(&buf);
+    println!("voice stream: {} descriptors", descs.len());
+    let mut hits = 0;
+    for w in descs.windows(2) {
+        let (a, b) = (w[0].0, w[1].0);
+        if b <= a || b - a < 4096 {
+            continue;
+        }
+        for (i, r) in slb::to_xma_riffs(&buf[a..b]).iter().enumerate() {
+            if want_riff.contains(&r.len()) {
+                let name = name_of
+                    .get(&w[1].1)
+                    .cloned()
+                    .unwrap_or_else(|| format!("id{}", w[1].1));
+                println!(
+                    "  ✅ cue {name} (id {}) stream {i}: payload {} B",
+                    w[1].1,
+                    r.len() - 60
+                );
+                hits += 1;
+            }
+        }
+    }
+    println!("  {hits} hit(s) in the voice stream\n");
+
+    // --- 2. every sound.pak entry
+    let stoc = src.read_file("dat/sound.pak").expect("sound.pak toc");
+    let entries = PakArchive::parse_toc(&stoc).expect("toc");
+    println!("sound.pak: {} entries", entries.len());
+    let mut phits = 0;
+    let mut scanned = 0usize;
+    for e in &entries {
+        // Only entries big enough to hold the target.
+        let need = wanted.iter().copied().min().unwrap_or(0) as u32;
+        if e.comp_size < need {
+            continue;
+        }
+        let Ok(bytes) = src.read_segment_range("dat/sound", e.offset as u64, e.comp_size as usize)
+        else {
+            continue;
+        };
+        scanned += 1;
+        for (i, r) in slb::to_xma_riffs(&bytes).iter().enumerate() {
+            if want_riff.contains(&r.len()) {
+                println!(
+                    "  ✅ sound.pak entry hash {:08x} offset {} size {} — stream {i}: payload {} B",
+                    e.name_hash,
+                    e.offset,
+                    e.comp_size,
+                    r.len() - 60
+                );
+                phits += 1;
+            }
+        }
+    }
+    println!("  scanned {scanned} entries large enough; {phits} hit(s)");
+}

crates/sylpheed-formats/examples/focus_alpha_census.rs

@@ -0,0 +1,65 @@
+//! Which focus records have a VARYING alpha — disc-wide, not export-wide?
+//!
+//! `rest()` returns an element's last hold keyframe. For a constant-alpha
+//! element that is harmless. For one that pulses it returns the PEAK, which is
+//! the `ui-settle-time.md` pathology: the plate's `ptbtn00f` ramps 0→80→0 and
+//! `rest()` reports 80, its maximum.
+//!
+//! The port censused this over its own export (34 records, 2 varying) and
+//! concluded there is nothing to fix. That conclusion is only as wide as the
+//! export. This asks the same question of the whole disc.
+use sylpheed_formats::{pak, ratc, ui_layout};
+
+fn main() {
+    let root = std::env::var("SYLPHEED_DISC").unwrap_or_else(|_| "/disc".into());
+    let mut paks: Vec<_> = std::fs::read_dir(format!("{root}/dat")).expect("dat/")
+        .flatten().map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("pak")).collect();
+    paks.sort();
+    let (mut n_rec, mut n_elem, mut varying) = (0usize, 0usize, 0usize);
+    let (mut at_peak, mut mid_ramp) = (0usize, 0usize);
+    let mut by_pak: std::collections::BTreeMap<String, usize> = Default::default();
+    let mut hits: Vec<String> = Vec::new();
+    for p in &paks {
+        let pn = p.file_name().unwrap().to_string_lossy().to_string();
+        let Ok(ar) = pak::PakArchive::open(p) else { continue };
+        for (ei, e) in ar.entries().iter().enumerate() {
+            let Ok(by) = ar.read(e) else { continue };
+            if !ratc::is_ratc(&by) { continue }
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            for (rn, &(o, s)) in &b.records {
+                // A focus record is one whose name is another record's plus `f`.
+                let Some(stem) = rn.strip_suffix("f.rat") else { continue };
+                if !b.records.contains_key(&format!("{stem}.rat")) { continue }
+                if o + s > by.len() { continue }
+                let Some(lb) = ui_layout::parse_build(&by[o..o + s]) else { continue };
+                n_rec += 1;
+                for el in &lb.elements {
+                    if el.keyframes.is_empty() { continue }
+                    n_elem += 1;
+                    let a: Vec<u32> = el.keyframes.iter().map(|k| k.fade >> 24).collect();
+                    let (lo, hi) = (*a.iter().min().unwrap(), *a.iter().max().unwrap());
+                    if lo == hi { continue }
+                    varying += 1;
+                    let rest = el.rest().map(|k| k.fade >> 24).unwrap_or(0);
+                    if rest == hi { at_peak += 1 } else { mid_ramp += 1 }
+                    *by_pak.entry(pn.clone()).or_default() += 1;
+                    hits.push(format!(
+                        "{pn} [{ei}] {rn}::{}  alpha {lo}..{hi}  rest()={rest}{}",
+                        el.name, if rest == hi { "  🔴 == PEAK" } else { "" }));
+                }
+            }
+        }
+    }
+    println!("focus records disc-wide          : {n_rec}");
+    println!("  their timed elements           : {n_elem}");
+    println!("  with a VARYING alpha           : {varying}");
+    println!("    of which rest() == the PEAK  : {at_peak}   <- burns bright forever");
+    println!("    of which rest() is MID-RAMP  : {mid_ramp}   <- neither extreme; looks plausible");
+    println!("\nby pak:");
+    for (k, v) in &by_pak { println!("  {k:<34} {v}") }
+    println!("\nevery varying one:");
+    hits.sort(); hits.dedup();
+    for h in &hits { println!("  {h}") }
+    println!("\n({} distinct)", hits.len());
+}

crates/sylpheed-formats/examples/forced_backdrop_ink_thresholds.rs

@@ -0,0 +1,90 @@
+//! Reconcile two ink counts for one screen that were never counting the same pixels.
+//!
+//! The port agent double-witnessed the pixel-cost claim in Godot — a renderer
+//! sharing no code with `compose` — and got `GP_TITLE` entry 12 at **59 530 px**
+//! ink above threshold 0 and **48 368** above 1. This crate reported **49 771**.
+//! Neither is wrong; the question is which convention each was using, and on a
+//! mostly-dark frame the answer moves thousands of pixels.
+//!
+//! So: count the same composite every way, and print the family. Whichever row
+//! the port's numbers land in is the convention, and then the two renderers can be
+//! compared on purpose rather than by coincidence.
+//!
+//!     cargo run -p sylpheed-formats --example forced_backdrop_ink_thresholds
+
+use std::path::PathBuf;
+
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use ui_layout::ComposeOptions;
+
+fn order_without_rule(build: &ui_layout::UiBuild, bundle: &[u8]) -> Vec<usize> {
+    let mut idx: Vec<usize> = (0..build.elements.len()).collect();
+    idx.sort_by_key(|&i| {
+        let el = &build.elements[i];
+        (
+            ui_layout::sprite_layer_key(build, bundle, el)
+                .or_else(|| ui_layout::implied_layer_key(&el.name))
+                .unwrap_or(u32::MAX),
+            i,
+        )
+    });
+    idx
+}
+
+fn counts(rgba: &[u8], t: u8) -> (usize, usize) {
+    let rgb = rgba
+        .chunks_exact(4)
+        .filter(|p| p[0] > t || p[1] > t || p[2] > t)
+        .count();
+    let alpha = rgba.chunks_exact(4).filter(|p| p[3] > t).count();
+    (rgb, alpha)
+}
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let ar = PakArchive::open(root.join("dat/GP_TITLE.pak")).expect("GP_TITLE.pak");
+
+    for entry in [12usize, 15] {
+        let by = ar.read(&ar.entries()[entry]).expect("entry");
+        let b = ui_layout::parse_build(&by).expect("parse");
+        for (label, opts) in [
+            (
+                "primitives on (what the cost run used)",
+                ComposeOptions {
+                    include_primitives: true,
+                    backdrop: [0, 0, 0, 255],
+                    ..Default::default()
+                },
+            ),
+            (
+                "primitives+focus+animated",
+                ComposeOptions {
+                    include_primitives: true,
+                    include_focus: true,
+                    include_animated: true,
+                    backdrop: [0, 0, 0, 255],
+                    ..Default::default()
+                },
+            ),
+        ] {
+            let with = ui_layout::derived_paint_order(&b, &by);
+            let without = order_without_rule(&b, &by);
+            let a = ui_layout::compose_with_order(&b, &by, opts.clone(), None, Some(&with));
+            let c = ui_layout::compose_with_order(&b, &by, opts, None, Some(&without));
+            println!("\n== GP_TITLE entry {entry} — {label}  ({}x{})", a.width, a.height);
+            println!("   threshold |  RGB>t with rule |  A>t with rule | RGB>t WITHOUT | A>t WITHOUT");
+            for t in [0u8, 1, 2, 4, 8, 16] {
+                let (r1, a1) = counts(&a.rgba, t);
+                let (r0, a0) = counts(&c.rgba, t);
+                println!("     >{t:<8} | {r1:>16} | {a1:>14} | {r0:>13} | {a0:>11}");
+            }
+            let changed = a
+                .rgba
+                .chunks_exact(4)
+                .zip(c.rgba.chunks_exact(4))
+                .filter(|(x, y)| x != y)
+                .count();
+            println!("   exact-RGBA changed pixels between the two orders: {changed}");
+        }
+    }
+}

crates/sylpheed-formats/examples/forced_backdrop_key_source.rs

@@ -0,0 +1,71 @@
+//! Of the forced instances the rule merely CONFIRMS, how many have a key READ
+//! FROM THE FILE, and how many an IMPLIED key that is itself a measurement?
+//!
+//! `forced_backdrop_necessity.rs` asked only whether an element had *a* key,
+//! collapsing `sprite_layer_key` (a `u16` read out of the `T8aD` header — decoded)
+//! with `implied_layer_key` (this crate's per-name table of positions **measured
+//! in the running game**). For counting whether the rule moves anything that is
+//! the right question. For describing what a confirmation is *made of*, it is not:
+//! "the file already settles it" and "another measurement already settles it" are
+//! different claims, and a reader who sees "own key" will take the first.
+//!
+//! Raised by the port agent 2026-08-30.
+//!
+//!     cargo run -p sylpheed-formats --example forced_backdrop_key_source
+
+use std::path::PathBuf;
+
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let mut paks: Vec<PathBuf> = std::fs::read_dir(root.join("dat"))
+        .expect("dat/")
+        .filter_map(|e| e.ok().map(|e| e.path()))
+        .filter(|p| p.extension().is_some_and(|x| x == "pak"))
+        .collect();
+    paks.sort();
+
+    let (mut read, mut implied, mut none) = (0usize, 0usize, 0usize);
+    println!("# archive  entry  element  key_source  key");
+    for pak in &paks {
+        let Ok(ar) = PakArchive::open(pak) else { continue };
+        let name = pak.file_name().unwrap().to_string_lossy().to_string();
+        for (i, e) in ar.entries().iter().enumerate() {
+            let Ok(by) = ar.read(e) else { continue };
+            let Some(b) = ui_layout::parse_build(&by) else {
+                continue;
+            };
+            for el in &b.elements {
+                if !ui_layout::forced_backdrop(&b, el) {
+                    continue;
+                }
+                let (src, key) = match ui_layout::sprite_layer_key(&b, &by, el) {
+                    Some(k) => {
+                        read += 1;
+                        ("read_T8aD", Some(k))
+                    }
+                    None => match ui_layout::implied_layer_key(&el.name) {
+                        Some(k) => {
+                            implied += 1;
+                            ("implied_MEASURED", Some(k))
+                        }
+                        None => {
+                            none += 1;
+                            ("none", None)
+                        }
+                    },
+                };
+                println!(
+                    "  {name}  {i}  {}  {src}  {}",
+                    el.name,
+                    key.map(|k| format!("0x{k:08X}")).unwrap_or("-".into())
+                );
+            }
+        }
+    }
+    println!("\n# forced instances by key source:");
+    println!("#   read from the T8aD header (decoded):        {read}");
+    println!("#   implied — this crate's MEASURED name table: {implied}");
+    println!("#   none — only forced_backdrop can speak:      {none}");
+}

crates/sylpheed-formats/examples/forced_backdrop_necessity.rs

@@ -0,0 +1,114 @@
+//! Which screens does `forced_backdrop` DECIDE, and which does it merely agree with?
+//!
+//! Every check this corpus has run on the rule measured its **stability** — that
+//! no verdict moved when something else changed. That is a different property
+//! from **necessity**: an element whose position is already fixed by a read or an
+//! implied key is confirmed by the rule, not decided by it.
+//!
+//! So: compute `derived_paint_order` with the rule, and again with the
+//! `forced_backdrop` fallback removed, and report every entry whose order moves.
+//! Where nothing moves, the rule is decorative on that screen; where it moves,
+//! the rule is the only thing holding the order up.
+//!
+//! Raised by the port agent 2026-08-30. Reach note in
+//! `docs/re/structures/ui-forced-backdrop.md`.
+//!
+//!     cargo run -p sylpheed-formats --example forced_backdrop_necessity -- [pak...]
+//!
+//! 🔴 With no argument this used to default to `GP_TITLE` alone, so a bare run
+//! reported **6 instances, not 80** — a thirteenth of the census, printed in the
+//! same format and reading like the whole thing. The port agent hit it and nearly
+//! filed the discrepancy back at me. It now walks every `dat/*.pak` by default and
+//! says on stderr how many archives it opened, because "I ran your instrument" has
+//! to mean the same thing to both of us.
+
+use std::path::PathBuf;
+
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+
+fn order_without_rule(build: &ui_layout::UiBuild, bundle: &[u8]) -> Vec<usize> {
+    let mut idx: Vec<usize> = (0..build.elements.len()).collect();
+    idx.sort_by_key(|&i| {
+        let el = &build.elements[i];
+        (
+            ui_layout::sprite_layer_key(build, bundle, el)
+                .or_else(|| ui_layout::implied_layer_key(&el.name))
+                .unwrap_or(u32::MAX),
+            i,
+        )
+    });
+    idx
+}
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let (mut total_decides, mut total_agrees) = (0usize, 0usize);
+    let mut paks: Vec<PathBuf> = std::env::args().skip(1).map(PathBuf::from).collect();
+    if paks.is_empty() {
+        let mut all: Vec<PathBuf> = std::fs::read_dir(root.join("dat"))
+            .expect("dat/")
+            .filter_map(|e| e.ok().map(|e| e.path()))
+            .filter(|p| p.extension().is_some_and(|x| x == "pak"))
+            .collect();
+        all.sort();
+        paks = all;
+    }
+    eprintln!("# scanning {} archive(s)", paks.len());
+    for path in &paks {
+    let ar = PakArchive::open(path).expect("pak");
+    println!("# {}", path.display());
+    println!("# entry  forced  decides  elements   note");
+
+    let mut decides = Vec::new();
+    let mut agrees = Vec::new();
+    #[allow(unused)]
+    let _ = (&decides, &agrees);
+    for (i, e) in ar.entries().iter().enumerate() {
+        let Ok(by) = ar.read(e) else { continue };
+        let Some(b) = ui_layout::parse_build(&by) else {
+            continue;
+        };
+        let with = ui_layout::derived_paint_order(&b, &by);
+        let without = order_without_rule(&b, &by);
+
+        // Which elements does the rule fire on, and of those, which have no key
+        // of their own to fall back on?
+        let mut forced = Vec::new();
+        let mut keyless = Vec::new();
+        for el in &b.elements {
+            if !ui_layout::forced_backdrop(&b, el) {
+                continue;
+            }
+            forced.push(el.name.clone());
+            let own = ui_layout::sprite_layer_key(&b, &by, el)
+                .or_else(|| ui_layout::implied_layer_key(&el.name));
+            if own.is_none() {
+                keyless.push(el.name.clone());
+            }
+        }
+        if forced.is_empty() {
+            continue;
+        }
+        let moved = with != without;
+        if moved {
+            decides.push(i);
+        } else {
+            agrees.push(i);
+        }
+        println!(
+            "  {i:>5}  {:>6}  {:>7}  {:>8}   forced=[{}] keyless=[{}]",
+            forced.len(),
+            if moved { "YES" } else { "no" },
+            b.elements.len(),
+            forced.join(","),
+            keyless.join(","),
+        );
+    }
+    println!("# rule DECIDES the order on entries {decides:?}");
+    println!("# rule merely AGREES on entries {agrees:?}\n");
+    total_decides += decides.len();
+    total_agrees += agrees.len();
+    }
+    println!("# TOTAL over {} archive(s): {total_decides} deciding entries, \
+{total_agrees} agreeing", paks.len());
+}

crates/sylpheed-formats/examples/forced_backdrop_pixel_cost.rs

@@ -0,0 +1,119 @@
+//! What does `forced_backdrop` cost IN PIXELS on the screens it decides?
+//!
+//! `forced_backdrop_necessity.rs` answers "does the derived ORDER move", which is
+//! a property of the sort. The port agent then pointed out — correctly — that its
+//! re-run of that probe was **my code executed twice**, not a second witness, so
+//! the disc-wide 62 has one measurement behind it and only `GP_TITLE` has two.
+//!
+//! This does not fix that (it is still this crate), but it moves the question to a
+//! **different layer**: render each deciding build twice, once in the order
+//! `compose` derives and once with the `forced_backdrop` fallback removed, and
+//! count the pixels that differ. "The order moved" and "the picture moved" are not
+//! the same claim, and the second is the one anybody cares about — the tie-break
+//! work already found overlapping reorders that cost exactly zero pixels.
+//!
+//! Each entry carries its own CONTROL: the pixel count of the composite itself.
+//! If a build renders empty, its zero means the instrument saw nothing, not that
+//! the rule is free.
+//!
+//!     cargo run -p sylpheed-formats --example forced_backdrop_pixel_cost -- [pak...]
+//!
+//! With no argument it walks **every `dat/*.pak`** — the necessity probe defaulted
+//! to `GP_TITLE`, which made a bare run report a thirteenth of the census and read
+//! like the whole thing.
+
+use std::path::PathBuf;
+
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use ui_layout::ComposeOptions;
+
+fn order_without_rule(build: &ui_layout::UiBuild, bundle: &[u8]) -> Vec<usize> {
+    let mut idx: Vec<usize> = (0..build.elements.len()).collect();
+    idx.sort_by_key(|&i| {
+        let el = &build.elements[i];
+        (
+            ui_layout::sprite_layer_key(build, bundle, el)
+                .or_else(|| ui_layout::implied_layer_key(&el.name))
+                .unwrap_or(u32::MAX),
+            i,
+        )
+    });
+    idx
+}
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let mut paks: Vec<PathBuf> = std::env::args().skip(1).map(PathBuf::from).collect();
+    if paks.is_empty() {
+        let mut all: Vec<PathBuf> = std::fs::read_dir(root.join("dat"))
+            .expect("dat/")
+            .filter_map(|e| e.ok().map(|e| e.path()))
+            .filter(|p| p.extension().is_some_and(|x| x == "pak"))
+            .collect();
+        all.sort();
+        paks = all;
+    }
+    eprintln!("# scanning {} archive(s)", paks.len());
+
+    let opts = ComposeOptions {
+        include_primitives: true,
+        backdrop: [0, 0, 0, 255],
+        ..Default::default()
+    };
+
+    println!("# archive  entry  element  changed_px  total_px  ink_px(control)  pct");
+    let (mut decided, mut zero_cost, mut blind) = (0usize, 0usize, 0usize);
+    for pak in &paks {
+        let Ok(ar) = PakArchive::open(pak) else { continue };
+        let name = pak.file_name().unwrap().to_string_lossy().to_string();
+        for (i, e) in ar.entries().iter().enumerate() {
+            let Ok(by) = ar.read(e) else { continue };
+            let Some(b) = ui_layout::parse_build(&by) else {
+                continue;
+            };
+            let with = ui_layout::derived_paint_order(&b, &by);
+            let without = order_without_rule(&b, &by);
+            if with == without {
+                continue;
+            }
+            let forced: Vec<&str> = b
+                .elements
+                .iter()
+                .filter(|el| ui_layout::forced_backdrop(&b, el))
+                .map(|el| el.name.as_str())
+                .collect();
+
+            let a = ui_layout::compose_with_order(&b, &by, opts.clone(), None, Some(&with));
+            let c = ui_layout::compose_with_order(&b, &by, opts.clone(), None, Some(&without));
+            let n = a
+                .rgba
+                .chunks_exact(4)
+                .zip(c.rgba.chunks_exact(4))
+                .filter(|(x, y)| x != y)
+                .count();
+            // Control: does this build put any ink down at all, against the bare
+            // backdrop? A build that renders to nothing cannot show a reorder.
+            let ink = a
+                .rgba
+                .chunks_exact(4)
+                .filter(|p| p[..3] != [0, 0, 0])
+                .count();
+            let total = a.rgba.len() / 4;
+
+            decided += 1;
+            if ink == 0 {
+                blind += 1;
+            } else if n == 0 {
+                zero_cost += 1;
+            }
+            println!(
+                "  {name}  {i}  {}  {n}  {total}  {ink}  {:.2}%",
+                forced.join(","),
+                100.0 * n as f64 / total as f64
+            );
+        }
+    }
+    println!("\n# builds whose ORDER the rule decides: {decided}");
+    println!("# of those, costing ZERO pixels:        {zero_cost}");
+    println!("# of those, BLIND (build renders no ink, control fails): {blind}");
+}

crates/sylpheed-formats/examples/inrange_fallback_count.rs

@@ -0,0 +1,86 @@
+//! Do `ui_layout`'s two IN-RANGE fallbacks ever fire? Counted, disc-wide.
+//!
+//! An in-range fallback supplies a value that is legitimate, so no output can
+//! distinguish it from the real thing and inspection cannot settle it. The only
+//! question that has an answer is *how often does it fire*.
+//!
+//!   ui_layout.rs:1681  kf.time.unwrap_or(0)  -- 0 is a real keyframe time
+//!                      (pose 0's time IS 0), so a fabricated one is invisible.
+//!   ui_layout.rs:1010  pose_at(t).map(|k| k.fade >> 24).unwrap_or(0) > 0
+//!                      -- alpha 0 is legitimate, and it makes "no pose here"
+//!                      read as "fully transparent", biasing an occlusion test
+//!                      toward NOT occluded.
+//!
+//! (ui_layout.rs:973's `unwrap_or(0)` is NOT counted: it is guarded two lines
+//! later by `if tmax == 0 { return false; }`, so 0 is handled, not assumed.)
+//!
+//!     cargo run -p sylpheed-formats --example inrange_fallback_count
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use std::io::Write;
+use std::path::PathBuf;
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let mut paks: Vec<PathBuf> = std::fs::read_dir(root.join("dat")).expect("dat/")
+        .filter_map(|e| e.ok().map(|e| e.path()))
+        .filter(|p| p.extension().is_some_and(|x| x == "pak")).collect();
+    paks.sort();
+    let (mut kf, mut untimed, mut builds) = (0u64, 0u64, 0u64);
+    let (mut queries, mut none_at) = (0u64, 0u64);
+    for pak in &paks {
+        let Ok(ar) = PakArchive::open(pak) else { continue };
+        for e in ar.entries() {
+            let Ok(by) = ar.read(e) else { continue };
+            if !ui_layout::is_build(&by) { continue }
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            builds += 1;
+            // (a) :1681 -- how many poses carry no time?
+            for el in &b.elements {
+                for k in &el.keyframes {
+                    kf += 1;
+                    if k.time.is_none() { untimed += 1 }
+                }
+            }
+            // (b) :1010 -- ask every element for a pose at every time that any
+            // element declares, which is the set the occlusion test draws from.
+            let mut times: Vec<u32> = b.elements.iter()
+                .flat_map(|e| e.keyframes.iter().filter_map(|k| k.time)).collect();
+            times.sort_unstable(); times.dedup();
+            for el in &b.elements {
+                for &t in &times {
+                    queries += 1;
+                    if el.pose_at(t).is_none() { none_at += 1 }
+                }
+            }
+        }
+        print!("."); std::io::stdout().flush().ok();
+    }
+    println!();
+    println!("{builds} builds, {kf} keyframes");
+    println!(":1681  untimed poses (the fallback would fabricate t=0): {untimed}");
+    println!(":1010  pose_at queries {queries}, of which None (fallback reads a=0): {none_at}");
+    // NEGATIVE CONTROL. Both counters above report 0, and a zero is the result
+    // this corpus has learned to distrust most -- it reads clean rather than
+    // suspicious. So prove the detector CAN see a hit: ask every element for a
+    // pose at a time no build declares. If pose_at is total, `none_out` is 0 too
+    // and the 0 above means nothing.
+    let mut out_queries = 0u64;
+    let mut none_out = 0u64;
+    for pak in &paks {
+        let Ok(ar) = PakArchive::open(pak) else { continue };
+        for e in ar.entries() {
+            let Ok(by) = ar.read(e) else { continue };
+            if !ui_layout::is_build(&by) { continue }
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            for el in &b.elements {
+                for &t in &[u32::MAX, 1_000_000u32] {
+                    out_queries += 1;
+                    if el.pose_at(t).is_none() { none_out += 1 }
+                }
+            }
+        }
+    }
+    println!("CONTROL  pose_at at an undeclared time: {out_queries} queries, {none_out} None");
+    println!("         (if this is 0 the detector is blind and the 0 above is meaningless)");
+    println!("--- END ---");
+}

crates/sylpheed-formats/examples/kf_flip_test.rs

@@ -0,0 +1,72 @@
+//! Do `+4` / `+8` = 180 mean MIRROR?
+//!
+//! The disc-wide census shows `+4` and `+8` are dominated by 180 and ±90, while
+//! `+12` (the decoded screen-plane rotation) takes 157 distinct values including
+//! odd ones. That shape says flips rather than free rotation.
+//!
+//! Structural test, no renderer involved: if 180 means "mirror", then the same
+//! sprite should appear both with the field 0 and with it 180 **within one
+//! build** -- a mirrored pair. Free-rotation semantics predicts no such pairing.
+//!
+//! CONTROL: the same search run on `+12`, which is decoded as a real rotation
+//! and should NOT show a 0/180 pairing pattern of the same strength.
+use sylpheed_formats::{pak, ui_layout};
+use std::collections::{BTreeMap, BTreeSet};
+
+fn main() {
+    let dir = std::env::args().nth(1).expect("<disc>/dat");
+    let mut paks: Vec<_> = std::fs::read_dir(&dir).expect("dir")
+        .filter_map(|e| e.ok().map(|e| e.path()))
+        .filter(|p| p.extension().map(|x| x == "pak").unwrap_or(false)).collect();
+    paks.sort();
+
+    // field -> (pak, entry, sprite) -> set of values seen
+    let mut seen: [BTreeMap<(String, usize, String), BTreeSet<i32>>; 3] =
+        [BTreeMap::new(), BTreeMap::new(), BTreeMap::new()];
+
+    for p in &paks {
+        let Ok(ar) = pak::PakArchive::open(p) else { continue };
+        let pn = p.file_name().unwrap().to_string_lossy().to_string();
+        for (i, e) in ar.entries().to_vec().iter().enumerate() {
+            let Ok(bytes) = ar.read(e) else { continue };
+            let Some(b) = ui_layout::parse_build(&bytes) else { continue };
+            let mut groups: Vec<(String, Vec<ui_layout::Keyframe>)> =
+                b.elements.iter().map(|el| (el.name.clone(), el.keyframes.clone())).collect();
+            for el in &b.elements {
+                if let Some(&(off, size)) = b.records.get(&el.name) {
+                    if let Some(lb) = ui_layout::parse_build(&bytes[off..off + size]) {
+                        for le in &lb.elements {
+                            groups.push((le.name.clone(), le.keyframes.clone()));
+                        }
+                    }
+                }
+            }
+            for (nm, ks) in groups {
+                for k in &ks {
+                    let key = (pn.clone(), i, nm.clone());
+                    seen[0].entry(key.clone()).or_default().insert(k.unknown_4);
+                    seen[1].entry(key.clone()).or_default().insert(k.unknown_8);
+                    seen[2].entry(key).or_default().insert(k.rotation_deg);
+                }
+            }
+        }
+    }
+
+    for (idx, label) in [(0, "+4"), (1, "+8"), (2, "+12 (rotation, CONTROL)")] {
+        let m = &seen[idx];
+        let mut pair_0_180 = 0usize;   // a sprite seen at BOTH 0 and 180 in one build
+        let mut only_180 = 0usize;
+        let mut multi = 0usize;        // more than two distinct values
+        for v in m.values() {
+            if v.len() > 2 { multi += 1; }
+            let has0 = v.contains(&0);
+            let has180 = v.contains(&180) || v.contains(&-180);
+            if has0 && has180 { pair_0_180 += 1; }
+            else if has180 && !has0 { only_180 += 1; }
+        }
+        println!("{label}: {} sprite-instances", m.len());
+        println!("    both 0 and ±180 in one build : {pair_0_180}");
+        println!("    ±180 without any 0           : {only_180}");
+        println!("    more than 2 distinct values  : {multi}");
+    }
+}

crates/sylpheed-formats/examples/kf_timeline.rs

@@ -0,0 +1,19 @@
+use sylpheed_formats::{pak, ui_layout};
+fn main(){
+    let mut a=std::env::args().skip(1);
+    let pk=a.next().unwrap(); let bi:usize=a.next().unwrap().parse().unwrap();
+    let ar=pak::PakArchive::open(pk).unwrap();
+    let by=ar.read(&ar.entries()[bi]).unwrap();
+    let b=ui_layout::parse_build(&by).unwrap();
+    for t in a {
+        let i:usize=t.parse().unwrap();
+        let e=&b.elements[i];
+        println!("[{i}] {}  kind=0x{:x} parent={:?} pivot=({},{}) kfs={}",
+                 e.name, e.kind, e.parent, e.pivot_x, e.pivot_y, e.keyframes.len());
+        for k in &e.keyframes {
+            println!("     t={:<5} a={:<4} xy=({},{}) s={}/{} rot={} u4={} u8={} tint={:08x}",
+                k.time.map(|v|v as i64).unwrap_or(-1), k.fade>>24, k.x,k.y,
+                k.scale_x,k.scale_y,k.rotation_deg,k.unknown_4,k.unknown_8,k.tint);
+        }
+    }
+}

crates/sylpheed-formats/examples/kf_unknown_census.rs

@@ -0,0 +1,83 @@
+//! What are the keyframe block's `+4` and `+8`?
+//!
+//! `+12` is decoded as a screen-plane rotation in degrees. `+4` and `+8` sit
+//! immediately before it and are carried but unexplained; one standing 🟡
+//! reading is that the three together are rotations about three axes, "not tied
+//! to an observed rotation". This censuses them across every UI pak on the disc
+//! so the reading can be argued with rather than assumed.
+use sylpheed_formats::{pak, ui_layout};
+use std::collections::BTreeMap;
+
+fn main() {
+    let dir = std::env::args().nth(1).expect("usage: <disc>/dat");
+    let mut paks: Vec<_> = std::fs::read_dir(&dir)
+        .expect("dir")
+        .filter_map(|e| e.ok().map(|e| e.path()))
+        .filter(|p| p.extension().map(|x| x == "pak").unwrap_or(false))
+        .collect();
+    paks.sort();
+
+    let mut h4: BTreeMap<i32, usize> = BTreeMap::new();
+    let mut h8: BTreeMap<i32, usize> = BTreeMap::new();
+    let mut h12: BTreeMap<i32, usize> = BTreeMap::new();
+    let mut both_nz: Vec<String> = Vec::new();
+    let (mut kfs, mut builds) = (0usize, 0usize);
+
+    for p in &paks {
+        let Ok(ar) = pak::PakArchive::open(p) else { continue };
+        let name = p.file_name().unwrap().to_string_lossy().to_string();
+        for (i, e) in ar.entries().to_vec().iter().enumerate() {
+            let Ok(bytes) = ar.read(e) else { continue };
+            let Some(b) = ui_layout::parse_build(&bytes) else { continue };
+            builds += 1;
+            // parents and leaves alike
+            let mut groups: Vec<(String, Vec<ui_layout::Keyframe>)> = b
+                .elements.iter().map(|el| (el.name.clone(), el.keyframes.clone())).collect();
+            for el in &b.elements {
+                if let Some(&(off, size)) = b.records.get(&el.name) {
+                    if let Some(lb) = ui_layout::parse_build(&bytes[off..off + size]) {
+                        for le in &lb.elements {
+                            groups.push((format!("{}->{}", el.name, le.name), le.keyframes.clone()));
+                        }
+                    }
+                }
+            }
+            for (nm, ks) in groups {
+                for k in &ks {
+                    kfs += 1;
+                    *h4.entry(k.unknown_4).or_default() += 1;
+                    *h8.entry(k.unknown_8).or_default() += 1;
+                    *h12.entry(k.rotation_deg).or_default() += 1;
+                    if k.unknown_4 != 0 || k.unknown_8 != 0 {
+                        both_nz.push(format!("{name} e{i} {nm}  +4={} +8={} +12={}",
+                            k.unknown_4, k.unknown_8, k.rotation_deg));
+                    }
+                }
+            }
+        }
+    }
+    println!("{builds} builds, {kfs} keyframes (parents + leaves)\n");
+    for (nm, h) in [("+4", &h4), ("+8", &h8), ("+12 (rotation)", &h12)] {
+        let nz: usize = h.iter().filter(|(k, _)| **k != 0).map(|(_, v)| *v).sum();
+        println!("{nm}: {} distinct values, {} non-zero keyframes ({:.4}%)",
+                 h.len(), nz, 100.0 * nz as f64 / kfs as f64);
+        let mut top: Vec<_> = h.iter().filter(|(k, _)| **k != 0).collect();
+        top.sort_by_key(|(_, v)| std::cmp::Reverse(**v));
+        for (k, v) in top.iter().take(6) { println!("    {k:>8} x{v}"); }
+    }
+    println!("\nkeyframes with a non-zero +4 or +8: {}", both_nz.len());
+    // Per-pak, so a reader can ask whether a pak they have a CAPTURE of is
+    // among them -- which decides whether the field is testable at all.
+    let mut per: BTreeMap<String, usize> = BTreeMap::new();
+    for l in &both_nz {
+        let pak = l.split_whitespace().next().unwrap_or("?").to_string();
+        *per.entry(pak).or_default() += 1;
+    }
+    println!("  by pak:");
+    for (k, v) in &per { println!("    {k:<28} {v}"); }
+    println!("  paks with NONE: (any UI pak not listed above)");
+    if let Ok(f) = std::env::var("KF_SHOW") {
+        println!("\n  all lines for {f}:");
+        for l in both_nz.iter().filter(|l| l.starts_with(&f)) { println!("    {l}"); }
+    }
+}

crates/sylpheed-formats/examples/leaf_alpha_compose.rs

@@ -0,0 +1,56 @@
+//! How do a parent record's alpha ramp and its nested `.rat` leaf's compose?
+//!
+//! The port emits both but will not draw the leaf without knowing the rule --
+//! rightly, since drawing on a guess trades a visible 1.82 % error for an
+//! invisible wrong one. There is an oracle for this: the GPU draw capture
+//! records **vertex colours**, and on the title's `ptloop` draw they are
+//! `C3FFFFFF` and `B6FFFFFF` -- alpha **195** and **182**, not 255. So the game's
+//! composed alpha is observable, and a candidate rule either predicts those two
+//! numbers or does not.
+//!
+//!     cargo run -p sylpheed-formats --example leaf_alpha_compose -- <GP_TITLE.pak>
+use sylpheed_formats::{pak, ui_layout};
+
+fn alpha_of(kf: &ui_layout::Keyframe) -> u32 {
+    // The keyframe block's +0 is an ARGB fade colour; alpha is its high byte.
+    kf.fade >> 24
+}
+
+fn main() {
+    let path = std::env::args().nth(1).expect("usage: <pak>");
+    let ar = pak::PakArchive::open(&path).expect("open");
+    let e = &ar.entries()[4]; // GP_TITLE entry 4 = the English title
+    let bytes = ar.read(e).expect("read");
+    let build = ui_layout::parse_build(&bytes).expect("build");
+
+    for name in ["ptloop01.rat", "ptloop02.rat"] {
+        println!("\n=== {name} ===");
+        if let Some(el) = build.elements.iter().find(|x| x.name == name) {
+            println!("  PARENT keyframes (t, alpha, scale, rot, x,y):");
+            for k in &el.keyframes {
+                println!("    t={:<5} a={:<4} scale=({},{})  rot={:<5} ({},{})",
+                    k.time.map(|t| t as i64).unwrap_or(-1), alpha_of(k), k.scale_x, k.scale_y, k.rotation_deg, k.x, k.y);
+            }
+        }
+        match build.records.get(name) {
+            Some(&(off, size)) => {
+                let leaf = &bytes[off..off + size];
+                match ui_layout::parse_build(leaf) {
+                    Some(lb) => {
+                        for le in &lb.elements {
+                            println!("  LEAF element {:?}:", le.name);
+                            for k in &le.keyframes {
+                                println!("    t={:<5} a={:<4} scale=({},{})  rot={:<5} ({},{})",
+                                    k.time.map(|t| t as i64).unwrap_or(-1), alpha_of(k), k.scale_x, k.scale_y,
+                                    k.rotation_deg, k.x, k.y);
+                            }
+                        }
+                    }
+                    None => println!("  leaf did not parse"),
+                }
+            }
+            None => println!("  no leaf record"),
+        }
+    }
+    println!("\nOBSERVED in the draw capture: quad A alpha 195 (0xC3), quad B alpha 182 (0xB6)");
+}

crates/sylpheed-formats/examples/leaf_dump.rs

@@ -0,0 +1,42 @@
+//! Dump a record's parent keyframes and its nested `.rat` leaf's, for any entry.
+//!
+//!     cargo run -p sylpheed-formats --example leaf_dump -- <pak> <entry> <name>
+use sylpheed_formats::{pak, ui_layout};
+
+fn a(k: &ui_layout::Keyframe) -> u32 { k.fade >> 24 }
+fn t(k: &ui_layout::Keyframe) -> i64 { k.time.map(|v| v as i64).unwrap_or(-1) }
+
+fn show(tag: &str, els: &[ui_layout::Element]) {
+    for e in els {
+        println!("  {tag} {:?}  pivot=({},{})  kind={:#x}", e.name, e.pivot_x, e.pivot_y, e.kind);
+        for k in &e.keyframes {
+            println!("     t={:<5} a={:<4} scale=({},{})  rot={:<5} pos=({},{})  tint={:#010x}",
+                t(k), a(k), k.scale_x, k.scale_y, k.rotation_deg, k.x, k.y, k.tint);
+        }
+    }
+}
+
+fn main() {
+    let mut it = std::env::args().skip(1);
+    let path = it.next().expect("pak");
+    let entry: usize = it.next().expect("entry").parse().expect("entry");
+    let want = it.next().expect("name");
+    let ar = pak::PakArchive::open(&path).expect("open");
+    let bytes = ar.read(&ar.entries()[entry]).expect("read");
+    let b = ui_layout::parse_build(&bytes).expect("build");
+    println!("entry {entry}: {} elements, design {}x{}", b.elements.len(), b.design_w, b.design_h);
+    let els: Vec<_> = b.elements.iter().filter(|e| e.name.contains(&want)).cloned().collect();
+    show("PARENT", &els);
+    for e in &els {
+        match b.records.get(&e.name) {
+            Some(&(off, size)) => {
+                println!("  -- leaf of {:?}: {size} B at {off}", e.name);
+                match ui_layout::parse_build(&bytes[off..off + size]) {
+                    Some(lb) => show("  LEAF", &lb.elements),
+                    None => println!("     leaf did not parse"),
+                }
+            }
+            None => println!("  -- {:?} has NO leaf record", e.name),
+        }
+    }
+}

crates/sylpheed-formats/examples/leafdbg.rs

@@ -0,0 +1,20 @@
+use sylpheed_formats::{pak, ui_layout};
+fn main(){
+    let ar=pak::PakArchive::open(std::env::args().nth(1).unwrap()).unwrap();
+    let by=ar.read(&ar.entries()[4]).unwrap();
+    let b=ui_layout::parse_build(&by).unwrap();
+    for n in ["ptloop01.rat","ptloop02.rat"] {
+        let el=b.elements.iter().find(|e| e.name==n).unwrap();
+        println!("{n}: kind={:#x} animated={} rec={:?}", el.kind, el.animated,
+                 b.records.get(n).map(|&(o,s)|(o,s)));
+        if let Some(&(o,s))=b.records.get(n) {
+            match ui_layout::parse_build(&by[o..o+s]) {
+                Some(lb)=>for le in &lb.elements {
+                    println!("   leaf {:?} sprite={:?} in_sprites={}", le.name, le.sprite,
+                             le.sprite.as_ref().map(|x| b.sprites.contains_key(x)).unwrap_or(false));
+                },
+                None=>println!("   leaf parse FAILED"),
+            }
+        }
+    }
+}

crates/sylpheed-formats/examples/loo_band.rs

@@ -0,0 +1,26 @@
+// Leave-one-out over the elements that touch a band, dumping raw RGBA each time.
+use sylpheed_formats::{pak, ui_layout};
+fn main(){
+    let mut a=std::env::args().skip(1);
+    let pk=a.next().unwrap();
+    let bi:usize=a.next().unwrap().parse().unwrap();
+    let dir=a.next().unwrap();
+    let ar=pak::PakArchive::open(pk).unwrap();
+    let by=ar.read(&ar.entries()[bi]).unwrap();
+    let b=ui_layout::parse_build(&by).unwrap();
+    let o=ui_layout::ComposeOptions{ backdrop:[0,0,0,255], ..Default::default() };
+    let n=b.elements.len();
+    let base=ui_layout::compose(&b,&by,o.clone(),None);
+    std::fs::write(format!("{dir}/base.raw"),&base.rgba).unwrap();
+    println!("canvas {}x{}  elements {n}", base.width, base.height);
+    for i in 0..n {
+        let e=&b.elements[i];
+        let Some(kf)=e.rest() else { continue };
+        // only bother with elements whose rest pose can touch the band
+        let mut v=vec![true;n]; v[i]=false;
+        let c=ui_layout::compose(&b,&by,o.clone(),Some(&v));
+        std::fs::write(format!("{dir}/wo-{i}.raw"),&c.rgba).unwrap();
+        println!("{i}\t{}\t{}\t({},{})\ta={}", e.name,
+                 e.sprite.clone().unwrap_or_default(), kf.x, kf.y, kf.fade>>24);
+    }
+}

crates/sylpheed-formats/examples/name_from_hash.rs

@@ -0,0 +1,46 @@
+//! Recover a `sound.pak` TOC name from its hash by generating candidates.
+//!
+//! The hash is a Barrett-reduction over the uppercased path, so it cannot be
+//! inverted — but the naming is regular enough to enumerate. Tries the shapes
+//! this disc actually uses for sound entries.
+//!
+//!     cargo run -p sylpheed-formats --example name_from_hash -- <hex-hash>…
+use sylpheed_formats::hash::name_hash;
+
+fn main() {
+    let wanted: Vec<u32> = std::env::args()
+        .skip(1)
+        .filter_map(|a| u32::from_str_radix(a.trim_start_matches("0x"), 16).ok())
+        .collect();
+    assert!(!wanted.is_empty(), "give hashes in hex");
+    let langs = ["eng", "jpn", ""];
+    let dirs = ["", "Movie", "etc", "Voice", "Sound", "BGM", "bgm", "se", "SE"];
+    let mut tried = 0usize;
+    let mut check = |name: String, tried: &mut usize| {
+        *tried += 1;
+        let h = name_hash(&name);
+        if wanted.contains(&h) {
+            println!("  ✅ {h:08x}  {name}");
+        }
+    };
+    for l in langs {
+        for d in dirs {
+            let pre = match (l.is_empty(), d.is_empty()) {
+                (true, true) => String::new(),
+                (true, false) => format!("{d}\\"),
+                (false, true) => format!("{l}\\"),
+                (false, false) => format!("{l}\\{d}\\"),
+            };
+            for stem in ["BGM", "bgm", "JNGL", "jngl", "SE", "Static", "VOICE"] {
+                for n in 0..1200u32 {
+                    check(format!("{pre}{stem}_{n:03}.slb"), &mut tried);
+                    check(format!("{pre}{stem}{n:03}.slb"), &mut tried);
+                }
+            }
+            for bare in ["Static.slb", "static.slb", "SE.slb", "BGM.slb"] {
+                check(format!("{pre}{bare}"), &mut tried);
+            }
+        }
+    }
+    println!("tried {tried} candidate names");
+}

crates/sylpheed-formats/examples/ordinal_entry_map.rs

@@ -0,0 +1,63 @@
+//! Where does `screen --build N`'s ORDINAL diverge from the pak ENTRY index?
+//!
+//! `screen render --build N` takes an ordinal into the filtered build list, not
+//! a pak entry. On `GP_TITLE` `[10]` is entry 12, which is how I rendered two
+//! loading screens while believing they were the splashes — and every downstream
+//! number validated. This enumerates the divergence across the disc so any
+//! `--build N` in `docs/` can be checked instead of trusted.
+//!
+//! Two lists, because `screen list --all` swaps the predicate (`is_composable`
+//! for `is_build`) and therefore RENUMBERS: `--build 4` and `--build 4 --all`
+//! are not necessarily the same object.
+//!
+//!     cargo run -p sylpheed-formats --example ordinal_entry_map
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use std::io::Write;
+use std::path::PathBuf;
+
+/// One decompression pass per entry, both predicates applied to it: reading the
+/// archive twice doubled the cost on `GP_READY_ROOM` (902 entries) for nothing.
+fn maps(ar: &PakArchive) -> (Vec<usize>, Vec<usize>) {
+    let (mut d, mut a) = (Vec::new(), Vec::new());
+    for (i, e) in ar.entries().iter().enumerate() {
+        let Ok(by) = ar.read(e) else { continue };
+        if ui_layout::is_build(&by) { d.push(i) }
+        if ui_layout::is_composable(&by) { a.push(i) }
+    }
+    (d, a)
+}
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let mut paks: Vec<PathBuf> = std::fs::read_dir(root.join("dat")).expect("dat/")
+        .filter_map(|e| e.ok().map(|e| e.path()))
+        .filter(|p| p.extension().is_some_and(|x| x == "pak")).collect();
+    paks.sort();
+    let (mut clean, mut div, mut allshift) = (0usize, 0usize, 0usize);
+    for pak in &paks {
+        let Ok(ar) = PakArchive::open(pak) else { continue };
+        let name = pak.file_name().unwrap().to_string_lossy().to_string();
+        let (d, a) = maps(&ar);
+        if d.is_empty() && a.is_empty() { continue }
+        let bad = d.iter().enumerate().find(|(o, &e)| *o != e).map(|(o, _)| o);
+        // does `--all` renumber? compare the entry each ordinal resolves to
+        let shift = (0..d.len().min(a.len())).find(|&o| d[o] != a[o]);
+        let tag = match bad {
+            None => { clean += 1; format!("{:4} builds  ordinal == entry throughout", d.len()) }
+            Some(o) => { div += 1;
+                let t: Vec<String> = d.iter().enumerate().skip(o).take(5)
+                    .map(|(x, &y)| format!("[{x}]->{y}")).collect();
+                format!("{:4} builds  🔴 diverges at ordinal {o}: {}", d.len(), t.join(" ")) }
+        };
+        let s = match shift {
+            Some(o) => { allshift += 1;
+                format!("   ⚠️  --all renumbers from [{o}]: entry {} -> {}", d[o], a[o]) }
+            None if a.len() != d.len() => format!("   (--all appends {} more)", a.len() - d.len()),
+            None => String::new(),
+        };
+        println!("{name:30} {tag}{s}");
+        std::io::stdout().flush().ok();
+    }
+    println!("\n{clean} archives ordinal==entry, {div} diverge, {allshift} renumbered by --all");
+    println!("--- END ---");
+}

crates/sylpheed-formats/examples/palogo_eff_check.rs

@@ -0,0 +1,40 @@
+//! Are `palogo_gamearts_eff` / `palogo_seta_eff` dwell-FALLBACK cases, or PLATEAU
+//! cases? The port agent lists them among `GP_TITLE`'s four visible fallback
+//! fires; this census listed only `palogo_sqex_eff` and `palogo_anima_eff`.
+//!
+//! It matters because the two are different defects. A plateau is a pose the
+//! element genuinely HOLDS, and `rest_plateau()` returning it is correct. Only the
+//! fallback is the unsound path.
+//!     cargo run -p sylpheed-formats --example palogo_eff_check
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use std::path::PathBuf;
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let ar = PakArchive::open(root.join("dat/GP_TITLE.pak")).expect("GP_TITLE");
+    for (i, e) in ar.entries().iter().enumerate() {
+        let Ok(by) = ar.read(e) else { continue };
+        let Some(b) = ui_layout::parse_build(&by) else { continue };
+        for el in &b.elements {
+            if !el.name.starts_with("palogo") || !el.name.contains("eff") { continue }
+            // A single-keyframe element has no gap to maximise, so neither path
+            // applies and `rest()` trivially returns the only pose. Excluding it
+            // here matches the census, which filters `len < 2`.
+            if el.keyframes.len() < 2 { continue }
+            let plateau = el.keyframes.windows(2).position(|w| {
+                w[0].x == w[1].x && w[0].y == w[1].y && w[0].scale_x == w[1].scale_x
+                    && w[0].scale_y == w[1].scale_y && w[0].fade == w[1].fade
+            });
+            let ks: Vec<String> = el.keyframes.iter().map(|k| format!(
+                "{}:a{} {},{} {}%",
+                k.time.map(|v| v.to_string()).unwrap_or("-".into()),
+                (k.fade >> 24) & 0xff, k.x, k.y, k.scale_x)).collect();
+            let r = el.rest();
+            println!("e{i:<3} {:24} kf=[{}]", el.name, ks.join("  "));
+            println!("       plateau at pair {:?}   -> path: {}   rest a={} t={:?}",
+                     plateau,
+                     if plateau.is_some() { "PLATEAU (sound: the pose is held)" } else { "DWELL FALLBACK (unsound)" },
+                     r.map(|k| (k.fade >> 24) & 0xff).unwrap_or(0),
+                     r.and_then(|k| k.time));
+        }
+    }
+}

crates/sylpheed-formats/examples/plateau_choice.rs

@@ -0,0 +1,90 @@
+//! When an element has MORE THAN ONE plateau, does `rest_plateau()` pick the
+//! wrong one — and is that the 21.9 % residual?
+//!
+//! `rest_vs_settle` found that among elements holding a pose ACROSS the screen's
+//! settle instant, `pose_at(settle)` and `rest()` still disagree 21.9 % of the
+//! time. I hypothesised that `rest_plateau()` picks the **longest** run (it does —
+//! `len >= any_len`), which need not be the run covering the settle instant.
+//!
+//! ⚠️ **Control**: on elements with exactly ONE plateau that covers the settle
+//! instant, the two MUST agree. If they do not, the hypothesis is not the
+//! explanation and something else is wrong.
+//!
+//!     cargo run -p sylpheed-formats --example plateau_choice
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use std::path::PathBuf;
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let mut paks: Vec<PathBuf> = std::fs::read_dir(root.join("dat")).expect("dat/")
+        .filter_map(|e| e.ok().map(|e| e.path()))
+        .filter(|p| p.extension().is_some_and(|x| x == "pak")).collect();
+    paks.sort();
+    let (mut one_cov, mut one_agree) = (0usize, 0usize);          // control
+    let (mut multi_cov, mut multi_agree, mut multi_wrongrun) = (0usize, 0usize, 0usize);
+    for pak in &paks {
+        let Ok(ar) = PakArchive::open(pak) else { continue };
+        for e in ar.entries() {
+            let Ok(by) = ar.read(e) else { continue };
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            let Some((lo, hi)) = b.settle_window() else { continue };
+            if hi - lo < 10 { continue }
+            let st = lo + (hi - lo) / 2;
+            for el in &b.elements {
+                let k = &el.keyframes;
+                if k.len() < 2 { continue }
+                let same = |a: &ui_layout::Keyframe, c: &ui_layout::Keyframe| {
+                    a.fade == c.fade && a.scale_x == c.scale_x && a.scale_y == c.scale_y
+                        && a.tint == c.tint && a.x == c.x && a.y == c.y
+                };
+                // enumerate maximal runs of length >= 2, with their time spans
+                let mut runs: Vec<(usize, usize)> = Vec::new();
+                let mut i = 0usize;
+                while i < k.len() {
+                    let mut j = i;
+                    while j + 1 < k.len() && same(&k[j], &k[j + 1]) { j += 1 }
+                    if j - i + 1 >= 2 { runs.push((i, j)) }
+                    i = j + 1;
+                }
+                if runs.is_empty() { continue }
+                let covers = |&(a, c): &(usize, usize)| match (k[a].time, k[c].time) {
+                    (Some(t0), Some(t1)) => t0 <= st && st <= t1,
+                    _ => false,
+                };
+                let covering: Vec<_> = runs.iter().filter(|r| covers(r)).collect();
+                if covering.is_empty() { continue }
+                let (Some(r), Some(s)) = (el.rest(), el.pose_at(st)) else { continue };
+                let agree = r.fade == s.fade && r.x == s.x && r.y == s.y
+                    && r.scale_x == s.scale_x && r.scale_y == s.scale_y;
+                if runs.len() == 1 {
+                    one_cov += 1;
+                    if agree { one_agree += 1 }
+                } else {
+                    multi_cov += 1;
+                    if agree { multi_agree += 1 }
+                    else {
+                        // did rest() land on a run that does NOT cover settle?
+                        let on_covering = covering.iter().any(|&&(a, c)| {
+                            (a..=c).any(|idx| {
+                                let kk = &k[idx];
+                                kk.fade == r.fade && kk.x == r.x && kk.y == r.y
+                                    && kk.scale_x == r.scale_x && kk.scale_y == r.scale_y
+                            })
+                        });
+                        if !on_covering { multi_wrongrun += 1 }
+                    }
+                }
+            }
+        }
+    }
+    println!("CONTROL — exactly ONE plateau, and it covers the settle instant:");
+    println!("  {one_cov} elements, rest() and pose_at(settle) agree on {one_agree} ({:.1} %)",
+             100.0 * one_agree as f64 / one_cov.max(1) as f64);
+    println!("\nTEST — MORE THAN ONE plateau, at least one covering the settle instant:");
+    println!("  {multi_cov} elements, agree on {multi_agree} ({:.1} %)",
+             100.0 * multi_agree as f64 / multi_cov.max(1) as f64);
+    println!("  of the {} disagreements, rest() landed on a run that does NOT cover",
+             multi_cov - multi_agree);
+    println!("  the settle instant: {multi_wrongrun}");
+    println!("\n--- END (if this line is missing, the run did not finish) ---");
+}

crates/sylpheed-formats/examples/prm_alpha_census.rs

@@ -0,0 +1,50 @@
+//! Does a primitive's alpha AT t=0 predict the layer it paints on?
+//!
+//! `implied_layer_key` is a measured per-name table. The four entries in it, read
+//! against their own keyframes, suggest a rule derived from the file instead:
+//!
+//!   * `palogo_eff0.prm`  measured FIRST (0x0000)   -- alpha at t=0 = ?
+//!   * `pfbase.tbm`       measured FIRST (0x0000)   -- alpha at t=0 = ?
+//!   * `pteff02.prm`      measured MIDDLE (0x8030)  -- alpha at t=0 = ?
+//!   * `pteff00.prm`      measured LAST             -- alpha at t=0 = ?
+//!
+//! ⚠️ The rule was invented AFTER seeing three of those answers, so it is fitted
+//! on them and only `pfbase.tbm` is out of sample. This prints all four plus a
+//! disc-wide census, so the fit and its reach are visible together.
+use sylpheed_formats::{pak, ratc, ui_layout};
+use std::collections::BTreeMap;
+
+fn main() {
+    let root = std::env::var("SYLPHEED_DISC").unwrap_or_else(|_| "/disc".into());
+    let mut paks: Vec<_> = std::fs::read_dir(format!("{root}/dat")).expect("dat/")
+        .flatten().map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("pak")).collect();
+    paks.sort();
+    // name -> (count, set of t=0 alphas, set of "starts at max" flags)
+    let mut byname: BTreeMap<String, (usize, BTreeMap<u32, usize>)> = BTreeMap::new();
+    for p in &paks {
+        let Ok(ar) = pak::PakArchive::open(p) else { continue };
+        for e in ar.entries() {
+            let Ok(by) = ar.read(e) else { continue };
+            if !ratc::is_ratc(&by) { continue }
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            for el in &b.elements {
+                // primitives and the keyless: anything with no layer key
+                if ui_layout::sprite_layer_key(&b, &by, el).is_some() { continue }
+                let Some(k0) = el.keyframes.first() else { continue };
+                let a0 = k0.fade >> 24;
+                let ent = byname.entry(el.name.clone()).or_default();
+                ent.0 += 1;
+                *ent.1.entry(a0).or_default() += 1;
+            }
+        }
+    }
+    println!("{:>28}  {:>7}  alpha at t=0 (count)", "keyless element", "n");
+    let known = ["palogo_eff0.prm", "pfbase.tbm", "pteff02.prm", "pteff00.prm"];
+    for (n, (c, a)) in &byname {
+        let tag = if known.contains(&n.as_str()) { "  <- IN THE MEASURED TABLE" } else { "" };
+        if *c < 4 && tag.is_empty() { continue }
+        let al: Vec<String> = a.iter().map(|(k, v)| format!("{k}x{v}")).collect();
+        println!("  {n:>26}  {c:>7}  {}{tag}", al.join(" "));
+    }
+}

crates/sylpheed-formats/examples/prm_colour_census.rs

@@ -0,0 +1,37 @@
+//! What COLOUR is a primitive, and does any of them only make sense additively?
+//!
+//! `ui-prm-primitives.md` leaves blend mode open, and `forced_backdrop` assumes
+//! straight alpha-over. A quad whose ARGB would tint the whole screen a colour no
+//! screen shows is evidence against alpha-over for that quad.
+use sylpheed_formats::{pak, ratc, ui_layout};
+use std::collections::BTreeMap;
+fn main(){
+    let root=std::env::var("SYLPHEED_DISC").unwrap_or_else(|_|"/disc".into());
+    let mut paks:Vec<_>=std::fs::read_dir(format!("{root}/dat")).expect("dat/")
+        .flatten().map(|e|e.path())
+        .filter(|p|p.extension().and_then(|s|s.to_str())==Some("pak")).collect();
+    paks.sort();
+    let mut m:BTreeMap<String,BTreeMap<String,usize>>=BTreeMap::new();
+    for p in &paks {
+        let Ok(ar)=pak::PakArchive::open(p) else { continue };
+        for e in ar.entries() {
+            let Ok(by)=ar.read(e) else { continue };
+            if !ratc::is_ratc(&by) { continue }
+            let Some(b)=ui_layout::parse_build(&by) else { continue };
+            for el in &b.elements {
+                if el.sprite.is_some() { continue }
+                for k in &el.keyframes {
+                    *m.entry(el.name.clone()).or_default()
+                        .entry(format!("{:08x}", k.fade)).or_default()+=1;
+                }
+            }
+        }
+    }
+    println!("{:>26}  fade ARGB values (count)", "keyless element");
+    for (n,v) in &m {
+        let tot:usize=v.values().sum();
+        if tot<4 { continue }
+        let s:Vec<String>=v.iter().map(|(k,c)|format!("{k}x{c}")).collect();
+        println!("  {n:>24}  {}", s.join("  "));
+    }
+}

crates/sylpheed-formats/examples/prm_forced_first.rs

@@ -0,0 +1,58 @@
+//! Which keyless primitives have their paint position FORCED by occlusion?
+//!
+//! An opaque full-screen quad must sort below every element visible at any
+//! instant it is opaque. Where that set is *every* other element, its position is
+//! forced to first — derived from the file, not analogised from a neighbour.
+//!
+//! Controls, both measured in the running game and both reproduced here:
+//!   * `palogo_eff0.prm` is measured painting FIRST — and comes out forced first.
+//!   * `pteff00.prm` is measured painting LAST — and is forced below only a
+//!     handful, so the constraint permits it on top.
+//!
+//! ⚠️ Assumes straight alpha-over blending. Blend mode is ❔ in
+//! `ui-prm-primitives.md`; an additive quad at alpha 255 would not occlude.
+use sylpheed_formats::{pak, ratc, ui_layout};
+
+fn main() {
+    let root = std::env::var("SYLPHEED_DISC").unwrap_or_else(|_| "/disc".into());
+    let mut paks: Vec<_> = std::fs::read_dir(format!("{root}/dat")).expect("dat/")
+        .flatten().map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("pak")).collect();
+    paks.sort();
+    let (mut forced, mut partial, mut free) = (0usize, 0usize, 0usize);
+    let mut names: std::collections::BTreeMap<String, (usize, usize)> = Default::default();
+    for p in &paks {
+        let Ok(ar) = pak::PakArchive::open(p) else { continue };
+        for e in ar.entries() {
+            let Ok(by) = ar.read(e) else { continue };
+            if !ratc::is_ratc(&by) { continue }
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            let tmax = b.elements.iter().flat_map(|el| el.keyframes.iter().filter_map(|k| k.time))
+                        .max().unwrap_or(0);
+            if tmax == 0 { continue }
+            for el in &b.elements {
+                if ui_layout::sprite_layer_key(&b, &by, el).is_some() { continue }
+                // full-screen only: a quad that does not cover cannot occlude
+                if el.pivot_x * 2 < 1280 || el.pivot_y * 2 < 720 { continue }
+                let op: Vec<u32> = (0..=tmax)
+                    .filter(|&t| el.pose_at(t).map(|k| k.fade >> 24) == Some(255)).collect();
+                if op.is_empty() { continue }
+                let others: Vec<&ui_layout::Element> =
+                    b.elements.iter().filter(|o| o.index != el.index).collect();
+                if others.is_empty() { continue }
+                let below = others.iter().filter(|o|
+                    op.iter().any(|&t| o.pose_at(t).map(|k| k.fade >> 24).unwrap_or(0) > 0)).count();
+                let ent = names.entry(el.name.clone()).or_default();
+                ent.1 += 1;
+                if below == others.len() { forced += 1; ent.0 += 1 }
+                else if below > 0 { partial += 1 } else { free += 1 }
+            }
+        }
+    }
+    println!("keyless FULL-SCREEN primitives with an opaque interval:");
+    println!("  position FORCED FIRST (below every other element) : {forced}");
+    println!("  forced below SOME but not all                     : {partial}");
+    println!("  occludes nothing                                  : {free}");
+    println!("\nby name — instances forced first / total:");
+    for (n, (f, t)) in &names { println!("  {n:>24}  {f:>4} / {t}"); }
+}

crates/sylpheed-formats/examples/prm_occlusion_check.rs

@@ -0,0 +1,73 @@
+//! An OPAQUE full-screen primitive cannot paint on top of elements that are
+//! visible at the same time — the screen would be blank.
+//!
+//! That is a constraint read off the file, not a preference. For each keyless
+//! primitive this computes the interval over which it is opaque, and the interval
+//! over which any OTHER element is visible, and reports the overlap.
+//!
+//! The falsifier: `pteff00.prm` is MEASURED painting last on the title and the
+//! main menu. If any of its instances is opaque while content is up, the
+//! constraint is wrong and this whole line is dead.
+use sylpheed_formats::{pak, ratc, ui_layout};
+
+/// Interval(s) where alpha >= `thr`, sampled at every half unit.
+fn opaque_span(el: &ui_layout::Element, thr: u32, tmax: u32) -> Vec<(f64, f64)> {
+    let mut out = Vec::new();
+    let mut cur: Option<f64> = None;
+    let mut t = 0.0;
+    while t <= tmax as f64 {
+        let a = el.pose_at(t as u32).map(|k| k.fade >> 24).unwrap_or(0);
+        if a >= thr {
+            if cur.is_none() { cur = Some(t) }
+        } else if let Some(s) = cur.take() {
+            out.push((s, t));
+        }
+        t += 0.5;
+    }
+    if let Some(s) = cur { out.push((s, tmax as f64)) }
+    out
+}
+
+fn main() {
+    let root = std::env::var("SYLPHEED_DISC").unwrap_or_else(|_| "/disc".into());
+    let mut paks: Vec<_> = std::fs::read_dir(format!("{root}/dat")).expect("dat/")
+        .flatten().map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("pak")).collect();
+    paks.sort();
+    let want = ["pteff00.prm", "pgloading_eff00.prm", "palogo_eff0.prm",
+                "pfbase.tbm", "pteff02.prm", "pzeff00.prm", "pceff00.prm", "pdeff00.prm"];
+    println!("{:>22} {:>5}  {:>16}  {:>18}  overlap", "primitive", "entry", "opaque while", "content visible");
+    for p in &paks {
+        let Ok(ar) = pak::PakArchive::open(p) else { continue };
+        for (ei, e) in ar.entries().iter().enumerate() {
+            let Ok(by) = ar.read(e) else { continue };
+            if !ratc::is_ratc(&by) { continue }
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            let tmax = b.elements.iter().flat_map(|el| el.keyframes.iter().filter_map(|k| k.time))
+                        .max().unwrap_or(0);
+            if tmax == 0 { continue }
+            for el in &b.elements {
+                if !want.contains(&el.name.as_str()) { continue }
+                if ui_layout::sprite_layer_key(&b, &by, el).is_some() { continue }
+                let op = opaque_span(el, 255, tmax);
+                if op.is_empty() { continue }
+                // when is any OTHER element visible?
+                let mut cmin = f64::MAX; let mut cmax = f64::MIN;
+                for o in &b.elements {
+                    if o.index == el.index { continue }
+                    for (s, t) in opaque_span(o, 1, tmax) { cmin = cmin.min(s); cmax = cmax.max(t) }
+                }
+                if cmin > cmax { continue }
+                // overlap of the primitive's opaque span with the content span
+                let ov: f64 = op.iter()
+                    .map(|&(s, t)| (t.min(cmax) - s.max(cmin)).max(0.0)).sum();
+                let opd: String = op.iter().map(|&(s,t)| format!("{s:.0}-{t:.0}")).collect::<Vec<_>>().join(",");
+                let flag = if ov > 2.0 { "  🔴 CANNOT BE ON TOP" } else { "" };
+                println!("{:>22} {:>5}  {:>16}  {:>18}  {ov:6.1}{flag}",
+                    el.name, format!("{}:{}", p.file_name().unwrap().to_string_lossy()
+                        .trim_end_matches(".pak").trim_start_matches("GP_"), ei),
+                    opd, format!("{cmin:.0}-{cmax:.0}"));
+            }
+        }
+    }
+}

crates/sylpheed-formats/examples/prm_span_sensitivity.rs

@@ -0,0 +1,82 @@
+//! Does `forced_backdrop`'s verdict depend on how the screen's timeline ENDS?
+//!
+//! The rule quantifies over "every instant the primitive is opaque" and "every
+//! element visible then", so both halves depend on where the timeline stops and
+//! on what an element does after its own last keyframe. The port asked, and it is
+//! the right question: a verdict that flips with the convention is not a decode.
+//!
+//! Four conventions, all applied to the same disc:
+//!   A  span = max keyframe time over all elements; elements HOLD their last pose
+//!      (what `forced_backdrop` does, and what the port implements)
+//!   B  span = the primitive's OWN last keyframe time; elements hold
+//!   C  span = the bundle header `+0x08` (the declared length); elements hold
+//!   D  span = max keyframe time; an element is GONE after its own last keyframe
+//!
+//! D is the one worth the most: it is the assumption the port flagged as "doing
+//! real work", and it strictly shrinks the visible set, so it can only turn
+//! `forced` into `not forced`.
+use sylpheed_formats::{pak, ratc, ui_layout};
+
+fn last_t(el: &ui_layout::Element) -> u32 {
+    el.keyframes.iter().filter_map(|k| k.time).max().unwrap_or(0)
+}
+
+fn forced(b: &ui_layout::UiBuild, el: &ui_layout::Element, tmax: u32, hold: bool) -> Option<bool> {
+    if el.sprite.is_some() { return None }
+    if (el.pivot_x * 2) < b.design_w as u32 || (el.pivot_y * 2) < b.design_h as u32 { return None }
+    if tmax == 0 { return None }
+    let alpha = |e: &ui_layout::Element, t: u32| -> u32 {
+        if !hold && t > last_t(e) { return 0 }
+        e.pose_at(t).map(|k| k.fade >> 24).unwrap_or(0)
+    };
+    let op: Vec<u32> = (0..=tmax).filter(|&t| alpha(el, t) == 255).collect();
+    if op.is_empty() { return None }
+    let others: Vec<&ui_layout::Element> = b.elements.iter().filter(|o| o.index != el.index).collect();
+    if others.is_empty() { return None }
+    let below = others.iter().filter(|o| op.iter().any(|&t| alpha(o, t) > 0)).count();
+    Some(below == others.len())
+}
+
+fn main() {
+    let root = std::env::var("SYLPHEED_DISC").unwrap_or_else(|_| "/disc".into());
+    let mut paks: Vec<_> = std::fs::read_dir(format!("{root}/dat")).expect("dat/")
+        .flatten().map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("pak")).collect();
+    paks.sort();
+    let (mut n, mut a_true) = (0usize, 0usize);
+    let mut flips = [0usize; 3];
+    let mut examples: Vec<String> = Vec::new();
+    for p in &paks {
+        let Ok(ar) = pak::PakArchive::open(p) else { continue };
+        for (ei, e) in ar.entries().iter().enumerate() {
+            let Ok(by) = ar.read(e) else { continue };
+            if !ratc::is_ratc(&by) { continue }
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            let tall = b.elements.iter().flat_map(|el| el.keyframes.iter().filter_map(|k| k.time))
+                        .max().unwrap_or(0);
+            let hdr = if by.len() >= 12 { u32::from_be_bytes(by[8..12].try_into().unwrap()) } else { 0 };
+            for el in &b.elements {
+                let Some(va) = forced(&b, el, tall, true) else { continue };
+                n += 1; if va { a_true += 1 }
+                for (k, vb) in [forced(&b, el, last_t(el), true),
+                                forced(&b, el, hdr, true),
+                                forced(&b, el, tall, false)].into_iter().enumerate() {
+                    if vb != Some(va) {
+                        flips[k] += 1;
+                        if k == 2 && examples.len() < 6 {
+                            examples.push(format!("{}:{} {} A={va} D={vb:?}",
+                                p.file_name().unwrap().to_string_lossy(), ei, el.name));
+                        }
+                    }
+                }
+            }
+        }
+    }
+    println!("keyless full-screen primitives with an opaque interval: {n}");
+    println!("  convention A (span = all elements' max, hold)  -> forced first: {a_true}\n");
+    println!("  verdicts that CHANGE under:");
+    println!("    B  span = the primitive's own last keyframe  : {}", flips[0]);
+    println!("    C  span = the header's declared length +0x08 : {}", flips[1]);
+    println!("    D  elements GONE after their last keyframe   : {}", flips[2]);
+    for e in &examples { println!("       {e}") }
+}

crates/sylpheed-formats/examples/ptloop_leaf_extent.rs

@@ -0,0 +1,65 @@
+//! The FULL extent of the two title sweep leaves, across their whole cycle.
+//!
+//! `ptloop_leaf_sweep_at.rs` samples t=340..540 — a window chosen to compare two
+//! competing fits — so it never showed how far the leaves travel. That gap let a
+//! claim stand that `ptloop01/02` "do not free-run", measured over the PARENT's
+//! 200x90 rect, which is a pivot anchor the leaf spends almost no time inside.
+//! `sylpheed-port` reports x tracks of -639..1521 and -839..1721 from their
+//! export; this checks that against the disc.
+//!
+//!     cargo run -p sylpheed-formats --example ptloop_leaf_extent
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use std::path::PathBuf;
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let ar = PakArchive::open(root.join("dat/GP_TITLE.pak")).expect("GP_TITLE.pak");
+    for entry in [4usize, 5, 7] {
+        let Ok(by) = ar.read(&ar.entries()[entry]) else { continue };
+        let Some(b) = ui_layout::parse_build(&by) else { continue };
+        println!("\n######## GP_TITLE entry {entry} ########");
+        for parent in ["ptloop01", "ptloop02"] {
+            let Some(el) = b.elements.iter().find(|e| e.name.starts_with(parent)) else {
+                println!("  {parent}: not present in this build"); continue };
+            let Some(&(off, size)) = b.records.get(&el.name) else {
+                println!("  {}: no nested record", el.name); continue };
+            let span = u32::from_be_bytes(by[off + 8..off + 12].try_into().unwrap());
+            let Some(lb) = ui_layout::parse_build(&by[off..off + size]) else {
+                println!("  {}: leaf will not parse", el.name); continue };
+            println!("  {} parent rest ({},{})  nested cycle span {span}",
+                     el.name, el.keyframes.last().map(|k| k.x).unwrap_or(0),
+                     el.keyframes.last().map(|k| k.y).unwrap_or(0));
+            for le in &lb.elements {
+                let (mut lo, mut hi) = (i64::MAX, i64::MIN);
+                let (mut sxs, mut sys) = (Vec::new(), Vec::new());
+                for t in 0..=span {
+                    if let Some(k) = le.pose_at(t) {
+                        lo = lo.min(k.x as i64); hi = hi.max(k.x as i64);
+                        if !sxs.contains(&k.scale_x) { sxs.push(k.scale_x) }
+                        if !sys.contains(&k.scale_y) { sys.push(k.scale_y) }
+                    }
+                }
+                // A CYCLE LENGTH IS NOT A MOTION DURATION. Find the last t at
+                // which x still changes: sylpheed-port reports the final segment
+                // HOLDS, which would make px/unit larger than cycle-based maths.
+                let mut last_move = 0u32;
+                let mut prev = None;
+                for t in 0..=span {
+                    if let Some(k) = le.pose_at(t) {
+                        if prev.map_or(false, |p| p != k.x) { last_move = t }
+                        prev = Some(k.x);
+                    }
+                }
+                let w = (le.pivot_x * 2) as i64;
+                println!("    leaf {:<12} pivot {}x{}  quad w={w}  x track {lo} .. {hi}  \
+                          (centre {} .. {})  scale_x {:?} scale_y {:?}",
+                         le.name, le.pivot_x, le.pivot_y,
+                         lo + le.pivot_x as i64, hi + le.pivot_x as i64, sxs, sys);
+                println!("      motion ends at t={last_move} of a {span}-unit cycle ->                           {:.3} px/unit over the MOVING span (vs {:.3} over the cycle)",
+                         (hi - lo) as f64 / last_move.max(1) as f64,
+                         (hi - lo) as f64 / span as f64);
+            }
+        }
+    }
+    println!("--- END ---");
+}

crates/sylpheed-formats/examples/ptloop_leaf_keyframes.rs

@@ -0,0 +1,37 @@
+//! The sweep leaves' RAW keyframes, so a segment rate can be checked not assumed.
+//!
+//! `sylpheed-port` reports `pteff03` as +4.0000 px/unit over t 0..150 and +4.0000
+//! again over 150..540 -- perfectly linear -- against `pteff03a` at -4.0667 then
+//! -4.0625. That asymmetry is what makes their "inversion" observation sharp: my
+//! linearity gate fails on the leaf whose source is exactly straight. It is their
+//! number from their export, so it is worth deriving independently.
+//!
+//!     cargo run -p sylpheed-formats --example ptloop_leaf_keyframes
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use std::path::PathBuf;
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let ar = PakArchive::open(root.join("dat/GP_TITLE.pak")).expect("GP_TITLE.pak");
+    let by = ar.read(&ar.entries()[4]).expect("entry 4");
+    let b = ui_layout::parse_build(&by).expect("parse");
+    for parent in ["ptloop01", "ptloop02"] {
+        let Some(el) = b.elements.iter().find(|e| e.name.starts_with(parent)) else { continue };
+        let Some(&(off, size)) = b.records.get(&el.name) else { continue };
+        let Some(lb) = ui_layout::parse_build(&by[off..off + size]) else { continue };
+        for le in &lb.elements {
+            println!("\n== {} -> leaf {}", el.name, le.name);
+            let ks: Vec<_> = le.keyframes.iter().collect();
+            for w in ks.windows(2) {
+                let (a, c) = (w[0], w[1]);
+                match (a.time, c.time) {
+                    (Some(t0), Some(t1)) if t1 > t0 => println!(
+                        "   t {t0:>4} -> {t1:<4}  x {:>6} -> {:<6}  = {:+.4} px/unit",
+                        a.x, c.x, (c.x - a.x) as f64 / (t1 - t0) as f64),
+                    _ => println!("   t {:?} -> {:?}  x {} -> {}  (no rate)", a.time, c.time, a.x, c.x),
+                }
+            }
+        }
+    }
+    println!("--- END ---");
+}

crates/sylpheed-formats/examples/ptloop_leaf_sweep_at.rs

@@ -0,0 +1,91 @@
+//! Where are the title's two light-sweep quads at a given time — and is a
+//! best-fit against a framebuffer PNG even measuring their position?
+//!
+//! `ui-leaf-vs-parent-alpha.md` solves the sweep instant as **t = 357.7** from a
+//! GPU per-draw capture: quad centre x measured off the submitted vertex buffer,
+//! which is a position measurement at 4 px/unit. The port agent separately
+//! best-fits the same leaf against `live-title-build4-no-plate.png` and gets
+//! **~400 units**, and asked whether the two used the same capture.
+//!
+//! Before comparing the numbers, check whether the second method can see what it
+//! claims to measure. A fit that is minimised by the quad being OFF-SCREEN is
+//! minimised by absence, and would return "best" at whatever time draws least —
+//! the same shape as the `.tbm` control that could not fail.
+//!
+//! So: print the leaves' own x, alpha, and on-screen overlap across the window.
+//!
+//!     cargo run -p sylpheed-formats --example ptloop_leaf_sweep_at
+
+use std::path::PathBuf;
+
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+
+const SCREEN_W: i64 = 1280;
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let ar = PakArchive::open(root.join("dat/GP_TITLE.pak")).expect("GP_TITLE.pak");
+    let by = ar.read(&ar.entries()[4]).expect("entry 4");
+    let b = ui_layout::parse_build(&by).expect("parse");
+
+    for parent in ["ptloop01", "ptloop02"] {
+        let Some(el) = b.elements.iter().find(|e| e.name.starts_with(parent)) else {
+            eprintln!("no element {parent}");
+            continue;
+        };
+        let Some(&(off, size)) = b.records.get(&el.name) else {
+            eprintln!("{}: no nested record", el.name);
+            continue;
+        };
+        // `ui-record-loop-length.md`: a nested record's header `+0x08` is its
+        // CYCLE LENGTH, and its keyframes need not fill it. This is why two
+        // captures of the same settled title do not share a sweep phase.
+        let loop_len = u32::from_be_bytes(by[off + 8..off + 12].try_into().unwrap());
+        println!("\n-- {} nested record: loop length (+0x08) = {loop_len}", el.name);
+        let Some(lb) = ui_layout::parse_build(&by[off..off + size]) else {
+            eprintln!("{}: leaf will not parse", el.name);
+            continue;
+        };
+        for le in &lb.elements {
+            let w = (le.pivot_x * 2) as i64;
+            println!(
+                "\n== {} -> leaf {} (sprite {:?}, pivot {}x{}, {} keyframes, last t={:?})",
+                el.name,
+                le.name,
+                le.sprite,
+                le.pivot_x,
+                le.pivot_y,
+                le.keyframes.len(),
+                le.keyframes.last().map(|k| k.time)
+            );
+            // ⚠️ A keyframe's `x` is the quad's LEFT edge, not its centre. The
+            // draw-capture fit is quoted in CENTRES, so compare `centre`, which is
+            // `x + pivot_x`. Printing `x` under a "centre" heading is how a
+            // 200-px offset gets into a comparison unnoticed.
+            println!("      t |    x | centre |   a | on-screen px of a {w}px-wide quad");
+            for t in [
+                340u32, 350, 355, 357, 358, 360, 370, 380, 390, 395, 400, 405, 410, 420, 440, 480,
+                540,
+            ] {
+                let Some(k) = le.pose_at(t) else {
+                    println!("   {t:>4} |   (no pose)");
+                    continue;
+                };
+                let x = k.x as i64;
+                let a = k.fade >> 24;
+                let l = x;
+                let r = l + w;
+                let vis = (r.min(SCREEN_W) - l.max(0)).max(0);
+                println!(
+                    "   {t:>4} | {x:>4} | {:>6} | {a:>3} | {vis:>5} px  {}",
+                    x + le.pivot_x as i64,
+                    if vis == 0 {
+                        "*** ENTIRELY OFF SCREEN ***"
+                    } else {
+                        ""
+                    }
+                );
+            }
+        }
+    }
+}

crates/sylpheed-formats/examples/record_loop_length.rs

@@ -0,0 +1,69 @@
+//! Is a nested record's header `+0x08` its LOOP LENGTH — and do its keyframes
+//! have to fill it?
+//!
+//! A `*f` focus record animates forever while its button is focused, so
+//! something must say where the cycle restarts. The keyframes cannot: the plate's
+//! `ptbtn00f` runs 0→80→0 over 105 units, and looping at 105 gives a period 15 %
+//! short of every measurement of the real thing.
+//!
+//! Each record is itself a RATC bundle with its own header, and `+0x08` is a
+//! frame count. If it is the loop length then it must never be LESS than the
+//! record's largest keyframe time — an animation cannot restart before its own
+//! last pose — and it may be more, which is a hold at the final pose.
+//!
+//! Two controls, both of which a wrong reading fails:
+//!   * `+0x08 < max keyframe time` must never happen. That is the falsifier.
+//!   * The distribution must not be trivial: if every record had exactly
+//!     `+0x08 == max t`, the field would carry nothing and "loop length" would be
+//!     an unfalsifiable relabelling of the keyframes.
+use sylpheed_formats::{pak, ratc, ui_layout};
+use std::collections::BTreeMap;
+
+fn main() {
+    let root = std::env::var("SYLPHEED_DISC").unwrap_or_else(|_| "/disc".into());
+    let mut paks: Vec<_> = std::fs::read_dir(format!("{root}/dat")).expect("dat/")
+        .flatten().map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("pak")).collect();
+    paks.sort();
+    let (mut total, mut exact, mut holds, mut violations) = (0usize, 0usize, 0usize, 0usize);
+    let mut hold_hist: BTreeMap<i64, usize> = BTreeMap::new();
+    let mut worst: Vec<(i64, String)> = Vec::new();
+    for p in &paks {
+        let Ok(ar) = pak::PakArchive::open(p) else { continue };
+        for e in ar.entries() {
+            let Ok(by) = ar.read(e) else { continue };
+            if !ratc::is_ratc(&by) { continue }
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            for (rn, &(o, s)) in &b.records {
+                if o + 12 > by.len() || o + s > by.len() { continue }
+                if &by[o..o + 4] != b"RATC" { continue }
+                let len = u32::from_be_bytes(by[o + 8..o + 12].try_into().unwrap()) as i64;
+                let Some(lb) = ui_layout::parse_build(&by[o..o + s]) else { continue };
+                let maxt = lb.elements.iter()
+                    .flat_map(|el| el.keyframes.iter().filter_map(|k| k.time))
+                    .max().unwrap_or(0) as i64;
+                if maxt == 0 { continue }          // a static record declares no cycle
+                total += 1;
+                let slack = len - maxt;
+                *hold_hist.entry(slack).or_default() += 1;
+                if slack == 0 { exact += 1 } else if slack > 0 { holds += 1 } else {
+                    violations += 1;
+                    if worst.len() < 12 {
+                        worst.push((slack, format!("{}:{rn} len={len} maxt={maxt}",
+                            p.file_name().unwrap().to_string_lossy())));
+                    }
+                }
+            }
+        }
+    }
+    println!("nested records with timed keyframes : {total}");
+    println!("  +08 == max keyframe time (exact)  : {exact}  ({:.1}%)", 100.0*exact as f64/total as f64);
+    println!("  +08 >  max keyframe time (a hold) : {holds}  ({:.1}%)", 100.0*holds as f64/total as f64);
+    println!("  +08 <  max keyframe time  🔴      : {violations}  ({:.2}%)  <- the falsifier",
+             100.0*violations as f64/total as f64);
+    println!("\nslack (+08 - max t) distribution, most common first:");
+    let mut h: Vec<_> = hold_hist.iter().collect();
+    h.sort_by_key(|&(_, n)| std::cmp::Reverse(*n));
+    for (k, n) in h.iter().take(14) { println!("   slack {k:>6} : {n}"); }
+    if !worst.is_empty() { println!("\nviolations:"); for (s, w) in &worst { println!("   {s:>6}  {w}"); } }
+}

crates/sylpheed-formats/examples/record_loop_length_api.rs

@@ -0,0 +1,63 @@
+//! Verify the newly-public `ui_layout::loop_length_units` against the disc.
+//!
+//! `sylpheed-port` reads a record's `+0x08` itself, guarded on the RATC magic,
+//! because the field was exposed on no public ref at all — example, test and
+//! `docs/re/` only. This checks the public function reproduces the numbers the
+//! finding was written from before the port depends on it.
+//!
+//! CONTROL FIRST: the function must return `None` for a non-RATC slice and for a
+//! slice too short to hold the field. An accessor that returns a number for
+//! anything cannot be trusted to return the right one.
+//!
+//!     cargo run -p sylpheed-formats --example record_loop_length_api
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use std::path::PathBuf;
+
+fn main() {
+    // ---- controls -------------------------------------------------------
+    assert_eq!(ui_layout::loop_length_units(b"NOTR\x00\x00\x00\x00\x00\x00\x00\x78"), None,
+               "control FAILED: accepted a non-RATC slice");
+    assert_eq!(ui_layout::loop_length_units(b"RATC\x00\x00"), None,
+               "control FAILED: accepted a slice too short for +0x08");
+    assert_eq!(ui_layout::loop_length_units(b"RATC\x00\x00\x00\x00\x00\x00\x00\x78"), Some(120),
+               "control FAILED: did not read +0x08 big-endian");
+    println!("controls pass: rejects non-RATC, rejects short, reads BE at +0x08");
+
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let ar = PakArchive::open(root.join("dat/GP_TITLE.pak")).expect("GP_TITLE.pak");
+
+    // The records the finding names, with their published values.
+    let expect: &[(&str, u32)] = &[("ptbtn00f.rat", 120), ("ptloop01.rat", 600),
+                                   ("ptloop02.rat", 720)];
+    let mut seen = 0usize;
+    let (mut recs, mut viol) = (0usize, 0usize);
+
+    for (ei, e) in ar.entries().iter().enumerate() {
+        let Ok(by) = ar.read(e) else { continue };
+        let Some(b) = ui_layout::parse_build(&by) else { continue };
+        for (name, (off, size)) in &b.records {
+            let rec = &by[*off..(*off + *size).min(by.len())];
+            let Some(len) = ui_layout::loop_length_units(rec) else { continue };
+            recs += 1;
+            // the disc-wide invariant the finding rests on
+            let largest = ui_layout::parse_build(rec)
+                .map(|l| l.elements.iter()
+                     .flat_map(|el| el.keyframes.iter().filter_map(|k| k.time))
+                     .max().unwrap_or(0))
+                .unwrap_or(0);
+            if len < largest { viol += 1; }
+            for (want_name, want) in expect {
+                if name == want_name && seen < 16 {
+                    seen += 1;
+                    let ok = if len == *want { "OK" } else { "MISMATCH" };
+                    println!("  entry {ei:2}  {name:16} +0x08 = {len:4}  \
+                              (published {want})  largest kf {largest:4}  {ok}");
+                    assert_eq!(len, *want, "{name} disagrees with the published value");
+                }
+            }
+        }
+    }
+    println!("\n{recs} records read through the public fn; \
+              {viol} violate +0x08 >= largest keyframe time");
+    assert!(seen > 0, "found none of the named records — the check proved nothing");
+}

crates/sylpheed-formats/examples/rest_fallback_audit.rs

@@ -0,0 +1,68 @@
+//! Does "1 697 fallback fires return a visible pose" survive being said out loud?
+//!
+//! `rest-fallback-census.txt` reports that of 2 305 elements where the dwell
+//! fallback decides, 1 697 rest at `alpha > 0`. It was written as if that number
+//! were the defect. **It is only a defect where the element is a transient.** An
+//! element that genuinely ends visible and stays visible SHOULD rest visible, and
+//! the fallback happening to be the path that got there is not an error.
+//!
+//! The port agent hit the mirror image of this: it counted a screen's own exit
+//! ramp as the end of an element's visibility, so `ptmsg` — the main menu's
+//! permanent footer — came out as "a 2-unit flash". The story collapsed when
+//! said aloud. This asks the same question of my number.
+//!
+//! Split the 1 697 by what the element's LAST keyframe does:
+//!   * last alpha > 0  -> the element ends visible; resting visible is right
+//!   * last alpha == 0 -> it fades out; a visible rest is a transient's peak
+//!
+//!     cargo run -p sylpheed-formats --example rest_fallback_audit
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use std::path::PathBuf;
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let mut paks: Vec<PathBuf> = std::fs::read_dir(root.join("dat")).expect("dat/")
+        .filter_map(|e| e.ok().map(|e| e.path()))
+        .filter(|p| p.extension().is_some_and(|x| x == "pak")).collect();
+    paks.sort();
+    let (mut fires, mut vis, mut ends_visible, mut ends_zero, mut at_peak) = (0, 0, 0, 0, 0);
+    // ⚠️ The port agent's exit-ramp finding applies to THIS split too: if a
+    // screen's exit ramp drives every element to a=0, then "last keyframe a=0"
+    // says nothing about the element being a transient. Measure it on ALL
+    // elements before using it on the 1 697.
+    let (mut all_el, mut all_end_zero) = (0usize, 0usize);
+    for pak in &paks {
+        let Ok(ar) = PakArchive::open(pak) else { continue };
+        for e in ar.entries() {
+            let Ok(by) = ar.read(e) else { continue };
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            for el in &b.elements {
+                if el.keyframes.len() < 2 { continue }
+                all_el += 1;
+                if (el.keyframes.last().unwrap().fade >> 24) & 0xff == 0 { all_end_zero += 1 }
+                if el.keyframes.windows(2).any(|w| w[0].x == w[1].x && w[0].y == w[1].y
+                    && w[0].scale_x == w[1].scale_x && w[0].scale_y == w[1].scale_y
+                    && w[0].fade == w[1].fade) { continue }
+                fires += 1;
+                let Some(r) = el.rest() else { continue };
+                let a = (r.fade >> 24) & 0xff;
+                if a == 0 { continue }
+                vis += 1;
+                let last = (el.keyframes.last().unwrap().fade >> 24) & 0xff;
+                if last > 0 { ends_visible += 1 } else { ends_zero += 1 }
+                let peak = el.keyframes.iter().map(|k| (k.fade >> 24) & 0xff).max().unwrap_or(0);
+                if a == peak { at_peak += 1 }
+            }
+        }
+    }
+    println!("fallback fires                         {fires}");
+    println!("  of those, rest alpha > 0             {vis}");
+    println!("    element's LAST keyframe alpha > 0  {ends_visible}   <- ends visible; resting visible is CORRECT");
+    println!("    element's LAST keyframe alpha = 0  {ends_zero}   <- fades out; a visible rest is a transient's peak");
+    println!("  rest alpha == the element's MAX      {at_peak}");
+    println!("\nCONTROL on the split itself — is 'ends at a=0' near-universal?");
+    println!("  all elements with >= 2 keyframes     {all_el}");
+    println!("  of those, last keyframe alpha = 0    {all_end_zero}  ({:.1} %)",
+             100.0 * all_end_zero as f64 / all_el as f64);
+    println!("\n--- END (if this line is missing, the run did not finish) ---");
+}

crates/sylpheed-formats/examples/rest_fallback_census.rs

@@ -0,0 +1,77 @@
+//! When the resting-pose DWELL FALLBACK actually runs, does it pick a visible pose?
+//!
+//! `ui-resting-pose.md` argues the fallback is structurally unsound — the gap it
+//! maximises is time spent *interpolating*, so neither endpoint is held. Its one
+//! worked example, `GP_TITLE` build 7's `ptlogo_eff3.t32`, **no longer
+//! discriminates**: under the corrected keyframe-record layout the longest gap
+//! moved from `61→103` to `0→46`, and both ends of that are `a = 0`. The page's
+//! listing still shows the stale parser's trailing `-`.
+//!
+//! Losing the example is not the same as closing the question, so: disc-wide, how
+//! often does the fallback fire, and when it does, does it return something the
+//! player would see? An element resting at `a = 0` is harmless whichever end the
+//! rule lands on.
+//!
+//!     cargo run -p sylpheed-formats --example rest_fallback_census
+
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use std::path::PathBuf;
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let mut paks: Vec<PathBuf> = std::fs::read_dir(root.join("dat"))
+        .expect("dat/")
+        .filter_map(|e| e.ok().map(|e| e.path()))
+        .filter(|p| p.extension().is_some_and(|x| x == "pak"))
+        .collect();
+    paks.sort();
+
+    let (mut elements, mut plateau, mut fallback, mut fb_visible) = (0usize, 0, 0, 0);
+    let mut worst: Vec<(u32, String, String)> = Vec::new();
+    let mut per_pak: std::collections::BTreeMap<String, (usize, usize)> = Default::default();
+    for pak in &paks {
+        let Ok(ar) = PakArchive::open(pak) else { continue };
+        let name = pak.file_name().unwrap().to_string_lossy().to_string();
+        for (i, e) in ar.entries().iter().enumerate() {
+            let Ok(by) = ar.read(e) else { continue };
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            for el in &b.elements {
+                if el.keyframes.len() < 2 { continue }
+                elements += 1;
+                // a plateau is two ADJACENT poses that are equal — the same test
+                // the plateau path makes before the fallback can run
+                let has_plateau = el.keyframes.windows(2).any(|w| {
+                    w[0].x == w[1].x && w[0].y == w[1].y
+                        && w[0].scale_x == w[1].scale_x && w[0].scale_y == w[1].scale_y
+                        && w[0].fade == w[1].fade
+                });
+                if has_plateau { plateau += 1; continue }
+                fallback += 1;
+                per_pak.entry(name.clone()).or_default().0 += 1;
+                let Some(r) = el.rest() else { continue };
+                let a = (r.fade >> 24) & 0xff;
+                if a > 0 {
+                    fb_visible += 1;
+                    per_pak.entry(name.clone()).or_default().1 += 1;
+                    worst.push((a, name.clone(), format!("e{i}/{}", el.name)));
+                }
+            }
+        }
+    }
+    println!("POPULATION: {elements} elements with >= 2 keyframes, over {} archives", paks.len());
+    println!("COVERAGE:   {plateau} have a plateau (fallback never runs)");
+    println!("            {fallback} have NONE -> the dwell fallback decides");
+    println!("            {fb_visible} of those rest at alpha > 0 -- i.e. VISIBLE\n");
+    println!("PER ARCHIVE — fallback fires / of those, rests VISIBLE:");
+    let mut rows: Vec<_> = per_pak.into_iter().collect();
+    rows.sort_by(|a, b| b.1.1.cmp(&a.1.1));
+    for (pak, (fires, vis)) in &rows {
+        println!("   {pak:34} {fires:5} fires   {vis:5} visible");
+    }
+    println!();
+    worst.sort_by(|a, b| b.0.cmp(&a.0));
+    for (a, pak, el) in worst.iter().take(6) {
+        println!("   a={a:3}  {pak}  {el}");
+    }
+    println!("\n--- END OF CENSUS (if this line is missing, the run did not finish) ---");
+}

crates/sylpheed-formats/examples/rest_fallback_title.rs

@@ -0,0 +1,27 @@
+//! Which `GP_TITLE` elements does the resting-pose dwell fallback decide, and does
+//! it hand back a visible pose? The disc-wide census says 5 fires / 4 visible here.
+//!     cargo run -p sylpheed-formats --example rest_fallback_title
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use std::path::PathBuf;
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let ar = PakArchive::open(root.join("dat/GP_TITLE.pak")).expect("GP_TITLE");
+    for (i, e) in ar.entries().iter().enumerate() {
+        let Ok(by) = ar.read(e) else { continue };
+        let Some(b) = ui_layout::parse_build(&by) else { continue };
+        for el in &b.elements {
+            if el.keyframes.len() < 2 { continue }
+            if el.keyframes.windows(2).any(|w| w[0].x == w[1].x && w[0].y == w[1].y
+                && w[0].scale_x == w[1].scale_x && w[0].scale_y == w[1].scale_y
+                && w[0].fade == w[1].fade) { continue }
+            let Some(r) = el.rest() else { continue };
+            let a = (r.fade >> 24) & 0xff;
+            let ks: Vec<String> = el.keyframes.iter()
+                .map(|k| format!("{}:a{}", k.time.map(|v| v.to_string()).unwrap_or("-".into()), (k.fade >> 24) & 0xff))
+                .collect();
+            println!("entry {i:2}  {:24} rest a={a:3} t={:?}   [{}]{}",
+                     el.name, r.time, ks.join(" "),
+                     if a > 0 { "   <== VISIBLE" } else { "" });
+        }
+    }
+}

crates/sylpheed-formats/examples/rest_vs_settle.rs

@@ -0,0 +1,97 @@
+//! Should the settled pose come from each element's `rest()`, or from the
+//! **screen's** settle instant?
+//!
+//! Three iterations have measured how badly `rest()`'s dwell fallback behaves —
+//! 2 305 elements where it decides, 1 457 of them handed the element's *maximum*
+//! alpha, and by construction none of those poses is held. What has been missing
+//! is a proposal.
+//!
+//! `UiBuild::settle_time()` already exists: the midpoint of the longest
+//! keyframe-free interval **across the whole build**. That is the port agent's
+//! "re-key on the screen's span rather than the element's", and its shipped path
+//! poses `pose_at(hold)` and agrees with every capture it holds at 0.01 %.
+//!
+//! ⚠️ **Control first.** On elements where `rest()` is already sound — the plateau
+//! path, a pose the element genuinely holds — `pose_at(settle)` must AGREE. If it
+//! disagrees there, it is not a better rule, it is a different one.
+//!
+//! ⚠️ `ui-settle-time.md` records that 42 % of bundles have a settle window under
+//! 10 units and never settle at all. Bundles are split on that here rather than
+//! averaged over.
+//!
+//!     cargo run -p sylpheed-formats --example rest_vs_settle
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use std::path::PathBuf;
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let mut paks: Vec<PathBuf> = std::fs::read_dir(root.join("dat")).expect("dat/")
+        .filter_map(|e| e.ok().map(|e| e.path()))
+        .filter(|p| p.extension().is_some_and(|x| x == "pak")).collect();
+    paks.sort();
+    // control population (plateau) and test population (fallback), each split by
+    // whether the bundle settles at all
+    let (mut ctl_n, mut ctl_cov, mut ctl_agree) = (0usize, 0usize, 0usize);
+    let (mut fb_n, mut fb_rest_vis, mut fb_settle_vis) = (0usize, 0usize, 0usize);
+    let mut narrow = 0usize;
+    for pak in &paks {
+        let Ok(ar) = PakArchive::open(pak) else { continue };
+        for e in ar.entries() {
+            let Ok(by) = ar.read(e) else { continue };
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            let Some((lo, hi)) = b.settle_window() else { continue };
+            if hi - lo < 10 { narrow += 1; continue }   // this bundle never settles
+            let st = lo + (hi - lo) / 2;
+            for el in &b.elements {
+                if el.keyframes.len() < 2 { continue }
+                let plateau = el.keyframes.windows(2).any(|w| w[0].x == w[1].x
+                    && w[0].y == w[1].y && w[0].scale_x == w[1].scale_x
+                    && w[0].scale_y == w[1].scale_y && w[0].fade == w[1].fade);
+                let (Some(r), Some(s)) = (el.rest(), el.pose_at(st)) else { continue };
+                let (ra, sa) = ((r.fade >> 24) & 0xff, (s.fade >> 24) & 0xff);
+                if plateau {
+                    // ⚠️ The first version of this control compared EVERY plateau
+                    // element and got 46.6 % agreement — then I asked what that
+                    // means physically. `rest()` finds *a* held pose; many
+                    // elements hold one during the build-in and then move on.
+                    // `pose_at(settle)` asks what is on screen WHEN THE SCREEN HAS
+                    // SETTLED. Those are different questions, so disagreement
+                    // proves nothing. The fair control is the subset where the
+                    // held interval actually CONTAINS the settle instant.
+                    ctl_n += 1;
+                    let covers = el.keyframes.windows(2).any(|w| {
+                        let held = w[0].x == w[1].x && w[0].y == w[1].y
+                            && w[0].scale_x == w[1].scale_x
+                            && w[0].scale_y == w[1].scale_y && w[0].fade == w[1].fade;
+                        match (w[0].time, w[1].time) {
+                            (Some(a), Some(bb)) => held && a <= st && st <= bb,
+                            _ => false,
+                        }
+                    });
+                    if covers {
+                        ctl_cov += 1;
+                        if ra == sa && r.x == s.x && r.y == s.y
+                            && r.scale_x == s.scale_x && r.scale_y == s.scale_y { ctl_agree += 1 }
+                    }
+                } else {
+                    fb_n += 1;
+                    if ra > 0 { fb_rest_vis += 1 }
+                    if sa > 0 { fb_settle_vis += 1 }
+                }
+            }
+        }
+    }
+    println!("bundles skipped as never-settling (window < 10 units): {narrow}\n");
+    println!("CONTROL — elements where rest() takes the SOUND plateau path:");
+    println!("  {ctl_n} plateau elements in settling bundles");
+    println!("  {ctl_cov} of them HOLD ACROSS the settle instant — the fair control");
+    println!("  pose_at(settle) agrees with rest() on {ctl_agree} of those ({:.1} %)",
+             100.0 * ctl_agree as f64 / ctl_cov.max(1) as f64);
+    println!("\nTEST — elements where the unsound dwell fallback decides:");
+    println!("  {fb_n} elements");
+    println!("    rest()          returns a VISIBLE pose on {fb_rest_vis} ({:.1} %)",
+             100.0 * fb_rest_vis as f64 / fb_n.max(1) as f64);
+    println!("    pose_at(settle) returns a VISIBLE pose on {fb_settle_vis} ({:.1} %)",
+             100.0 * fb_settle_vis as f64 / fb_n.max(1) as f64);
+    println!("\n--- END (if this line is missing, the run did not finish) ---");
+}

crates/sylpheed-formats/examples/scale_census.rs

@@ -0,0 +1,48 @@
+//! Every scale value on the disc's UI, parents AND nested leaves.
+//!
+//! `DECISIONS.md` records `ptlogo_eff2` at 125 % as "the single drawn element in
+//! the whole export at a scale that is not a whole multiple of 100 %". That
+//! census was over parents only -- leaves were never opened. This opens them.
+use sylpheed_formats::{pak, ui_layout};
+use std::collections::BTreeMap;
+
+fn main() {
+    let path = std::env::args().nth(1).expect("pak");
+    let ar = pak::PakArchive::open(&path).expect("open");
+    let mut hist: BTreeMap<(u32, u32), Vec<String>> = BTreeMap::new();
+    let mut leaves_opened = 0usize;
+    for (i, e) in ar.entries().to_vec().iter().enumerate() {
+        let Ok(bytes) = ar.read(e) else { continue };
+        let Some(b) = ui_layout::parse_build(&bytes) else { continue };
+        for el in &b.elements {
+            for k in &el.keyframes {
+                hist.entry((k.scale_x, k.scale_y))
+                    .or_default()
+                    .push(format!("e{i}/{}", el.name));
+            }
+            if let Some(&(off, size)) = b.records.get(&el.name) {
+                if let Some(lb) = ui_layout::parse_build(&bytes[off..off + size]) {
+                    leaves_opened += 1;
+                    for le in &lb.elements {
+                        for k in &le.keyframes {
+                            hist.entry((k.scale_x, k.scale_y))
+                                .or_default()
+                                .push(format!("e{i}/{}->LEAF/{}", el.name, le.name));
+                        }
+                    }
+                }
+            }
+        }
+    }
+    println!("{leaves_opened} leaves opened\n");
+    println!("{:>12} {:>7}  examples", "scale", "count");
+    for (k, v) in &hist {
+        let mut ex: Vec<&String> = v.iter().collect();
+        ex.sort(); ex.dedup();
+        let odd = k.0 % 100 != 0 || k.1 % 100 != 0;
+        println!("{}{:>5},{:<5} {:>7}  {}", if odd { "* " } else { "  " },
+                 k.0, k.1, v.len(),
+                 ex.iter().take(3).map(|s| s.as_str()).collect::<Vec<_>>().join(", "));
+    }
+    println!("\n* = not a whole multiple of 100%");
+}

crates/sylpheed-formats/examples/settle_midramp_census.rs

@@ -0,0 +1,75 @@
+//! How often does posing at the SCREEN's settle instant catch an element
+//! mid-ramp? The adversarial census of my own proposal.
+//!
+//! The port agent found `ptmsg` — the main menu's footer — at alpha **127.5 of
+//! 255** at that screen's settle instant, because the longest keyframe-free
+//! interval ends exactly as the footer starts to arrive. `screen render --settle`
+//! already prints "⚠️ narrow — this bundle may never settle" there: the window is
+//! **12 units**.
+//!
+//! ⚠️ **And my `rest_vs_settle` filter was too permissive**: it dropped bundles
+//! with a window under 10 units, so a 12-unit window passed while the tool itself
+//! was flagging it. This splits by width instead of picking one cutoff.
+//!
+//! "Mid-ramp" = at the settle instant the element sits strictly inside an interval
+//! whose two endpoint poses DIFFER — it is interpolating, not held.
+//!
+//!     cargo run -p sylpheed-formats --example settle_midramp_census
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use std::path::PathBuf;
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let mut paks: Vec<PathBuf> = std::fs::read_dir(root.join("dat")).expect("dat/")
+        .filter_map(|e| e.ok().map(|e| e.path()))
+        .filter(|p| p.extension().is_some_and(|x| x == "pak")).collect();
+    paks.sort();
+    // buckets by settle-window width
+    let edges = [0u32, 10, 20, 30, 60, u32::MAX];
+    let names = ["< 10", "10–19", "20–29", "30–59", ">= 60"];
+    let mut els = [0usize; 5];
+    let mut mid = [0usize; 5];
+    let mut bundles = [0usize; 5];
+    for pak in &paks {
+        let Ok(ar) = PakArchive::open(pak) else { continue };
+        for e in ar.entries() {
+            let Ok(by) = ar.read(e) else { continue };
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            let Some((lo, hi)) = b.settle_window() else { continue };
+            let w = hi - lo;
+            let bi = edges.windows(2).position(|p| w >= p[0] && w < p[1]).unwrap_or(4);
+            bundles[bi] += 1;
+            let st = lo + w / 2;
+            for el in &b.elements {
+                let k = &el.keyframes;
+                if k.len() < 2 { continue }
+                els[bi] += 1;
+                // the interval containing the settle instant
+                let mut interpolating = false;
+                for pair in k.windows(2) {
+                    if let (Some(t0), Some(t1)) = (pair[0].time, pair[1].time) {
+                        if t0 <= st && st <= t1 && t0 != t1 {
+                            let same = pair[0].fade == pair[1].fade
+                                && pair[0].x == pair[1].x && pair[0].y == pair[1].y
+                                && pair[0].scale_x == pair[1].scale_x
+                                && pair[0].scale_y == pair[1].scale_y;
+                            if !same && st != t0 && st != t1 { interpolating = true }
+                            break;
+                        }
+                    }
+                }
+                if interpolating { mid[bi] += 1 }
+            }
+        }
+    }
+    println!("{:8}{:>10}{:>10}{:>12}{:>10}", "window", "bundles", "elements", "mid-ramp", "share");
+    for i in 0..5 {
+        if els[i] == 0 { continue }
+        println!("{:8}{:>10}{:>10}{:>12}{:>9.1}%", names[i], bundles[i], els[i], mid[i],
+                 100.0 * mid[i] as f64 / els[i] as f64);
+    }
+    let te: usize = els.iter().sum(); let tm: usize = mid.iter().sum();
+    println!("{:8}{:>10}{:>10}{:>12}{:>9.1}%", "ALL", bundles.iter().sum::<usize>(), te, tm,
+             100.0 * tm as f64 / te as f64);
+    println!("\n--- END (if this line is missing, the run did not finish) ---");
+}

crates/sylpheed-formats/examples/settle_narrow_rate.rs

@@ -0,0 +1,49 @@
+//! What share of bundles have a NARROW settle window -- and of WHICH bundles?
+//!
+//! `screen render --settle`'s help says "a narrow one means the bundle never
+//! settles (42 % of them, mostly `loop*` fragments)". The 42 % is correct and is
+//! stated precisely in ui-settle-time.md: 731 of **1 758 composable bundles
+//! carrying two or more keyframe times**. But inside `screen render`, "them"
+//! reads as the bundles you would render -- the SCREEN BUILDS -- which is a
+//! different and much smaller population. This computes both.
+//!
+//!     cargo run -p sylpheed-formats --example settle_narrow_rate
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use std::path::PathBuf;
+
+fn main() {
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let mut paks: Vec<PathBuf> = std::fs::read_dir(root.join("dat")).expect("dat/")
+        .filter_map(|e| e.ok().map(|e| e.path()))
+        .filter(|p| p.extension().is_some_and(|x| x == "pak")).collect();
+    paks.sort();
+    // (with >=2 keyframe times, narrow) for each population
+    let (mut b2, mut bn) = (0usize, 0usize);   // screen builds  (is_build)
+    let (mut c2, mut cn) = (0usize, 0usize);   // composable      (is_composable)
+    for pak in &paks {
+        let Ok(ar) = PakArchive::open(pak) else { continue };
+        for e in ar.entries() {
+            let Ok(by) = ar.read(e) else { continue };
+            let is_b = ui_layout::is_build(&by);
+            let is_c = ui_layout::is_composable(&by);
+            if !is_b && !is_c { continue }
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            let mut ts: Vec<u32> = b.elements.iter()
+                .flat_map(|el| el.keyframes.iter().filter_map(|k| k.time)).collect();
+            ts.sort_unstable(); ts.dedup();
+            if ts.len() < 2 { continue }
+            let narrow = match b.settle_window() { Some((lo, hi)) => hi - lo < 10, None => true };
+            if is_b { b2 += 1; if narrow { bn += 1 } }
+            if is_c { c2 += 1; if narrow { cn += 1 } }
+        }
+    }
+    println!("population                                        n     narrow (<10 u)   share");
+    println!("SCREEN BUILDS (is_build, what `screen render` renders by default)");
+    println!("                                              {b2:5}   {bn:9}      {:.0} %",
+             100.0 * bn as f64 / b2.max(1) as f64);
+    println!("COMPOSABLE bundles (is_composable, what --all admits)");
+    println!("                                              {c2:5}   {cn:9}      {:.0} %",
+             100.0 * cn as f64 / c2.max(1) as f64);
+    println!("\nui-settle-time.md quotes 731 / 1758 = 42 % over composable bundles.");
+    println!("--- END ---");
+}

crates/sylpheed-formats/examples/settle_window.rs

@@ -0,0 +1,31 @@
+// The settled screen, computed from the keyframe times alone.
+//
+// `rest()` picks each element's last HOLD keyframe independently, which is right
+// for an element that ends settled and wrong for a transient: a 2-frame flash
+// holds at its PEAK, so `rest()` leaves it burning forever. The settled screen is
+// instead one INSTANT that every element is posed at, and the instant to pick is
+// inside the longest interval during which no element has a keyframe at all.
+use sylpheed_formats::{pak, ui_layout};
+fn main(){
+    let mut a=std::env::args().skip(1);
+    let pk=a.next().unwrap();
+    let ar=pak::PakArchive::open(&pk).unwrap();
+    let only:Option<usize>=a.next().and_then(|s|s.parse().ok());
+    for (i,e) in ar.entries().iter().enumerate() {
+        if let Some(o)=only { if o!=i { continue } }
+        let Ok(by)=ar.read(e) else { continue };
+        let Some(b)=ui_layout::parse_build(&by) else { continue };
+        if b.elements.len()<2 { continue }
+        let mut ts:Vec<u32>=b.elements.iter().flat_map(|el|
+            el.keyframes.iter().filter_map(|k|k.time)).collect();
+        if ts.len()<2 { continue }
+        ts.sort_unstable(); ts.dedup();
+        // longest gap between consecutive keyframe times
+        let (mut best,mut lo,mut hi)=(0u32,0u32,0u32);
+        for w in ts.windows(2) {
+            if w[1]-w[0] > best { best=w[1]-w[0]; lo=w[0]; hi=w[1]; }
+        }
+        println!("{:>4}  {:<28} times {:>3}  span {:>4}  settle window [{lo},{hi}] = {best} units ({:.2}s)  -> t={}",
+                 i, format!("{:08x}",e.name_hash), ts.len(), ts.last().unwrap(), best as f64/60.0, lo+best/2);
+    }
+}

crates/sylpheed-formats/examples/settle_window_check.rs

@@ -0,0 +1,27 @@
+//! Where does `settle_window()`'s answer come from? The port agent recomputes the
+//! publisher splash's widest keyframe-free gap as 190 units; `--settle` reports 8.
+//! One of the two readings is wrong and the file settles it.
+//!     cargo run -p sylpheed-formats --example settle_window_check -- <build>
+use sylpheed_formats::{pak::PakArchive, ui_layout};
+use std::path::PathBuf;
+fn main() {
+    let b: usize = std::env::args().nth(1).unwrap_or("10".into()).parse().unwrap();
+    let root = PathBuf::from(std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC"));
+    let ar = PakArchive::open(root.join("dat/GP_TITLE.pak")).expect("GP_TITLE");
+    let by = ar.read(&ar.entries()[b]).expect("entry");
+    let build = ui_layout::parse_build(&by).expect("parse");
+    println!("entry {b}: {} elements", build.elements.len());
+    for el in &build.elements {
+        let ts: Vec<String> = el.keyframes.iter()
+            .map(|k| k.time.map(|v| v.to_string()).unwrap_or("-".into())).collect();
+        println!("   {:26} [{}]", el.name, ts.join(" "));
+    }
+    let mut ts: Vec<u32> = build.elements.iter()
+        .flat_map(|e| e.keyframes.iter().filter_map(|k| k.time)).collect();
+    ts.sort_unstable(); ts.dedup();
+    println!("\nunion of all element keyframe times: {ts:?}");
+    let gaps: Vec<(u32,u32,u32)> = ts.windows(2).map(|w| (w[1]-w[0], w[0], w[1])).collect();
+    let mut g = gaps.clone(); g.sort_by(|a,b| b.0.cmp(&a.0));
+    println!("widest gaps: {:?}", &g[..g.len().min(4)]);
+    println!("settle_window() reports {:?}", build.settle_window());
+}

crates/sylpheed-formats/examples/sprite_dims.rs

@@ -0,0 +1,12 @@
+use sylpheed_formats::{pak, ui_layout, t8ad};
+fn main(){
+    let mut a=std::env::args().skip(1);
+    let pk=a.next().unwrap(); let i:usize=a.next().unwrap().parse().unwrap();
+    let ar=pak::PakArchive::open(pk).unwrap();
+    let by=ar.read(&ar.entries()[i]).unwrap();
+    let b=ui_layout::parse_build(&by).unwrap();
+    let mut v:Vec<(String,u32,u32)>=b.sprites.iter().filter_map(|(n,&(o,s))|{
+        let im=t8ad::parse(&by[o..o+s])?; Some((n.clone(),im.width,im.height))}).collect();
+    v.sort();
+    for (n,w,h) in v { println!("  {w:>5} x {h:<5}  {n}"); }
+}

crates/sylpheed-formats/examples/sprite_of.rs

@@ -0,0 +1,9 @@
+use sylpheed_formats::{pak, ui_layout};
+fn main(){
+    let ar=pak::PakArchive::open(std::env::args().nth(1).unwrap()).unwrap();
+    let b=ui_layout::parse_build(&ar.read(&ar.entries()[4]).unwrap()).unwrap();
+    for el in b.elements.iter().filter(|e| e.name.contains("ptloop")||e.name.contains("ptbtn")) {
+        println!("{:<18} sprite={:?}  has_leaf={}", el.name, el.sprite,
+                 b.records.contains_key(&el.name));
+    }
+}

crates/sylpheed-formats/examples/tie_break_pixel_cost.rs

@@ -0,0 +1,332 @@
+//! What does the unknown paint-order TIE-BREAK actually cost, in pixels?
+//!
+//! `ui-paint-order-derived-check.md` bounds *where* a wrong tie-break could
+//! show — 24 overlapping tied pairs across `GP_TITLE` — and says outright that
+//! nobody has measured how many of them change a pixel. Overlap is an upper
+//! bound: two elements can overlap and still composite identically in either
+//! order, if either is transparent where they meet.
+//!
+//! This renders each screen twice — once in the order `compose` derives, once
+//! with one tied pair swapped — and counts the pixels that differ. Same-key
+//! elements are contiguous in the derived order (a stable sort by `(key, i)`),
+//! so swapping two of them paints nothing else in between: the diff is the
+//! tie-break's cost and nothing else.
+//!
+//! Every entry also runs a CONTROL: a swap of two OVERLAPPING elements with
+//! DIFFERENT keys, i.e. a pair whose order the game is known to care about. If
+//! the control diff is zero the instrument cannot see a reorder on this screen
+//! and its zeros mean nothing.
+//!
+//!     cargo run -p sylpheed-formats --example tie_break_pixel_cost -- <GP_TITLE.pak>
+use sylpheed_formats::{pak, ui_layout};
+use ui_layout::{ComposeOptions, UiBuild};
+
+/// Pixels that differ, and the largest per-channel difference.
+fn diff(a: &[u8], b: &[u8]) -> (usize, u8) {
+    let (mut n, mut worst) = (0usize, 0u8);
+    for (pa, pb) in a.chunks_exact(4).zip(b.chunks_exact(4)) {
+        if pa != pb {
+            n += 1;
+            for k in 0..4 {
+                worst = worst.max(pa[k].abs_diff(pb[k]));
+            }
+        }
+    }
+    (n, worst)
+}
+
+/// Where does element `ei` actually put ink? Render with it and without it;
+/// the pixels that move are the ones it paints. This is what turns a bare
+/// "0 px differ" into an explained one: bounding boxes can overlap while the
+/// sprites inside them never touch the same pixel.
+fn ink_mask(
+    build: &UiBuild,
+    bundle: &[u8],
+    opts: ComposeOptions,
+    order: &[usize],
+    base: &[u8],
+    ei: usize,
+) -> Vec<bool> {
+    let n_el = build.elements.iter().map(|e| e.index).max().unwrap_or(0) + 1;
+    let mut vis = vec![true; n_el.max(build.elements.len())];
+    vis[build.elements[ei].index] = false;
+    let without = ui_layout::compose_with_order(build, bundle, opts, Some(&vis), Some(order));
+    base.chunks_exact(4)
+        .zip(without.rgba.chunks_exact(4))
+        .map(|(x, y)| x != y)
+        .collect()
+}
+
+fn swapped(order: &[usize], a: usize, b: usize) -> Vec<usize> {
+    let mut o = order.to_vec();
+    let (pa, pb) = (
+        o.iter().position(|&e| e == a).unwrap(),
+        o.iter().position(|&e| e == b).unwrap(),
+    );
+    o.swap(pa, pb);
+    o
+}
+
+/// The element's on-screen rect, the same approximation the tie census uses:
+/// the declared pivot doubled, placed at the keyframe. `at` selects the pose —
+/// `None` is `rest()`, which is where the original census was computed.
+///
+/// 🔴 An element that is TRANSPARENT at the chosen pose gets no rect at all. A
+/// tie involving something invisible cannot cost a pixel, and counting it as an
+/// overlap is what made the original census an upper bound rather than a cost.
+fn rect(e: &ui_layout::Element, at: Option<u32>) -> Option<(i32, i32, i32, i32)> {
+    let kf = match at {
+        Some(t) => e.pose_at(t)?,
+        None => e.rest()?.clone(),
+    };
+    if kf.fade >> 24 == 0 || kf.scale_x == 0 || kf.scale_y == 0 {
+        return None;
+    }
+    let (w, h) = ((e.pivot_x * 2) as i32, (e.pivot_y * 2) as i32);
+    if w == 0 || h == 0 {
+        return None;
+    }
+    Some((kf.x, kf.y, w, h))
+}
+
+fn overlaps(a: &ui_layout::Element, b: &ui_layout::Element, at: Option<u32>) -> bool {
+    let (Some(ra), Some(rb)) = (rect(a, at), rect(b, at)) else {
+        return false;
+    };
+    (ra.0 + ra.2).min(rb.0 + rb.2) - ra.0.max(rb.0) > 0
+        && (ra.1 + ra.3).min(rb.1 + rb.3) - ra.1.max(rb.1) > 0
+}
+
+struct Case {
+    name: &'static str,
+    opts: ComposeOptions,
+}
+
+fn cases() -> Vec<Case> {
+    vec![
+        Case {
+            name: "default (what `screen render` draws)",
+            opts: ComposeOptions {
+                backdrop: [0, 0, 0, 255],
+                ..Default::default()
+            },
+        },
+        Case {
+            name: "everything on (focus+animated+primitives)",
+            opts: ComposeOptions {
+                include_focus: true,
+                include_animated: true,
+                include_primitives: true,
+                backdrop: [0, 0, 0, 255],
+                ..Default::default()
+            },
+        },
+        // 🔴 The two cases above pose at `rest()`, which is each element's last
+        // hold picked independently — so they draw transients that the settled
+        // screen does not have (`docs/re/structures/ui-settle-time.md`). A tie
+        // between two elements that are transparent at the settle time cannot
+        // cost a pixel on the screen the player sees, however much their rects
+        // overlap at rest. `at` is filled in per entry.
+        Case {
+            name: "AT THE SETTLE TIME (what the player sees)",
+            opts: ComposeOptions {
+                backdrop: [0, 0, 0, 255],
+                at: Some(0), // replaced per entry
+                ..Default::default()
+            },
+        },
+    ]
+}
+
+fn tied_overlapping_pairs(build: &UiBuild, bytes: &[u8], at: Option<u32>) -> Vec<(usize, usize, u32)> {
+    let keys: Vec<u32> = build
+        .elements
+        .iter()
+        .map(|e| ui_layout::sprite_layer_key(build, bytes, e).unwrap_or(u32::MAX))
+        .collect();
+    let mut out = Vec::new();
+    for a in 0..keys.len() {
+        for b in (a + 1)..keys.len() {
+            if keys[a] != keys[b] || keys[a] == u32::MAX {
+                continue;
+            }
+            if overlaps(&build.elements[a], &build.elements[b], at) {
+                out.push((a, b, keys[a]));
+            }
+        }
+    }
+    out
+}
+
+/// A pair the game's own order DOES separate: overlapping, different keys.
+/// Used as the control — swapping it must move pixels.
+fn control_pair(build: &UiBuild, bytes: &[u8], at: Option<u32>) -> Option<(usize, usize)> {
+    let keys: Vec<u32> = build
+        .elements
+        .iter()
+        .map(|e| ui_layout::sprite_layer_key(build, bytes, e).unwrap_or(u32::MAX))
+        .collect();
+    let mut best: Option<(i64, usize, usize)> = None;
+    for a in 0..keys.len() {
+        for b in (a + 1)..keys.len() {
+            if keys[a] == keys[b] || keys[a] == u32::MAX || keys[b] == u32::MAX {
+                continue;
+            }
+            if !overlaps(&build.elements[a], &build.elements[b], at) {
+                continue;
+            }
+            let (ra, rb) = (rect(&build.elements[a], at)?, rect(&build.elements[b], at)?);
+            let ox = ((ra.0 + ra.2).min(rb.0 + rb.2) - ra.0.max(rb.0)) as i64;
+            let oy = ((ra.1 + ra.3).min(rb.1 + rb.3) - ra.1.max(rb.1)) as i64;
+            let area = ox * oy;
+            if best.map_or(true, |(x, _, _)| area > x) {
+                best = Some((area, a, b));
+            }
+        }
+    }
+    best.map(|(_, a, b)| (a, b))
+}
+
+fn main() {
+    let path = std::env::args()
+        .nth(1)
+        .expect("usage: tie_break_pixel_cost <pak>");
+    let ar = pak::PakArchive::open(&path).expect("open pak");
+    let entries: Vec<_> = ar.entries().to_vec();
+    println!("# tie-break pixel cost — {path}\n");
+    let mut totals = (0usize, 0usize, 0usize); // pairs, changed-a-pixel, controls-dead
+    for (i, e) in entries.iter().enumerate() {
+        let Ok(bytes) = ar.read(e) else { continue };
+        let Some(build) = ui_layout::parse_build(&bytes) else {
+            continue;
+        };
+        // The census pairs are still computed at rest, so the report can say
+        // how many of THOSE survive posing at the settle time.
+        let pairs_at_rest = tied_overlapping_pairs(&build, &bytes, None);
+        if pairs_at_rest.is_empty() {
+            continue;
+        }
+        let settle = build.settle_time();
+        println!(
+            "entry {i:2}  {} elements  {} overlapping tied pair(s) at rest{}",
+            build.elements.len(),
+            pairs_at_rest.len(),
+            match (settle, build.settle_window()) {
+                (Some(t), Some((lo, hi))) => format!("  settle t={t} (window {} units)", hi - lo),
+                _ => "  NO SETTLE WINDOW".to_string(),
+            }
+        );
+        let derived = ui_layout::derived_paint_order(&build, &bytes);
+        for mut c in cases() {
+            // The settle case is a no-op on a bundle that never settles.
+            if c.opts.at.is_some() {
+                match settle {
+                    Some(t) => c.opts.at = Some(t),
+                    None => {
+                        println!("  [{}] SKIPPED: no settle window", c.name);
+                        continue;
+                    }
+                }
+            }
+            let pairs = tied_overlapping_pairs(&build, &bytes, c.opts.at);
+            if pairs.len() != pairs_at_rest.len() {
+                println!(
+                    "  [{}] 🔴 {} of the {} tied pairs are GONE at this pose (an element is \
+transparent or collapsed there) — they cannot cost a pixel",
+                    c.name,
+                    pairs_at_rest.len() - pairs.len(),
+                    pairs_at_rest.len()
+                );
+            }
+            let base = ui_layout::compose_with_order(&build, &bytes, c.opts, None, Some(&derived));
+            let drawn: std::collections::HashSet<usize> = base.drawn.iter().copied().collect();
+            // Control first. An instrument that cannot see a reorder it is
+            // supposed to see makes every zero below meaningless.
+            let ctrl = match control_pair(&build, &bytes, c.opts.at) {
+                Some((a, b)) if drawn.contains(&a) && drawn.contains(&b) => {
+                    let alt = ui_layout::compose_with_order(
+                        &build,
+                        &bytes,
+                        c.opts,
+                        None,
+                        Some(&swapped(&derived, a, b)),
+                    );
+                    let (n, w) = diff(&base.rgba, &alt.rgba);
+                    Some((a, b, n, w))
+                }
+                _ => None,
+            };
+            match ctrl {
+                Some((a, b, n, w)) if n > 0 => println!(
+                    "  [{}] CONTROL ok: swapping [{a}] {} x [{b}] {} moves {n} px (max Δ {w})",
+                    c.name, build.elements[a].name, build.elements[b].name
+                ),
+                Some((a, b, _, _)) => {
+                    totals.2 += 1;
+                    println!(
+                        "  [{}] CONTROL DEAD: swapping [{a}] {} x [{b}] {} changes NOTHING — \
+zeros below are uninterpretable",
+                        c.name, build.elements[a].name, build.elements[b].name
+                    )
+                }
+                None => {
+                    totals.2 += 1;
+                    println!(
+                        "  [{}] CONTROL UNAVAILABLE: no overlapping different-key pair is drawn",
+                        c.name
+                    )
+                }
+            }
+            for &(a, b, key) in &pairs {
+                let both_drawn = drawn.contains(&a) && drawn.contains(&b);
+                if !both_drawn {
+                    println!(
+                        "  [{}] [{a}] {} x [{b}] {} (key {key}): NOT BOTH DRAWN — unreachable here",
+                        c.name, build.elements[a].name, build.elements[b].name
+                    );
+                    continue;
+                }
+                let alt = ui_layout::compose_with_order(
+                    &build,
+                    &bytes,
+                    c.opts,
+                    None,
+                    Some(&swapped(&derived, a, b)),
+                );
+                let (n, w) = diff(&base.rgba, &alt.rgba);
+                let total = (base.width as usize) * (base.height as usize);
+                // Explain the number: how many pixels do the two BOTH paint on?
+                // A zero with a large shared-ink count is a real "order does
+                // not matter here"; a zero with no shared ink means the
+                // bounding boxes overlapped and the sprites did not.
+                let ma = ink_mask(&build, &bytes, c.opts, &derived, &base.rgba, a);
+                let mb = ink_mask(&build, &bytes, c.opts, &derived, &base.rgba, b);
+                let shared = ma.iter().zip(&mb).filter(|(x, y)| **x && **y).count();
+                let (ia, ib) = (
+                    ma.iter().filter(|x| **x).count(),
+                    mb.iter().filter(|x| **x).count(),
+                );
+                println!(
+                    "  [{}] [{a}] {} x [{b}] {} (key {key}): {n} px differ ({:.4}% of frame), \
+max Δ {w}  | ink {ia} / {ib} px, shared {shared} px",
+                    c.name,
+                    build.elements[a].name,
+                    build.elements[b].name,
+                    100.0 * n as f64 / total as f64
+                );
+                if c.name.starts_with("default") {
+                    totals.0 += 1;
+                    if n > 0 {
+                        totals.1 += 1;
+                    }
+                }
+            }
+        }
+        println!();
+    }
+    println!(
+        "default-options summary: {} of {} overlapping tied pairs change at least one pixel; \
+{} dead/unavailable controls",
+        totals.1, totals.0, totals.2
+    );
+}

crates/sylpheed-formats/examples/tie_cost_over_time.rs

@@ -0,0 +1,76 @@
+//! How many tied pairs can cost a pixel, as a function of TIME?
+//!
+//! `tie_break_pixel_cost` answers "at one pose". That leaves the answer looking
+//! like it might be a knife-edge: pick a different instant and the count could
+//! jump. This sweeps every keyframe time in the bundle and reports, per entry,
+//! how many same-key pairs are simultaneously **opaque, non-collapsed and
+//! overlapping** — the pairs whose order could possibly matter at that instant.
+//!
+//! The instrument's control is built in: the count at t=0 (nothing has faded in)
+//! and the count at rest must bracket it, and an entry whose count is flat at
+//! zero for the whole sweep would be suspicious rather than reassuring — so the
+//! peak is printed too.
+use sylpheed_formats::{pak, ui_layout};
+use ui_layout::UiBuild;
+
+fn rect(e: &ui_layout::Element, t: u32) -> Option<(i32, i32, i32, i32)> {
+    let kf = e.pose_at(t)?;
+    if kf.fade >> 24 == 0 || kf.scale_x == 0 || kf.scale_y == 0 {
+        return None;
+    }
+    let (w, h) = ((e.pivot_x * 2) as i32, (e.pivot_y * 2) as i32);
+    if w == 0 || h == 0 { return None; }
+    Some((kf.x, kf.y, w, h))
+}
+
+fn live_pairs(b: &UiBuild, bytes: &[u8], keys: &[u32], t: u32) -> usize {
+    let mut n = 0;
+    for a in 0..keys.len() {
+        for c in (a + 1)..keys.len() {
+            if keys[a] != keys[c] || keys[a] == u32::MAX { continue }
+            let (Some(ra), Some(rb)) = (rect(&b.elements[a], t), rect(&b.elements[c], t)) else { continue };
+            if (ra.0 + ra.2).min(rb.0 + rb.2) - ra.0.max(rb.0) > 0
+                && (ra.1 + ra.3).min(rb.1 + rb.3) - ra.1.max(rb.1) > 0 { n += 1 }
+        }
+    }
+    n
+}
+
+fn main() {
+    let path = std::env::args().nth(1).expect("usage: tie_cost_over_time <pak>");
+    let ar = pak::PakArchive::open(&path).expect("open pak");
+    println!("# tied pairs that could cost a pixel, over time — {path}\n");
+    for (i, e) in ar.entries().to_vec().iter().enumerate() {
+        let Ok(by) = ar.read(e) else { continue };
+        let Some(b) = ui_layout::parse_build(&by) else { continue };
+        let keys: Vec<u32> = b.elements.iter()
+            .map(|el| ui_layout::sprite_layer_key(&b, &by, el).unwrap_or(u32::MAX)).collect();
+        let mut ts: Vec<u32> = b.elements.iter()
+            .flat_map(|el| el.keyframes.iter().filter_map(|k| k.time)).collect();
+        ts.sort_unstable(); ts.dedup();
+        if ts.len() < 2 { continue }
+        let last = *ts.last().unwrap();
+        // sample every keyframe time AND every midpoint between them
+        let mut samples: Vec<u32> = ts.clone();
+        for w in ts.windows(2) { samples.push(w[0] + (w[1] - w[0]) / 2); }
+        samples.sort_unstable(); samples.dedup();
+        let counts: Vec<(u32, usize)> =
+            samples.iter().map(|&t| (t, live_pairs(&b, &by, &keys, t))).collect();
+        let peak = counts.iter().map(|&(_, n)| n).max().unwrap_or(0);
+        if peak == 0 { continue }
+        let Some((lo, hi)) = b.settle_window() else { continue };
+        let st = b.settle_time().unwrap();
+        let at_settle = live_pairs(&b, &by, &keys, st);
+        // the whole plateau, not just its midpoint
+        let plateau: Vec<usize> =
+            (lo..=hi).step_by(((hi - lo).max(1) / 8).max(1) as usize)
+                .map(|t| live_pairs(&b, &by, &keys, t)).collect();
+        let pmax = plateau.iter().copied().max().unwrap_or(0);
+        println!("entry {i:2}  peak {peak} live pair(s) over t=0..{last}   \
+settle window [{lo},{hi}]  at t={st}: {at_settle}   ACROSS THE WHOLE WINDOW: max {pmax}");
+        let busy: Vec<String> = counts.iter().filter(|&&(_, n)| n > 0)
+            .map(|&(t, n)| format!("t{t}:{n}")).collect();
+        if busy.len() <= 24 { println!("      live only at  {}", busy.join(" ")); }
+        else { println!("      live at {} of {} sampled instants", busy.len(), counts.len()); }
+    }
+}

crates/sylpheed-formats/examples/voice_region_cap_sweep.rs

@@ -0,0 +1,71 @@
+//! Is raising the start filter's 1.5 MB cap safe, disc-wide?
+//!
+//! `voice_region_fix_test.rs` shows that for `ADV` the predecessor start recovers
+//! the decoder's own three byte_sizes exactly. But the cap exists to protect a
+//! case: the code says *"only within one bank (~1.5 MB), else this is the first cue
+//! in its block and the audio starts at the anchor itself"*. Raising it blindly
+//! could pull a **previous asset's** streams into the region.
+//!
+//! So compare, per movie: the chunk list the resolver gives today against the one
+//! the predecessor start gives. A safe change makes the FIRST chunk bigger and
+//! leaves the rest identical. An unsafe one adds leading chunks.
+//!
+//!     cargo run -p sylpheed-formats --example voice_region_cap_sweep
+
+use sylpheed_formats::hash::name_hash;
+use sylpheed_formats::media::{DirectorySource, DiscSource};
+use sylpheed_formats::pak::PakArchive;
+use sylpheed_formats::slb::{self, VoiceLang};
+use sylpheed_formats::{movie_manifest, movie_voice};
+
+fn main() {
+    let disc = std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC");
+    let src = DirectorySource::new(std::path::PathBuf::from(&disc));
+    let code = VoiceLang::English.code_pub();
+    let tpak = src.open_pak("dat/tables.pak").expect("tables.pak");
+    let manifest = tpak.entries().iter()
+        .find_map(|e| tpak.read(e).ok().filter(|b| movie_manifest::is_manifest(b)))
+        .expect("manifest");
+    let marker = format!("{code}\\Movie\\VOICE_ADV.slb");
+    let registry = tpak.entries().iter().find_map(|e| {
+        tpak.read(e).ok().filter(|b| b.windows(marker.len()).any(|w| w == marker.as_bytes()))
+    }).expect("registry");
+    let ids = movie_voice::registry_voice_ids(&registry);
+    let stoc = src.read_file("dat/sound.pak").expect("sound.pak");
+    let entries = PakArchive::parse_toc(&stoc).expect("toc");
+
+    let (mut same, mut grew, mut extra, mut skip) = (0, 0, 0, 0);
+    for m in movie_manifest::parse(&manifest) {
+        let movie = m.movie;
+        let Some(token) = movie_manifest::voice_token(&manifest, &movie) else { skip += 1; continue };
+        let Some(&id) = ids.get(&token) else { skip += 1; continue };
+        let Some(anchor) = ["Movie","etc","Voice"].iter().find_map(|dir| {
+            let h = name_hash(&format!("{code}\\{dir}\\{token}.slb"));
+            entries.binary_search_by_key(&h, |e| e.name_hash).ok().map(|i| entries[i].offset as u64)
+        }) else { skip += 1; continue };
+        let win_start = anchor.saturating_sub(2*1024*1024) & !3;
+        let Ok(window) = src.read_segment_range("dat/sound", win_start, 8*1024*1024) else { skip += 1; continue };
+        let Some(end_local) = movie_voice::find_descriptor(&window, id) else { skip += 1; continue };
+        let end = win_start + end_local as u64;
+        let cand = movie_voice::find_descriptor(&window, id.wrapping_sub(1))
+            .or_else(|| movie_voice::find_descriptor_before(&window, end_local))
+            .map(|o| win_start + o as u64)
+            .filter(|&s| s < end);
+        let today = cand.filter(|&s| end - s < 1_500_000).unwrap_or(anchor);
+        let Some(proposed) = cand else { skip += 1; continue };
+        if today == proposed { same += 1; continue }
+        let sizes = |s: u64| -> Vec<usize> {
+            src.read_segment_range("dat/sound", s, (end - s) as usize)
+                .map(|b| slb::to_xma_riffs(&b).iter().map(|r| r.len() - 60).collect())
+                .unwrap_or_default()
+        };
+        let (a, b) = (sizes(today), sizes(proposed));
+        let tail_same = a.len() == b.len() && a.iter().skip(1).eq(b.iter().skip(1));
+        let verdict = if a.len() == b.len() && tail_same && b[0] > a[0] {
+            grew += 1; "first chunk GREW, tail identical"
+        } else if b.len() > a.len() { extra += 1; "EXTRA leading chunks" }
+        else { extra += 1; "changed otherwise" };
+        println!("{movie:10} today {a:?}\n{:10} prop  {b:?}   {verdict}", "");
+    }
+    println!("\nunchanged {same}   fixed-cleanly {grew}   would-break {extra}   skipped {skip}");
+}

crates/sylpheed-formats/examples/voice_region_chunk_census.rs

@@ -0,0 +1,50 @@
+//! How many voice regions hold three chunks? A COUNT, stated with its population.
+//!
+//! `voice-region-starts-late.md` published "8 of 10 three-chunk regions start
+//! mid-stream". The port agent counts **25** three-chunk regions. Mine was not a
+//! count: the audit that produced it was cut short and I read a partial file as a
+//! complete one — it ends mid-list with no summary line.
+//!
+//! This does the cheap half properly. It does not step backwards looking for the
+//! clip; it resolves each region once and counts its chunks, and it prints the
+//! population, the coverage and the skips **in the same output** so a truncated run
+//! cannot be mistaken for a complete one.
+//!
+//!     cargo run -p sylpheed-formats --example voice_region_chunk_census
+
+use sylpheed_formats::media::{self, DirectorySource, DiscSource};
+use sylpheed_formats::movie_manifest;
+use sylpheed_formats::slb::{self, VoiceLang};
+use std::collections::BTreeMap;
+
+fn main() {
+    let disc = std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC");
+    let src = DirectorySource::new(std::path::PathBuf::from(&disc));
+    let tpak = src.open_pak("dat/tables.pak").expect("tables.pak");
+    let manifest = tpak
+        .entries().iter()
+        .find_map(|e| tpak.read(e).ok().filter(|b| movie_manifest::is_manifest(b)))
+        .expect("manifest");
+    let movies: Vec<String> = movie_manifest::parse(&manifest).into_iter().map(|m| m.movie).collect();
+    let total = movies.len();
+
+    let mut hist: BTreeMap<usize, Vec<String>> = BTreeMap::new();
+    let (mut resolved, mut unresolved, mut unreadable) = (0, 0, 0);
+    for movie in movies {
+        let Some((start, end)) = media::resolve_movie_voice_region(&src, &movie, VoiceLang::English)
+        else { unresolved += 1; continue };
+        let Ok(b) = src.read_segment_range("dat/sound", start, (end - start) as usize)
+        else { unreadable += 1; continue };
+        resolved += 1;
+        hist.entry(slb::to_xma_riffs(&b).len()).or_default().push(movie);
+    }
+    println!("POPULATION: {total} movies in the manifest");
+    println!("COVERAGE:   {resolved} resolved and read, {unresolved} unresolved, {unreadable} unreadable");
+    println!("            {} accounted for\n", resolved + unresolved + unreadable);
+    for (n, ms) in &hist {
+        println!("  {n} chunk(s): {:>3} region(s)   {}", ms.len(),
+                 ms.iter().cloned().collect::<Vec<_>>().join(" "));
+    }
+    println!("\nTHREE-CHUNK REGIONS: {}", hist.get(&3).map(|v| v.len()).unwrap_or(0));
+    println!("--- END OF CENSUS (if this line is missing, the run did not finish) ---");
+}

crates/sylpheed-formats/examples/voice_region_chunks.rs

@@ -0,0 +1,97 @@
+//! What ARE the chunks a movie-voice region decodes to?
+//!
+//! The port reports a resolved voice region decoding to **three** chunks — two
+//! of equal duration each spanning the whole movie, and a leading one that
+//! "matches nothing" — and notes that this is the same 2+1 signature the BGM
+//! banks showed before `bank_header_len` attributed the extra to a bank header.
+//! Two different asset kinds with one signature is worth checking, because if
+//! the same explanation applies then `bank_header_len` is incomplete, and if it
+//! does not then the leading chunk is something we are discarding.
+//!
+//! `slb.rs`'s own doc comment already predicts the answer and disagrees with
+//! "drop it": the header signature fires on 28 entries, all music banks, with
+//! "zero false positives on the 7 993 mid-bank windows, WHERE THE LEADING
+//! REGION IS REAL". A voice region is a mid-bank window by construction —
+//! `resolve_movie_voice_region` starts it at the PREDECESSOR cue's trailer.
+//!
+//!     cargo run -p sylpheed-formats --example voice_region_chunks -- <disc-dir>
+use sylpheed_formats::media::{self, DirectorySource, DiscSource};
+use sylpheed_formats::slb::{self, VoiceLang};
+
+fn main() {
+    let disc = std::env::args()
+        .nth(1)
+        .unwrap_or_else(|| std::env::var("SYLPHEED_DISC").expect("disc dir"));
+    let src = DirectorySource::new(std::path::PathBuf::from(&disc));
+
+    // Disc-wide, not the four movies that motivated the question: every movie
+    // the manifest binds a voice to.
+    let movies: Vec<String> = {
+        use sylpheed_formats::movie_manifest;
+        let tpak = src.open_pak("dat/tables.pak").expect("tables.pak");
+        let manifest = tpak
+            .entries()
+            .iter()
+            .find_map(|e| tpak.read(e).ok().filter(|b| movie_manifest::is_manifest(b)))
+            .expect("movie manifest");
+        movie_manifest::parse(&manifest)
+            .into_iter()
+            .map(|m| m.movie)
+            .collect()
+    };
+    println!("{} movies in the manifest\n", movies.len());
+    let mut census: std::collections::BTreeMap<usize, usize> = Default::default();
+    let (mut with_header, mut with_leading, mut no_leading) = (0, 0, 0);
+    for movie in movies.iter().map(|s| s.as_str()) {
+        let Some((start, end)) = media::resolve_movie_voice_region(&src, movie, VoiceLang::English)
+        else {
+            continue;
+        };
+        let len = end - start;
+        let Ok(bytes) = src.read_segment_range("dat/sound", start, len as usize) else {
+            println!("{movie:8}  region {start}..{end} unreadable");
+            continue;
+        };
+        // Where does the first RIFF sit? Everything before it is the leading
+        // headerless packet region.
+        let first_riff = bytes
+            .windows(4)
+            .position(|w| w == b"RIFF")
+            .map(|p| p as i64)
+            .unwrap_or(-1);
+        let hdr = slb::bank_header_len(&bytes);
+        let riffs = slb::to_xma_riffs(&bytes);
+        let kind = if first_riff <= 0 {
+            no_leading += 1;
+            "no leading region".to_string()
+        } else if hdr == Some(first_riff as usize) {
+            with_header += 1;
+            format!("BANK HEADER ({first_riff} B = {} packets exactly)", first_riff / 2048)
+        } else {
+            with_leading += 1;
+            *census.entry(first_riff as usize % 2048).or_default() += 1;
+            format!(
+                "leading STREAM ({first_riff} B = {} packets + {} B)",
+                first_riff / 2048,
+                first_riff % 2048
+            )
+        };
+        println!(
+            "{movie:10} {start:12}..{end:12} {len:9} B  chunks {}  {kind}",
+            riffs.len()
+        );
+        if let Ok(dir) = std::env::var("VOICE_CHUNK_DUMP") {
+            for (i, r) in riffs.iter().enumerate() {
+                let _ = std::fs::write(format!("{dir}/{movie}-chunk{i}.wav"), r);
+            }
+        }
+    }
+    println!(
+        "\n{with_header} region(s) open with a BANK HEADER (bank_header_len fires)\n\
+{with_leading} open with a leading STREAM\n{no_leading} start at a RIFF"
+    );
+    println!("leading-stream length mod 2048, i.e. the derived data offset:");
+    for (rem, n) in &census {
+        println!("  {rem:5} B  x{n}");
+    }
+}

crates/sylpheed-formats/examples/voice_region_fix_test.rs

@@ -0,0 +1,40 @@
+//! Would keeping the predecessor (instead of falling back to `anchor`) recover
+//! the streams the running decoder actually decodes?
+//!
+//! `voice_region_start_why.rs` shows the failing branch: the start filter
+//! `end - s < 1_500_000` rejects `ADV`'s predecessor because its span is 3.6 MB,
+//! so `start` falls back to `anchor` — a TOC offset, not a stream boundary.
+//!
+//! This does NOT patch the resolver. It asks the one question that decides whether
+//! raising that cap is the fix: **from the predecessor, does `to_xma_riffs` return
+//! the decoder's own byte_sizes?** For `ADV` those are known, so this is a test and
+//! not a fit.
+//!
+//!     cargo run -p sylpheed-formats --example voice_region_fix_test
+
+use sylpheed_formats::media::{DirectorySource, DiscSource};
+use sylpheed_formats::slb;
+
+const ADV_PRED: u64 = 433_425_776;
+const ADV_ANCHOR: u64 = 433_930_240;
+const ADV_END: u64 = 437_044_592;
+/// What the running decoder reported.
+const WANT: [usize; 3] = [1_294_336, 1_118_208, 1_171_456];
+
+fn main() {
+    let disc = std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC");
+    let src = DirectorySource::new(std::path::PathBuf::from(&disc));
+    for (label, start) in [("anchor (today)", ADV_ANCHOR), ("predecessor (proposed)", ADV_PRED)] {
+        let bytes = src
+            .read_segment_range("dat/sound", start, (ADV_END - start) as usize)
+            .expect("region");
+        let sizes: Vec<usize> = slb::to_xma_riffs(&bytes).iter().map(|r| r.len() - 60).collect();
+        let hit = sizes.len() == 3 && sizes.iter().zip(WANT.iter()).all(|(a, b)| a == b);
+        println!(
+            "{label:24} start {start}  span {:>9}  -> {:?}{}",
+            ADV_END - start,
+            sizes,
+            if hit { "   <== MATCHES THE DECODER" } else { "" }
+        );
+    }
+}

crates/sylpheed-formats/examples/voice_region_start_audit.rs

@@ -0,0 +1,63 @@
+//! Does `resolve_movie_voice_region` start inside the first stream, disc-wide?
+//!
+//! Verified on `ADV`: the resolver starts **238 packets (487 424 B) late**, and
+//! extending the span by exactly that reproduces the running decoder's three
+//! byte_sizes to the byte. The decoder is the ground truth there, but it exists
+//! for one movie only — so this asks a structural question instead.
+//!
+//! **If the region began at a stream boundary, stepping the start backwards would
+//! immediately expose the PREVIOUS asset's chunks.** If it began mid-stream, the
+//! first chunk instead *grows*, packet for packet, until the real boundary. The
+//! number of packets it grows for is the clip.
+//!
+//!     cargo run -p sylpheed-formats --example voice_region_start_audit
+
+use sylpheed_formats::media::{self, DirectorySource, DiscSource};
+use sylpheed_formats::movie_manifest;
+use sylpheed_formats::slb::{self, VoiceLang};
+
+fn main() {
+    let disc = std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC");
+    let src = DirectorySource::new(std::path::PathBuf::from(&disc));
+    let tpak = src.open_pak("dat/tables.pak").expect("tables.pak");
+    let manifest = tpak
+        .entries()
+        .iter()
+        .find_map(|e| tpak.read(e).ok().filter(|b| movie_manifest::is_manifest(b)))
+        .expect("manifest");
+    let movies: Vec<String> = movie_manifest::parse(&manifest)
+        .into_iter()
+        .map(|m| m.movie)
+        .collect();
+
+    println!("{:10} {:>8} {:>12} {:>10}  {}", "movie", "chunks", "first chunk", "clip pkts", "verdict");
+    let (mut clipped, mut clean, mut skipped) = (0, 0, 0);
+    for movie in movies {
+        let Some((start, end)) = media::resolve_movie_voice_region(&src, &movie, VoiceLang::English)
+        else { skipped += 1; continue };
+        // ONE read of the region plus a lead-in, then slide inside it. Re-reading
+        // several MB per step made this too slow to finish at all.
+        const LEAD: u64 = 600 * 2048;
+        let lead = LEAD.min(start);
+        let buf = match src.read_segment_range("dat/sound", start - lead, (end - (start - lead)) as usize) {
+            Ok(b) => b, Err(_) => { skipped += 1; continue }
+        };
+        let at = |back: usize| -> Vec<Vec<u8>> {
+            let off = lead as usize - back * 2048;
+            slb::to_xma_riffs(&buf[off..])
+        };
+        let base_riffs = at(0);
+        if base_riffs.is_empty() { skipped += 1; continue }
+        let n0 = base_riffs.len();
+        let first0 = base_riffs[0].len() - 60;
+        let mut clip = 0usize;
+        for k in 1..=(lead as usize / 2048) {
+            if at(k).len() != n0 { break }
+            clip = k;
+        }
+        let verdict = if clip == 0 { clean += 1; "starts at a boundary" }
+                      else { clipped += 1; "STARTS MID-STREAM" };
+        println!("{movie:10} {n0:>8} {first0:>12} {clip:>10}  {verdict}");
+    }
+    println!("\nclipped {clipped}   clean {clean}   skipped {skipped}");
+}

crates/sylpheed-formats/examples/voice_region_start_why.rs

@@ -0,0 +1,70 @@
+//! WHY does `resolve_movie_voice_region` start inside the first stream?
+//!
+//! [`voice-region-starts-late.md`] establishes that it does — 238 packets late for
+//! `ADV`, 8 of 10 multichannel regions disc-wide — but not why, and a fix guessed
+//! from one movie would be worse than a documented defect. This reproduces the
+//! resolver's own steps and prints each candidate, so the failing branch is visible
+//! rather than inferred.
+//!
+//! The suspicion the code itself raises: the start is filtered by
+//! `end - s < 1_500_000` — "only within one bank" — and `ADV`'s region has to span
+//! **3.6 MB**. If that filter rejects the real predecessor, `start` silently falls
+//! back to `anchor`, which is a TOC offset and not a stream boundary at all.
+//!
+//!     cargo run -p sylpheed-formats --example voice_region_start_why
+
+use sylpheed_formats::hash::name_hash;
+use sylpheed_formats::media::{DirectorySource, DiscSource};
+use sylpheed_formats::pak::PakArchive;
+use sylpheed_formats::slb::VoiceLang;
+use sylpheed_formats::{movie_manifest, movie_voice};
+
+fn main() {
+    let disc = std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC");
+    let src = DirectorySource::new(std::path::PathBuf::from(&disc));
+    let code = VoiceLang::English.code_pub();
+    let tpak = src.open_pak("dat/tables.pak").expect("tables.pak");
+    let manifest = tpak
+        .entries().iter()
+        .find_map(|e| tpak.read(e).ok().filter(|b| movie_manifest::is_manifest(b)))
+        .expect("manifest");
+    let marker = format!("{code}\\Movie\\VOICE_ADV.slb");
+    let registry = tpak.entries().iter().find_map(|e| {
+        tpak.read(e).ok().filter(|b| b.windows(marker.len()).any(|w| w == marker.as_bytes()))
+    }).expect("registry");
+    let ids = movie_voice::registry_voice_ids(&registry);
+    let stoc = src.read_file("dat/sound.pak").expect("sound.pak");
+    let entries = PakArchive::parse_toc(&stoc).expect("toc");
+
+    println!("{:10} {:>6} {:>12} {:>12} {:>12} {:>10} {:>9}  {}",
+             "movie","id","anchor","pred(id-1)","pred(before)","span","chosen","note");
+    for m in movie_manifest::parse(&manifest) {
+        let movie = m.movie;
+        let Some(token) = movie_manifest::voice_token(&manifest, &movie) else { continue };
+        let Some(&id) = ids.get(&token) else { continue };
+        let Some(anchor) = ["Movie","etc","Voice"].iter().find_map(|dir| {
+            let h = name_hash(&format!("{code}\\{dir}\\{token}.slb"));
+            entries.binary_search_by_key(&h, |e| e.name_hash).ok().map(|i| entries[i].offset as u64)
+        }) else { continue };
+        let win_start = anchor.saturating_sub(2*1024*1024) & !3;
+        let Ok(window) = src.read_segment_range("dat/sound", win_start, 8*1024*1024) else { continue };
+        let Some(end_local) = movie_voice::find_descriptor(&window, id) else { continue };
+        let end = win_start + end_local as u64;
+        let p1 = movie_voice::find_descriptor(&window, id.wrapping_sub(1)).map(|o| win_start + o as u64);
+        let pb = movie_voice::find_descriptor_before(&window, end_local).map(|o| win_start + o as u64);
+        let cand = p1.or(pb);
+        // the resolver's own filter
+        let kept = cand.filter(|&s| s < end && end - s < 1_500_000);
+        let chosen = kept.unwrap_or(anchor);
+        let span = cand.map(|s| end.saturating_sub(s)).unwrap_or(0);
+        let note = match (cand, kept) {
+            (Some(_), None) => "REJECTED by the 1.5 MB filter -> fell back to anchor",
+            (Some(_), Some(_)) => "predecessor kept",
+            (None, _) => "no predecessor found -> anchor",
+        };
+        println!("{movie:10} {id:>6} {anchor:>12} {:>12} {:>12} {span:>10} {:>9}  {note}",
+                 p1.map(|v| v.to_string()).unwrap_or("-".into()),
+                 pb.map(|v| v.to_string()).unwrap_or("-".into()),
+                 if chosen == anchor { "anchor" } else { "pred" });
+    }
+}

crates/sylpheed-formats/examples/voice_stream_cue_map.rs

@@ -0,0 +1,205 @@
+//! Who owns the bytes in front of a movie-voice region's first `RIFF`?
+//!
+//! [`voice-region-leading-chunk.md`] left one thing open: the leading chunk of
+//! the 17 stream-opening regions is real XMA audio that **no other movie-voice
+//! region claims** — but the census only enumerated the 95 movie cues, while the
+//! same continuous stream also carries the in-mission `VOICE_D_*` lines. The
+//! leading hypothesis was that the bytes belong to one of those, and the port
+//! pointed out that the byte-span test already written settles it *without
+//! anyone listening* if the enumeration is widened.
+//!
+//! So this widens it the whole way: rather than resolving cues one at a time
+//! through the manifest, scan the stream itself for **every** trailer descriptor
+//! — the `(id: u32be, 0x11, …)` pair whose id repeats at `+0x800`, which
+//! `movie_voice` documents as the end of a cue's audio. Cue N's audio is
+//! `[descriptor(N-1) .. descriptor(N)]`, so the full descriptor list IS the
+//! complete cue partition of the stream, movie and mission alike.
+//!
+//!     cargo run -p sylpheed-formats --example voice_stream_cue_map -- <disc-dir>
+use sylpheed_formats::media::{self, DirectorySource, DiscSource};
+use sylpheed_formats::slb::VoiceLang;
+
+const DESC_MARK: u32 = 0x11;
+const DESC_REPEAT: usize = 0x800;
+const ID_MAX: u32 = 0x1_0000;
+
+/// Every trailer descriptor in `buf`, as `(offset, id)`.
+///
+/// Same predicate `movie_voice::find_descriptor` uses — the id-repeat at +0x800
+/// is what makes a false match inside XMA audio ~2^-64.
+fn all_descriptors(buf: &[u8]) -> Vec<(usize, u32)> {
+    let be = |o: usize| u32::from_be_bytes([buf[o], buf[o + 1], buf[o + 2], buf[o + 3]]);
+    let mut out = Vec::new();
+    if buf.len() < DESC_REPEAT + 8 {
+        return out;
+    }
+    let end = buf.len() - (DESC_REPEAT + 4);
+    let mut o = 0;
+    while o <= end {
+        let id = be(o);
+        if id >= 1 && id < ID_MAX && be(o + 4) == DESC_MARK && be(o + DESC_REPEAT) == id {
+            out.push((o, id));
+        }
+        o += 4;
+    }
+    out
+}
+
+fn main() {
+    let disc = std::env::args()
+        .nth(1)
+        .unwrap_or_else(|| std::env::var("SYLPHEED_DISC").expect("disc dir"));
+    let src = DirectorySource::new(std::path::PathBuf::from(&disc));
+
+    // The cue-name -> id registry, so a descriptor id can be named.
+    let tpak = src.open_pak("dat/tables.pak").expect("tables.pak");
+    let marker = "eng\\Movie\\VOICE_ADV.slb";
+    let registry = tpak
+        .entries()
+        .iter()
+        .find_map(|e| {
+            tpak.read(e)
+                .ok()
+                .filter(|b| b.windows(marker.len()).any(|w| w == marker.as_bytes()))
+        })
+        .expect("voice registry");
+    let ids = sylpheed_formats::movie_voice::registry_voice_ids(&registry);
+    let name_of: std::collections::HashMap<u32, String> =
+        ids.iter().map(|(n, &i)| (i, n.clone())).collect();
+    println!("registry: {} cue names, {} distinct ids", ids.len(), name_of.len());
+
+    // The 17 regions that open with a headerless stream, from the manifest.
+    let movies: Vec<String> = {
+        use sylpheed_formats::movie_manifest;
+        let manifest = tpak
+            .entries()
+            .iter()
+            .find_map(|e| tpak.read(e).ok().filter(|b| movie_manifest::is_manifest(b)))
+            .expect("manifest");
+        movie_manifest::parse(&manifest).into_iter().map(|m| m.movie).collect()
+    };
+    let mut regions = Vec::new();
+    for m in &movies {
+        if let Some((s, e)) = media::resolve_movie_voice_region(&src, m, VoiceLang::English) {
+            regions.push((m.clone(), s, e));
+        }
+    }
+    let lo = regions.iter().map(|r| r.1).min().unwrap();
+    let hi = regions.iter().map(|r| r.2).max().unwrap();
+    // Scan a window covering every region, with margin for cues either side.
+    let win_start = lo.saturating_sub(8 * 1024 * 1024) & !3;
+    let win_len = (hi - win_start + 8 * 1024 * 1024) as usize;
+    println!("scanning dat/sound {win_start}..{} ({:.1} MB)", win_start + win_len as u64,
+             win_len as f64 / 1e6);
+    let buf = src
+        .read_segment_range("dat/sound", win_start, win_len)
+        .expect("stream window");
+    let descs = all_descriptors(&buf);
+    println!("{} trailer descriptors found\n", descs.len());
+
+    let named = descs.iter().filter(|(_, id)| name_of.contains_key(id)).count();
+    println!("  of those, {named} carry an id the registry names, {} do not\n",
+             descs.len() - named);
+
+    // For each stream-opening region, name the cue that OWNS the leading span:
+    // the cue whose [prev_desc .. desc] interval contains it.
+    println!("leading span -> owning cue\n");
+    let mut verdicts: std::collections::BTreeMap<&str, usize> = Default::default();
+    for (m, s, e) in &regions {
+        let Ok(bytes) = src.read_segment_range("dat/sound", *s, (e - s) as usize) else { continue };
+        let Some(fr) = bytes.windows(4).position(|w| w == b"RIFF") else { continue };
+        if fr == 0 || sylpheed_formats::slb::bank_header_len(&bytes) == Some(fr) {
+            continue; // bank-header case, not ours
+        }
+        let (a, b) = (*s, *s + fr as u64); // the leading span, global offsets
+        // Descriptors bracketing the MIDDLE of the leading span.
+        let mid = (a + b) / 2;
+        let mid_local = (mid - win_start) as usize;
+        let before = descs.iter().rev().find(|(o, _)| (*o as u64) < mid_local as u64);
+        let after = descs.iter().find(|(o, _)| *o >= mid_local);
+        let owner = after.map(|(_, id)| *id);
+        let owner_name = owner
+            .and_then(|id| name_of.get(&id).cloned())
+            .unwrap_or_else(|| owner.map(|i| format!("<unnamed id {i}>")).unwrap_or("<none>".into()));
+        let kind = if owner_name.starts_with("VOICE_D_") {
+            "MISSION line"
+        } else if owner_name.starts_with("VOICE_") {
+            "movie cue"
+        } else {
+            "unknown"
+        };
+        *verdicts.entry(kind).or_default() += 1;
+        println!(
+            "  {m:8} lead {:8} B  bracketed by desc@{:?} .. desc@{:?}  owner {owner_name} [{kind}]",
+            b - a,
+            before.map(|(o, i)| (*o as u64 + win_start, *i)),
+            after.map(|(o, i)| (*o as u64 + win_start, *i)),
+        );
+    }
+    println!("\nverdicts: {verdicts:?}");
+
+    // WHY do exactly these 17 open mid-cue? `resolve_movie_voice_region` takes
+    // the predecessor trailer as the region start, but guards it with
+    // `end - start < 1_500_000` and falls back to the .slb TOC anchor when that
+    // fails. If the guard is the cause, then the stream-opening regions are
+    // exactly the cues whose true span exceeds the guard.
+    println!("\ncue span vs the 1.5 MB guard, and what the region actually starts at:\n");
+    let (mut over, mut under, mut over_is_stream, mut under_is_stream) = (0, 0, 0, 0);
+    for (m, s, e) in &regions {
+        let Ok(bytes) = src.read_segment_range("dat/sound", *s, (e - s) as usize) else { continue };
+        let fr = bytes.windows(4).position(|w| w == b"RIFF");
+        let is_stream = matches!(fr, Some(f) if f > 0
+            && sylpheed_formats::slb::bank_header_len(&bytes) != Some(f));
+        // The true predecessor trailer for this cue, from the full descriptor list.
+        let end_local = (*e - win_start) as usize;
+        let prev = descs.iter().rev().find(|(o, _)| *o < end_local).map(|(o, _)| *o as u64 + win_start);
+        let Some(prev) = prev else { continue };
+        let span = e - prev;
+        let guarded = span >= 1_500_000;
+        if guarded { over += 1; if is_stream { over_is_stream += 1 } }
+        else { under += 1; if is_stream { under_is_stream += 1 } }
+        if is_stream {
+            println!(
+                "  {m:8} true cue span {span:8} B (> guard: {guarded})  region starts at {s}, \
+true start {prev}  -> {} B of the cue's own audio is OUTSIDE the region",
+                s.saturating_sub(prev)
+            );
+        }
+    }
+    println!("\ncues over the 1.5 MB guard: {over}, of which stream-opening: {over_is_stream}");
+    println!("cues under the guard:      {under}, of which stream-opening: {under_is_stream}");
+
+    // How many streams is ONE cue stored as? The port measured that a region's
+    // leading chunk is the TAIL of its first full-length chunk, i.e. the cue is
+    // re-presented. Structurally that predicts a fixed number of stream starts
+    // inside a cue's TRUE span [desc(N-1) .. desc(N)] -- which is measurable
+    // from the bytes alone, with no decoder.
+    println!("\nstream starts inside each cue's TRUE span (desc(N-1)..desc(N)):\n");
+    let mut hist: std::collections::BTreeMap<usize, usize> = Default::default();
+    let mut hist_long: std::collections::BTreeMap<usize, usize> = Default::default();
+    for w in descs.windows(2) {
+        let (a, b) = (w[0].0, w[1].0);
+        if b <= a || b - a < 4096 {
+            continue;
+        }
+        let span = &buf[a..b];
+        // A stream start is a RIFF; plus the run before the first one, when it
+        // is not a bank header, is itself a stream.
+        let riffs = span
+            .windows(4)
+            .enumerate()
+            .filter(|(_, w)| *w == b"RIFF")
+            .count();
+        let lead_is_stream = match span.windows(4).position(|w| w == b"RIFF") {
+            Some(f) if f > 0 => sylpheed_formats::slb::bank_header_len(span) != Some(f),
+            _ => false,
+        };
+        let streams = riffs + usize::from(lead_is_stream);
+        *hist.entry(streams).or_default() += 1;
+        if b - a >= 1_500_000 {
+            *hist_long.entry(streams).or_default() += 1;
+        }
+    }
+    println!("  all inter-descriptor spans:  {hist:?}");
+    println!("  spans >= 1.5 MB (the long cues): {hist_long:?}");
+}

crates/sylpheed-formats/examples/voice_three_stream_sizes.rs

@@ -0,0 +1,122 @@
+//! Are the three streams of a voice cue in a CONSISTENT size relationship?
+//!
+//! The port selected a voice presentation on this argument: `ADV` chunk 1 is
+//! mono-in-stereo (channel 2 digitally silent) and chunk 2 is dual-mono (both
+//! channels identical), so chunk 2's extra bytes encode a duplicate channel
+//! rather than fidelity — which would explain its higher declared
+//! `PsuedoBytesPerSec` without appealing to encode quality.
+//!
+//! That is a claim about the *encoding*, and it makes a structural prediction:
+//! if stream 3 is always "the same take with its channel duplicated", it should
+//! sit in a consistent size ratio to stream 2 across every 3-stream cue on the
+//! disc. If the ratio scatters — or if some third streams are tiny — then the
+//! observation is about `ADV`, not about the format.
+//!
+//!     cargo run -p sylpheed-formats --example voice_three_stream_sizes -- <disc>
+use sylpheed_formats::media::{DirectorySource, DiscSource};
+use sylpheed_formats::slb;
+
+const DESC_MARK: u32 = 0x11;
+const DESC_REPEAT: usize = 0x800;
+const ID_MAX: u32 = 0x1_0000;
+
+fn all_descriptors(buf: &[u8]) -> Vec<(usize, u32)> {
+    let be = |o: usize| u32::from_be_bytes([buf[o], buf[o + 1], buf[o + 2], buf[o + 3]]);
+    let mut out = Vec::new();
+    if buf.len() < DESC_REPEAT + 8 {
+        return out;
+    }
+    let end = buf.len() - (DESC_REPEAT + 4);
+    let mut o = 0;
+    while o <= end {
+        let id = be(o);
+        if id >= 1 && id < ID_MAX && be(o + 4) == DESC_MARK && be(o + DESC_REPEAT) == id {
+            out.push((o, id));
+        }
+        o += 4;
+    }
+    out
+}
+
+/// The declared `PsuedoBytesPerSec` at `fmt +0x20` of a RIFF chunk, if present.
+fn declared_rate(riff: &[u8]) -> Option<u32> {
+    if riff.len() < 0x28 || &riff[0..4] != b"RIFF" {
+        return None;
+    }
+    Some(u32::from_le_bytes(riff[0x20..0x24].try_into().ok()?))
+}
+
+fn main() {
+    let disc = std::env::args()
+        .nth(1)
+        .unwrap_or_else(|| std::env::var("SYLPHEED_DISC").expect("disc"));
+    let src = DirectorySource::new(std::path::PathBuf::from(&disc));
+    let tpak = src.open_pak("dat/tables.pak").expect("tables.pak");
+    let marker = "eng\\Movie\\VOICE_ADV.slb";
+    let registry = tpak
+        .entries()
+        .iter()
+        .find_map(|e| {
+            tpak.read(e)
+                .ok()
+                .filter(|b| b.windows(marker.len()).any(|w| w == marker.as_bytes()))
+        })
+        .expect("registry");
+    let ids = sylpheed_formats::movie_voice::registry_voice_ids(&registry);
+    let name_of: std::collections::HashMap<u32, String> =
+        ids.iter().map(|(n, &i)| (i, n.clone())).collect();
+
+    // Same window the cue map uses.
+    let win_start: u64 = 421_739_888 & !3;
+    let win_len: usize = 116_300_000;
+    let buf = src
+        .read_segment_range("dat/sound", win_start, win_len)
+        .expect("window");
+    let descs = all_descriptors(&buf);
+
+    println!("{:<14} {:>10} {:>10} {:>10}  {:>7} {:>9} {:>9}",
+             "cue", "stream1", "stream2", "stream3", "s3/s2", "rate2", "rate3");
+    let mut ratios: Vec<f64> = Vec::new();
+    let mut tiny = 0;
+    for w in descs.windows(2) {
+        let (a, b) = (w[0].0, w[1].0);
+        if b <= a || b - a < 4096 {
+            continue;
+        }
+        let span = &buf[a..b];
+        let riffs = slb::to_xma_riffs(span);
+        if riffs.len() != 3 {
+            continue;
+        }
+        let name = name_of
+            .get(&w[1].1)
+            .cloned()
+            .unwrap_or_else(|| format!("id{}", w[1].1));
+        let (s1, s2, s3) = (riffs[0].len(), riffs[1].len(), riffs[2].len());
+        let r = s3 as f64 / s2 as f64;
+        ratios.push(r);
+        if r < 0.5 {
+            tiny += 1;
+        }
+        println!(
+            "{:<14} {s1:>10} {s2:>10} {s3:>10}  {r:>7.4} {:>9} {:>9}",
+            name.trim_start_matches("VOICE_"),
+            declared_rate(&riffs[1]).map(|v| v.to_string()).unwrap_or("-".into()),
+            declared_rate(&riffs[2]).map(|v| v.to_string()).unwrap_or("-".into()),
+        );
+    }
+    ratios.sort_by(|a, b| a.partial_cmp(b).unwrap());
+    let n = ratios.len();
+    println!("\n{n} three-stream cues");
+    if n > 0 {
+        let mean = ratios.iter().sum::<f64>() / n as f64;
+        let var = ratios.iter().map(|r| (r - mean).powi(2)).sum::<f64>() / n as f64;
+        println!(
+            "  stream3/stream2 ratio: min {:.4}  median {:.4}  max {:.4}  mean {:.4}  sd {:.4}",
+            ratios[0], ratios[n / 2], ratios[n - 1], mean, var.sqrt()
+        );
+        println!("  cues where stream 3 is less than HALF of stream 2: {tiny}");
+        let near = ratios.iter().filter(|r| (**r - 1.0).abs() < 0.15).count();
+        println!("  cues where stream 3 is within 15% of stream 2: {near} of {n}");
+    }
+}

crates/sylpheed-formats/src/audio.rs

@@ -97,6 +97,14 @@ pub struct AudioInfo {
     pub size_bytes: usize,
     /// 2048-byte XMA packet count, for XMA/raw-XMA streams.
     pub xma_packets: Option<u32>,
+    /// The stream's **declared** average bytes per second.
+    ///
+    /// For XMA1 this is `XMASTREAMFORMAT::PsuedoBytesPerSec`. It is what makes a
+    /// duration available for a codec we cannot decode: `data_bytes / this`
+    /// agreed with an independently decoded duration to **0.01 %** on the two
+    /// movie voices it was checked against
+    /// (`docs/re/structures/voice-region-leading-chunk.md`).
+    pub avg_bytes_per_sec: Option<u32>,
 }
 
 impl AudioInfo {
@@ -110,6 +118,7 @@ impl AudioInfo {
             duration_secs: None,
             size_bytes: size,
             xma_packets: None,
+            avg_bytes_per_sec: None,
         }
     }
 
@@ -181,6 +190,7 @@ fn parse_riff_wave(bytes: &[u8]) -> Option<AudioInfo> {
 
     let mut pos = 12;
     let (mut tag, mut channels, mut rate, mut bits) = (0u16, 0u16, 0u32, 0u16);
+    let mut avg_bps = 0u32;
     let mut data_bytes: Option<u64> = None;
     let mut have_fmt = false;
 
@@ -191,13 +201,37 @@ fn parse_riff_wave(bytes: &[u8]) -> Option<AudioInfo> {
         match id {
             b"fmt " if body + 16 <= bytes.len() => {
                 tag = le16(body);
-                channels = le16(body + 2);
-                rate = le32(body + 4);
-                bits = le16(body + 14);
-                // WAVE_FORMAT_EXTENSIBLE stores the real tag in the GUID's first
-                // two bytes, right after cbSize (+2) → +24 from the fmt body.
-                if tag == WAVE_FORMAT_EXTENSIBLE && body + 26 <= bytes.len() {
-                    tag = le16(body + 24);
+                // 🔴 XMA1 is NOT a WAVEFORMATEX. Reading it as one is where
+                // `audio info` got "16 channels, 4310 Hz, 2-bit" from the
+                // movie voices: 16 is `wBitsPerSample` read as channels, and
+                // 4310 is `wEncodeOptions` (0x10d6) read as a sample rate.
+                //
+                // XMA1 carries `XMAWAVEFORMAT`, then one `XMASTREAMFORMAT` per
+                // stream (xenia-canary `src/xenia/apu/xma_context.h`,
+                // cross-checked against the disc's own movie-voice headers):
+                //
+                //   +0  wFormatTag   +2  wBitsPerSample  +4  wEncodeOptions
+                //   +6  wLargestSkip +8  wNumStreams     +10 bLoopCount (u8)
+                //   +11 bStreamCount (u8)
+                //   +12 PsuedoBytesPerSec  +16 SampleRate  +20 LoopStart
+                //   +24 LoopEnd  +28 SubframeData (u8)  +29 Channels (u8)
+                //   +30 ChannelMask
+                if tag == WAVE_FORMAT_XMA && body + 32 <= bytes.len() {
+                    bits = le16(body + 2);
+                    avg_bps = le32(body + 12);
+                    rate = le32(body + 16);
+                    channels = bytes[body + 29] as u16;
+                } else {
+                    channels = le16(body + 2);
+                    rate = le32(body + 4);
+                    bits = le16(body + 14);
+                    avg_bps = le32(body + 8);
+                    // WAVE_FORMAT_EXTENSIBLE stores the real tag in the GUID's
+                    // first two bytes, right after cbSize (+2) → +24 from the
+                    // fmt body.
+                    if tag == WAVE_FORMAT_EXTENSIBLE && body + 26 <= bytes.len() {
+                        tag = le16(body + 24);
+                    }
                 }
                 have_fmt = true;
             }
@@ -222,6 +256,15 @@ fn parse_riff_wave(bytes: &[u8]) -> Option<AudioInfo> {
     info.channels = Some(channels).filter(|&c| c > 0);
     info.sample_rate = Some(rate).filter(|&r| r > 0);
     info.bits_per_sample = Some(bits).filter(|&b| b > 0);
+    info.avg_bytes_per_sec = Some(avg_bps).filter(|&b| b > 0);
+
+    // A declared byte rate gives a duration for a codec we cannot decode. Only
+    // for XMA1, where the field is `PsuedoBytesPerSec` and means exactly this.
+    if codec == AudioCodec::Xma && avg_bps > 0 {
+        if let Some(d) = data_bytes {
+            info.duration_secs = Some(d as f32 / avg_bps as f32);
+        }
+    }
 
     match codec {
         AudioCodec::Pcm | AudioCodec::PcmFloat => {
@@ -356,6 +399,58 @@ mod tests {
         assert!((audio.samples[2] - 0.99997).abs() < 1e-3); // 32767/32768
     }
 
+    /// XMA1 is not a `WAVEFORMATEX`, and reading it as one produced nonsense.
+    ///
+    /// The bytes here are the real `fmt ` chunk of `ADV`'s first movie-voice
+    /// presentation, copied off the disc. Read as a `WAVEFORMATEX` it reports
+    /// **16 channels, 4310 Hz, 2-bit** — 16 is `wBitsPerSample`, 4310 is
+    /// `wEncodeOptions` (`0x10d6`). Read as an `XMAWAVEFORMAT` it reports 2
+    /// channels, 48 kHz, 16-bit, 8142 B/s.
+    ///
+    /// The duration is the part worth guarding: this crate has no XMA decoder,
+    /// and `data_bytes / PsuedoBytesPerSec` is the only route to one. It agrees
+    /// with an independently decoded 137.324 s to **0.02 %**.
+    #[test]
+    fn xma1_fmt_is_not_a_waveformatex() {
+        let mut v = Vec::new();
+        v.extend_from_slice(b"RIFF");
+        v.extend_from_slice(&0u32.to_le_bytes());
+        v.extend_from_slice(b"WAVE");
+        v.extend_from_slice(b"fmt ");
+        v.extend_from_slice(&32u32.to_le_bytes());
+        // XMAWAVEFORMAT, exactly as it appears on the disc.
+        v.extend_from_slice(&[
+            0x65, 0x01, // wFormatTag  = 0x0165 (XMA1)
+            0x10, 0x00, // wBitsPerSample = 16
+            0xd6, 0x10, // wEncodeOptions = 0x10d6   <- was misread as the rate
+            0x00, 0x00, // wLargestSkip
+            0x01, 0x00, // wNumStreams
+            0x00, // bLoopCount
+            0x02, // bStreamCount
+            0xce, 0x1f, 0x00, 0x00, // PsuedoBytesPerSec = 8142
+            0x80, 0xbb, 0x00, 0x00, // SampleRate = 48000
+            0x00, 0x00, 0x00, 0x00, // LoopStart
+            0x00, 0x00, 0x00, 0x00, // LoopEnd
+            0x00, // SubframeData
+            0x02, // Channels = 2                    <- was read from +2 as 16
+            0x02, 0x00, // ChannelMask
+        ]);
+        v.extend_from_slice(b"data");
+        v.extend_from_slice(&1_118_208u32.to_le_bytes());
+
+        let info = AudioInfo::probe(&v);
+        assert_eq!(info.codec, AudioCodec::Xma);
+        assert_eq!(info.channels, Some(2), "channels came from wBitsPerSample");
+        assert_eq!(info.sample_rate, Some(48_000), "rate came from wEncodeOptions");
+        assert_eq!(info.bits_per_sample, Some(16));
+        assert_eq!(info.avg_bytes_per_sec, Some(8142));
+        let d = info.duration_secs.expect("duration from the declared byte rate");
+        assert!(
+            (d - 137.324).abs() < 0.05,
+            "declared-rate duration {d} should match the decoded 137.324 s"
+        );
+    }
+
     #[test]
     fn probe_xma2_riff_reports_metadata_not_decode() {
         // Minimal RIFF/WAVE with an XMA2 fmt tag.

crates/sylpheed-formats/src/media.rs

@@ -288,12 +288,29 @@ pub fn resolve_movie_voice_region<S: DiscSource + ?Sized>(
 
     // Start = the predecessor trailer. Prefer the exact `id-1`; where the id
     // sequence has a gap (VOICE_D_453 → 454) fall back to the nearest trailer
-    // below — but only within one bank (~1.5 MB), else this is the first cue in
-    // its block and the audio starts at the anchor itself.
+    // below.
+    //
+    // 🔴 There used to be a second condition here — `end - s < 1_500_000`, "only
+    // within one bank, else this is the first cue in its block and the audio
+    // starts at the anchor itself". **It was wrong, and it silently truncated the
+    // first stream of every region larger than 1.5 MB.** `anchor` is a TOC offset,
+    // not a stream boundary, so the fallback started mid-packet-run: `ADV` began
+    // **238 packets (487 424 B) into its own first stream**, and a consumer then
+    // saw a leading chunk that "matched nothing" and dropped 62 % of a real stream.
+    //
+    // Ground truth is the running decoder, which reports `ADV`'s three contexts as
+    // 1 294 336 / 1 118 208 / 1 171 456 (`--xma_param_probe`). With the cap gone the
+    // region reproduces all three exactly; with it, the first is 806 912.
+    //
+    // Disc-wide over the 95 manifest movies that resolve: **17 regions fixed, 78
+    // unchanged, 0 changed in any other way** — in every one of the 17 the first
+    // chunk grows and the remaining chunks are byte-identical, which is what a
+    // corrected start looks like and what pulling in a neighbouring asset does not.
+    // `docs/re/structures/voice-region-starts-late.md`.
     let start = movie_voice::find_descriptor(&window, id.wrapping_sub(1))
         .or_else(|| movie_voice::find_descriptor_before(&window, end_local))
         .map(|o| win_start + o as u64)
-        .filter(|&s| s < end && end - s < 1_500_000)
+        .filter(|&s| s < end)
         .unwrap_or(anchor);
     Some((start, end))
 }

crates/sylpheed-formats/src/slb.rs

@@ -377,6 +377,39 @@ pub fn leading_data_offset(first_riff: usize) -> usize {
     first_riff % XMA1_PACKET
 }
 
+/// Length of the **bank header** when an entry begins with one, in bytes.
+///
+/// A music bank opens with a header the header itself sizes: big-endian, the
+/// 2048-byte block size sits at `+0x18`, the bank id is repeated at `+0x00` and
+/// `+0x20`, and `+0x24` is the header's length **in blocks** (5, i.e. 10 240 B,
+/// on every music bank on this disc).
+///
+/// This exists because [`leading_data_offset`] derives a leading packet stream's
+/// start as `first_riff % XMA1_PACKET`, which is only correct when the header is
+/// SMALLER than one packet. A music bank's header is exactly five packets, so
+/// the modulus returns 0 and the whole header was being emitted as a sub-wave —
+/// a third "stem" on a bank the corpus documents as two
+/// (`docs/re/structures/bgm-two-stems.md`).
+///
+/// Disc-wide over `sound.pak`'s 9 519 entries the signature fires on **28**, all
+/// of them music banks (ids 1001–1023, 1101–1105), and on every one of the 28
+/// the declared header ends **exactly** at the first `RIFF` — so no bank on this
+/// disc has both a header at offset 0 and a leading packet stream. Zero false
+/// positives on the 7 993 mid-bank windows, where the leading region IS real.
+pub fn bank_header_len(slb: &[u8]) -> Option<usize> {
+    if slb.len() < 0x38 {
+        return None;
+    }
+    if slb[0x18..0x1c] != [0x00, 0x00, 0x08, 0x00] {
+        return None;
+    }
+    if slb[0x00..0x04] != slb[0x20..0x24] {
+        return None;
+    }
+    let blocks = u32::from_be_bytes(slb[0x24..0x28].try_into().ok()?) as usize;
+    blocks.checked_mul(XMA1_PACKET)
+}
+
 pub fn to_xma_riffs(slb: &[u8]) -> Vec<Vec<u8>> {
     let mut out = Vec::new();
     let first_riff = find(slb, b"RIFF", 0);
@@ -422,7 +455,15 @@ pub fn to_xma_riffs(slb: &[u8]) -> Vec<Vec<u8>> {
     // bound to `VOICE_D_453`/`454`, i.e. precisely the broken ones — and
     // ≤0.25 s to 66 of the rest. Callers clamp to the movie length anyway.
     if let Some(ri) = first_riff {
-        let start = leading_data_offset(ri);
+        // A bank that carries its OWN header at offset 0 states how long it is,
+        // and on this disc that header always runs right up to the first `RIFF`
+        // — so there is no leading packet stream at all. Without this the
+        // modulus below returns 0 for a 5-packet header and the header itself is
+        // emitted as a sub-wave: `BGM_103.slb` came back as THREE waves against a
+        // census, an executable reference and a runtime XMA probe that all say
+        // two. It decodes to 0.009 s of PCM (the same chain returns 87.744 s for
+        // the bank's real wave 0), and it is 99.1 % zero bytes.
+        let start = bank_header_len(slb).unwrap_or_else(|| leading_data_offset(ri));
         if ri > start {
             if let Some(data) = slb.get(start..ri) {
                 if data.iter().any(|b| *b != 0) {

crates/sylpheed-formats/src/ui_layout.rs

@@ -111,12 +111,22 @@ pub struct Keyframe {
     /// starts are negative.
     pub x: i32,
     pub y: i32,
-    /// Keyframe time, or `None` for the group's **last** frame.
+    /// The time at which this pose is reached.
     ///
-    /// A group's data stops 4 bytes short of its final block's time slot — that
-    /// word is already the next group's element index. Reading it anyway is
-    /// where a stray `time = 1869640736` comes from, and it silently corrupts
-    /// the max-dwell pick in [`Element::rest`].
+    /// ✅ Always `Some` since 2026-08-29. A placement group is an 8-byte header
+    /// followed by `frames` records of `{ u32 time; 36-byte pose }`, so the time
+    /// word **precedes** the pose it belongs to. Our block window starts at the
+    /// pose, so pose `k`'s time is the previous stride's `+36` word, and pose
+    /// 0's is the group's lead-in word at `header + 8`.
+    ///
+    /// ⚠️ The old reading took `+36` as *this* pose's time. That left the final
+    /// pose — the end of every fade-out — untimed, and it is where the "a
+    /// group's data stops 4 bytes short of its final block's time slot" note and
+    /// the stray `time = 1869640736` both came from. There is no short group and
+    /// no missing word; the association was off by one.
+    /// See `docs/re/ui-keyframe-record-layout.md`.
+    ///
+    /// `Option` is retained for the `SYLPHEED_KF_TIME_LEGACY=1` escape hatch.
     pub time: Option<u32>,
 }
 
@@ -182,13 +192,90 @@ impl Element {
     ///
     /// Falls back to the longest-dwell rule when no two adjacent keyframes
     /// agree — a group that ramps through every frame and never holds.
+    /// The element's pose at keyframe time `t`, linearly interpolated.
+    ///
+    /// `rest()` returns the last HOLD keyframe **of one element, chosen
+    /// independently of every other element**. That is the wrong pose twice over:
+    ///
+    /// * for anything still moving — the title's light sweeps hold at `x = 1521`,
+    ///   off the right edge, so a resting composite deletes them rather than
+    ///   settling them;
+    /// * 🔴 and for anything **transient**. `ptlogo_back2eff1` is a two-frame
+    ///   flash (`a=0` until t52, `255` at t54–56, `0` again by t58); its last
+    ///   hold *is* the flash peak, so `rest()` leaves it burning forever. Five
+    ///   such flashes stack on the title and blow the light arc out to pure
+    ///   white — see `docs/re/structures/ui-settle-time.md`.
+    ///
+    /// A settled screen is one INSTANT that every element is posed at, which is
+    /// what [`UiBuild::settle_time`] computes and `ComposeOptions::at` applies.
+    ///
+    /// The ramp is linear (`docs/re/ui-keyframe-time-unit.md`), and a group
+    /// **holds** at its last keyframe rather than looping, so `t` past the end
+    /// clamps.
+    pub fn pose_at(&self, t: u32) -> Option<Keyframe> {
+        let ks = &self.keyframes;
+        if ks.is_empty() {
+            return None;
+        }
+        let timed: Vec<(u32, &Keyframe)> =
+            ks.iter().filter_map(|k| k.time.map(|tt| (tt, k))).collect();
+        if timed.is_empty() {
+            return Some(ks[ks.len() - 1].clone());
+        }
+        if t <= timed[0].0 {
+            return Some(timed[0].1.clone());
+        }
+        if t >= timed[timed.len() - 1].0 {
+            return Some(timed[timed.len() - 1].1.clone());
+        }
+        for w in timed.windows(2) {
+            let ((t0, a), (t1, b)) = (w[0], w[1]);
+            if t >= t0 && t <= t1 {
+                if t1 == t0 {
+                    return Some(b.clone());
+                }
+                let f = (t - t0) as f64 / (t1 - t0) as f64;
+                let li = |x: i32, y: i32| x + ((y - x) as f64 * f).round() as i32;
+                let lu = |x: u32, y: u32| (x as f64 + (y as f64 - x as f64) * f).round() as u32;
+                // ARGB / RGBA words interpolate per BYTE, not as integers.
+                let lc = |x: u32, y: u32| {
+                    let mut o = 0u32;
+                    for sh in [24, 16, 8, 0] {
+                        let (cx, cy) = ((x >> sh) & 0xff, (y >> sh) & 0xff);
+                        o |= (lu(cx, cy) & 0xff) << sh;
+                    }
+                    o
+                };
+                return Some(Keyframe {
+                    fade: lc(a.fade, b.fade),
+                    rotation_deg: li(a.rotation_deg, b.rotation_deg),
+                    unknown_4: li(a.unknown_4, b.unknown_4),
+                    unknown_8: li(a.unknown_8, b.unknown_8),
+                    scale_x: lu(a.scale_x, b.scale_x),
+                    scale_y: lu(a.scale_y, b.scale_y),
+                    tint: lc(a.tint, b.tint),
+                    x: li(a.x, b.x),
+                    y: li(a.y, b.y),
+                    time: Some(t),
+                });
+            }
+        }
+        Some(timed[timed.len() - 1].1.clone())
+    }
+
     pub fn rest(&self) -> Option<&Keyframe> {
         // `lastall`: the LAST keyframe for every element, bypassing the plateau
-        // rule entirely. This is what the shifted time reading predicts — under
-        // it the final pose is reached at a definite time and nothing follows,
-        // so "rest" needs no heuristic. Testing it against the captures is an
-        // independent check on that reading, from static composites rather than
-        // from animation timing.
+        // rule entirely.
+        //
+        // ⚠️ ITS STATED PURPOSE IS RETIRED (corrected 2026-08-30). This comment
+        // read: "This is what the shifted time reading predicts — under it the
+        // final pose is reached at a definite time and nothing follows, so
+        // 'rest' needs no heuristic. Testing it against the captures is an
+        // independent check on that reading." The shifted reading was **refuted**
+        // by the record-layout fix above, so this override no longer checks
+        // anything about it. It survives only as a plain "take the last
+        // keyframe" diagnostic, alongside the documented `last` and `maxalpha`
+        // (see `docs/re/structures/ui-resting-pose.md`).
         if std::env::var("SYLPHEED_REST_RULE").as_deref() == Ok("lastall") {
             return self.keyframes.last();
         }
@@ -224,7 +311,16 @@ impl Element {
                     let (Some(t0), Some(t1)) =
                         (self.keyframes[k].time, self.keyframes[k + 1].time)
                     else {
-                        continue; // the last frame carries no time
+                        // ⚠️ PRE-FIX COMMENT, corrected 2026-08-30. This read
+                        // "the last frame carries no time", which was the rule
+                        // BEFORE the record-layout fix directly above. Post-fix
+                        // every pose is timed — measured at **0 untimed of
+                        // 24 811 keyframes** across 965 builds — so this branch
+                        // is unreachable on this disc. Kept as a guard because
+                        // `time` is still `Option<u32>` and a malformed group
+                        // could produce `None`; it is no longer a description of
+                        // the format.
+                        continue;
                     };
                     let dwell = t1.saturating_sub(t0);
                     // `>=`, not `>`: on a tie take the LATER frame. A group is
@@ -402,6 +498,30 @@ fn opt_link(rec: &[u8]) -> Option<String> {
     (!s.is_empty()).then_some(s)
 }
 
+/// A RATC record's animation **loop length** in keyframe units — its `+0x08`.
+///
+/// Works at either level: a nested `.rat` leaf is itself a RATC bundle with the
+/// same header shape as the one containing it, so this reads a whole screen
+/// build's length and a single record's length through one path.
+///
+/// **Why it is public.** The loop length is not the largest keyframe time —
+/// `ptbtn00f.rat`, the `PRESS Ⓐ` plate glow, declares **120** while its last
+/// keyframe is at **105**, and that 15-unit slack is the plate holding dark
+/// between cycles. A consumer that infers the period from the keyframes gets
+/// 105 (1.750 s) against a real pulse measured four times at 2.12–2.34 s.
+/// Decoded disc-wide: 1 781 records, **0** violations of
+/// `+0x08 >= largest keyframe time` — see
+/// `docs/re/structures/ui-record-loop-length.md`.
+///
+/// Returns `None` for anything that is not a RATC record, so it is safe to call
+/// on an arbitrary slice; callers do not need their own magic guard.
+pub fn loop_length_units(rec: &[u8]) -> Option<u32> {
+    if rec.len() < 0x0c || rec[0..4] != *b"RATC" {
+        return None;
+    }
+    Some(be32(rec, 0x08))
+}
+
 /// The sprite a `.rat` record places: a NUL-terminated name at `0x20`.
 ///
 /// The field is **not** 16 bytes. Capping it there truncates every longer name —
@@ -493,8 +613,10 @@ fn mark_focused_states(elements: &mut [Element]) {
 /// Read the placement region that follows the declaration table, filling in each
 /// element's keyframe group.
 fn parse_placements(bundle: &[u8], elements: &mut [Element]) -> Vec<usize> {
-    // Experiment gate, default off; see the `time` field below.
-    let shift_times = std::env::var("SYLPHEED_KF_TIME_SHIFT").as_deref() == Ok("1");
+    // Escape hatch for the pre-2026-08-29 reading, which mis-associated every
+    // keyframe time by one slot and could not time a group's final pose at all.
+    // See `docs/re/ui-keyframe-record-layout.md`.
+    let legacy_times = std::env::var("SYLPHEED_KF_TIME_LEGACY").as_deref() == Ok("1");
     let count = elements.len();
     let mut order = Vec::with_capacity(count);
     let mut pos = DECL_TABLE_AT + count * DECL_ENTRY;
@@ -507,7 +629,13 @@ fn parse_placements(bundle: &[u8], elements: &mut [Element]) -> Vec<usize> {
         if idx >= count || frames == 0 || frames > 4096 {
             break;
         }
-        // Group header is (index, count) then one lead-in word; blocks follow.
+        // The region is `frames` records of 40 bytes, each `{ u32 time; 36-byte
+        // pose }`, after an 8-byte header — so the word at `pos + 8` is the
+        // FIRST pose's time, and each 40-byte stride's `+36` word is the time of
+        // the pose that follows it. Our block window is offset 4 bytes into the
+        // record (it starts at the pose), which is why the pose field offsets
+        // below are right while the times were off by one.
+        let first_time = be32(bundle, pos + 8);
         let first = pos + 12;
         // The region is packed so that the next group's header sits 4 bytes
         // inside the last block — i.e. the group owns `frames * 40 - 4` bytes of
@@ -529,16 +657,17 @@ fn parse_placements(bundle: &[u8], elements: &mut [Element]) -> Vec<usize> {
                 tint: be32(bundle, blk + 24),
                 x: be32(bundle, blk + 28) as i32,
                 y: be32(bundle, blk + 32) as i32,
-                // Only a block wholly inside the group carries a time.
-                //
-                // ⚠️ Which block a time word BELONGS TO is under test — see
-                // `docs/re/ui-keyframe-time-unit.md`. Set `SYLPHEED_KF_TIME_SHIFT=1`
-                // to read `W[k-1]` as block `k`'s time ("the word is the time the
-                // NEXT pose is reached") instead of `W[k]`. Default is unchanged.
-                time: if shift_times {
-                    (k >= 1).then(|| be32(bundle, blk - KEYFRAME + 36))
-                } else {
+                // Pose `k`'s time is the word that PRECEDES it: the group's
+                // lead-in word for `k == 0`, and the previous stride's `+36`
+                // otherwise. Every pose is timed; nothing is missing and nothing
+                // is special-cased. Checked disc-wide — see
+                // `docs/re/ui-keyframe-record-layout.md`.
+                time: if legacy_times {
                     (blk + 40 <= group_end).then(|| be32(bundle, blk + 36))
+                } else if k == 0 {
+                    Some(first_time)
+                } else {
+                    Some(be32(bundle, blk - KEYFRAME + 36))
                 },
             });
         }
@@ -724,6 +853,12 @@ pub struct ComposeOptions {
     /// Left on with the derived order, an opaque black quad sorts last and wipes
     /// 32 of `GP_DIALOG`'s builds.
     pub include_primitives: bool,
+    /// Pose every element at this keyframe time instead of at its resting pose.
+    ///
+    /// `None` keeps the settled composite, which is what every existing caller
+    /// wants. A capture taken mid-animation needs the render posed at the same
+    /// instant — see [`Element::pose_at`].
+    pub at: Option<u32>,
 }
 
 impl Default for ComposeOptions {
@@ -733,6 +868,7 @@ impl Default for ComposeOptions {
             include_animated: false,
             backdrop: [14, 14, 20, 255],
             include_primitives: false,
+            at: None,
         }
     }
 }
@@ -825,6 +961,99 @@ pub fn implied_layer_key(name: &str) -> Option<u32> {
 /// they land does not affect a composite. Ties keep declaration order — the game
 /// breaks them some other way, which is unexplained and looks harmless because
 /// tied elements are same-layer.
+/// Is this element an opaque full-screen quad that **must** sort below everything?
+///
+/// A keyless primitive has no layer key and the game's own code decides where it
+/// paints ([`implied_layer_key`] records the names measured in the running game).
+/// For one whole class of them the file settles it without a measurement: an
+/// element that covers the screen and is **fully opaque** at some instant cannot
+/// paint above anything visible at that instant, or the screen would be blank.
+/// Where the elements visible during its opaque span are *all* of them, its
+/// position is forced to first.
+///
+/// Two controls, both measured in the running game and both reproduced by this
+/// rule rather than assumed by it:
+///
+/// * `palogo_eff0.prm` is measured painting **first** — and comes out forced
+///   first (opaque for 211 instants, below 6 of 6). A rule keyed on the *name*
+///   would get this wrong: it is named like an overlay.
+/// * `pteff00.prm` is measured painting **last** — and is forced below only 3 of
+///   23 elements on the title, because it is opaque for 2 instants at the screen's
+///   entry and exit, so the rule permits it on top.
+///
+/// Disc-wide: 80 instances forced first, 50 constrained but not forced, 0
+/// unconstrained. It also explains the 36 dialog builds that composite to one
+/// colour — `pzeff00.prm` is forced first in 32 of 32 instances.
+///
+/// ⚠️ Assumes straight alpha-over blending. Blend mode is an open question in
+/// `docs/re/structures/ui-prm-primitives.md`; an *additive* quad at alpha 255
+/// would not occlude, and this rule would then be placing it wrongly.
+pub fn forced_backdrop(build: &UiBuild, el: &Element) -> bool {
+    // 🔴 Untextured primitives only. A `.t32` sprite's ELEMENT alpha being 255
+    // says nothing about whether its texture covers the screen — most of it may
+    // be transparent, so it occludes nothing. Applied without this guard the
+    // rule claims 22 textured sprites must sort first, against their own layer
+    // keys: `pneff01.t32` (key 0xd850, paints #8 of 13) and `pbfriendly.t32`
+    // (key 0x9230, #17 of 49). Those disagreements are the rule being wrong,
+    // not the keys.
+    if el.sprite.is_some() {
+        return false;
+    }
+    // The element must have a declared size at all; coverage itself is tested
+    // per instant below, against the SCALED size.
+    if el.pivot_x == 0 || el.pivot_y == 0 {
+        return false;
+    }
+    let tmax = build
+        .elements
+        .iter()
+        .flat_map(|e| e.keyframes.iter().filter_map(|k| k.time))
+        .max()
+        .unwrap_or(0);
+    if tmax == 0 {
+        return false;
+    }
+    // An instant counts only where the element is BOTH fully opaque AND actually
+    // covering — tested together, because both animate on the same ramp.
+    //
+    // ⚠️ Coverage is the SCALED size, not the declared one, and the test must be
+    // two-sided. A quad scaled down does not cover what its pivot suggests —
+    // `pbafc.prm` declares 844x600 and draws ~17x18 at 2 %/3 %. And a quad scaled
+    // *up* can cover from a smaller declared size, so rejecting on the declared
+    // size would replace one error with its mirror. Checked before adopting:
+    // across 921 keyless elements, **0** cover the screen only via scale, so the
+    // mirror case does not occur on this disc — the per-instant test is in
+    // because it does not need that to stay true.
+    let (dw, dh) = ((el.pivot_x * 2) as u64, (el.pivot_y * 2) as u64);
+    let opaque: Vec<u32> = (0..=tmax)
+        .filter(|&t| {
+            el.pose_at(t).map_or(false, |k| {
+                k.fade >> 24 == 255
+                    && dw * k.scale_x as u64 / 100 >= build.design_w as u64
+                    && dh * k.scale_y as u64 / 100 >= build.design_h as u64
+            })
+        })
+        .collect();
+    if opaque.is_empty() {
+        return false;
+    }
+    let mut others = 0usize;
+    let mut occluded = 0usize;
+    for o in &build.elements {
+        if o.index == el.index {
+            continue;
+        }
+        others += 1;
+        if opaque
+            .iter()
+            .any(|&t| o.pose_at(t).map(|k| k.fade >> 24).unwrap_or(0) > 0)
+        {
+            occluded += 1;
+        }
+    }
+    others > 0 && occluded == others
+}
+
 pub fn derived_paint_order(build: &UiBuild, bundle: &[u8]) -> Vec<usize> {
     let mut idx: Vec<usize> = (0..build.elements.len()).collect();
     idx.sort_by_key(|&i| {
@@ -832,6 +1061,9 @@ pub fn derived_paint_order(build: &UiBuild, bundle: &[u8]) -> Vec<usize> {
         (
             sprite_layer_key(build, bundle, el)
                 .or_else(|| implied_layer_key(&el.name))
+                // An opaque full-screen quad that covers every other element
+                // while it is opaque cannot be on top — see `forced_backdrop`.
+                .or_else(|| forced_backdrop(build, el).then_some(0))
                 .unwrap_or(u32::MAX),
             i,
         )
@@ -900,11 +1132,73 @@ fn measured_paint_order(build: &UiBuild) -> Option<Vec<usize>> {
     None
 }
 
+impl UiBuild {
+    /// The instant at which this screen is *settled*, in keyframe time units.
+    ///
+    /// A screen is not settled when each element sits at its own last hold —
+    /// that is what [`Element::rest`] gives, and it is wrong for a transient
+    /// (see the note there). It is settled at one shared instant, and the disc
+    /// says which: gather every keyframe time in the build, and take the
+    /// **longest interval containing none of them**. Inside that gap nothing has
+    /// an inflection, so every element is either holding or on a long linear
+    /// ramp — which is exactly what "the screen has stopped changing" means.
+    ///
+    /// Returns the midpoint of that gap, or `None` when the build has fewer than
+    /// two distinct keyframe times.
+    ///
+    /// ⚠️ **Not every bundle has a settled instant.** Disc-wide over the 1 758
+    /// composable bundles carrying two or more keyframe times, 30 % have a gap of
+    /// at least half a second and 42 % have one under 10 units — the latter are
+    /// mostly `loop*` animation fragments, which are *meant* to be in motion and
+    /// have no settled pose to find. Check the gap width before trusting the
+    /// midpoint; `settle_window` returns it.
+    pub fn settle_time(&self) -> Option<u32> {
+        self.settle_window().map(|(lo, hi)| lo + (hi - lo) / 2)
+    }
+
+    /// The `[start, end]` of the longest keyframe-free interval — see
+    /// [`UiBuild::settle_time`]. The width `end - start` is how much confidence
+    /// the midpoint deserves.
+    pub fn settle_window(&self) -> Option<(u32, u32)> {
+        let mut ts: Vec<u32> = self
+            .elements
+            .iter()
+            .flat_map(|e| e.keyframes.iter().filter_map(|k| k.time))
+            .collect();
+        ts.sort_unstable();
+        ts.dedup();
+        if ts.len() < 2 {
+            return None;
+        }
+        ts.windows(2)
+            .map(|w| (w[1] - w[0], w[0], w[1]))
+            .max_by_key(|&(d, _, _)| d)
+            .map(|(_, lo, hi)| (lo, hi))
+    }
+}
+
 pub fn compose(
     build: &UiBuild,
     bundle: &[u8],
     opts: ComposeOptions,
     visible: Option<&[bool]>,
+) -> ComposedScreen {
+    compose_with_order(build, bundle, opts, visible, None)
+}
+
+/// `compose`, with the paint order supplied by the caller.
+///
+/// The only reason this exists is to *measure* what a paint order costs: render
+/// a screen twice, once with the order `compose` would pick and once with two
+/// elements swapped, and diff the pixels. `order` is a permutation of element
+/// indices, first painted first; `None` means "whatever `compose` would use".
+/// Nothing in the normal render path passes anything but `None`.
+pub fn compose_with_order(
+    build: &UiBuild,
+    bundle: &[u8],
+    opts: ComposeOptions,
+    visible: Option<&[bool]>,
+    order_override: Option<&[usize]>,
 ) -> ComposedScreen {
     let (w, h) = (build.design_w, build.design_h);
     // A dim backdrop stands in for the PRMD dim-quad + the live 3D scene behind
@@ -928,8 +1222,10 @@ pub fn compose(
     // same-layer-key ties, two being total occlusions. Of the port's five
     // screens only `EXTRAS` rests on a derived order with ties: 15 tied pairs,
     // 2 overlapping. See docs/re/structures/ui-paint-order-derived-check.md.
-    let order: Vec<usize> =
-        measured_paint_order(build).unwrap_or_else(|| derived_paint_order(build, bundle));
+    let order: Vec<usize> = match order_override {
+        Some(o) => o.to_vec(),
+        None => measured_paint_order(build).unwrap_or_else(|| derived_paint_order(build, bundle)),
+    };
     for &ei in &order {
         let Some(el) = build.elements.get(ei) else {
             continue;
@@ -967,7 +1263,23 @@ pub fn compose(
         {
             continue;
         }
-        let Some(kf) = el.rest() else { continue };
+        // 🔴 `at` poses LEAVES ONLY, never the top-level elements.
+        //
+        // Posing everything at one global time was tried and is wrong: a
+        // top-level group's final keyframes are its **exit ramp** — the fade-out
+        // played when the screen leaves — and `rest()` deliberately stops at the
+        // last *hold* keyframe before it. Posing the title at t=358 walked every
+        // parent into its exit and drove the render's disagreement with the
+        // capture from 10.92 to 61.74. The leaf is the thing still animating at
+        // that instant, and it runs on its own timeline
+        // (`docs/re/structures/ui-leaf-vs-parent-alpha.md`).
+        let Some(kf) = (match opts.at {
+            Some(t) => el.pose_at(t),
+            None => el.rest().cloned(),
+        }) else {
+            continue;
+        };
+        let kf = &kf;
         // An untextured primitive: a solid quad of the keyframe's `fade` colour,
         // sized by the declared pivot. `kind & 0x10` marks these exactly — see
         // `docs/re/structures/ui-prm-primitives.md`. They are the screen's
@@ -999,6 +1311,65 @@ pub fn compose(
             missing.push(sprite.clone());
             continue;
         };
+        // A nested `.rat` leaf sometimes carries the geometry while the parent
+        // carries none — the title's light sweeps are the case: the parent sits
+        // fixed at (441,270) scale 100 %, and the leaf holds the 600 %/800 %
+        // scale, the +30°/−45° rotation and the whole sweep. Drawing the parent
+        // put the sprite upright in the middle of the screen.
+        //
+        // ⚠️ NOT a blanket rule. A button's base record has a leaf that
+        // DUPLICATES it, and there the parent wins
+        // (`docs/re/structures/ui-button-focus-record.md`). The discriminator is
+        // which record actually carries geometry, so the leaf is used only when
+        // its pose genuinely differs — see `ui-leaf-vs-parent-alpha.md`.
+        let leaf = build.records.get(&el.name).and_then(|&(lo, ls)| {
+            if lo + ls > bundle.len() {
+                return None;
+            }
+            let lb = parse_build(&bundle[lo..lo + ls])?;
+            let pose = |e: &Element| match opts.at {
+                Some(t) => e.pose_at(t),
+                None => e.rest().cloned(),
+            };
+            let differs = lb.elements.iter().any(|le| {
+                pose(le).map_or(false, |lk| {
+                    lk.rotation_deg != 0 || lk.scale_x != kf.scale_x || lk.scale_y != kf.scale_y
+                })
+            });
+            if differs { Some(lb) } else { None }
+        });
+        if let Some(lb) = leaf {
+            let mut any = false;
+            for le in &lb.elements {
+                let lk = match opts.at {
+                    Some(t) => le.pose_at(t),
+                    None => le.rest().cloned(),
+                };
+                let Some(lk) = lk else { continue };
+                // A leaf element resolves no sprite of its own: sprite names are
+                // resolved against the bundle a build was parsed from, and a leaf
+                // is parsed from its own slice. Its NAME is the sprite name, and
+                // the sprite itself lives in the PARENT bundle's table.
+                let lsp = le.sprite.clone().unwrap_or_else(|| le.name.clone());
+                let Some(&(so, ss)) = build.sprites.get(&lsp) else { continue };
+                let Some(limg) = t8ad::parse(&bundle[so..so + ss]) else { continue };
+                // 🔴 Only count it as drawn if it CAN draw. `blit` returns early
+                // on a zero scale — "collapsed to nothing", not "unset" — so
+                // setting the flag unconditionally would let a scale-0 leaf
+                // suppress its parent and blank the element outright.
+                // `pgloading_loop5`'s leaf is scale (0,0), and scale-0 is one of
+                // the failures this corpus is already named for.
+                if lk.scale_x == 0 || lk.scale_y == 0 {
+                    continue;
+                }
+                blit(&mut canvas, w, h, &limg, &lk, le.pivot_x, le.pivot_y);
+                any = true;
+            }
+            if any {
+                drawn.push(el.index);
+                continue;
+            }
+        }
         blit(&mut canvas, w, h, &img, kf, el.pivot_x, el.pivot_y);
         drawn.push(el.index);
     }
@@ -1117,6 +1488,11 @@ fn blit(
     // Keep the pivot point fixed as the element scales.
     let ox = kf.x - (pivot_x as i32 * (sx_pct as i32 - 100)) / 100;
     let oy = kf.y - (pivot_y as i32 * (sy_pct as i32 - 100)) / 100;
+    // The pivot's ABSOLUTE position is invariant under scale, which is the whole
+    // point of the two lines above: at 100 % `ox = kf.x` so the pivot sits at
+    // `kf.x + pivot_x`; at 200 % `ox = kf.x - pivot_x` and the pivot sits at
+    // `ox + 2·pivot_x`, the same place. So rotation turns about it.
+    let (pax, pay) = (kf.x + pivot_x as i32, kf.y + pivot_y as i32);
     // Two modulate colours multiply into one: `tint` (RGBA, and `0xffffffff` on
     // essentially every keyframe seen) and `fade` (**ARGB** — the high byte is
     // the alpha that ramps, the low 24 bits a colour multiply that is `0xffffff`
@@ -1135,6 +1511,73 @@ fn blit(
         ((kf.tint >> 8) & 0xff) * fb / 255,
         (kf.tint & 0xff) * fa / 255,
     );
+    // ---- rotated path -------------------------------------------------------
+    // `+12` is a screen-plane rotation in DEGREES, clockwise-positive with Y
+    // down (`docs/re/structures/ui-keyframe-rotation.md`). The game submits
+    // rotated quads for it; this used to draw them axis-aligned, which put the
+    // title's two light sweeps upright instead of at +30° / −45° and left at
+    // least two thirds of that screen's disagreement with the capture
+    // (`title-residual-tone-vs-geometry.md`).
+    //
+    // Zero rotation keeps the original forward-mapped path byte for byte, so
+    // the screens that do not rotate cannot regress. A rotated element is drawn
+    // by INVERSE mapping instead: forward-mapping a rotation leaves gaps.
+    let rot = ((kf.rotation_deg % 360) + 360) % 360;
+    if rot != 0 {
+        let th = (rot as f64).to_radians();
+        let (cs, sn) = (th.cos(), th.sin());
+        // Axis-aligned bounds of the rotated destination rect.
+        let corners = [
+            (ox, oy),
+            (ox + dw as i32, oy),
+            (ox + dw as i32, oy + dh as i32),
+            (ox, oy + dh as i32),
+        ];
+        let (mut x0, mut y0, mut x1, mut y1) = (i32::MAX, i32::MAX, i32::MIN, i32::MIN);
+        for (cx, cy) in corners {
+            let (rx, ry) = ((cx - pax) as f64, (cy - pay) as f64);
+            let px = pax as f64 + rx * cs - ry * sn;
+            let py = pay as f64 + rx * sn + ry * cs;
+            x0 = x0.min(px.floor() as i32);
+            y0 = y0.min(py.floor() as i32);
+            x1 = x1.max(px.ceil() as i32);
+            y1 = y1.max(py.ceil() as i32);
+        }
+        for ty in y0.max(0)..=y1.min(ch as i32 - 1) {
+            for tx in x0.max(0)..=x1.min(cw as i32 - 1) {
+                // Rotate the destination pixel BACK to find its source pixel.
+                let (rx, ry) = ((tx - pax) as f64 + 0.5, (ty - pay) as f64 + 0.5);
+                let ux = rx * cs + ry * sn;
+                let uy = -rx * sn + ry * cs;
+                let dx = ux + (pax - ox) as f64;
+                let dy = uy + (pay - oy) as f64;
+                if dx < 0.0 || dy < 0.0 || dx >= dw as f64 || dy >= dh as f64 {
+                    continue;
+                }
+                let sxi = ((dx as u32) * sw / dw).min(sw - 1);
+                let syi = ((dy as u32) * sh / dh).min(sh - 1);
+                let si = ((syi * sw + sxi) * 4) as usize;
+                if si + 3 >= img.rgba.len() {
+                    continue;
+                }
+                let sr = img.rgba[si] as u32 * tr / 255;
+                let sg = img.rgba[si + 1] as u32 * tg / 255;
+                let sb = img.rgba[si + 2] as u32 * tb / 255;
+                let sa = img.rgba[si + 3] as u32 * ta / 255;
+                if sa == 0 {
+                    continue;
+                }
+                let di = ((ty as u32 * cw + tx as u32) * 4) as usize;
+                for (k, sc) in [sr, sg, sb].into_iter().enumerate() {
+                    let dc = canvas[di + k] as u32;
+                    canvas[di + k] = ((sc * sa + dc * (255 - sa)) / 255) as u8;
+                }
+                canvas[di + 3] = 255;
+            }
+        }
+        return;
+    }
+    // ---- unrotated path (unchanged) -----------------------------------------
     for row in 0..dh {
         let ty = oy + row as i32;
         if ty < 0 {
@@ -1182,6 +1625,70 @@ fn blit(
 mod tests {
     use super::*;
 
+    /// A solid opaque rectangle sprite, for exercising `blit` geometry.
+    fn solid(w: u32, h: u32) -> t8ad::T8adImage {
+        t8ad::T8adImage { width: w, height: h, rgba: vec![255u8; (w * h * 4) as usize],
+                          flags: 0 }
+    }
+    fn kf_at(x: i32, y: i32, rot: i32) -> Keyframe {
+        Keyframe { fade: 0xff_ff_ff_ff, rotation_deg: rot, unknown_4: 0, unknown_8: 0,
+                   scale_x: 100, scale_y: 100, tint: 0xffff_ffff, x, y, time: Some(0) }
+    }
+    fn draw(img: &t8ad::T8adImage, kf: &Keyframe, px: u32, py: u32) -> Vec<u8> {
+        let mut c = vec![0u8; 64 * 64 * 4];
+        blit(&mut c, 64, 64, img, kf, px, py);
+        c
+    }
+    fn covered(c: &[u8]) -> Vec<(i32, i32)> {
+        let mut v = Vec::new();
+        for y in 0..64 { for x in 0..64 {
+            if c[((y * 64 + x) * 4 + 3) as usize] != 0 { v.push((x as i32, y as i32)); }
+        }}
+        v
+    }
+
+    /// 🔴 CONTROL for the rotated path. An estimator that is wrong on a known
+    /// angle cannot be trusted on an unknown one, so the rotated blit is pinned
+    /// against angles whose answer is arithmetic rather than measured.
+    #[test]
+    fn rotation_control_known_angles() {
+        let img = solid(10, 4);
+        // pivot at the sprite's centre, so rotation turns in place
+        let (px, py) = (5u32, 2u32);
+        let base = draw(&img, &kf_at(20, 30, 0), px, py);
+
+        // 0° and 360° must be identical to the unrotated path, byte for byte:
+        // the fast path must be exactly the old behaviour.
+        assert_eq!(base, draw(&img, &kf_at(20, 30, 360), px, py),
+                   "360 degrees must equal the unrotated path exactly");
+
+        // 90° must turn a 10x4 into a 4x10 about the same centre.
+        let r90 = covered(&draw(&img, &kf_at(20, 30, 90), px, py));
+        let b = covered(&base);
+        let bw = b.iter().map(|p| p.0).max().unwrap() - b.iter().map(|p| p.0).min().unwrap();
+        let bh = b.iter().map(|p| p.1).max().unwrap() - b.iter().map(|p| p.1).min().unwrap();
+        let rw = r90.iter().map(|p| p.0).max().unwrap() - r90.iter().map(|p| p.0).min().unwrap();
+        let rh = r90.iter().map(|p| p.1).max().unwrap() - r90.iter().map(|p| p.1).min().unwrap();
+        assert_eq!((bw, bh), (9, 3), "unrotated extent");
+        assert_eq!((rw, rh), (3, 9), "90 degrees must swap the extents");
+
+        // The covered area must be conserved to a few percent -- a rotation that
+        // loses or invents pixels is the forward-mapping bug this path avoids.
+        let (a0, a90) = (b.len() as f64, r90.len() as f64);
+        assert!((a0 - a90).abs() / a0 < 0.15,
+                "area changed too much under rotation: {a0} -> {a90}");
+
+        // And the centroid must stay on the pivot.
+        let cen = |v: &Vec<(i32, i32)>| {
+            let n = v.len() as f64;
+            (v.iter().map(|p| p.0 as f64).sum::<f64>() / n,
+             v.iter().map(|p| p.1 as f64).sum::<f64>() / n)
+        };
+        let (c0, c9) = (cen(&b), cen(&r90));
+        assert!((c0.0 - c9.0).abs() < 1.0 && (c0.1 - c9.1).abs() < 1.0,
+                "rotation moved the centroid: {c0:?} -> {c9:?}");
+    }
+
     /// A synthetic build bundle: RATC magic, entry count at 0x14, a declaration
     /// table at 0x20, then a placement region.
     fn synth_build(decls: &[(&str, u32, u32, u32, u32)], groups: &[(usize, Vec<Keyframe>)]) -> Vec<u8> {

crates/sylpheed-formats/tests/media_disc.rs

@@ -86,3 +86,39 @@ fn manifest_binding_is_the_only_route() {
         None
     );
 }
+
+/// The resolved `ADV` voice region must contain **all three** streams the running
+/// decoder decodes — not a truncated first one.
+///
+/// Ground truth is the emulator, not this crate: booting with `--xma_param_probe`
+/// reports three XMA contexts with `byte_size` 1 294 336 / 1 118 208 / 1 171 456
+/// (`docs/re/structures/voice-three-streams-are-concurrent.md`). Until 2026-08-30
+/// the resolver's start filter capped a region at 1.5 MB, `ADV`'s span is 3.6 MB,
+/// so the start fell back to `anchor` — a TOC offset, 238 packets into the first
+/// stream — and this returned 806 912 for the first chunk.
+///
+/// This is a regression test against an EXTERNAL measurement, which is the only
+/// kind that can catch the class of bug it was written for: every internal check
+/// passed happily while a third of a stream was missing.
+#[test]
+fn adv_voice_region_holds_all_three_decoded_streams() {
+    let Some(src) = disc() else {
+        eprintln!("SKIP: set SYLPHEED_DISC");
+        return;
+    };
+    let (start, end) = media::resolve_movie_voice_region(&src, "ADV", VoiceLang::English)
+        .expect("ADV voice region");
+    let bytes = src
+        .read_segment_range("dat/sound", start, (end - start) as usize)
+        .expect("region bytes");
+    let sizes: Vec<usize> = sylpheed_formats::slb::to_xma_riffs(&bytes)
+        .iter()
+        .map(|r| r.len() - 60)
+        .collect();
+    assert_eq!(
+        sizes,
+        vec![1_294_336, 1_118_208, 1_171_456],
+        "the region must reproduce the RUNNING DECODER's byte_sizes; \
+         a first chunk of 806912 means the start filter has come back"
+    );
+}

crates/sylpheed-formats/tests/slb_leading_segment_disc.rs

@@ -269,3 +269,62 @@ fn a_waves_declared_size_is_confirmed_by_the_next_seek() {
     assert!(checked >= 30, "expected banks to check, got {checked}");
     eprintln!("wave-boundary identity held for {checked} banks");
 }
+
+/// A **music** bank has no leading segment — the bytes before its first `RIFF`
+/// are the bank header, and emitting them made `BGM_103` look like three stems.
+///
+/// The header sizes itself (`+0x24`, in 2048-byte blocks), and on every bank on
+/// this disc that size lands exactly on the first `RIFF`. So the guard is not a
+/// heuristic and has no threshold: if a bank states a header, believe it.
+#[test]
+fn a_bank_that_states_its_own_header_has_no_leading_segment() {
+    skip_without_disc!(root);
+    let snd = PakArchive::open(root.join("dat/sound.pak")).expect("sound.pak");
+    let mut with_header = 0usize;
+    let mut mid_bank = 0usize;
+    // Peek at the 56-byte header through the archive's flat data rather than
+    // decompressing 9 519 entries: `sound.pak` stores them uncompressed, and a
+    // full read of all of them is several GB (it OOM-killed the test runner).
+    for entry in snd.entries() {
+        let Some(head) = snd.data_at(entry.offset as usize, 0x38) else { continue };
+        match slb::bank_header_len(head) {
+            Some(h) => {
+                let b = snd.read(entry).expect("read a bank that states a header");
+                let ri = b.windows(4).position(|w| w == b"RIFF").expect("has a RIFF");
+                // Declared header ends exactly at the first RIFF: no gap, so
+                // nothing before it can be a packet stream.
+                assert_eq!(h, ri, "a bank header that does not end at its first RIFF");
+                with_header += 1;
+            }
+            None => mid_bank += 1,
+        }
+    }
+    // 28 music banks (ids 1001-1023, 1101-1105); the rest are mid-bank windows,
+    // where the leading region IS real and must keep being emitted.
+    assert_eq!(with_header, 28, "banks stating their own header at offset 0");
+    assert!(mid_bank > 9000, "mid-bank windows, got {mid_bank}");
+    eprintln!("{with_header} banks state a header; {mid_bank} mid-bank windows");
+}
+
+/// The regression itself: the menu's music bank is **two** sub-waves, and they
+/// are the two the corpus names — matching the executable's `BGM_103` and the
+/// two streams the runtime XMA probe saw at the main menu.
+#[test]
+fn the_menu_music_bank_is_exactly_two_sub_waves() {
+    skip_without_disc!(root);
+    let snd = PakArchive::open(root.join("dat/sound.pak")).expect("sound.pak");
+    for (name, sizes) in [
+        ("BGM_103.slb", [3_876_864usize, 3_930_112]),
+        ("BGM_001.slb", [4_466_688, 4_673_536]),
+    ] {
+        let entry = snd.find_by_name(name).expect("bank present");
+        let b = snd.read(entry).expect("read");
+        let riffs = slb::to_xma_riffs(&b);
+        assert_eq!(riffs.len(), 2, "{name}: sub-wave count");
+        for (r, want) in riffs.iter().zip(sizes) {
+            let di = r.windows(4).position(|w| w == b"data").expect("data chunk");
+            let got = u32::from_le_bytes(r[di + 4..di + 8].try_into().unwrap()) as usize;
+            assert_eq!(got, want, "{name}: sub-wave payload size");
+        }
+    }
+}

crates/sylpheed-formats/tests/ui_forced_backdrop_disc.rs

@@ -0,0 +1,197 @@
+//! An opaque full-screen primitive cannot paint above what it would hide.
+//!
+//! A keyless primitive has no layer key, and `implied_layer_key` records the
+//! handful whose position was measured in the running game. For one class the
+//! file settles it without a measurement: an element covering the screen and
+//! fully opaque at some instant cannot paint above anything visible then, or the
+//! screen is blank. Where that set is *every* other element, the position is
+//! forced to first.
+//!
+//! The port found this by contradiction on `build_12`/`build_15`, which its
+//! renderer composited to solid black at every instant of their declared life.
+//!
+//! Argument, census and reach: `docs/re/structures/ui-forced-backdrop.md`.
+
+use std::path::PathBuf;
+
+use sylpheed_formats::{pak::PakArchive, ratc, ui_layout};
+
+fn disc_root() -> Option<PathBuf> {
+    let p = PathBuf::from(std::env::var("SYLPHEED_DISC").ok()?);
+    p.join("dat").is_dir().then_some(p)
+}
+
+fn build(ar: &PakArchive, i: usize) -> (Vec<u8>, ui_layout::UiBuild) {
+    let by = ar.read(&ar.entries()[i]).expect("entry");
+    let b = ui_layout::parse_build(&by).expect("parse");
+    (by, b)
+}
+
+fn el<'a>(b: &'a ui_layout::UiBuild, name: &str) -> &'a ui_layout::Element {
+    b.elements.iter().find(|e| e.name == name).expect(name)
+}
+
+/// The two controls are measured orders from the running game. The rule has to
+/// reproduce one and permit the other, or it is not measuring occlusion.
+#[test]
+fn the_rule_reproduces_both_measured_primitives() {
+    let Some(root) = disc_root() else {
+        eprintln!("SYLPHEED_DISC unset — skipping");
+        return;
+    };
+    let ar = PakArchive::open(root.join("dat/GP_TITLE.pak")).expect("GP_TITLE.pak");
+
+    // `palogo_eff0.prm` is MEASURED painting first. Named like an overlay, so a
+    // name-based rule gets it wrong; occlusion gets it right.
+    let (_, splash) = build(&ar, 11);
+    assert!(
+        ui_layout::forced_backdrop(&splash, el(&splash, "palogo_eff0.prm")),
+        "the developer splash's backdrop is measured FIRST and must come out forced"
+    );
+
+    // `pteff00.prm` is MEASURED painting last. It is opaque only at its screen's
+    // entry and exit, so the rule must NOT force it down.
+    for entry in [4usize, 5] {
+        let (_, b) = build(&ar, entry);
+        assert!(
+            !ui_layout::forced_backdrop(&b, el(&b, "pteff00.prm")),
+            "entry {entry}: pteff00.prm is measured painting LAST and must stay permitted on top"
+        );
+    }
+}
+
+/// The case that prompted it: the loading screens.
+#[test]
+fn the_loading_screens_backdrop_sorts_first() {
+    let Some(root) = disc_root() else {
+        eprintln!("SYLPHEED_DISC unset — skipping");
+        return;
+    };
+    let ar = PakArchive::open(root.join("dat/GP_TITLE.pak")).expect("GP_TITLE.pak");
+    for entry in [12usize, 15] {
+        let (by, b) = build(&ar, entry);
+        let prim = el(&b, "pgloading_eff00.prm");
+        assert!(ui_layout::forced_backdrop(&b, prim), "entry {entry}");
+        let order = ui_layout::derived_paint_order(&b, &by);
+        assert_eq!(
+            order.first().copied(),
+            Some(prim.index),
+            "entry {entry}: the backdrop must be painted first, not last"
+        );
+    }
+}
+
+/// 🔴 The rule quantifies over "every instant the primitive is opaque" and "every
+/// element visible then", so both halves depend on where the timeline ends and on
+/// what an element does after its own last keyframe. **The hold is not a
+/// convenience: a measured order requires it.**
+///
+/// `palogo_eff0.prm` is a SINGLE keyframe at t=0. If an element counted as *gone*
+/// after its last keyframe, the splash's backdrop would exist for one instant, no
+/// other element would be up yet, and the rule would call it free — against the
+/// order measured in the running game, which paints it first.
+///
+/// Disc-wide the choice decides **72 of 130** verdicts, so this is the load-bearing
+/// half of the rule. (Using the header's declared `+0x08` as the span instead of
+/// the elements' maximum changes **0**.)
+#[test]
+fn the_hold_after_a_final_keyframe_is_required_by_a_measured_order() {
+    let Some(root) = disc_root() else {
+        eprintln!("SYLPHEED_DISC unset — skipping");
+        return;
+    };
+    let ar = PakArchive::open(root.join("dat/GP_TITLE.pak")).expect("GP_TITLE.pak");
+    for entry in [10usize, 11] {
+        let (_, b) = build(&ar, entry);
+        let prim = el(&b, "palogo_eff0.prm");
+        assert_eq!(prim.keyframes.len(), 1, "entry {entry}: the case rests on it being static");
+
+        // With the hold — what `pose_at` does, and what the game does.
+        assert!(
+            ui_layout::forced_backdrop(&b, prim),
+            "entry {entry}: measured painting FIRST, so the rule must force it"
+        );
+
+        // Without it, spelled out here rather than imported, so the test states
+        // the counterfactual it is pinning.
+        let tmax = b.elements.iter()
+            .flat_map(|e| e.keyframes.iter().filter_map(|k| k.time)).max().unwrap_or(0);
+        let last = |e: &ui_layout::Element| e.keyframes.iter().filter_map(|k| k.time).max().unwrap_or(0);
+        let alpha_no_hold = |e: &ui_layout::Element, t: u32| -> u32 {
+            if t > last(e) { 0 } else { e.pose_at(t).map(|k| k.fade >> 24).unwrap_or(0) }
+        };
+        let opaque: Vec<u32> = (0..=tmax).filter(|&t| alpha_no_hold(prim, t) == 255).collect();
+        let others: Vec<_> = b.elements.iter().filter(|o| o.index != prim.index).collect();
+        let below = others.iter()
+            .filter(|o| opaque.iter().any(|&t| alpha_no_hold(o, t) > 0)).count();
+        assert_ne!(
+            below, others.len(),
+            "entry {entry}: without the hold this element would come out FREE — which is \
+why the hold is load-bearing rather than incidental"
+        );
+    }
+}
+
+/// Disc-wide: the rule must fire on a real population and never on something it
+/// cannot occlude.
+#[test]
+fn forced_backdrops_are_full_screen_and_plentiful() {
+    let Some(root) = disc_root() else {
+        eprintln!("SYLPHEED_DISC unset — skipping");
+        return;
+    };
+    let mut paks: Vec<PathBuf> = std::fs::read_dir(root.join("dat"))
+        .expect("dat/")
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("pak"))
+        .collect();
+    paks.sort();
+    let (mut forced, mut prm, mut tbm) = (0usize, 0usize, 0usize);
+    for p in &paks {
+        let Ok(ar) = PakArchive::open(p) else { continue };
+        for e in ar.entries() {
+            let Ok(by) = ar.read(e) else { continue };
+            if !ratc::is_ratc(&by) {
+                continue;
+            }
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            for element in &b.elements {
+                if !ui_layout::forced_backdrop(&b, element) {
+                    continue;
+                }
+                forced += 1;
+                if element.name.ends_with(".prm") { prm += 1 }
+                else if element.name.ends_with(".tbm") { tbm += 1 }
+                // 🔴 Untextured only. This assertion caught the rule's real
+                // limit: applied to `.t32` sprites it claimed 22 of them must
+                // sort first, against their own layer keys — a sprite's element
+                // alpha says nothing about its texture's coverage.
+                assert!(
+                    element.sprite.is_none(),
+                    "{}: a textured sprite cannot be judged to occlude by element alpha",
+                    element.name
+                );
+                assert!(
+                    element.pivot_x * 2 >= b.design_w as u32
+                        && element.pivot_y * 2 >= b.design_h as u32,
+                    "{}: a quad that does not cover the screen cannot occlude it",
+                    element.name
+                );
+            }
+        }
+    }
+    assert!(forced > 50, "expected a real population, got {forced}");
+    eprintln!("{forced} keyless primitives have their position forced to first");
+
+    // 🔴 Pin the split, so anyone tightening this rule sees what it would cost.
+    // Only the `.prm` half is DECODED: a solid colour quad's fade IS its pixel, so
+    // opacity and coverage are the same fact. Every `.tbm` in the set carries fade
+    // `ffffffff` — a white SOLID quad painted first would make the screen white, so
+    // they are textured, and element alpha does not establish their coverage.
+    // Their verdicts are kept because restricting to `.prm` would send eleven
+    // screens' backgrounds back to last, which is the bug this rule fixed.
+    assert!(prm >= 40 && tbm >= 30,
+        "expected roughly 42 .prm / 38 .tbm forced instances, got {prm} / {tbm} — \
+if this moved, re-read the self-refutation section of ui-forced-backdrop.md");
+}

crates/sylpheed-formats/tests/ui_header_time_disc.rs

@@ -120,8 +120,17 @@ fn header_0x08_against_the_keyframe_times() {
                 worst.push(format!("{pak}: max keyframe {max_time} > header {dur}"));
             }
         }
-        let r = ((max_time as f64 / dur as f64) * 10.0).round() as u32;
-        *ratio.entry(r.min(30)).or_default() += 1;
+        // ⚠️ Bundles whose every group is a single static pose contribute
+        // `max_time == 0` and say nothing about whether `+0x08` is a length.
+        // Before 2026-08-29 they were invisible here, because the old keyframe
+        // time reading left a one-frame group's only pose untimed; the corrected
+        // record layout (`docs/re/ui-keyframe-record-layout.md`) gives it the
+        // group's lead-in time, which is 0. They are excluded rather than
+        // allowed to swamp the histogram's zero bucket — 546 of them do.
+        if max_time > 0 {
+            let r = ((max_time as f64 / dur as f64) * 10.0).round() as u32;
+            *ratio.entry(r.min(30)).or_default() += 1;
+        }
     });
 
     eprintln!("bundles with keyframe times and a non-zero +0x08: {animated}");
@@ -142,11 +151,18 @@ fn header_0x08_against_the_keyframe_times() {
 
     assert!(animated > 0, "no animated bundles — the sweep is broken");
 
-    // MEASURED 2026-08-24. +0x08 bounds the keyframe times in EVERY one of the
-    // 2313 bundles that have both, and 444 of them reach it exactly. The
+    // MEASURED 2026-08-24, re-measured 2026-08-29 under the corrected keyframe
+    // record layout. +0x08 bounds the keyframe times in EVERY one of the 2 859
+    // bundles that have both (2 313 before the correction, which could not time
+    // a group's final pose at all), and 444 of them reach it exactly. The
     // spread-out ratio histogram is what rules out the boring explanation: a
     // large unrelated constant would bound everything too, but then the ratios
     // would pile up near zero instead of peaking at 1.0.
+    //
+    // ✅ The correction STRENGTHENS this result rather than weakening it: 546
+    // more bundles now carry a readable last-pose time, and `over` is still 0 —
+    // i.e. the newly-visible times, which are the LATEST in every group, still
+    // do not run past the header's.
     assert_eq!(over, 0, "a keyframe time runs past the header's +0x08");
     assert!(exact > 400, "the bound is never attained — it may be unrelated");
     let near_one = ratio.get(&10).copied().unwrap_or(0);

crates/sylpheed-formats/tests/ui_keyframe_record_disc.rs

@@ -0,0 +1,204 @@
+//! A placement group's time word **precedes** the pose it belongs to.
+//!
+//! A group is an 8-byte header `{u32 element_index, u32 frame_count}` followed
+//! by `frame_count` records of 40 bytes, each `{u32 time; 36-byte pose}`. The
+//! parser's block window starts at the *pose*, four bytes into the record, so
+//! the word at a block's `+36` is the time of the pose that FOLLOWS it, and the
+//! first pose's time is the group's lead-in word at `header + 8`.
+//!
+//! The old reading took `+36` as the block's own time. That is off by one, and
+//! it is where two long-standing oddities came from: the group looked four bytes
+//! short, and the final pose — the end of every fade-out — carried no time.
+//!
+//! Full argument and disc-wide census: `docs/re/ui-keyframe-record-layout.md`.
+//!
+//! Two checks here, both disc-wide:
+//!
+//! 1. **Every pose is timed, and the times are non-decreasing.** Under the old
+//!    reading the last pose has no time at all, so this cannot even be asked.
+//! 2. **A monotone alpha ramp of three or more segments runs at a constant
+//!    rate.** Interpolation between keyframes is linear
+//!    (`docs/re/ui-keyframe-time-unit.md`), so a correct time assignment makes
+//!    multi-keyframe ramps come out at a constant d(alpha)/d(time). The old
+//!    reading achieves this on **zero** ramps on the whole disc.
+
+use std::path::{Path, PathBuf};
+
+use sylpheed_formats::{pak::PakArchive, ratc, ui_layout};
+
+fn disc_root() -> Option<PathBuf> {
+    if let Ok(p) = std::env::var("SYLPHEED_DISC") {
+        let p = PathBuf::from(p);
+        if p.join("dat").is_dir() {
+            return Some(p);
+        }
+    }
+    let default = Path::new(
+        "/home/fabi/RE - Project Sylpheed/Project Sylpheed - Arc of Deception (USA, Europe) (En,Ja)",
+    );
+    if default.join("dat").is_dir() {
+        return Some(default.to_path_buf());
+    }
+    None
+}
+
+fn for_each_build(root: &Path, mut f: impl FnMut(&str, &[u8])) {
+    let mut paks: Vec<PathBuf> = std::fs::read_dir(root.join("dat"))
+        .expect("dat/")
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("pak"))
+        .collect();
+    paks.sort();
+    for p in &paks {
+        let name = p.file_name().unwrap().to_string_lossy().to_string();
+        let Ok(arc) = PakArchive::open(p) else { continue };
+        for e in arc.entries() {
+            let Ok(bytes) = arc.read(e) else { continue };
+            if ratc::is_ratc(&bytes) {
+                f(&name, &bytes);
+            }
+        }
+    }
+}
+
+/// Maximal runs of strictly monotone alpha with at least `min_seg` segments.
+fn monotone_ramps(alphas: &[i32], min_seg: usize) -> Vec<(usize, usize)> {
+    let mut out = Vec::new();
+    let (mut i, n) = (0usize, alphas.len());
+    while i + 1 < n {
+        if alphas[i] == alphas[i + 1] {
+            i += 1;
+            continue;
+        }
+        let up = alphas[i + 1] > alphas[i];
+        let mut j = i + 1;
+        while j + 1 < n && ((alphas[j + 1] > alphas[j]) == up) && alphas[j + 1] != alphas[j] {
+            j += 1;
+        }
+        if j - i >= min_seg {
+            out.push((i, j));
+        }
+        i = j;
+    }
+    out
+}
+
+fn constant_rate(times: &[u32], alphas: &[i32], a: usize, b: usize) -> Option<bool> {
+    let mut rates = Vec::new();
+    for k in a..b {
+        let dt = times[k + 1].checked_sub(times[k])?;
+        if dt == 0 {
+            return None;
+        }
+        rates.push((alphas[k + 1] - alphas[k]).unsigned_abs() as f64 / dt as f64);
+    }
+    let mean = rates.iter().sum::<f64>() / rates.len() as f64;
+    if mean == 0.0 {
+        return None;
+    }
+    let worst = rates.iter().map(|r| (r - mean).abs()).fold(0.0, f64::max);
+    Some(worst / mean <= 0.06)
+}
+
+#[test]
+fn every_pose_is_timed_and_the_times_are_ordered() {
+    let Some(root) = disc_root() else {
+        eprintln!("SKIP: extracted disc not found (set SYLPHEED_DISC to enable)");
+        return;
+    };
+    if std::env::var("SYLPHEED_KF_TIME_LEGACY").as_deref() == Ok("1") {
+        eprintln!("SKIP: the legacy time reading is selected");
+        return;
+    }
+
+    let (mut groups, mut untimed, mut out_of_order) = (0usize, 0usize, 0usize);
+    let mut examples: Vec<String> = Vec::new();
+    for_each_build(&root, |pak, bytes| {
+        let Some(build) = ui_layout::parse_build(bytes) else {
+            return;
+        };
+        if build.from_fallback {
+            return;
+        }
+        for el in &build.elements {
+            if el.keyframes.is_empty() {
+                continue;
+            }
+            groups += 1;
+            if el.keyframes.iter().any(|k| k.time.is_none()) {
+                untimed += 1;
+                if examples.len() < 8 {
+                    examples.push(format!("{pak}: {} has an untimed pose", el.name));
+                }
+                continue;
+            }
+            let t: Vec<u32> = el.keyframes.iter().map(|k| k.time.unwrap()).collect();
+            if t.windows(2).any(|w| w[1] < w[0]) {
+                out_of_order += 1;
+                if examples.len() < 8 {
+                    examples.push(format!("{pak}: {} times {t:?} descend", el.name));
+                }
+            }
+        }
+    });
+
+    eprintln!("placement groups: {groups}; untimed: {untimed}; out of order: {out_of_order}");
+    for e in &examples {
+        eprintln!("  {e}");
+    }
+    assert!(groups > 10_000, "expected the whole disc, saw {groups} groups");
+    assert_eq!(untimed, 0, "every pose must carry a time");
+    assert_eq!(out_of_order, 0, "keyframe times must not descend");
+}
+
+#[test]
+fn multi_segment_alpha_ramps_run_at_a_constant_rate() {
+    let Some(root) = disc_root() else {
+        eprintln!("SKIP: extracted disc not found (set SYLPHEED_DISC to enable)");
+        return;
+    };
+    if std::env::var("SYLPHEED_KF_TIME_LEGACY").as_deref() == Ok("1") {
+        eprintln!("SKIP: the legacy time reading is selected");
+        return;
+    }
+
+    let (mut ramps, mut constant) = (0usize, 0usize);
+    for_each_build(&root, |_pak, bytes| {
+        let Some(build) = ui_layout::parse_build(bytes) else {
+            return;
+        };
+        if build.from_fallback {
+            return;
+        }
+        for el in &build.elements {
+            if el.keyframes.iter().any(|k| k.time.is_none()) {
+                continue;
+            }
+            let t: Vec<u32> = el.keyframes.iter().map(|k| k.time.unwrap()).collect();
+            let a: Vec<i32> = el
+                .keyframes
+                .iter()
+                .map(|k| ((k.fade >> 24) & 0xff) as i32)
+                .collect();
+            for (lo, hi) in monotone_ramps(&a, 3) {
+                if let Some(ok) = constant_rate(&t, &a, lo, hi) {
+                    ramps += 1;
+                    constant += usize::from(ok);
+                }
+            }
+        }
+    });
+
+    let share = 100.0 * constant as f64 / ramps as f64;
+    eprintln!("multi-segment alpha ramps: {constant}/{ramps} at a constant rate ({share:.1}%)");
+    assert!(ramps > 500, "expected the whole disc, saw {ramps} ramps");
+    // The old reading scores 0 of 1042. Half is a floor, not a target: the rest
+    // are genuinely shaped ramps, authored with keyframes that are not evenly
+    // spaced. Anything near zero means the time assignment has slipped again.
+    assert!(
+        share > 45.0,
+        "only {share:.1}% of ramps run at a constant rate — the time \
+         association has probably slipped (the old off-by-one scored 0%)"
+    );
+}

crates/sylpheed-formats/tests/ui_record_loop_length_disc.rs

@@ -0,0 +1,121 @@
+//! A nested record's header `+0x08` is its LOOP LENGTH, and its keyframes need
+//! not fill it.
+//!
+//! A `*f` focus record animates for as long as its button is focused, so
+//! something has to say where the cycle restarts. The keyframes cannot: the
+//! `PRESS Ⓐ` plate's `ptbtn00f` ramps 0→80→0 over **105** units, and a 105-unit
+//! period is 15 % short of every measurement of the real thing.
+//!
+//! Each record is itself a RATC bundle with its own header. `+0x08` is a frame
+//! count, and if it is the loop length it must never be **less** than the
+//! record's largest keyframe time — an animation cannot restart before its own
+//! last pose. Disc-wide that holds 1 781 times out of 1 781, and 7.7 % of records
+//! declare *more*, which is a hold at the final pose before the cycle repeats.
+//!
+//! `ptbtn00f` is one of those: 105 units of ramp inside a **120**-unit cycle, so
+//! it rests dark for 15 units between pulses.
+//!
+//! Argument, the falsification test against the measured period, and the census:
+//! `docs/re/structures/ui-record-loop-length.md`.
+
+use std::path::PathBuf;
+
+use sylpheed_formats::{pak::PakArchive, ratc, ui_layout};
+
+fn disc_root() -> Option<PathBuf> {
+    let p = PathBuf::from(std::env::var("SYLPHEED_DISC").ok()?);
+    p.join("dat").is_dir().then_some(p)
+}
+
+/// Read a nested record's declared length and its largest keyframe time.
+fn record_len_and_maxt(bundle: &[u8], off: usize, size: usize) -> Option<(i64, i64)> {
+    if off + 12 > bundle.len() || off + size > bundle.len() || &bundle[off..off + 4] != b"RATC" {
+        return None;
+    }
+    let len = u32::from_be_bytes(bundle[off + 8..off + 12].try_into().ok()?) as i64;
+    let lb = ui_layout::parse_build(&bundle[off..off + size])?;
+    let maxt = lb
+        .elements
+        .iter()
+        .flat_map(|el| el.keyframes.iter().filter_map(|k| k.time))
+        .max()? as i64;
+    (maxt > 0).then_some((len, maxt))
+}
+
+/// The falsifier: a loop cannot restart before its own last keyframe.
+#[test]
+fn a_records_declared_length_is_never_shorter_than_its_keyframes() {
+    let Some(root) = disc_root() else {
+        eprintln!("SYLPHEED_DISC unset — skipping");
+        return;
+    };
+    let mut paks: Vec<PathBuf> = std::fs::read_dir(root.join("dat"))
+        .expect("dat/")
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("pak"))
+        .collect();
+    paks.sort();
+
+    let (mut total, mut exact, mut holds) = (0usize, 0usize, 0usize);
+    for p in &paks {
+        let Ok(ar) = PakArchive::open(p) else { continue };
+        for e in ar.entries() {
+            let Ok(by) = ar.read(e) else { continue };
+            if !ratc::is_ratc(&by) {
+                continue;
+            }
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            for (rn, &(o, s)) in &b.records {
+                let Some((len, maxt)) = record_len_and_maxt(&by, o, s) else { continue };
+                total += 1;
+                assert!(
+                    len >= maxt,
+                    "{}:{rn} declares a {len}-unit cycle but has a keyframe at t={maxt} — \
+a loop cannot restart before its own last pose",
+                    p.file_name().unwrap().to_string_lossy()
+                );
+                if len == maxt { exact += 1 } else { holds += 1 }
+            }
+        }
+    }
+    assert!(total > 1500, "expected >1500 timed nested records, got {total}");
+    // The field must carry information. If every record declared exactly its own
+    // last keyframe time, "loop length" would be an unfalsifiable relabelling.
+    assert!(
+        holds > 50,
+        "only {holds} of {total} records declare a hold — the field would be carrying nothing"
+    );
+    eprintln!("{total} records: {exact} exact, {holds} with a hold before the cycle repeats");
+}
+
+/// The case that motivated it, pinned by name.
+#[test]
+fn the_press_a_plate_glow_holds_dark_for_fifteen_units() {
+    let Some(root) = disc_root() else {
+        eprintln!("SYLPHEED_DISC unset — skipping");
+        return;
+    };
+    let ar = PakArchive::open(root.join("dat/GP_TITLE.pak")).expect("GP_TITLE.pak");
+    let by = ar.read(&ar.entries()[2]).expect("entry 2 — the PRESS A plate");
+    let b = ui_layout::parse_build(&by).expect("parse");
+    let &(o, s) = b.records.get("ptbtn00f.rat").expect("the focus record");
+    let (len, maxt) = record_len_and_maxt(&by, o, s).expect("a timed record");
+    assert_eq!(maxt, 105, "the glow's ramp ends at t=105");
+    assert_eq!(len, 120, "but the cycle is 120 units");
+    assert_eq!(len - maxt, 15, "so it holds dark for 15 units between pulses");
+
+    // The five main-menu focus records fill their cycle exactly — the contrast
+    // that shows the slack is a property of this record, not of the format.
+    let menu = ar.read(&ar.entries()[5]).expect("entry 5 — the main menu");
+    let mb = ui_layout::parse_build(&menu).expect("parse");
+    let mut checked = 0;
+    for n in 1..=5 {
+        let name = format!("ptbtn0{n}f.rat");
+        let Some(&(mo, ms)) = mb.records.get(&name) else { continue };
+        let (l, m) = record_len_and_maxt(&menu, mo, ms).expect("timed");
+        assert_eq!((l, m), (120, 120), "{name} should fill its 120-unit cycle exactly");
+        checked += 1;
+    }
+    assert_eq!(checked, 5, "expected five main-menu focus records");
+}

crates/sylpheed-formats/tests/ui_settle_time_disc.rs

@@ -0,0 +1,142 @@
+//! A settled screen is one INSTANT, not one hold per element.
+//!
+//! `Element::rest()` returns an element's last *hold* keyframe, picked for that
+//! element alone. For anything that ends the screen settled that is right. For a
+//! **transient** it is exactly wrong: a two-frame flash's last hold is the flash
+//! *peak*, so `rest()` leaves it burning for the whole screen.
+//!
+//! `GP_TITLE` build 4 is the case that found this. `ptlogo_back2eff1` … `eff5`
+//! are five staggered flashes — `a=0` until t52, `255` for two frames, `0` again
+//! two frames later — that sweep left to right across the logo once and are gone
+//! by t110. Two elements, `ptlogo_back2eff` (t66–238) and `ptlogo_back2`
+//! (t80–243), then hold for the rest of the screen. `rest()` draws all seven at
+//! `a=255` simultaneously, and stacking five extra white glows blows the light
+//! arc out to saturation: against the console capture the arc's mean error is
+//! 33.22 and 8 581 pixels sit at the clipping level, where the console has 1 459.
+//!
+//! `UiBuild::settle_time()` recovers the right instant from the disc alone — the
+//! midpoint of the longest keyframe-free interval — with no reference to any
+//! capture. For this build that is t=198, and posing there takes the arc error to
+//! 11.79 and the clipped count to 1 452 against the console's 1 459.
+//!
+//! Argument, controls and the disc-wide census: `docs/re/structures/ui-settle-time.md`.
+
+use std::path::PathBuf;
+
+use sylpheed_formats::{pak::PakArchive, ratc, ui_layout};
+
+fn disc_root() -> Option<PathBuf> {
+    if let Ok(p) = std::env::var("SYLPHEED_DISC") {
+        let p = PathBuf::from(p);
+        if p.join("dat").is_dir() {
+            return Some(p);
+        }
+    }
+    None
+}
+
+/// The case that found the bug, asserted end to end.
+#[test]
+fn a_flash_is_transparent_at_the_settle_time_and_opaque_at_rest() {
+    let Some(root) = disc_root() else {
+        eprintln!("SYLPHEED_DISC unset — skipping");
+        return;
+    };
+    let arc = PakArchive::open(root.join("dat/GP_TITLE.pak")).expect("GP_TITLE.pak");
+    let bytes = arc.read(&arc.entries()[4]).expect("build 4");
+    let b = ui_layout::parse_build(&bytes).expect("parse");
+
+    let (lo, hi) = b.settle_window().expect("a settle window");
+    let t = b.settle_time().expect("a settle time");
+    assert!(hi - lo >= 60, "title's settle window should be a second or more, got {lo}..{hi}");
+    assert!(lo < t && t < hi, "settle time {t} must lie inside {lo}..{hi}");
+
+    let alpha = |k: &ui_layout::Keyframe| k.fade >> 24;
+    let mut flashes = 0;
+    for el in &b.elements {
+        let Some(name) = el.name.strip_prefix("ptlogo_back2eff") else { continue };
+        // `ptlogo_back2eff.t32` itself holds; only the numbered ones flash.
+        if !name.starts_with(|c: char| c.is_ascii_digit()) {
+            continue;
+        }
+        flashes += 1;
+        let rest = el.rest().expect("a rest pose");
+        let posed = el.pose_at(t).expect("a posed keyframe");
+        assert_eq!(
+            alpha(rest),
+            255,
+            "{}: rest() is expected to report the FLASH PEAK — that is the bug",
+            el.name
+        );
+        assert_eq!(
+            alpha(&posed),
+            0,
+            "{} flashes once before t110 and must be gone at the settle time {t}",
+            el.name
+        );
+    }
+    assert_eq!(flashes, 5, "GP_TITLE build 4 has five numbered back2 flashes");
+
+    // …while the two that genuinely hold are still opaque there.
+    for want in ["ptlogo_back2eff.t32", "ptlogo_back2.t32"] {
+        let el = b.elements.iter().find(|e| e.name == want).expect(want);
+        assert_eq!(
+            alpha(&el.pose_at(t).expect("posed")),
+            255,
+            "{want} holds across the settle time and must stay opaque"
+        );
+    }
+}
+
+/// The window is a property of the data, so it must be computable disc-wide
+/// without panicking, and must be self-consistent wherever it exists.
+#[test]
+fn settle_windows_are_self_consistent_disc_wide() {
+    let Some(root) = disc_root() else {
+        eprintln!("SYLPHEED_DISC unset — skipping");
+        return;
+    };
+    let mut paks: Vec<PathBuf> = std::fs::read_dir(root.join("dat"))
+        .expect("dat/")
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("pak"))
+        .collect();
+    paks.sort();
+
+    let (mut with, mut wide) = (0usize, 0usize);
+    for p in &paks {
+        let Ok(a) = PakArchive::open(p) else { continue };
+        for e in a.entries() {
+            let Ok(by) = a.read(e) else { continue };
+            if !ratc::is_ratc(&by) {
+                continue;
+            }
+            let Some(b) = ui_layout::parse_build(&by) else { continue };
+            let Some((lo, hi)) = b.settle_window() else { continue };
+            with += 1;
+            assert!(lo < hi, "an empty window is not a window: {lo}..{hi}");
+            let t = b.settle_time().expect("a window implies a time");
+            assert!((lo..=hi).contains(&t), "settle time {t} outside {lo}..{hi}");
+            // No element may have a keyframe strictly inside the window — that
+            // is the whole definition, so it is worth asserting rather than
+            // trusting.
+            for el in &b.elements {
+                for k in &el.keyframes {
+                    if let Some(kt) = k.time {
+                        assert!(
+                            kt <= lo || kt >= hi,
+                            "{}: keyframe t={kt} lies inside the settle window {lo}..{hi}",
+                            el.name
+                        );
+                    }
+                }
+            }
+            if hi - lo >= 30 {
+                wide += 1;
+            }
+        }
+    }
+    assert!(with > 1000, "expected >1000 bundles with a settle window, got {with}");
+    eprintln!("{with} bundles have a settle window; {wide} are at least 30 units wide");
+}

docs/agents/CONTAINER-NOTES.md

@@ -12,6 +12,17 @@ already went wrong once.
 * **The toolchain is real.** `tools/re-capture/rebuild_canary.sh` exists because
   the old box had no cmake/ninja/clang and only runtime sonames, so it hand-
   relinked object files. **Do not use it here.** Use `build-canary`.
+  🔴 **But `build-canary` does not work in this container as it stands
+  (2026-08-29).** It builds `${PROJECT_DIR:-/work}/xenia-canary`, which **does
+  not exist here** — the Canary source is at **`/canary`** (`$XENIA_SRC`). The
+  warm 235 MB tree at `/sylph-home/re/canary-build` is configured with
+  `CMAKE_HOME_DIRECTORY=/work/xenia-canary`, also missing, and its
+  `build-Release.ninja` carries **no per-file rules** — it wants to re-run CMake
+  first, which would fail on the absent source root. **So any Canary change is a
+  full reconfigure against `/canary` plus a full compile**, not an incremental
+  one. Budget for that before starting: `SYLPH_JOBS=4`, and this box has been
+  sitting at **~700 MB free** with a documented history of full-parallel builds
+  OOM-killing the host.
 * **numpy and Pillow are installed.** `entities2.py`, `flight_probe.py` and the
   image oracles work. Their absence used to look like a logic bug.
 
@@ -40,6 +51,71 @@ python3 tools/re-capture/gmem.py find hex:820af844 400
 ```
 
 * **One emulator at a time.** `run-canary` enforces it with a lockfile.
+* 🔴 **`run-canary` is SILENT TWICE OVER, and that defeats `audio-capture`.**
+  Line 82 is `export SDL_AUDIODRIVER="${SDL_AUDIODRIVER:-dummy}"`, and its
+  header explains why: `--apu=nop` stalls the guest in the intro movie, so the
+  SDL driver against a *dummy* device is what lets the title advance. The
+  comment's premise — "there is no PulseAudio here" — **stopped being true when
+  `tools/audio-capture` landed**, and it starts a daemon on demand.
+  So a capture through the null sink records **pure silence**, at the right
+  length, with a perfectly healthy-looking run behind it. To actually record the
+  game:
+
+  ⚠️ **And that is only the first of TWO layers.** `run-canary` also passes
+  **`--mute=true`** on its own command line (line 98). With the driver fixed and
+  the mute left alone, Canary attaches a healthy 6-channel stream to the sink,
+  holds it at 100 % volume for the whole run — and emits silence. Both have to go:
+
+  ```bash
+  audio-capture start                     # or load a null sink yourself
+  PULSE_SINK=cap SDL_AUDIODRIVER=pulseaudio \
+    run-canary --mute=false …             # `"$@"` is last, so this wins
+  ```
+
+  Record at the monitor's real format, too — `parec` defaults to stereo/44.1 kHz
+  and will silently resample a 6-channel monitor:
+  `parec -d cap.monitor --channels=6 --rate=48000 --format=s16le`.
+
+  🔴 **And even with both mutes off, a PulseAudio-monitor capture is not
+  faithful — use the ALSA tee instead.** A null sink's *monitor* is sampled on a
+  wall clock and **invents silence** whenever the client is late, so a capture
+  through it is 39 % holes that the game never emitted. `PULSE_LATENCY_MSEC`
+  only trades gap count against gap size and never wins.
+  ✅ **The working route is `--apu=alsa` with an ALSA `file` tee in front of a
+  paced slave** — full recipe, controls and three configuration traps in
+  [`audio-capture-alsa-file-tee.md`](../re/audio-capture-alsa-file-tee.md).
+* 🔴 **A BARE ALSA `file` tee WILL FILL THE DISK — always run a size guard.**
+  Xenia's ALSA writer thread pads silence whenever its ring is empty
+  (`alsa_audio_driver.cc:359`), so against a device that never blocks it
+  free-runs: measured at **~250× real time, 7.34 GB in 50 seconds**. The slave
+  must pace — `slave.pcm { type pulse }` — and the capture loop should abort
+  above ~3× real time. The next person to try a bare tee hits this in the first
+  minute.
+* ✅ **And use `--gpu=null` for an audio capture.** It is what takes the guest
+  from 0.70× to **0.96×** real time, which stops Xenia padding at all: 0.31 %
+  silence and 0.01 gaps/s, against 9.98 % / 8.37 rendered. ⚠️ No video, so
+  screen-based provenance is unavailable (use the XMA probe), and `--gpu=null`
+  runs here die at ~70 s with `PM4_DRAW_INDX: Failed in backend`.
+  🔴 **REFUTED 2026-08-30 — that lifetime does not hold.** A `--gpu=null` capture
+  ran **148.02 s** and ended on its own probe's timer with the emulator still
+  alive, having decoded the whole `ADV` movie
+  ([`intro-audio-output-census.md`](../re/structures/intro-audio-output-census.md)).
+  More than twice the quoted figure. Whatever produced the ~70 s was fixed or was
+  never general, and this note had been the reason not to use `--gpu=null` for
+  anything long — which is exactly the configuration a clean audio capture needs.
+
+  ⚠️ **Do not read Canary's 6-channel PulseAudio stream as evidence the GAME is
+  5.1.** `pactl` will show `float32le 6ch 48000Hz`, channel-mapped to a full 5.1
+  layout, on any title. That is `AudioDriver::kFrameChannelsDefault = 6`, a
+  hardcoded constant — the code path actually used
+  (`SDLAudioSystem::CreateDriver(index, semaphore, &driver)`) constructs
+  `SDLAudioDriver(semaphore)` and takes every default. The *format* is Xenia's;
+  only the *content* of those six channels is the guest's.
+
+  ⚠️ **Check `pactl list sink-inputs` before trusting a recording.** If it is
+  empty, Canary never attached and you are recording zeroes; the sink also sits
+  at `IDLE`. `audio-capture run` warns on a `-inf` peak afterwards, which is the
+  backstop — but a live check fails in seconds instead of after the whole run.
 * Boot is slow cold, ~25 s once the shader/code caches are warm — so a
   launch-and-dump fits in a single call.
 * **Screens: classify by whole-image statistics** (`screen_id.py`), not named
@@ -49,7 +125,19 @@ python3 tools/re-capture/gmem.py find hex:820af844 400
 ## Verifying your own work
 
 * Reborn's disc-gated tests **self-skip** without `SYLPHEED_DISC`. A green run
-  with it unset means almost nothing. `build-reborn test` wires it up for you.
+  with it unset means almost nothing.
+  🔴 **But `build-reborn` does not work in this container (2026-08-29).** Line 15
+  is `SRC="${PROJECT_DIR:-/work}/Syplheed-Reborn"` — note the transposed letters —
+  and no such directory exists; the workspace is at **`/work`** itself. It fails
+  immediately with `cd: /work/Syplheed-Reborn: No such file or directory`, so the
+  documented way to run the disc-gated tests is broken.
+  ✅ **Run them directly instead**, setting the variable yourself:
+  ```bash
+  SYLPHEED_DISC=/disc cargo test -p sylpheed-formats --test <name>
+  ```
+  ⚠️ This is the **second** wrapper in this container pointing at a source root
+  that does not exist — `build-canary` has the same defect. Check a wrapper's
+  `SRC` before trusting that a green or a failure came from your code.
 * Prefer a headless self-verify over "it compiles": `sylpheed-cli mesh render`,
   `screen render`, `save info` all produce checkable artifacts.
 * A Bevy system-parameter conflict is invisible to the type checker and panics
@@ -125,3 +213,61 @@ XEX decrypt + LZX decompress, and the disassembly-to-database step — belongs i
 `crates/sylpheed-formats`.** Until then, every static finding rests on an
 artefact this project cannot rebuild, and that is a real gap in the corpus rather
 than a convenience.
+
+## 🔴 Pressing Ⓐ on the title faults the guest — and the fault fills the disk
+
+Three attempts to capture the main menu on 2026-08-29 ended the same way. Every
+run that tapped Ⓐ **on the title** faulted; every run that tapped nothing there
+completed and produced its capture.
+
+| run | input on the title | outcome |
+|---|---|---|
+| 1 | Ⓐ, then Ⓐ again on the transition | guest fault, **519 MB** of register dump |
+| 2 | one Ⓐ | drifted to a `flight` classification, 97 MB |
+| 3 | one Ⓐ | guest fault, **223 MB** of register dump |
+| 4–6 | none (`NOTAP=1`) | all completed normally |
+
+This is the crash `ui_draw_capture.sh`'s own header records from 2026-08-18 — "a
+stray A there sends the guest into the save-data probe". ⚠️ The corpus's existing
+menu measurements (Q4, Q5, the focus ring) were taken by some route that survived
+this; what differs has not been found. **Menu-side dynamic RE is blocked until it
+is.**
+
+⚠️ **A guest fault writes an UNBOUNDED register dump to stdout.** Xenia runs with
+`break_on_unimplemented_instructions = true`, and the dump is `vN = [...]` / `rN =
+...` lines at roughly 100 MB per 30 s. The filesystem here sits at **91 %**. Any
+scripted run that presses a button must watch `canary.stdout` and kill on growth —
+`ls -la` on it before trusting a long run.
+
+📌 Two knobs added to `ui_draw_capture.sh` for boot-side work: `GRACE=1` (the fixed
+8 s wait before arming means an `ARM=early` capture otherwise misses both splashes,
+which run at ~1.2–9.5 s of guest time) and `NOTAP=1` (no input at all — the movie
+tap fires on "the screen changed a lot", which is also true of a fading splash).
+
+### ⚠️ `ARM=early` loses its F10 about 40 % of the time
+
+Five `ui_draw_capture.sh ARM=early` runs on 2026-08-29: **two logged `ARMED EARLY`
+and produced no `xenia_re_ui_draws_NN.log` at all.** The keypress goes to the
+window and is silently lost — nothing in the session log distinguishes a run that
+armed from one that did not, so **check the log file exists before spending the
+run**, and treat a repeat measurement as needing more attempts than samples.
+
+* 🔴 **`sylpheed-cli` in `$CARGO_TARGET_DIR` can be STALE, and `screen info` lies
+  quietly when it is.** The copy here was built **2026-08-29 12:38**, before the
+  keyframe-record-layout fix. The old parser shifted every keyframe time by one slot
+  and could not time a group's final pose, printing a trailing `-`:
+
+  ```
+  stale  pteff00.prm  4 kf  rest t=70   [12:0,0  70:0,0  80:0,0  -:0,0]
+  fresh  pteff00.prm  4 kf  rest t=12   [ 0:0,0  12:0,0  70:0,0  80:0,0]
+  ```
+
+  Both outputs are well-formed and neither announces its age. A whole page of this
+  corpus (`screen-transitions.md`) argued from *"there is exactly one untimed
+  keyframe"*, which was the stale parser's artefact.
+
+  ⚠️ **`cargo build -p sylpheed-cli` before trusting `screen info`** — it takes 8 s
+  against a warm cache. ✅ Renders are **byte-identical** across the two binaries
+  (checked on `GP_TUTORIAL` build 0, max per-channel difference **0**), so
+  `screen render` output and anything derived from element identity, pivots or
+  keyframe *counts* is unaffected. It is the *times* that move.

docs/game/navigation.md

@@ -7,8 +7,9 @@ and wants to reach a mission — or who needs to script that journey.
 Internal names (`ptbtn03`, `GP_LOAD`, build numbers) appear only as footnotes,
 because they are how *we* find things, not what the game shows anyone.
 
-**Status:** skeleton. Most of it is ❔ and is *meant* to be — this page exists to
-be filled in by playing, not to look finished.
+**Status:** filling in. §1–§4 now carry what the committed oracle frames actually
+show; what is still ❔ is what no capture answers. This page exists to be filled
+in by playing, not to look finished.
 
 > ## ⚠️ Fill this in from the real game
 >
@@ -28,10 +29,29 @@ Confidence: ✅ seen in a capture · 🟡 inferred · ❔ unknown.
 
 | # | What you see | What you do | What happens |
 |---|---|---|---|
-| 1 | Publisher and developer logos on black | nothing | plays through 🟡 |
-| 2 | The opening cinematic | ❔ can it be skipped, and with which button? | ends into the title 🟡 |
-| 3 | **Title screen** — the wordmark animates in, then a prompt | press **Ⓐ** | goes to the main menu ✅ |
-| 4 | **Main menu** | — | see §2 |
+| 1 | **SQUARE ENIX** in white on black, the two dots in red, `™` after it ✅ | nothing | fades on to the next logo |
+| 2 | **GAME ARTS**, **SETA** and **studio anima** stacked on black ✅ | nothing | fades on into the cinematic |
+| 3 | The opening cinematic | **Ⓐ** skips it ✅ | ends into the title |
+| 4 | **Title screen** — the wordmark appears **first, with no prompt**; `PRESS Ⓐ BUTTON` fades in **2.13 s** later, above the 2006/2007 Square Enix copyright line, and then pulses about every 2.2 s ✅ | press **Ⓐ** | goes to the main menu ✅ |
+| 5 | **Main menu** | — | see §2 |
+
+✅ **The order is publisher then developer, confirmed in three cold boots
+(2026-08-29)** — `SQUARE ENIX` for ~4.3 s, a ~0.25 s black hold, then
+`GAME ARTS` / `SETA` / `studio anima` for ~3.5 s, and both dwells are declared on
+the disc (240 and 195 keyframe units). ⚠️ There is a **third** SQUARE ENIX
+wordmark about ten seconds in — bloomed, below centre — and it is the opening
+card of the intro movie, not a splash.
+[the three frames side by side](../re/captures/boot-order/splash-order-two-runs.png) ·
+[`boot-order-and-splash-dwell.md`](../re/boot-order-and-splash-dwell.md)
+
+Both logo screens are **still pictures the game draws**, not video — neither is a
+`.wmv` on the disc. Captures:
+[publisher](../re/captures/title-builds/live-splash-publisher.png) ·
+[developer](../re/captures/title-builds/live-splash-developer.png) ·
+[title](../re/captures/title-builds/live-title-press-a.png).
+
+⚠️ **One Ⓐ skips the cinematic**, and it is worth a lot of time: the title
+arrived at **57 s** with the skip against **193 s** without it ✅.
 
 ⚠️ **The title screen has two states that look identical.** The one that ends
 the boot accepts Ⓐ. The one the attract loop returns to, after the game has sat
@@ -43,6 +63,21 @@ boot.
 ⚠️ **The title is not input-ready for about ten seconds** after it appears ✅.
 And even then Ⓐ registers roughly half the time, with nothing yet found that
 predicts which ✅ — budget retries.
+🔴 **Refutation attempt, 2026-08-29 — both halves of that came out wrong on the
+runs I could test.** Two boots, Ⓐ pressed **7.29 s** and **7.28 s** after the
+title art settled (5.15 s and 5.15 s after the prompt appeared): **accepted both
+times, first press, no retry**, and each went straight on to the main menu. Ⓑ on
+the menu was then also accepted first press, both runs.
+⚠️ Reach: **n = 2**, so "half the time" is only made unlikely (2/2 has p ≈ 0.25
+under it), not excluded — but *"not input-ready for about ten seconds"* is
+contradicted outright, because 7.3 s worked twice. Keep the retry budget; drop
+the ten-second wait. Evidence:
+[run 1](../re/data/plate-timing-run1.tsv) · [run 2](../re/data/plate-timing-run2.tsv) ·
+[`title-plate-delay-measured.md`](../re/title-plate-delay-measured.md).
+
+⚠️ **The prompt takes 2.13 s to arrive, measured twice (2.138 s / 2.132 s).**
+Timed from the moment the wordmark stops animating, not from the moment it first
+appears — the build-in itself varies by half a second between runs.
 
 ---
 
@@ -51,18 +86,57 @@ predicts which ✅ — budget retries.
 Five options in a vertical stack, roughly centred, with a highlighted state on
 the focused one.
 
+> ✅ **The focused option carries a small ring to the left of its label, and the
+> ring turns — continuously, about once every 2.2 s.** It has a bright head, so
+> you can see it go round. It is the **only** thing moving on this screen once it
+> has settled: the labels, the bracket and the footer are all completely still
+> (temporal std exactly 0.000 over 20 s). Ⓑ
+> [five frames, 4 s apart](../re/captures/focus-ring/ring-single-frames-4s-apart.png) ·
+> [the measurement](../re/focus-ring-spin-measured.md)
+
 | position | label | what it opens |
 |---|---|---|
-| 1 | ❔ | ❔ |
-| 2 | ❔ | ❔ |
-| 3 | ❔ | ❔ |
-| 4 | ❔ | ❔ |
-| 5 | ❔ | ❔ |
+| 1 | **NEW GAME** | a **DIFFICULTY** prompt, then **SELECT DATA** ✅ |
+| 2 | **LOAD GAME** | the save-slot list ✅ |
+| 3 | **TUTORIAL** | the lesson list ✅ |
+| 4 | **OPTIONS** | the settings menu ✅ |
+| 5 | **EXTRAS** | a three-item submenu ✅ |
 
-**To fill in, by looking:** read the five labels off the screen and say what each
-one leads to. ❔ Which item is focused when the menu opens · ❔ does the cursor
-wrap from the last item back to the first · ❔ does left/right do anything ·
-❔ what B does here — back to the title, or nothing.
+Read off [`live-main-menu.png`](../re/captures/title-builds/live-main-menu.png);
+destinations off
+[`q4-destinations.png`](../re/captures/menu-nav/q4-destinations.png) and
+[`newgame-difficulty.png`](../re/captures/newgame-path/newgame-difficulty.png).
+
+The screen is the title art gone dim, with the wordmark ghosted behind the list
+and a bracket of glowing rule-lines drawn around it. The focused item is bright
+white with a **spinning ring** to its left; the others are dim blue. Every item
+carries a small dot-in-circle at the left end of its underline — that is on all
+five all the time and is *not* the cursor.
+
+**Moving around ✅**
+
+| you press | what happens |
+|---|---|
+| ⬆ / ⬇ | one item, and it **wraps** at both ends |
+| ⬅ / ➡ | nothing |
+| Ⓐ | opens the focused item |
+| Ⓑ | 🟡 back to the title — see the warning below |
+
+❔ **Which item is focused when the menu opens is not fixed.** Four boots of the
+same harness opened on `TUTORIAL`, `TUTORIAL`, `NEW GAME`, `NEW GAME`. Do not
+assume the top item, and do not assume the middle one either.
+
+> ⚠️ **The main menu is the one screen whose footer does not offer Ⓑ.** It reads
+> `⊙ : Select   Ⓐ : OK` — every submenu adds `Ⓑ : Back`. Measured: **zero**
+> red-Ⓑ glyph pixels anywhere in the frame, on two captures, with the same
+> detector finding the glyph on `EXTRAS` and `DIFFICULTY` ✅.
+> ✅ **But Ⓑ does leave it, and the objection that stood here is refuted
+> (2026-08-29).** This page used to say the title "returns on its own after
+> ~8–10 s idle", so an observer could not tell Ⓑ from the timer. That timer
+> belongs to the **title**, not to this screen: the main menu was held untouched
+> for **≥ 60 s** and never moved. Ⓑ is delivered and is the only input in ≥ 100 s
+> before the return, so the ordering is measured — the *latency* is not
+> ([the measurement](../re/menu-idle-and-b-2026-08-29.md)).
 
 *Internals: `GP_TITLE.pak` build 5; buttons `ptbtn01`–`ptbtn05` top to bottom.*
 
@@ -73,26 +147,82 @@ wrap from the last item back to the first · ❔ does left/right do anything ·
 One section each, in the shape of §2: what is on screen, what the cursor does,
 what each choice leads to, and what a wrong choice shows you.
 
-### Continue / Load ❔
-❔ How saves are listed · ❔ what an empty slot looks like · ❔ the confirmation
-prompt and where the cursor starts.
+### New game ✅
+Ⓐ on `NEW GAME` does **not** start a mission. It opens **DIFFICULTY** —
+`EASY` / `NORMAL` / `HARD` / `BACK`, opening focused on **NORMAL** ✅ — and Ⓐ
+there opens **SELECT DATA**, a save-slot picker headed
+`Current Storage: Dummy HDD` that asks you to choose a file for the auto-save.
+Pick one and a movie plays ✅.
+[DIFFICULTY](../re/captures/difficulty-screen.png)
+
+### Load game ✅
+A vertical list of numbered slots, **8 rows visible**, scrolling as a carousel —
+one capture shows the order `19, 20, 01, 02, 03, 04` with `01` focused, so the
+list runs past the end and back round to the start ✅. Each row shows
+`Difficulty`, `Flight Time` and `Clear Ratio`; a **Details** panel to the right
+gives `STAGE`, `Game Status`, `Points` and `Times Cleared`, and an empty slot
+leaves every one of those blank ✅. `Current Storage: Dummy HDD` sits along the
+top.
+
+Its footer offers more than the other menus:
+`⊙ : Select   Ⓐ : OK   Ⓑ : Back   Ⓧ : Delete   Ⓨ : Select Storage` ✅.
+[capture](../re/captures/menu-nav/q4-destinations.png) (left panel)
+
+❔ Still open: the overwrite / delete confirmation, and where its cursor starts.
 
 Known: `title → LOAD GAME → slot 01 → YES → READY ROOM → TAKE OFF` reaches
 flight ✅.
 
-### Options ❔
-❔ Which settings exist, what each ranges over, how a change is applied and
-whether it needs confirming.
+### Tutorial ✅
+A list of lessons in two headed groups, with a one-line description shown on the
+left for whichever is focused ✅ — e.g. `BASIC CONTROLS` reads
+*"Learn how to move and attack"*. Opens focused on the first entry.
 
-### Extras ❔
-❔ What is in it — a movie theatre, a gallery, records? ❔ what is locked at the
-start and what unlocks it.
+| group | lessons |
+|---|---|
+| **Level 1** | `BASIC CONTROLS`, `HEADS-UP DISPLAY`, `RADAR` |
+| **Level 2** | `SUPPLY AND SPECIAL MOVES`, `RADIO ORDERS`, `ADVANCED CONTROLS` |
+| — | `BACK` |
 
-### Mission select ❔
-⚠️ **Stage select would not move**: sixteen d-pad presses never left Stage 01 ✅.
-Whether that is because only one stage was unlocked, or because the list is
-driven some other way, is unknown — worth settling early, since a scripted run
-has to get past it.
+[capture](../re/captures/menu-nav/q4-destinations.png) (middle panel)
+
+### Options ✅ (one level in)
+`GAME SETTINGS` · `CONTROL SETTINGS` · `SOUND SETTINGS` · `SCREEN SETTINGS` ·
+`BACK`, opening focused on the first ✅.
+[capture](../re/captures/menu-nav/q4-destinations.png) (right panel)
+
+❔ Still open: what is inside each of the four, what each setting ranges over, and
+whether a change needs confirming.
+
+### Extras ✅
+Three items: `MISSION SELECT` · `MOVIE THEATER` · `BACK`, opening focused on
+`MISSION SELECT` ✅. The cursor wraps here too — it is a menu rule, not a
+per-screen one ✅.
+[capture](../re/captures/title-builds/live-extras.png)
+
+❔ `MOVIE THEATER` has never been opened.
+
+### Mission select ✅ — and the "stuck cursor" is explained
+The stage list on the left (**8 rows visible of 16**, with a scrollbar), a detail
+panel showing the stage's name, a picture, `High Score` and `Best Time`, and a
+**Wide Area Space Map** on the right with the named systems on it. The chosen
+difficulty is printed top-right. Footer:
+`⊙ : Select   Ⓐ : OK   Ⓑ : Back   Ⓨ : Difficulty` ✅.
+
+⚠️ **"Stage select would not move" — sixteen d-pad presses never left Stage 01 —
+is now explained: the other fifteen stages were LOCKED** ✅. A locked row is
+drawn *dimmer than an unfocused one*: measured, the labels sit at three distinct
+brightnesses — focused **254**, unlocked **183**, locked **104** — and on a save
+with the story unlocked the same rows read 183, with the cursor able to reach
+**Stage16** at the bottom of the scrolled list.
+[the measurement](../re/menu-navigation-semantics.md#-mission-select-the-cursor-was-stuck-because-the-stages-were-locked) ·
+[locked](../re/captures/mission-select-stage01-only.png) ·
+[unlocked](../re/captures/mission-select-all-story-unlocked.png) ·
+[at Stage16](../re/captures/mission-select-ends-at-stage16.png)
+
+So: if you are scripting a run, **check what the save has unlocked** before
+concluding the list is broken. ❔ Whether the list wraps past Stage16, and
+whether a locked row is skipped or simply unreachable, is not settled.
 
 ### Briefing and Ready Room ❔
 ❔ What you read, what you choose, and what finally launches the mission.
@@ -122,6 +252,36 @@ side the cursor is on before pressing Ⓐ.**
 
 ---
 
+## 4b. What a screen change looks like ✅ measured, three of them
+
+Every screen carries a full-screen black quad (`pteff00.prm`) that paints last.
+A screen change is that quad ramping to opaque on the way out, and the **incoming**
+screen's own copy of it starting opaque and clearing on the way in — so a
+transition is two screens' quads, not one shared effect. The outgoing ramp's length
+is on the disc and matches the game **three for three**; the black between them
+does not, and is not a constant.
+
+| you press | going | outgoing ramp | black between | incoming clears over |
+|---|---|---|---|---|
+| Ⓑ | main menu → title | 5 frames | **none — they cross-fade** | 8 frames |
+| Ⓐ | title → main menu | 4 frames | ~3 frames | 5 frames |
+| Ⓑ | EXTRAS → main menu | 5 frames | **2 frames, fully blank** | 5 frames |
+
+⚠️ **Ⓑ is not "the cancel animation".** Ⓑ out of the main menu cross-fades — the
+title is already drawing while the menu is still fading — while Ⓑ out of EXTRAS
+goes properly black first. Same button, two different-looking moves, and if you are
+scripting against "the screen goes black" one of them will not do it.
+
+⚠️ **Ⓐ off the title is slow to start.** About 25 rendered frames (~0.8 s) pass
+between a delivered press and anything changing on screen; the other two start
+immediately. A script that presses and then looks 0.5 s later sees the title still
+up and can conclude the press was dropped.
+
+Timings are in *rendered frames* at ~30 Hz, from the emulator's own draw stream, so
+they do not stretch when the emulator runs slow —
+[`screen-transitions.md`](../re/screen-transitions.md) ·
+[`data/fade-three-transitions.txt`](../re/data/fade-three-transitions.txt).
+
 ## 5. Flying
 
 Not started, and the game teaches it better than we could: **play the in-game
@@ -147,3 +307,66 @@ Traps that read as bugs but are not, all measured ✅:
 * **A trace consumer that exits stalls the emulator**, which also reads as a dead
   pad.
 * Cold boot is slow; ~25 s once the shader and code caches are warm.
+* **`pkill -f xenia_canary` kills the shell that ran it**, because `-f` matches
+  the whole command line and your own `bash -c` contains the pattern. The script
+  dies before the emulator does, silently, with no output at all. Kill by process
+  **name**: `ps -o pid= -C xenia_canary | xargs -r kill -9`. (The same trap is in
+  `METHOD.md` for `pgrep` wait-loops; it cost another launch on 2026-08-30.)
+* **`kill -9` on xenia ORPHANS `/tmp/xenia-canary.lock`**, and the next
+  `run-canary` refuses with *"an emulator is already running"* — to **stderr**,
+  where a polling script never looks. A probe of mine then sampled a dead display
+  for **484 s**, reporting `other` every 4 s, because `screen_id.py` on an empty
+  screen returns `other` and *"not the title yet"* is indistinguishable from
+  *"there is no emulator"*. Kill with a plain `kill` so it can clear its own lock;
+  if you must use `-9`, `rm -f /tmp/xenia-canary.lock` after. **And assert the
+  emulator is alive before entering any wait loop** — `ps -C xenia_canary` — so
+  the loop cannot spend its whole deadline on nothing.
+* ✅ **Ⓐ on a settled boot title DOES reach the main menu — re-run clean,
+  2026-08-30, and the withdrawn counter-example below is now explained.** One
+  trial, **exactly one emulator verified by count**, gated on the plate pulse
+  (glyph in [500, 2500] held 12 samples) so the press lands on the boot title
+  rather than the attract loop's. Delivery confirmed (`[file-pad] keystroke
+  vk=5800 down`/`up`). Glyph after the press: `0, 0` at +2 s and +4 s — the
+  transition — then **327 steady from +6 s to +39 s**. ⚠️ 327 is a proxy, so the
+  screen was checked with [`which_title_screen.py`](../../tools/re-capture/which_title_screen.py)
+  instead: **`main_menu` at RMSE 19.91 and 20.08, margin ~10**, inside the 9.9–11.7
+  band its control establishes on four known captures. The `before` frame gives
+  the "neither" signature (margin 0.10), correctly, since the title is neither.
+  📌 **Latency 4–6 s**, which is why a script that presses and looks 0.5 s later
+  concludes the press was dropped. So the count is now **3 of 3**, and the two
+  earlier failures were the three-emulator confound, not the game.
+
+* ~~🔴🔴 **THE ENTRY BELOW IS WITHDRAWN — the experiment was confounded.**~~ When it
+  ran, **three emulators were live at once** (started 15:39, 15:44 and 16:12 on
+  2026-08-30), all reading the same `/tmp/xenia_pad.txt` and sharing display `:98`.
+  A press written to that file is delivered to **every** instance, and `screenshot`
+  grabs whichever window is topmost — which need not be the one that acted on it.
+  So "Ⓐ was delivered and the screen did not change" may simply be *two different
+  emulators*, and the keystroke-level confirmation proves only that **some**
+  instance received it. ⚠️ The cause was mine: `run-canary`'s lockfile is the
+  implementation of the "one emulator at a time" rule, and I had been clearing it
+  with `rm -f` to get past a stale one — which disables the guard for the next
+  launch too. **Clear a stale lock only after confirming zero live instances**
+  (`ps -C xenia_canary --no-headers | wc -l`). The claim below is unsupported and
+  needs a clean re-run before anyone relies on it.
+
+* ~~🔴 **Ⓐ on a settled boot title does NOT reliably reach the menu.**~~ This page's
+  §1 and `canary-scripted-input-traps.md` record "the boot title accepts a single
+  Ⓐ (2 of 2 runs)". A run on 2026-08-30 gated on the **plate pulse** (glyph in
+  [500, 2500] held 12 consecutive samples), fired at t=484.5 s with glyph 1723 —
+  a verified settled boot title, not the attract one — pressed Ⓐ, and **the press
+  was delivered** (`[file-pad] keystroke vk=5800 down` / `up`, 8 `[RE-INPUT]`
+  lines). Twenty seconds later every captured frame still classified as the title.
+  So the sample is no longer 2 of 2, and a script that presses once and proceeds
+  can be left on the title with nothing in its log to say so. **Confirm the screen
+  changed; do not infer it from a delivered press.**
+* **`screen_id.py` reports `menu` during the attract loop.** Two boots on
+  2026-08-30 logged `menu` at t=106 s and t=418 s while the game was still in the
+  intro movie. A wait-loop that breaks on `menu` will act on the wrong screen; the
+  loops here break on `title` for that reason.
+* **`screen_id.py` cannot tell EXTRAS from the main menu** — both are dark blue
+  `GP_TITLE` screens and it answers `menu` for either. Use
+  [`which_title_screen.py`](../../tools/re-capture/which_title_screen.py), which
+  separates them by ~11 RMSE against ~18 within-class, and read the **margin**: a
+  margin under ~1 means "neither", which is what you get on a screen outside
+  `GP_TITLE` entirely.

docs/port/MISSION.md

@@ -74,10 +74,39 @@ alongside it.
 | **Q7** | **Transitions.** What happens visually between screens — the `pteff00.prm` quads, a fade, a cut — and its timing | Described and timed against a capture |
 | **Q8** | **Menu audio.** Which BGM per screen; which cue on move / confirm / back / error. The cue table is complete; the event binding is not | Cue names bound to events, with how you established each |
 | **Q9** | **Video binding.** Which movie is the boot intro vs the new-game intro; whether playback is skippable and what ends it | Named movies plus the playback rules |
-| **Q10** | **What are a music bank's sub-waves?** `BGM_001.slb` is three sub-waves — 10 KB, 4.47 MB, 4.67 MB — and we currently **concatenate them blindly** into one 347 s track. Two near-equal halves could be intro + loop, or two variations, or two halves of one piece. A menu that loops its music needs to know which | The role of each sub-wave, established for at least the menu BGM. "Concatenate" is a decision, not a default — right now it is a default nobody chose |
+| **Q10** | ~~**What are a music bank's sub-waves?**~~ ✅ **ANSWERED — see below.** Every factual premise in the original row is refuted: a bank is **two** waves, not three (the 10 KB was the bank *header*, emitted by our own reader), and the three candidate roles it listed — intro + loop, two variations, two halves — are all dead. | ✅ **Gate met.** Role established on the menu's own bank: [`bgm-two-stems.md`](../re/structures/bgm-two-stems.md). 🟡 One sub-question survives — *which kind* of second stem — and it is 🟡 by measurement, not by neglect |
 | **S1** | ~~**Ready Room probe.**~~ **DONE 2026-08-28 — [no-go](../re/ready-room-probe.md).** It is 2D and enumerates fine, but the pak is briefing/tactical-map content, not the Ready Room menu | ✅ go/no-go written |
 
-## 🔴 Emulator-side questions are blocked — the title is not reachable here
+## ✅ Emulator-side questions are NOT blocked — corrected 2026-08-30
+
+⚠️ **This heading read "🔴 Emulator-side questions are blocked — the title is not
+reachable here".** That is false and has been for some time: **twelve** emulator
+runs on 2026-08-30 reached the settled title, gated on the plate pulse, and drove
+it into the menu, `EXTRAS` and out of the archive. `HANDOFF.md` recorded the
+banner as withdrawn; this document did not, and it is the one the brief says to
+read **every iteration**.
+
+🔴 **My first correction of this section was itself wrong, on all three clauses,
+and is replaced (2026-08-30).** It read: *"The two items this section named are
+UNBLOCKED, not answered … Both need a running menu, both now have one, and neither
+has been attempted."* I wrote that without reading either page. Reading them:
+
+* **`8AX` vs `ptbase` was RESOLVED on 2026-08-29.** Its page says so in its status
+  line — both its questions closed, kept for the evidence.
+  [8AX](../re/structures/ui-8ax-fullres-background.md)
+* **The gamma control was attempted and half-answered**, and its page records that
+  the run *"needed the emulator only to **boot**, not to reach a menu … parked
+  behind the title-screen blocker for no reason."*
+  [tone curve](../re/structures/ui-render-tone-curve.md)
+* **So neither ever needed a running menu**, and this section's premise was wrong
+  independently of whether the menu was reachable.
+
+⚠️ **A correction is a new claim.** Mine replaced a stale status with an unchecked
+one, in the same edit that criticised the document for carrying unchecked status —
+which is the failure I had just finished cataloguing elsewhere.
+
+The original section is kept below for the record, demoted so it cannot be read as
+current.
 
 **Status 2026-08-29, instrument-verified.** Two open items need a running menu:
 the gamma control behind [tone curve](../re/structures/ui-render-tone-curve.md),
@@ -100,7 +129,24 @@ reachable from this container on 2026-08-28. Clearing the shader cache fixed a
 including three earlier "the title never appears" claims that were withdrawn
 because the instrument was broken each time.
 
-## 🟡 Needs one more run — a Japanese-locale capture
+## ✅ The Japanese-locale capture was taken — TWICE. Corrected 2026-08-30.
+
+⚠️ **This heading read "🟡 Needs one more run — a Japanese-locale capture", and the
+text below calls it "one capture we cannot take".** Both are false.
+[`live-title-jp-at-rest.png`](../re/captures/title-builds/live-title-jp-at-rest.png)
+and [`-run2`](../re/captures/title-builds/live-title-jp-at-rest-run2.png) are
+committed, from two independent sessions, via
+[`jp_title_session.sh`](../../tools/re-capture/jp_title_session.sh) which sets the
+console language and always restores it.
+
+📌 **And both questions it was blocking are closed** — Q1's association by the
+[record-layout fix](../re/ui-keyframe-record-layout.md), and `rest()` for a
+plateau-less element by a 1 036/1 036 discriminator, then **confirmed against this
+very capture**: the corrected pose scores RMSE 41.69 where the stale one scores
+58.41 ([`ui-resting-pose.md`](../re/structures/ui-resting-pose.md)).
+
+⚠️ I noticed this section was stale several iterations ago, said so in a message,
+and did not fix it. Kept below, demoted.
 
 Recorded rather than worked around, per "do not improvise around a blocker".
 
@@ -208,7 +254,21 @@ settled and only multi-keyframe absolute timing is open; `rest()` differs from
 its alternative on **one** element across all five screens, and the current
 answer there is the defensible one.
 
-## 🔵 Needs a human decision — rotation (raised 2026-08-29)
+## ✅ Rotation — the decision was TAKEN and implemented. Corrected 2026-08-30.
+
+⚠️ **This heading read "🔵 Needs a human decision — rotation (raised 2026-08-29)".**
+It was answered the same day it was raised: `HANDOFF.md` records *"OPTION A IS
+DONE. The reference renderer rotates"*, and `ui_layout.rs` carries the rotated blit
+with a control test (`rotation_control_known_angles`) pinning it against angles
+whose answer is arithmetic — 0° and 360° byte-identical to the unrotated path.
+
+✅ **And the field itself is now confirmed from the ORACLE, not just decoded.** The
+port's `rotation_deg` of **+30** on `pteff03` and **−45** on `pteff03a` predict a
+rotated quad's AABB height at 1135.3 and 1301.1; the game's draw stream measures
+**1134** and **1303** — both under 0.2 %
+([`data/title-sweep-drawn-at-rest.txt`](../re/data/title-sweep-drawn-at-rest.txt)).
+
+The original section is kept below, demoted.
 
 The port agent asks whether it should **render** `rotation_deg` (decoded at
 keyframe `+12`) when `sylpheed-cli screen render` deliberately does not. Its own
@@ -230,6 +290,37 @@ What needs a decision is which way the divergence gets closed:
 
 Recorded rather than chosen, per "do not improvise around a blocker".
 
+## ✅ Q10 is answered — corrected 2026-08-30
+
+The Q10 row above was written on a premise that has since been **refuted in every
+part**, and it survived as a live question for days after the refutation landed.
+Recording the correction here rather than silently editing the row:
+
+* ❌ *"`BGM_001.slb` is three sub-waves (10 KB, 4.47 MB, 4.67 MB)"* — the 10 KB is
+  the **bank header**. Our reader emitted it, from a modulus valid only for a
+  header shorter than one XMA packet. A bank is **two** waves, **28/28** disc-wide.
+* ❌ *"we currently concatenate them blindly"* — and concatenating is **wrong**,
+  now measured: the two waves are **sample-synchronous** and the running game
+  decodes **both at once** (the XMA probe at the main menu saw two stereo streams
+  whose byte sizes are `BGM_103`'s two declared waves, exactly).
+* ❌ *"could be intro + loop, or two variations, or two halves of one piece"* — all
+  three predict unequal durations; **32 banks give equal ones**.
+* ✅ **The gate — "the role of each sub-wave, established for at least the menu
+  BGM" — is met**, and on the menu's own bank: `BGM_103`, named from the
+  executable, confirmed against the disc and against the running game.
+
+🟡 **What is still open is narrower than the row**: *which kind* of second stem —
+the rear pair of a 4-channel mix, or a second intensity layer. Both predict
+simultaneity, so runtime observation cannot separate them, and a coherence
+discriminator run 2026-08-30 **refuted the "filtered copy" model but could not
+separate the two** — its own control showed that in this material even L vs R of
+one performance reads only 0.22–0.50, so the test's premise does not hold.
+[`../re/data/bgm-stem-coherence.txt`](../re/data/bgm-stem-coherence.txt)
+
+⚠️ **This distinction does not block the port.** Both readings give the same
+instruction: play both waves, aligned at sample 0, together. It changes only how
+they would be *mixed* if the port ever does surround.
+
 ## Known unknowns — say so, do not fill them in
 
 Some of these may turn out to be undecodable. That is a valid, useful answer, and

docs/re/INDEX.md

@@ -35,6 +35,7 @@ Promote to a prose `structures/…md` file when a format needs behavioural notes
 | Scripted input / profile traps | ✅/🟡 | [canary-scripted-input-traps](canary-scripted-input-traps.md) | Why a scripted run appears unable to press Ⓐ: **F10 opens the emulator menu bar**, and any Xenia UI makes `XamInputGetKeystrokeEx` return SUCCESS with an empty keystroke *before* any driver is asked (Canary now logs `[RE-INPUT] … swallowed by IsUIActive`); the title needs a **signed-in profile** (hence `--create_profile_if_none`); and a **FIFO trace consumer that exits stalls the emulator**, which reads exactly like a dead pad. 🟡 The main menu HAS been reached — Ⓐ works, but only intermittently (1 in ~4), which is the open question |
 | Title-screen guest crash | ✅ | [title-crash-stl-tree](title-crash-stl-tree.md) | The guest throws **`std::out_of_range`** from its cache-manager flush (`sub_823070B0`, an STL map/set erase that builds `'invalid map/set<T> iterator'`); the access violation after it is only the throw **returning**, because this build does not unwind guest EH. Trigger found and controlled: an **incomplete on-disc cache** (`~/.local/share/Xenia/cache/aab216c3`) throws ~100 s into a boot, a complete one never does — 2 runs each way. ❌ `mem_watch`, the handoff's suspect #1, is **eliminated**: cold cache + `--mem_watch=false` throws anyway |
 | Save file (`savedata`) | ✅/❔ | [savegame-format](structures/savegame-format.md) + [`tools/re-capture/savegame.py`](../../tools/re-capture/savegame.py) | `GDHA` container, zlib payload, chunk stream (`GDAA` / phase name / `GHAD` 122 B progress block / 16×20 B slot table / trailer). **Container and layout read off the title's own serializer `0x822C00E8` and verified by a byte-identical round-trip**; the whole save is 545 B. Payload offsets are also the live save object's offsets (`save+8` GHAD, `save+136` slots). A second save made in-game names **Points** (+24), **flight time in ms** (+4) and **clear ratio %** (+8) off the game's own Details panel; the payload is a **pure function of game state** (same state saved twice = byte-identical, only the header FILETIME and its uninitialised pointer padding move), and the 16 `SHAB` records are **not** the UI's 20 save slots. Difficulty vs stage is undecided — three fields hold 2. **A third save, taken after developing exactly one Arsenal weapon** (Light Machine Gun MG I, 4000 P), moves exactly three things: `+24` Points 4101→101 (which **separates it from `+28`**, that did not move), `+8` clear ratio 5→6 (so the ratio counts *collection*, not only stages), and two entries of the 54-byte blob — `2→4` for the item bought and `0→2` for the successor the game announced as newly developable, giving the blob its alphabet ✅ *0 locked / 2 developable / 4 developed* (only the `4`s are stored — `2` is re-derived at load). **Saves can also be written back**: three derived header fields (length at `+0x30`, payload length at `+0x8c`, `adler32` at `+0x8e`) are all that stand between a parse and a hand-written save that the title loads, and [`savegame_edit.py`](../../tools/re-capture/savegame_edit.py) re-wraps a real save byte-identically. That turned the blob's index space from blocked-on-story-progress into four probe saves — see the [economy note](arsenal-develop-economy.md) |
+| `--build N` addressing (ordinal vs pak entry) | ✅ | [build-ordinal-vs-entry](structures/build-ordinal-vs-entry.md) + [`data/ordinal-entry-map.txt`](data/ordinal-entry-map.txt) | `screen --build N` indexes a **predicate-filtered list**, not the pak. Disc-wide: **21 of 24** build-bearing archives diverge, **18 at ordinal 0** — `--build 0` is entry **108** in each `GP_MAIN_GAME_*2D`, entry 24/26 in `GP_HANGAR_ARSENAL`/`GP_READY_ROOM`. `GP_TITLE` is the **only** archive whose ordinals 0–9 are the identity, which is the sole reason 207 of the corpus's 226 build citations are safe. ⚠️ `--all` swaps the predicate and **renumbers 18 archives**, so `--build N` and `--build N --all` differ. Instrument controlled against the CLI's own `screen list` on `GP_TITLE` (12 builds, `[10]→12`, `[11]→15`) — a first version using `parse_build` as the predicate **failed** that control, reporting ordinal==entry throughout. Audit of all 226 citations: 1 defect found and fixed (a five-row table in `ui-keyframe-time-unit.md` labelled "build 11" spanned builds 10 and 11 — placements all correct, only the label wrong); `GP_DIALOG --build 0` and `GP_DEBRIEFING_PILOTLOG --build 10` re-run and reproduce |
 
 ## Runtime / dynamic-capture technique
 
@@ -136,6 +137,7 @@ files, which is how the same ground got covered twice.
 | [`structures/stage-mission-tables.md`](structures/stage-mission-tables.md) | The stage table set — phases, routes, sub-objectives and AI parameters | ✅ the table set and how the stage record reaches it, validated across; **`AIParams` disc-wide: 23 objects, one shared 34-profile roster (782 records), loader `sub_8233C368`; `Type`→field-count holds except the two `_Test` templates** |
 | [`structures/texture-color-k8888.md`](structures/texture-color-k8888.md) | Texture colour interpretation — `k_8_8_8_8` (32bpp UI/HUD textures) | — |
 | [`ui-keyframe-time-unit.md`](ui-keyframe-time-unit.md) | What a keyframe time is worth, and what shape the ramp has |  ✅ CONFIRMED from the running game's own draw stream — the ramp is **linear** (a declared 15-unit fade lands on `round(255·k/15)` for all seven samples) and the animation clock advances **2 time units per submitted frame**. 🟡 the seconds conversion (`1 unit = 1/60 s`) rests on a measured 27.6 present-frames/second |
+| [`ui-keyframe-record-layout.md`](ui-keyframe-record-layout.md) | A keyframe's time word comes **before** its pose — the placement record, decoded | ✅ CONFIRMED, **decoded**. A group is an 8-byte header then `frames` records of `{u32 time; 36-byte pose}`, so the time precedes the pose; the group's lead-in word at `header+8` is pose 0's time and **every** pose is timed. Disc-wide over 13 991 groups in 33 archives, each test with a control: lead-in prepended is non-decreasing **13 991/13 991**; a non-zero lead-in is strictly below the next time **5 058/5 058** (control 70.9 %); a multi-segment alpha ramp runs at a constant `dα/dt` **857/1 540** against **0/1 042** under the old reading. 🔴 Retires two long-standing corpus claims — *"a group's data stops 4 bytes short of its final block's time slot"* and *"the last keyframe carries no time"* — both of which were this off-by-one. Adoption is free: all 12 `GP_TITLE` builds render byte-identically, and over 217 builds only two elements pick a different `rest()` pose, both between equally invisible ones. ❔ the executable's own parser was **not** found (the 40/60 stride query is weak, not negative) |
 | [`structures/ui-composable-bundles.md`](structures/ui-composable-bundles.md) | A screen build is not the only thing `compose` can draw |  ✅ CONFIRMED by measurement over the disc, with the artifact to |
 | [`structures/ui-focus-and-effect-elements.md`](structures/ui-focus-and-effect-elements.md) | `_eff` glow layers are not focused-state records |  ✅ CONFIRMED by measurement over all 965 screen builds on the disc, |
 | [`structures/ui-paint-order-key.md`](structures/ui-paint-order-key.md) | The paint order comes from a layer key in the T8aD sprite header |  ✅ CONFIRMED on both screens whose paint order has been measured — |
@@ -147,17 +149,38 @@ files, which is how the same ground got covered twice.
 | [`structures/unit-struct-runtime.md`](structures/unit-struct-runtime.md) | Runtime `Unit` struct (craft / vessel definitions) — read from live guest memory | — |
 | [`structures/weapon-struct-runtime.md`](structures/weapon-struct-runtime.md) | Runtime `Weapon` / `Shell` structs — read from live guest memory | — |
 | [`structures/xbg7-mesh.md`](structures/xbg7-mesh.md) | XBG7 — mesh geometry (inside XPR2 model containers) | — |
+| [`capture-harness-status.md`](capture-harness-status.md) | Why the harness stops reaching the title — and the two instruments that could not see the disc |  ✅ **the disc is BACK** (2026-08-29, container replaced at 11:07:38): `/disc` is a real 6.2 GB read-only mount and `screen list` returns 12 builds. The "no disc" section is withdrawn — and its two instruments were blind either way: `find / -xdev` cannot cross into a bind mount on another device, and `sylph-doctor` only ever looks under `/work`. Earlier sections: `screenshot` costs 10.8 s under xenia (92×), and `trace_gpu_stream` is a no-op in the Release build |
 | [`title-crash-stl-tree.md`](title-crash-stl-tree.md) | The title-screen crash is an STL `map`/`set` erase on a bad iterator |  ✅ CONFIRMED — the guest throws std::out_of_range from an STL |
 | [`ui-paint-order-third-permutation.md`](ui-paint-order-third-permutation.md) | A third measured paint order — tool built and validated, screen not reached |  ✅ the reader works and is CONFIRMED against both previously |
 | [`ui-quad-class-foothold.md`](ui-quad-class-foothold.md) | The guest's UI quad class — a foothold found from the capture's vertex layout |  🟡 PROBABLE for the identification below (it is a static read, but |
-| [`menu-navigation-semantics.md`](menu-navigation-semantics.md) | The title menu — how it moves, and where each button goes |  ✅ measured: wraps both ends, Ⓑ restores focus, ⬅➡ inert; 4 of 5 destinations driven. 🟡 GamePart id is a name match, ❔ `NEW GAME` untested |
+| [`menu-navigation-semantics.md`](menu-navigation-semantics.md) | The title menu — how it moves, and where each button goes |  ✅ measured: wraps both ends, Ⓑ restores focus, ⬅➡ inert; all 5 destinations driven. 🟡 GamePart id is a name match. 🟡 **Ⓑ leaving the MAIN menu downgraded 2026-08-29** — uncited, and the main menu is the only screen whose footer omits Ⓑ (0 glyph px in frame vs 514/518 elsewhere). ✅ **MISSION SELECT's stuck cursor was a LOCKED stage list** — labels have three brightnesses, locked 104 / unfocused 183 / focused 254 |
 | [`screen-transitions.md`](screen-transitions.md) | Between two screens — a fade through black, and where its timing lives |  ✅ the fade quad's keyframe group is decoded (disc-wide: per-pak all-or-nothing; `GP_TITLE` = the 6 screens, not the 6 overlays); the ~0.4 s fade-OUT is measured, not on the disc |
 | [`menu-audio-cues.md`](menu-audio-cues.md) | Menu audio — the event vocabulary is on the disc, the binding is not |  ✅ `SE_UI_*` cue names/ids decoded and `BANK_SE`→`Static.slb` (0/322 in FILES); 🟡 event binding is a name match; ❔ `Static.slb` has no wave boundaries, so SE audio is not extractable |
 | [`boot-config-and-gamepart-registry.md`](boot-config-and-gamepart-registry.md) | What the game reads at boot — `config.ini`, and which GameParts exist |  ✅ `config.ini` selects the language (the disc's only config); ❔ its `[SYSTEM]` is empty so the boot order is not in config; 🟡 24/29 ids bind to a class, `GP_ADVERTISE_DEMO` is never registered |
 | [`movie-binding.md`](movie-binding.md) | Which movie plays where — boot intro, attract loop, new-game intro |  ✅ decoded from the movie manifest (`ADVERTISE_MOVIE`→`ADV.wmv`, `MS00A`→`S00A.wmv`); attract identity confirmed independently by frame matching; 🟡 skippability unsettled |
 | [`ready-room-probe.md`](ready-room-probe.md) | S1 — the Ready Room probe: no-go, and not for the reason expected |  ✅ it is 2D and enumerates (60 builds), but the pak is briefing/tactical-map content; and `kind == 0x3002` finds 0 buttons there |
-| [`ui-title-build-map.md`](ui-title-build-map.md) | Which `GP_TITLE` build is which screen state |  ✅ CONFIRMED for title / `PRESS Ⓐ` / main menu / `EXTRAS` against live captures; the archive is 8 screens × EN/JP, and "6/8/9 are submenus" is withdrawn |
+| [`ui-title-build-map.md`](ui-title-build-map.md) | Which `GP_TITLE` build is which screen state |  ✅ CONFIRMED for title / `PRESS Ⓐ` / main menu / `EXTRAS` against live captures; the archive is 8 screens × EN/JP, and "6/8/9 are submenus" is withdrawn  ✅ **2026-08-29: the two "unidentified `DELTASABER` plates" are the LOADING screen** — builds 0/1 the plain variant, 10/11 the dressed one, decoded from their `pgloading_*` element names, and the executable (`sub_821C4EB0`, bytes checked in the image) names exactly five title-side screens: `TITLE_SCREEN`, `BUTTON`, `TITLE_MENU`, `LOADING`, `LOADING2`. 🟡 which loading bundle takes which of the two names is undecided. 🟡 the English member of a pair is the one in the first half of `GP_TITLE.p00` — 8/8 structurally, 3/3 where a capture can check it. |
 | [`ui-title-paint-order-capture.md`](ui-title-paint-order-capture.md) | The title screen's paint order, measured from the guest's draw submissions |  ✅ CONFIRMED — the order in which the running game paints the title |
 | [`upstream-baseline.md`](upstream-baseline.md) | A stock-upstream baseline runs Stage 02 crash-free |  ✅ CONFIRMED — upstream canary_experimental + only the pad |
 | [`weapon-datasheet-runtime.md`](weapon-datasheet-runtime.md) | Weapon DATA SHEET — runtime capture (Route B) |  🟡 first dynamic capture, 2026-07-28. The Arsenal's Gallery Mode panel is a |
 | [`xpr2-colour-check.md`](xpr2-colour-check.md) | XPR2 colours: channel order ✅ confirmed against the running game | — |
+| [`focus-ring-spin-measured.md`](focus-ring-spin-measured.md) | The main menu's focus ring spins continuously — and how fast | ✅ **measured**: period **2.177 s** over 9 revolutions (8 evenly spaced autocorrelation peaks) = 120 units = 60 frames = 2.00 s at 30 Hz. A pulse is excluded — annulus total conserved to 0.4 % while per-bin brightness swings by 24. ✅ the ring is the **only** moving thing on the settled main menu (std exactly 0.000 elsewhere). 🔴 no angle is quoted: the angular estimator FAILED its own control (30° → 0°) |
+| [`structures/slb-bank-header-not-a-wave.md`](structures/slb-bank-header-not-a-wave.md) | Why a music bank read as THREE sub-waves when the census says two | ✅ **decoded**: the third is the **bank header**, emitted by our own reader. `to_xma_riffs`'s hybrid branch derives a leading packet stream's start as `first_riff % 2048`, which is right only for a header shorter than one packet; a music bank's header is exactly **5 packets (10 240 B)**, so the modulus gave 0 and the whole header came back as sub-wave 0. The header states its own length at `+0x24` in blocks. Disc-wide over 9 519 `sound.pak` entries: **28** match the header signature at offset 0 (ids 1001–1023, 1101–1105), **28/28** end exactly at the first `RIFF`, **0** have a gap, **0** false positives — so a header at offset 0 and a leading packet stream never coexist. Decode control, same chain, same bank: the emitted region gives **0.009 s** against **87.744 s** for the real wave 0. Corroborated by the runtime XMA probe, which saw exactly two streams at the main menu. Fixed + 2 regression tests; the `VOICE_D_453` recovery is untouched (10/10 green) |
+| [`title-plate-delay-measured.md`](title-plate-delay-measured.md) | How long the boot title shows build 4 before the `PRESS Ⓐ` plate | ✅ **decoded after a refutation**: build 2 and build 4 run on **one clock started together**, and the plate's own `ptbtn00` reaches `a=255` at `t=238`; the last build-in ramp ends at `t=118`, so the interval is a declared **120 units = 2.000 s**. 🔴 The instruction that shipped first — "wait 2.13 s after build 4 settles" — was **refuted by the port** with disc arithmetic and is corrected in place; 🔴 `rest.t` is **not** when a screen settles (it is the last hold keyframe before the exit: `ptlogo1` rests at `t=251` and stops moving at `t=42`). ⚠️ The wall-clock 2.13 s is 6.7 % long because Canary presents at **28.06 / 28.14 fps** against a nominal 30, matching the corpus's independent **28.5 fps**; author the 120 units. ✅ **measured**, two independent boots: **2.138 s** and **2.132 s** from the frame build 4 settles (glyph = its no-plate 154, motion → 0). Agreeing to **6 ms**. So the boot title's end state is **not** plate-free and a compositor must draw **two builds at once**. ⚠️ Measure from *settled*, not from first pixels — "first drawn → plate" is 3.78 s vs 4.26 s across the same two runs, because the build-in animation's own duration varies with emulator frame pacing. Plate pulse re-measured at 2.12/2.19/2.34/2.31 s (mean 2.24), replicating the corpus's ≈2.3 s. ✅ black hold between screens bracketed at **0.14–0.30 s**, consistent with the declared 12 units. 🔴 the Ⓐ→menu latency is still **not** available: both runs freeze one frame for ~1.4 s at surface mean **26.626** — agreeing between runs to 1e-6, and reproduced with stream restarts disabled — which is a guest **load stall**, not the capture path. Probe: 8.7 ms/frame, 7.97/7.98 fps against a requested 8, controls 9/9 + 4/4 |
+| [`menu-idle-and-b-2026-08-29.md`](menu-idle-and-b-2026-08-29.md) | The main menu does not idle back to the title — and four durations that were a pipeline | ✅ **refuted**: no self-return in **≥ 60 s** untouched; the ~8–10 s idle belongs to the **title**. 🟡 Ⓑ→title ordering measured, latency not. 🔴 `classify_array` at **1503 ms/frame** drained an 8 fps stream at 0.64 fps and manufactured four latencies (24.66 s / 15.58 s / 25.60 s / 20.26 s) — all withdrawn; a backlog preserves ordering and destroys durations |
+| [`structures/ui-settle-time.md`](structures/ui-settle-time.md) | Which instant a "settled screen" composite depicts | ✅ **decoded**: a settled screen is **one instant every element is posed at**, and the disc names it — the midpoint of the **longest keyframe-free interval** in the build (`UiBuild::settle_time` / `settle_window`). 🔴 `rest()` is *not* that: it picks each element's last hold **independently**, so a two-frame flash holds at its **peak** and burns forever. `GP_TITLE` build 4 has five staggered flashes (`ptlogo_back2eff1`…`eff5`, all extinguished by t110) that `rest()` draws simultaneously and permanently, saturating the light arc. Predicted t=198 from `[160,236]` **before scoring**: arc band **33.22 → 11.79**, clipped pixels **8 581 → 1 452** against the console's **1 459** (an unfitted statistic), whole frame 14.07 → 12.06; controls at t=100 and t=358 are far worse, and a hand-picked visibility list reaches the identical 12.06/11.79/1 452. Controls: `at=None` byte-identical (`cmp`), pre- and post-rotation tags both 14.07, 13 paint-order tests green. ⚠️ **Reach**: of 1 758 bundles with ≥2 keyframe times only **30 %** have a window ≥ 30 units and **42 %** under 10 — mostly `loop*` fragments that never settle; check the width. 🔴 Withdraws two claims in [`ui-rotation-implemented.md`](structures/ui-rotation-implemented.md) — its "Flat. No minimum." (`at` posed **leaves only**) and its "Reborn does not draw `ptlogo1`/`ptlogo2`" (both **are** drawn; only kind-`0x4` ghosts are skipped, and hiding the real ones makes the error *worse* by +5.20/+7.47). ❔ its **10.92** baseline is unreproducible — 14.07 at both tags |
+| [`structures/ui-tie-break-cost-at-settle.md`](structures/ui-tie-break-cost-at-settle.md) | What the unknown paint-order tie-break costs, in pixels | ✅ **decoded**, closing the open half of Q3: at the settled instant the tie-break costs **at most 1 px at Δ1**, on the **Japanese title only** (`ptlogo2`×`ptlogo_tm`, 5 px shared ink); **exactly 0 px on all five port screens**. The earlier 24-pair bound was a `rest()` count — and 10 of the title's 11 tied pairs are between `ptlogo_back2eff1`…`eff5`, five transient flashes that are **transparent** on the settled screen ([`ui-settle-time.md`](structures/ui-settle-time.md)). Live pairs at settle: entry 4 → **1**, entry 7 → **2**, the four loading bundles → **0**. ✅ Not a knife-edge — sweeping every keyframe time and midpoint, the count is **flat across the whole settle window**, and the loading bundles' tie is live only at t17–t33. ✅ Controls: an overlapping *different*-key swap moves 25 310 / 268 698 / ~765 000 px on the entries reporting zero; zeros are explained by shared-ink counts (the `ptframe` pairs share **0 px** of ink). ⚠️ Entries 0/1/12/15 have **no live control** — their zeros rest on keyframe data, not a render. 🟡 Refutation attempt on the corpus's "24 pairs": **survives** as a rest-pose bound, 16/16 on entry 7. ❔ *Why* ties order as they do is still unknown — and now worth one pixel |
+| [`structures/ui-record-loop-length.md`](structures/ui-record-loop-length.md) | Where a looping record's cycle restarts — and the `PRESS Ⓐ` plate's real period | ✅ **decoded**: a nested record is itself a RATC bundle and its header **`+0x08` is the loop length**; its keyframes need not fill it, and the slack is a hold at the final pose. Disc-wide over **1 781** timed nested records: 92.3 % declare exactly their last keyframe time, **7.7 % declare more**, and **0 declare less** — the falsifier (a cycle cannot restart before its own last pose) never fires. 🔴 **The plate's `ptbtn00f` is 105 units of ramp inside a 120-unit cycle, so it holds dark for 15 units** — the port was shipping **105**, and the answer is **120**. ✅ Falsification test against the running game, using a pacing factor measured *independently* on the focus ring (declared 120 → **2.177 s**, factor **1.0885**): to reach the corpus's measured 2.12–2.34 s, 105 units needs a factor of **1.211–1.337** (🔴 excludes the ring's) while 120 needs **1.060–1.170** (✅ contains it). Different elements, different bundles, separate runs — tied only by both declaring 120. ⚠️ Says where a cycle *ends*, not which records cycle. ❔ the **top-level** `+0x08` (300 on every `GP_TITLE` entry, elements ending at 244–269) is a different question, untouched |
+| [`structures/ui-focus-record-pulse-census.md`](structures/ui-focus-record-pulse-census.md) | Every focus record whose glow pulses, and where `rest()` puts it | ✅ **decoded**, disc-wide: **1 130** focus records, **2 664** timed elements, **210 with a varying alpha** — of which **202** have `rest()` == the **peak** (burns bright forever) and **8** land **mid-ramp**. By pak: `PILOTLOG` 116, `MOVIE_THEATER` 54, `HANGAR_ARSENAL` 30, `LEADERBOARD` 8, **`GP_TITLE` 2**. 🟡 Bounds rather than refutes the port's "34 in the export, 2 varying, nothing to fix" — correct, and correct *because* `GP_TITLE` has 2; the pathology sits in the screens a wider port needs next. 🔴 The 8 mid-ramp ones are the worse mode: `py_ranking_btn01f` swings 255→127→255 and `rest()` returns **244**, neither extreme, which looks entirely plausible and nothing reports it. ✅ Control: `ptbtn01f` is genuinely constant (255 throughout) and is **not** flagged; two hits verified keyframe by keyframe. ⚠️ A pulsing element has no resting pose — the question is malformed, not mis-answered; `pose_at(t)` inside the record's declared cycle ([`ui-record-loop-length.md`](structures/ui-record-loop-length.md)) is the only well-formed query. ⚠️ 210 is a **floor**: focus records are matched by the `Xf.rat` name rule, and varying scale/rotation/position is not counted |
+| [`structures/ui-title-buildin-measured.md`](structures/ui-title-buildin-measured.md) | The title's build-in and the plate glow, read out of the guest's own draw stream | ✅ **measured** (Canary, `ARM=early` draw capture): the decoded *mechanism* is observed, not just its end state. **The five flashes fire in a six-frame window and are absent from all 155 other sampled frames**; `ptlogo_back2eff1` is drawn in exactly 2 frames at **t = 54.0** against a decoded peak of **t54–56**, and `ptlogo1` first appears at **t = 42.2** against a decoded **t42** — with units/frame taken from the **glow's period alone**, a different element. The two holders (`ptlogo_back2eff`, `ptlogo_back2`) are continuous from frame 134. ✅ The glow's per-vertex colour alpha IS its fade alpha: **observed range 0…80 against a decoded peak of 80**, exact and unfitted; **period 51.158 presented frames** over 20 cycle starts; fitting the decoded ramp gives RMS **13.16** against **38.18 reversed** (2.9×), so the asymmetry is real and correctly directed. Structure: the settled title is 10–11 draws naming no sprite — which is why arming at the title sees nothing. ⚠️ Frame **107** is a 27-draw spike between the movie's last frame and the title's first; calling it "the composite" was an **over-read** — it binds **no texture** and only 4 of its 27 draws log geometry. The second title entry has no such frame. ⚠️ The two entries are the same animation at **different sampling phases** (only 4 of 46 aligned frames match), which is what makes the `eff3` result robust. 🔴🔴 **RETRACTED — the game DOES draw `ptlogo_back2eff3`, and all five flashes fire in both entries in the declared stagger** (`eff3` at frames 133–134 / 5957–5958, i.e. t=60.1 and 62.3, inside its declared t∈(58,64)). The absence was an **instrument artefact**: a draw batches several quads (`indices=8` is two) and the log dumps only the first 8 vertices, so min/max over a line **merges** them — and because the wipe is right-aligned, `eff3` (788…1196) lies entirely inside `eff4` (447…1196), making the union *exactly* `eff4`'s extent. The merged box matched `eff4` to 1 px. 🔴 Three explanations had been "ruled out" and all three were aimed at the wrong failure — notably the invisible-draw check counted draws with **no** geometry, where the hiding place was **partial** geometry. Superseded text follows: ~~three alternative explanations tested and failed: *phase* (its window is **6 units** against a **2.23-unit** step, so it cannot be missed — frames 133/134 sit at t=60.1/62.3 inside it and draw `eff2` and `eff4` instead), *an unlogged draw* (exactly 2 blind draws/frame, always the same full-screen-triangle shader, present when no wipe is active), and *a bad position guess* (dropping position entirely, **zero** quads anywhere have a width within ±30 of 408; the spectrum jumps 262 → 748). Draw counts across both entries: eff1 **4**, eff2 **3**, eff3 **0**, eff4 **6**.~~ (all from the merged-box parse, and wrong) 🔴 **The port draws `eff3` at t=60–62 and the console does not.** ❔ Why is not established — nothing in its element record differs from its neighbours. ⚠️ An earlier "sub-frame phase" explanation and the advice that drawing all five "shows more sweep than the console" are both **withdrawn**. ⚠️ What a frame-by-frame build-in comparison *will* show is disagreement about which flash lands in which frame — 2 units/submitted frame against this run's 2.231 units/presented frame — and neither side is wrong. 🔴 **Trap:** matching a bound texture's dimensions to a sprite fails both ways — it missed every flash *and* read the intro movie's 640×360 YUV planes as `ptbase2`. ✅ A regression of five events' observed frames against their declared times (residuals ≤0.9 frames) recovers the intercept at frame **106.1** when the composite spike, not in the fit, is frame **107**. ⚠️ Per-vertex alpha = fade alpha holds for the **glow** and does not generalise — `eff4` reads 255/127/254 on consecutive frames. ❔ Frame rate not recorded, so nothing is in seconds; the glow's period implies a **114**-unit cycle against a declared 120, unexplained; `eff5` vs `ptlogo_back2eff` not separated |
+| [`structures/boot-splash-gap-measured.md`](structures/boot-splash-gap-measured.md) | The black gap between the two boot splashes | ✅ **measured** in the guest's **draw stream**, which separates true black from a fade tail where luminance cannot: the publisher's last sprite is frame 125 (alpha 7), then **frames 126–129 submit NO sprite quad at all**, then the developer fades in at alpha 34. **The gap is 4 presented frames.** Converted with the disc as its own clock — `palogo_sqex` declares alpha≥1 for **239.8 units** and is drawn in **105** frames → **2.284 units/frame** (the title capture independently gave 2.231) — that is **~9.1 units ≈ 0.152 s**, against the **12** the port authored; ⚠️ and the true black is *shorter*, since both boundary frames still carry picture. 🔴 **RETRACTED**: "the developer splash is ONE composited 525×259 quad" — the same batching artefact. It draws three logos and three glows as separate quads in one `indices=24` call; the 525×259 was `gamearts_eff` merged with `seta_eff`. The port refuted it with arithmetic (a 259-tall box cannot hold logos spanning y 164…585) before I checked. ⚠️ The gap measurement is unaffected — those glows are the developer splash's first draw. ❌ Not declared on the disc: `palogo_eff0.prm` is a single static keyframe, and the top-level `+0x08` is a **family constant** (300 / 60) whose slack ranges 12–226 units. ❔ The executable is **not** looked at — named, not claimed. 🔴 The instrument was perturbing the measurement: the capture script taps Ⓐ on "screen changed a lot", which is also true of a fading splash — it tapped through the publisher and the developer never appeared. `GRACE=1` and `NOTAP=1` knobs added |
+| [`structures/ui-forced-backdrop.md`](structures/ui-forced-backdrop.md) | Where a keyless primitive paints, when the file forces it | ✅ **decoded**, partly closing `ui-prm-primitives.md`'s standing blocker: **an element covering the screen and fully opaque at some instant cannot paint above anything visible then**, and where that set is *every* other element its position is **forced first**. Disc-wide **80** instances forced, 50 constrained but not forced, 0 unconstrained. ✅ **Two controls, both measured orders from the running game**: it reproduces `palogo_eff0.prm` = FIRST (opaque 211 instants, below 6/6) — which a **name**-based rule gets wrong, since it is named like an overlay — and permits `pteff00.prm` on top (opaque 2 instants, below 3/23), which is where it is measured. ✅ Answers the port's `build_12`/`build_15` blank-screen contradiction: `pgloading_eff00.prm` is forced first, 4/4. ✅ Explains 36 builds the corpus recorded as "one colour" with no cause — `pzeff00.prm` forced first 32/32, so **our own sort wiped them**. 🔴 The rule's limit was found by its own test failing: applied to `.t32` sprites it claimed 22 must sort first against their own keys (`pneff01` 0xd850 at #8/13, `pbfriendly` 0x9230 at #17/49) — a sprite's *element* alpha says nothing about its *texture*'s coverage, so it is now restricted to untextured primitives. ⚠️ Assumes straight alpha-over; blend mode is still ❔. ⚠️ A lower bound, not an ordering. ⚠️ No new oracle run — the controls are prior measurements |
+| [`structures/tbm-submenu-not-reached.md`](structures/tbm-submenu-not-reached.md) | Does a `.tbm` draw pixels in the running game? | ✅ **YES — measured 2026-08-30**, and it closes the surviving "inert" reading in [ui-forced-backdrop](structures/ui-forced-backdrop.md). The `TUTORIAL` screen was reached and captured: a **full-screen blue circuit/hex background**, where `GP_TUTORIAL` build 0's **element 0 is `pubase.tbm`, pivot (640,360)** = 1280×720, the only full-screen *textured* element in the bundle (the other, `pueff00.prm`, is an untextured primitive the colour census puts at pure black). Our render of the same build is the **identical layout on pure black** — 6.0–6.4 % inked against the game's 99.7 %. So the rule's **24 `.tbm` deciders are correct, not harmless**, and 🔴 **`screen render` silently omits the background of every screen carrying a `.tbm`**. ⚠️ One `.tbm` observed; the class question is settled, the ten other families are not. 🔴 Getting there took three runs and cost two instrument failures worth reading: a 0.12 s Ⓐ during a screen load is **never delivered** (`[RE-INPUT]` is the only witness), and **correlation cannot identify a screen when the candidate renders are near-blank** — masked correlation failed its control (picked `EXTRAS` over the known menu by 0.004), a high-passed variant passed by only 1.28×, and **reading the title off the screen** settled it in one look |
+| [`structures/ui-forced-backdrop.md`](structures/ui-forced-backdrop.md) *(span sensitivity)* | How much of the forced-backdrop rule rests on the timeline convention | ✅ **decoded**: the span is `0..=max keyframe time over every element`, and an element **holds** its final pose — decoded, not assumed ([`ui-keyframe-time-unit.md`](ui-keyframe-time-unit.md), [`ui-record-loop-length.md`](structures/ui-record-loop-length.md)). Sensitivity over the 130 keyless full-screen primitives with an opaque interval: using the header's declared **`+0x08`** instead changes **0** verdicts (interchangeable); using the primitive's **own** last keyframe changes **72**; counting elements **gone** after their last keyframe changes **72**. 🔴 So the hold decides **55 %** of verdicts — and dropping it is **refuted by a measured order**: `palogo_eff0.prm` is a single keyframe at t=0, so without the hold it is opaque for one instant, nothing else is up, and the rule calls it *free* against a game measured painting it first. ✅ The verdicts that matter are convention-independent — `pgloading_eff00.prm` is FIRST under all four, `pteff00.prm` FREE under all four. ⚠️ The port's **256 vs 211** was a **bundle mismatch, not a definitional one**: `palogo_eff0.prm` runs to t=255 on the publisher splash (entries 10/13) and t=210 on the developer (11/14) |
+| [`structures/ui-clock-freezes-at-settle.md`](structures/ui-clock-freezes-at-settle.md) | The top-level clock stops at the settle point — observed in the running game | ✅ **measured**: `GP_TITLE` build 4 declares `t = 0…269`, about 120 presented frames at this run's pacing, and the dwell lasted **~1 100**. `ptcopyright` declares alpha≥1 for **106 units** (t=138…244) and is **drawn for 1 050 frames**; `ptlogo1` declares an exit at t=264 and is drawn for 1 095. Both vanish within three frames of the dwell ending. **The clock advances through the build-in, stops inside the settle window `[160,236]`, and holds; the exit ramp plays when the screen leaves, not on a timer** — [`ui-settle-time.md`](structures/ui-settle-time.md)'s decode observed from the other side. A nested record keeps looping on its own clock throughout. 🔴 **This closes the 114-vs-120 gap, and it was my arithmetic**: 2.231 units/frame was regressed over *build-in* events (the only stretch the top-level clock advances) and applied to a period measured during the freeze — two different clocks. The declared **120** was never in doubt from the calibration-free dark-fraction test. ✅ The 51.158-frame period is now confirmed by a **second independent estimator** (autocorrelation, lag 51 with harmonics at 102/154) — ⚠️ whose first version **failed its control**, returning 48, because it indexed by sample position where the log's frame numbers have gaps. ❔ The **sweeps'** period stays unmeasured: the same validated estimator disagrees between two dwells of one screen (515 vs 452 frames). 🔴 **Blocker: a single Ⓐ on the title faults the guest** — 3 attempts, 2 register dumps of 223 MB and 519 MB, against 3 no-input runs that all completed; bounds menu-side dynamic RE here, and any scripted button press needs a `canary.stdout` size guard |
+| [`structures/boot-splash-dwells-are-declared.md`](structures/boot-splash-dwells-are-declared.md) | How long each boot splash is shown | ✅ **decoded**: the dwells are the bundles' own declared timelines — publisher **t=0…255 = 4.250 s**, developer **t=0…210 = 3.500 s** at 60 units/s. The corpus's independent screenshot timing over 3 cold boots gives 4.30/4.60/4.37 and **3.51/3.50/3.37** — the developer agreeing to **1.1 %**, two of its three runs to 0.3 %. 🔴 **Wall clock is the wrong unit to author**: a fresh no-input boot measured the same two dwells at **5.10–5.61 s** and 3.83–4.30 s, 15–20 % longer than both the declared values and the corpus's runs, on the same disc — so a seconds figure is one run's emulator pacing. Boundaries from the draw stream: publisher wordmark frames 6–119, **3 frames with no sprite drawn**, developer glows 123, wordmarks 140–209, intro video 216. 🔴 **The frame→wall-clock instrument resolves to one BUFFER FLUSH, not one frame** — 69 of 125 samples showed no advance and the rest jumped 7–15 frames, making the apparent rate swing 0.0164–0.0316 s/frame; frames 119 and 123 fall in one burst, so the inter-splash gap is **not separable** by it. Quoted as brackets; sub-flush estimates withdrawn before reporting. ⚠️ `palogo_anima` never appears — almost certainly the 8-vertex cap (7 elements batched, 2 logged), the same trap as the `eff3` false negative, so it is named not reported. ❔ the publisher's 4.1 % error vs the developer's 1.1 % is unexplained |
+| [`structures/ui-forced-backdrop.md`](structures/ui-forced-backdrop.md) *(colour census + self-refutation)* | What colour a keyless element is, and which forced verdicts the argument actually supports | ✅ **decoded, disc-wide**: every full-screen `*eff00*` **primitive** is **pure black** at its various alphas (`ff000000`, `7f000000`, `40000000`, `b2000000`, `cc000000`, `d4000000`, `00000000`) — exactly an alpha-over dim or fade, and an *additive* black quad would be a no-op nobody would author. The **only** non-black primitive on the disc is `pbafc.prm`, RGB `00e8e0` cyan at alphas to `ff`, and it is **844×600, not full-screen**, so outside the backdrop rule's geometry guard — ❔ it is now the sole additive candidate. 🔴 **Self-refutation: of the 80 forced-first instances only 42 are `.prm`; 38 are `.tbm` carrying fade `ffffffff`.** A *solid* white quad painted first would make the screen white and no screen is white, so a `.tbm` is a white **modulation on a texture** — and element alpha does not establish its coverage. That is the `.t32` error one extension further out: I had fixed the symptom (`el.sprite.is_some()`) not the cause, **an element's alpha is not its texture's opacity, and only an untextured primitive makes the two the same fact**. So 42 verdicts stay **decoded**, 38 drop to 🟡 (still almost certainly right — all named `*base*`, full-screen, and `pfbase.tbm`'s first position is *measured* — but on a name-and-role argument this page elsewhere calls the weaker kind). ⚠️ Code deliberately unchanged: restricting to `.prm` would send eleven screens' backgrounds back to last, the blank-screen bug the rule fixed. Split pinned by a test |
+| [`structures/ui-prm-blend-mode.md`](structures/ui-prm-blend-mode.md) | Whether a primitive blends additively or alpha-over | ❔ **undecodable, with reach** — but the consequence is closed. Looked in **the bundle** (no field: the declaration words are constant and a primitive has no RATC child at all), **the colour census** (every full-screen `*eff00*` primitive is **pure black**; the only non-black primitive on the disc is `pbafc.prm`, cyan `00e8e0`), **the occlusion constraint** (inapplicable — `pbafc.prm` strobes 255/124 every 2 units, travels, and is scaled **2 %×3 %**, so it draws ~**17×18 px**, not its declared 844×600), and **the oracle** (`GP_READY_ROOM` is a recorded no-go and gameplay needs the Ⓐ that faults the guest). ✅ **Why it stopped mattering:** for a *black* quad the hypotheses differ only in whether it hides what is beneath — drawn **first** it is correct under **both**, drawn **last** only under additive. So `forced_backdrop`'s verdict is robust to the open question, and the port's original "layerless sorts last" was wrong under alpha-over and merely pointless under additive. ⚠️ This is not evidence *for* alpha-over. 🔴 The investigation found `forced_backdrop` judged coverage from the **pivot alone**, ignoring scale; checked first, **all 80 forced instances are at 100 %**, so no verdict moved and the added guard is defensive |
+| [`structures/title-a-press-fault.md`](structures/title-a-press-fault.md) | Why a single Ⓐ on the title faults the guest — the blocker on all menu-side dynamic RE | ✅ **SOLVED 2026-08-30, and it is the emulator, not the game.** Xenia returns `X_ERROR_SUCCESS` with a *zeroed* keystroke on every `XamInputGetKeystrokeEx` while a XAM dialog is up (`xam_input.cc:197`, upstream); the game's pump is an **unbounded** `while (GetKeystrokeEx()==SUCCESS) queue.push_back()`, so it queued **8 388 608** empty keystrokes, grew its vector to 64 MB, asked for 128 MB, got a failed allocation back **unchecked** and copied off the top of the guest thread stack. ✅ **The number is the argument**: the Canary counter reports **8 388 601** swallowed calls at the last report before the crash, the dump's `r29` says the vector held **8 388 608** — two independent instruments, 7 apart, inside the 600-call reporting granularity. No new boot: the failing run's 326 MB log was still on disk. 🔴 **RETRACTED — "`r9` is a wild pointer above 4 GB"**. Xenia prints `si_addr`, a *host* address, and the guest is mapped at `0x100000000`: `0x1701D0000 − 0x100000000 = 0x701D0000`, which **is** `r9` in the dump — an ordinary guest heap address on an uncommitted page. Subtract `0x100000000` from every `Access Violation … at 0x1________` before reading it. ✅ **Decoded code path**, image-checked with **0 mismatches** over 586 instructions: `sub_824574C0` the input-manager singleton at `0x828F3888`, `sub_82457038` the keystroke pump, `sub_82457780` its `vector<X_INPUT_KEYSTROKE>` insert-with-grow. ✅ **It explains the earlier successes**: whether a XAM dialog is up is *emulator* state, so "reproduced 4/4" and "Q4/Q5 pressed Ⓐ fine" were both always true. 🟡 **Which** dialog is still open — `XamShowDeviceSelectorUI` is ruled out (`storage_selection_dialog = false` takes the headless path), `XamShowSigninUI` / `XamShowMessageBoxUIEx` are not; the settling experiment is one log line per `is_xam_dialog_present_.store(true)` site, not another blind boot. 🟡 Three untried routes out: dismiss the dialog, `--headless`, or return `X_ERROR_EMPTY` from the swallow. ✅ `frame_clock.sh`'s 300 MB guard killed the run as designed — keep it |
+| [`structures/plate-pulse-phase-lock.md`](structures/plate-pulse-phase-lock.md) | Does gating on the plate pulse bias what a title capture can show? | ✅ **measured — it PHASE-LOCKS the shutter.** The plate's pulse is part of the animation, so `wait_plate_pulse.py` does not only wait for settling, it synchronises the shutter to the animation's phase: at the shutter instant the sweep strips sit **25–26 px apart across two runs in different locales and different sessions** — **1.6 %** of a ~1600 px traverse. 🔴 **Consequence: the RMSE 0.32 recorded as "between-session capture noise" is a lower bound produced by the instrument, not a property of the game**; the honest figure at an arbitrary phase is **11.9**, a factor of 37, and I had read 0.32 as evidence the JP title is still when it is evidence the gate works. ✅ **The era adjudication survives** — margin **16.72** clears even 11.9 — and survives *for the reason its own file gave*: correlated noise moves both candidates together and cancels in a margin, so prefer margins to absolute scores under a gated shutter. ✅ The within-run at-rest result also survives (five frames ~1.5 s apart are not gated individually). ⚠️ Reach: this shows the lock, not its mechanism — both runs boot the same ISO from the same state, so a deterministic boot could produce it without the gate; **two runs deliberately shuttered at gate + k frames would separate those** and were not run |
+| [`structures/plate-pulse-measured.md`](structures/plate-pulse-measured.md) | Does the `PRESS Ⓐ` plate stay up, pulse, or blink once? | ✅ **measured** — it **PULSES**, continuously and without decay, on a title held with **no input**: two windows in one boot, 58 s and 57 s, ~23 cycles each, periods **2.530 / 2.540 s** agreeing to 0.4 %. ⚠️ **It never goes off** — the plate-absent floor is **159** green pixels (the title art's own, from `live-title-build4-no-plate.png`) and the pulse bottoms at **714**, 4.5× that. So the port's "flash and nothing after", reasoned from `ptbtn00` expiring at t=244, is wrong; `ptbtn00f`'s 120-unit cycle is what runs. 🔴 **Two estimators, one misspecified**: mid-crossings replicate to 0.4 %, a single-sinusoid fit does not (2.553 vs 2.413) because the waveform is fast-rise/slow-decay — and its own r² of 0.468/0.228 is the tell. Both were controlled on synthetics at 2.24/2.55/3.10 s laid on the real timestamps and recovered all three exactly. 🟡 wall-clock is **13 % longer** than the corpus's earlier 2.24 s mean — same declared 120 units, different pacing (×1.27 vs ×1.12), so **author the units**. ⚠️ Reach: one boot; does not distinguish the boot title from an attract-loop title; the glyph count is a thresholded pixel count and **not** an alpha, so no duty cycle can be read off it |

docs/re/REFUTED.md

@@ -617,3 +617,175 @@ neighbourhood, not just the line.
   `10 144 of 10 148 references resolve`) → **withdrawn; it is on the disc.** It is
   the `GP_STAGE_CLEAR` child the same scan named `8AX`. With the name decoded the
   count is **10 148 of 10 148**. [`ratc-child-names.md`](structures/ratc-child-names.md)
+
+## UI timing (2026-08-29)
+
+* "a screen has SETTLED at its `rest.t`" → **refuted.** `rest.t` is the last
+  *hold* keyframe before the exit, not the end of motion. Build 4's `ptlogo1`
+  rests at `t=251` and stops moving at **`t=42`**; the title's visible build-in
+  ends at `t≈118`, where `pteff01`, `pteff02.prm` and `ptlogoall_eff` end their
+  ramps together. Believing `rest.t` put a port's plate 3.97 s late —
+  [`title-plate-delay-measured.md`](title-plate-delay-measured.md).
+* "the `PRESS Ⓐ` plate is composited a measured 2.13 s after the title settles,
+  and the port should author that" → **the measurement stands, the instruction
+  was refuted by the port.** Build 2 has a keyframe group of its own; both builds
+  run on **one clock started together** and the plate's declared `t=238` supplies
+  the timing, so nothing is authored. `238 − 118 = 120 units = 2.000 s`, of which
+  2.13 s was a wall-clock reading stretched by Canary presenting at ~28.1 fps.
+  ⚠️ General lesson: **a wall-clock duration off this emulator is ~6 % long**, so
+  a measured interval that lands near a round number of units probably *is* that
+  number of units.
+* "a music bank has three sub-waves" → **refuted; it was our reader.** The third
+  is the bank header, emitted because `to_xma_riffs` derived a leading packet
+  stream's start as `first_riff % 2048` — valid only for a header shorter than
+  one packet. 28/28 disc-wide —
+  [`structures/slb-bank-header-not-a-wave.md`](structures/slb-bank-header-not-a-wave.md).
+
+## The oracle harness and the container (2026-08-29)
+
+* "the decoder container has no disc" → **refuted the same day.** The container
+  was replaced and `/disc` is a real 6.2 GB read-only mount. Worse, both
+  instruments behind the claim were blind to the answer either way:
+  `find / -xdev` **cannot cross** into a bind mount on another device, and
+  `sylph-doctor` only checks `/work` and never `$SYLPHEED_DISC`. "sylph-doctor
+  agrees" was two instruments sharing one blind spot.
+  → To test for the disc, ask the variable that names it:
+  `sylpheed-cli screen list "$SYLPHEED_DISC/dat/GP_TITLE.pak"`.
+* "the main menu returns to the title on its own after ~8–10 s idle" → **refuted.**
+  The menu sat untouched for **≥ 60 s** without moving (correlation never leaving
+  0.9245–0.9249). The ~8–10 s idle is real but belongs to the **title**. This was
+  the only reason "Ⓑ leaves the main menu" was classed as authored.
+* "whole-image statistics (green / white / mean) can tell the title from the
+  attract movie" → **refuted.** A frame of `ADV.wmv` with a bright green laser
+  reads green 0.0018 / white 0.086 / mean (53,67,76) — the title's numbers. A
+  probe built on it tapped Ⓐ into the movie and waited 120 s for a menu that was
+  never coming. → Correlate against a committed capture instead, and keep movie
+  frames as the negative controls.
+* "a 360-bin angular cross-correlation can measure the focus ring's rotation
+  angle" → **refuted by its own control**: a synthetic **30°** rotation of a live
+  frame came back as **0°** (peak 0.596), while 90/180/270° came back exactly
+  (peak 1.000) — it only resolves exact pixel permutations. No angle was quoted;
+  the spin was established from brightness conservation instead.
+* "a latency read off a classified `x11grab` stream is a duration" → **refuted.**
+  At 1503 ms per classification against an 8 fps stream the consumer ran at
+  0.64 fps, so frames were stale and increasingly so. Four "durations" died with
+  it. The tell was that a screen transition, a button press and a plate fade all
+  came out at ~20–25 s. → A backlog **preserves ordering and destroys
+  durations**; check consumed-fps against requested-fps before quoting a time.
+
+## UI timing and transitions (2026-08-30)
+
+Seven claims died this session. Each was recorded in its own page at the time,
+and **none of them reached this file** — which is the one the brief says to grep
+before proposing anything. A refutation that lives only where it was made is not
+reachable by the person about to repeat it.
+
+* "the fade-OUT duration is not in the file — the port must author it" → **mine,
+  and wrong in every sentence.** The [record-layout
+  fix](ui-keyframe-record-layout.md) times a group's final pose, so block 4
+  carries `t = 80` / `74` / `269`: the ramp is **decoded** at 10 / 10 / 8 units.
+  The section asserting this stood 78 lines above its own correction, in a
+  heading, telling the port to author a decoded value.
+  [`screen-transitions.md`](screen-transitions.md)
+* "the ~14 units the fade-out does not account for are a black HOLD" → **mine,
+  arithmetic that fit.** Measured: the content elements' own fade-outs, starting
+  six frames before the quad's ramp. [`screen-transitions.md`](screen-transitions.md)
+* "the black interval between screens is a LOAD" → **mine, refuted three ways.**
+  Bundle size runs backwards (the 12.3 MB screen gaps 0, the 7.0 MB one gaps 3);
+  the gap is 3 frames in three independent runs; and press-to-change latency moved
+  ~12 frames between those runs while the gap did not move at all.
+  [`screen-transitions.md`](screen-transitions.md)
+* "Ⓑ has no black interval" → **mine, one screen pair generalised.** `EXTRAS → menu`
+  via Ⓑ gives **two completely empty frames**. [`screen-transitions.md`](screen-transitions.md)
+* "`ptloop01`/`ptloop02` do not free-run on the settled title" → **mine, measured
+  over the wrong rectangle.** The parent's `(441,270)` 200×90 is a **pivot anchor**;
+  the leaf sweeps a 400 px quad whose left edge travels −639…1521. The zero was
+  measured in a dead zone. [`structures/ui-resting-pose.md`](structures/ui-resting-pose.md)
+* "the game runs the splash dwells ~8.5 % long" → **mine, and it was one element's
+  visible span read as the screen's.** The `_eff` glow is lit from t≈0 while the
+  logo is still transparent, so the screen's visible span is the full group. Six
+  ratios recomputed to a mean of 1.0146 with one below unity.
+  [`boot-order-and-splash-dwell.md`](boot-order-and-splash-dwell.md)
+* "`EXTRAS` can supply only one transition measurement — a **structural** limit"
+  → **mine, and refuted by one `screen info`.** Build 6 declares three buttons
+  (`ptbtn11/12/13`, kind `0x3002`). ⚠️ `sylpheed-port` had copied this sentence out
+  of a message into their own record as an established fact **while holding the
+  file that refuted it**. [`data/fade-four-transitions.txt`](data/fade-four-transitions.txt)
+* "the black gap is determined by the OUTGOING screen" → **mine, superseded
+  twice.** The same origin gives 0 and 1 to different destinations; every repeated
+  *pair* is identical across five replicates. The pair determines; the origin only
+  constrains. [`data/fade-four-transitions.txt`](data/fade-four-transitions.txt)
+
+### The JP title might not draw the sweep leaves at rest — ❌ REFUTED (2026-08-30, mine)
+
+* ~~"the JP title does not draw the sweep leaves at rest"~~ — refuted, see below.
+* ~~"build 7's denser logo stack occludes the sweep leaves"~~ — refuted, see below.
+
+I hypothesised that build 7's denser logo stack (katakana + crystalline burst)
+**occludes** the two sweep leaves, to explain why two JP title captures differ by
+RMSE 0.32 inside the adjudication box while two EN captures a plateau-phase apart
+differ by 11.9. A draw capture in `ja` (control: the same extraction on the EN
+title log) shows the **same three tall ROT strips, same dimensions, at HIGHER
+alpha than English** — 180/188/194 vs 160/168/166. There is no absence to
+explain. [data](data/title-sweep-jp-draw-capture.txt)
+
+The 0.32 had a different cause: **my own gate**. See below.
+
+### "Two sessions sample a free-running clock" — ❌ REFUTED (2026-08-30, mine)
+
+* ~~"a free-running clock lands somewhere else on a fresh boot"~~ — refuted, the gate phase-locks it.
+* ~~"the in-box capture noise of 0.32 between sessions"~~ — refuted as a noise floor; it measures the trigger.
+
+`jp-title-at-rest.txt` justified a second capture as probing the between-run axis
+"where a free-running clock lands somewhere else on a fresh boot", and reported
+its in-box **0.32 as capture noise**. Measured at the shutter instant, the sweep
+strips sit **25–26 px apart across two runs in different locales and different
+sessions** — 1.6 % of a ~1600 px traverse. The plate pulse *is* part of the
+animation, so gating on it phase-locks the shutter. **0.32 is a lower bound
+produced by the instrument, not a property of the game**; the honest figure at an
+arbitrary phase is 11.9. The era adjudication is unaffected — its margin, 16.72,
+clears even 11.9. [details](structures/plate-pulse-phase-lock.md)
+
+### Refutation attempt on `sylpheed-port` — ✅ THE CLAIM SURVIVED (2026-08-30)
+
+**Target:** the port's rejection of a positional mechanism, resting on 98 % of
+off-edge area matching exactly with a residual of ±1–2 levels *inside lit logos*.
+
+**My attempt:** if the sweep leaves' ink crosses the logos, that residual could
+be sweep ink our renderer omits — and phase-locking would have made it look
+stable across sessions rather than exposing it.
+
+**Result: refuted, the claim stands.** `jp-title-at-rest.txt` has five frames
+~1.5 s apart *within* a run — not gated individually, so genuinely different
+sweep phases — and the 350×396 logo ROI is **byte-identical across all of them
+(0 / 138 600 px differing, max |d| 0), reproduced in two independent sessions**,
+while 5–8 % of the whole frame moves as a contrast control. The sweep ink does
+not land on the logos. The ±1–2 residual is not sweep.
+
+### Music-bank stems (2026-08-30)
+
+* ~~"wave 1 is wave 0 put through a filter"~~ — ❌ **refuted** on `BGM_103` by
+  magnitude-squared coherence. A real linear filter of wave 0 reads **0.93–0.94**
+  in every band (positive control); the measurement reads **0.027** at 1–4 kHz.
+  No linear filter does that in a band where both waves carry energy.
+  [data](data/bgm-stem-coherence.txt)
+* ~~"the rear-pair reading can be tested by coherence"~~ — ❌ **refuted, and it was
+  my own test's premise.** The control that matters — L vs R *within* one wave,
+  genuinely one performance in two channels — reads only **0.221–0.497**, so in
+  this material "same performance" does not imply high coherence. A 4-channel
+  mix's rear pair is not a linear filter of its front pair, so the discriminator
+  never had the power to separate the two readings. The 🟡 stands.
+
+### Refutation attempt on the corpus's "two stems of ONE PERFORMANCE" — 🟡 SURVIVED, WEAKENED (2026-08-30)
+
+**Target:** `structures/bgm-two-stems.md` (the `BGM_103` section is another
+agent's), which reads the two waves as two stems *of one performance*.
+
+**My attempt:** if they are one performance, they should share signal structure;
+coherence should be well above the independent floor across the bands carrying
+the music.
+
+**Result: the claim survives, but one of its supporting readings is dead and the
+bands carrying 96 % of the energy read 0.169 and 0.184** — far above the 0.001
+independent floor, so *not* independent, and far below a filtered copy. "One
+performance" stands; "rear pair, i.e. a filtered view of the same mix" does not.

docs/re/audio-capture-alsa-file-tee.md

@@ -0,0 +1,239 @@
+# ✅ Capturing the emulator's audio: the ALSA `file` tee, and why PulseAudio's monitor cannot do it
+
+**Classification: measured**, on the capture chain. Supersedes the tuning advice
+in [`audio-capture-channel-map-trap.md`](audio-capture-channel-map-trap.md),
+which chased the wrong subsystem.
+
+## The root cause of every bad capture so far
+
+A PulseAudio null sink's **monitor is sampled on a wall clock**. When the client
+is late, PulseAudio does not wait — it **emits silence to keep its own
+timeline**. So the 39.3 % silence measured in the take-2 capture was never audio
+that went missing; it was silence PulseAudio *invented*.
+
+That is why `PULSE_LATENCY_MSEC` produced a non-monotonic curve (39.3 % → 15.6 %
+→ 50.1 % silence at 5.3 / 200 / 500 ms) and never won: **the buffer size trades
+gap count against gap size, and no setting escapes a clock the capture point
+does not share.** The instrument was wrong, not mistuned.
+
+**ALSA's `file` plugin has no clock at all.** It tees exactly what the client
+writes. A slow producer yields a *shorter file*, not a gap-riddled one — turning
+a data-loss problem into a time-base problem, which is the right trade when the
+question is "is the correct audio playing".
+
+## ✅ Control — 6 distinct tones, byte-exact
+
+| | |
+|---|---|
+| source | 12.000 s, 6 channels at 400 / 800 / 200 / 1600 / 3200 / 6400 Hz |
+| captured | **12.000 s**, **0.00 % silence**, **0 gaps**, no duplicate channels |
+
+⚠️ **Channel order is ALSA's, not WAV's.** Captured channel *i* holds source
+channel `[0,1,4,5,2,3]` — i.e. `FL FR BL BR FC LFE` where the WAV file had
+`FL FR FC LFE BL BR`. Deterministic, invertible, and **not** data loss; do not
+mistake it for the remap corruption documented in the companion page.
+
+🔴 **But this permutation does NOT travel — measure it per capture.** It was
+measured on *this* chain, with these tones. A later Canary capture through the same
+recipe came out as the **identity**, and labelling its channels from this table put
+the silent channel on `BR` when it was `LFE`
+([`structures/intro-audio-decomposed.md`](structures/intro-audio-decomposed.md)).
+A 6×6 correlation against a known reference costs nothing and is **its own control**:
+if every row's maximum falls on a distinct source channel, the mapping is a genuine
+permutation and you have measured it rather than assumed it.
+
+## The three configuration traps, in the order they bite
+
+1. **`ALSA_CONFIG_PATH` REPLACES the entire ALSA config.** Without
+   `</usr/share/alsa/alsa.conf>` the named `null` device is undefined and the
+   client fails with `Input/output error`.
+2. 🔴 **But with that include, overriding `pcm.!default` silently does not
+   take** — no error, no file, the client runs happily to completion. Both the
+   full inline form and the `pcm.!default "name"` alias failed this way.
+   **The fix is to drop the include** and declare the slave with an *inline
+   plugin type* (`{ type null }`, `{ type pulse }`), which needs no named
+   reference. Xenia hardcodes `snd_pcm_open(..., "default", ...)`
+   (`alsa_audio_driver.cc:150`), so `default` **must** be the tee — a named
+   device is not reachable.
+3. **`| head -N` kills the producer.** An `ffmpeg … | head -3` SIGPIPEs ffmpeg
+   before it writes, and the symptom is "no file" with no error — indisting-
+   uishable from a broken config.
+
+## 🔴 And the reason a bare `file` tee is NOT enough for Xenia
+
+Xenia's ALSA driver runs a writer thread that **pads silence whenever its ring
+buffer is empty** (`alsa_audio_driver.cc:359`). Against a device that never
+blocks, `snd_pcm_avail_update` always reports space, so the thread spins:
+
+> **Measured: ~250× real time — 7.34 GB, 12 746 s of nominal audio, in ~50 s of
+> wall clock**, nearly all of it driver-generated silence. It was killed and the
+> file deleted; it would have filled the disk.
+
+⚠️ This is exactly the limit the route's proposer flagged — it had been verified
+with `ffmpeg` as the client, which is self-paced, and **not** with Canary, which
+pads.
+
+## ✅ The configuration that satisfies both constraints
+
+**Tee in front of a paced slave.** The file plugin captures what the client
+writes; the slave supplies the clock that stops the driver free-running. The
+wall-clock silence-insertion then happens *downstream of the capture point*
+rather than inside it.
+
+```
+# NO include: `type pulse` is an inline plugin type, and the include is what
+# makes a pcm.!default override fail to take.
+pcm.!default {
+    type file
+    slave.pcm { type pulse }
+    file "/path/to/capture.raw"
+    format raw
+}
+```
+
+```bash
+ALSA_CONFIG_PATH=…/asound-tee-pulse.conf PULSE_SINK=cap \
+  run-canary --apu=alsa --mute=false …      # "$@" is last, so both win
+ffmpeg -f s16le -ar 48000 -ac 6 -i capture.raw out.wav
+```
+
+✅ Control through this exact config: **12.000 s, 0.00 % silence, 0 gaps.**
+
+⚠️ **`--apu=alsa` is a third option neither agent had tried.** The note that
+`--apu=nop` stalls the guest in the intro movie still stands and is why
+`--mute=true` was there; it says nothing about the ALSA backend.
+
+## ✅ Measured on Canary — and the residual silence changes meaning
+
+150 s boot, `--apu=alsa --mute=false`, tee in front of the paced pulse slave.
+⚠️ **Xenia's ALSA driver is `SND_PCM_FORMAT_FLOAT_LE`** (`alsa_audio_driver.cc:173`)
+and its log confirms `ALSA initialized: 48000 Hz, 6 channels (output: 6),
+period: 512, buffer: 2048`. The raw tee is therefore **float32, 6 channels** —
+reading it as `s16` produces a plausible-looking file with a giveaway signature:
+peaks alternating exactly `−0.00 / −4.82 / −0.00 / −4.82 / −0.00 / −4.82`, which
+is the two halves of each float landing in alternate "channels".
+
+| capture route | silence | gaps/s | notes |
+|---|---|---|---|
+| PulseAudio monitor, xenia default (~5.3 ms) | 39.3 % | 30.5 | |
+| PulseAudio monitor, `PULSE_LATENCY_MSEC=200` | 15.6 % | 3.5 | |
+| PulseAudio monitor, `PULSE_LATENCY_MSEC=500` | 50.1 % | 1.3 | |
+| **ALSA tee → paced pulse slave** | **9.98 %** | 8.37 | 106.2 s captured over ~151 s wall = **0.70× real time** |
+
+**The file is short rather than gap-riddled, which is the intended trade** — and
+six distinct channels, no duplicates, sensible peaks (−4.41 / −3.96 / −4.41 /
+−11.65 / −8.09 / −6.53 dBFS).
+
+🔴 **But the residual ~10 % silence is NOT removed, and its meaning has changed.**
+It is no longer invented by PulseAudio's monitor — the tee records exactly what
+Xenia wrote, and **Xenia wrote silence**, because its writer thread pads whenever
+the guest has not filled the ring (`alsa_audio_driver.cc:359`). So:
+
+* ✅ the capture is now **faithful** — every sample in it is a sample the
+  emulator emitted;
+* ❔ the emulator is still emitting padding, because the guest runs at ~0.7× real
+  time here, and **no capture method can remove that**. Fixing it needs the guest
+  to keep up, or a change to the driver's padding behaviour.
+
+⚠️ **So this is a 3.9× improvement in silence and a change of attribution, not a
+clean capture.** At 9.98 % / 8.37 gaps/s it sits right on the port's "≥10 %
+silent *and* ≥1 gap/s" fail bar. **Do not treat it as an oracle without saying
+which side of that line it fell on.**
+
+## ✅ SOLVED — `--gpu=null` removes the residual, and the capture is clean
+
+The residual padding was the guest running at **0.70× real time**, and the
+dominant load is **llvmpipe software rendering** — which an *audio* capture does
+not need at all.
+
+| configuration | silence | gaps/s |
+|---|---|---|
+| PulseAudio monitor, xenia default | 39.3 % | 30.5 |
+| ALSA tee → paced slave, rendered (llvmpipe) | 9.98 % | 8.37 |
+| **ALSA tee → paced slave, `--gpu=null`** | **0.31 %** | **0.01** |
+
+**One gap in 67.7 s.** Six distinct channels, no duplicates, peaks −5.15 / −4.55
+/ −4.47 / −11.65 / −6.73 / −6.40 dBFS. For scale, the port's *genuine music bed*
+control measures 1.1 % silence at 3.3 gaps/s — **this capture is cleaner than
+their known-good reference.**
+
+✅ **Control that the run is still comparable:** `ADV`'s three XMA contexts
+(1 294 336 / 1 118 208 / 1 171 456) appear in the `--gpu=null` log, so the
+movie's voice is decoding exactly as in a rendered boot. That is also better
+provenance for an *audio* question than screenshots were — it evidences the thing
+being recorded rather than what was on screen.
+
+### The full working recipe
+
+```bash
+MAP=front-left,front-right,front-center,lfe,rear-left,rear-right
+pactl load-module module-null-sink sink_name=cap channels=6 channel_map=$MAP
+# asound.conf: NO include; tee in front of a PACED slave
+#   pcm.!default { type file  slave.pcm { type pulse }  file "…"  format raw }
+ALSA_CONFIG_PATH=…/asound.conf PULSE_SINK=cap \
+  run-canary --apu=alsa --mute=false --gpu=null …
+ffmpeg -f f32le -ar 48000 -ac 6 -i capture.raw out.wav      # float32, not s16
+```
+
+⚠️ `--gpu=null` means **no video**, so screen-based provenance is unavailable —
+use the XMA probe instead. And it is only appropriate when the question is about
+audio; it changes what the guest is doing.
+
+## ✅ The distinction that makes even an imperfect tee capture usable
+
+Contributed by the port, and it is sharper than the framing this page had:
+
+* **PulseAudio's monitor SUBSTITUTES.** Audio that existed is *replaced* by
+  silence to keep the wall clock. Information is destroyed, and deleting the
+  holes cannot recover it — it only compresses time unevenly.
+* **Xenia's padding is ADDITIVE.** The silence is *inserted between* samples the
+  guest emitted. **Nothing is lost.** Every real sample is present and in order.
+
+So **stripping all-channel-zero runs from an ALSA-tee capture is exact, not a
+repair** — it returns a contiguous stream of everything the guest produced. That
+means even the 0.70×-real-time rendered capture (9.98 % padded) is usable for
+correlation, where none of the PulseAudio-monitor captures ever were, however
+they were tuned.
+
+✅ **VERIFIED 2026-08-29.** The port controlled it rather than relying on the
+reasoning: a real music+SFX bed (137.37 s, carrying **454 genuine zero runs of
+its own**, which is what makes it an honest control) had **1 149 holes inserted
+at 8.37 gaps/s to +9.9 % length** — matching the measured ALSA profile — then
+stripped:
+
+| | r | lag | margin |
+|---|---|---|---|
+| original vs itself (ceiling) | 1.000 | 0.0 s | +0.141 |
+| **padded** vs original | **0.436** | −12.2 s | **+0.006** |
+| **stripped** vs original | **1.000** | **0.0 s** | **+0.142** |
+
+Two things beyond the yes:
+
+* ✅ **It runs the inference forwards.** Padding at this profile puts correlation
+  squarely in the known-absent regime (margin +0.006) on a file whose contents
+  are controlled — so the earlier captures were unusable *for the reason claimed*
+  rather than for some other one. Until now that was reasoning backwards from a
+  failure to a cause.
+* ✅ **Only ONE side needs stripping.** The stripped capture matches the
+  **unstripped** source at the ceiling, so a capture needs no preprocessing at
+  all before being handed over — no shared step for two parties to get out of
+  sync on.
+
+🔴 **And the danger, which is the part to repeat:** stripping removes *genuine*
+silence too and cannot tell the two apart. It is **exact on additive ALSA
+padding and vandalism on a PulseAudio monitor capture**, where the silence
+replaced real audio. On mostly-silent material the genuine runs would cost
+something measurable — here they totalled 0.71 s in 137 s and cost nothing.
+⚠️ **Running it on the wrong artefact would look like it worked.**
+
+⚠️ **Consequence for `check-capture`:** its silence/gap-rate rule was built when
+only *damage* existed, and **cannot distinguish genuine emulator padding from
+capture damage.** A FAIL on an ALSA-tee capture is a statement about the
+recording path, not about the file's usability.
+
+## Consequences for verification
+
+🔴 **Short file becomes the failure mode**, so a capture check needs an
+**expected-duration** test alongside silence fraction and gap rate. And a
+**runaway guard** is not optional: abort if the file exceeds ~3× real time, or
+one misconfiguration writes 7 GB before anyone looks.

docs/re/audio-capture-channel-map-trap.md

@@ -0,0 +1,308 @@
+# 🔴 A 6-channel PulseAudio capture SCRAMBLES AND DUPLICATES channels unless the maps match
+
+**Classification: measured**, on the capture chain itself rather than on the
+game. Recorded because a capture taken with this defect was handed to the port
+as evidence, cost them a full controlled analysis, and the negative they
+correctly reported was **my instrument, not the guest**.
+
+## What happened
+
+`adv-game-output-6ch.wav` was captured from Canary through a PulseAudio null
+sink and shared as "what the game emits during `ADV`". The port could not match
+it against **anything** — the `ADV` bed, any of the three XMA voice streams,
+`BGM_103`, `S00A` — with best-vs-runner-up margins of 0.001–0.016 everywhere,
+i.e. plateaux rather than peaks. They controlled that three ways (their
+instrument finds `bed` vs `bed` at r=1.000 margin +0.115; their `.ogv` reference
+matches the disc's `.wmv` at r=1.000 margin +0.114; and drift was excluded by
+windowed lags scattering across the movie). They also observed that **capture
+channels 3 and 6 were byte-identical, same MD5**.
+
+That duplicate pair is the tell, and it is reproducible without the emulator.
+
+## The control I should have run first
+
+Six channels, each a **different** tone, so any reorder, drop or duplication
+shows up as a wrong frequency. Played to the sink with `paplay`, recorded from
+its monitor with the same `parec` invocation the `ADV` capture used.
+
+**Sink map `FL,FR,RL,RR,FC,LFE`, i.e. NOT the stream's map — the original setup:**
+
+| channel | expected | captured | |
+|---|---|---|---|
+| 0 | 400 Hz | 400 Hz | ok |
+| 1 | 800 Hz | **3200 Hz** | wrong |
+| 2 | 200 Hz | 200 Hz | ok |
+| 3 | 1600 Hz | **800 Hz** | wrong |
+| 4 | 3200 Hz | **800 Hz** | wrong |
+| 5 | 6400 Hz | **200 Hz** | wrong |
+
+`ch2 == ch5`, **byte-identical** — the same artefact the port found. The 6400 Hz
+and 1600 Hz channels are **gone entirely**, replaced by duplicates.
+
+**Sink map made identical to Canary's own stream map**
+(`front-left,front-right,front-center,lfe,rear-left,rear-right`), and the same
+map given to `parec` explicitly:
+
+| channel | expected | captured |
+|---|---|---|
+| 0–5 | 400 / 800 / 200 / 1600 / 3200 / 6400 | **400 / 800 / 200 / 1600 / 3200 / 6400** |
+
+No duplicates. **CONTROL PASSED.**
+
+## 🔴 And a LEVEL CHECK cannot see this failure — by construction
+
+The port made this point while building a checker for it, and it refutes
+something written above.
+
+In the known-bad control, **all six channels report a peak of −18.063656 dB,
+identical to six decimals, while the file contains three duplicate pairs.** Equal
+tone amplitudes make the peak table uniform no matter how the channels are
+permuted or duplicated — and on *real* content the peaks simply differ from each
+other, which looks equally healthy. Either way the table is uninformative.
+
+⚠️ So "the WAV has plausible per-channel levels" was not weak evidence that the
+capture was sound; it was **no** evidence, and this page said otherwise. The
+per-channel peak table is the natural thing to eyeball after a capture and it is
+**blind to remap corruption**. What detects it is hashing each channel and
+comparing — the port's `tools/port/check-capture`, controlled in both directions
+(six distinct tones → PASS; this page's known-bad pattern → FAIL naming all four
+pairs; the withdrawn capture → FAIL on `ch2 == ch5`).
+
+## The rule
+
+⚠️ **A null sink whose `channel_map` differs from the client's makes PulseAudio
+remap, and a 6-channel remap silently loses channels and duplicates others.**
+There is no error, no warning, and the WAV has the right length, the right
+channel count and plausible per-channel levels. Set the sink's map to the
+client's, and pass the same map to `parec`:
+
+```bash
+MAP=front-left,front-right,front-center,lfe,rear-left,rear-right
+pactl load-module module-null-sink sink_name=cap channels=6 channel_map=$MAP
+parec -d cap.monitor --channels=6 --rate=48000 --format=s16le --channel-map=$MAP …
+```
+
+## 🔴 What this withdraws
+
+* **`adv-game-output-6ch.wav` is withdrawn as evidence.** Its channels are
+  scrambled and one pair is a duplicate. Nothing should be concluded from it,
+  in either direction — it is not evidence that the game emits something
+  unexpected, and the port's inability to match it is fully explained.
+* **"All six channels carry signal"** — withdrawn. One of the six was a copy of
+  another.
+* **"The surround and LFE channels are not zero, which a stereo guest padded
+  into a 6-channel frame would give"** — withdrawn. It was offered as weak
+  support for the 5.1 reading of a voice cue's three streams
+  ([`voice-three-streams-are-concurrent.md`](structures/voice-three-streams-are-concurrent.md)),
+  and it is worth nothing. The port said a duplicated channel is not an
+  independent one, and they were right before this control existed.
+
+✅ **Unaffected:** the three-XMA-context concurrency result. That is read from
+the emulator's own log, not from the audio path, and it reproduced on two
+independent boots.
+
+## The lesson, in the form it should have been applied
+
+The corpus's own rule is *run your instrument through a control first*. Here the
+control needed no emulator, no disc and 30 seconds: **play a known signal through
+the capture chain and check that it comes back.** It was not run, an artefact was
+published, and the person who found the defect was the one who could not see the
+instrument. ⚠️ **A capture is an instrument, not just an output** — the same
+scrutiny a parser or an estimator gets.
+
+---
+
+## ✅ The capture that passes — recipe, and how it proves itself
+
+Take 2, 2026-08-29. Verified with the port's independent
+`tools/port/check-capture` (six distinct channel MD5s → PASS) **before** being
+shared, deliberately using their tool rather than the hand that made the file.
+
+```bash
+MAP=front-left,front-right,front-center,lfe,rear-left,rear-right   # Canary's own
+pactl load-module module-null-sink sink_name=cap channels=6 channel_map=$MAP
+parec -d cap.monitor --channels=6 --rate=48000 --format=s16le \
+      --channel-map=$MAP --file-format=wav out.wav &      # recorder FIRST
+PULSE_SINK=cap SDL_AUDIODRIVER=pulseaudio \
+  run-canary --mute=false …                                # both mutes off
+```
+
+Two properties make it self-checking, and both were the port's asks:
+
+* **The recorder starts before the emulator**, so WAV `t=0` precedes process
+  launch and the movie cannot fall outside the window by accident.
+* **A screenshot every ~11 s, keyed to the recording's own clock.** Classified
+  against the committed references afterwards, this run reads `movie/other` for
+  **t = 10 … 251** and then `title_noplate` at **t = 262** (r = +0.998),
+  `title_plate` at 277/289. So the 253 s of audio sits wholly inside the movie,
+  with the title arriving just after it ends. **A miss would now be diagnosable
+  instead of ambiguous** — which is the whole difference from take 1.
+
+⚠️ It is still the **full mix** — the movie's own WMA bed plus the voice streams.
+Nothing at this boundary separates them.
+
+## ❔ New, unexplained: this run decoded FIVE XMA streams, not three
+
+`--xma_param_probe` on the take-2 boot logs five distinct `byte_size` values:
+`ADV`'s three (**1 294 336 / 1 118 208 / 1 171 456**) plus **1 150 976** and
+**1 269 760**. The extra pair belongs to some other cue and is unidentified —
+they are not `BGM_103`'s two waves (3 876 864 / 3 930 112). A *pair* is the shape
+[`bgm-two-stems`](structures/bgm-two-stems.md) documents for music banks, so a
+second bank is the first guess and it is untested.
+
+---
+
+## 🔴 TAKE 2 IS ALSO UNUSABLE — the sink is being STARVED, 39.3 % digital silence
+
+Take 2 passed the duplicate-channel check and carried a verified screen log, and
+the port still could not find either the movie's WMA bed or the cutscene voice in
+it — this time with a **calibrated** correlator (they had retracted their first
+one: it scored 0.415 hunting a bed inside a synthetic mix that certainly
+contained it, so it could not have found the target even when present). Their
+rebuilt instrument passes both directions, and their negative on take 2 stands.
+
+They named the two readings: *the capture path is still losing the guest's mix*,
+or *the guest is not emitting these sources*. ⚠️ They flagged the second as
+landing on them hard — if the game never plays the `.wmv`'s WMA track, the port's
+intro audio has been wrong since P4.
+
+**It is the first, and the capture says so on its face.** Take 2, measured
+directly:
+
+| | |
+|---|---|
+| frames that are digital silence on **all six** channels | **6 557 892 / 16 680 453 = 39.3 %** |
+| non-silent runs | **10 595**, median **13.60 ms**, longest 1.19 s |
+| silent runs | **10 596**, median **3.94 ms** |
+| burst + gap period | **≈17.5 ms → 57 Hz**, duty cycle **60.7 %** |
+
+The recording is chopped into ~13 ms fragments separated by ~4 ms holes, ten
+thousand times over. That is a **starved sink** — PulseAudio filling underruns
+with silence because the guest is not keeping the driver fed — and it destroys
+envelope correlation *by construction*: the envelope is dominated by a 57 Hz chop
+that has nothing to do with the content.
+
+✅ **So the port's alarming hypothesis is NOT supported by this capture.** Nothing
+here says the game fails to play the movie's audio track. What it says is that
+**this capture cannot answer the question either way**, and the earlier
+autocorrelation hint pointed the same way — the file's strongest periodicity is
+at **5.2 s** (r = 0.449), not at `BGM_102`'s 37.487 s loop, and 5.2 s is a beat of
+the dropout schedule rather than anything musical. (Estimator controlled: it
+recovers a synthetic 37.487 s loop as **37.480 s**, and scores non-repeating noise
+at r = 0.019.)
+
+### Why the sink starves — and 🔴 why "it cannot be fixed by configuration" was WRONG
+
+`parec` reads a sink **monitor**, which advances at wall-clock rate and
+substitutes silence whenever nothing is written. **And every sink in this
+container is a null sink**, because there is no audio hardware at all — no
+`/proc/asound/cards`, no `/dev/snd`, no `/etc/asound.conf` — so PulseAudio's
+stock `default.pa:109` `module-always-sink` supplies one, whose stated purpose is
+to "make sure we always have a sink around, **even if it is a null sink**". A
+null sink has no hardware clock: it is driven on a timer, and anything the client
+fails to write in time becomes silence in the monitor.
+
+From that I concluded the route "cannot be fixed by configuration" and that only
+an in-emulator tap would work. **That was wrong, and it was wrong because I
+assumed the holes meant the guest was running below real time without testing the
+alternative** — that the *client buffer* is simply too small. Xenia asks SDL for
+`channel_samples_ = 256`, i.e. **5.33 ms** at 6 channels, and `daemon.conf` here
+is stock with no fragment tuning at all.
+
+`PULSE_LATENCY_MSEC` overrides what SDL's PulseAudio backend requests. Measured,
+same title, same sink, same `parec` invocation:
+
+| client buffer | duration | **silence** | gaps/s | median gap |
+|---|---|---|---|---|
+| xenia default (~5.3 ms) | 347.5 s | 39.3 % | 30.5 | 3.94 ms |
+| **`PULSE_LATENCY_MSEC=200`** (114.7 ms reported) | 88.0 s | **15.6 %** | 3.5 | 37.33 ms |
+| `PULSE_LATENCY_MSEC=500` | 87.9 s | **50.1 %** | **1.3** | 346.67 ms |
+
+**200 ms is 2.5× better than the default. 500 ms is worse than either.** The
+relationship is **not monotonic**: raising the buffer keeps cutting the gap
+*rate* (30.5 → 3.5 → 1.3) while the *total silence* bottoms out at 200 ms and
+then doubles, because an over-large buffer starves in a few enormous holes
+instead of many small ones — a 346 ms median gap at 500 ms against 37 ms at 200.
+
+🔴 **And that is a warning about the metric, not just the setting.** The port's
+`check-capture` bar is **20 gaps/s**, derived from good controls (starved 32.9,
+genuine music bed 3.3, voice track 0.03). The 500 ms file scores **1.3 gaps/s —
+better than a real music bed — while being 50 % silence.** A gap-*rate* test
+alone would pass the worst capture of the three. It needs a **total-silence**
+companion, and this is the same shape as the defect that made a level table
+useless: one number that cannot see the failure mode next door.
+
+⚠️ **Not yet a clean bill of health.** The two runs are not like-for-like: 88 s
+against 347 s, and the short one covers the splash logos, where silence between
+cards is real. What is established is the *direction and scale* — the dropouts
+were substantially a **client-buffer** problem, not proof that the guest runs
+below real time.
+
+✅ **Consequence: the in-emulator tap may not be needed.** The capture route is
+worth retrying at a raised latency before anyone spends a session on a Canary
+rebuild.
+
+❔ **The route that would work is an internal tap**, and it does not exist yet.
+`SDLAudioDriver::SubmitFrame(float* frame)`
+(`/canary/src/xenia/apu/sdl/sdl_audio_driver.cc`) receives exactly `frame_size_`
+bytes — `sizeof(float) × frame_channels_ × channel_samples_` — of the guest's own
+frame, in guest order, with **no wall clock in the loop**. A cvar-gated WAV
+writer there is the same shape as `xma_param_probe`: additive, default-off,
+read-only. It would produce a gap-free recording however slowly the emulator
+runs, because it records what the guest *produced* rather than what a device
+*consumed*.
+
+🔴 **Blocked on the build, not on the change — and this is a container fact
+worth knowing before anyone plans around it.** `build-canary` builds
+`${PROJECT_DIR:-/work}/xenia-canary`, which does not exist here; the source is at
+`/canary`. The warm 235 MB tree at `/sylph-home/re/canary-build` is configured
+with `CMAKE_HOME_DIRECTORY=/work/xenia-canary` — also missing — and its
+`build-Release.ninja` has no per-file rules, so it re-runs CMake first and that
+reconfigure fails on the absent root. **Any Canary change is therefore a full
+reconfigure plus a full compile**, at `SYLPH_JOBS=4` on a box sitting at ~700 MB
+free with a documented history of parallel builds OOM-killing the host.
+
+**Not attempted, deliberately** — that is a whole session's risk for one probe,
+and the rule here is not to improvise around a blocker. Recorded so the next
+session can decide with the cost in front of it rather than discovering it
+halfway through a build.
+
+## 🔴 And a provenance number I got wrong
+
+I told the port take 2 was **253.3 s**. The file is **318.5 s**, and the full
+recording on disk is 349 s. I read `ffprobe` *while the recorder was still
+writing*, quoted the partial length, and copied the file before it finished — so
+the shared artefact is itself a truncation of the run.
+
+The corrected provenance, from the same screen log: movie/other **t = 10 … 251**,
+`title_noplate` at **262**, `title_plate` **277 … 318**, back to movie/other at
+**329** (the documented title idle timeout). ⚠️ So the shared file **includes the
+title screen**, which contradicts what I told them — I had said it sat wholly
+inside the movie window.
+
+**A length in a provenance claim must be read from the finished artefact.**
+Measuring a file that is still being written is the same class of error as
+reading a level table that cannot see the defect.
+
+🔴 **And it is worse than "truncated" — the shared file declares itself EMPTY.**
+`parec` writes the WAV header with zero sizes and only patches them on a clean
+exit, so a copy taken mid-recording has:
+
+| field | shared artefact | the finished local recording |
+|---|---|---|
+| `RIFF` size | **8** | 200 165 472 |
+| `data` size | **0** | 200 165 436 |
+| actual bytes | 183 478 556 | 200 165 480 |
+
+Python's `wave` module **refuses to open it** (`fmt chunk and/or data chunk
+missing`). `ffmpeg` and `ffprobe` recover by scanning, report a plausible
+duration, and that is exactly why the defect went unnoticed — **the lenient
+reader hid it from me and the strict one would have caught it instantly.**
+
+⚠️ **Attribution of the starvation numbers, corrected.** The 39.3 % / 16 680 453
+frames / 10 595 runs above were measured on the **finished local recording**
+(347.5 s), not on the artefact that was shared (318.5 s). The port measured the
+shared copy independently and got **35.6 % / 15 289 876 frames / 10 482 runs**;
+median burst 13.5 ms vs 13.6, gap 3.9 vs 3.9, period 17.4 ms vs ≈17.5. The
+diagnosis is unaffected — both files are starved — but **a number must say which
+artefact it came from**, and these did not.

docs/re/bgm-102-decoded-during-boot.md

@@ -0,0 +1,104 @@
+# ✅ The two unexplained XMA streams are `BGM_102.slb` — and the corpus's `BGM_103` sizes survive a check
+
+**Classification: decoded** for the identification (the bank, plus a disc-wide
+search); **measured** for the fact that it was decoded during a boot.
+
+Closes the ❔ left by the take-2 audio capture, where
+[`audio-capture-channel-map-trap.md`](audio-capture-channel-map-trap.md) recorded
+that `--xma_param_probe` logged **five** distinct streams on one boot when only
+`ADV`'s three were accounted for.
+
+## The identification
+
+The probe gives a `byte_size` and nothing else, so the disc was asked which cue
+owns a stream that long. Both unexplained sizes are whole packet counts —
+1 150 976 = 562 packets, 1 269 760 = 620 — and
+`--example find_stream_by_size` searched every inter-descriptor span of the
+continuous voice stream **and** every `sound.pak` entry large enough:
+
+| | |
+|---|---|
+| hits in the movie-voice stream | **0** |
+| hits in `sound.pak` | one entry carrying **both**: hash `9799c546` |
+
+One entry holding both sizes is the two-stem shape, not a coincidence of two
+separate matches. The hash recovers by candidate enumeration
+(`--example name_from_hash`) to **`BGM_102.slb`**.
+
+```
+BGM_102.slb  2 445 760 B on disc, header 10 240 -> 2 streams
+   stream 0: 1 150 976 B (562 packets)  declared 30 703 B/s  => 37.487 s
+   stream 1: 1 269 760 B (620 packets)  declared 33 872 B/s  => 37.487 s
+```
+
+✅ So the boot's five streams were **`ADV`'s three voice streams plus one music
+bank's two stems**, and nothing is unaccounted for.
+
+## 🟡 What it does NOT establish: which screen it belongs to
+
+The capture window ran from process launch to **t = 253 s**, and its screen log
+reads movie/attract throughout, with the title arriving at t = 262 s — *after*
+the recording ended. So `BGM_102` was decoded somewhere inside a
+launch-to-just-before-title window.
+
+⚠️ **That is not enough to call it the attract music.** The probe fires on *first
+decode* and its log lines carry a thread id, not a timestamp, so nothing here
+says *when* in those 253 s it started — and a title BGM being decoded moments
+before the title appears is exactly as consistent. The numbering makes that a
+live hypothesis rather than a remote one: the corpus already has the **main
+menu** on cue **1103** → `BGM_103`, so **1102** sitting one below it is at least
+suggestive of the title.
+
+**The experiment that would settle it** is cheap and is not done: put a
+wall-clock timestamp on the probe line (or bound the run so it stops before the
+title) and compare against the screen log the capture already produces.
+
+## 🟢 Refutation attempt — HANDOFF's `BGM_103` wave sizes. It SURVIVED.
+
+HANDOFF asserts the menu's music is `BGM_103` partly on *"`BGM_103.slb`'s two
+declared waves (3 876 864 / 3 930 112 B)"*. Read off the disc:
+
+```
+BGM_103.slb  7 841 292 B, header 10 240 -> 2 streams
+   stream 0: 3 876 864 B  declared 44 181 B/s  => 87.750 s
+   stream 1: 3 930 112 B  declared 44 788 B/s  => 87.749 s
+```
+
+**Exact, both.** The claim stands unchanged.
+
+## ✅ And a third route to "two stems of identical duration"
+
+[`bgm-two-stems`](structures/bgm-two-stems.md) established equal duration by
+decoding. The XMA1 `PsuedoBytesPerSec` fix
+([`voice-region-leading-chunk.md`](structures/voice-region-leading-chunk.md))
+gives the same answer from the header alone, on three banks:
+
+| bank | stem 0 | stem 1 |
+|---|---|---|
+| `BGM_102` | 37.487 s | 37.487 s |
+| `BGM_103` | 87.750 s | 87.749 s |
+| `BGM_001` | 173.821 s | 173.821 s |
+
+🔴 **An explanation I gave here was wrong and is withdrawn (2026-08-29).** It
+said `BGM_001`'s declared **173.821 s** disagreed with a decoded **167.663 s**,
+and that "declared covers the encoded stream including its trailing silence; the
+decoded figure is where the audio stops". **There is no disagreement to explain.**
+A full decode of `BGM_001` yields **173.809 s of PCM** — the 167.663 s is where
+the music *fades out*, measured from the audio, and the stream continues silent
+to its declared end **inside** that decode. Declared and decoded agree.
+
+✅ **The declared-rate method is now cross-checked on three banks against
+independent decodes**, and it is better than the first version of this page
+claimed:
+
+| bank | declared | decoded | agreement |
+|---|---|---|---|
+| `BGM_103` | 87.750 / 87.749 s | **87.744 s** | 5–6 ms |
+| `BGM_102` | 37.487 s | **37.482 s** | 5 ms |
+| `BGM_001` | 173.821 s | **173.809 s** | 12 ms |
+
+⚠️ The conclusion that survives unchanged is the useful one: **trust it for
+lengths, not for musical boundaries.** A bank's declared length includes whatever
+silence the encode carries, so it is not a loop point — that has to be measured
+from the audio, and for `BGM_001` that is 167.663 s, 6.1 s before the stream
+ends.

docs/re/boot-order-and-splash-dwell.md

@@ -0,0 +1,216 @@
+# The boot's first ten seconds: publisher, then developer — and the movie has a logo card too
+
+**Status:** ✅ `CONFIRMED`. The **order** is measured in three independent cold
+boots and confirmed **by eye**, not only by a correlation. The **dwells** are
+**decoded** — they are on the disc, and the running game reproduces them to
+within the emulator's own frame pacing.
+
+Raised by the port agent against `data/boot-timeline-2026-08-29.tsv`, whose
+`label` column runs `splash_dev` *before* `splash_pub` — the opposite of what
+`authored/flow.json` carries. If that ordering were real it would be a boot-order
+bug in the port. **It is not real, and this page says why.**
+
+## The order: publisher first
+
+![the two splashes and the movie's logo card](captures/boot-order/splash-order-two-runs.png)
+
+*Brightened ×6 — these frames have a surface mean of ≈5/255. Top-left and
+top-right are the two splashes; the bottom row is what comes next and is NOT a
+splash.*
+
+| run | `SQUARE ENIX` (publisher) | `GAME ARTS`/`SETA`/`studio anima` (developer) |
+|---|---|---|
+| 1 | 3.046 → 7.343 s | 7.683 → 11.191 s |
+| 2 | 1.180 → 5.784 s | 6.051 → 9.554 s |
+| 3 | 1.192 → 5.562 s | 5.929 → 9.295 s |
+
+Three cold boots, `t = 0` at process launch, a ~0.2–0.3 s black hold between
+them. **Publisher first, every time**, and the top row of the contact sheet is
+what the two segments actually show. `docs/game/navigation.md` §1 and
+[`ui-title-build-map.md`](ui-title-build-map.md) stand.
+
+## Why the committed TSV says otherwise — the probe attached late
+
+`data/boot-timeline-2026-08-29.tsv` opens at `t = 0.692` with twelve
+**byte-identical** rows: mean `5.642`, `splash_dev` `+0.8707`, `splash_pub`
+`+0.0294`, to four decimals. Twelve identical samples over 1.27 s are one
+observation of a held screen, not twelve.
+
+Those exact numbers appear in my run 1 at **8.42 – 10.94 s** — same mean, same
+two correlations, same four decimals. So that capture's `t = 0` is roughly
+**7.7 s into the guest's boot**: the publisher splash had already been and gone
+before the stream opened, and the developer splash was simply the first thing the
+probe ever saw.
+
+**The label column is right about what each frame is. It is wrong about what came
+before the file starts.** Nothing in the TSV is retracted; its *reach* is.
+
+## The trap that makes this worse: `ADV.wmv` opens with a SQUARE ENIX card
+
+After the developer splash there is a black hold and then a screen that scores
+**0.59 – 0.75** against `live-splash-publisher.png` — above the classifier's
+threshold, so it is labelled `splash_pub` a second time. In all three runs:
+
+| run | second "splash_pub" |
+|---|---|
+| 1 | 17.793 → 20.301 s |
+| 2 | 16.930 → 20.664 s |
+| 3 | 14.669 → 17.308 s |
+
+The bottom row of the contact sheet is that screen. It is a **blurred, bloomed
+SQUARE ENIX wordmark, lower in the frame** — the intro movie's own opening title
+card, i.e. `ADV.wmv` ([`movie-binding.md`](movie-binding.md)) already playing.
+The real splash's wordmark is sharp and centred; the movie's is soft and sits
+below centre.
+
+⚠️ **So `splash_pub` is not a safe label once the movie has started.** A boot
+classifier keyed on `live-splash-publisher.png` will fire twice per boot. The
+discriminators that do work: the real splash holds *perfectly still* (identical
+frame statistics to four decimals for seconds at a time) and scores **0.93–0.94**;
+the movie card drifts continuously and never exceeds **0.76**.
+
+## The dwells are on the disc — do not author them
+
+Both splash bundles declare their whole life. Read with the corrected keyframe
+record layout ([`ui-keyframe-record-layout.md`](ui-keyframe-record-layout.md))
+and Q1's `1 unit = 1/60 s`:
+
+| | declared | visible span | measured (run 1 / 2 / 3) |
+|---|---|---|---|
+| publisher, `palogo_sqex.t32` | α `0@15 → 255@30 → 255@235 → 232@239 → 32@251 → 0@255` | `15 → 255` = 240 u = **4.000 s** | 4.297 / 4.604 / 4.370 s |
+| developer, `palogo_gamearts.t32` (`seta`, `anima` identical) | α `0@15 → 255@30 → 255@190 → 232@194 → 32@206 → 0@210` | `15 → 210` = 195 u = **3.250 s** | 3.508 / 3.503 / 3.366 s |
+
+Measured ÷ declared, over all six spans: **1.074, 1.151, 1.093, 1.079, 1.078,
+1.036** — mean **1.085**. A 30 Hz timeline stretched by 8.5 % is the game
+presenting at **27.6 fps**, which is the rate this corpus has measured
+independently three times (27.6 on the boot splash, 28.3 and 28.8 on the idle
+title — [`ui-keyframe-time-unit.md`](ui-keyframe-time-unit.md)).
+
+✅ **Classified decoded.** The port reads **240 units** for the publisher and
+**195 units** for the developer and authors nothing.
+
+## 🔴 WITHDRAWN — "the game runs them ~8.5 % long". I measured one element's span and called it the screen's.
+
+**Retracted the same day.** `sylpheed-port` said the port plays the **full group**
+— 255 and 210 units — not my 240/195, and they are right for a reason sharper than
+either of us first had. The `_eff` elements ramp **α 0 → 255 over t=0..15**, while
+the main logo is still fully transparent there:
+
+```
+palogo_sqex.t32      0:a=0   15:a=0    30:a=255  235:a=255 239:a=232 251:a=32 255:a=0
+palogo_sqex_eff.t32  0:a=0   15:a=255  30:a=212   45:a=0
+```
+
+So **the screen is visible from within t=0..15**, and its visible span is 0→255
+and 0→210 — the full group. My "240 units visible" was **one element's** visible
+span, computed while another element of the same build was already on screen.
+
+Recomputed against the screen:
+
+| | ratios | |
+|---|---|---|
+| publisher (255 u = 4.250 s) | 1.011, 1.083, 1.028 | |
+| developer (210 u = 3.500 s) | 1.002, 1.001, **0.962** | one **below** unity |
+| **mean** | **1.0145** | against 1.085 before |
+
+A 1.5 % mean with a measurement below unity is not a clock running at 54 u/s.
+**The systematic is gone and Q1 stands unqualified.**
+
+⚠️ **And the consequence I drew was wrong too.** "A port playing 240 units at 60
+shows the publisher splash 0.42 s less" — it plays 255, so the gap is 0.174 s, and
+on the developer splash the port runs *longer* than my mean. There is no direction
+to correct in, and nothing here supports moving `keyframe_units_per_second`.
+
+🟡 **What survives, weakly:** against the full group the publisher still runs long
+in all three boots (1.011, 1.083, 1.028) while the developer sits at unity. Three
+boots per screen is thin and it is not a systematic.
+
+### ✅ And the splash builds carry their own OPAQUE BLACK backdrop — verified
+
+`sylpheed-port` found the fifth family member on their own side while confirming
+the above: their "visible" test counted **any element with alpha > 0**, which
+includes `palogo_eff0.prm`. Checked against the disc
+(`tools/re-capture/fade_quads.py e10 e11`):
+
+```
+entry 10   [0] palogo_eff0.prm  1 kf   t=0  fade=0xff000000 (alpha 255)  scale=100x100  pos=(0,0)
+entry 11   [0] palogo_eff0.prm  1 kf   t=0  fade=0xff000000 (alpha 255)  scale=100x100  pos=(0,0)
+```
+
+Alpha 255 over RGB `000000`: **full-screen opaque black, drawn from t=0 and
+showing nothing.** So "any element drawn" reports these screens visible from t=0
+while the frame is black — **"visible" read as "drawn"**, the fifth member.
+
+📌 **Worth having on its own:** this verifies, from the disc, the premise behind
+`screen render --black` — *"what the game composites over on a screen carrying its
+own background, and so what a framebuffer capture must be compared against"*. On
+the splash builds that background is **declared**, not assumed.
+
+📌 **This is the fourth instance of one family** — pivot anchor read as drawn
+extent, centre track as bounding box, cycle length as motion duration, and now
+**one element's visible span read as the screen's**. Every one is a number used as
+though it described the thing beside it.
+
+`sylpheed-port` reported their `verify-dwell` at 4.28 s / 3.58 s and called it
+agreement with these boots. Checking the arithmetic rather than the impression:
+
+| | declared | at Q1's 60 u/s | measured (3 cold boots) | ratio |
+|---|---|---|---|---|
+| publisher | 240 u | **4.000 s** | 4.297 / 4.604 / 4.370, mean **4.424** | **1.106** |
+| developer | 195 u | **3.250 s** | 3.508 / 3.503 / 3.366, mean **3.459** | **1.064** |
+
+**All six ratios exceed 1** — 1.074, 1.151, 1.093, 1.079, 1.078, 1.036 — mean
+**1.085**. The implied unit rate is **54.3** and **56.4 units/s**, and the port's
+own two numbers imply **56.1** and **54.5**. Four estimates, none at 60.
+
+⚠️ **The obvious explanation does not work.** A detector triggering early and
+late would lengthen the interval — but the declared span *is* `15 → 255`, and
+outside it the alpha is **0**, so there is nothing on screen to trigger on. An
+8.5 % overshoot is 20 units, ten rendered frames, which a threshold cannot
+manufacture from a blank screen.
+
+🟡 **So this is a real systematic and its cause is not established.** Either the
+title's timeline advances at ~55 units/s rather than Q1's 60, or the boot inserts
+something between the declared span and what a capture sees. ⚠️ It is **not** the
+same discrepancy as the sweep leaf's (which runs ~50 % slow, not 8.5 %), and I am
+recording it as an open qualification on Q1 rather than a correction to it — three
+boots per screen is thin, and Q1 was measured on a different quantity.
+
+📌 **For the port:** these dwells are still *decoded* and still should not be
+authored — but a port that plays 240 units at exactly 60 u/s will show the
+publisher splash for **0.42 s less** than the game does.
+
+⚠️ **Reach of the ±:** a correlation crossing a threshold during a fade is not a
+sharp edge, so an individual span is good to roughly ±0.2 s. The developer's
+first two runs agree to **5 ms**, which is the instrument at its best; run 2's
+publisher span (4.604 s) is the outlier and its onset at 1.180 s is early enough
+to be a stream still filling. The *order* does not depend on any of this.
+
+## Method
+
+`tools/re-capture/boot_timeline_probe.py`, whose `--control` was run first and
+passed **11/11** on the content classifier and **4/4** on the plate detector,
+including `live-splash-publisher.png → splash_pub` and
+`live-splash-developer.png → splash_dev` with each rejecting the other at
+**0.035**. So a 0.87 reading against the developer reference is a real match and
+not an artefact of two dark images: the two references are both dark and they do
+not correlate with each other.
+
+Both splash references are themselves committed captures whose identity is
+independent of any correlation — `live-splash-publisher.png` was matched to
+`GP_TITLE` entry 10, whose elements are literally named `palogo_sqex`, and
+`live-splash-developer.png` to entry 11, `palogo_gamearts` / `palogo_seta` /
+`palogo_anima`.
+
+Boots were cold: `/dev/shm/xenia_*` cleared, no pad input at any point.
+
+## What this does not say
+
+* Nothing here is about the **movie's** length or the attract loop; the runs were
+  cut at 26–45 s. That half is in `data/boot-timeline-2026-08-29.tsv`, whose
+  *intervals* are unaffected by the attach offset even though its absolute `t` is.
+* The 0.2–0.3 s black hold between the two splashes was not separately timed
+  against the declared `palogo_eff0.prm` backdrop; it is consistent with the
+  0.14–0.30 s black hold already measured between screens
+  ([`title-plate-delay-measured.md`](title-plate-delay-measured.md)) but that is
+  a consistency note, not a measurement of this particular gap.

docs/re/boot-settle-times-measured.md

@@ -0,0 +1,168 @@
+# ✅ `settle_time()` — when each boot screen actually arrives, measured
+
+**Classification: measured.** None of this is on the disc as a settle time. The
+disc declares *keyframes*; when a screen visibly arrives is a property of the
+running game, and the port authors these numbers from this page.
+
+Answers the port's standing ask: its boot sequencer paces every screen off
+`rest.t`, which is the **last hold keyframe** and not when a screen arrives — it
+holds the title for 4.350 s where the build-in is over at about 2 s.
+
+**Run:** one cold boot, 2026-08-29. Container had **no Xenia storage root at
+all**, so this is a fresh profile (`--create_profile_if_none`) with no shader
+cache — the slowest case, deliberately.
+Frame log committed at [`data/boot-settle-run1.tsv`](data/boot-settle-run1.tsv);
+analysis `tools/re-capture/settle_analyse.py`.
+
+## The instrument was controlled first, and then caught being wrong
+
+`title_timing_probe.py --control` passed **9/9** on the content classifier —
+including the movie-frame and `difficulty-screen` negatives — and **4/4** on the
+plate detector, before the run. The run itself sampled **2 107 frames in 263.7 s
+= 7.99 fps against a requested 8**, with an independent one-shot grab every 20 s
+agreeing with the stream to under 1 grey level. So this is not the backlog
+failure mode that cost this corpus four withdrawn durations.
+
+🔴 **And the probe's own `title_static` mark is still biased early — do not use
+it for a duration.** It fires when the classifier first labels a frame
+`title_*` *and* motion is low, which happens **during the crossfade out of the
+attract movie, before the wordmark has drawn**. In this run it fired at
+`t=242.655` while the green-glyph count was still **0**; the title art does not
+reach its steady state until `243.595`. Any `title_static → plate` figure from
+this probe is therefore inflated by about a second.
+
+## The landmarks, taken from content rather than from the probe's marks
+
+The robust landmark is the **glyph plateau**: the title art alone scores a steady
+`glyph = 154` (the corpus's `live-title-build4-no-plate.png` scores 159), and the
+plate takes it past 700.
+
+| landmark | t (s) | how |
+|---|---|---|
+| attract movie ends, first title ink | 243.362 | glyph leaves 0 |
+| **title art fully drawn** | **243.595** | glyph reaches its steady 154 |
+| **`PRESS Ⓐ` plate on** | **245.842** | glyph crosses 400 → 771 |
+| Ⓐ pressed | 250.983 | |
+| ⚠️ guest load stall | 251.601 – 253.135 | 13 byte-identical frames |
+| **main menu arrives** | **254.707** | classifier |
+| **main menu settled** | **255.238** | motion below a run-calibrated floor |
+| Ⓑ pressed | 262.864 | |
+| **title back** | **263.346** | |
+
+### What the port should author
+
+| | measured | ⚠️ |
+|---|---|---|
+| title build-in (first ink → fully drawn) | **0.23 s** | from first ink; **1.63 s** from the first frame the classifier calls `title_*`, which is where the crossfade starts |
+| **title settled → plate on** | **2.247 s** | matches the disc's declared **120 units** |
+| plate pulse period | **≈2.37 s** | trough-to-trough, 248.098 → 250.467 |
+| **main menu build-in** | **0.531 s** | |
+| **Ⓑ → title** | **0.482 s** | |
+| Ⓐ → menu | 3.763 s | 🔴 **do not author** — contains a 1.53 s emulator load stall, below |
+
+🔴 **`rest.t` is confirmed to be the wrong landmark.** The title's `rest.t` is 251
+units = 4.183 s; its art is finished at ~2 s and the plate is on at 2.25 s. A
+sequencer pacing off `rest.t` holds the title roughly twice as long as the game
+does.
+
+## 🟢 A refutation attempt that FAILED — the corpus's 2.13 s plate delay survives
+
+The probe's own marks gave a plate delay of **3.203 s** (`title_static` 242.655 →
+`plate` 245.858), against the corpus's two committed runs at **2.138 / 2.132 s**
+and a declared 120 units ≈ 2.0 s. A 50 % disagreement, from a cold-cache boot, is
+exactly where you would expect the corpus to be wrong.
+
+**It is not. The instrument was** — but 🔴 **one of the two arguments I gave for
+that is withdrawn (2026-08-29).**
+
+* 🔴 **WITHDRAWN — "the presentation rate is not depressed in this run".** This
+  said the plate **pulse period** acts as an internal clock and measured
+  **2.369 s** against the corpus's ≈2.3 s. Re-examined, that estimate rests on
+  **one interval between two distinct troughs**, at a 125 ms sample interval, so
+  its uncertainty is **±0.177 s (±6.7 %)** — and trough-picking on a noisy
+  plateau is fragile enough that re-running it gave **2.628 s** rather than
+  2.369, because an adjacent local minimum had been taken as a separate trough.
+  Against the corpus's ≈2.24 s that is **+17.3 %**, about 2σ. So the pulse
+  period does **not** show the run running at normal speed; it is simply too
+  weak to show anything, and **it cannot resolve a real-time factor below ~7 %
+  at all**. It should never have carried the argument.
+* ✅ **The conclusion survives on the other leg, which is the sound one.**
+  Re-measured from content rather than from the probe's mark, steady title art
+  (`243.595`) → plate on (`245.842`) is **2.247 s**, and that agrees with the
+  corpus's three independent readings — 2.13 / 2.132 / 2.138 — to within the
+  ±0.125 s sample interval. Both of its landmarks are sharp content transitions
+  (a glyph plateau, and a glyph crossing), unlike a trough on a noisy plateau.
+  A 17 % slowdown would have put this at 2.49 s; it did not.
+
+⚠️ **What that leaves open, and the port authors from these numbers:** this run
+carries an unmeasured real-time factor somewhere under ~7 %, because nothing in
+it was precise enough to pin one. The plate delay is anchored by agreement with
+three prior runs; **the menu build-in (0.531 s) and Ⓑ→title (0.482 s) are not
+anchored by anything**, and a few per cent of emulator slowdown sits inside them
+undetected. They were already flagged as one-run figures; this is the second
+reason to treat them as provisional.
+
+✅ So the 2.13 s stands, the 120-unit reading stands, and the 3.203 s is
+`title_static` firing during a crossfade. Recorded because a failed refutation is
+worth as much as a successful one, and because the next person to read the
+probe's `title_static` will otherwise repeat it.
+
+## 🟢 And the load stall reproduces — third independent run, cold cache
+
+[`title-plate-delay-measured.md`](title-plate-delay-measured.md) records a frozen
+frame on the Ⓐ path in two runs: **14 frames (1.53 s)** and **12 frames
+(1.39 s)**, both at surface mean **26.626**, and concludes any Ⓐ→menu figure from
+this harness is an emulator load time rather than a game constant.
+
+This run is a third: **13 frames, 251.601 – 253.135 = 1.53 s, surface mean
+26.631**, labelled `title_plate` throughout.
+
+✅ The claim survives, and is now stronger in a way the earlier runs could not
+show: this boot had **no shader cache at all**, so the stall is not a warm-cache
+artefact. ⚠️ One honest qualification — the earlier note says its two runs agreed
+"to six decimals"; mine agrees only to three (26.631 vs 26.626), so the mean is
+reproducible but not byte-identical across all three.
+
+## Reach
+
+* **One run.** The durations above are one cold boot. The two that are
+  cross-checked against independent evidence — the plate delay, against the
+  corpus's two runs and the disc's 120 units; the load stall, against two prior
+  runs — are the ones to lean on. The menu build-in (0.531 s) and Ⓑ→title
+  (0.482 s) rest on **this run alone**.
+  🟢 **The re-take was offered and declined, 2026-08-29**: the port authors
+  neither number, is already within ~0.1 s of both from the disc's own
+  keyframes, and asked that no emulator time be spent on its account. Authoring a
+  one-run measurement over a decoded value would gain nothing measurable. Left
+  provisional deliberately rather than for want of a run.
+* **Sampling is 8 fps**, so every landmark carries ±0.125 s, and the guest's own
+  presentation rate cannot be measured from it — 8 fps is far below the ~28 fps
+  the game presents at, so every sample is a distinct guest frame and repeats
+  only appear when the guest itself stalls.
+* The splash dwells are **not** re-measured here; they are already in
+  [`boot-order-and-splash-dwell.md`](boot-order-and-splash-dwell.md).
+
+---
+
+## 🟢 The consumer's own red flag was larger than this measurement supports
+
+Recorded because it is the outcome of the measurement and it went the other way
+from what the port expected.
+
+The port's standing 🔴 read: *"`rest.t` is the wrong landmark, therefore
+everything the sequencer paces off it is late."* **The premise is confirmed here
+and the consequence is not.** Measuring the port the same way this page measures
+the game — visible span, per-frame greyscale mean — its publisher wordmark runs
+4.25 s against three cold boots at 4.297 / 4.604 / 4.370, and its developer logos
+3.50 s against 3.508 / 3.503 / 3.366.
+
+⚠️ **The discrepancy it was about to chase was the plate-delay trap in a second
+place.** It had been comparing *arrival-to-arrival* transition timestamps against
+*visible spans*; those differ by the exit ramp plus the black hold, about 0.6 s,
+which was the whole of it — the same shape as timing the title from where it
+stops animating rather than from where it first appears.
+
+✅ So the generalisation this page supports is narrower than "the sequencer is
+late": **`rest.t` is the wrong landmark for the title specifically**, where it
+overstates by 4.183 s against ~2 s. Whether any *other* screen is mis-paced does
+not follow from it and was not measured here.

docs/re/capture-harness-status.md

@@ -1,3 +1,62 @@
+# ✅ WITHDRAWN 2026-08-29 (later the same day) — the interactive title IS reachable here, twice, with no pad input
+
+**This banner supersedes everything below it about the title being unreachable,
+and it supersedes the 🔴 "Emulator-side questions are blocked" section of
+[MISSION](../port/MISSION.md).** Everything below is kept because the harness
+defects it diagnoses were real and the fixes are in use; what it concluded about
+the *game* is now refuted by measurement.
+
+**Two consecutive boots reached the interactive title, with the `PRESS Ⓐ BUTTON`
+plate, without a single pad press before it:**
+
+| | run 1 | run 2 |
+|---|---|---|
+| plate on screen at | **205.4 s** into the probe | **218.4 s** |
+| pad input before that | **none** | **none** |
+| Ⓐ then reached the main menu | ✅ | ✅ |
+| Ⓑ then returned to the title | ✅ | ✅ |
+
+Full per-frame traces, 8 fps, 1783 and 1886 frames:
+[`data/plate-timing-run1.tsv`](data/plate-timing-run1.tsv) ·
+[`data/plate-timing-run2.tsv`](data/plate-timing-run2.tsv). The measurement they
+were taken for is [`title-plate-delay-measured.md`](title-plate-delay-measured.md).
+
+So the standing negative — "three runs, two locales, two launch paths, ~35
+minutes of emulator time, no interactive title" — does not hold in this
+container today. **The attract loop is simply passed through in ~3.5 minutes and
+the title follows.**
+
+## ❔ What changed is NOT established, and I am not going to guess it
+
+What is different about this container, stated as facts rather than as a cause:
+
+* it came up with **no Xenia storage root at all** — no
+  `~/.local/share/Xenia`, so no profile, no `xconfig.settings`, and no shader
+  cache. The earlier runs signed in a profile that already existed.
+* run 1 therefore had to create one, with canary's own
+  `--create_profile_if_none=Decoder`. Run 2 signed in the profile run 1 made
+  (`B13EBABEBABEBABE`).
+* the launch was otherwise `boot_menu.sh`'s, minus `skip_intro.sh` — this
+  measurement had to leave the title untouched, so nothing tapped Ⓐ at all.
+
+⚠️ **A cold profile is a correlation across two runs, not a cause.** It is
+written down so the next session can test it directly (delete the storage root,
+boot, compare) instead of re-deriving that the title is reachable.
+
+## 🔵 What this unblocks
+
+* the **Japanese-locale capture** that MISSION parks as "🟡 needs one more run":
+  the mechanism (`set_console_language.py ja`, `user.language` at file offset
+  `0x912`) is in place, and the reason it was parked — *the title never
+  appears* — is gone. ⚠️ Note the storage root is new, so `xconfig.settings` has
+  been recreated and the byte offset should be re-located by its three landmarks
+  rather than assumed.
+* the two items MISSION lists as emulator-blocked: the gamma control behind
+  [tone curve](structures/ui-render-tone-curve.md), and separating `8AX` from
+  `ptbase` in [8AX](structures/ui-8ax-fullres-background.md).
+
+---
+
 # 🔴 Why the boot harness stopped reaching the title — `screenshot` costs 10.8 s
 
 **Status:** ✅ **diagnosed, with a control.** Four consecutive runs on
@@ -362,3 +421,173 @@ The gamma run's flags plainly took effect — that run is where
 `VdGetCurrentDisplayGamma` was captured — while its dump showed the file's
 values. So the dump reflects the config file and cannot confirm or refute a
 command-line override.
+
+---
+
+# ✅ 2026-08-29 (later) — the disc is back, and the section below is withdrawn as CURRENT status
+
+Kept for its history, not as a live claim. The container was replaced: PID 1
+here started at **11:07:38 UTC**, 25 minutes after commit `b9aca6a` wrote the
+section below at 10:42, and the replacement has the disc mounted.
+
+| check | result |
+|---|---|
+| `/proc/mounts` | `/dev/sda2 /disc ext4 ro,relatime` — a real bind mount |
+| device | `/disc` is device **2050**; `/` is device **92** |
+| size | 6.2 GB, 74 entries under `dat/`, `default.xex` = 3 497 984 B |
+| ISO | `/iso/game.iso`, 7 835 492 352 B |
+| end to end | `sylpheed-cli screen list /disc/dat/GP_TITLE.pak` → 12 builds, element/sprite counts matching the committed build map |
+
+⚠️ **Two instruments would have said "no disc" either way, and both are still
+in place.** This is the reusable lesson, and it is worth more than the
+resolved incident:
+
+* **`find / -xdev` cannot see `/disc`.** `-xdev` refuses to cross a filesystem
+  boundary; `/disc` is on a different device from `/`. The withdrawn section's
+  headline measurement — "no ISO, no `default.xex`, no `GP_TITLE.pak` anywhere"
+  — is what that command returns **whether or not the disc is mounted**. It had
+  no reach over the question it was used to answer.
+* **`sylph-doctor` never checks `$SYLPHEED_DISC`.** Its two disc lines are
+  `find /work -maxdepth 2 -iname '*.iso'` and `[ -d /work/sylph_extract/dat ]`
+  (lines 79–82). With the disc at `/disc` it reports "no ISO under /work" and
+  "no extracted disc — Reborn disc tests will SKIP" — as it does right now,
+  against a working disc. "`sylph-doctor` agrees" was two instruments sharing
+  one blind spot, not corroboration.
+
+**To check for the disc, ask the variable that names it**: `ls "$SYLPHEED_DISC/dat"`,
+or `sylpheed-cli screen list "$SYLPHEED_DISC/dat/GP_TITLE.pak"`, which fails
+loudly and cheaply.
+
+# 🔴 2026-08-29 — the disc is not in the decoder container at all *(WITHDRAWN — see the section immediately above)*
+
+**Status:** ✅ **diagnosed, root-caused in the launcher.** This supersedes every
+"the emulator did not reach the title" entry above as the *current* reason the
+oracle is unavailable: there is no game to run.
+
+## The measurement
+
+| looked for | result |
+|---|---|
+| `find / -xdev -iname '*.iso'` | **0** |
+| `find / -xdev -iname 'default.xex'` | **0** |
+| `find / -xdev -iname 'GP_TITLE.pak'` | **0** |
+| `$SYLPHEED_DISC` | **empty** |
+| `/work/sylph_extract` | does not exist |
+| `/exchange/files` | **empty** |
+
+`sylph-doctor` agrees and says so in its own words:
+
+```
+── project ──
+  ✖ /work/xenia-canary not mounted
+  ✖ /work/Syplheed-Reborn not mounted
+  ! no ISO under /work — run-canary needs SYLPH_ISO
+  ! no extracted disc — Reborn disc tests will SKIP
+```
+
+Everything else is healthy: `xenia_canary` is built and present, display `:98`
+is up, `screenshot` works, Vulkan (llvmpipe) enumerates, cargo and the python
+stack are fine. **The emulator has no disc to boot.**
+
+## The cause — the volume migration, and a mount nobody replaced
+
+Before [`06676d3`](#) the launcher bind-mounted the human's working tree:
+
+```
+-v "$PROJECT:$PROJECT"
+-v "$PROJECT:/work"
+```
+
+The ISO and `sylph_extract/` live in that tree, so the disc arrived **incidentally
+with the repository mount**, and `run-canary`'s `find "$PROJECT_DIR" -maxdepth 2
+-iname '*.iso'` found it.
+
+`06676d3` replaced that with the agent's own clone in a named volume —
+
+```
+-v "sylpheed-decoder-repo:/work"
+```
+
+— which is the right fix for the collision class it was written for, and it
+removed the disc along with the working tree. **Nothing was added to replace
+it.** The launcher still forwards
+
+```
+[ -n "${SYLPH_ISO:-}" ] && _out+=(-e "SYLPH_ISO=$SYLPH_ISO")
+```
+
+but that is an **environment variable with no bind mount behind it** — it names a
+host path that does not exist inside the container, so it cannot help.
+
+**The port container does not have this bug.** `docker/port/sylph-port` mounts
+the disc explicitly:
+
+```
+_out+=(-v "$DISC:/disc:ro" -e "SYLPHEED_DISC=/disc")
+```
+
+So the one container that *owns* the disc and the oracle is the one container
+without them.
+
+## Reach of the negative
+
+Whole-filesystem, single pass, `-xdev` per mount, three independent names (the
+ISO, the executable, a pak the corpus names constantly). The exchange volume is
+empty, so the disc is not arriving by `share` either. This is not "I looked in
+the usual place".
+
+## What it blocks — everything disc-side and everything dynamic
+
+* the **oracle** — no boot, no capture, no `run-canary`;
+* every `sylpheed-cli` invocation that names a pak — `screen list`, `screen info`,
+  `screen render`, `pak textures`;
+* `build-reborn test` — the disc-gated tests self-skip, and per MISSION a green
+  run then means almost nothing. (`build-reborn` is *also* pointing at
+  `/work/Syplheed-Reborn`, a path the monorepo no longer has.)
+* **static RE of the executable** — the XEX is on the disc, so the whole
+  PPC-disassembly route is shut too, not just the dynamic one.
+
+## What it does not block
+
+The committed corpus. `docs/re/captures/` is 99 MB of oracle frames and
+`docs/re/data/` 2.5 MB of extracted tables, both in git — enough to re-measure
+against captures, which is what this iteration did instead.
+
+## 🔵 For the human — the one-line fix
+
+Add a disc mount to `docker/decoder/sylph-decoder`, the way `sylph-port` already
+has one:
+
+```bash
+[ -d "$DISC" ] && _out+=(-v "$DISC:/disc:ro" -e "SYLPHEED_DISC=/disc")
+[ -f "$SYLPH_ISO" ] && _out+=(-v "$SYLPH_ISO:/disc.iso:ro" -e "SYLPH_ISO=/disc.iso")
+```
+
+Recorded rather than worked around, per *do not improvise around a blocker* —
+and **not attempted**, because the launcher runs on the host and this container
+cannot restart itself.
+
+⚠️ `sylph-doctor` reports the missing ISO as `!` (a warning) rather than `✖`. For
+the decoder that is not a warning: it is the difference between having an oracle
+and not having one.
+
+### A second, smaller consequence of the same migration — no git identity
+
+`git commit` in a fresh decoder container fails with *"Author identity
+unknown"*: nothing in the image, the entrypoint or `sylph-decoder` sets
+`user.name` / `user.email`, and the old bind mount used to bring the human's
+`.git/config` along with the tree.
+
+Set locally, per iteration if the volume is recreated:
+
+```bash
+git config --local user.name  "sylph-decoder"
+git config --local user.email "fabian@diekaulbachs.de"
+```
+
+⚠️ `push-work`'s header warns at length against `git config --local`, because
+the credential helper it wrote there leaked a container-only path onto the host.
+**That warning no longer applies to identity**: `/work` is a private named
+volume now, not a shared bind mount, so nothing written to its `.git/config`
+can reach a host checkout. The credential helper is still applied per-invocation
+with `-c`, and should stay that way.

docs/re/data/a-press-fault-log-extract.txt

@@ -0,0 +1,138 @@
+# Extract from the Ⓐ-press fault run's xenia.log (2026-08-29)
+#
+# Source: /sylph-home/re/canary-build/bin/Linux/Release/xenia.log, 326 921 343 bytes,
+# mtime 2026-08-29 22:15. 32 356 '==== CRASH DUMP ====' blocks. This file is the
+# part that carries the diagnosis; the whole log is not committed (326 MB).
+#
+# ---- 1. the three real Ⓐ keystrokes, then the swallow begins (log lines 1180-1262)
+
+i> 0100000C [UI-CAP] writing xenia_re_ui_draws_01.log (from frame 0)
+!> 0001278F MEM-WATCH rss=590MB (peak 590MB) vsz=19185MB malloc_inuse=313MB mmap=90MB cache_deque=40 cache_list=40
+!> 0001278F MEM-WATCH rss=590MB (peak 590MB) vsz=19189MB malloc_inuse=313MB mmap=90MB cache_deque=40 cache_list=40
+i> F8000008 [file-pad] #3 buttons=1000 lt=0 rt=0 lx=0 ly=0 rx=0 ry=0
+i> F8000008 [file-pad] keystroke vk=5800 down
+i> F8000008 [RE-INPUT] XamInputGetKeystrokeEx -> user=0 vk=5800 flags=0001 (call flags 00000003)
+i> F8000008 [file-pad] #4 buttons=0000 lt=0 rt=0 lx=0 ly=0 rx=0 ry=0
+i> F8000008 [file-pad] keystroke vk=5800 up
+i> F8000008 [RE-INPUT] XamInputGetKeystrokeEx -> user=0 vk=5800 flags=0002 (call flags 00000003)
+!> 0001278F MEM-WATCH rss=594MB (peak 594MB) vsz=19189MB malloc_inuse=314MB mmap=90MB cache_deque=40 cache_list=40
+!> 0001278F MEM-WATCH rss=595MB (peak 595MB) vsz=19189MB malloc_inuse=313MB mmap=90MB cache_deque=40 cache_list=40
+i> F8000008 XThreadF80000B8 (1A) Stack: 70880000-70900000
+K> F80000B8 XThread::Execute thid 26 (handle=F80000B8, 'XThread76FFE6C0 (F80000B8)', native=76FFE6C0)
+F> F80000B8 HostPathDevice::ResolvePath(\aab216c3\5\c10eae6)
+F> F80000B8 HostPathDevice::ResolvePath(\aab216c3\5)
+F> F8000084 DiscImageDevice::ResolvePath(\dat)
+F> F8000008 DiscImageDevice::ResolvePath(\dat\movie)
+F> F8000008 DiscImageDevice::ResolvePath(\dat\movie)
+i> F8000008 XThreadF8000154 (1B) Stack: 70880000-70890000
+i> F8000008 XThreadF8000158 (1C) Stack: 708B0000-708C0000
+i> F8000008 XThreadF800015C (1D) Stack: 708E0000-708F0000
+i> F8000008 XThreadF8000160 (1E) Stack: 70910000-70920000
+K> F8000158 XThread::Execute thid 28 (handle=F8000158, 'XThread6FFFF6C0 (F8000158)', native=6FFFF6C0)
+K> F8000154 XThread::Execute thid 27 (handle=F8000154, 'XThread75FFD6C0 (F8000154)', native=75FFD6C0)
+K> F800015C XThread::Execute thid 29 (handle=F800015C, 'XThread6EFFE6C0 (F800015C)', native=6EFFE6C0)
+!> 0001278F MEM-WATCH rss=660MB (peak 660MB) vsz=19473MB malloc_inuse=324MB mmap=90MB cache_deque=40 cache_list=40
+!> 0001278F MEM-WATCH rss=661MB (peak 661MB) vsz=19473MB malloc_inuse=324MB mmap=90MB cache_deque=40 cache_list=40
+!> 0001278F MEM-WATCH rss=661MB (peak 661MB) vsz=19473MB malloc_inuse=324MB mmap=90MB cache_deque=40 cache_list=40
+i> F8000008 [file-pad] #5 buttons=1000 lt=0 rt=0 lx=0 ly=0 rx=0 ry=0
+i> F8000008 [file-pad] keystroke vk=5800 down
+i> F8000008 [RE-INPUT] XamInputGetKeystrokeEx -> user=0 vk=5800 flags=0001 (call flags 00000003)
+i> F8000008 [file-pad] #6 buttons=0000 lt=0 rt=0 lx=0 ly=0 rx=0 ry=0
+i> F8000008 [file-pad] keystroke vk=5800 up
+i> F8000008 [RE-INPUT] XamInputGetKeystrokeEx -> user=0 vk=5800 flags=0002 (call flags 00000003)
+w> F8000008 XThread::Resume: host resume was refused for thread F8000154
+w> F8000008 XThread::Resume: host resume was refused for thread F8000158
+w> F8000008 XThread::Resume: host resume was refused for thread F800015C
+K> F8000160 XThread::Execute thid 30 (handle=F8000160, 'XThread6DFFD6C0 (F8000160)', native=6DFFD6C0)
+w> F8000008 XThread::Resume: host resume was refused for thread F8000154
+w> F8000008 XThread::Resume: host resume was refused for thread F8000158
+w> F8000008 XThread::Resume: host resume was refused for thread F800015C
+w> F8000008 XThread::Resume: host resume was refused for thread F8000160
+w> F8000008 XThread::Resume: host resume was refused for thread F8000160
+w> F8000008 XThread::Resume: host resume was refused for thread F8000160
+w> F8000008 XThread::Resume: host resume was refused for thread F8000160
+w> F8000008 XThread::Resume: host resume was refused for thread F8000160
+w> F8000008 XThread::Resume: host resume was refused for thread F8000160
+!> F8000008 BaseHeap::Release failed because address is not a region start: addr=1E4B0E00 heap_base=00000000 page=124080 owning_region_start=1C220000 region_page_count=14976 state=03
+!> F8000008 PhysicalHeap::Release failed due to parent heap failure
+!> F8000008 BaseHeap::Release failed because address is not a region start: addr=1E7A8F00 heap_base=00000000 page=124840 owning_region_start=1C220000 region_page_count=14976 state=03
+!> F8000008 PhysicalHeap::Release failed due to parent heap failure
+F> F8000084 DiscImageDevice::ResolvePath(\dat)
+!> 0001278F MEM-WATCH rss=830MB (peak 830MB) vsz=19501MB malloc_inuse=349MB mmap=90MB cache_deque=40 cache_list=40
+!> 0001278F MEM-WATCH rss=831MB (peak 831MB) vsz=19501MB malloc_inuse=349MB mmap=90MB cache_deque=40 cache_list=40
+!> 0001278F MEM-WATCH rss=831MB (peak 831MB) vsz=19501MB malloc_inuse=349MB mmap=90MB cache_deque=40 cache_list=40
+!> 0001278F MEM-WATCH rss=831MB (peak 831MB) vsz=19501MB malloc_inuse=349MB mmap=90MB cache_deque=40 cache_list=40
+!> 0001278F MEM-WATCH rss=831MB (peak 831MB) vsz=19501MB malloc_inuse=349MB mmap=90MB cache_deque=40 cache_list=40
+!> 0001278F MEM-WATCH rss=832MB (peak 832MB) vsz=19501MB malloc_inuse=348MB mmap=90MB cache_deque=40 cache_list=40
+!> 0001278F MEM-WATCH rss=832MB (peak 832MB) vsz=19501MB malloc_inuse=348MB mmap=90MB cache_deque=40 cache_list=40
+i> F8000008 [file-pad] #7 buttons=1000 lt=0 rt=0 lx=0 ly=0 rx=0 ry=0
+i> F8000008 [file-pad] keystroke vk=5800 down
+i> F8000008 [RE-INPUT] XamInputGetKeystrokeEx -> user=0 vk=5800 flags=0001 (call flags 00000003)
+i> F8000008 XThreadF80000D4 (1F) Stack: 70880000-70900000
+K> F80000D4 XThread::Execute thid 31 (handle=F80000D4, 'XThread9BFFF6C0 (F80000D4)', native=9BFFF6C0)
+F> F80000D4 HostPathDevice::ResolvePath(\aab216c3\a\c7e701e)
+F> F80000D4 HostPathDevice::ResolvePath(\aab216c3\a)
+F> F80000D4 HostPathDevice::ResolvePath(\d5faa9db\e\b80b1a0)
+F> F80000D4 HostPathDevice::ResolvePath(\d5faa9db\e)
+F> F80000D4 HostPathDevice::ResolvePath(\d5faa9db\c\6dea48b)
+F> F80000D4 HostPathDevice::ResolvePath(\d5faa9db\c)
+i> F8000008 [file-pad] #8 buttons=0000 lt=0 rt=0 lx=0 ly=0 rx=0 ry=0
+i> F8000008 [file-pad] keystroke vk=5800 up
+i> F8000008 [RE-INPUT] XamInputGetKeystrokeEx -> user=0 vk=5800 flags=0002 (call flags 00000003)
+!> 0001278F MEM-WATCH rss=833MB (peak 833MB) vsz=19501MB malloc_inuse=349MB mmap=90MB cache_deque=40 cache_list=41
+w> F8000008 [RE-INPUT] XamInputGetKeystrokeEx swallowed by IsUIActive (ui_active=true, 1 so far)
+!> F8000008 BaseHeap::Release failed because address is not a region start: addr=1DA98C80 heap_base=00000000 page=121496 owning_region_start=1C220000 region_page_count=14976 state=03
+!> F8000008 PhysicalHeap::Release failed due to parent heap failure
+w> F8000008 [RE-INPUT] XamInputGetKeystrokeEx swallowed by IsUIActive (ui_active=true, 601 so far)
+w> F8000008 [RE-INPUT] XamInputGetKeystrokeEx swallowed by IsUIActive (ui_active=true, 1201 so far)
+w> F8000008 [RE-INPUT] XamInputGetKeystrokeEx swallowed by IsUIActive (ui_active=true, 1801 so far)
+w> F8000008 [RE-INPUT] XamInputGetKeystrokeEx swallowed by IsUIActive (ui_active=true, 2401 so far)
+w> F8000008 [RE-INPUT] XamInputGetKeystrokeEx swallowed by IsUIActive (ui_active=true, 3001 so far)
+w> F8000008 [RE-INPUT] XamInputGetKeystrokeEx swallowed by IsUIActive (ui_active=true, 3601 so far)
+
+# ---- 2. the last swallow report before the first crash dump (log line <15243)
+15236:w> F8000008 [RE-INPUT] XamInputGetKeystrokeEx swallowed by IsUIActive (ui_active=true, 8388001 so far)
+15237:w> F8000008 [RE-INPUT] XamInputGetKeystrokeEx swallowed by IsUIActive (ui_active=true, 8388601 so far)
+# total 'swallowed' report lines before the first crash dump:
+13982
+# they are emitted every 600th call, so swallowed calls ~= 600 x that count
+
+# ---- 3. the first crash dump's GPRs (log line 15243+)
+!> F8000008 ==== CRASH DUMP ====
+Thread ID (Host: 0xEEFFE6C0 / Guest: 0x00000006)
+Thread Handle: 0xF8000008
+PC: 0x824578A0
+Access Violation: write at 0x00000001701D0000
+Registers:
+ r0   = 0000000000000000
+ r1   = 00000000701CF7B0
+ r2   = 0000000020000000
+ r3   = 00000000701CF5F0
+ r4   = 0000000000000000
+ r5   = 0000000000000000
+ r6   = 0000000000000000
+ r7   = 00000000A3AC0000
+ r8   = 00000000701D0008
+ r9   = 00000000701D0000
+ r10  = 0000000000000000
+ r11  = 00000000A3AC0A18
+ r12  = 0000000082457864
+ r13  = 000000003001E000
+ r14  = 0000000000000000
+ r15  = 0000000000000000
+ r16  = 0000000000000000
+ r17  = 0000000000000000
+ r18  = 00000000BCE24BFC
+ r19  = 0000000000000001
+ r20  = 0000000000000000
+ r21  = FFFFFFFFFFFFFFFF
+ r22  = 00000000BC65D540
+ r23  = FFFFFFFF828F3844
+ r24  = 000000000000052F
+ r25  = FFFFFFFF828E0000
+ r26  = 0000000000800001
+ r27  = 0000000001000000
+ r28  = 00000000701CF898
+ r29  = 0000000000800000
+ r30  = FFFFFFFF828F38CC
+ r31  = 00000000A7AC0000

docs/re/data/adv-stream-assignment.txt

@@ -0,0 +1,50 @@
+# Which ADV voice stream sits where -- the assignment, and how it was settled.
+#
+# 2026-08-30. Chunks dumped by examples/adv_voice_dump.rs from the resolved
+# movie voice region (dat/sound 433930240..437044592), decoded with ffmpeg's
+# xma decoder to f32le 48 kHz stereo.
+#
+# chunk  bytes    byte_size  probe ctx   dur      L rms    R rms    L/R r   R silent
+#   0     806972    806912   ctx0 TAIL   84.55s  -24.79   -24.81   +0.932    53.1%
+#   1    1118268   1118208   ctx1       137.32s  -20.33     -inf   +0.000   100.0%
+#   2    1171516   1171456   ctx2       137.32s  -30.67   -30.68   +0.962    53.6%
+#
+# ctx0's full byte_size is 1294336; the region resolver starts at the
+# predecessor cue's trailer, so chunk 0 is its clipped tail (62 %).
+#
+# 🔴 WHAT DID NOT WORK: envelope correlation cannot discriminate.
+# Every residual channel shares the dialogue's activity timing, so a
+# ⚠️ IN THIS REGIME ONLY (corrected 2026-08-30): the port controlled the same
+# estimator on a single dialogue track and got r=1.0000 at zero offset with
+# -0.08..+0.08 elsewhere -- it localises sharply. The saturation below needs
+# CONCURRENT streams sharing timing at zero lag. Not a general limit.
+# per-pair lag search returns 0.86-0.95 for EVERY chunk against EVERY
+# channel. Recorded because it looks like a strong result and is not.
+#
+# 🔴 Sample-level correlation also fails: the chunks do not start with the
+# movie and the XMA decode's framing offset is unknown, so r ~ 0.
+#
+# ✅ WHAT SETTLES IT: level, under the SAME 0.600 gain the bed uses.
+#
+# chunk   level   x0.600   nearest residuals (|error| dB)
+#  0L    -24.79   -29.23   FL 0.05  FR 0.06  FC 3.96
+#  0R    -24.81   -29.25   FL 0.03  FR 0.04  FC 3.98
+#  1L    -20.33   -24.77   FC 0.50  FL 4.51  FR 4.52
+#  2L    -30.67   -35.11   BL 0.35  BR 0.38  FR 5.82
+#  2R    -30.68   -35.12   BL 0.34  BR 0.37  FR 5.83
+#
+# Ratio test, immune to any worry about chunk 0 being clipped:
+#   chunk0L - chunk2L = +5.88 dB ;  FL - BL = +6.18 dB  -> agree to 0.30 dB
+#   swapped, the ratio would be wrong by 11.76 dB
+#
+# Structural confirmation: chunk 1 is the ONLY chunk with a digitally silent
+# channel (R, 100 %), and LFE is the ONLY output channel with an empty
+# residual (-115.73 dBFS). One-to-one.
+#
+# Internal L/R correlation also tracks:
+#   chunk0 +0.932 <-> FL/FR residual +0.918
+#   chunk2 +0.962 <-> BL/BR residual +0.929
+#
+# ==> ctx0 (1294336) -> FL, FR
+# ==> ctx1 (1118208) -> FC, LFE silent
+# ==> ctx2 (1171456) -> BL, BR

docs/re/data/b-on-main-menu.txt

@@ -0,0 +1,63 @@
+# What Ⓑ does on the MAIN MENU -- measured 2026-08-30.
+#
+# menu-navigation-semantics.md had this row at 🟡 with an EMPTY evidence cell,
+# and it is what the port still authors as on_cancel.
+#
+# Harness: tools/re-capture/b_from_menu.py -- the plate-pulse title detector,
+# the glyph-327 menu detector, delivery confirmed from [RE-INPUT] rather than
+# from the pad, and change detected rather than timed. B is kXInputPadB =
+# 0x5801 (ui/virtual_key.h:323).
+#
+#   [321.7s] TITLE (glyph 959)
+#   [322.7s] A delivered (attempt 1)
+#   [327.7s] MENU (glyph 327) -- pressing B
+#   [331.2s] B delivered (attempt 1)
+#   [335.0s] screen changed: 73.5 % of pixels differ, glyph 0
+#   [341.3s] glyph 154
+#
+# THE SERIES ACROSS THE PRESS (t : glyph):
+#   326.2 : 0
+#   326.5 : 327
+#   326.7 : 327
+#   326.9 : 327
+#   327.2 : 327
+#   327.4 : 327
+#   327.7 : 327
+#   331.2 : 327
+#   331.6 : 0
+#   332.4 : 0
+#   332.8 : 0
+#   333.3 : 0
+#   333.8 : 0
+#   334.1 : 0
+#   334.5 : 0
+#   335.0 : 0
+#   340.2 : 0
+#   340.5 : 54
+#   340.7 : 154
+#   340.8 : 154
+#   340.9 : 154
+#   341.0 : 154
+#   341.1 : 154
+#   341.2 : 154
+#   341.3 : 154
+#
+# READING: B on the main menu goes to the TITLE. Both captures name
+# themselves -- PROJECT SYLPHEED with the (C)2006,2007 SQUARE ENIX line.
+#   2-after-B-on-menu.png  the title MID-BUILD-IN: wordmark drawn, the green
+#                          copyright line not yet -- which is why glyph is 0
+#                          while 78.0 % of the surface is inked
+#   3-after-B-again.png    copyright drawn, glyph 154 = the plate-absent floor
+#
+# ✅ NO LOADING SCREEN between. The disc carries four pgloading_* bundles and
+# none appears on this path.
+#
+# ✅ LATENCY <= 0.4 s: B delivered at 331.2, glyph leaves 327 by 331.6, at a
+# 4 Hz sample rate. The corpus previously had this as 'not measured (a
+# backlogged probe void)'.
+#
+# 🔴 WHAT THIS RUN CANNOT SAY: 'B on the title -> nothing'. The second B was
+# delivered at 340.2, DURING the title's build-in, so the glyph 0 -> 154
+# change that follows is the build-in completing and not a response. That row
+# stays 🟡 with no evidence, and a run that answers it must wait for the title
+# to SETTLE before pressing.

docs/re/data/bgm-stem-coherence.txt

@@ -0,0 +1,71 @@
+# Is a music bank's wave 1 the SAME instruments filtered, or DIFFERENT parts?
+# BGM_103 (the menu's music) -- 2026-08-30
+#
+# structures/bgm-two-stems.md leaves two readings alive for wave 1: the rear
+# pair of a 4-channel mix, or a second intensity layer -- and correctly notes
+# that runtime simultaneity cannot separate them, because both predict it.
+# This is a static attempt at a discriminator.
+#
+# METHOD: magnitude-squared coherence, Welch, NFFT 8192 @ 48 kHz, 60 s window
+# (702 segments, so the bias floor is ~1/702 = 0.0014). Coherence is ~1 wherever
+# one signal is a LINEAR FILTER of the other and ~0 for independent signals.
+# tools/re-capture/bgm_stem_coherence.py
+#
+# WAVES: slb_extract_wave.py BGM_103.slb 14336 1893 2 48000   (wave 0)
+#        slb_extract_wave.py BGM_103.slb 3903488 1919 2 48000 (wave 1)
+#        then ffmpeg -i x.riff x.wav. Both decode to 87.744 s, 4 211 729 frames.
+# CONTROL BANK: BGM_104.slb 14336 1305 (a different piece, same codec).
+#
+CONTROLS
+  POS w0 vs linear-filter(w0)        0-0.2k 0.929  0.2-1k 0.938  1-4k 0.936  4-12k 0.938  12-16k 0.938  16-24k 0.937
+  NEG w0 vs a different bank         0-0.2k 0.001  0.2-1k 0.001  1-4k 0.001  4-12k 0.001  12-16k 0.001  16-24k 0.002
+  NEG w0 vs w0 shifted 1 s           0-0.2k 0.057  0.2-1k 0.048  1-4k 0.007  4-12k 0.019  12-16k 0.015  16-24k 0.004
+  REF w0 L vs R (one perf.)          0-0.2k 0.321  0.2-1k 0.221  1-4k 0.363  4-12k 0.445  12-16k 0.497  16-24k 0.450
+  REF w1 L vs R (one perf.)          0-0.2k 0.078  0.2-1k 0.051  1-4k 0.089  4-12k 0.411  12-16k 0.453  16-24k 0.455
+
+MEASUREMENT
+  w0 vs w1                           0-0.2k 0.169  0.2-1k 0.184  1-4k 0.027  4-12k 0.635  12-16k 0.768  16-24k 0.827
+
+ENERGY SHARE
+  w0                                 0-0.2k  71.4%  0.2-1k  24.8%  1-4k   2.4%  4-12k   1.0%  12-16k   0.1%  16-24k   0.2%
+  w1                                 0-0.2k  53.8%  0.2-1k  40.9%  1-4k   2.3%  4-12k   2.1%  12-16k   0.3%  16-24k   0.6%
+
+# ------------------------------------------------------------------------------
+# READING IT
+#
+# ✅ THE INSTRUMENT IS CALIBRATED. A real linear filter of w0 reads 0.93-0.94 in
+# every band; a different bank reads 0.001-0.002; w0 against itself misaligned by
+# 1 s reads 0.004-0.057. So the estimator detects filtering and is not fooled by
+# two pieces of music in the same codec.
+#
+# ❌ REFUTED: "wave 1 is wave 0 put through a filter." The positive control says
+# a filter reads 0.936 at 1-4 kHz. The measurement reads 0.027 there. No linear
+# filter produces that in a band where both waves carry energy.
+#
+# 📌 THE FREQUENCY STRUCTURE IS INVERTED relative to any mic-pair or reverb
+# model. Coherence RISES with frequency -- 0.169, 0.184, 0.027, 0.635, 0.768,
+# 0.827 -- while energy FALLS -- 71.4 %, 24.8 %, 2.4 %, 1.0 %, 0.1 %, 0.2 %.
+# A rear pair or a reverb return decorrelates FASTEST at high frequency, which
+# is the opposite. What is coherent lives in bands holding ~1.3 % of the energy;
+# the bands holding 96 % of it read 0.169 and 0.184.
+#
+# 📌 AND IN THE MUSICAL MIDRANGE THE TWO WAVES ARE FURTHER APART THAN THE TWO
+# CHANNELS OF ONE WAVE: 1-4 kHz gives 0.027 between waves against 0.363 for w0's
+# own L vs R -- a factor of 13. Two channels of one performance agree far more
+# than the two waves do.
+#
+# 🔴 BUT THE L-R CONTROL IS ALSO WHAT LIMITS THIS TOOL, AND IT KILLS THE CLEAN
+# ANSWER. L vs R within a single wave is genuinely "one performance, two
+# channels", and it reads only 0.221-0.497 -- nowhere near the 0.94 a filter
+# gives. So in THIS material "same performance" does not imply high coherence,
+# which means my positive control was the wrong model of the rear-pair reading:
+# a real 4-channel mix's rear pair is not a linear filter of its front pair.
+#
+# => The filter model is dead. The two named readings are NOT separated. This
+#    tool cannot separate them, and the reason is stated rather than discovered
+#    later: it tests for linear filtering, and neither reading requires it.
+#
+# ⚠️ REACH: one bank (BGM_103), one 60 s window, mono-summed for the coherence
+# rows. Not run over the other 31 banks. The 16-24 kHz reading of 0.827 sits in
+# 0.2-0.6 % of the energy and is unexplained -- it is NOT generic codec
+# behaviour, since the different-bank control reads 0.002 in the same band.

docs/re/data/black-backdrop-predicate.txt

@@ -0,0 +1,55 @@
+# Does a screen declare its own OPAQUE-BLACK backdrop? Disc-wide. 2026-08-30.
+# instrument: crates/sylpheed-formats/examples/black_backdrop_predicate.rs
+# predicate: some .prm element holds fade == 0xff000000 at t=0.
+#
+# sylpheed-port proposed this as a rule separating STANDALONE screens from
+# COMPOSITED ones, split 12/4 across their sixteen exported screens, and asked
+# for it to be tested against archives they do not have.
+#
+== CONTROL: GP_TITLE's 16 composable bundles (port reports 12 with, 4 without)
+   entry  0  no
+   entry  1  no
+   entry  2  no
+   entry  3  no
+   entry  4  YES  pteff00.prm
+   entry  5  YES  pteff00.prm
+   entry  6  YES  pteff00.prm
+   entry  7  YES  pteff00.prm
+   entry  8  YES  pteff00.prm
+   entry  9  YES  pteff00.prm
+   entry 10  YES  palogo_eff0.prm
+   entry 11  YES  palogo_eff0.prm
+   entry 12  YES  pgloading_eff00.prm
+   entry 13  YES  palogo_eff0.prm
+   entry 14  YES  palogo_eff0.prm
+   entry 15  YES  pgloading_eff00.prm
+   -> 12 with, 4 without
+
+== DISC-WIDE, over every screen build
+GP_BUNK.pak                       6 / 8    declare a black backdrop
+GP_CHALLENGE.pak                  6 / 78   declare a black backdrop
+GP_DEBRIEFING_PILOTLOG.pak        0 / 18   declare a black backdrop
+GP_DIALOG.pak                    34 / 105  declare a black backdrop
+GP_GAMEOVER.pak                   0 / 10   declare a black backdrop
+GP_HANGAR_ARSENAL.pak             0 / 390  declare a black backdrop
+GP_LEADERBOARD.pak                0 / 4    declare a black backdrop
+GP_MAIN_GAME_D2D.pak              0 / 18   declare a black backdrop
+GP_MAIN_GAME_E2D.pak              0 / 18   declare a black backdrop
+GP_MAIN_GAME_F2D.pak              0 / 18   declare a black backdrop
+GP_MAIN_GAME_I2D.pak              0 / 18   declare a black backdrop
+GP_MAIN_GAME_J2D.pak              0 / 18   declare a black backdrop
+GP_MAIN_GAME_S2D.pak              0 / 18   declare a black backdrop
+GP_MISSION_LOG.pak                0 / 4    declare a black backdrop
+GP_MISSION_SELECT.pak             2 / 66   declare a black backdrop
+GP_MOVIE_THEATER.pak              2 / 56   declare a black backdrop
+GP_OPTIONS.pak                    0 / 14   declare a black backdrop
+GP_PAUSE_MENU.pak                 0 / 6    declare a black backdrop
+GP_READY_ROOM.pak                 0 / 60   declare a black backdrop
+GP_SAVE_LOAD.pak                 10 / 18   declare a black backdrop
+GP_STAGE_CLEAR.pak                4 / 4    declare a black backdrop
+GP_SYSTEM.pak                     2 / 2    declare a black backdrop
+GP_TITLE.pak                      8 / 12   declare a black backdrop
+GP_TUTORIAL.pak                   2 / 2    declare a black backdrop
+
+76 of 965 screen builds disc-wide declare an opaque-black backdrop (7.9 %)
+--- END ---

docs/re/data/boot-splash-gap-draws.csv

@@ -0,0 +1,234 @@
+# Every sprite quad submitted during the boot splashes, from the guest's
+# own draw stream. Capture: ui_draw_capture.sh GRACE=1 NOTAP=1 ARM=early,
+# 2026-08-29. Full-screen quads (w>=1250) are omitted.
+# frames 126..129 carry NO sprite quad at all -- that is the black gap.
+frame,x,y,w,h,vertex_alpha
+2,301,317,685,90,119
+3,301,317,685,90,153
+4,301,317,685,90,187
+6,301,317,685,90,246
+7,301,317,685,90,240
+9,301,317,685,90,229
+10,301,317,685,90,223
+11,301,317,685,90,220
+12,301,317,685,90,214
+13,301,317,685,90,211
+14,301,317,685,90,183
+15,301,317,685,90,155
+16,301,317,685,90,127
+17,301,317,685,90,98
+18,301,317,685,90,70
+19,301,317,685,90,56
+20,301,317,685,90,28
+21,307,331,666,65,255
+22,307,331,666,65,255
+23,307,331,666,65,255
+24,307,331,666,65,255
+25,307,331,666,65,255
+26,307,331,666,65,255
+27,307,331,666,65,255
+28,307,331,666,65,255
+29,307,331,666,65,255
+30,307,331,666,65,255
+31,307,331,666,65,255
+32,307,331,666,65,255
+34,307,331,666,65,255
+35,307,331,666,65,255
+37,307,331,666,65,255
+38,307,331,666,65,255
+39,307,331,666,65,255
+40,307,331,666,65,255
+41,307,331,666,65,255
+42,307,331,666,65,255
+43,307,331,666,65,255
+44,307,331,666,65,255
+45,307,331,666,65,255
+46,307,331,666,65,255
+47,307,331,666,65,255
+48,307,331,666,65,255
+49,307,331,666,65,255
+50,307,331,666,65,255
+51,307,331,666,65,255
+52,307,331,666,65,255
+53,307,331,666,65,255
+54,307,331,666,65,255
+55,307,331,666,65,255
+56,307,331,666,65,255
+57,307,331,666,65,255
+58,307,331,666,65,255
+59,307,331,666,65,255
+60,307,331,666,65,255
+61,307,331,666,65,255
+62,307,331,666,65,255
+63,307,331,666,65,255
+64,307,331,666,65,255
+65,307,331,666,65,255
+66,307,331,666,65,255
+67,307,331,666,65,255
+68,307,331,666,65,255
+69,307,331,666,65,255
+70,307,331,666,65,255
+71,307,331,666,65,255
+72,307,331,666,65,255
+73,307,331,666,65,255
+74,307,331,666,65,255
+75,307,331,666,65,255
+76,307,331,666,65,255
+77,307,331,666,65,255
+78,307,331,666,65,255
+79,307,331,666,65,255
+80,307,331,666,65,255
+81,307,331,666,65,255
+82,307,331,666,65,255
+83,307,331,666,65,255
+84,307,331,666,65,255
+85,307,331,666,65,255
+86,307,331,666,65,255
+87,307,331,666,65,255
+88,307,331,666,65,255
+89,307,331,666,65,255
+90,307,331,666,65,255
+91,307,331,666,65,255
+92,307,331,666,65,255
+93,307,331,666,65,255
+94,307,331,666,65,255
+95,307,331,666,65,255
+96,307,331,666,65,255
+97,307,331,666,65,255
+98,307,331,666,65,255
+99,307,331,666,65,255
+100,307,331,666,65,255
+102,307,331,666,65,255
+103,307,331,666,65,255
+105,307,331,666,65,255
+106,307,331,666,65,255
+107,307,331,666,65,255
+108,307,331,666,65,255
+109,307,331,666,65,255
+110,307,331,666,65,255
+111,307,331,666,65,255
+112,307,331,666,65,255
+113,307,331,666,65,249
+114,307,331,666,65,243
+115,307,331,666,65,231
+116,307,331,666,65,198
+117,307,331,666,65,181
+118,307,331,666,65,165
+119,307,331,666,65,148
+120,307,331,666,65,115
+121,307,331,666,65,81
+122,307,331,666,65,65
+123,307,331,666,65,31
+124,307,331,666,65,15
+125,307,331,666,65,7
+130,378,155,525,259,34
+131,378,155,525,259,51
+132,378,155,525,259,85
+133,378,155,525,259,119
+134,378,155,525,259,136
+135,378,155,525,259,153
+136,378,155,525,259,170
+137,378,155,525,259,221
+138,378,155,525,259,255
+139,378,155,525,259,255
+140,378,155,525,259,255
+141,378,155,525,259,255
+142,378,155,525,259,255
+143,378,155,525,259,255
+144,378,155,525,259,255
+145,378,155,525,259,255
+146,378,155,525,259,254
+147,378,155,525,259,220
+148,378,155,525,259,186
+149,378,155,525,259,152
+151,378,155,525,259,84
+152,378,155,525,259,50
+153,378,155,525,259,33
+154,390,162,499,241,255
+155,390,162,499,241,255
+156,390,162,499,241,255
+157,390,162,499,241,255
+158,390,162,499,241,255
+159,390,162,499,241,255
+160,390,162,499,241,255
+161,390,162,499,241,255
+162,390,162,499,241,255
+163,390,162,499,241,255
+164,390,162,499,241,255
+165,390,162,499,241,255
+166,390,162,499,241,255
+167,390,162,499,241,255
+168,390,162,499,241,255
+169,390,162,499,241,255
+170,390,162,499,241,255
+171,390,162,499,241,255
+172,390,162,499,241,255
+173,390,162,499,241,255
+174,390,162,499,241,255
+176,390,162,499,241,255
+177,390,162,499,241,255
+179,390,162,499,241,255
+180,390,162,499,241,255
+181,390,162,499,241,255
+183,390,162,499,241,255
+184,390,162,499,241,255
+185,390,162,499,241,255
+186,390,162,499,241,255
+187,390,162,499,241,255
+188,390,162,499,241,255
+189,390,162,499,241,255
+190,390,162,499,241,255
+191,390,162,499,241,255
+192,390,162,499,241,255
+193,390,162,499,241,255
+194,390,162,499,241,255
+195,390,162,499,241,255
+196,390,162,499,241,255
+197,390,162,499,241,255
+198,390,162,499,241,255
+199,390,162,499,241,255
+200,390,162,499,241,255
+201,390,162,499,241,255
+202,390,162,499,241,255
+203,390,162,499,241,255
+204,390,162,499,241,255
+205,390,162,499,241,255
+206,390,162,499,241,255
+207,390,162,499,241,255
+208,390,162,499,241,255
+209,390,162,499,241,255
+210,390,162,499,241,255
+211,390,162,499,241,255
+212,390,162,499,241,255
+213,390,162,499,241,255
+214,390,162,499,241,255
+215,390,162,499,241,255
+216,390,162,499,241,255
+217,390,162,499,241,255
+218,390,162,499,241,255
+219,390,162,499,241,255
+221,390,162,499,241,255
+223,390,162,499,241,255
+224,390,162,499,241,255
+225,390,162,499,241,255
+226,390,162,499,241,255
+227,390,162,499,241,255
+228,390,162,499,241,255
+229,390,162,499,241,255
+230,390,162,499,241,255
+231,390,162,499,241,255
+232,390,162,499,241,255
+233,390,162,499,241,255
+234,390,162,499,241,255
+235,390,162,499,241,255
+236,390,162,499,241,254
+237,390,162,499,241,243
+238,390,162,499,241,231
+239,390,162,499,241,198
+240,390,162,499,241,165
+241,390,162,499,241,131
+242,390,162,499,241,115
+243,390,162,499,241,81
+244,390,162,499,241,48
+245,390,162,499,241,23
+246,390,162,499,241,7

docs/re/data/decoder-eras-all-16-builds.txt

@@ -0,0 +1,46 @@
+# The two decoder eras, rendered: all 16 composable bundles of GP_TITLE.
+# 2026-08-30.
+#
+# STALE era = origin/main  (ui_layout.rs: "Keyframe time, or None for the
+#             group's last frame" -- a pose's time read from the NEXT record)
+# FIXED era = formats-pin-2026-08-30 == this branch (a pose's time PRECEDES it)
+#
+# Both built from source; renders are `screen render --all --build N --primitives`.
+#
+# CONTROL 1 -- the two binaries really do embody the two eras:
+#   stale  rest (0,0) t=70  [12:0,0 70:0,0 80:0,0 -:0,0]
+#   fixed  rest (0,0) t=12  [0:0,0 12:0,0 70:0,0 80:0,0]     (build 5, pteff00.prm)
+# CONTROL 2 -- the renderer is deterministic: same binary, same flags, twice,
+#   entry 7 -> 0 differing px, entry 12 -> 0 differing px.
+
+entry  what                    differing px     RMSE  max|d|
+    0  loading                            0    0.000       0
+    1  loading                            0    0.000       0
+    2  plate                              0    0.000       0
+    3  plate                              0    0.000       0
+    4  title                              0    0.000       0
+    5  main_menu                          0    0.000       0
+    6  extras                             0    0.000       0
+    7  title_jp                       74507   12.409     233  <-- DIFFERS
+    8  main_menu_jp                       0    0.000       0
+    9  extras_jp                          0    0.000       0
+   10  splash publisher               32842    1.767      35  <-- DIFFERS
+   11  splash developer               23201    0.942      31  <-- DIFFERS
+   12  loading (dressed)              49771   10.078     229  <-- DIFFERS
+   13  splash publisher twin          31708    1.782      35  <-- DIFFERS
+   14  splash developer twin          23201    0.942      31  <-- DIFFERS
+   15  loading twin                   49771   10.078     229  <-- DIFFERS
+
+7 of 16 bundles differ between the eras; 16-7 are byte-identical.
+
+# MECHANISM, entry 7 (title_jp): exactly ONE element's rest POSITION moves.
+#   stale   8 ptlogo_eff3.t32 ... rest (108,72)
+#   fixed   8 ptlogo_eff3.t32 ... rest  (98,42)
+# ptlogo_eff3.t32 is the element MISSION.md and ui-resting-pose.md already
+# name as THE plateau-less rest() discriminator. 74 507 px, RMSE 12.4.
+
+# MECHANISM, entries 10-15: NO rest position changes at all. The rest
+# SELECTION moves to a different keyframe which happens to sit at the same
+# (x,y) with a different SCALE and ALPHA -- e.g. pgloading_delta.t32 holds
+# (120,560) at 0%,0% a=0 / 75%,75% a=128 / 96%,96% a=192. Comparing the
+# 'rest (x,y)' column alone says nothing changed; the pixels say otherwise.

docs/re/data/env-var-surface.txt

@@ -0,0 +1,37 @@
+# The environment-variable surface, both directions. 2026-08-30.
+#
+# sylpheed-port swept documented -> parsed and found three live-but-undocumented
+# flags, noting that a capability documented only in an 11 000-line record is, to
+# anyone reading the interface, a capability that does not exist. This is the
+# mirror on my side: every env var the CODE reads, checked against the docs.
+# Like theirs it ENUMERATES, so it completes rather than samples.
+#
+#   41 environment variables read by crates/
+#   19 documented
+#   22 NOT documented, splitting cleanly:
+#
+#      7 read only in examples/ -- per-example output filters and dump paths.
+#        KF_SHOW, MAX_PAD, OUT_DIR_X, SUPPRESS_SUBSTR, SYLPH_RAW,
+#        VOICE_CHUNK_DUMP, DUMP_XPR_DIR
+#        Scratch. Reachable only by editing an example's command line.
+#
+#     15 read in src/ -- LIVE capabilities of the library and CLI:
+#        mesh / 3D   XCOLORSUB XDUMPHDR XDUMPVERT XMESHDBG XMIRROR XNODEDUMP
+#                    XNODEXFORM XONLYSUB XSPANHIDE XSPANONLY
+#        texture     XPR_FORCE_ENDIAN XPR_NO_BC_DWORD_SWAP XPR_NO_DETILE
+#                    XPR_NO_ENDIAN XPR_RES_INDEX
+#
+# ✅ FOR THE PORT: none of the 15 is in the UI path. Every env var ui_layout.rs
+# and the screen commands read is documented -- SYLPHEED_REST_RULE and
+# SYLPHEED_KF_TIME_LEGACY. The menu lane is clean in this direction.
+#
+# ⚠️ The five XPR_* are TEXTURE DECODE toggles and the port consumes textures. If
+# a sprite comparison ever disagrees, these are the knobs, and they are invisible
+# from the interface.
+#
+# 🔴 LIMIT, stated rather than glossed: I verified NONE of the 15 end to end.
+# `texture export` takes a loose file and the disc keeps its textures inside paks,
+# so the check cost more than the answer was worth in this iteration. That matters
+# because sylpheed-port found `--no-hold` PARSED, DOCUMENTED and INERT under an
+# interaction with `--time`: "parsed and reachable" is not "works". So the honest
+# claim is that 15 undocumented env vars are READ, not that 15 capabilities exist.

docs/re/data/fade-envelope-menu-to-title.txt

@@ -0,0 +1,43 @@
+# Menu -> title transition, per-frame, from the running game.
+# tools/re-capture/fade_decompose.sh -> log_ui_draws capture (260 frames)
+# tools/re-capture/fade_envelope.py  (the fade quad = last FULL-SCREEN
+#   UNTEXTURED quad in a frame: a .prm carries no tex[base=], and the fade
+#   quad paints last).
+# Xenia VdSwap frame numbers. 2026-08-30.
+#
+# TIMING CHECK: F10 armed the capture at frame 1; the script sent (B) 1.2 s
+# later. 1.2 s at 30 Hz is frame ~36. The fade begins at 34. The press and
+# the transition agree without either being used to place the other.
+#
+# frame   untextured full-screen quad alphas, in submission order
+   28   [[64]]                     draws= 12 tex= 10
+   29   [[64]]                     draws= 12 tex= 10
+   30   [[64]]                     draws= 12 tex= 10
+   31   [[64]]                     draws= 12 tex= 10
+   32   [[64]]                     draws= 12 tex= 10
+   34   [[64, 255], [64]]          draws= 15 tex= 12   <- content starts fading
+   35   [[64, 223], [64]]          draws= 15 tex= 12
+   36   [[64, 207], [64]]          draws= 15 tex= 12
+   37   [[64, 175], [64]]          draws= 14 tex= 11
+   39   [[64, 95], [64]]           draws= 11 tex=  8
+   40   [[64, 31], [64], [102]]    draws= 12 tex=  6   <- BLACK QUAD APPEARS
+   41   [[64, 15], [64], [127]]    draws= 12 tex=  6
+   43   [[64], [64], [255]]        draws= 12 tex=  6   <- fully black
+   44   [[64], [64], [255]]        draws= 12 tex=  6
+   45   [[64], [64], [255]]        draws= 12 tex=  6
+   46   [[64]]                     draws=  6 tex=  2   <- menu stops drawing (6 draws vs 12); ONE frame of black
+   47   [[64]]                     draws=  8 tex=  6
+   49   [[64]]                     draws=  8 tex=  6
+   50   [[64]]                     draws=  8 tex=  6
+   51   [[64]]                     draws=  8 tex=  6
+   52   [[64]]                     draws=  8 tex=  6
+   53   [[64]]                     draws=  8 tex=  6
+   54   [[64]]                     draws=  8 tex=  6
+   55   [[64]]                     draws=  8 tex=  6
+   56   [[73]]                     draws=  8 tex=  6
+   57   [[93]]                     draws=  8 tex=  6
+   58   [[113]]                    draws=  9 tex=  7
+   59   [[152]]                    draws= 12 tex= 10
+   60   [[172]]                    draws= 12 tex= 10
+
+missing submitted frames in this span: 33->34, 37->39, 41->43, 47->49

docs/re/data/fade-four-transitions.txt

@@ -0,0 +1,354 @@
+# FOUR screen changes, per frame, from the running game. 2026-08-30.
+# tools/re-capture/fade_decompose.sh (WHERE=menu | title | extras)
+#
+# Captures 2 and 4 are the SAME transition, title -> menu via (A), run twice.
+# They are the hold-vs-load test: a load varies with cache and contention,
+# a deterministic hold does not. The pair carries its own control -- the
+# press-to-first-change latency DIFFERS by ~12 frames between the two runs,
+# so conditions demonstrably were not identical, while the black gap is
+# exactly 3 frames in both.
+#
+#   quantity                    run 1 (cap 2)          run 2 (cap 4)
+#   outgoing quad rise          67-70: 63,127,191,255  64-67: 63,127,191,255
+#   frames black ([255] alone)  70,71,72 = 3           67,68,69 = 3
+#   incoming appears            frame 73               frame 70
+#   incoming decay              255,-,127,84,63        255,169,127,84,42
+#   press -> first change       ~25 frames             ~10 frames
+
+############ CAPTURE 1 -- menu -> title, via (B) ############
+frame  untextured full-screen   textured (distinct)        draws tex
+   28  [64]                   [142, 146, 192, 255]         12  10
+   29  [64]                   [143, 146, 192, 255]         12  10
+   30  [64]                   [143, 147, 192, 255]         12  10
+   31  [64]                   [143, 147, 192, 255]         12  10
+   32  [64]                   [144, 148, 192, 255]         12  10
+   34  [64, 255, 64]          [144, 148, 169, 191, 254, 255]   15  12
+   35  [64, 223, 64]          [84, 143, 145, 149, 191, 255]   15  12
+   36  [64, 207, 64]          [42, 119, 145, 149, 159, 255]   15  12
+   37  [64, 175, 64]          [71, 95, 145, 149, 191, 255]   14  11
+   39  [64, 95, 64]           [146, 150, 255]              11   8
+   40  [64, 31, 64, 102]      [146, 151, 255]              12   6
+   41  [64, 15, 64, 127]      [146, 151, 255]              12   6
+   43  [64, 64, 255]          [147, 152, 255]              12   6
+   44  [64, 64, 255]          [147, 152, 255]              12   6
+   45  [64, 64, 255]          [148, 152, 255]              12   6
+   46  [64]                   [255]                         6   2
+   47  [64]                   [32, 255]                     8   6
+   49  [64]                   [32, 96, 255]                 8   6
+   50  [64]                   [48, 128, 255]                8   6
+
+############ CAPTURE 2 -- title -> menu, via (A), run 1 ############
+frame  untextured full-screen   textured (distinct)        draws tex
+   60  []                     [42, 50, 55, 84, 255]         9   8
+   61  []                     [16, 18, 255]                 8   7
+   62  []                     [235, 255]                    7   6
+   63  []                     [196, 255]                    7   6
+   64  []                     [156, 255]                    7   6
+   65  []                     [117, 255]                    7   6
+   66  []                     [78, 255]                     7   6
+   67  [63]                   [19, 255]                     8   4
+   68  [127]                  [255]                         6   2
+   69  [191]                  [255]                         6   2
+   70  [255]                  [255]                         6   2
+   71  [255]                  [255]                         6   2
+   72  [255]                  [255]                         6   2
+   73  [64, 255]              [255]                         7   3
+   75  [64, 127]              [2, 252, 255]                 7   3
+   76  [64, 84]               [3, 251, 255]                 7   3
+   77  [64, 63]               [3, 251, 255]                 7   3
+   78  [64]                   [5, 249, 255]                 7   3
+   79  [64]                   [5, 249, 255]                 7   3
+   80  [64]                   [7, 32, 247, 255]             8   6
+   81  [64]                   [8, 96, 246, 255]             8   6
+   82  [64]                   [8, 160, 246, 255]            8   6
+
+############ CAPTURE 3 -- EXTRAS -> menu, via (B) ############
+frame  untextured full-screen   textured (distinct)        draws tex
+   28  [64]                   [128, 171, 181, 255]         11   9
+   29  [64]                   [128, 172, 182, 255]         11   9
+   30  [64]                   [111, 127, 172, 182, 185, 255]   11   9
+   31  [64]                   [42, 79, 139, 172, 183, 223, 255]   11   9
+   32  [64]                   [31, 69, 127, 173, 183, 255]   10   8
+   33  [64]                   [31, 173, 184, 255]           9   7
+   34  [64, 51]               [174, 184, 255]               8   4
+   35  [64, 102]              [174, 184, 255]               8   4
+   36  [64, 178]              [174, 185, 255]               8   4
+   37  [64, 229]              [174, 185, 255]               8   4
+   38  [64, 255]              [175, 186, 255]               8   4
+   39  []                     []                            3   0
+   40  []                     []                            3   0
+   41  [64, 169]              [1, 253, 255]                 7   3
+   42  [64, 148]              [2, 252, 255]                 7   3
+   43  [64, 106]              [2, 252, 255]                 7   3
+   44  [64, 63]               [3, 251, 255]                 7   3
+   45  [64, 21]               [4, 250, 255]                 7   3
+   46  [64]                   [5, 249, 255]                 7   3
+   47  [64]                   [6, 248, 255]                 7   3
+   48  [64]                   [7, 32, 247, 255]             8   6
+   49  [64]                   [8, 96, 246, 255]             8   6
+   50  [64]                   [9, 192, 245, 255]            8   6
+
+############ CAPTURE 4 -- title -> menu, via (A), run 2 ############
+frame  untextured full-screen   textured (distinct)        draws tex
+   61  []                     [137, 255]                    7   6
+   62  []                     [98, 255]                     7   6
+   63  []                     [78, 255]                     7   6
+   64  [63]                   [19, 255]                     8   4
+   65  [127]                  [255]                         6   2
+   66  [191]                  [255]                         6   2
+   67  [255]                  [255]                         6   2
+   68  [255]                  [255]                         6   2
+   69  [255]                  [255]                         6   2
+   70  [64, 255]              [255]                         7   3
+   71  [64, 169]              [1, 253, 255]                 7   3
+   72  [64, 127]              [2, 252, 255]                 7   3
+   73  [64, 84]               [3, 251, 255]                 7   3
+   74  [64, 42]               [4, 250, 255]                 7   3
+   75  [64]                   [5, 249, 255]                 7   3
+   76  [64]                   [6, 248, 255]                 7   3
+   77  [64]                   [7, 32, 247, 255]             8   6
+   78  [64]                   [8, 96, 246, 255]             8   6
+   79  [64]                   [9, 192, 245, 255]            8   6
+   80  [64]                   [10, 244, 255]                8   6
+
+################################################################################
+# A THIRD title -> menu REPLICATE, 2026-08-30 -- from a run that executed the
+# WRONG EXPERIMENT. The script was invoked as WHERE=menu2extras but a condition
+# edit had silently failed to apply, so it took the `title` branch instead. The
+# capture is well-formed and is of a different transition than intended -- the
+# same shape as the build-ordinal error, caught only because the log lacked the
+# navigation lines the intended branch prints.
+#
+#   run              outgoing ramp              black frames   incoming decay
+#   1 (fadecap2)     67-70: 63,127,191,255      70,71,72 = 3   73-77
+#   2 (fadecap4)     64-67: 63,127,191,255      67,68,69 = 3   70-74
+#   3 (m2e)          92-95: 63,127,191,255      95,96,97 = 3   98-103
+#
+# ✅ THREE INDEPENDENT RUNS, gap = 3 frames every time, and the outgoing ramp is
+# byte-identical in all three (63, 127, 191, 255 -- steps of exactly 64). That
+# strengthens "the black gap is not a load" from two replicates to three, and the
+# ramp's exactness across runs makes the 4-frame outgoing duration as solid as
+# anything measured here.
+#
+# 🟡 STILL OPEN: menu -> EXTRAS, the reverse of the pair measured at a 2-frame
+# gap. The instrument is fixed (WHERE=menu2extras now reaches its branch) and the
+# run has not been taken.
+
+################################################################################
+# FIFTH TRANSITION: menu -> EXTRAS via (A). 2026-08-30.
+# The reverse of the pair already measured at a 2-frame gap, taken to test whether
+# the black gap is a property of the screen PAIR or of the DIRECTION.
+#
+# Navigation verified both ways before arming: extras margin 11.23, back on the
+# menu margin 11.60, against the discriminator's 9.9-11.7 control band. And the
+# run announced its effective configuration -- "branch taken = menu2extras: back
+# on the MENU with focus restored -> press (A)" -- which is the guard added after
+# the previous run silently took the wrong branch.
+#
+#   frames 42-46  outgoing quad 51, 102, 153, [45 absent], 255  -- 5 frames,
+#                 matching build 5's declared close of 10 units = 5 frames
+#   frame  49     EMPTY: 3 draws, 0 textured
+#   frames 51+    EXTRAS building
+#
+# ⚠️ Frames 48 and 50 carry no `--- frame` header at all, so the gap is ONE logged
+# empty frame with two unlogged neighbours. Quoted as 1, not silently rounded to 3.
+#
+################################################################################
+# ALL FIVE, ORDERED BY OUTGOING SCREEN -- which is the first thing that orders them
+#
+#   transition              black gap   outgoing         outgoing close (disc)
+#   menu -> title    (B)    0           menu (build 5)   10 units = 5 frames
+#   menu -> EXTRAS   (A)    1           menu (build 5)   10 units = 5 frames
+#   EXTRAS -> menu   (B)    2           EXTRAS (build 6) 10 units = 5 frames
+#   title -> menu    (A) x3 3, 3, 3     title (build 4)    8 units = 4 frames
+#
+# 🟡 THE GAP TRACKS THE OUTGOING SCREEN, not the direction and not the button: the
+# two transitions leaving the MENU give 0 and 1, the one leaving EXTRAS gives 2,
+# and the three leaving the TITLE give 3 every time. Direction is ruled out --
+# EXTRAS->menu (2) and menu->EXTRAS (1) are the same pair in both directions and
+# differ; button is ruled out -- (B) gives 0 and 2, (A) gives 1 and 3.
+#
+# 🔴 BUT THAT IS NOT YET A RULE. With three outgoing screens and one value each
+# (bar the title's three), "each outgoing screen has its own gap" only restates
+# the data; a rule would PREDICT. And nothing declared does: the outgoing close is
+# 5, 5, 5, 4 frames against gaps 0/1, 2, 3 -- if anything inverted, on three
+# points. Recorded as a narrowing of WHERE to look, not as a rule.
+
+################################################################################
+# SIXTH TRANSITION: menu -> a screen OUTSIDE GP_TITLE, via (A). 2026-08-30.
+#
+# Taken because sylpheed-port's BLOCKED row asks for a SECOND VALUE ON ONE
+# OUTGOING SCREEN -- the thing that would make "the gap tracks the outgoing
+# screen" predictive rather than a restatement. ⚠️ The menu is the only screen in
+# GP_TITLE that can supply it: the title's sole exit is (A) to the menu and
+# EXTRAS's sole exit is (B) to the menu, so neither has a second destination.
+#
+# ⚠️ CONFOUND NAMED IN ADVANCE, before the result was seen: this transition leaves
+# the ARCHIVE, so a pak load could inflate the gap for reasons having nothing to
+# do with the outgoing screen.
+#
+#   frames  4-21   menu settled ([64] = pteff02.prm)
+#   frames 24-28   outgoing quad 25, 127, 255 -- 4-5 frames, matching build 5's
+#                  declared close of 10 units = 5 frames
+#   frame  30      EMPTY: 3 draws, 0 textured
+#   frames 32+     the new screen builds ([127] primitive, not the menu's [64])
+#
+# ✅ GAP = 1, the same as menu -> EXTRAS. So the confound is MEASURED ABSENT:
+# leaving the archive costs no extra black. That is worth having on its own.
+#
+################################################################################
+# SIX TRANSITIONS, GROUPED BY OUTGOING SCREEN
+#
+#   outgoing screen      gaps            n
+#   menu   (build 5)     0, 1, 1         3   -> title, -> EXTRAS, -> another archive
+#   EXTRAS (build 6)     2               1   -> menu
+#   title  (build 4)     3, 3, 3         3   -> menu (three runs)
+#
+# 🟡 The ordering menu {0,1} < EXTRAS {2} < title {3} now rests on 3 + 1 + 3
+# measurements rather than 2 + 1 + 3, and the menu's three values agree to within
+# ONE frame across three different destinations, one of them in another pak.
+#
+# 🔴 Still not predictive. Nothing declared separates 0/1 from 2 from 3: the
+# outgoing closes are 5, 5, 4 frames for menu, EXTRAS, title against gaps of
+# {0,1}, {2}, {3}. And EXTRAS still has n=1 with no way to get a second value.
+
+################################################################################
+# SEVENTH TRANSITION: EXTRAS -> a screen outside GP_TITLE, via (A). 2026-08-30.
+#
+# 🔴 Taken because my own claim that EXTRAS had a SOLE EXIT was wrong. I recorded
+# its n=1 as STRUCTURAL; the disc refutes that -- build 6 declares three buttons,
+# ptbtn11/ptbtn12/ptbtn13, all kind 0x3002. The cap was an unverified assertion.
+#
+#   frames 28-35   EXTRAS settled ([64]); textured content fades 31-35
+#   frames 36-40   outgoing quad 25, 178, 229, 255 -- 4-5 frames, matching
+#                  build 6's declared close of 10 units = 5 frames
+#   frames 42,43,44  EMPTY: 3 draws, 0 textured  -- THREE frames
+#   frames 45+     a different archive builds (23-28 draws/frame against
+#                  GP_TITLE's 11-14)
+#
+# ✅ GAP = 3. So EXTRAS as outgoing screen gives {2, 3}.
+#
+################################################################################
+# SEVEN TRANSITIONS, BY OUTGOING SCREEN
+#
+#   outgoing            gaps        n   destinations
+#   menu   (build 5)    0, 1, 1     3   title, EXTRAS, another archive
+#   EXTRAS (build 6)    2, 3        2   menu, another archive
+#   title  (build 4)    3, 3, 3     3   menu x3
+#
+# 📌 A PAIRWISE CONTROL that holds the destination class constant: menu -> another
+# archive gives 1, EXTRAS -> another archive gives 3. Same kind of destination,
+# gap differs by the outgoing screen. That is the strongest support yet for the
+# outgoing-screen dependence, because it removes the destination as the variable.
+#
+# 🔴 BUT THE CLEAN ORDERING IS GONE. EXTRAS {2,3} and title {3,3,3} now OVERLAP at
+# 3, so "menu < EXTRAS < title" no longer separates them. What survives is weaker:
+# the outgoing screen constrains the gap to a 2-wide band, and different outgoing
+# screens have different bands that are not disjoint. Still not predictive, and
+# now not even cleanly ordered.
+
+################################################################################
+# EIGHTH TRANSITION: a SECOND EXTRAS -> menu, via (B). 2026-08-30.
+# Taken to verify the fixed effective-config guard on the one screen screen_id.py
+# cannot resolve, and to replicate the table's weakest cell at the same time.
+#
+# ✅ THE GUARD WORKS, verified in a run rather than asserted:
+#     arming on       = menu  [screen_id: cannot separate menu/EXTRAS]
+#     discriminator   = extras  rmse=18.94  (other main_menu 30.09, margin 11.15)
+#   Before the fix this run would have announced "arming on = menu" while armed on
+#   EXTRAS. The ambiguity is now visible instead of hidden.
+#
+#   frames 29-31   outgoing quad 229, 255, 255
+#   frames 32, 33  EMPTY: 3 draws, 0 textured
+#   frames 34-38   incoming menu's quad decaying 169, 148, 106, 63, 21
+#   GAP = 2, identical to the first EXTRAS -> menu.
+#
+################################################################################
+# 📌 EIGHT TRANSITIONS: THE GAP IS A PROPERTY OF THE ORDERED PAIR, NOT THE ORIGIN
+#
+#   transition        gaps       n   repeats agree?
+#   title  -> menu    3, 3, 3    3   YES
+#   EXTRAS -> menu    2, 2       2   YES
+#   menu   -> title   0          1   -
+#   menu   -> EXTRAS  1          1   -
+#   menu   -> other   1          1   -
+#   EXTRAS -> other   3          1   -
+#
+# EVERY repeated pair is identical -- 3/3 and 2/2, five replicates, no variation.
+# EVERY differing value comes from a DIFFERENT pair. And the same origin gives
+# different values to different destinations: menu 0 vs 1, EXTRAS 2 vs 3.
+#
+# 🔴 So "the outgoing screen determines the gap" is superseded a second time. The
+# origin CONSTRAINS it (menu {0,1}, EXTRAS {2,3}, title {3}); the ORDERED PAIR
+# determines it, reproducibly. Still nothing declared predicts which value a pair
+# gets, so this remains a description with five replicates behind it rather than a
+# rule.
+
+################################################################################
+# NINTH TRANSITION: menu -> a SECOND screen outside GP_TITLE, via (A). 2026-08-30.
+#
+# Taken because the ordered-pair claim needs a second distinct destination from
+# the SAME origin -- data, not a fit. sylpheed-port checked "nothing declared
+# predicts the gap" independently and confirmed it, and DECLINED to search
+# combinations on the grounds that four pairs against many candidate two-screen
+# functions fits by construction. This adds a pair instead.
+#
+# ⚠️ The button is not controlled -- there is no focus readout -- so the
+# destination is IDENTIFIED AFTERWARDS by its draw signature:
+#     menu -> other (1st):  incoming primitive [127],  12-13 draws/frame
+#     menu -> other (2nd):  incoming primitive [255],   7-9  draws/frame
+#   Different screens.
+#
+#   frames 21-34   menu settled ([64]); textured content fades 32-34
+#   frames 37-42   outgoing quad 25, 51, 102, 229, 255
+#   frame  44      the new screen is ALREADY drawing -- [255] plus textured
+#                  content. NO empty frame anywhere.
+#
+# ✅ GAP = 0.
+#
+################################################################################
+# NINE TRANSITIONS. The menu as origin now gives FOUR values across FOUR
+# destinations: title 0, EXTRAS 1, other-1 1, other-2 0.
+#
+# 📌 That is further evidence for the ordered pair over the origin: the same
+# origin gives both 0 and 1 depending on where it goes, and the two repeated pairs
+# remain internally identical (3,3,3 and 2,2).
+#
+# 🟡 AN OBSERVATION, EXPLICITLY NOT A RULE. The incoming screen's own full-screen
+# primitive differs between the two "other" destinations: [255] where the gap is 0,
+# [127] where it is 1. A screen that begins from opaque black would not need a
+# blank frame, since its own backdrop covers it -- which is a tempting mechanism
+# and it FAILS on menu -> EXTRAS: EXTRAS declares a black backdrop
+# (ui-forced-backdrop.md, 12 of 16) and still gives 1.
+# 🔴 So it is recorded as an observation with its counter-example, not fitted. Nine
+# transitions against many candidate two-screen functions is the same construction
+# sylpheed-port declined to search, and their reason applies unchanged to me.
+
+################################################################################
+# CAN THE TWO "other" DESTINATIONS BE NAMED? Attempted 2026-08-30, FAILED.
+#
+# sylpheed-port's caveat on the ninth pair: the destination identification is
+# after the fact by draw signature, which establishes THAT the two screens differ
+# ([255] at 7-9 draws/frame against [127] at 12-13) but not WHICH screen either
+# is. The gap value is attributed to a pair whose second member is known only as
+# "not the other one". Correct, and worth trying to remove.
+#
+# Both runs saved a screenshot of the destination. Scored against the archives the
+# menu's non-EXTRAS buttons plausibly lead to:
+#
+#   m2o   GP_OPTIONS 43.30  GP_MISSION_SELECT 49.18  GP_SYSTEM 54.64
+#         GP_SAVE_LOAD 54.79  GP_TUTORIAL 55.56        -> best margin 5.88
+#   m2o2  GP_SYSTEM 45.74  GP_MISSION_SELECT 48.02  GP_OPTIONS 49.44
+#         GP_TUTORIAL 56.54  GP_SAVE_LOAD 57.00       -> best margin 2.28
+#
+# 🔴 REJECTED, against this corpus's own calibration. which_title_screen.py's
+# control puts a TRUE match at RMSE ~18-20 with a margin of ~10, and a "neither"
+# at ~34 with a margin under 1. These best fits are 43 and 46 -- roughly double a
+# real match -- with margins of 5.88 and 2.28. Accepting "m2o is GP_OPTIONS" on
+# 5.88 would be the same weak-margin acceptance a threshold was added to the
+# navigation search to prevent, three iterations ago.
+#
+# ⚠️ Reach of the negative: one build per archive was rendered (the default, which
+# is the largest), and the screen a button opens need not be the largest build.
+# So this does not refute those archives -- it fails to identify, which is
+# different. The port's caveat stands and the ninth pair keeps it.

docs/re/data/fallback-fabrication-sweep.txt

@@ -0,0 +1,100 @@
+# Fallbacks that could FABRICATE a quantity, in sylpheed-formats + sylpheed-cli.
+# 2026-08-30. The mirror of sylpheed-port's sweep of their own tree.
+#
+# 112 fallback sites (unwrap_or / unwrap_or_else / unwrap_or_default /
+# serde(default)). 64 supply 0, false, empty or Default -- sentinels that assert
+# nothing. Of the 48 remaining, most are pass-through (unwrap_or(s),
+# unwrap_or(name)) or an extent (unwrap_or(bytes.len())), which are identity.
+#
+# POSITIVE CONTROL: the filter found media.rs:314 unwrap_or(anchor) -- the
+# voice-region start fallback landed earlier this session -- so the detector
+# finds a known case rather than only reporting absence.
+#
+# mesh.rs 1077/1084/1099/1106/1139/1177 (1.0, 0.85, 1, 0.5, 0.70, 0.45) are
+# env-var tunables (XBG7_EDGE_CAP etc.) with defaults documented in
+# structures/xbg7-mesh.md. Knobs, not measurements. Out of the menu lane.
+#
+## ui_layout.rs -- the crate the port PINS. 8 sites; 6 sentinel or pass-through;
+## 2 could fabricate a quantity:
+#
+#   :695   unwrap_or((DESIGN_W, DESIGN_H))  -> MEASURED BELOW: never fires
+#   :1681  kf.time.unwrap_or(0)             -> unreachable today; note below
+#
+## Does the design-size fallback ever fire? Disc-wide.
+## instrument: examples/design_size_fallback.rs
+## CONTROL: it must reproduce screen list's 1280x720 for every build.
+##   A first version read EVERY RATC child and FAILED that control -- it
+##   reported all 965 builds stating a non-standard size (GP_TUTORIAL 12x3),
+##   because a T8aD sprite header read at +0x18 is garbage that passes the
+##   range test. Filtered to the .rat records, the control passes.
+#
+GP_BUNK.pak                        8 read       0 FABRICATED
+GP_CHALLENGE.pak                  78 read       0 FABRICATED
+GP_DEBRIEFING_PILOTLOG.pak        18 read       0 FABRICATED
+GP_DIALOG.pak                    105 read       0 FABRICATED
+GP_GAMEOVER.pak                   10 read       0 FABRICATED
+GP_HANGAR_ARSENAL.pak            390 read       0 FABRICATED
+GP_LEADERBOARD.pak                 4 read       0 FABRICATED
+GP_MAIN_GAME_D2D.pak              18 read       0 FABRICATED
+GP_MAIN_GAME_E2D.pak              18 read       0 FABRICATED
+GP_MAIN_GAME_F2D.pak              18 read       0 FABRICATED
+GP_MAIN_GAME_I2D.pak              18 read       0 FABRICATED
+GP_MAIN_GAME_J2D.pak              18 read       0 FABRICATED
+GP_MAIN_GAME_S2D.pak              18 read       0 FABRICATED
+GP_MISSION_LOG.pak                 4 read       0 FABRICATED
+GP_MISSION_SELECT.pak             66 read       0 FABRICATED
+GP_MOVIE_THEATER.pak              56 read       0 FABRICATED
+GP_OPTIONS.pak                    14 read       0 FABRICATED
+GP_PAUSE_MENU.pak                  6 read       0 FABRICATED
+GP_READY_ROOM.pak                 60 read       0 FABRICATED
+GP_SAVE_LOAD.pak                  18 read       0 FABRICATED
+GP_STAGE_CLEAR.pak                 4 read       0 FABRICATED
+GP_SYSTEM.pak                      2 read       0 FABRICATED
+GP_TITLE.pak                      12 read       0 FABRICATED
+GP_TUTORIAL.pak                    2 read       0 FABRICATED
+965 builds state a design size, 0 get the 1280x720 FALLBACK
+0 builds state something other than 1280x720
+
+# So design_w/design_h is READ, not fabricated: 965 of 965 builds state it
+# explicitly and every one states 1280x720. The port can rely on it.
+#
+# The remaining site, ui_layout.rs:1681, serialises kf.time.unwrap_or(0) when
+# writing a bundle back. `time` is still Option<u32> (line 130). Under the
+# corrected record layout every pose is timed, so this cannot fire today -- the
+# same status as the port's exit_ramp_units branch. What makes it worse than
+# theirs if it ever did: their fabricated value was 24.0, a conspicuous magic
+# number. Mine is 0, which is a LEGITIMATE keyframe time -- pose 0's time really
+# is 0 -- so a fabricated one would be indistinguishable from a real one in any
+# output. An in-range fallback cannot be caught downstream.
+
+################################################################################
+# COUNTED, not inspected -- 2026-08-30, after sylpheed-port pointed out that
+# classifying defaults "by inspection" is exactly the method that cannot see an
+# in-range fallback. That correction applies to this file's own first pass: 64
+# sites were waved through as sentinels by reading them.
+# instrument: examples/inrange_fallback_count.rs
+#
+#   965 builds, 24 811 keyframes
+#   :1681  untimed poses (fallback would fabricate t=0):            0
+#   :1010  pose_at queries 168 264, of which None (reads a=0):      0
+#
+# ⚠️ Two zeroes, which is the result this corpus distrusts most. So the detector
+# was made to prove it can see a hit -- ask pose_at for a time no build declares:
+#
+#   CONTROL  10 906 out-of-range queries, 0 None      <-- THE CONTROL FAILED
+#
+# The detector was BLIND, and the :1010 zero meant nothing. The failure is the
+# finding: pose_at is TOTAL. Reading the source, its only None path is an
+# `if ks.is_empty() { return None }` guard at line 217 -- and disc-wide there are
+# 0 elements with zero keyframes out of 5 453. So :1010's unwrap_or(0) is
+# unreachable by CONSTRUCTION, which is stronger than "0 in this corpus", and it
+# was established by the control failing rather than by the count passing.
+#
+# :1681 stands on a different footing: 0 of 24 811, and `time` really is
+# Option<u32>, with the STALE reader demonstrably producing None (its `screen
+# info` prints a trailing `-`). So the state is representable and a detector
+# would see it; the corrected reader simply never produces one.
+#
+# :973's unwrap_or(0) is NOT a hazard: it is guarded two lines later by
+# `if tmax == 0 { return false; }`. Read, not counted, and that is sufficient
+# because the guard is the proof.

docs/re/data/focus-record-alpha-census.txt

@@ -0,0 +1,226 @@
+focus records disc-wide          : 1130
+  their timed elements           : 2664
+  with a VARYING alpha           : 210
+    of which rest() == the PEAK  : 202   <- burns bright forever
+    of which rest() is MID-RAMP  : 8   <- neither extreme; looks plausible
+
+by pak:
+  GP_DEBRIEFING_PILOTLOG.pak         116
+  GP_HANGAR_ARSENAL.pak              30
+  GP_LEADERBOARD.pak                 8
+  GP_MOVIE_THEATER.pak               54
+  GP_TITLE.pak                       2
+
+every varying one:
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn01f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn02f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn03f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn04f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn05f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn06f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn07f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn08f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn09f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn10f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn11f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn12f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn13f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn14f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn15f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn16f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn17f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn18f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn19f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn20f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn21f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn22f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn23f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [10] pp_order_btn24f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn01f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn02f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn03f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn04f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn05f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn06f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn07f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn08f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn09f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn10f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn11f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn12f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn13f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn14f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn15f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn16f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn17f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn18f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn19f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn20f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn21f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn22f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn23f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [11] pp_order_btn24f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [136] pl_main_btn0f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [136] pl_main_btn1f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [136] pl_main_btn2f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [136] pl_main_btn3f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [166] pl_main_btn0f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [166] pl_main_btn1f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [166] pl_main_btn2f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [166] pl_main_btn3f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [22] pl_main_btn0f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [22] pl_main_btn1f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [22] pl_main_btn2f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [22] pl_main_btn3f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [24] pl_main_btn0f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [24] pl_main_btn1f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn01f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn02f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn03f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn04f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn05f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn06f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn07f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn08f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn09f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn10f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn11f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn12f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn13f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn14f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn15f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn16f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn17f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn18f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn19f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn20f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn21f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn22f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn23f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [3] pp_order_btn24f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [43] pl_main_btn0f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [43] pl_main_btn1f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [43] pl_main_btn2f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [43] pl_main_btn3f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [53] pl_main_btn0f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [53] pl_main_btn1f.rat::pl_main_eff06.t32  alpha 0..128  rest()=128  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn01f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn02f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn03f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn04f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn05f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn06f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn07f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn08f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn09f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn10f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn11f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn12f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn13f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn14f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn15f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn16f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn17f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn18f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn19f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn20f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn21f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn22f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn23f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_DEBRIEFING_PILOTLOG.pak [5] pp_order_btn24f.rat::pp_order_btn_f.t32  alpha 0..212  rest()=212  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [129] psbtn2f.rat::pspylon_nose.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [129] psbtn3f.rat::pspylon_main2.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [129] psbtn4f.rat::pspylon_main3.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [129] psbtn5f.rat::pspylon_main1.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [167] psbtn2f.rat::pspylon_nose.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [167] psbtn3f.rat::pspylon_main2.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [167] psbtn4f.rat::pspylon_main3.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [167] psbtn5f.rat::pspylon_main1.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [239] psbtn2f.rat::pspylon_nose.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [239] psbtn3f.rat::pspylon_main2.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [239] psbtn4f.rat::pspylon_main3.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [239] psbtn5f.rat::pspylon_main1.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [24] psselect_slotf.rat::psselect_slotf_eff1.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [253] psbtn2f.rat::pspylon_nose.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [253] psbtn3f.rat::pspylon_main2.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [253] psbtn4f.rat::pspylon_main3.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [253] psbtn5f.rat::pspylon_main1.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [31] psselect_slotf.rat::psselect_slotf_eff1.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [42] psselect_slotf.rat::psselect_slotf_eff1.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [43] psselect_slotf.rat::psselect_slotf_eff1.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [455] psbtn2f.rat::pspylon_nose.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [455] psbtn3f.rat::pspylon_main2.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [455] psbtn4f.rat::pspylon_main3.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [455] psbtn5f.rat::pspylon_main1.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [458] psbtn2f.rat::pspylon_nose.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [458] psbtn3f.rat::pspylon_main2.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [458] psbtn4f.rat::pspylon_main3.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [458] psbtn5f.rat::pspylon_main1.t32  alpha 64..192  rest()=192  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [60] psselect_slotf.rat::psselect_slotf_eff1.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_HANGAR_ARSENAL.pak [61] psselect_slotf.rat::psselect_slotf_eff1.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_LEADERBOARD.pak [11] py_ranking_btn01f.rat::py_ranking_btn01f.t32  alpha 127..255  rest()=244
+  GP_LEADERBOARD.pak [11] py_ranking_btn02f.rat::py_ranking_btn02f.t32  alpha 127..255  rest()=244
+  GP_LEADERBOARD.pak [11] py_ranking_btn03f.rat::py_ranking_btn03f.t32  alpha 127..255  rest()=244
+  GP_LEADERBOARD.pak [11] py_ranking_btn04f.rat::py_ranking_btn04f.t32  alpha 127..255  rest()=244
+  GP_LEADERBOARD.pak [6] py_ranking_btn01f.rat::py_ranking_btn01f.t32  alpha 127..255  rest()=244
+  GP_LEADERBOARD.pak [6] py_ranking_btn02f.rat::py_ranking_btn02f.t32  alpha 127..255  rest()=244
+  GP_LEADERBOARD.pak [6] py_ranking_btn03f.rat::py_ranking_btn03f.t32  alpha 127..255  rest()=244
+  GP_LEADERBOARD.pak [6] py_ranking_btn04f.rat::py_ranking_btn04f.t32  alpha 127..255  rest()=244
+  GP_MOVIE_THEATER.pak [10] px_movie_tn030f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [11] px_movie_tn130f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [12] px_movie_tn040f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [13] px_movie_tn022f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [14] px_movie_tn121f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [15] px_movie_tn131f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [16] px_movie_tn041f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [17] px_movie_tn140f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [18] px_movie_tn050f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [19] px_movie_tn122f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [20] px_movie_tn150f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [21] px_movie_tn060f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [22] px_movie_tn151f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [23] px_movie_tn061f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [24] px_movie_tn160f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [25] px_movie_tn070f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [26] px_movie_tn152f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [27] px_movie_tn071f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [28] px_movie_tn090f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [29] px_movie_tn000f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [2] px_movie_tn000f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [30] px_movie_tn100f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [31] px_movie_tn010f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [32] px_movie_tn110f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [33] px_movie_tn020f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [34] px_movie_tn111f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [35] px_movie_tn021f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [36] px_movie_tn120f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [37] px_movie_tn030f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [38] px_movie_tn130f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [39] px_movie_tn040f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [3] px_movie_tn100f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [40] px_movie_tn022f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [41] px_movie_tn121f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [42] px_movie_tn131f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [43] px_movie_tn041f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [44] px_movie_tn140f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [45] px_movie_tn050f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [46] px_movie_tn122f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [47] px_movie_tn150f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [48] px_movie_tn060f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [49] px_movie_tn151f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [4] px_movie_tn010f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [50] px_movie_tn061f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [51] px_movie_tn160f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [52] px_movie_tn070f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [53] px_movie_tn152f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [54] px_movie_tn071f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [55] px_movie_tn090f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [5] px_movie_tn110f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [6] px_movie_tn020f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [7] px_movie_tn111f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [8] px_movie_tn021f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_MOVIE_THEATER.pak [9] px_movie_tn120f.rat::px_movie_btnf.t32  alpha 64..255  rest()=255  🔴 == PEAK
+  GP_TITLE.pak [2] ptbtn00f.rat::ptbtn00f.t32  alpha 0..80  rest()=80  🔴 == PEAK
+  GP_TITLE.pak [3] ptbtn00f.rat::ptbtn00f.t32  alpha 0..80  rest()=80  🔴 == PEAK
+
+(210 distinct)