re(ui): the focus ring SPINS, the game draws it, and the leaf owns the f record

Three things, all from parsing ptbtn0Nf.rat as a build.

1. THE RING SPINS. Its two keyframes differ in exactly one field: rotation_deg
ramps 0 -> 360 with position, scale, alpha and tint all constant. A spin in
place, the same shape as the GP_BUNK example already recorded.

2. THE ORACLE CONFIRMS THE GAME RENDERS IT. In the OPTIONS-focused capture the
ring's bright head sits in a completely different angular position from the
sprite's own -- caught mid-spin. This is a SECOND independent confirmation that
rotation_deg is drawn, now on a different screen and a different element from the
ptloop sweeps, and it raises rotation's priority: it is not a title-only concern
that sits off-screen at rest, it is the main menu's focus marker.
NO ANGLE IS QUOTED. A brightest-region centroid says ~250 deg, but the control
refuses that precision -- rotating the sprite by a known 30/90/180/270 and
re-measuring gives errors up to 19.8 deg. What survives the error bar is that a
<=20 deg error cannot manufacture a ~250 deg displacement.

3. WHICH PLACEMENT WINS -- correcting this page's own earlier caveat, which said
to use the leaf only for elements the parent does not declare. Right for a BASE
record, wrong for an f record: the parent declares NO element for ptbtn0Nf.rat at
all (zero of build 5's 16), so the f record's placement comes from its leaf for
BOTH elements, label included. The label's (-7,-7) is load-bearing -- the f
sprite is 13px larger per axis and -7 keeps them concentric (535+96/2 = 583 vs
542+83/2 = 583.5). Corroborated against the oracle: the focused-minus-unfocused
region is x 505..703, and the leaf predicts a right edge near 707 where the
parent reading predicts 714.

Also exposes UiBuild::records (name -> (offset, size) of a nested .rat leaf).
Nested records were parsed into a PRIVATE map, so a consumer holding a UiBuild
could not locate a leaf's bytes at all -- which is exactly what blocked the port
from reaching the ring.

crates/sylpheed-cli/src/main.rs

@@ -103,6 +103,120 @@ enum Commands {
         #[command(subcommand)]
         cmd: MeshCommands,
     },
+
+    /// Audio tools (identify WAV/XMA/XMA2 + metadata)
+    Audio {
+        #[command(subcommand)]
+        cmd: AudioCommands,
+    },
+
+    /// UI screen tools — reassemble a screen from its RATC bundle
+    Screen {
+        #[command(subcommand)]
+        cmd: ScreenCommands,
+    },
+
+    /// Save file (`savedata`) tools
+    Save {
+        #[command(subcommand)]
+        cmd: SaveCommands,
+    },
+}
+
+#[derive(Subcommand)]
+enum ScreenCommands {
+    /// List the screen builds in a UI pak, with their element counts
+    List {
+        /// Path to a `GP_*.pak`
+        pak: PathBuf,
+        /// Widen the list from screen builds to **every composable bundle** —
+        /// including the ones with no `.rat` layout child, such as the
+        /// developer-logo splash. 2 859 RATC bundles on the disc compose; only
+        /// 965 are screen builds, and the rest are mostly two-element fragments
+        /// (a button and its glow), so this is off by default. **It renumbers
+        /// `--build`**, which is why it is a flag and not the default.
+        #[arg(long)]
+        all: bool,
+    },
+    /// Print one build's element declaration table and resting placements
+    Info {
+        /// Path to a `GP_*.pak`
+        pak: PathBuf,
+        /// Which build (index into `screen list`); default = the largest
+        #[arg(long)]
+        build: Option<usize>,
+        /// Widen the list from screen builds to **every composable bundle** —
+        /// including the ones with no `.rat` layout child, such as the
+        /// developer-logo splash. 2 859 RATC bundles on the disc compose; only
+        /// 965 are screen builds, and the rest are mostly two-element fragments
+        /// (a button and its glow), so this is off by default. **It renumbers
+        /// `--build`**, which is why it is a flag and not the default.
+        #[arg(long)]
+        all: bool,
+
+        /// Also print the bundle's other orderings and, per element, the decoded
+        /// sprite size beside the declared pivot and every keyframe's
+        /// scale/position/time — what a placement or paint-order hypothesis has
+        /// to be tested against.
+        #[arg(long)]
+        geometry: bool,
+    },
+    /// Composite one build to a PNG — the headless self-verify for the viewer
+    Render {
+        /// Path to a `GP_*.pak`
+        pak: PathBuf,
+        /// Output PNG
+        output: PathBuf,
+        /// Which build (index into `screen list`); default = the largest
+        #[arg(long)]
+        build: Option<usize>,
+        /// Draw the focused-state (`*f`) records over their base elements
+        #[arg(long)]
+        focus: bool,
+        /// Draw `loop*` sprite animations
+        #[arg(long)]
+        animated: bool,
+        /// Start the canvas black instead of the default dim slate — what the
+        /// game composites over on a screen carrying its own background, and so
+        /// what a framebuffer capture must be compared against.
+        #[arg(long)]
+        black: bool,
+        /// Draw the untextured `.prm` primitives (fade / dim / flash quads).
+        /// Off by default: they are decoded, but where they paint on a screen
+        /// without a measured order is unsolved — see
+        /// `docs/re/structures/ui-prm-primitives.md`.
+        #[arg(long)]
+        primitives: bool,
+        /// Widen the list from screen builds to **every composable bundle** —
+        /// including the ones with no `.rat` layout child, such as the
+        /// developer-logo splash. 2 859 RATC bundles on the disc compose; only
+        /// 965 are screen builds, and the rest are mostly two-element fragments
+        /// (a button and its glow), so this is off by default. **It renumbers
+        /// `--build`**, which is why it is a flag and not the default.
+        #[arg(long)]
+        all: bool,
+    },
+}
+
+#[derive(Subcommand)]
+enum SaveCommands {
+    /// Parse a `savedata` file and print every field with its confidence
+    Info {
+        /// Path to a `savedata` file
+        file: PathBuf,
+        /// Also print the still-unidentified fields
+        #[arg(long)]
+        all: bool,
+    },
+}
+
+#[derive(Subcommand)]
+enum AudioCommands {
+    /// Identify an audio file/stream and print its metadata
+    Info {
+        /// Path to a WAV / XMA / raw audio stream
+        file: PathBuf,
+    },
 }
 
 #[derive(Subcommand)]
@@ -219,9 +333,433 @@ async fn main() -> Result<()> {
                 cmd_pak_textures(&pak, &output, verbose)
             }
         },
+        Commands::Audio { cmd } => match cmd {
+            AudioCommands::Info { file } => cmd_audio_info(&file),
+        },
+        Commands::Screen { cmd } => match cmd {
+            ScreenCommands::List { pak, all } => cmd_screen_list(&pak, all),
+            ScreenCommands::Info {
+                pak,
+                build,
+                geometry,
+                all,
+            } => cmd_screen_info(&pak, build, geometry, all),
+            ScreenCommands::Render {
+                pak,
+                output,
+                build,
+                focus,
+                animated,
+                black,
+                all,
+                primitives,
+            } => cmd_screen_render(
+                &pak, &output, build, focus, animated, black, all, primitives,
+            ),
+        },
+        Commands::Save { cmd } => match cmd {
+            SaveCommands::Info { file, all } => cmd_save_info(&file, all),
+        },
     }
 }
 
+// ── UI screens ───────────────────────────────────────────────────────────────
+
+/// Every RATC entry of a UI pak that parses as a screen build, with its bytes.
+///
+/// `all` widens the filter from `is_build` — which requires a `.rat` layout
+/// child — to anything `compose` can draw. The developer-logo splash is the
+/// reason: it declares its sprites directly, has no `.rat` child at all, and so
+/// is invisible to every screen command without this. See
+/// `docs/re/structures/ui-composable-bundles.md`.
+fn screen_builds(pak: &Path, all: bool) -> Result<Vec<(usize, Vec<u8>)>> {
+    use sylpheed_formats::{pak::PakArchive, ui_layout};
+    let ar = PakArchive::open(pak).context("open pak")?;
+    let mut out = Vec::new();
+    for (i, e) in ar.entries().iter().enumerate() {
+        let Ok(bytes) = ar.read(e) else { continue };
+        let keep = if all {
+            ui_layout::is_composable(&bytes)
+        } else {
+            ui_layout::is_build(&bytes)
+        };
+        if keep {
+            out.push((i, bytes));
+        }
+    }
+    Ok(out)
+}
+
+/// Resolve `--build`: an explicit index into the build list, else the largest
+/// build (a screen pak's biggest bundle is the full screen; the small ones are
+/// language or context variants).
+fn pick_build(builds: &[(usize, Vec<u8>)], want: Option<usize>) -> Result<usize> {
+    if builds.is_empty() {
+        anyhow::bail!("no screen builds in this pak");
+    }
+    match want {
+        Some(i) if i < builds.len() => Ok(i),
+        Some(i) => anyhow::bail!("build {i} out of range (0..{})", builds.len()),
+        None => Ok(builds
+            .iter()
+            .enumerate()
+            .max_by_key(|(_, (_, b))| b.len())
+            .map(|(i, _)| i)
+            .unwrap()),
+    }
+}
+
+fn cmd_screen_list(pak: &Path, all: bool) -> Result<()> {
+    use sylpheed_formats::ui_layout;
+    let builds = screen_builds(pak, all)?;
+    println!("{} screen build(s) in {}", builds.len(), pak.display());
+    for (i, (entry, bytes)) in builds.iter().enumerate() {
+        match ui_layout::parse_build(bytes) {
+            Some(b) => println!(
+                "  [{i}] entry {entry:<3} {:>8} B  {}x{}  {} elements, {} sprites{}{}",
+                bytes.len(),
+                b.design_w,
+                b.design_h,
+                b.elements.len(),
+                b.sprites.len(),
+                b.context_hint
+                    .as_deref()
+                    .map(|c| format!("  context={c}"))
+                    .unwrap_or_default(),
+                if b.from_fallback { "  (fallback)" } else { "" },
+            ),
+            None => println!("  [{i}] entry {entry:<3} {:>8} B  (unparsed)", bytes.len()),
+        }
+    }
+    Ok(())
+}
+
+fn cmd_screen_info(pak: &Path, want: Option<usize>, geometry: bool, all: bool) -> Result<()> {
+    use sylpheed_formats::ui_layout;
+    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")?;
+    println!(
+        "build [{idx}]  {}x{}  {} elements  {} sprites{}",
+        b.design_w,
+        b.design_h,
+        b.elements.len(),
+        b.sprites.len(),
+        if b.from_fallback {
+            "  (recovered from .rat records — the declaration table was unusable)"
+        } else {
+            ""
+        }
+    );
+    println!(
+        "{:<3} {:<30} {:>7} {:>8} {:>12} {:>4}  rest / keyframes",
+        "#", "element", "parent", "kind", "pivot", "kf"
+    );
+    for el in &b.elements {
+        // The resting pose is the max-dwell keyframe, not the first or the last.
+        let rest = match el.rest() {
+            None => "—".to_string(),
+            Some(k) if el.keyframes.len() == 1 => format!("({},{})", k.x, k.y),
+            Some(k) => {
+                // The final frame of a group carries no time — print it as `-`
+                // rather than inventing one.
+                let t = |t: Option<u32>| t.map(|v| v.to_string()).unwrap_or_else(|| "-".into());
+                format!(
+                    "rest ({},{}) t={}  [{}]",
+                    k.x,
+                    k.y,
+                    t(k.time),
+                    el.keyframes
+                        .iter()
+                        .map(|f| format!("{}:{},{}", t(f.time), f.x, f.y))
+                        .collect::<Vec<_>>()
+                        .join(" ")
+                )
+            }
+        };
+        println!(
+            "{:<3} {:<30} {:>7} {:>8} {:>12} {:>4}  {rest}",
+            el.index,
+            el.name,
+            el.parent.map(|p| p.to_string()).unwrap_or_else(|| "-".into()),
+            format!("{:#x}", el.kind),
+            format!("({},{})", el.pivot_x, el.pivot_y),
+            el.keyframes.len(),
+        );
+        if let Some(link) = &el.focus_link {
+            println!("{:<3} {:<30} → focus {link}", "", "");
+        }
+    }
+    if geometry {
+        print_geometry(&b, bytes);
+    }
+    Ok(())
+}
+
+/// The two other orderings the bundle carries, and each element's real drawn
+/// size. Both were needed to settle the title screen's paint order — see
+/// `docs/re/BACKLOG.md`.
+fn print_geometry(b: &sylpheed_formats::ui_layout::UiBuild, bytes: &[u8]) {
+    println!();
+    let identity: Vec<usize> = (0..b.placement_order.len()).collect();
+    println!(
+        "placement-region group order: {:?}{}",
+        b.placement_order,
+        if b.placement_order == identity {
+            "  (== declaration order)"
+        } else {
+            "  (DIFFERS from declaration order)"
+        }
+    );
+    if let Some(kids) = sylpheed_formats::ratc::parse(bytes) {
+        println!(
+            "RATC child order: {:?}",
+            kids.iter()
+                .map(|c| format!("{}:{}", c.kind, c.name))
+                .collect::<Vec<_>>()
+        );
+    }
+    println!();
+    println!("geometry — decoded sprite size vs the declared pivot, and every keyframe");
+    println!(
+        "{:<3} {:<26} {:>11} {:>11} {:>5}  keyframes  t: x,y sx%,sy% a=alpha r=rot°",
+        "#", "sprite", "decoded", "pivot*2", "same"
+    );
+    for el in &b.elements {
+        let dims = el
+            .sprite
+            .as_ref()
+            .and_then(|s| b.sprites.get(s))
+            .and_then(|&(off, size)| sylpheed_formats::t8ad::parse(&bytes[off..off + size]))
+            .map(|img| (img.width, img.height));
+        let pv = (el.pivot_x * 2, el.pivot_y * 2);
+        let same = match dims {
+            Some(d) if d == pv => "yes",
+            Some(_) => "NO",
+            None => "-",
+        };
+        let kfs = el
+            .keyframes
+            .iter()
+            .map(|f| {
+                let rot = if f.rotation_deg != 0 {
+                    format!(" r={}", f.rotation_deg)
+                } else {
+                    String::new()
+                };
+                format!(
+                    "{}: {},{} {}%,{}% a={}{rot}",
+                    f.time.map(|v| v.to_string()).unwrap_or_else(|| "-".into()),
+                    f.x,
+                    f.y,
+                    f.scale_x,
+                    f.scale_y,
+                    (f.fade >> 24) & 0xff
+                )
+            })
+            .collect::<Vec<_>>()
+            .join("  ");
+        println!(
+            "{:<3} {:<26} {:>11} {:>11} {:>5}  {kfs}",
+            el.index,
+            el.sprite.as_deref().unwrap_or("—"),
+            dims.map(|(w, h)| format!("{w}x{h}"))
+                .unwrap_or_else(|| "—".into()),
+            format!("{}x{}", pv.0, pv.1),
+            same,
+        );
+    }
+}
+
+fn cmd_screen_render(
+    pak: &Path,
+    output: &Path,
+    want: Option<usize>,
+    focus: bool,
+    animated: bool,
+    black: bool,
+    all: bool,
+    primitives: 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 screen = ui_layout::compose(
+        &b,
+        bytes,
+        ComposeOptions {
+            include_focus: focus,
+            include_animated: animated,
+            backdrop: if black {
+                [0, 0, 0, 255]
+            } else {
+                ComposeOptions::default().backdrop
+            },
+            include_primitives: primitives,
+        },
+        None,
+    );
+    image::save_buffer(
+        output,
+        &screen.rgba,
+        screen.width,
+        screen.height,
+        image::ExtendedColorType::Rgba8,
+    )
+    .context("write PNG")?;
+    println!(
+        "build [{idx}]: drew {}/{} elements → {} ({}x{})",
+        screen.drawn.len(),
+        b.elements.len(),
+        output.display(),
+        screen.width,
+        screen.height
+    );
+    if !screen.missing.is_empty() {
+        println!("  sprites that did not resolve/decode: {:?}", screen.missing);
+    }
+    let undrawn: Vec<&str> = b
+        .elements
+        .iter()
+        .filter(|e| !screen.drawn.contains(&e.index))
+        .map(|e| e.name.as_str())
+        .collect();
+    if !undrawn.is_empty() {
+        println!("  not drawn ({}): {undrawn:?}", undrawn.len());
+    }
+    Ok(())
+}
+
+// ── save file ────────────────────────────────────────────────────────────────
+
+fn cmd_save_info(file: &Path, all: bool) -> Result<()> {
+    use sylpheed_formats::savegame::{
+        self, Confidence, DevelopState, FieldKind, GHAD_LAYOUT,
+    };
+    let raw = std::fs::read(file).context("read save")?;
+    let save = savegame::parse(&raw).map_err(|e| anyhow::anyhow!("{e}"))?;
+
+    let mark = |c: Confidence| match c {
+        Confidence::Confirmed => "OK ",
+        Confidence::Probable => "~  ",
+        Confidence::Unknown => "?  ",
+        Confidence::Refuted => "REF",
+    };
+
+    println!(
+        "container : GDHA, {} B header + {} B deflate → {} B payload",
+        save.header.bytes.len(),
+        raw.len() - save.header.bytes.len(),
+        save.payload.len()
+    );
+    println!(
+        "round-trip: {}",
+        if save.round_trips() {
+            "byte-identical"
+        } else {
+            "MISMATCH — the parse is wrong"
+        }
+    );
+    println!("phase     : {}", save.phase);
+    println!("\nGHAD progress block:");
+    for f in GHAD_LAYOUT {
+        if !all && f.confidence == Confidence::Unknown && f.name.is_empty() {
+            continue;
+        }
+        let value = match f.kind {
+            FieldKind::Millis => save
+                .ghad_value(f)
+                .map(|v| format!("{v} ms ({})", savegame::fmt_millis(v as u32))),
+            FieldKind::Percent => save.ghad_value(f).map(|v| format!("{v} %")),
+            FieldKind::Raw | FieldKind::DevelopBlob => Some(
+                save.ghad_bytes(f)
+                    .iter()
+                    .map(|b| format!("{b:02x}"))
+                    .collect::<Vec<_>>()
+                    .join(" "),
+            ),
+            _ => save.ghad_value(f).map(|v| format!("{v}")),
+        }
+        .unwrap_or_else(|| "-".into());
+        println!(
+            "  {} +{:<3} {:<14} {}",
+            mark(f.confidence),
+            f.offset,
+            if f.name.is_empty() { "(unnamed)" } else { f.name },
+            value
+        );
+        if all && !f.note.is_empty() {
+            println!("           {}", f.note);
+        }
+    }
+
+    let dev = save.develop_state();
+    let owned = dev.iter().filter(|d| **d == DevelopState::Developed).count();
+    let ready = dev
+        .iter()
+        .filter(|d| **d == DevelopState::Developable)
+        .count();
+    println!(
+        "\nArsenal   : {owned} developed, {ready} developable, {} locked (of {})",
+        dev.len() - owned - ready,
+        dev.len()
+    );
+
+    println!("\nper-stage records (SHAB — NOT the UI's save slots):");
+    for (i, r) in save.records.iter().enumerate() {
+        if !r.is_used() {
+            continue;
+        }
+        println!(
+            "  stage {:02}  difficulty~{}  points?{}  best {}  ",
+            i + 1,
+            r.a,
+            r.b,
+            savegame::fmt_millis(r.best_time_ms)
+        );
+    }
+
+    println!("\nheader summary (what the in-game Details panel reads):");
+    for m in save.header.summary() {
+        println!("  +{:#04x} {:<14} {}", m.header_offset, m.name, m.value);
+    }
+    println!("  — a payload edit that leaves these stale shows no change on the panel,");
+    println!("    which is not evidence that the payload field was the wrong one.");
+    Ok(())
+}
+
+// ── audio info ───────────────────────────────────────────────────────────────
+
+fn cmd_audio_info(file: &Path) -> Result<()> {
+    use sylpheed_formats::AudioInfo;
+    let bytes = std::fs::read(file).with_context(|| format!("Cannot read {}", file.display()))?;
+    let info = AudioInfo::probe(&bytes);
+
+    println!("{} {}", "Audio:".green().bold(), file.display());
+    println!("  Codec      : {}", info.codec.label().yellow());
+    let opt = |v: Option<String>| v.unwrap_or_else(|| "—".dimmed().to_string());
+    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(d) = info.duration_secs {
+        println!("  Duration   : {d:.2} s");
+    }
+    if let Some(p) = info.xma_packets {
+        println!("  XMA packets: {} (2048 B each)", p.to_string().yellow());
+    }
+    println!("  Size       : {} bytes", info.size_bytes.to_string().yellow());
+    if info.codec.needs_decoder() {
+        println!(
+            "  {} decode not supported (needs an XMA2 decoder + the sound-bank descriptor)",
+            "note:".dimmed()
+        );
+    }
+    Ok(())
+}
+
 // ── extract ────────────────────────────────────────────────────────────────
 
 async fn cmd_extract(iso_path: &Path, output_dir: &Path) -> Result<()> {
@@ -376,9 +914,16 @@ fn cmd_texture_info(file: &Path) -> Result<()> {
     let tex = X360Texture::from_xpr2(&bytes)
         .with_context(|| format!("Failed to parse texture: {}", file.display()))?;
 
+    let d = tex.format.desc();
     println!("{} {}", "Texture:".green().bold(), file.display());
     println!("  Resolution : {}×{}", tex.width.to_string().yellow(), tex.height.to_string().yellow());
-    println!("  Format     : {:?}", tex.format);
+    println!(
+        "  Format     : {} ({:?})  ·  {} bpp, {}",
+        tex.format.gpu_name().yellow(),
+        tex.format,
+        d.bpp,
+        if d.compressed { "compressed" } else { "uncompressed" },
+    );
     println!("  Mip levels : {}", tex.mip_levels);
     println!("  Data size  : {} bytes", tex.data.len().to_string().yellow());
 
@@ -913,24 +1458,6 @@ fn decode_to_rgba8(tex: &sylpheed_formats::texture::X360Texture) -> Result<Vec<u
 
 use sylpheed_formats::pak::inner_format_label as inner_label;
 
-/// Try to recover an IDXD entry's original TOC path from its identity tokens.
-/// Uses the entry's ID/Name/Model fields plus identifier-like pool tokens as
-/// candidates for [`sylpheed_formats::hash::recover_toc_name`].
-fn idxd_toc_name(obj: &IdxdObject, name_hash: u32) -> Option<String> {
-    let mut cands: Vec<&str> = Vec::new();
-    for key in ["ID", "Name", "Model"] {
-        if let Some(v) = obj.get_raw(key) {
-            cands.push(v);
-        }
-    }
-    for t in obj.tokens() {
-        if t.contains('_') || t.len() >= 5 {
-            cands.push(t.as_str());
-        }
-    }
-    sylpheed_formats::hash::recover_toc_name(name_hash, &cands)
-}
-
 fn cmd_pak_list(pak: &Path, idxd_only: bool) -> Result<()> {
     let arc = PakArchive::open(pak).with_context(|| format!("opening {}", pak.display()))?;
     println!(
@@ -958,7 +1485,7 @@ fn cmd_pak_list(pak: &Path, idxd_only: bool) -> Result<()> {
         }
         let (detail, name) = if is_idxd {
             match IdxdObject::parse(&payload) {
-                Ok(o) => (o.identity(), idxd_toc_name(&o, e.name_hash)),
+                Ok(o) => (o.identity(), o.recover_toc_path(e.name_hash)),
                 Err(_) => (String::new(), None),
             }
         } else {

crates/sylpheed-formats/data/ship_placements.txt

@@ -12,7 +12,12 @@
 
 ship e106 ref=e106_bdy_04
   e106_bdy_01 1 0 0 0 1 0 0 0 1 -263.9948 -150.43242 1164.8667
-  e106_bdy_02 -1 0 0 0 1 0 0 0 1 264.0088 -150.41339 1164.8651
+# 2026-08-12: this rotation was diag(-1,1,1) - the X-flip `correlate` bakes in
+# when a draw's buffer is the mirror of the decoded one. With distinct anchor
+# assignment the twins now decode to their OWN buffers (the container carries
+# both halves), so the mirror lives in the data and the placement is plain
+# identity. Re-emitting from the capture agrees: `1 0 0 0 1 0 0 0 1 264.04343`.
+  e106_bdy_02 1 0 0 0 1 0 0 0 1 264.0088 -150.41339 1164.8651
   e106_bdy_03 1 0 0 0 1 0 0 0 1 0.0029247368 -34.517372 1075.878
   e106_bdy_04 1 0 0 0 1 0 0 0 1 0 0 0
   e106_brg_01 1 0 0 0 1 0 0 0 1 -0.005471501 153.31795 -164.03748

crates/sylpheed-formats/data/unit_definition_layout.txt

@@ -0,0 +1,177 @@
+# Unit / vessel definition object layout — offset, field, kind.
+#
+# Read out of the title's own loader, not inferred: `sub_82341A20` builds every
+# key as `addi r4, r30, -N` with `r30 = 0x82088f94`, so the field NAME for each
+# store is a string in the executable image; pairing each key with the first
+# store after its accessor call gives the offset. The accessor for floats is
+# `sub_822FC5A8`, which returns 0.0 when the pool has no value for the key.
+#
+# Verified against live objects dumped from a running Stage 02: 406 field values
+# agree with the disc records and 0 disagree, over 11 objects spanning both the
+# UNIT and VESSEL schemas (see docs/re/live-unit-definitions.md).
+#
+# Two conventions matter for a reimplementation:
+#   * angle fields are DEGREES on disc and RADIANS in this object;
+#   * a field the disc record omits is left at the accessor's miss value (0.0 for
+#     floats) unless something later derives it — `Size_Y` takes `Size_X`.
+#
+# offset  kind  field
+24      str   Model
+28      str   CollisionModel
+48      f32   Size_X
+52      f32   Size_Y
+56      f32   Size_Z
+64      f32   Color_R
+68      f32   Color_G
+72      f32   Color_B
+80      f32   Size_Radius
+84      f32   HP
+88      f32   HQRatio
+92      f32   ShieldRatio
+96      f32   ThrusterRatio
+100     word  IsDestructible
+104     str   NamePlate
+112     word  MountedShieldGenerator
+116     f32   ResistanceToOptics
+120     f32   ResistanceToShell
+124     f32   ResistanceToExplosion
+128     f32   ResistanceToPlayer
+132     f32   ResistanceParalyze
+136     str   HUDMarkerID
+156     f32   MinimumVelocity
+160     f32   MaximumVelocity
+164     f32   CruisingVelocity
+168     f32   Acceleration
+172     f32   Deceleration
+176     f32   AV_PitchPlus_Max
+180     f32   AV_PitchPlus_Min
+184     f32   AA_PitchPlus_Max
+188     f32   AA_PitchPlus_Min
+192     f32   AV_PitchMinus_Max
+196     f32   AV_PitchMinus_Min
+200     f32   AA_PitchMinus_Max
+204     f32   AA_PitchMinus_Min
+208     f32   AV_Yaw_Max
+212     f32   AV_Yaw_Min
+216     f32   AA_Yaw_Max
+220     f32   AA_Yaw_Min
+224     f32   AV_Roll_Max
+228     f32   AV_Roll_Min
+232     f32   AA_Roll_Max
+236     f32   AA_Roll_Min
+248     f32   SideThrustVelocity_Max
+252     f32   SideThrustAcceleration
+256     f32   MaximumBank_Normal
+260     f32   YawDragFactor
+264     f32   PitchDragFactor
+268     f32   RollDragFactor
+272     f32   DragFactorThreshold
+276     f32   ArterBurner_Vc
+280     f32   ReverseThrust_Vc
+284     f32   ArterBurner_Acc
+288     f32   ReverseThrust_Acc
+292     f32   AccPitchFactor
+296     f32   DecPitchFactor
+300     f32   AV_AxisMode_Max
+304     f32   AV_AxisMode_Min
+308     f32   AA_AxisMode_Max
+312     f32   AA_AxisMode_Min
+316     f32   PowerCutConsumeShield
+320     f32   PowerCutDeceleration
+324     f32   AB_ConsumeShield_Begin
+328     f32   AB_ConsumeShield
+332     f32   AB_AV_PitchPlus
+336     f32   AB_AA_PitchPlus
+340     f32   AB_AV_PitchMinus
+344     f32   AB_AA_PitchMinus
+348     f32   AB_AV_Yaw
+352     f32   AB_AA_Yaw
+356     f32   AB_AV_Roll
+360     f32   AB_AA_Roll
+364     word  SideRoll
+368     f32   SideRoll_Time
+372     f32   SideRoll_Length
+376     word  BarrelRoll
+380     f32   BarrelRoll_CountMinimum
+384     f32   BarrelRoll_CountMaximum
+388     f32   BarrelRoll_Time
+392     f32   BarrelRoll_Radius
+396     word  TurnAttack
+400     f32   TurnAttack_CutoffRatio
+404     f32   TurnAttack_DoubleRatio
+408     f32   CutoffTimeMin
+412     f32   CutoffTimeMax
+416     f32   TurnAttack_DoubleTimeMin
+420     f32   TurnAttack_DoubleTimeMax
+424     word  TurnAway
+428     f32   Turn_AngularVelocity
+432     f32   TurnAway_Time_Minimum
+436     f32   TurnAway_Time_Maximum
+440     word  BoostAway
+444     f32   BoostAway_Time_Minimum
+448     f32   BoostAway_Time_Maximum
+452     word  HoldPosition
+456     f32   HoldPosition_LengthMin
+460     f32   HoldPosition_LengthMax
+464     f32   HoldPosition_MinimumTime
+468     f32   HoldPosition_MaximumTime
+472     f32   HoldPosition_SideRatio
+476     f32   HoldPosition_BackRatio
+480     f32   HoldPosition_CutoffRatio
+484     f32   HoldPosition_CancelTime
+488     word  Slalom
+492     f32   Slalom_CutoffRatio
+496     f32   Slalom_TurnCount_Min
+500     f32   Slalom_TurnCount_Max
+504     word  Through
+508     f32   Through_CutoffRatio
+512     f32   Through_AngleMinimum
+516     f32   Through_AngleMaximum
+520     f32   Through_Time1Max
+524     f32   Through_Time1Min
+528     f32   Through_Time2Max
+532     f32   Through_Time2Min
+536     f32   Through_LengthMinimum
+540     f32   Through_LengthMaximum
+544     word  SolidCutoff
+548     f32   SolidCutoff_Ratio
+552     f32   SolidCutoff_LengthMin
+556     f32   SolidCutoff_LengthMax
+560     f32   HomingResistAdjustment
+564     f32   UsingChaffRatio
+568     f32   MaxValue
+572     f32   ChargeDelay
+576     f32   ChargeDelay_Break
+580     f32   ChargeSpeed
+584     f32   Delay
+588     f32   DelayAdjustment
+596     str   LowerHPFxModel
+604     str   ExplosionFxModel
+612     str   DestroyMotionName
+620     str   ExplosionMotionName
+624     f32   DestroyMotionTime
+628     f32   DryMass
+632     f32   GrossMass
+636     word  Thruster
+640     word  SideThruster
+644     word  ExplosionSE
+648     word  JumpIn
+652     word  JumpOut
+656     word  ShipEnvironmentSE
+660     word  LowerHPSE
+664     f32   LowerHPThresholdRatio
+668     f32   SELength
+672     f32   RadarRange
+676     f32   FCSRange
+680     f32   FiringRange
+684     word  MountedFCS
+692     f32   AttackVesselPoint
+696     f32   AttackCraftPoint
+700     f32   DefencePoint
+736     str   ShieldRecoverEffectName
+740     str   ShieldHitEffectName
+744     str   JumpIn
+748     str   JumpOut
+752     str   FadeIn
+756     str   FadeOut
+760     str   Effect_Paralyze

crates/sylpheed-formats/examples/achievements_map.rs

@@ -0,0 +1,55 @@
+//! RE probe: the `ACHIEVEMENTS_REQUIREMENTS` config list.
+//!
+//! `GamePart_Debriefing` (`0x8218CF38`..`0x82191B18`) walks this list after a
+//! mission (`sub_8218F9A8`): for each entry it takes the entry's **index** `n`,
+//! tests bit `n` of an awarded-mask, and if the bit is clear it evaluates the
+//! entry (`0x8218FAB0`) and sets the bit when satisfied. `GamePart_ChallengeMission`
+//! then gates each challenge mission on a bit of the same space via its own
+//! `REQUIREMENT` key. So this list *is* the achievement/bit numbering.
+//!
+//! Run: cargo run --release -p sylpheed-formats --example achievements_map -- <disc-root>
+
+use sylpheed_formats::{idxd::IdxdObject, pak::PakArchive};
+
+fn find(h: &[u8], n: &[u8]) -> bool {
+    h.windows(n.len()).any(|w| w == n)
+}
+
+fn main() {
+    let disc = std::env::args().nth(1).unwrap_or_else(|| {
+        std::env::var("SYLPHEED_DISC").expect("pass disc root or set SYLPHEED_DISC")
+    });
+    let dat = format!("{disc}/dat");
+    let mut paks: Vec<_> = std::fs::read_dir(&dat)
+        .expect("dat dir")
+        .filter_map(|e| e.ok())
+        .map(|e| e.path())
+        .filter(|p| p.extension().is_some_and(|x| x == "pak"))
+        .collect();
+    paks.sort();
+
+    for p in &paks {
+        let Ok(arc) = PakArchive::open(p) else { continue };
+        for (i, e) in arc.entries().iter().enumerate() {
+            let Ok(b) = arc.read(e) else { continue };
+            if !find(&b, b"ACHIEVEMENTS_REQUIREMENTS") {
+                continue;
+            }
+            let name = p.file_name().unwrap().to_string_lossy().to_string();
+            match IdxdObject::parse(&b) {
+                Ok(o) => {
+                    let t = o.tokens();
+                    println!(
+                        "\n===== {name} entry #{i}  schema {:08x}  {} tokens =====",
+                        o.schema_hash,
+                        t.len()
+                    );
+                    for (j, tok) in t.iter().enumerate() {
+                        println!("  {j:3}  {tok}");
+                    }
+                }
+                Err(err) => println!("\n===== {name} entry #{i}: not IDXD ({err}) ====="),
+            }
+        }
+    }
+}

crates/sylpheed-formats/examples/bench_ships.rs

@@ -0,0 +1,22 @@
+//! Time repeated per-ship decodes of one container, as the viewer does.
+use std::collections::HashSet;
+use std::time::Instant;
+use sylpheed_formats::mesh::Xbg7Model;
+use sylpheed_formats::ship::{is_base_part, ship_id_of};
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let bytes = std::fs::read(&a[1]).unwrap();
+    let names = sylpheed_formats::mesh::xbg7_resource_names(&bytes);
+    let ids: Vec<String> = {
+        let mut v: Vec<String> = names.iter().filter(|n| is_base_part(n))
+            .filter_map(|n| ship_id_of(n).map(|s| s.to_string())).collect();
+        v.sort(); v.dedup(); v.truncate(5); v
+    };
+    for id in &ids {
+        let want: HashSet<String> = names.iter()
+            .filter(|n| ship_id_of(n) == Some(id.as_str())).cloned().collect();
+        let t = Instant::now();
+        let got = Xbg7Model::models_named(&bytes, &want, &|| false);
+        println!("{id}: {} models in {:?}", got.len(), t.elapsed());
+    }
+}

crates/sylpheed-formats/examples/better_home.rs

@@ -0,0 +1,123 @@
+//! Does a resource have a CLEANER home in its container than the one we picked?
+//!
+//! After the pad-scoring fix, only two resources on the disc still decode to an
+//! index run with degenerate triangles — `e201_bdy_03_m` (2 containers) and
+//! `_rou_f402_dead` (9). Degeneracy says the run does not fit the pool, so either
+//! the vertex block is wrong or the candidate list never offered the right one.
+//! This walks every candidate vertex-run start for the resource's declaration and
+//! scores each `(start, pad)` the way the anchor now does — degenerate triangles
+//! first, then winding, plus coverage — so the answer is one of:
+//!   * a strictly cleaner candidate exists (the selection is at fault),
+//!   * several are equally clean (genuinely ambiguous), or
+//!   * nothing is clean (the block is not in the candidate list at all).
+//!
+//! Usage: better_home <container.xpr> <resource-name>
+use sylpheed_formats::mesh::{debug_resource_params, debug_vertex_run_starts, Xbg7Model};
+
+fn be16(b: &[u8], at: usize) -> u32 {
+    ((b[at] as u32) << 8) | b[at + 1] as u32
+}
+
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let bytes = std::fs::read(&a[1]).expect("container");
+    let name = &a[2];
+
+    let Some((markers, stride)) = debug_resource_params(&bytes, name) else {
+        eprintln!("no such XBG7 resource: {name}");
+        std::process::exit(1);
+    };
+    let (vc, ic) = markers[0];
+    println!("{name}: {} marker(s), first = {vc} verts / {ic} indices, stride {stride}", markers.len());
+
+    // Where did the decoder put it?
+    let ours = Xbg7Model::stage_models(&bytes)
+        .into_iter()
+        .find(|m| m.name == *name)
+        .and_then(|m| m.meshes.first().and_then(|s| s.vbuf_offset));
+    println!("our anchor: {ours:?}");
+
+    let starts = debug_vertex_run_starts(&bytes, stride);
+    println!("{} candidate vertex-run starts for stride {stride}", starts.len());
+
+    // Score every (start, pad): degenerate triangles, winding against the stored
+    // normals, and whether the run covers the pool exactly.
+    let mut rows: Vec<(usize, f32, usize, usize, usize, bool)> = Vec::new(); // degen, wind, start, pad, max_idx, covered
+    for &vb in &starts {
+        for pad in 0..=3usize {
+            if vb < ic * 2 + pad {
+                continue;
+            }
+            let ib = vb - ic * 2 - pad;
+            if ib + ic * 2 > bytes.len() || vb + vc * stride > bytes.len() {
+                continue;
+            }
+            let idx: Vec<u32> = (0..ic).map(|k| be16(&bytes, ib + k * 2)).collect();
+            let max_idx = *idx.iter().max().unwrap_or(&0) as usize;
+            if max_idx >= vc {
+                continue; // out of range — not a candidate at all
+            }
+            let pos: Vec<[f32; 3]> = (0..vc)
+                .map(|v| {
+                    let at = vb + v * stride;
+                    [
+                        f32::from_be_bytes(bytes[at..at + 4].try_into().unwrap()),
+                        f32::from_be_bytes(bytes[at + 4..at + 8].try_into().unwrap()),
+                        f32::from_be_bytes(bytes[at + 8..at + 12].try_into().unwrap()),
+                    ]
+                })
+                .collect();
+            if pos.iter().any(|p| p.iter().any(|c| !c.is_finite() || c.abs() > 1e6)) {
+                continue;
+            }
+            let mut degen = 0usize;
+            let (mut agree, mut counted) = (0usize, 0usize);
+            for t in idx.chunks_exact(3) {
+                let (x, y, z) = (t[0] as usize, t[1] as usize, t[2] as usize);
+                if x == y || y == z || x == z {
+                    degen += 1;
+                    continue;
+                }
+                // Winding needs normals; use the geometric centroid normal as a
+                // stand-in so this stays declaration-agnostic: a consistent mesh
+                // has all faces pointing away from the centroid on a convex-ish
+                // hull. Weak, so degeneracy leads the sort.
+                let e1 = [pos[y][0] - pos[x][0], pos[y][1] - pos[x][1], pos[y][2] - pos[x][2]];
+                let e2 = [pos[z][0] - pos[x][0], pos[z][1] - pos[x][1], pos[z][2] - pos[x][2]];
+                let f = [
+                    e1[1] * e2[2] - e1[2] * e2[1],
+                    e1[2] * e2[0] - e1[0] * e2[2],
+                    e1[0] * e2[1] - e1[1] * e2[0],
+                ];
+                let cx: [f32; 3] = {
+                    let mut c = [0.0f32; 3];
+                    for p in &pos {
+                        for k in 0..3 {
+                            c[k] += p[k] / pos.len() as f32;
+                        }
+                    }
+                    c
+                };
+                let out = [pos[x][0] - cx[0], pos[x][1] - cx[1], pos[x][2] - cx[2]];
+                counted += 1;
+                if f[0] * out[0] + f[1] * out[1] + f[2] * out[2] > 0.0 {
+                    agree += 1;
+                }
+            }
+            let w = if counted == 0 { 0.0 } else { agree as f32 / counted as f32 };
+            rows.push((degen, w.max(1.0 - w), vb, pad, max_idx, max_idx + 1 == vc));
+        }
+    }
+    rows.sort_by(|a, b| a.0.cmp(&b.0).then(b.1.total_cmp(&a.1)));
+    println!("\n{} in-range candidates; best 12 by (degenerate, winding):", rows.len());
+    for (d, w, vb, pad, mx, cov) in rows.iter().take(12) {
+        let mark = if Some(*vb) == ours { "  <-- ours" } else { "" };
+        println!(
+            "  vb 0x{vb:07X} pad {pad}  degen {d:>4}  wind {w:.3}  max_idx {mx}/{}  {}{mark}",
+            vc - 1,
+            if *cov { "covers" } else { "SHORT" }
+        );
+    }
+    let clean = rows.iter().filter(|r| r.0 == 0 && r.5).count();
+    println!("\n{clean} candidates are degenerate-free AND cover the pool exactly");
+}

crates/sylpheed-formats/examples/bounds_in_descriptor.rs

@@ -0,0 +1,53 @@
+//! Does a resource's DESCRIPTOR carry its bounding box?
+//!
+//! The last cross-container disagreements are 24-vertex bound boxes swapping
+//! identities; no anchoring rule can pin them (see docs). If the descriptor
+//! states the box, that is the missing information. This decodes the resource,
+//! takes the box its geometry actually spans, and searches the descriptor for
+//! those float values.
+//!
+//! Usage: bounds_in_descriptor <container.xpr> <resource>...
+use sylpheed_formats::mesh::{xbg7_descriptor_range, Xbg7Model};
+use std::collections::HashSet;
+
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let bytes = std::fs::read(&a[1]).expect("container");
+    let want: HashSet<String> = a[2..].iter().cloned().collect();
+    for m in Xbg7Model::models_named(&bytes, &want, &|| false) {
+        let (mut lo, mut hi) = ([f32::MAX; 3], [f32::MIN; 3]);
+        for s in &m.meshes {
+            for q in &s.positions {
+                for k in 0..3 {
+                    lo[k] = lo[k].min(q[k]);
+                    hi[k] = hi[k].max(q[k]);
+                }
+            }
+        }
+        let Some((d0, d1)) = xbg7_descriptor_range(&bytes, &m.name) else { continue };
+        println!(
+            "{} descriptor 0x{d0:x}..0x{d1:x} ({} bytes), box lo{:?} hi{:?}",
+            m.name,
+            d1 - d0,
+            lo.map(|v| v.round()),
+            hi.map(|v| v.round())
+        );
+        // Where in the descriptor does each bound value appear (±0.01)?
+        let targets: Vec<(&str, f32)> = vec![
+            ("lo.x", lo[0]), ("lo.y", lo[1]), ("lo.z", lo[2]),
+            ("hi.x", hi[0]), ("hi.y", hi[1]), ("hi.z", hi[2]),
+        ];
+        for (label, v) in targets {
+            let mut at: Vec<usize> = Vec::new();
+            let mut o = d0;
+            while o + 4 <= d1 {
+                let f = f32::from_be_bytes(bytes[o..o + 4].try_into().unwrap());
+                if (f - v).abs() <= 0.01 * (1.0 + v.abs()) {
+                    at.push(o - d0);
+                }
+                o += 4;
+            }
+            println!("   {label:5} {v:10.3} at descriptor offsets {:x?}", &at[..at.len().min(6)]);
+        }
+    }
+}

crates/sylpheed-formats/examples/caption_coverage.rs

@@ -0,0 +1,38 @@
+//! How many caption lines does `build_caption_text` actually recover?
+use std::collections::BTreeMap;
+use sylpheed_formats::{movie_subtitle, PakArchive};
+
+fn main() {
+    let disc = std::env::var("SYLPHEED_DISC").expect("set SYLPHEED_DISC");
+    let pak = PakArchive::open(format!("{disc}/dat/GP_MAIN_GAME_E.pak")).expect("pak");
+    let all = movie_subtitle::build_caption_text(&pak);
+    let demo = movie_subtitle::build_demo_text(&pak);
+
+    let mut per: BTreeMap<&str, (usize, usize)> = BTreeMap::new();
+    for (id, lines) in &all {
+        let fam = id.split('_').next().unwrap();
+        let e = per.entry(fam).or_default();
+        e.0 += 1;
+        e.1 += lines.len();
+    }
+    println!("{:<8} {:>8} {:>9}", "family", "ids", "lines");
+    let (mut ids, mut lines) = (0, 0);
+    for (fam, (i, l)) in &per {
+        println!("{fam:<8} {i:>8} {l:>9}");
+        ids += i;
+        lines += l;
+    }
+    println!("{:<8} {:>8} {:>9}", "TOTAL", ids, lines);
+    println!(
+        "\nbuild_demo_text alone: {} ids, {} lines",
+        demo.len(),
+        demo.values().map(|v| v.len()).sum::<usize>()
+    );
+    // The DEMO family must come out identical either way — that is the control.
+    let demo_via_all: usize = all
+        .iter()
+        .filter(|(k, _)| k.starts_with("DEMO_"))
+        .map(|(_, v)| v.len())
+        .sum();
+    println!("DEMO via build_caption_text: {demo_via_all} lines");
+}

crates/sylpheed-formats/examples/capture_ib_truth.rs

@@ -0,0 +1,222 @@
+//! Where does a drawn block's INDEX buffer really live?
+//!
+//! Our XBG7 anchor scan only ever *assumes* the layout `[index buffer][vertex
+//! buffer]` with a pad of at most 3 bytes between them (`anchor_pool_mesh`:
+//! `ib = vb - idx_count*2 - pad`). Nothing on disc states it, and it is the gate
+//! that rejected the capture-proven `e106_eng_02_l` block
+//! (docs/re/captures/…): the block's index data was not where the decoder
+//! looked. The F10 ship capture was extended on 2026-08-13 to log each draw's
+//! index-buffer base, count and min/max index value, so the assumption is now
+//! directly checkable:
+//!
+//!   * `vbase - ibase` is the real gap in guest memory, and a stage container is
+//!     uploaded contiguously (see `shared_vbase_check`), so the same difference
+//!     holds in the file;
+//!   * `max index vs vcount` says whether a draw covers its whole vertex pool —
+//!     the "buffer not covered" miss class is a *sub-range draw* if it does not.
+//!
+//! Usage:
+//!   cargo run --release --example capture_ib_truth -- <Stage_SNN.xpr> <capture.log>...
+use sylpheed_formats::mesh::{debug_resource_params, xbg7_resource_names, Xbg7Model};
+use sylpheed_formats::ship_capture::{parse_capture, CapturedDraw};
+use std::collections::HashMap;
+
+fn q(v: f32) -> i64 {
+    (v as f64 * 1e4).round() as i64
+}
+
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    if a.len() < 3 {
+        eprintln!("usage: capture_ib_truth <container.xpr> <capture.log>...");
+        std::process::exit(2);
+    }
+    let bytes = std::fs::read(&a[1]).expect("container");
+
+    // One entry per (log, vbase): the capture already de-dups per placement, and
+    // a buffer drawn at several transforms has the same index buffer each time.
+    let mut draws: Vec<CapturedDraw> = Vec::new();
+    let mut seen = std::collections::HashSet::new();
+    for log in &a[2..] {
+        let text = std::fs::read_to_string(log).expect("log");
+        for d in parse_capture(&text) {
+            // One entry per (log, vbase, index range): the engine issues SEVERAL
+            // draws over one vertex buffer, each with its own index sub-range, and
+            // it is their UNION that describes the block. (Captures taken before
+            // 2026-08-13 de-dup by (vbase, transform) and so hold only the first
+            // batch — such a log reads as a mysteriously short draw.)
+            let k = d.ib.map(|i| (i.ibase, i.icount)).unwrap_or((0, 0));
+            if d.ib.is_some() && d.pos.len() >= 4 && seen.insert((log.clone(), d.vbase, k)) {
+                draws.push(d);
+            }
+        }
+    }
+    eprintln!("{} drawn buffers with an index buffer", draws.len());
+
+    // ── Place the drawn buffers in the file: POSITION is f32×3 big-endian at
+    // vertex offset 0, so the dumped positions are a literal byte pattern.
+    let be = |at: usize| f32::from_be_bytes(bytes[at..at + 4].try_into().unwrap());
+    let mut index: HashMap<(i64, i64, i64), Vec<u32>> = HashMap::new();
+    let mut o = 0usize;
+    while o + 12 <= bytes.len() {
+        let (x, y, z) = (be(o), be(o + 4), be(o + 8));
+        if x.is_finite() && y.is_finite() && z.is_finite() && x.abs() < 1e6 && y.abs() < 1e6 && z.abs() < 1e6 {
+            index.entry((q(x), q(y), q(z))).or_default().push(o as u32);
+        }
+        o += 4;
+    }
+    let mut deltas: HashMap<i64, usize> = HashMap::new();
+    let mut hits: Vec<(i64, usize, &CapturedDraw)> = Vec::new(); // (delta, file offset, draw)
+    for d in &draws {
+        let k = (q(d.pos[0][0]), q(d.pos[0][1]), q(d.pos[0][2]));
+        for dx in -1..=1i64 {
+            for dy in -1..=1i64 {
+                for dz in -1..=1i64 {
+                    let Some(cands) = index.get(&(k.0 + dx, k.1 + dy, k.2 + dz)) else { continue };
+                    for &off in cands {
+                        for stride in (12..=64).step_by(4) {
+                            let ok = (1..4).all(|j| {
+                                let at = off as usize + j * stride;
+                                at + 12 <= bytes.len()
+                                    && (0..3).all(|c| (be(at + c * 4) - d.pos[j][c]).abs() <= 1e-4)
+                            });
+                            if ok {
+                                let delta = d.vbase as i64 - off as i64;
+                                *deltas.entry(delta).or_default() += 1;
+                                hits.push((delta, off as usize, d));
+                                break;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    let Some((&base_delta, &n)) = deltas.iter().max_by_key(|(_, n)| **n) else {
+        eprintln!("no draw could be placed in this container");
+        std::process::exit(1);
+    };
+    println!("container load constant: vbase - file_offset = 0x{base_delta:X}  ({n} buffers agree)");
+
+    // ── Our decoder's view of the same container.
+    let models = Xbg7Model::stage_models(&bytes);
+    let mut by_off: HashMap<usize, Vec<(String, usize, usize)>> = HashMap::new();
+    for m in &models {
+        for sm in &m.meshes {
+            if let Some(off) = sm.vbuf_offset {
+                by_off
+                    .entry(off)
+                    .or_default()
+                    .push((m.name.clone(), sm.positions.len(), sm.indices.len()));
+            }
+        }
+    }
+    println!("decoded {} resources, {} distinct vertex offsets\n", models.len(), by_off.len());
+
+    // Declared-but-not-decoded resources, indexed by their first marker's
+    // (vertex, index) counts. A drawn buffer our decoder cannot name is the one
+    // thing a capture can give the residual misses: ground truth for where the
+    // block actually is. Matching on counts is enough to propose an identity —
+    // then `debug_try_anchor` at that offset says which gate rejects it.
+    let decoded_names: std::collections::HashSet<String> =
+        models.iter().map(|m| m.name.clone()).collect();
+    let mut undecoded_by_counts: HashMap<(usize, usize), Vec<String>> = HashMap::new();
+    for n in xbg7_resource_names(&bytes) {
+        if decoded_names.contains(&n) {
+            continue;
+        }
+        if let Some((markers, _)) = debug_resource_params(&bytes, &n) {
+            if let Some(&(v, i)) = markers.first() {
+                undecoded_by_counts.entry((v, i)).or_default().push(n);
+            }
+        }
+    }
+
+    // ── The report: one row per drawn BUFFER, aggregating its index batches.
+    let mut per_buf: HashMap<u32, (usize, Vec<sylpheed_formats::ship_capture::CapturedIndexBuffer>, u32)> =
+        HashMap::new();
+    for (delta, voff, d) in &hits {
+        if *delta != base_delta {
+            continue;
+        }
+        let e = per_buf.entry(d.vbase).or_insert((*voff, Vec::new(), d.vcount));
+        let ib = d.ib.unwrap();
+        if !e.1.contains(&ib) {
+            e.1.push(ib);
+        }
+    }
+
+    let (mut pad0, mut pad_small, mut pad_off, mut unnamed) = (0usize, 0usize, 0usize, 0usize);
+    let (mut cover_exact, mut cover_short, mut idx_equal, mut idx_partial) = (0usize, 0usize, 0usize, 0usize);
+    let mut rows: Vec<(usize, String)> = Vec::new();
+    for (_, (voff, ibs, vcount)) in per_buf.iter() {
+        let batches = ibs.len();
+        let total: u32 = ibs.iter().map(|i| i.icount).sum();
+        let lo = ibs.iter().map(|i| i.ibase).min().unwrap() as i64 - base_delta;
+        let hi = ibs.iter().map(|i| i.ibase + i.icount * 2).max().unwrap() as i64 - base_delta;
+        let umax = ibs.iter().map(|i| i.imax).max().unwrap();
+        let gap = *voff as i64 - hi; // bytes from the end of the index data to the vertex buffer
+        let names = by_off.get(voff);
+        let dec_idx = names
+            .and_then(|v| v.iter().find(|(_, p, _)| *p as u32 == *vcount).map(|(_, _, i)| *i as u32));
+        // The decoder's assumption, scored: it expects the whole index buffer at
+        // `vb - 2*idx_count - pad`, pad ≤ 3.
+        let dec_pad = dec_idx.map(|i| *voff as i64 - (i as i64) * 2 - lo);
+        match dec_pad {
+            Some(0) => pad0 += 1,
+            Some(p) if (1..=3).contains(&p) => pad_small += 1,
+            Some(_) => pad_off += 1,
+            None => unnamed += 1,
+        }
+        if umax + 1 == *vcount {
+            cover_exact += 1;
+        } else {
+            cover_short += 1;
+        }
+        match dec_idx {
+            Some(i) if i == total => idx_equal += 1,
+            Some(_) => idx_partial += 1,
+            None => {}
+        }
+        rows.push((
+            *voff,
+            format!(
+                "vb 0x{:07X} v={:<6} batches {:<3} idx {:<6} span {:<7} gap {:<8} decpad {:<7} cover {:<10} {}",
+                voff,
+                vcount,
+                batches,
+                total,
+                hi - lo,
+                gap,
+                dec_pad.map(|p| p.to_string()).unwrap_or_else(|| "?".into()),
+                if umax + 1 == *vcount { "exact".to_string() } else { format!("{}/{}", umax, vcount - 1) },
+                names
+                    .map(|v| v
+                        .iter()
+                        .map(|(n, p, i)| format!("{n}(v{p},i{i})"))
+                        .collect::<Vec<_>>()
+                        .join(" "))
+                    .unwrap_or_else(|| {
+                        // Nothing of ours sits here — is it a resource that never
+                        // decodes? Propose it by (vertex, index) counts.
+                        undecoded_by_counts
+                            .get(&(*vcount as usize, total as usize))
+                            .map(|v| format!("MISSED? {}", v.join(" ")))
+                            .unwrap_or_else(|| "-".into())
+                    })
+            ),
+        ));
+    }
+    rows.sort();
+    for (_, r) in &rows {
+        println!("{r}");
+    }
+    println!("\nplaced {} drawn buffers in this container", rows.len());
+    println!(
+        "DECODER layout assumption — whole index buffer at vb - 2*idx_count - pad:  pad 0 {pad0} · pad 1..3 {pad_small} · elsewhere {pad_off} · not decoded here {unnamed}"
+    );
+    println!(
+        "index extent: our idx_count == sum of captured batches for {idx_equal} buffers, differs for {idx_partial}"
+    );
+    println!("vertex-pool coverage by the union of batches: exact {cover_exact} · short {cover_short}");
+}

crates/sylpheed-formats/examples/capture_index_bytes.rs

@@ -0,0 +1,175 @@
+//! Do our decoded triangle indices equal the ones the GPU actually read?
+//!
+//! `capture_ib_truth` established *where* a block's index buffer lives and that
+//! its length matches ours. This asks the stronger question: are the index VALUES
+//! the same, in the same order? The capture prints the first 24 indices of every
+//! draw batch verbatim (`idx: …`), and a batch's `ibase` locates it inside the
+//! block's index buffer — so for each drawn buffer we can line the captured run
+//! up against `GameMesh::indices` at the right offset and compare element by
+//! element. That tests the whole index path at once: the anchor, the u16
+//! big-endian read, the triangle-list interpretation (a strip would disagree
+//! immediately), and the sub-mesh carve.
+//!
+//! Usage:
+//!   cargo run --release --example capture_index_bytes -- <Stage_SNN.xpr> <capture.log>...
+use sylpheed_formats::mesh::Xbg7Model;
+use sylpheed_formats::ship_capture::{parse_capture, CapturedDraw};
+use std::collections::HashMap;
+
+fn q(v: f32) -> i64 {
+    (v as f64 * 1e4).round() as i64
+}
+
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    if a.len() < 3 {
+        eprintln!("usage: capture_index_bytes <container.xpr> <capture.log>...");
+        std::process::exit(2);
+    }
+    let bytes = std::fs::read(&a[1]).expect("container");
+
+    let mut draws: Vec<CapturedDraw> = Vec::new();
+    let mut seen = std::collections::HashSet::new();
+    for log in &a[2..] {
+        let text = std::fs::read_to_string(log).expect("log");
+        for d in parse_capture(&text) {
+            let k = d.ib.map(|i| (i.ibase, i.icount)).unwrap_or((0, 0));
+            if d.ib.map_or(false, |i| i.head_len > 0) && d.pos.len() >= 4 && seen.insert((log.clone(), d.vbase, k)) {
+                draws.push(d);
+            }
+        }
+    }
+    eprintln!("{} draw batches with an index head", draws.len());
+
+    // Place each drawn buffer in the file by its dumped positions (see
+    // capture_ib_truth for the method) and keep the modal load constant.
+    let be = |at: usize| f32::from_be_bytes(bytes[at..at + 4].try_into().unwrap());
+    let mut index: HashMap<(i64, i64, i64), Vec<u32>> = HashMap::new();
+    let mut o = 0usize;
+    while o + 12 <= bytes.len() {
+        let (x, y, z) = (be(o), be(o + 4), be(o + 8));
+        if x.is_finite() && y.is_finite() && z.is_finite() && x.abs() < 1e6 && y.abs() < 1e6 && z.abs() < 1e6 {
+            index.entry((q(x), q(y), q(z))).or_default().push(o as u32);
+        }
+        o += 4;
+    }
+    let mut deltas: HashMap<i64, usize> = HashMap::new();
+    let mut hits: Vec<(i64, usize, &CapturedDraw)> = Vec::new();
+    for d in &draws {
+        let k = (q(d.pos[0][0]), q(d.pos[0][1]), q(d.pos[0][2]));
+        for dx in -1..=1i64 {
+            for dy in -1..=1i64 {
+                for dz in -1..=1i64 {
+                    let Some(cands) = index.get(&(k.0 + dx, k.1 + dy, k.2 + dz)) else { continue };
+                    for &off in cands {
+                        for stride in (12..=64).step_by(4) {
+                            let ok = (1..4).all(|j| {
+                                let at = off as usize + j * stride;
+                                at + 12 <= bytes.len()
+                                    && (0..3).all(|c| (be(at + c * 4) - d.pos[j][c]).abs() <= 1e-4)
+                            });
+                            if ok {
+                                *deltas.entry(d.vbase as i64 - off as i64).or_default() += 1;
+                                hits.push((d.vbase as i64 - off as i64, off as usize, d));
+                                break;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    let Some((&base_delta, _)) = deltas.iter().max_by_key(|(_, n)| **n) else {
+        eprintln!("no draw could be placed in this container");
+        std::process::exit(1);
+    };
+    println!("load constant 0x{base_delta:X}");
+
+    // Our decode, indexed by vertex offset. A model may hold several sub-meshes;
+    // compare against the one whose vertex count matches the draw.
+    let models = Xbg7Model::stage_models(&bytes);
+    let mut by_off: HashMap<usize, Vec<(String, usize, Vec<u32>)>> = HashMap::new();
+    for m in &models {
+        for sm in &m.meshes {
+            if let Some(off) = sm.vbuf_offset {
+                by_off
+                    .entry(off)
+                    .or_default()
+                    .push((m.name.clone(), sm.positions.len(), sm.indices.clone()));
+            }
+        }
+    }
+
+    // Where does each buffer's index data START? Take it from the capture, not
+    // from an assumed pad: `capture_ib_truth` established that a buffer's batches
+    // tile its index buffer exactly (sum of counts == our idx_count, span ==
+    // 2*count), so the lowest `ibase` over a buffer's batches IS the block's
+    // index start. Assuming `vb - 2*len` instead is wrong for the buffers that
+    // sit at pad 2 and shifts the whole comparison by one element.
+    let mut ib_start: HashMap<u32, i64> = HashMap::new();
+    for (delta, _, d) in &hits {
+        if *delta != base_delta {
+            continue;
+        }
+        let ibase = d.ib.unwrap().ibase as i64;
+        ib_start.entry(d.vbase).and_modify(|e| *e = (*e).min(ibase)).or_insert(ibase);
+    }
+
+    let (mut agree, mut disagree, mut unmatched, mut nooverlap) = (0usize, 0usize, 0usize, 0usize);
+    let mut bad: Vec<String> = Vec::new();
+    let mut checked_elems = 0usize;
+    let mut done: std::collections::HashSet<(u32, u32)> = std::collections::HashSet::new();
+    for (delta, voff, d) in &hits {
+        if *delta != base_delta {
+            continue;
+        }
+        let ib = d.ib.unwrap();
+        if !done.insert((d.vbase, ib.ibase)) {
+            continue;
+        }
+        let Some(cands) = by_off.get(voff) else {
+            unmatched += 1;
+            continue;
+        };
+        let Some((name, _, ours)) = cands.iter().find(|(_, p, _)| *p as u32 == d.vcount) else {
+            unmatched += 1;
+            continue;
+        };
+        // Element 0 of our index list is the block's index start, as observed.
+        let ours_start = ib_start[&d.vbase] - base_delta;
+        let batch_off = ib.ibase as i64 - base_delta - ours_start;
+        if batch_off < 0 || batch_off % 2 != 0 {
+            nooverlap += 1;
+            continue;
+        }
+        let first = (batch_off / 2) as usize;
+        let n = (ib.head_len as usize).min(ours.len().saturating_sub(first));
+        if n == 0 {
+            nooverlap += 1;
+            continue;
+        }
+        let mism = (0..n).find(|&k| ours[first + k] != ib.head[k]);
+        checked_elems += n;
+        match mism {
+            None => agree += 1,
+            Some(k) => {
+                disagree += 1;
+                if bad.len() < 8 {
+                    bad.push(format!(
+                        "{name} vb 0x{:07X} batch@{first}: ours {:?} != captured {:?} (first differs at {k})",
+                        voff,
+                        &ours[first..first + n.min(12)],
+                        &ib.head[..n.min(12)]
+                    ));
+                }
+            }
+        }
+    }
+    println!(
+        "index runs compared: {agree} identical · {disagree} differing · {unmatched} no decoded resource · {nooverlap} batch outside our buffer"
+    );
+    println!("{checked_elems} index elements checked against the GPU");
+    for b in &bad {
+        println!("  MISMATCH {b}");
+    }
+}

crates/sylpheed-formats/examples/capture_truth_scan.rs

@@ -0,0 +1,112 @@
+//! Which container did each captured draw come from, and where in it?
+//!
+//! Extends the single-container `--map` check in `shared_vbase_check` to a whole
+//! `resource3d` directory. For each container it indexes every 4-byte-aligned
+//! position triple, looks up each draw's first dumped position, confirms the run
+//! at a fixed stride, and reports the modal `vbase − offset`. A container the
+//! engine loaded shows one dominant constant; an unrelated one shows noise.
+//!
+//! The output is capture-named ground truth for anchors far beyond the one ship
+//! `Stage_S01` gave us.
+//!
+//! Usage: capture_truth_scan <resource3d_dir> <capture.log>...
+use sylpheed_formats::ship_capture::{parse_capture, parse_drawlog, CapturedDraw};
+use std::collections::HashMap;
+
+fn q(v: f32) -> i64 {
+    (v as f64 * 1e4).round() as i64
+}
+
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let dir = &a[1];
+    let mut draws: Vec<CapturedDraw> = Vec::new();
+    let mut seen = std::collections::HashSet::new();
+    for log in &a[2..] {
+        let text = std::fs::read_to_string(log).expect("log");
+        let mut d = parse_capture(&text);
+        if d.is_empty() {
+            d = parse_drawlog(&text);
+        }
+        for x in d {
+            // One entry per buffer; the logs are already deduped per transform.
+            if x.pos.len() >= 8 && x.vcount >= 20 && seen.insert((log.clone(), x.vbase)) {
+                draws.push(x);
+            }
+        }
+    }
+    eprintln!("{} distinct (log, vbase) draws to place", draws.len());
+
+    let mut files: Vec<_> = std::fs::read_dir(dir)
+        .unwrap()
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("xpr"))
+        .collect();
+    files.sort();
+
+    let mut placed = 0usize;
+    for f in &files {
+        let Ok(bytes) = std::fs::read(f) else { continue };
+        // Index quantised position triples. Junk floats (NaN/huge) are skipped,
+        // which prunes most of a texture-heavy container.
+        let be = |at: usize| f32::from_be_bytes(bytes[at..at + 4].try_into().unwrap());
+        let mut index: HashMap<(i64, i64, i64), Vec<u32>> = HashMap::new();
+        let mut o = 0usize;
+        while o + 12 <= bytes.len() {
+            let (x, y, z) = (be(o), be(o + 4), be(o + 8));
+            if x.is_finite() && y.is_finite() && z.is_finite() && x.abs() < 1e6 && y.abs() < 1e6 && z.abs() < 1e6
+            {
+                index.entry((q(x), q(y), q(z))).or_default().push(o as u32);
+            }
+            o += 4;
+        }
+        let mut deltas: HashMap<i64, Vec<(u32, u32)>> = HashMap::new();
+        for d in &draws {
+            let k = (q(d.pos[0][0]), q(d.pos[0][1]), q(d.pos[0][2]));
+            // ±1 in each axis: the log rounds, our file value may round the
+            // other way at a tie.
+            for dx in -1..=1i64 {
+                for dy in -1..=1i64 {
+                    for dz in -1..=1i64 {
+                        let Some(cands) = index.get(&(k.0 + dx, k.1 + dy, k.2 + dz)) else {
+                            continue;
+                        };
+                        for &off in cands {
+                            for stride in (12..=64).step_by(4) {
+                                let ok = (1..4).all(|j| {
+                                    let at = off as usize + j * stride;
+                                    at + 12 <= bytes.len()
+                                        && (0..3).all(|c| {
+                                            (be(at + c * 4) - d.pos[j][c]).abs() <= 1e-4
+                                        })
+                                });
+                                if ok {
+                                    deltas
+                                        .entry(d.vbase as i64 - off as i64)
+                                        .or_default()
+                                        .push((d.vbase, d.vcount));
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        let mut top: Vec<_> = deltas.into_iter().collect();
+        top.sort_by_key(|(_, v)| std::cmp::Reverse(v.len()));
+        if let Some((delta, hits)) = top.first() {
+            if hits.len() >= 3 {
+                placed += hits.len();
+                println!(
+                    "{:<22} base=0x{:<10X} buffers={}",
+                    f.file_name().unwrap().to_string_lossy(),
+                    delta,
+                    hits.len()
+                );
+            }
+        }
+    }
+    eprintln!("{placed} draws placed in a container");
+}

crates/sylpheed-formats/examples/challenge_map.rs

@@ -0,0 +1,81 @@
+//! RE probe: what does the disc say about CHALLENGE / EXTRA missions?
+//!
+//! The title's stage-config reader (`0x82184b98`..`0x82184e94`) selects one of three
+//! config sections by a mode field at `obj+144`:
+//!   mode == 3        -> "EXTRA"
+//!   mode == 5 or 6   -> "CHALLENGE"
+//!   otherwise        -> "FILE"
+//! so challenge missions are a *mode*, not a separate stage numbering. This probe
+//! asks the disc which stage records exist and what GP_CHALLENGE.pak carries.
+//!
+//! Run: cargo run --release -p sylpheed-formats --example challenge_map -- <disc-root>
+
+use sylpheed_formats::{idxd::IdxdObject, pak::PakArchive};
+
+fn main() {
+    let disc = std::env::args().nth(1).unwrap_or_else(|| {
+        std::env::var("SYLPHEED_DISC").expect("pass disc root or set SYLPHEED_DISC")
+    });
+
+    println!("=== 1. StageResource records in GP_MAIN_GAME_E.pak ===");
+    let arc = PakArchive::open(format!("{disc}/dat/GP_MAIN_GAME_E.pak")).unwrap();
+    let mut rows = vec![];
+    for e in arc.entries() {
+        let Ok(b) = arc.read(e) else { continue };
+        let Ok(o) = IdxdObject::parse(&b) else { continue };
+        if o.schema_hash != 0x3c9ae32e {
+            continue;
+        }
+        let t = o.tokens();
+        let stage = t
+            .iter()
+            .find_map(|s| s.strip_prefix("EnumUnit_").map(|x| x.trim_end_matches(".tbl").to_string()))
+            .unwrap_or("?".into());
+        let bg = o.get_raw("BackGroundID").unwrap_or("?").to_string();
+        rows.push((stage, bg, t.len()));
+    }
+    rows.sort();
+    println!("  {} stage records", rows.len());
+    for (s, bg, n) in &rows {
+        println!("    {s:8} bg={bg:16} tokens={n}");
+    }
+
+    println!("\n=== 2. GP_CHALLENGE.pak contents ===");
+    match PakArchive::open(format!("{disc}/dat/GP_CHALLENGE.pak")) {
+        Ok(ch) => {
+            let mut by_schema: std::collections::BTreeMap<u32, usize> = Default::default();
+            let mut all_tokens: Vec<(u32, Vec<String>)> = vec![];
+            for e in ch.entries() {
+                let Ok(b) = ch.read(e) else { continue };
+                let Ok(o) = IdxdObject::parse(&b) else { continue };
+                *by_schema.entry(o.schema_hash).or_default() += 1;
+                all_tokens.push((o.schema_hash, o.tokens().iter().map(|s| s.to_string()).collect()));
+            }
+            println!("  {} entries, {} IDXD objects", ch.entries().len(), all_tokens.len());
+            for (h, n) in &by_schema {
+                println!("    schema {h:08x}  x{n}");
+            }
+            for (h, t) in all_tokens.iter().take(12) {
+                println!("    -- {h:08x}: {:?}", &t[..t.len().min(60)]);
+            }
+        }
+        Err(e) => println!("  open failed: {e}"),
+    }
+
+    println!("\n=== 3. tokens mentioning Challenge / EX across the main pak ===");
+    let mut hits: std::collections::BTreeSet<String> = Default::default();
+    for e in arc.entries() {
+        let Ok(b) = arc.read(e) else { continue };
+        let Ok(o) = IdxdObject::parse(&b) else { continue };
+        for t in o.tokens() {
+            let l = t.to_ascii_lowercase();
+            if l.contains("challenge") || t.ends_with("_EX") || t.contains("_EX4") || t.contains("_EX5") {
+                hits.insert(format!("{:08x} {t}", o.schema_hash));
+            }
+        }
+    }
+    for h in hits.iter().take(120) {
+        println!("    {h}");
+    }
+    println!("  ({} distinct)", hits.len());
+}

crates/sylpheed-formats/examples/challenge_screen.rs

@@ -0,0 +1,78 @@
+//! RE probe: the GamePart_ChallengeMission screen config.
+//!
+//! The class's code range (`0x82187E60`..`0x8218CF10`, bounded by the factory
+//! creator thunks either side) references these config keys:
+//!   MISSIONS, MISSION_ID, NEW_STAGE, REQUIREMENT, REQUIREMENT_DESC, "Always",
+//!   GRAY_BUTTON, NORMAL_BUTTON, THUMBNAIL, STAGE_DESC, TEXT_STAGE,
+//!   RECORD_TYPE, "Time", TEXT_RECORD, BASE_INFO
+//! i.e. the challenge list is a *config record* with a per-mission REQUIREMENT.
+//! It lives in `tables.pak` (one copy per language), not in GP_CHALLENGE.pak.
+//!
+//! Run: cargo run --release -p sylpheed-formats --example challenge_screen -- <disc-root>
+
+use sylpheed_formats::{idxd::IdxdObject, pak::PakArchive};
+
+const KEYS: &[&str] = &[
+    "MISSIONS",
+    "MISSION_ID",
+    "REQUIREMENT",
+    "REQUIREMENT_DESC",
+    "NEW_STAGE",
+    "GRAY_BUTTON",
+    "NORMAL_BUTTON",
+    "RECORD_TYPE",
+    "THUMBNAIL",
+    "STAGE_DESC",
+];
+
+fn find(h: &[u8], n: &[u8]) -> bool {
+    h.windows(n.len()).any(|w| w == n)
+}
+
+fn main() {
+    let disc = std::env::args().nth(1).unwrap_or_else(|| {
+        std::env::var("SYLPHEED_DISC").expect("pass disc root or set SYLPHEED_DISC")
+    });
+
+    let dat = format!("{disc}/dat");
+    let mut paks: Vec<_> = std::fs::read_dir(&dat)
+        .expect("dat dir")
+        .filter_map(|e| e.ok())
+        .map(|e| e.path())
+        .filter(|p| p.extension().is_some_and(|x| x == "pak"))
+        .collect();
+    paks.sort();
+
+    for p in &paks {
+        let Ok(arc) = PakArchive::open(p) else { continue };
+        for (i, e) in arc.entries().iter().enumerate() {
+            let Ok(b) = arc.read(e) else { continue };
+            if KEYS.iter().filter(|k| find(&b, k.as_bytes())).count() < KEYS.len() {
+                continue;
+            }
+            let name = p.file_name().unwrap().to_string_lossy().to_string();
+            match IdxdObject::parse(&b) {
+                Ok(o) => {
+                    let toks = o.tokens();
+                    // language tag: the PATH value, e.g. "dat\GP_CHALLENGE.pak+eng\"
+                    let lang = toks
+                        .iter()
+                        .find(|t| t.contains("GP_CHALLENGE.pak+"))
+                        .map(|t| t.to_string())
+                        .unwrap_or_default();
+                    println!(
+                        "\n===== {name} entry #{i}  schema {:08x}  {} tokens  [{lang}] =====",
+                        o.schema_hash,
+                        toks.len()
+                    );
+                    // Print the pool in order; the record is key/value interleaved and
+                    // IDXD dedupes repeats, so pairing is read by eye, not asserted.
+                    for (j, t) in toks.iter().enumerate() {
+                        println!("  {j:3}  {t}");
+                    }
+                }
+                Err(e) => println!("\n===== {name} entry #{i}: IDXD parse failed: {e} ====="),
+            }
+        }
+    }
+}

crates/sylpheed-formats/examples/composite_geometry.rs

@@ -0,0 +1,34 @@
+//! How much of the "decoded geometry" belongs to SCENE COMPOSITES rather than to
+//! real meshes? A composite (`rou_*`, `e_rou_*`) carries node transforms; the
+//! anchor scan nevertheless finds a block for it, and that pseudo-geometry lands
+//! in coverage and consistency counts.
+//! Usage: composite_geometry <resource3d_dir>
+use sylpheed_formats::mesh::{scene_world_nodes, Xbg7Model};
+fn main() {
+    let dir = std::env::args().nth(1).expect("resource3d dir");
+    let mut files: Vec<_> = std::fs::read_dir(&dir)
+        .unwrap()
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("xpr"))
+        .collect();
+    files.sort();
+    let (mut total, mut composite, mut composite_named) = (0usize, 0usize, 0usize);
+    for f in &files {
+        let Ok(bytes) = std::fs::read(f) else { continue };
+        for m in Xbg7Model::anchor_models_cancellable(&bytes, 0.0, &|| false) {
+            total += 1;
+            let has_nodes = !scene_world_nodes(&bytes, &m.name).is_empty();
+            let named = m.name.starts_with("rou_") || m.name.starts_with("e_rou_");
+            if has_nodes {
+                composite += 1;
+            }
+            if named {
+                composite_named += 1;
+            }
+        }
+    }
+    println!(
+        "{total} decoded; {composite} have scene nodes (a composite), {composite_named} are named rou_/e_rou_"
+    );
+}

crates/sylpheed-formats/examples/consensus_check.rs

@@ -0,0 +1,87 @@
+//! Minority report: which container decodes a shared resource differently from
+//! all the others?
+//!
+//! Cross-container consistency has been measured as "do the spans agree", which
+//! only says a resource is inconsistent — not which copy is wrong. With three or
+//! more copies the majority is the reference, and the minority names the
+//! container AND the resource to look at. That is what caught the `n054`/`n056`
+//! shift chain after the exact-coverage fix.
+//!
+//! Usage: consensus_check <resource3d_dir> [--list]
+use sylpheed_formats::mesh::Xbg7Model;
+use std::collections::{BTreeMap, HashMap};
+
+fn main() {
+    let dir = std::env::args().nth(1).expect("resource3d dir");
+    let list = std::env::args().any(|a| a == "--list");
+    let mut files: Vec<_> = std::fs::read_dir(&dir)
+        .unwrap()
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("xpr"))
+        .collect();
+    files.sort();
+
+    // name -> [(container, verts, tris, span)]
+    let mut seen: BTreeMap<String, Vec<(String, usize, usize, [i64; 3])>> = BTreeMap::new();
+    for f in &files {
+        let Ok(bytes) = std::fs::read(f) else { continue };
+        let where_ = f.file_name().unwrap().to_string_lossy().to_string();
+        for m in Xbg7Model::anchor_models_cancellable(&bytes, 0.0, &|| false) {
+            let (mut lo, mut hi) = ([f32::MAX; 3], [f32::MIN; 3]);
+            for s in &m.meshes {
+                for q in &s.positions {
+                    for k in 0..3 {
+                        lo[k] = lo[k].min(q[k]);
+                        hi[k] = hi[k].max(q[k]);
+                    }
+                }
+            }
+            if lo[0] == f32::MAX {
+                continue;
+            }
+            let v: usize = m.meshes.iter().map(|s| s.positions.len()).sum();
+            let t: usize = m.meshes.iter().map(|s| s.indices.len() / 3).sum();
+            let span = [
+                (hi[0] - lo[0]).round() as i64,
+                (hi[1] - lo[1]).round() as i64,
+                (hi[2] - lo[2]).round() as i64,
+            ];
+            seen.entry(m.name.clone()).or_default().push((where_.clone(), v, t, span));
+        }
+    }
+
+    let (mut resources, mut minority) = (0usize, 0usize);
+    let mut rows: Vec<String> = Vec::new();
+    for (name, list_) in &seen {
+        // Only compare decodes that agree on how much geometry they found, and
+        // only where a majority can exist.
+        if list_.len() < 3 || !list_.iter().all(|e| e.1 == list_[0].1 && e.2 == list_[0].2) {
+            continue;
+        }
+        let mut votes: HashMap<[i64; 3], usize> = HashMap::new();
+        for e in list_ {
+            *votes.entry(e.3).or_default() += 1;
+        }
+        let (best, n) = votes.iter().max_by_key(|(_, n)| **n).unwrap();
+        if *n * 2 <= list_.len() {
+            continue; // no majority — cannot call anyone the odd one out
+        }
+        resources += 1;
+        for e in list_.iter().filter(|e| e.3 != *best) {
+            minority += 1;
+            rows.push(format!(
+                "{:<22} {name:<26} v={:<6} {:?} vs the other {n} containers' {:?}",
+                e.0, e.1, e.3, best
+            ));
+        }
+    }
+    if list {
+        for r in &rows {
+            println!("{r}");
+        }
+    }
+    println!(
+        "{minority} minority decodes across {resources} resources that have a majority"
+    );
+}

crates/sylpheed-formats/examples/correlate_capture.rs

@@ -16,7 +16,7 @@
 //! Usage:
 //!   SYLPHEED_ISO=... cargo run --release --example correlate_capture -- \
 //!       <capture.log> <Stage_SNN> <ship_id> [ref_part_substr] [--emit]
-//! e.g. SYLPHEED_ISO="/home/fabi/RE Project Sylpheed/Project Sylpheed - Arc of
+//! e.g. SYLPHEED_ISO="/home/fabi/RE - Project Sylpheed/Project Sylpheed - Arc of
 //!      Deception (USA, Europe) (En,Ja).iso" \
 //!      cargo run --release --example correlate_capture -- \
 //!      xenia_ship_capture.log Stage_S01 e106 bdy_04 --emit

crates/sylpheed-formats/examples/coverage_audit.rs

@@ -0,0 +1,48 @@
+//! Do real index buffers address their whole vertex pool?
+//!
+//! `validate_block` rejects a block whose indices reach fewer than `vtx_count−4`
+//! vertices ("buffer not covered"). That gate is the furthest-reached rejection
+//! for a handful of resources that never decode — so the question is whether it
+//! is well founded. This measures the slack on every block that DOES decode: if
+//! real geometry always covers its pool, under-coverage is good evidence of a
+//! wrong candidate and the gate stands.
+use sylpheed_formats::mesh::Xbg7Model;
+use std::collections::BTreeMap;
+
+fn main() {
+    let dir = std::env::args().nth(1).expect("resource3d dir");
+    let mut files: Vec<_> = std::fs::read_dir(&dir)
+        .unwrap()
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("xpr"))
+        .collect();
+    files.sort();
+
+    let mut hist: BTreeMap<i64, usize> = BTreeMap::new();
+    let mut worst: Vec<(i64, String)> = Vec::new();
+    for f in &files {
+        let Ok(bytes) = std::fs::read(f) else { continue };
+        for m in Xbg7Model::anchor_models_cancellable(&bytes, 0.0, &|| false) {
+            for sub in &m.meshes {
+                if sub.positions.is_empty() || sub.indices.is_empty() {
+                    continue;
+                }
+                let max_idx = *sub.indices.iter().max().unwrap() as i64;
+                let slack = sub.positions.len() as i64 - 1 - max_idx;
+                *hist.entry(slack.min(20)).or_default() += 1;
+                if slack > 4 {
+                    worst.push((slack, format!("{} in {}", m.name, f.file_name().unwrap().to_string_lossy())));
+                }
+            }
+        }
+    }
+    println!("unreferenced tail vertices (vtx_count − 1 − max index), over decoded sub-meshes:");
+    for (slack, n) in &hist {
+        println!("  {:>3}{} : {n}", slack, if *slack == 20 { "+" } else { " " });
+    }
+    worst.sort_by_key(|(s, _)| std::cmp::Reverse(*s));
+    for (s, w) in worst.iter().take(5) {
+        println!("  largest slack {s}: {w}");
+    }
+}

crates/sylpheed-formats/examples/cue_unit_check.rs

@@ -0,0 +1,59 @@
+//! Are subtitle cue times really seconds?
+//!
+//! Every "audio missing" verdict in voice-bank-leading-region.md rests on
+//! reading `track_voice_cues`' `f32` as seconds. `parse_timing` does compute
+//! `mm*60 + ss` — but only if the token really is `mm:ss.cc`. The movies are on
+//! the disc, so their true length is an independent oracle: a cue must land
+//! INSIDE its own movie.
+use std::process::Command;
+
+use sylpheed_formats::{movie_subtitle, PakArchive};
+
+fn movie_secs(path: &str) -> Option<f32> {
+    let out = Command::new("ffprobe")
+        .args([
+            "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", path,
+        ])
+        .output()
+        .ok()?;
+    String::from_utf8_lossy(&out.stdout).trim().parse().ok()
+}
+
+fn main() {
+    let disc = std::env::var("SYLPHEED_DISC").expect("set SYLPHEED_DISC");
+    let lang = PakArchive::open(format!("{disc}/dat/movie/eng.pak")).expect("eng.pak");
+
+    let mut checked = 0;
+    let mut over = 0;
+    let mut worst: Vec<(String, f32, f32)> = Vec::new();
+    let dir = format!("{disc}/dat/movie");
+    let Ok(rd) = std::fs::read_dir(&dir) else { return };
+    for e in rd.flatten() {
+        let p = e.path();
+        if p.extension().is_none_or(|x| x != "wmv") {
+            continue;
+        }
+        let base = p.file_stem().unwrap().to_string_lossy().to_string();
+        let cues = movie_subtitle::track_voice_cues(&lang, &base);
+        if cues.is_empty() {
+            continue;
+        }
+        let last = cues.iter().map(|(_, t)| *t).fold(0.0f32, f32::max);
+        let Some(secs) = movie_secs(&p.to_string_lossy()) else { continue };
+        checked += 1;
+        if last > secs {
+            over += 1;
+            worst.push((base, last, secs));
+        }
+    }
+    worst.sort_by(|a, b| (b.1 - b.2).partial_cmp(&(a.1 - a.2)).unwrap());
+    println!("movies with cues checked: {checked}");
+    println!("cues landing AFTER the movie ends: {over}");
+    for (m, last, secs) in worst.iter().take(8) {
+        println!("  {m:<28} last cue {last:>8.2}s  movie {secs:>8.2}s");
+    }
+    println!(
+        "\nIf cues were centiseconds the last cue would be ~100x too big and \
+         essentially all {checked} would overflow."
+    );
+}

crates/sylpheed-formats/examples/decl_word_probe.rs

@@ -0,0 +1,67 @@
+//! Does any unread declaration word POINT at the element's T8aD child?
+//!
+//! `pteff05.t32`/`pteff04.t32` resolve to no sprite because the `T8aD` they want
+//! is registered under the name `8AX`. Elimination says `8AX` is the one they
+//! mean -- one unresolved element, one unclaimed non-focus-state child, in 6 of
+//! 6 title-side builds. Elimination is not a pointer, so: the 60-byte
+//! declaration reads name[0..28], parent@32, kind@40, pivot@48/52. The words at
+//! +28, +36, +44 and +56 are unread. If one of them indexes the RATC child
+//! table, the RESOLVED elements are the control -- their child index is known,
+//! so a candidate field must reproduce it for them before it may be believed for
+//! the unresolved one.
+//!
+//!     cargo run -p sylpheed-formats --example decl_word_probe -- <pak> [entry]
+use sylpheed_formats::{pak, ratc, ui_layout};
+
+const OFFS: [usize; 4] = [28, 36, 44, 56];
+
+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 path = std::env::args().nth(1).expect("usage: decl_word_probe <pak> [entry]");
+    let want: Option<usize> = std::env::args().nth(2).and_then(|s| s.parse().ok());
+    let ar = pak::PakArchive::open(&path).expect("open pak");
+    let entries: Vec<_> = ar.entries().to_vec();
+    // Per candidate offset, across every build: control hits / control total.
+    let mut hit = [0usize; 4];
+    let mut tot = 0usize;
+    for (i, e) in entries.iter().enumerate() {
+        if want.is_some_and(|w| w != i) { continue; }
+        let Ok(bytes) = ar.read(e) else { continue };
+        let Some(build) = ui_layout::parse_build(&bytes) else { continue };
+        let Some(kids) = ratc::parse(&bytes) else { continue };
+        // Index space to test against: the T8aD children, in child order.
+        let t8: Vec<&ratc::RatcChild> = kids.iter().filter(|c| c.kind == "T8aD").collect();
+        if build.elements.iter().all(|el| el.sprite.is_some() || el.kind & 0x10 != 0) {
+            continue;
+        }
+        println!("== entry {i}  ({} elements, {} T8aD children)", build.elements.len(), t8.len());
+        for (n, c) in t8.iter().enumerate() { println!("     child[{n:2}] {}", c.name); }
+        for el in &build.elements {
+            if el.kind & 0x10 != 0 { continue; }
+            let d = &bytes[0x20 + el.index * 60..0x20 + (el.index + 1) * 60];
+            let words: Vec<u32> = OFFS.iter().map(|&o| be32(d, o)).collect();
+            // The control: for a RESOLVED element, which T8aD child is it?
+            let truth = el.sprite.as_ref()
+                .and_then(|s| t8.iter().position(|c| &c.name == s));
+            if let Some(t) = truth {
+                tot += 1;
+                for (k, w) in words.iter().enumerate() {
+                    if *w as usize == t { hit[k] += 1; }
+                }
+            }
+            println!(
+                "   [{:2}] {:26} sprite={:?} child={:?}  +28={} +36={} +44={} +56={}",
+                el.index, el.name, el.sprite, truth,
+                words[0] as i32, words[1] as i32, words[2] as i32, words[3] as i32
+            );
+        }
+    }
+    println!("\nCONTROL: resolved elements whose child index a word reproduces, of {tot}:");
+    for (k, o) in OFFS.iter().enumerate() {
+        println!("   +{o:<3} {:3}/{tot}", hit[k]);
+    }
+}

crates/sylpheed-formats/examples/desc_dump.rs

@@ -0,0 +1,71 @@
+//! Dump an XBG7 resource's descriptor around each index marker, to see whether a
+//! grouped pool carries a declaration PER sub-mesh (the 2026-08-13 mixed-stride
+//! finding says it must: n201's four sub-meshes use strides 24/24/24/28 and four
+//! different vertex shaders).
+//! Usage: desc_dump <container.xpr> <resource>
+
+fn be32(b: &[u8], o: usize) -> u32 {
+    u32::from_be_bytes(b[o..o + 4].try_into().unwrap())
+}
+
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let bytes = std::fs::read(&a[1]).unwrap();
+    let want = &a[2];
+    // Walk the XPR2 directory by hand (the crate's reader is private).
+    // 16-byte directory entries at 0x10: type tag, data offset, descriptor size,
+    // name offset — all relative to 0x10 (see texture::Xpr2ResourceEntry).
+    let num = be32(&bytes, 12) as usize;
+    for i in 0..num {
+        let e = &bytes[0x10 + i * 16..0x10 + i * 16 + 16];
+        let tag = &e[0..4];
+        let data_off = be32(e, 4) as usize + 0x10;
+        let desc_size = be32(e, 8) as usize;
+        let name_off = be32(e, 12) as usize + 0x10;
+        if tag != b"XBG7" {
+            continue;
+        }
+        let name = {
+            let s = name_off.min(bytes.len());
+            let end = bytes[s..].iter().position(|&c| c == 0).unwrap_or(0) + s;
+            String::from_utf8_lossy(&bytes[s..end]).to_string()
+        };
+        if name != *want {
+            continue;
+        }
+        let desc = &bytes[data_off..(data_off + desc_size).min(bytes.len())];
+        println!("{name}: descriptor at 0x{data_off:X}, {} bytes", desc.len());
+        // markers: a == c*2, c%3==0, vertex count 32 bytes earlier
+        let mut rel = 0usize;
+        while rel + 8 <= desc.len() {
+            let (x, c) = (be32(desc, rel), be32(desc, rel + 4));
+            if c >= 3 && c % 3 == 0 && c < 400_000 && x == c * 2 && rel >= 32 {
+                let vc = be32(desc, rel - 32);
+                if (3..=200_000).contains(&vc) {
+                    println!("\n  marker @0x{rel:X}: {vc} verts / {c} indices — declaration triples after it:");
+                    let mut r = rel + 8;
+                    let mut stride = 0u32;
+                    for _ in 0..12 {
+                        if r + 12 > desc.len() {
+                            break;
+                        }
+                        let (o, code, usage) = (be32(desc, r), be32(desc, r + 4), be32(desc, r + 8) >> 16);
+                        if o == 0x00FF_0000 || code == 0xFFFF_FFFF || o > 0x1000 {
+                            println!("    end marker @0x{r:X}: off=0x{o:X} code=0x{code:X}");
+                            break;
+                        }
+                        println!("    off {o:>3}  code 0x{:06X}  usage {usage}", code & 0xFF_FFFF);
+                        stride = stride.max(o + 4);
+                        r += 12;
+                    }
+                    println!("    (min stride from element offsets: {stride})");
+                    rel += 8;
+                    continue;
+                }
+            }
+            rel += 4;
+        }
+        return;
+    }
+    eprintln!("resource not found");
+}

crates/sylpheed-formats/examples/edge_cap_sweep.rs

@@ -0,0 +1,80 @@
+//! Calibrate the connectivity cap against the whole disc.
+//!
+//! `XBG7_EDGE_CAP` sets the cap; this reports, for one setting, how much
+//! geometry decodes and how self-consistent it is across containers — the two
+//! numbers any change to the cap has to trade off. Run it once per cap value.
+use sylpheed_formats::mesh::Xbg7Model;
+use std::collections::BTreeMap;
+
+fn main() {
+    let dir = std::env::args().nth(1).expect("resource3d dir");
+    let mut files: Vec<_> = std::fs::read_dir(&dir)
+        .unwrap()
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("xpr"))
+        .collect();
+    files.sort();
+
+    // name -> (verts, tris) -> spans seen, exactly as mesh_consistency_disc.rs.
+    let mut seen: BTreeMap<String, Vec<([i64; 3], usize, usize)>> = BTreeMap::new();
+    let (mut models, mut verts) = (0usize, 0usize);
+    for f in &files {
+        let Ok(bytes) = std::fs::read(f) else { continue };
+        for m in Xbg7Model::anchor_models_cancellable(&bytes, 0.0, &|| false) {
+            let (mut lo, mut hi) = ([f32::MAX; 3], [f32::MIN; 3]);
+            for s in &m.meshes {
+                for q in &s.positions {
+                    for k in 0..3 {
+                        lo[k] = lo[k].min(q[k]);
+                        hi[k] = hi[k].max(q[k]);
+                    }
+                }
+            }
+            if lo[0] == f32::MAX {
+                continue;
+            }
+            let v: usize = m.meshes.iter().map(|s| s.positions.len()).sum();
+            let t: usize = m.meshes.iter().map(|s| s.indices.len() / 3).sum();
+            models += 1;
+            verts += v;
+            if std::env::var("DUMP").is_ok() {
+                // Per-resource signature, so two cap settings can be diffed:
+                // a cap change that silently MOVES an existing anchor is the
+                // risk a coverage count cannot see.
+                println!(
+                    "{}|{}|{v}|{t}|{}|{}|{}|{}",
+                    f.file_name().unwrap().to_string_lossy(),
+                    m.name,
+                    m.meshes[0].vbuf_offset.unwrap_or(0),
+                    (hi[0] - lo[0]).round() as i64,
+                    (hi[1] - lo[1]).round() as i64,
+                    (hi[2] - lo[2]).round() as i64
+                );
+            }
+            seen.entry(m.name.clone()).or_default().push((
+                [
+                    (hi[0] - lo[0]).round() as i64,
+                    (hi[1] - lo[1]).round() as i64,
+                    (hi[2] - lo[2]).round() as i64,
+                ],
+                v,
+                t,
+            ));
+        }
+    }
+    let (mut shared, mut inconsistent) = (0usize, 0usize);
+    for (_, list) in &seen {
+        if list.len() < 2 || !list.iter().all(|e| e.1 == list[0].1 && e.2 == list[0].2) {
+            continue;
+        }
+        shared += 1;
+        if list.iter().any(|e| e.0 != list[0].0) {
+            inconsistent += 1;
+        }
+    }
+    println!(
+        "cap={}  models={models}  verts={verts}  shared={shared}  inconsistent={inconsistent}",
+        std::env::var("XBG7_EDGE_CAP").unwrap_or_else(|_| "library default".into())
+    );
+}

crates/sylpheed-formats/examples/envelope_screen.rs

@@ -0,0 +1,106 @@
+//! Does every part of a ship sit inside the envelope its siblings describe?
+//!
+//! `slab_screen` compared *scale* and could not see the `e106` slab. What the eye
+//! used when the render exposed it was **relationship**: a blocky mass sitting
+//! apart from the hull. This measures that — assemble a ship, and for each part
+//! ask how far its world box protrudes beyond the box of all the OTHER parts,
+//! relative to the ship's own size. A mis-anchored block sticks out; a real part,
+//! however big, is part of the silhouette.
+//!
+//! Usage: envelope_screen <resource3d_dir> [protrusion_fraction]
+use sylpheed_formats::mesh::Xbg7Model;
+use sylpheed_formats::ship::{assemble_ship, ship_id_of};
+use std::collections::{BTreeSet, HashSet};
+
+fn main() {
+    let dir = std::env::args().nth(1).expect("resource3d dir");
+    let limit: f32 = std::env::args().nth(2).and_then(|s| s.parse().ok()).unwrap_or(0.35);
+    let mut files: Vec<_> = std::fs::read_dir(&dir)
+        .unwrap()
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("xpr"))
+        .collect();
+    files.sort();
+
+    let mut flagged = 0usize;
+    for f in &files {
+        let Ok(bytes) = std::fs::read(f) else { continue };
+        let ids: BTreeSet<String> = Xbg7Model::anchor_models_cancellable(&bytes, 0.0, &|| false)
+            .iter()
+            .filter_map(|m| ship_id_of(&m.name).map(|s| s.to_string()))
+            .collect();
+        for id in &ids {
+            let placed = assemble_ship(&bytes, id, true);
+            if placed.len() < 3 {
+                continue;
+            }
+            let want: HashSet<String> = placed.iter().map(|p| p.resource.clone()).collect();
+            let models = Xbg7Model::models_named(&bytes, &want, &|| false);
+            // World box per placement.
+            let mut boxes: Vec<(String, [f32; 3], [f32; 3])> = Vec::new();
+            for p in &placed {
+                let Some(m) = models.iter().find(|m| m.name == p.resource) else { continue };
+                let (mut lo, mut hi) = ([f32::MAX; 3], [f32::MIN; 3]);
+                for s in &m.meshes {
+                    for q in &s.positions {
+                        let w = p.apply(*q);
+                        for k in 0..3 {
+                            lo[k] = lo[k].min(w[k]);
+                            hi[k] = hi[k].max(w[k]);
+                        }
+                    }
+                }
+                if lo[0] != f32::MAX {
+                    boxes.push((p.resource.clone(), lo, hi));
+                }
+            }
+            if boxes.len() < 3 {
+                continue;
+            }
+            for i in 0..boxes.len() {
+                // Envelope of every OTHER part.
+                let (mut lo, mut hi) = ([f32::MAX; 3], [f32::MIN; 3]);
+                for (j, b) in boxes.iter().enumerate() {
+                    if i == j {
+                        continue;
+                    }
+                    for k in 0..3 {
+                        lo[k] = lo[k].min(b.1[k]);
+                        hi[k] = hi[k].max(b.2[k]);
+                    }
+                }
+                // Per-AXIS: a bow legitimately extends the ship along its long
+                // axis, so protrusion only means something measured against the
+                // envelope's size IN THAT AXIS. The e106 slab stuck ~1 500 out in
+                // Y where its siblings spanned ~800.
+                let mut worst = 0.0f32;
+                let mut worst_out = 0.0f32;
+                for k in 0..3 {
+                    let size_k = hi[k] - lo[k];
+                    if size_k <= 1.0 {
+                        continue;
+                    }
+                    let out_k = (lo[k] - boxes[i].1[k]).max(boxes[i].2[k] - hi[k]).max(0.0);
+                    if out_k / size_k > worst {
+                        worst = out_k / size_k;
+                        worst_out = out_k;
+                    }
+                }
+                let (out, size) = (worst_out, 1.0f32);
+                let _ = size;
+                if worst > limit {
+                    flagged += 1;
+                    println!(
+                        "{:<20} {:<22} protrudes {:>7.0} beyond its siblings ({:.0}% of the ship)",
+                        f.file_name().unwrap().to_string_lossy(),
+                        boxes[i].0,
+                        out,
+                        100.0 * worst
+                    );
+                }
+            }
+        }
+    }
+    println!("{flagged} parts protrude more than {:.0}% of their ship's size", 100.0 * limit);
+}

crates/sylpheed-formats/examples/filter_consistency.rs

@@ -0,0 +1,35 @@
+//! Does a FILTERED decode agree with the full one?
+//!
+//! Distinct anchor assignment resolves collisions against the set of resources
+//! being decoded — so `models_named` (a filtered subset, used by the ship
+//! assembler and the viewer) can reach a different answer from a whole-container
+//! decode. This measures that directly.
+//! Usage: filter_consistency <container.xpr> [resource...]
+use sylpheed_formats::mesh::Xbg7Model;
+use std::collections::HashSet;
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let bytes = std::fs::read(&a[1]).expect("container");
+    let full = Xbg7Model::anchor_models_cancellable(&bytes, 0.0, &|| false);
+    let names: Vec<String> = if a.len() > 2 {
+        a[2..].to_vec()
+    } else {
+        full.iter().map(|m| m.name.clone()).collect()
+    };
+    let mut differ = 0usize;
+    for n in &names {
+        let want: HashSet<String> = std::iter::once(n.clone()).collect();
+        let one = Xbg7Model::models_named(&bytes, &want, &|| false);
+        let (Some(f), Some(s)) = (full.iter().find(|m| &m.name == n), one.first()) else {
+            continue;
+        };
+        let off = |m: &Xbg7Model| m.meshes.first().and_then(|s| s.vbuf_offset).unwrap_or(0);
+        if off(f) != off(s) {
+            differ += 1;
+            if differ <= 10 {
+                println!("{n}: full decode at 0x{:x}, filtered at 0x{:x}", off(f), off(s));
+            }
+        }
+    }
+    println!("{differ} of {} resources decode differently when filtered", names.len());
+}

crates/sylpheed-formats/examples/find_ib.rs

@@ -0,0 +1,27 @@
+//! Where could a resource's index buffer be, given the vertex buffer a runtime
+//! capture proves the engine drew from? Tests the anchor scan's adjacency
+//! assumption against ground truth.
+use sylpheed_formats::mesh::{debug_find_index_buffer, debug_resource_params};
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let bytes = std::fs::read(&a[1]).unwrap();
+    for pair in a[2..].iter() {
+        let (name, off) = pair.split_once('@').unwrap();
+        let vb = usize::from_str_radix(off.trim_start_matches("0x"), 16).unwrap();
+        let params = debug_resource_params(&bytes, name);
+        let markers = params.as_ref().map(|(m, _)| m.clone()).unwrap_or_default();
+        println!("{name} @ 0x{vb:x}  markers={markers:?}");
+        let hits = debug_find_index_buffer(&bytes, name, vb);
+        if hits.is_empty() {
+            println!("   no index buffer anywhere in the container validates this block");
+        }
+        let mut hits = hits;
+        hits.sort_by_key(|(_, d)| d.abs());
+        for (ib, d) in hits.iter().take(8) {
+            println!("   ib 0x{ib:x}  vb-ib = {d} bytes");
+        }
+        if hits.len() > 8 {
+            println!("   … {} total", hits.len());
+        }
+    }
+}

crates/sylpheed-formats/examples/find_mirror.rs

@@ -0,0 +1,44 @@
+//! Does the container hold an X-mirrored copy of a resource's decoded buffer?
+//!
+//! The twin invariant (see `twin_mirror_audit`) flags `…_01`/`…_02` pairs that
+//! decode to unrelated geometry. If the mirror of one twin's buffer exists
+//! somewhere else in the container, that offset is where the other twin belongs
+//! and the pair is a mis-anchor; if it does not exist, the pair is simply not a
+//! mirrored pair.
+//!
+//! Usage: find_mirror <container.xpr> <resource>...
+use sylpheed_formats::mesh::Xbg7Model;
+use std::collections::HashSet;
+
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let bytes = std::fs::read(&a[1]).expect("container");
+    let want: HashSet<String> = a[2..].iter().cloned().collect();
+    let models = Xbg7Model::models_named(&bytes, &want, &|| false);
+    let be = |at: usize| f32::from_be_bytes(bytes[at..at + 4].try_into().unwrap());
+
+    for m in &models {
+        let pos: Vec<[f32; 3]> = m.meshes.iter().flat_map(|s| s.positions.clone()).take(8).collect();
+        if pos.len() < 8 {
+            continue;
+        }
+        let anchored = m.meshes[0].vbuf_offset.unwrap_or(0);
+        let (mut direct, mut mirror) = (Vec::new(), Vec::new());
+        for o in (0..bytes.len().saturating_sub(12 + 8 * 24)).step_by(4) {
+            for (flip, out) in [(1.0f32, &mut direct), (-1.0f32, &mut mirror)] {
+                if (0..8).all(|k| {
+                    let at = o + k * 24;
+                    (be(at) - flip * pos[k][0]).abs() <= 1e-4
+                        && (be(at + 4) - pos[k][1]).abs() <= 1e-4
+                        && (be(at + 8) - pos[k][2]).abs() <= 1e-4
+                }) {
+                    out.push(o);
+                }
+            }
+        }
+        println!(
+            "{:<20} anchored 0x{anchored:x}  direct copies {:x?}  mirrored copies {:x?}",
+            m.name, direct, mirror
+        );
+    }
+}

crates/sylpheed-formats/examples/flights.rs

@@ -7,10 +7,10 @@ fn main(){
     let mut seen=std::collections::BTreeSet::new(); let mut shown=0;
     println!("{} pilot-roster configs; distinct line-ups:", rosters.len());
     for r in &rosters{
-        let key:String=r.pilots.iter().map(|(c,p)|format!("{c}:{p}")).collect::<Vec<_>>().join(",");
+        let key:String=r.pilots().iter().map(|(c,p)|format!("{c}:{p}")).collect::<Vec<_>>().join(",");
         if seen.insert(key) && shown<8 {
             shown+=1;
-            let flt:Vec<String>=r.pilots.iter().map(|(c,p)|format!("{c}={p}")).collect();
+            let flt:Vec<String>=r.pilots().iter().map(|(c,p)|format!("{c}={p}")).collect();
             println!("  {}", flt.join("  "));
         }
     }

crates/sylpheed-formats/examples/gate_histogram.rs

@@ -0,0 +1,60 @@
+//! Which gate stops the resources that never decode?
+//! Usage: gate_histogram <resource3d_dir> [max_resources]
+use sylpheed_formats::mesh::{debug_best_rejection, xbg7_resource_names, Xbg7Model};
+use std::collections::{BTreeMap, HashSet};
+
+fn main() {
+    let dir = std::env::args().nth(1).expect("resource3d dir");
+    let cap: usize = std::env::args().nth(2).and_then(|s| s.parse().ok()).unwrap_or(usize::MAX);
+    let mut files: Vec<_> = std::fs::read_dir(&dir)
+        .unwrap()
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("xpr"))
+        .collect();
+    files.sort();
+
+    let mut hist: BTreeMap<usize, (usize, String)> = BTreeMap::new();
+    let mut done = 0usize;
+    for f in &files {
+        if done >= cap {
+            break;
+        }
+        let Ok(bytes) = std::fs::read(f) else { continue };
+        let names = xbg7_resource_names(&bytes);
+        if names.is_empty() {
+            continue;
+        }
+        let got: HashSet<String> = Xbg7Model::anchor_models_cancellable(&bytes, 0.0, &|| false)
+            .into_iter()
+            .map(|m| m.name)
+            .collect();
+        for n in names.iter().filter(|n| !got.contains(*n)) {
+            if done >= cap {
+                break;
+            }
+            done += 1;
+            if let Some((rank, why)) = debug_best_rejection(&bytes, n) {
+                let e = hist.entry(rank).or_insert((0, String::new()));
+                e.0 += 1;
+                if e.1.is_empty() {
+                    e.1 = format!("{n}: {why}");
+                }
+            }
+        }
+    }
+    println!("furthest gate reached, over {done} resources that never decode:");
+    let label = |r: usize| match r {
+        0 => "no gate reached",
+        1 => "index out of range",
+        2 => "buffer not covered by indices",
+        3 => "degenerate / implausible positions",
+        4 => "connectivity (mean edge / diagonal)",
+        5 => "winding consistency",
+        9 => "grouped pool (different path)",
+        _ => "?",
+    };
+    for (r, (n, ex)) in &hist {
+        println!("  {:<38} {n:>5}   e.g. {ex}", label(*r));
+    }
+}

crates/sylpheed-formats/examples/grouped_report.rs

@@ -0,0 +1,2 @@
+fn main(){let a:Vec<String>=std::env::args().collect();let b=std::fs::read(&a[1]).unwrap();
+for l in sylpheed_formats::mesh::debug_grouped_report(&b,&a[2],a[3].parse().unwrap()){println!("{l}")}}

crates/sylpheed-formats/examples/index_hash_dump.rs

@@ -0,0 +1,32 @@
+//! Dump a fingerprint of every decoded index run, so two decoder settings can be
+//! diffed exactly. Usage: index_hash_dump <resource3d_dir>
+use sylpheed_formats::mesh::Xbg7Model;
+
+fn main() {
+    let dir = std::env::args().nth(1).expect("resource3d dir");
+    let mut files: Vec<_> = std::fs::read_dir(&dir)
+        .unwrap()
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("xpr"))
+        .collect();
+    files.sort();
+    for f in &files {
+        let Ok(bytes) = std::fs::read(f) else { continue };
+        let w = f.file_name().unwrap().to_string_lossy().to_string();
+        for m in Xbg7Model::stage_models(&bytes) {
+            for (k, sm) in m.meshes.iter().enumerate() {
+                let mut h = 1469598103934665603u64;
+                for i in &sm.indices {
+                    h = (h ^ *i as u64).wrapping_mul(1099511628211);
+                }
+                println!(
+                    "{w} {} {k} vb={:?} n={} h={h:016x}",
+                    m.name,
+                    sm.vbuf_offset,
+                    sm.indices.len()
+                );
+            }
+        }
+    }
+}

crates/sylpheed-formats/examples/index_pad_check.rs

@@ -0,0 +1,134 @@
+//! Is our index list one element late? A capture-free check of the `pad` choice.
+//!
+//! `anchor_pool_mesh` tries `ib = vb − idx_count*2 − pad` for `pad` in `0..=3`,
+//! **pad 0 first and with the looser winding gate** (`XBG7_PAD0_CONSISTENCY`,
+//! 0.70) than the pad ≥ 1 path (0.85). The 2026-08-13 index-byte comparison
+//! against the runtime showed 17 draw batches whose captured indices equal our
+//! decoded list shifted by exactly one element — all of them on buffers whose
+//! real index data sits at pad 2. A one-element shift re-wires every triangle,
+//! and it is invisible to every count-based metric (the count, the coverage and
+//! the positions are all still right).
+//!
+//! This reproduces that finding from the container alone: for each resource it
+//! reads the index run at pad 0 and at pad 2 and scores both on two properties a
+//! correct triangle list has — **no degenerate triangles** (two equal indices)
+//! and consistent winding against the stored normals.
+//!
+//! Usage: index_pad_check <container.xpr> [name-substring]
+use sylpheed_formats::mesh::Xbg7Model;
+
+fn be16(b: &[u8], at: usize) -> u32 {
+    ((b[at] as u32) << 8) | b[at + 1] as u32
+}
+
+/// Degenerate triangles (a repeated index) and the fraction of triangles whose
+/// face normal agrees with their vertices' stored normals.
+fn score(idx: &[u32], pos: &[[f32; 3]], nrm: &[[f32; 3]]) -> (usize, f32, usize) {
+    let mut degen = 0usize;
+    let mut agree = 0usize;
+    let mut counted = 0usize;
+    for t in idx.chunks_exact(3) {
+        let (a, b, c) = (t[0] as usize, t[1] as usize, t[2] as usize);
+        if a == b || b == c || a == c {
+            degen += 1;
+            continue;
+        }
+        if a >= pos.len() || b >= pos.len() || c >= pos.len() {
+            continue;
+        }
+        let e1 = [pos[b][0] - pos[a][0], pos[b][1] - pos[a][1], pos[b][2] - pos[a][2]];
+        let e2 = [pos[c][0] - pos[a][0], pos[c][1] - pos[a][1], pos[c][2] - pos[a][2]];
+        let f = [
+            e1[1] * e2[2] - e1[2] * e2[1],
+            e1[2] * e2[0] - e1[0] * e2[2],
+            e1[0] * e2[1] - e1[1] * e2[0],
+        ];
+        if nrm.len() <= a {
+            continue;
+        }
+        let n = nrm[a];
+        let dot = f[0] * n[0] + f[1] * n[1] + f[2] * n[2];
+        counted += 1;
+        if dot > 0.0 {
+            agree += 1;
+        }
+    }
+    let frac = if counted == 0 { 0.0 } else { agree as f32 / counted as f32 };
+    (degen, frac.max(1.0 - frac), counted)
+}
+
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let bytes = std::fs::read(&a[1]).expect("container");
+    let filter = a.get(2).cloned().unwrap_or_default();
+
+    let models = Xbg7Model::stage_models(&bytes);
+    println!(
+        "{:<22} {:>6} {:>6}  {:<26} {:<26} verdict",
+        "resource", "verts", "idx", "pad 0 (what we decode)", "pad 2 (2 bytes earlier)"
+    );
+    let (mut better_p2, mut better_p0, mut tie) = (0usize, 0usize, 0usize);
+    let mut hist_ok: Vec<(usize, String, usize)> = Vec::new();
+    for m in &models {
+        if !filter.is_empty() && !m.name.contains(&filter) {
+            continue;
+        }
+        if m.meshes.len() != 1 {
+            continue; // single-block path only; grouped pools use another formula
+        }
+        let sm = &m.meshes[0];
+        let Some(vb) = sm.vbuf_offset else { continue };
+        let n = sm.indices.len();
+        if n < 6 || sm.normals.is_empty() || vb < n * 2 + 2 {
+            continue;
+        }
+        let read_at = |start: usize| -> Vec<u32> { (0..n).map(|k| be16(&bytes, start + k * 2)).collect() };
+        let l0 = read_at(vb - n * 2);
+        let l2 = read_at(vb - n * 2 - 2);
+        // Sanity: l0 must be what the decoder emitted, or the assumption that we
+        // took pad 0 is wrong for this resource and the comparison is meaningless.
+        let took_pad0 = l0 == sm.indices;
+        if !took_pad0 {
+            continue;
+        }
+        let (d0, c0, _) = score(&l0, &sm.positions, &sm.normals);
+        let (d2, c2, _) = score(&l2, &sm.positions, &sm.normals);
+        let max_i0 = l0.iter().max().copied().unwrap_or(0);
+        let max_i2 = l2.iter().max().copied().unwrap_or(0);
+        let v = sm.positions.len() as u32;
+        // A shifted list typically also overruns the pool by one vertex or leaves
+        // the last vertex unreferenced, so carry the coverage as evidence too.
+        let verdict = if d2 < d0 && c2 >= c0 {
+            better_p2 += 1;
+            "pad 2 is the real one"
+        } else if d0 < d2 || c0 > c2 {
+            better_p0 += 1;
+            "pad 0 fine"
+        } else {
+            tie += 1;
+            "indistinguishable"
+        };
+        if verdict == "pad 0 fine" {
+            hist_ok.push((d0, m.name.clone(), n));
+        }
+        if verdict != "pad 0 fine" || !filter.is_empty() {
+            println!(
+                "{:<22} {:>6} {:>6}  degen {:>5} wind {:.3} max {:<5}  degen {:>5} wind {:.3} max {:<5}  {}",
+                m.name, v, n, d0, c0, max_i0, d2, c2, max_i2, verdict
+            );
+        }
+    }
+    println!("\npad 2 wins: {better_p2} · pad 0 wins: {better_p0} · indistinguishable: {tie}");
+    // Is "no degenerate triangle" a safe invariant for a correctly anchored
+    // block? Distribution over the resources where pad 0 is the better choice.
+    let zero = hist_ok.iter().filter(|(d, _, _)| *d == 0).count();
+    println!(
+        "of the {} pad-0-correct resources, {zero} have ZERO degenerate triangles",
+        hist_ok.len()
+    );
+    let mut worst: Vec<_> = hist_ok.iter().filter(|(d, _, _)| *d > 0).collect();
+    worst.sort_by_key(|(d, _, _)| std::cmp::Reverse(*d));
+    for (d, n, idx) in worst.iter().take(10) {
+        println!("  {n}: {d} degenerate of {} triangles", idx / 3);
+    }
+}

crates/sylpheed-formats/examples/live_offsets.rs

@@ -0,0 +1,90 @@
+//! Where does each declared field sit inside the engine's live definition object?
+//!
+//! A live object carries no names, so the mapping has to be inferred: take a unit
+//! whose disc record SETS a field, look for that value in the dumped words of the
+//! matching live object, and keep the offsets that agree across several units.
+//!
+//! Run: live_offsets <disc-root> <live-dump.txt> <ID=0xVA> ...
+//!   e.g. … UN_f106_TCAF_Destroyer=0xbd3ee300 UN_f105_TCAF_Cruiser=0xbd40e200
+use std::collections::BTreeMap;
+use sylpheed_formats::idxd::IdxdObject;
+use sylpheed_formats::pak::PakArchive;
+
+fn main() {
+    let mut a = std::env::args().skip(1);
+    let disc = a.next().expect("disc root");
+    let dump = a.next().expect("live dump");
+    let pairs: Vec<(String, String)> = a
+        .filter_map(|s| s.split_once('=').map(|(i, v)| (i.to_string(), v.to_string())))
+        .collect();
+
+    // live: va -> offset -> f32
+    let mut live: BTreeMap<String, BTreeMap<usize, f32>> = BTreeMap::new();
+    let mut cur = String::new();
+    for line in std::fs::read_to_string(&dump).expect("dump").lines() {
+        if let Some(rest) = line.strip_prefix("=== ") {
+            cur = rest.trim().to_string();
+            continue;
+        }
+        let f: Vec<&str> = line.split_whitespace().collect();
+        if f.len() >= 4 && f[1].starts_with('+') {
+            if let (Ok(off), Ok(val)) =
+                (usize::from_str_radix(&f[1][1..], 16), f[3].parse::<f32>())
+            {
+                live.entry(cur.clone()).or_default().insert(off, val);
+            }
+        }
+    }
+
+    let pak = PakArchive::open(format!("{disc}/dat/GP_MAIN_GAME_E.pak")).expect("pak");
+    // key -> offset -> how many units agree
+    let mut votes: BTreeMap<String, BTreeMap<usize, usize>> = BTreeMap::new();
+    let mut units = 0usize;
+    for entry in pak.entries() {
+        let Ok(bytes) = pak.read(entry) else { continue };
+        let Ok(obj) = IdxdObject::parse(&bytes) else { continue };
+        let Some(id) = obj.get_raw("ID") else { continue };
+        let Some((_, va)) = pairs.iter().find(|(i, _)| i == id) else { continue };
+        let Some(words) = live.get(va) else { continue };
+        units += 1;
+        let mut numeric = 0usize;
+        let mut hit = 0usize;
+        for key in obj.tokens() {
+            let Some(v) = obj.get_f32(key) else { continue };
+            if !v.is_finite() || v == 0.0 {
+                continue; // zero matches everywhere and says nothing
+            }
+            numeric += 1;
+            let mut found = false;
+            for (off, w) in words {
+                if (*w - v).abs() <= v.abs() * 1e-6 {
+                    *votes.entry(key.clone()).or_default().entry(*off).or_default() += 1;
+                    found = true;
+                }
+            }
+            if found {
+                hit += 1;
+            }
+        }
+        eprintln!("  {id}: {numeric} numeric fields set on disc, {hit} found in the dumped window");
+    }
+    println!("{units} units correlated against their live objects\n");
+    println!("{:<28} {:>8}  offsets agreeing (votes)", "field", "unique?");
+    for (key, offs) in &votes {
+        let best = offs.iter().max_by_key(|(_, n)| **n).unwrap();
+        if *best.1 < units.max(2) {
+            continue; // needs every correlated unit to agree
+        }
+        let list: Vec<String> = offs
+            .iter()
+            .filter(|(_, n)| **n == *best.1)
+            .map(|(o, n)| format!("+{o:03x}×{n}"))
+            .collect();
+        println!(
+            "{:<28} {:>8}  {}",
+            key,
+            if list.len() == 1 { "unique" } else { "ambig" },
+            list.join(" ")
+        );
+    }
+}

crates/sylpheed-formats/examples/locate_draw.rs

@@ -0,0 +1,53 @@
+//! How many copies of a captured buffer does a container hold?
+//!
+//! The twins showed that two resources decoding to one buffer can mean the
+//! container really holds two (mirrored) copies and our scan found only one.
+//! This asks that question for any draw: give it a `vbase`, and it reports every
+//! offset whose leading vertices match the draw's dumped positions — directly, and
+//! X-mirrored.
+//!
+//! Usage: locate_draw <container.xpr> <capture.log> <vbase-hex>...
+use sylpheed_formats::ship_capture::{parse_capture, parse_drawlog};
+
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let bytes = std::fs::read(&a[1]).expect("container");
+    let text = std::fs::read_to_string(&a[2]).expect("log");
+    let mut draws = parse_capture(&text);
+    if draws.is_empty() {
+        draws = parse_drawlog(&text);
+    }
+    let be = |at: usize| f32::from_be_bytes(bytes[at..at + 4].try_into().unwrap());
+
+    for want in &a[3..] {
+        let vb = u32::from_str_radix(want.trim_start_matches("0x"), 16).expect("hex vbase");
+        let Some(d) = draws.iter().find(|d| d.vbase == vb) else {
+            println!("vbase 0x{vb:08X}: not in this log");
+            continue;
+        };
+        let n = d.pos.len().min(8);
+        let mut direct = Vec::new();
+        let mut mirror = Vec::new();
+        for o in (0..bytes.len().saturating_sub(12 + 64 * 24)).step_by(4) {
+            for (flip, out) in [(1.0f32, &mut direct), (-1.0f32, &mut mirror)] {
+                let hit = (0..n).all(|k| {
+                    let at = o + k * 24;
+                    (be(at) - flip * d.pos[k][0]).abs() <= 1e-4
+                        && (be(at + 4) - d.pos[k][1]).abs() <= 1e-4
+                        && (be(at + 8) - d.pos[k][2]).abs() <= 1e-4
+                });
+                if hit {
+                    out.push(o);
+                }
+            }
+        }
+        println!(
+            "vbase 0x{vb:08X} vcount={}: {} direct copy/copies {:x?}, {} mirrored {:x?}",
+            d.vcount,
+            direct.len(),
+            &direct[..],
+            mirror.len(),
+            &mirror[..]
+        );
+    }
+}

crates/sylpheed-formats/examples/miss_targets.rs

@@ -0,0 +1,86 @@
+//! Which container should the next runtime capture aim at?
+//!
+//! The 2026-08-13 stage-05 capture showed that a mission keeps several containers
+//! resident and that its OWN `Stage_SNN.xpr` is among them (the f101 ACROPOLIS was
+//! drawn from `Stage_S05.xpr`), so a capture can be aimed by choosing the mission.
+//! This ranks the targets: for every XBG7 resource on the disc it records the
+//! containers where it decodes and the ones where it does not, then reports
+//!
+//!   * resources that decode **nowhere** — the real gaps, where a capture is the
+//!     only ground truth left;
+//!   * per container, how many of those it holds (fly that mission);
+//!   * resources that miss in one container but decode in another — a defect worth
+//!     fixing, but the geometry is already recoverable, so a capture is not needed.
+//!
+//! Usage: miss_targets <resource3d_dir>
+use sylpheed_formats::mesh::{xbg7_resource_names, Xbg7Model};
+use std::collections::{BTreeMap, BTreeSet};
+
+fn main() {
+    let dir = std::env::args().nth(1).expect("resource3d dir");
+    let mut files: Vec<_> = std::fs::read_dir(&dir)
+        .unwrap()
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("xpr"))
+        .collect();
+    files.sort();
+
+    // resource -> (containers where it decodes, containers where it misses)
+    let mut ok: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
+    let mut miss: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
+    for f in &files {
+        let Ok(bytes) = std::fs::read(f) else { continue };
+        let where_ = f.file_name().unwrap().to_string_lossy().to_string();
+        let declared: BTreeSet<String> = xbg7_resource_names(&bytes).into_iter().collect();
+        if declared.is_empty() {
+            continue;
+        }
+        let decoded: BTreeSet<String> =
+            Xbg7Model::stage_models(&bytes).into_iter().map(|m| m.name).collect();
+        for n in &declared {
+            if decoded.contains(n) {
+                ok.entry(n.clone()).or_default().insert(where_.clone());
+            } else {
+                miss.entry(n.clone()).or_default().insert(where_.clone());
+            }
+        }
+    }
+
+    let never: BTreeMap<&String, &BTreeSet<String>> =
+        miss.iter().filter(|(n, _)| !ok.contains_key(*n)).collect();
+    let recoverable: Vec<&String> = miss.keys().filter(|n| ok.contains_key(*n)).collect();
+
+    println!("resources that decode NOWHERE: {}", never.len());
+    println!("resources that miss somewhere but decode elsewhere: {}\n", recoverable.len());
+
+    // Rank containers by how many never-decoding resources they hold.
+    let mut per_container: BTreeMap<&String, Vec<&String>> = BTreeMap::new();
+    for (n, wheres) in &never {
+        for w in wheres.iter() {
+            per_container.entry(w).or_default().push(n);
+        }
+    }
+    let mut ranked: Vec<_> = per_container.iter().collect();
+    ranked.sort_by_key(|(_, v)| std::cmp::Reverse(v.len()));
+    println!("container                   never-decoding resources it holds");
+    for (w, v) in ranked.iter().take(14) {
+        let sample: Vec<&str> = v.iter().take(6).map(|s| s.as_str()).collect();
+        println!("{:<26} {:>3}   {}", w, v.len(), sample.join(", "));
+    }
+
+    // Exclusives: a never-decoding resource that only ONE container holds is only
+    // reachable through whatever loads that container.
+    let excl: Vec<(&&String, &&BTreeSet<String>)> =
+        never.iter().filter(|(_, w)| w.len() == 1).collect();
+    println!("\nof the never-decoding, {} live in exactly one container", excl.len());
+    let mut by_one: BTreeMap<&String, Vec<&String>> = BTreeMap::new();
+    for (n, w) in &excl {
+        by_one.entry(w.iter().next().unwrap()).or_default().push(n);
+    }
+    let mut b: Vec<_> = by_one.iter().collect();
+    b.sort_by_key(|(_, v)| std::cmp::Reverse(v.len()));
+    for (w, v) in b.iter().take(10) {
+        println!("  {:<24} {:>3}   {}", w, v.len(), v.iter().take(5).map(|s| s.as_str()).collect::<Vec<_>>().join(", "));
+    }
+}

crates/sylpheed-formats/examples/movie_map_csv.rs

@@ -0,0 +1,27 @@
+//! Regenerate `docs/re/captures/movie-subtitle-voice-map.csv` from the record
+//! table. Keyed by cutscene SLOT, not by movie: three resupply movies are bound
+//! by two slots each, and the old movie-keyed CSV silently dropped one of each.
+use sylpheed_formats::{movie_manifest, IdxdObject, PakArchive};
+
+fn main() {
+    let disc = std::env::var("SYLPHEED_DISC").expect("set SYLPHEED_DISC");
+    let arc = PakArchive::open(format!("{disc}/dat/tables.pak")).expect("tables.pak");
+    let manifest = arc
+        .entries()
+        .iter()
+        .filter_map(|e| arc.read(e).ok())
+        .find(|b| IdxdObject::is_idxd(b) && movie_manifest::is_manifest(b))
+        .expect("movie manifest");
+
+    println!("slot,movie,telop,subtitle,voicetrack");
+    for e in movie_manifest::parse(&manifest) {
+        println!(
+            "{},{}.wmv,{},{},{}",
+            e.slot,
+            e.movie,
+            e.telop.unwrap_or_default(),
+            e.subtitle.unwrap_or_default(),
+            e.voice_token.unwrap_or_default()
+        );
+    }
+}

crates/sylpheed-formats/examples/name_resolution.rs

@@ -0,0 +1,51 @@
+//! Why does an element's sprite fail to resolve? Dump the two name spaces.
+//!
+//! `parse_build` resolves an element to a sprite by looking its DECLARED name up
+//! in (a) the `.rat` record table, then (b) the `T8aD` child table. `pteff05.t32`
+//! is in neither -- the `T8aD` it wants is registered as `8AX` -- so it resolves
+//! to None and `compose` drops it without recording it as missing. This prints
+//! both spaces, so the link between the two can be CHECKED rather than assumed.
+//!
+//!     cargo run -p sylpheed-formats --example name_resolution -- <pak> <entry>
+use sylpheed_formats::{pak, ui_layout};
+
+fn main() {
+    let path = std::env::args().nth(1).expect("usage: name_resolution <pak> [entry]");
+    let want: Option<usize> = std::env::args().nth(2).and_then(|s| s.parse().ok());
+    let ar = pak::PakArchive::open(&path).expect("open pak");
+    let entries: Vec<_> = ar.entries().to_vec();
+    for (i, e) in entries.iter().enumerate() {
+        if want.is_some_and(|w| w != i) {
+            continue;
+        }
+        let Ok(bytes) = ar.read(e) else { continue };
+        let Some(build) = ui_layout::parse_build(&bytes) else { continue };
+        let unresolved: Vec<&ui_layout::Element> = build
+            .elements
+            .iter()
+            .filter(|el| el.sprite.is_none() && el.kind & 0x10 == 0)
+            .collect();
+        let claimed: std::collections::HashSet<&str> =
+            build.elements.iter().filter_map(|e| e.sprite.as_deref()).collect();
+        let unclaimed: Vec<&String> =
+            build.sprites.keys().filter(|k| !claimed.contains(k.as_str())).collect();
+        if want.is_none() && unresolved.is_empty() && unclaimed.is_empty() {
+            continue;
+        }
+        let un: Vec<&str> = unresolved.iter().map(|e| e.name.as_str()).collect();
+        let uc: Vec<String> = unclaimed
+            .iter()
+            .map(|k| format!("{k}({} B)", build.sprites[*k].1))
+            .collect();
+        println!(
+            "entry {i:3}  {:2} elements  UNRESOLVED {:?}  UNCLAIMED {:?}",
+            build.elements.len(), un, uc
+        );
+        if want.is_some() {
+            for el in &build.elements {
+                let mark = if el.sprite.is_none() && el.kind & 0x10 == 0 { "   <-- UNRESOLVED" } else { "" };
+                println!("   [{:2}] kind {:#06x}  {:28} -> {:?}{mark}", el.index, el.kind, el.name, el.sprite);
+            }
+        }
+    }
+}

crates/sylpheed-formats/examples/node_scale.rs

@@ -0,0 +1,20 @@
+//! Dump a composite's scene nodes with their scale — the transform the static
+//! assembler copies verbatim into a placement.
+//! Usage: node_scale <container.xpr> <composite name>
+use sylpheed_formats::mesh::scene_world_nodes;
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let bytes = std::fs::read(&a[1]).expect("container");
+    for n in scene_world_nodes(&bytes, &a[2]) {
+        // Row norms of `m`: a rotation has all three at 1.0; anything else is a
+        // scale baked into the matrix, which `s` does not show.
+        let norm = |r: [f32; 3]| (r[0] * r[0] + r[1] * r[1] + r[2] * r[2]).sqrt();
+        println!(
+            "{:<26} s[{:7.3}{:7.3}{:7.3}]  |m rows|[{:7.3}{:7.3}{:7.3}]  t[{:9.1}{:9.1}{:9.1}]",
+            n.resource,
+            n.s[0], n.s[1], n.s[2],
+            norm(n.m[0]), norm(n.m[1]), norm(n.m[2]),
+            n.t[0], n.t[1], n.t[2]
+        );
+    }
+}

crates/sylpheed-formats/examples/pad_shift_audit.rs

@@ -0,0 +1,129 @@
+//! How much geometry on the disc was being read one index element late?
+//!
+//! The pad-scoring fix (2026-08-13) makes `anchor_pool_mesh` choose the pad whose
+//! index run is cleanest instead of the first that validates. This measures the
+//! blast radius: per container, how many single-block resources now decode from a
+//! run that is NOT the old first-match (`pad 0`) one, and how many decoded runs
+//! still contain degenerate triangles (the shift signature) afterwards.
+//!
+//! Usage: pad_shift_audit <resource3d_dir>
+use sylpheed_formats::mesh::Xbg7Model;
+
+fn be16(b: &[u8], at: usize) -> u32 {
+    ((b[at] as u32) << 8) | b[at + 1] as u32
+}
+
+/// Fraction of triangles whose face normal agrees with the stored normals,
+/// folded to `max(na, 1-na)` so both authored windings read as ≈1.
+fn winding(idx: &[u32], pos: &[[f32; 3]], nrm: &[[f32; 3]]) -> f32 {
+    let (mut agree, mut n) = (0usize, 0usize);
+    for t in idx.chunks_exact(3) {
+        let (a, b, c) = (t[0] as usize, t[1] as usize, t[2] as usize);
+        if a == b || b == c || a == c || a.max(b).max(c) >= pos.len() || a >= nrm.len() {
+            continue;
+        }
+        let e1 = [pos[b][0] - pos[a][0], pos[b][1] - pos[a][1], pos[b][2] - pos[a][2]];
+        let e2 = [pos[c][0] - pos[a][0], pos[c][1] - pos[a][1], pos[c][2] - pos[a][2]];
+        let f = [
+            e1[1] * e2[2] - e1[2] * e2[1],
+            e1[2] * e2[0] - e1[0] * e2[2],
+            e1[0] * e2[1] - e1[1] * e2[0],
+        ];
+        let nv = nrm[a];
+        n += 1;
+        if f[0] * nv[0] + f[1] * nv[1] + f[2] * nv[2] > 0.0 {
+            agree += 1;
+        }
+    }
+    if n == 0 {
+        return 1.0;
+    }
+    let fr = agree as f32 / n as f32;
+    fr.max(1.0 - fr)
+}
+
+fn degenerate(idx: &[u32]) -> usize {
+    idx.chunks_exact(3)
+        .filter(|t| t[0] == t[1] || t[1] == t[2] || t[0] == t[2])
+        .count()
+}
+
+fn main() {
+    let dir = std::env::args().nth(1).expect("resource3d dir");
+    let mut files: Vec<_> = std::fs::read_dir(&dir)
+        .unwrap()
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("xpr"))
+        .collect();
+    files.sort();
+
+    let (mut total, mut moved, mut still_degen) = (0usize, 0usize, 0usize);
+    let mut weak = 0usize;
+    let mut weak_wind: Vec<(f32, f32, String)> = Vec::new();
+    let mut worst: Vec<(usize, String, String)> = Vec::new();
+    for f in &files {
+        let Ok(bytes) = std::fs::read(f) else { continue };
+        let where_ = f.file_name().unwrap().to_string_lossy().to_string();
+        let mut c_moved = 0usize;
+        for m in Xbg7Model::stage_models(&bytes) {
+            // Degeneracy is counted over EVERY sub-mesh (grouped pools included —
+            // they have their own pad choice); the pad-0 comparison below only
+            // applies to single-block resources, whose run starts at `vb - 2n`.
+            for sm in &m.meshes {
+                let d = degenerate(&sm.indices);
+                if d > 0 {
+                    still_degen += 1;
+                    worst.push((d, m.name.clone(), where_.clone()));
+                }
+            }
+            if m.meshes.len() != 1 {
+                continue;
+            }
+            let sm = &m.meshes[0];
+            let Some(vb) = sm.vbuf_offset else { continue };
+            let n = sm.indices.len();
+            if n < 6 || vb < n * 2 {
+                continue;
+            }
+            total += 1;
+            let pad0: Vec<u32> = (0..n).map(|k| be16(&bytes, vb - n * 2 + k * 2)).collect();
+            if pad0 != sm.indices {
+                moved += 1;
+                c_moved += 1;
+                // How strong was the evidence for moving? A pad-0 run with
+                // degenerate triangles is a decisive shift signature; one with
+                // none moved on winding alone, which is weaker.
+                if degenerate(&pad0) == 0 {
+                    weak += 1;
+                    // Record how far apart the two runs' winding is, to see
+                    // whether these look like the same shift signature as the
+                    // decisive cases (pad-0 winding drifting toward 0.5) or like
+                    // noise between two equally clean readings.
+                    let w0 = winding(&pad0, &sm.positions, &sm.normals);
+                    let w2: f32 = {
+                        let l2: Vec<u32> = (0..n).map(|k| be16(&bytes, vb - n * 2 - 2 + k * 2)).collect();
+                        winding(&l2, &sm.positions, &sm.normals)
+                    };
+                    weak_wind.push((w0, w2, m.name.clone()));
+                }
+            }
+        }
+        if c_moved > 0 {
+            println!("{where_:<24} {c_moved} resources read from a non-pad-0 index run");
+        }
+    }
+    println!("\n{moved} of {total} single-block resources moved off the pad-0 run");
+    println!("{still_degen} decoded runs still contain a degenerate triangle");
+    println!("of the moved, {weak} had a pad-0 run with no degenerate triangle (moved on winding alone)");
+    let clear = weak_wind.iter().filter(|(w0, w2, _)| *w2 - *w0 > 0.15).count();
+    let close = weak_wind.iter().filter(|(w0, w2, _)| (*w2 - *w0).abs() <= 0.05).count();
+    println!("  of those: {clear} show the shift signature (pad-2 winding > pad-0 by >0.15), {close} are within 0.05 (noise)");
+    for (w0, w2, n) in weak_wind.iter().take(8) {
+        println!("    {n}: pad0 wind {w0:.3} -> pad2 {w2:.3}");
+    }
+    worst.sort_by_key(|(d, _, _)| std::cmp::Reverse(*d));
+    for (d, n, w) in worst.iter().take(15) {
+        println!("  {n} ({w}): {d} degenerate triangles");
+    }
+}

crates/sylpheed-formats/examples/paint_order_audit.rs

@@ -0,0 +1,136 @@
+//! Does the DERIVED paint order reproduce the ones measured from the game?
+//!
+//! `compose` uses a measured order for the three builds that have one and falls
+//! back to `derived_paint_order` (a sort on each sprite's layer key) everywhere
+//! else. The doc comment claims the derived order "reproduces both measured
+//! orders up to ties" — this checks that claim against all three, and says what
+//! the ties actually cost.
+//!
+//!     cargo run -p sylpheed-formats --example paint_order_audit -- <GP_TITLE.pak>
+use sylpheed_formats::{pak, ui_layout};
+
+fn measured(names: &[&str]) -> Option<(&'static str, Vec<usize>)> {
+    const TITLE: [&str; 24] = [
+        "ptlogo1.t32", "ptlogo2.t32", "ptlogo1.t32", "ptlogo2.t32", "ptlogo1.t32",
+        "ptlogo2.t32", "pteff01.t32", "ptlogo_tm.t32", "pteff00.prm", "ptbase2.t32",
+        "pteff04.t32", "ptloop01.rat", "ptloop02.rat", "pteff02.prm",
+        "ptlogo_back2eff1.t32", "ptlogo_back2eff2.t32", "ptlogo_back2eff3.t32",
+        "ptlogo_back2eff4.t32", "ptlogo_back2eff5.t32", "ptlogo_back2.t32",
+        "ptlogo_back2eff.t32", "ptcopyright.t32", "ptlogoall_eff.t32",
+        "ptlogoall_eff2.t32",
+    ];
+    const SPLASH: [&str; 7] = [
+        "palogo_eff0.prm", "palogo_gamearts.t32", "palogo_gamearts_eff.t32",
+        "palogo_seta.t32", "palogo_seta_eff.t32", "palogo_anima.t32",
+        "palogo_anima_eff.t32",
+    ];
+    const MENU: [&str; 16] = [
+        "pteff00.prm", "ptbase.t32", "pteff05.t32", "ptloop01.rat",
+        "ptloop02.rat", "pteff02.prm", "ptframe1.t32", "ptframe2.t32",
+        "pteff10.t32", "pteff12.t32", "ptbtn01.rat", "ptbtn02.rat",
+        "ptbtn03.rat", "ptbtn04.rat", "ptbtn05.rat", "ptmsg.t32",
+    ];
+    if names == TITLE {
+        return Some(("title", vec![9,11,12,10,13,6,20,19,14,15,18,16,17,0,2,4,7,1,3,5,22,23,21,8]));
+    }
+    if names == SPLASH { return Some(("splash", vec![0,2,4,6,1,3,5])); }
+    if names == MENU {
+        return Some(("main menu", vec![1,3,4,2,5,8,9,6,7,15,10,11,12,13,14,0]));
+    }
+    None
+}
+
+fn main() {
+    let path = std::env::args().nth(1).expect("usage: paint_order_audit <pak>");
+    let ar = pak::PakArchive::open(&path).expect("open pak");
+    let mut checked = 0;
+    let entries: Vec<_> = ar.entries().to_vec();
+    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 };
+        let names: Vec<&str> = build.elements.iter().map(|e| e.name.as_str()).collect();
+        // Every build: how exposed is it to tie-breaking? A tie between
+        // OVERLAPPING elements is where a derived order can go visibly wrong.
+        let keys_all: Vec<u32> = build.elements.iter()
+            .map(|e| ui_layout::sprite_layer_key(&build, &bytes, e).unwrap_or(u32::MAX))
+            .collect();
+        let mut tie_pairs = 0;
+        for a in 0..keys_all.len() {
+            for b in (a + 1)..keys_all.len() {
+                if keys_all[a] == keys_all[b] && keys_all[a] != u32::MAX { tie_pairs += 1; }
+            }
+        }
+        // Of the tied pairs, how many OVERLAP? Only those can paint visibly
+        // differently under an arbitrary tie-break. Rect from the declared
+        // pivot (= half the sprite for a .t32) at the resting placement.
+        let rect = |e: &ui_layout::Element| -> Option<(i32,i32,i32,i32)> {
+            let kf = e.rest()?;
+            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))
+        };
+        let mut tie_overlap = 0;
+        for a in 0..keys_all.len() {
+            for b in (a + 1)..keys_all.len() {
+                if keys_all[a] != keys_all[b] || keys_all[a] == u32::MAX { continue; }
+                let (Some(ra), Some(rb)) = (rect(&build.elements[a]), rect(&build.elements[b]))
+                    else { continue };
+                let ox = (ra.0 + ra.2).min(rb.0 + rb.2) - ra.0.max(rb.0);
+                let oy = (ra.1 + ra.3).min(rb.1 + rb.3) - ra.1.max(rb.1);
+                if ox > 0 && oy > 0 { tie_overlap += 1; }
+            }
+        }
+        let Some((label, want)) = measured(&names) else {
+            println!("entry {i:2}  (no measured order)  {} elements, {tie_pairs} tied pairs, \
+{tie_overlap} of them OVERLAPPING", build.elements.len());
+            // Name them: these are the only pairs whose order can show.
+            for a in 0..keys_all.len() {
+                for b in (a + 1)..keys_all.len() {
+                    if keys_all[a] != keys_all[b] || keys_all[a] == u32::MAX { continue; }
+                    let (Some(ra), Some(rb)) = (rect(&build.elements[a]), rect(&build.elements[b]))
+                        else { continue };
+                    let ox = (ra.0 + ra.2).min(rb.0 + rb.2) - ra.0.max(rb.0);
+                    let oy = (ra.1 + ra.3).min(rb.1 + rb.3) - ra.1.max(rb.1);
+                    if ox > 0 && oy > 0 {
+                        println!("      overlapping tie: [{a}] {} x [{b}] {}  key {}  rect {:?} / {:?}  overlap {}x{}",
+                            build.elements[a].name, build.elements[b].name, keys_all[a], ra, rb, ox, oy);
+                    }
+                }
+            }
+            continue;
+        };
+        checked += 1;
+        let got = ui_layout::derived_paint_order(&build, &bytes);
+        let keys: Vec<u32> = build.elements.iter()
+            .map(|e| ui_layout::sprite_layer_key(&build, &bytes, e).unwrap_or(u32::MAX))
+            .collect();
+        let exact = got == want;
+        // How many adjacent pairs in the MEASURED order does derived get wrong,
+        // and of those, how many are between elements sharing a layer key (a
+        // tie the sort cannot resolve) versus a genuine key-order conflict?
+        let pos_got: Vec<usize> = {
+            let mut p = vec![0; got.len()];
+            for (r, &e) in got.iter().enumerate() { p[e] = r; }
+            p
+        };
+        let (mut inv, mut tied) = (0, 0);
+        for a in 0..want.len() {
+            for b in (a + 1)..want.len() {
+                let (x, y) = (want[a], want[b]);
+                if pos_got[x] > pos_got[y] {
+                    inv += 1;
+                    if keys[x] == keys[y] { tied += 1; }
+                }
+            }
+        }
+        println!("entry {i:2}  {label:10}  {} elements", want.len());
+        println!("   derived == measured : {}", if exact { "YES" } else { "NO" });
+        println!("   inverted pairs      : {inv}  (of which same-layer-key ties: {tied})");
+        if !exact {
+            println!("   measured: {want:?}");
+            println!("   derived : {got:?}");
+            println!("   keys    : {keys:?}");
+        }
+    }
+    println!("\n{checked} build(s) with a measured order were checked");
+}

crates/sylpheed-formats/examples/params.rs

@@ -0,0 +1,13 @@
+fn main(){
+    let a:Vec<String>=std::env::args().collect();
+    let bytes=std::fs::read(&a[1]).unwrap();
+    let filter=a.get(2).cloned().unwrap_or_default();
+    for n in sylpheed_formats::mesh::xbg7_resource_names(&bytes) {
+        if !filter.is_empty() && !n.contains(&filter) { continue }
+        if let Some((m,stride))=sylpheed_formats::mesh::debug_resource_params(&bytes,&n) {
+            let strides = sylpheed_formats::mesh::debug_decl_strides(&bytes, &n);
+            println!("{n:<28} decl-stride {stride} markers {:?} per-sub-mesh strides {:?}",
+                     &m[..m.len().min(4)], strides);
+        }
+    }
+}

crates/sylpheed-formats/examples/plateauless_suppression.rs

@@ -0,0 +1,52 @@
+//! Does DRAWING NOTHING beat guessing, for an element with no held pose?
+//!
+//! A keyframe group is entry → hold → exit, and the exit ends invisible (on the
+//! five port screens the final keyframe is invisible for 21/24, 8/16, 12/18, 2/3
+//! and 6/7 elements). So the screen "as seen" is the HOLD — which is why
+//! `rest_plateau` is the primary rule. An element with **no** plateau has no
+//! hold, and `rest()` currently falls back to guessing an endpoint of a movement.
+//!
+//! This renders each screen twice — as-is, and with every plateau-less element
+//! suppressed via `compose`'s `visible` mask — and correlates both against the
+//! live capture. If suppression wins, the fallback should draw nothing.
+//! Writes both composites as raw RGBA (`<out>/entryNN_{asis,suppressed}.raw`,
+//! 1280x720) so the correlation is done outside — this crate has no image
+//! decoder and the comparison is not worth a dependency.
+use sylpheed_formats::{pak, ui_layout};
+
+fn main() {
+    let pak_path = std::env::args().nth(1).expect("usage: <GP_TITLE.pak> <outdir> <entry>...");
+    let ar = pak::PakArchive::open(&pak_path).expect("open");
+    let entries: Vec<_> = ar.entries().to_vec();
+    let outdir = std::env::args().nth(2).expect("outdir");
+    std::fs::create_dir_all(&outdir).ok();
+    for spec in std::env::args().skip(3) {
+        let idx: usize = spec.parse().unwrap();
+        let bytes = ar.read(&entries[idx]).expect("read");
+        let Some(build) = ui_layout::parse_build(&bytes) else { continue };
+        // plateau-less = rest() had to guess: no two adjacent keyframes share a pose
+        // Default: suppress plateau-less elements. With SUPPRESS_SUBSTR set,
+        // suppress every element whose NAME contains it instead — used to test
+        // the entry→hold→exit model's prediction that the splash glows are all
+        // finished by the moment the logos are up.
+        let by_name = std::env::var("SUPPRESS_SUBSTR").ok();
+        let mask: Vec<bool> = build.elements.iter().map(|e| {
+            if let Some(sub) = &by_name {
+                return !e.name.to_lowercase().contains(sub.as_str());
+            }
+            let k = &e.keyframes;
+            (0..k.len().saturating_sub(1)).any(|i| {
+                k[i].fade == k[i+1].fade && k[i].scale_x == k[i+1].scale_x
+                    && k[i].scale_y == k[i+1].scale_y && k[i].x == k[i+1].x && k[i].y == k[i+1].y
+            })
+        }).collect();
+        let suppressed = mask.iter().filter(|m| !**m).count();
+        let opts = ui_layout::ComposeOptions::default();
+        let a = ui_layout::compose(&build, &bytes, opts, None);
+        let b = ui_layout::compose(&build, &bytes, opts, Some(&mask));
+        std::fs::write(format!("{outdir}/entry{idx:02}_asis.raw"), &a.rgba).unwrap();
+        std::fs::write(format!("{outdir}/entry{idx:02}_suppressed.raw"), &b.rgba).unwrap();
+        println!("entry {idx:2}  {}x{}  elements {:2}  plateau-less suppressed {suppressed}",
+                 a.width, a.height, build.elements.len());
+    }
+}

crates/sylpheed-formats/examples/pool_window.rs

@@ -0,0 +1,29 @@
+//! Raw token sequence around a key, for one record — the ground truth for
+//! "is this field actually defaulted, or is our reader missing it?"
+//! Run: pool_window <disc-root> <ID substring> <key>
+use sylpheed_formats::idxd::IdxdObject;
+use sylpheed_formats::pak::PakArchive;
+fn main() {
+    let disc = std::env::args().nth(1).unwrap();
+    let want = std::env::args().nth(2).unwrap();
+    let key = std::env::args().nth(3).unwrap();
+    let pak = PakArchive::open(format!("{disc}/dat/GP_MAIN_GAME_E.pak")).unwrap();
+    for e in pak.entries() {
+        let Ok(b) = pak.read(e) else { continue };
+        let Ok(o) = IdxdObject::parse(&b) else { continue };
+        let Some(id) = o.get_raw("ID") else { continue };
+        if !id.contains(&want) { continue; }
+        let t = o.tokens();
+        println!("=== {id}   get_f32({key}) = {:?}", o.get_f32(&key));
+        for (i, tok) in t.iter().enumerate() {
+            if tok == &key {
+                let lo = i.saturating_sub(6);
+                let hi = (i + 7).min(t.len());
+                for j in lo..hi {
+                    println!("   [{j}]{} {:?}", if j == i { " <-- key" } else { "        " }, t[j]);
+                }
+                println!();
+            }
+        }
+    }
+}

crates/sylpheed-formats/examples/probe_anchor.rs

@@ -0,0 +1,6 @@
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let bytes = std::fs::read(&a[1]).unwrap();
+    let vb: usize = a[3].parse().unwrap();
+    println!("{:?}", sylpheed_formats::mesh::debug_try_anchor(&bytes, &a[2], vb, 3));
+}

crates/sylpheed-formats/examples/rat_inspect.rs

@@ -0,0 +1,118 @@
+//! Scratch: confirm the `.rat` layout record offsets against a real screen pak.
+//! Run: cargo run -p sylpheed-formats --example rat_inspect -- <GP_SCREEN.pak>
+use sylpheed_formats::{pak::PakArchive, ratc, t8ad};
+
+fn be32(b: &[u8], o: usize) -> u32 {
+    u32::from_be_bytes([b[o], b[o + 1], b[o + 2], b[o + 3]])
+}
+
+fn main() {
+    let path = std::env::args().nth(1).expect("pak path");
+    let ar = PakArchive::open(&path).expect("open pak");
+    println!("entries: {}", ar.len());
+
+    let mut decoded: Vec<Vec<u8>> = Vec::new();
+    for (i, e) in ar.entries().iter().enumerate() {
+        let d = ar.read(e).unwrap_or_default();
+        let magic = String::from_utf8_lossy(&d[..4.min(d.len())]).to_string();
+        let (nt, nr) = if ratc::is_ratc(&d) {
+            let k = ratc::parse(&d).unwrap_or_default();
+            (
+                k.iter().filter(|c| c.kind == "T8aD").count(),
+                k.iter()
+                    .filter(|c| c.name.to_lowercase().ends_with(".rat"))
+                    .count(),
+            )
+        } else {
+            (0, 0)
+        };
+        println!(
+            "  entry[{:2}] {:>8} B  magic={:4}  t32={:2} rat={:2}",
+            i,
+            d.len(),
+            magic,
+            nt,
+            nr
+        );
+        decoded.push(d);
+    }
+    // Pick the entry with the most children as "build0".
+    let bi = (0..decoded.len())
+        .filter(|&i| ratc::is_ratc(&decoded[i]))
+        .max_by_key(|&i| ratc::parse(&decoded[i]).map(|k| k.len()).unwrap_or(0))
+        .unwrap();
+    println!("=> inspecting richest build: entry[{}]", bi);
+    let bundle = &decoded[bi];
+    let kids = ratc::parse(bundle).unwrap_or_default();
+    let t32: Vec<_> = kids.iter().filter(|c| c.kind == "T8aD").collect();
+    let rat: Vec<_> = kids
+        .iter()
+        .filter(|c| c.name.to_lowercase().ends_with(".rat"))
+        .collect();
+    println!(
+        "build0: {} children, {} t32 sprites, {} rat records",
+        kids.len(),
+        t32.len(),
+        rat.len()
+    );
+    for c in t32.iter().take(5) {
+        let b = &bundle[c.offset..(c.offset + c.size).min(bundle.len())];
+        if let Some(img) = t8ad::parse(b) {
+            println!("  T8aD  {:28} {}x{}", c.name, img.width, img.height);
+        }
+    }
+    println!("  -- .rat records --");
+    for c in rat.iter().take(10) {
+        let r = &bundle[c.offset..(c.offset + c.size).min(bundle.len())];
+        if r.len() < 0x60 {
+            println!("  .rat {:20} (len {}, too short)", c.name, r.len());
+            continue;
+        }
+        let (dw, dh) = (be32(r, 0x18), be32(r, 0x1c));
+        let sprite = {
+            let s = &r[0x20..0x30.min(r.len())];
+            let end = s.iter().position(|&b| b == 0).unwrap_or(s.len());
+            String::from_utf8_lossy(&s[..end]).to_string()
+        };
+        let (pvx, pvy) = (be32(r, 0x50), be32(r, 0x54));
+        // scan for placement block [scaleX=100, scaleY=100, tint, X<dw, Y<dh]
+        let mut placement = None;
+        let mut o = 0x58;
+        while o + 20 <= r.len() {
+            if be32(r, o) == 100 && be32(r, o + 4) == 100 {
+                let (tint, x, y) = (be32(r, o + 8), be32(r, o + 12), be32(r, o + 16));
+                if x < dw && y < dh {
+                    placement = Some((o, tint, x, y));
+                    break;
+                }
+            }
+            o += 4;
+        }
+        println!(
+            "  .rat {:22} {}x{} sprite={:16} pivot=({},{}) place={:x?}",
+            c.name, dw, dh, sprite, pvx, pvy, placement
+        );
+    }
+
+    // End-to-end: composite the build and write it out as a PNG.
+    if let Some(screen) = sylpheed_formats::ui_layout::compose_build(bundle, false) {
+        println!(
+            "compose: {}x{}, drew {} records: {:?}",
+            screen.width,
+            screen.height,
+            screen.drawn.len(),
+            screen.drawn
+        );
+        if let Some(out) = std::env::args().nth(2) {
+            // Dependency-free PPM (P6, RGB — alpha already composited over the backdrop).
+            let mut buf = format!("P6\n{} {}\n255\n", screen.width, screen.height).into_bytes();
+            for px in screen.rgba.chunks_exact(4) {
+                buf.extend_from_slice(&px[..3]);
+            }
+            std::fs::write(&out, buf).unwrap();
+            println!("wrote {out}");
+        }
+    } else {
+        println!("compose: build produced no image");
+    }
+}

crates/sylpheed-formats/examples/rat_leaf_placement.rs

@@ -0,0 +1,71 @@
+//! Does a `.rat` leaf record decode with the same reader as a whole bundle?
+//!
+//! The port needs the position of `ptbtneff01.t32`, the focus ring, which is
+//! declared *inside* the nested `ptbtn0Nf.rat` leaf and is therefore invisible
+//! to anything that walks only a bundle's top-level elements.
+//!
+//! The leaf's first 32 bytes have the same shape as a bundle header --
+//! `"RATC"`, `0x3c` declaration-entry size at `+4`, element count at `+20`,
+//! design size at `+24`/`+28` -- so the hypothesis is that `parse_build` reads
+//! it unchanged. The control is the BASE record `ptbtn0N.rat`, whose single
+//! element's position is already known independently: the parent screen's
+//! `screen info` reports `ptbtn01.rat` resting at (542,162).
+//!
+//!     cargo run -p sylpheed-formats --example rat_leaf_placement -- <GP_TITLE.pak>
+use sylpheed_formats::{pak, ratc, ui_layout};
+
+fn main() {
+    let path = std::env::args().nth(1).expect("usage: … <pak>");
+    let ar = pak::PakArchive::open(&path).expect("open pak");
+    let entries: Vec<_> = ar.entries().to_vec();
+
+    for (ei, e) in entries.iter().enumerate() {
+        let Ok(bytes) = ar.read(e) else { continue };
+        let Some(kids) = ratc::parse(&bytes) else { continue };
+        // Only the title-family bundles carry ptbtn records.
+        if !kids.iter().any(|c| c.name == "ptbtn01f.rat") {
+            continue;
+        }
+        println!("=== pak entry {ei}");
+        for c in &kids {
+            if c.kind != "RATC" || !c.name.starts_with("ptbtn") {
+                continue;
+            }
+            let leaf = &bytes[c.offset..c.offset + c.size];
+            match ui_layout::parse_build(leaf) {
+                None => println!("  {:16} …parse_build says no", c.name),
+                Some(b) => {
+                    println!(
+                        "  {:16} {}x{}  {} element(s), fallback={}",
+                        c.name,
+                        b.design_w,
+                        b.design_h,
+                        b.elements.len(),
+                        b.from_fallback
+                    );
+                    for el in &b.elements {
+                        let r = el.rest();
+                        println!(
+                            "       [{}] {:18} pivot ({:4},{:4})  rest ({:5},{:5})  kf {}",
+                            el.index,
+                            el.name,
+                            el.pivot_x,
+                            el.pivot_y,
+                            r.map(|k| k.x).unwrap_or(-1),
+                            r.map(|k| k.y).unwrap_or(-1),
+                            el.keyframes.len()
+                        );
+                        for (i, k) in el.keyframes.iter().enumerate() {
+                            println!(
+                                "            kf{i}  t={:?} pos=({},{}) scale={}%,{}% a={} rot={} tint={:#010x}",
+                                k.time, k.x, k.y, k.scale_x, k.scale_y,
+                                k.fade >> 24, k.rotation_deg, k.tint
+                            );
+                        }
+                    }
+                }
+            }
+        }
+        println!();
+    }
+}

crates/sylpheed-formats/examples/ratc_child_names.rs

@@ -0,0 +1,78 @@
+//! Is a RATC child's name the printable run before its magic, or the `opt ` block?
+//!
+//! `ratc::parse` names each child by scanning backwards for the ASCII run that
+//! precedes its magic. That is usually right, but it is a HEURISTIC, and the
+//! real format states the name explicitly: immediately before each child sits
+//!
+//!     "opt " | BE32 length | name | NUL | 3 bytes | <child magic>
+//!
+//! -- the same `opt ` block `ui_layout::opt_link` already decodes for a button's
+//! focus link. When those 3 trailing bytes happen to be printable the heuristic
+//! reads THEM as the name: the title screens' full-resolution background comes
+//! out as `8AX` (bytes 38 41 58) instead of `pteff05.t32`, its element then
+//! resolves to no sprite, and `compose` drops the screen's background.
+//!
+//! This compares the two readings for every RATC child in the paks given.
+//!
+//!     cargo run -p sylpheed-formats --example ratc_child_names -- <pak>...
+use sylpheed_formats::{pak, ratc};
+
+/// The name stated by the `opt ` block that ends just before `at`.
+fn opt_name(buf: &[u8], at: usize) -> Option<String> {
+    // The block is short; search back a bounded window for the tag.
+    let lo = at.saturating_sub(128);
+    let win = &buf[lo..at];
+    let pos = lo + win.windows(4).rposition(|w| w == b"opt ")?;
+    let len = u32::from_be_bytes(buf[pos + 4..pos + 8].try_into().ok()?) as usize;
+    if len == 0 || len > 64 || pos + 8 + len > at {
+        return None;
+    }
+    let s = String::from_utf8_lossy(&buf[pos + 8..pos + 8 + len]).to_string();
+    // It must be THIS child's block: name, NUL, then a short run to the magic.
+    if at - (pos + 8 + len) > 8 {
+        return None;
+    }
+    (!s.is_empty() && s.chars().all(|c| c.is_ascii_graphic())).then_some(s)
+}
+
+fn main() {
+    let mut children = 0usize;
+    let mut with_opt = 0usize;
+    let mut agree = 0usize;
+    let mut disagree: Vec<(String, usize, String, String)> = Vec::new();
+    for path in std::env::args().skip(1) {
+        let Ok(ar) = pak::PakArchive::open(&path) else { continue };
+        let short = path.rsplit('/').next().unwrap_or(&path).to_string();
+        let entries: Vec<_> = ar.entries().to_vec();
+        for (i, e) in entries.iter().enumerate() {
+            let Ok(bytes) = ar.read(e) else { continue };
+            let Some(kids) = ratc::parse(&bytes) else { continue };
+            for c in &kids {
+                children += 1;
+                let Some(o) = opt_name(&bytes, c.offset) else { continue };
+                with_opt += 1;
+                if o == c.name {
+                    agree += 1;
+                } else {
+                    disagree.push((short.clone(), i, c.name.clone(), o));
+                }
+            }
+        }
+    }
+    println!("RATC children scanned : {children}");
+    println!("  with an `opt ` block: {with_opt}");
+    println!("  scanned name AGREES  : {agree}");
+    println!("  scanned name DIFFERS : {}", disagree.len());
+    let mut by_pair: std::collections::BTreeMap<(String, String), usize> = Default::default();
+    for (_, _, scanned, opt) in &disagree {
+        *by_pair.entry((scanned.clone(), opt.clone())).or_default() += 1;
+    }
+    println!("\ndistinct disagreements (scanned -> opt), with counts:");
+    for ((s, o), n) in &by_pair {
+        println!("   {s:24} -> {o:24}  x{n}");
+    }
+    println!("\nfirst 20 occurrences:");
+    for (p, i, s, o) in disagree.iter().take(20) {
+        println!("   {p} entry {i:4}  {s:20} -> {o}");
+    }
+}

crates/sylpheed-formats/examples/ratc_optless_children.rs

@@ -0,0 +1,119 @@
+//! The 60 RATC children that carry no `opt ` block — do they lack it, or is our
+//! window too small?
+//!
+//! [`ratc::parse`] now prefers the name a child's own `opt ` block states, and
+//! falls back to the old backwards printable-run scan when there is no block
+//! within 128 bytes. That fallback fires for 60 of the disc's 18 002 children
+//! (0.3 %), and the reach of the finding in `docs/re/structures/ratc-child-names.md`
+//! stops there: "whether they genuinely lack the block or sit past the search
+//! window is not established".
+//!
+//! This settles that. For every child with no accepted block it reports
+//!
+//!   * whether an `opt ` tag exists at all further back, and how far;
+//!   * which guard rejected a tag that WAS in the window (length, gap, charset);
+//!   * the child's position in its bundle and its magic, in case the opt-less
+//!     ones are structurally distinct (e.g. always the first child);
+//!   * the raw bytes before the magic, so the fallback's answer can be judged.
+//!
+//!     cargo run -p sylpheed-formats --example ratc_optless_children -- <pak>...
+use sylpheed_formats::{pak, ratc};
+
+/// Why a child has no accepted `opt ` name. Mirrors `ratc::opt_name`'s guards
+/// one for one, so a rejection here is the same rejection the parser made.
+#[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Clone)]
+enum Why {
+    /// No `opt ` tag in the 128-byte window, and none anywhere before it either.
+    NoTagAtAll,
+    /// No tag in the window, but one exists further back, this many bytes away.
+    TagBeyondWindow(usize),
+    /// Tag found, but its BE32 length is 0 or > 64.
+    BadLength(usize),
+    /// Tag found, name ends more than 8 bytes before the magic — a neighbour's.
+    GapTooBig(usize),
+    /// Tag found, the named bytes are not all printable ASCII.
+    NotGraphic,
+}
+
+/// The parser's own window.
+const WINDOW: usize = 128;
+
+fn classify(buf: &[u8], at: usize) -> Option<Why> {
+    let lo = at.saturating_sub(WINDOW);
+    let pos = match buf[lo..at].windows(4).rposition(|w| w == b"opt ") {
+        Some(p) => lo + p,
+        None => {
+            // Widen to the whole buffer before the child: is it merely far away?
+            return Some(match buf[..at].windows(4).rposition(|w| w == b"opt ") {
+                Some(p) => Why::TagBeyondWindow(at - p),
+                None => Why::NoTagAtAll,
+            });
+        }
+    };
+    let len = u32::from_be_bytes(buf.get(pos + 4..pos + 8)?.try_into().ok()?) as usize;
+    if len == 0 || len > 64 || pos + 8 + len > at {
+        return Some(Why::BadLength(len));
+    }
+    let gap = at - (pos + 8 + len);
+    if gap > 8 {
+        return Some(Why::GapTooBig(gap));
+    }
+    let s = String::from_utf8_lossy(&buf[pos + 8..pos + 8 + len]);
+    if s.is_empty() || !s.chars().all(|c| c.is_ascii_graphic()) {
+        return Some(Why::NotGraphic);
+    }
+    None // accepted — this child is not one of the 60
+}
+
+fn main() {
+    let mut total = 0usize;
+    let mut rows: Vec<(String, usize, usize, String, String, Why)> = Vec::new();
+    let mut first_child_of_bundle = 0usize;
+    for path in std::env::args().skip(1) {
+        let Ok(ar) = pak::PakArchive::open(&path) else { continue };
+        let short = path.rsplit('/').next().unwrap_or(&path).to_string();
+        let entries: Vec<_> = ar.entries().to_vec();
+        for (ei, e) in entries.iter().enumerate() {
+            let Ok(bytes) = ar.read(e) else { continue };
+            let Some(kids) = ratc::parse(&bytes) else { continue };
+            for (ci, c) in kids.iter().enumerate() {
+                total += 1;
+                let Some(why) = classify(&bytes, c.offset) else { continue };
+                if ci == 0 {
+                    first_child_of_bundle += 1;
+                }
+                let lo = c.offset.saturating_sub(24);
+                let hex = bytes[lo..c.offset]
+                    .iter()
+                    .map(|b| format!("{b:02x}"))
+                    .collect::<Vec<_>>()
+                    .join(" ");
+                rows.push((short.clone(), ei, ci, c.name.clone(), hex, why));
+            }
+        }
+    }
+    println!("RATC children scanned          : {total}");
+    println!("  with NO accepted `opt ` block: {}", rows.len());
+    println!("  ... of which are child #0    : {first_child_of_bundle}");
+
+    let mut by_why: std::collections::BTreeMap<String, usize> = Default::default();
+    for r in &rows {
+        let k = match &r.5 {
+            Why::TagBeyondWindow(_) => "TagBeyondWindow".to_string(),
+            Why::BadLength(_) => "BadLength".to_string(),
+            Why::GapTooBig(_) => "GapTooBig".to_string(),
+            other => format!("{other:?}"),
+        };
+        *by_why.entry(k).or_default() += 1;
+    }
+    println!("\nwhy, by cause:");
+    for (k, n) in &by_why {
+        println!("   {k:20} x{n}");
+    }
+
+    println!("\nevery occurrence (name is what the FALLBACK scan returned):");
+    for (p, ei, ci, name, hex, why) in &rows {
+        println!("   {p:28} entry {ei:4} child {ci:3}  {name:24} {why:?}");
+        println!("      24 bytes before the magic: {hex}");
+    }
+}

crates/sylpheed-formats/examples/roster_target.rs

@@ -0,0 +1,60 @@
+//! Which mission should the next unit harvest fly?
+//!
+//! Unit definitions are instantiated per stage, so coverage grows by visiting
+//! missions — but only if the mission fields units we have not read yet. This
+//! ranks every stage by how many of its roster units are missing from the
+//! harvested CSV.
+//!
+//! Usage: roster_target <disc-root> <unit-runtime-fields.csv>
+use sylpheed_formats::hash::name_hash;
+use sylpheed_formats::idxd::IdxdObject;
+use sylpheed_formats::pak::PakArchive;
+use std::collections::{BTreeMap, BTreeSet};
+
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let pak = PakArchive::open(format!("{}/dat/GP_MAIN_GAME_E.pak", a[1])).expect("pak");
+    let have: BTreeSet<String> = std::fs::read_to_string(&a[2])
+        .expect("csv")
+        .lines()
+        .skip(1)
+        .filter_map(|l| l.split(',').next().map(str::to_string))
+        .collect();
+    // Label each roster by STAGE: the TOC stores a hash of the original path, and
+    // the table names are known (`EnumUnit_SNN.tbl`), so hashing the candidates
+    // maps entries back to stages. Most rosters carry no `UN_S<NN>_` prop id, which
+    // is all `UnitRoster::stage` can infer from.
+    let mut by_hash: BTreeMap<u32, String> = BTreeMap::new();
+    // The TOC hashes a PATH, and these tables live under a directory — try the
+    // known schemes (see hash::TOC_NAME_SCHEMES) rather than the bare name.
+    for i in 1..=29 {
+        let stage = format!("S{i:02}");
+        for pre in ["", "unit\\", "battle\\", "stage\\", "enemy\\"] {
+            for suf in [".tbl", ""] {
+                by_hash.insert(name_hash(&format!("{pre}EnumUnit_{stage}{suf}")), stage.clone());
+            }
+        }
+    }
+    let mut rows: Vec<(usize, String, Vec<String>)> = Vec::new();
+    for e in pak.entries() {
+        let Some(stage) = by_hash.get(&e.name_hash).cloned() else { continue };
+        let Ok(b) = pak.read(e) else { continue };
+        let Ok(o) = IdxdObject::parse(&b) else { continue };
+        let mut units: Vec<String> = Vec::new();
+        for id in o.tokens().iter().filter(|s| s.starts_with("UN_")) {
+            let prop = id.contains("Asteroid") || id.contains("cmesh") || id.contains("_Box");
+            if !prop && !units.iter().any(|u| u == id) {
+                units.push(id.clone());
+            }
+        }
+        let missing: Vec<String> = units.iter().filter(|u| !have.contains(*u)).cloned().collect();
+        rows.push((missing.len(), stage, missing));
+    }
+    rows.sort_by_key(|(n, _, _)| std::cmp::Reverse(*n));
+    println!("units already harvested: {}\n", have.len());
+    println!("stage   missing  roster units not yet read");
+    for (n, stage, missing) in rows.iter().take(12) {
+        let s: Vec<&str> = missing.iter().take(6).map(|s| s.as_str()).collect();
+        println!("{stage:<8} {n:>5}   {}", s.join(", "));
+    }
+}

crates/sylpheed-formats/examples/screen_configs.rs

@@ -0,0 +1,18 @@
+//! RE probe: dump tables.pak screen-config records that mention a given token.
+//! Usage: screen_configs <disc-root> <substring>
+use sylpheed_formats::{idxd::IdxdObject, pak::PakArchive};
+fn main(){
+    let a:Vec<String>=std::env::args().collect();
+    let needle=a.get(2).cloned().unwrap_or_else(||"CHALLENGE".into());
+    let arc=PakArchive::open(format!("{}/dat/tables.pak",a[1])).unwrap();
+    for (i,e) in arc.entries().iter().enumerate(){
+        let Ok(b)=arc.read(e) else{continue};
+        let Ok(o)=IdxdObject::parse(&b) else{continue};
+        let t=o.tokens();
+        if !t.iter().any(|s|s.to_lowercase().contains(&needle.to_lowercase())){continue}
+        let path=t.iter().find(|s|s.contains(".pak+")).cloned().unwrap_or_default();
+        if !path.is_empty() && !path.contains("+eng"){continue}
+        println!("\n=== entry #{i} schema {:08x} [{path}] {} tokens ===",o.schema_hash,t.len());
+        for (j,tok) in t.iter().enumerate(){println!("  {j:3}  {tok}");}
+    }
+}

crates/sylpheed-formats/examples/screen_layout.rs

@@ -0,0 +1,111 @@
+//! Dump a UI screen's full layout from one RATC bundle: the element declaration
+//! table (what is drawn, in back-to-front order, with pivots and parent links)
+//! plus the placement region that follows it (per element: a keyframe group of
+//! scale / tint / X / Y).
+//!
+//! See docs/re/structures/ui-rat-layout.md. Run:
+//!   cargo run -p sylpheed-formats --example screen_layout -- <PAK> [0xHASH]
+//! With no hash, the largest RATC entry in the pak is used.
+
+use sylpheed_formats::pak::PakArchive;
+
+fn be32(b: &[u8], o: usize) -> u32 {
+    u32::from_be_bytes([b[o], b[o + 1], b[o + 2], b[o + 3]])
+}
+
+fn main() {
+    let mut args = std::env::args().skip(1);
+    let pak = args.next().expect("usage: screen_layout <pak> [0xHASH]");
+    let want = args.next();
+    let arc = PakArchive::open(&pak).expect("open pak");
+
+    let bytes = match want {
+        Some(h) if h.starts_with("0x") => {
+            let h = u32::from_str_radix(h.trim_start_matches("0x"), 16).expect("hash");
+            arc.read_by_hash(h).expect("entry").expect("decompress")
+        }
+        Some(name) => arc.read_by_name(&name).expect("entry present").expect("decompress"),
+        None => arc
+            .entries()
+            .iter()
+            .filter_map(|e| arc.read(e).ok())
+            .filter(|b| b.len() > 16 && &b[..4] == b"RATC")
+            .max_by_key(|b| b.len())
+            .expect("no RATC entry"),
+    };
+    assert_eq!(&bytes[..4], b"RATC", "not a RATC bundle");
+
+    let count = be32(&bytes, 0x14) as usize;
+    let mut names = Vec::with_capacity(count);
+    let mut meta = Vec::with_capacity(count);
+    for i in 0..count {
+        let e = &bytes[0x20 + i * 60..0x20 + (i + 1) * 60];
+        let name = String::from_utf8_lossy(&e[..28])
+            .trim_end_matches('\0')
+            .trim_end_matches(char::from(0))
+            .to_string();
+        let parent = be32(e, 32);
+        let kind = be32(e, 40);
+        let (px, py) = (be32(e, 48), be32(e, 52));
+        names.push(name);
+        meta.push((parent, kind, px, py));
+    }
+
+    // Placement region: groups of (u32 element index, u32 keyframe count) then
+    // `count` 40-byte keyframes; the X/Y sit 12 bytes into the scale/tint block.
+    let mut pos = 0x20 + count * 60;
+    // X/Y are SIGNED: off-screen animation starts are negative (e.g. -516).
+    let mut placements: Vec<Vec<(i32, i32, u32)>> = vec![Vec::new(); count];
+    for _ in 0..count {
+        if pos + 8 > bytes.len() { break }
+        let idx = be32(&bytes, pos) as usize;
+        let frames = be32(&bytes, pos + 4) as usize;
+        if idx >= count || frames == 0 || frames > 4096 { break }
+        let first = pos + 28; // header + lead-in, verified on the pause bundles
+        let mut group = Vec::with_capacity(frames);
+        for k in 0..frames {
+            let blk = first + k * 40;
+            if blk + 20 > bytes.len() { break }
+            group.push((be32(&bytes, blk + 12) as i32, be32(&bytes, blk + 16) as i32, be32(&bytes, blk + 20)));
+        }
+        placements[idx] = group;
+        pos = first + frames * 40 - 20;
+    }
+
+    println!("{} elements", count);
+    println!("{:<3} {:<30} {:>7} {:>8} {:>12} {:>4}  placement", "#", "element", "parent", "kind", "pivot", "kf");
+    for i in 0..count {
+        let (parent, kind, px, py) = meta[i];
+        let p = &placements[i];
+        // A group is an in → hold → out animation, so neither the first nor the
+        // last keyframe is where the element sits: report the MAX-DWELL one
+        // (longest gap to the next keyframe's time).
+        let shown = if p.is_empty() {
+            "—".into()
+        } else if p.len() == 1 {
+            format!("({},{})", p[0].0, p[0].1)
+        } else {
+            let mut best = (0usize, 0u32);
+            for k in 0..p.len() - 1 {
+                let d = p[k + 1].2.saturating_sub(p[k].2);
+                if d > best.1 { best = (k, d) }
+            }
+            let r = p[best.0];
+            format!(
+                "rest ({},{}) t={}..{}  [{}]",
+                r.0, r.1, r.2, p[best.0 + 1].2,
+                p.iter().map(|(x, y, t)| format!("{t}:{x},{y}")).collect::<Vec<_>>().join(" ")
+            )
+        };
+        println!(
+            "{:<3} {:<30} {:>7} {:>8} {:>12} {:>4}  {}",
+            i,
+            names[i],
+            if parent == u32::MAX { "-".into() } else { parent.to_string() },
+            format!("{kind:#x}"),
+            format!("({px},{py})"),
+            p.len(),
+            shown
+        );
+    }
+}

crates/sylpheed-formats/examples/se_wave_dump.rs

@@ -0,0 +1,27 @@
+//! Dump the menu's three SE cues as decodable `RIFF`s, to prove `se_wave_riff`
+//! produces something ffmpeg actually accepts.
+//!
+//!     cargo run -p sylpheed-formats --example se_wave_dump -- <outdir>
+//!     ffmpeg -i <outdir>/move.riff move.wav
+use sylpheed_formats::media::{self, DirectorySource};
+
+fn main() {
+    let out = std::env::args().nth(1).unwrap_or_else(|| "/tmp".into());
+    let disc = std::env::var("SYLPHEED_DISC").expect("SYLPHEED_DISC");
+    let src = DirectorySource::new(&disc);
+    for (name, off, pkts) in [("move", 0x1ec0usize, 4usize), ("back", 0x0ec0, 2), ("confirm", 0x5d6c0, 6)] {
+        match media::se_wave_riff(&src, "Static.slb", off, pkts, 1, 48000) {
+            Ok(riff) => {
+                let p = format!("{out}/{name}.riff");
+                std::fs::write(&p, &riff).unwrap();
+                println!("{p}: {} bytes ({pkts} packets at {off:#x})", riff.len());
+            }
+            Err(e) => println!("{name}: ERROR {e}"),
+        }
+    }
+    // The refusal path: a packet count the bank cannot satisfy.
+    match media::se_wave_riff(&src, "Static.slb", 0x1ec0, 1 << 20, 1, 48000) {
+        Ok(_) => println!("REFUSAL PATH FAILED — returned a short stream"),
+        Err(e) => println!("refusal path ok: {e}"),
+    }
+}

crates/sylpheed-formats/examples/shared_bank_takes.rs

@@ -0,0 +1,58 @@
+//! Does a shared resupply voice bank hold ONE line or SEVERAL takes?
+//!
+//! This decides whether the `samples/movie` lower bound on the sample rate is
+//! real. The test is static and does not need audio judgement: the movies that
+//! share a bank each have their OWN subtitle table. If those texts are identical
+//! the bank plausibly holds one generic line; if they differ, one bank is
+//! serving several distinct spoken lines.
+use std::collections::BTreeMap;
+
+use sylpheed_formats::{movie_subtitle, PakArchive};
+
+fn main() {
+    let disc = std::env::var("SYLPHEED_DISC").expect("set SYLPHEED_DISC");
+    let lang = PakArchive::open(format!("{disc}/dat/movie/eng.pak")).expect("eng.pak");
+    let text = PakArchive::open(format!("{disc}/dat/GP_MAIN_GAME_E.pak")).expect("text pak");
+    let demo_text = movie_subtitle::build_demo_text(&text);
+
+    // bank → the movies bound to it, from the record table (see movie-subtitle-link).
+    let banks: BTreeMap<&str, Vec<&str>> = BTreeMap::from([
+        ("VOICE_D_450", vec!["hokyu_LS_s02A", "hokyu_LS_s03A", "hokyu_LS_s06A"]),
+        (
+            "VOICE_D_451",
+            vec!["hokyu_LS_s09A", "hokyu_LS_s11A", "hokyu_LS_s15A", "hokyu_LS_s24A", "hokyu_LS_s27A"],
+        ),
+        ("VOICE_D_452", vec!["hokyu_DS_s02A", "hokyu_DS_s07A", "hokyu_DS_s08A", "hokyu_DS_s13A"]),
+        ("VOICE_D_453", vec!["hokyu_LS_s02H", "hokyu_LS_s03H", "hokyu_LS_s06H", "hokyu_LS_s09H"]),
+        ("VOICE_D_454", vec!["hokyu_DS_s07H", "hokyu_DS_s14H"]),
+    ]);
+
+    for (bank, movies) in &banks {
+        println!("\n== {bank}");
+        let mut seen: BTreeMap<String, Vec<&str>> = BTreeMap::new();
+        for m in movies {
+            let cues = movie_subtitle::track_voice_cues(&lang, m);
+            let mut line = String::new();
+            for (demo, t) in &cues {
+                let txt = demo_text
+                    .get(demo)
+                    .map(|v| v.join(" "))
+                    .unwrap_or_else(|| format!("<demo {demo}>"));
+                line.push_str(&format!("[{t:.2}] {txt}  "));
+            }
+            if line.is_empty() {
+                line.push_str("<no cues>");
+            }
+            seen.entry(line.trim().to_string()).or_default().push(m);
+        }
+        for (line, ms) in &seen {
+            println!("   {:?}", ms);
+            println!("      {line}");
+        }
+        println!(
+            "   -> {} distinct subtitle text(s) across {} movies",
+            seen.len(),
+            movies.len()
+        );
+    }
+}

crates/sylpheed-formats/examples/shared_vbase_check.rs

@@ -0,0 +1,262 @@
+//! Ask the runtime capture whether two resources that our decoder gives the
+//! **same geometry** really are the same geometry.
+//!
+//! Our XBG7 anchor scan sometimes lands two different resource names on one
+//! vertex buffer. Statics cannot separate "the container genuinely reuses a
+//! buffer" from "the scan picked the wrong candidate" — but a capture can: the
+//! engine uploads a buffer per resource and reuses one only 3.4 % of the time
+//! (see docs/re/structures/xbg7-mesh.md), so a group of `k` resources our
+//! decoder collapses onto one buffer should show up as `k` distinct `vbase`s
+//! carrying that same vertex count and those same positions. Fewer means at
+//! most one member of the group is really that geometry.
+//!
+//! Usage:
+//!   cargo run --release --example shared_vbase_check -- \
+//!       <Stage_SNN.xpr> <capture.log>...
+use sylpheed_formats::mesh::Xbg7Model;
+use sylpheed_formats::ship_capture::{parse_capture, parse_drawlog, CapturedDraw};
+use std::collections::{BTreeMap, BTreeSet};
+
+/// Quantised position key — the logs print 4 decimals, so compare at that scale.
+fn key(p: [f32; 3]) -> (i64, i64, i64) {
+    (
+        (p[0] as f64 * 1e4).round() as i64,
+        (p[1] as f64 * 1e4).round() as i64,
+        (p[2] as f64 * 1e4).round() as i64,
+    )
+}
+
+/// Where in the container does a captured buffer live? POSITION is `f32×3` big
+/// endian at vertex offset 0, so a draw's dumped positions are a literal byte
+/// pattern: find the first one, then confirm the next few at a fixed stride.
+/// This turns a capture into ground truth for a resource we mis-anchored.
+fn locate_run(bytes: &[u8], pos: &[[f32; 3]]) -> Vec<(usize, usize)> {
+    if pos.len() < 4 {
+        return Vec::new();
+    }
+    // The log prints 4 decimals, so match on value with the printing tolerance
+    // rather than on bytes.
+    let be = |b: &[u8], at: usize| f32::from_be_bytes(b[at..at + 4].try_into().unwrap());
+    let same = |b: &[u8], at: usize, p: [f32; 3]| {
+        at + 12 <= b.len() && (0..3).all(|c| (be(b, at + c * 4) - p[c]).abs() <= 1e-4)
+    };
+    let mut out = Vec::new();
+    for o in (0..bytes.len().saturating_sub(12)).step_by(4) {
+        if !same(bytes, o, pos[0]) {
+            continue;
+        }
+        for stride in (12..=64).step_by(4) {
+            if (1..4).all(|k| same(bytes, o + k * stride, pos[k])) {
+                out.push((o, stride));
+                break;
+            }
+        }
+    }
+    out
+}
+
+fn main() {
+    let args: Vec<String> = std::env::args().collect();
+    if args.len() < 3 {
+        eprintln!("usage: shared_vbase_check <Stage_SNN.xpr> <capture.log>...");
+        std::process::exit(2);
+    }
+    let bytes = std::fs::read(&args[1]).expect("read container");
+
+    // Every draw from every log, keyed by vertex count.
+    // Keep the logs apart: each is its own emulator run, so a `vbase` only
+    // means something within one log.
+    let mut logs: Vec<(String, Vec<CapturedDraw>)> = Vec::new();
+    for log in args[2..].iter().filter(|a| !a.starts_with("--")) {
+        let text = std::fs::read_to_string(log).expect("read log");
+        let mut d = parse_capture(&text);
+        if d.is_empty() {
+            d = parse_drawlog(&text);
+        }
+        eprintln!("{log}: {} draws", d.len());
+        logs.push((log.rsplit('/').next().unwrap_or(log).to_string(), d));
+    }
+
+    // `--map`: is a draw's guest `vbase` just the container file offset plus a
+    // constant? If the container is uploaded contiguously it is — and then a
+    // capture names the exact offset of every buffer the engine drew, which is
+    // ground truth the anchor scan currently has to guess at.
+    if args.iter().any(|a| a == "--map") {
+        for (log, draws) in &logs {
+            let mut seen: BTreeSet<u32> = BTreeSet::new();
+            let mut delta: BTreeMap<i64, usize> = BTreeMap::new();
+            let mut unfound = 0usize;
+            for d in draws {
+                if d.pos.len() < 8 || d.vcount < 20 || !seen.insert(d.vbase) {
+                    continue;
+                }
+                let at = locate_run(&bytes, &d.pos);
+                if at.is_empty() {
+                    unfound += 1;
+                    continue;
+                }
+                for (o, _) in at {
+                    *delta.entry(d.vbase as i64 - o as i64).or_default() += 1;
+                }
+            }
+            let mut top: Vec<_> = delta.iter().collect();
+            top.sort_by_key(|(_, n)| std::cmp::Reverse(**n));
+            println!("{log}: {} distinct vbases located, {unfound} not in this container", seen.len() - unfound);
+            for (d, n) in top.iter().take(5) {
+                println!("   vbase - offset = 0x{:X}  ×{n}", d);
+            }
+        }
+        return;
+    }
+
+    // Decode the container and group resources by the exact geometry they got.
+    let models = Xbg7Model::anchor_models_cancellable(&bytes, 0.0, &|| false);
+
+    // `--truth <base>`: with the container's guest load address (from `--map`),
+    // every draw names a file offset. Print it against the offset our anchor
+    // scan chose for each resource — a direct read-out of what we got wrong.
+    if let Some(a) = args.iter().find_map(|a| a.strip_prefix("--truth=")) {
+        let base = u32::from_str_radix(a.trim_start_matches("0x"), 16).expect("base");
+        // Where the anchor scan actually put each sub-mesh — exact, from the
+        // decoder, not inferred by searching for its leading vertices (the same
+        // leading run occurs at several offsets in a container, so a search
+        // cannot tell where a resource was anchored).
+        let mut ours: BTreeMap<usize, Vec<(String, usize)>> = BTreeMap::new();
+        for m in &models {
+            for sub in &m.meshes {
+                if let Some(o) = sub.vbuf_offset {
+                    ours.entry(o).or_default().push((m.name.clone(), sub.positions.len()));
+                }
+            }
+        }
+        if args.iter().any(|a| a == "--anchors") {
+            println!("{:<12}  where our decode put each resource", "file offset");
+            for (o, v) in &ours {
+                for (n, c) in v {
+                    println!("0x{o:<10x}  {n} ({c} verts)");
+                }
+            }
+            return;
+        }
+        let mut drawn: BTreeMap<usize, u32> = BTreeMap::new();
+        for (_, draws) in &logs {
+            for d in draws {
+                let off = d.vbase.wrapping_sub(base) as usize;
+                if off < bytes.len() && d.vcount >= 20 {
+                    drawn.insert(off, d.vcount);
+                }
+            }
+        }
+        // Which resources have the drawn vertex count, wherever we put them?
+        // Right size + wrong place is a different bug from never finding it.
+        let mut by_count: BTreeMap<usize, Vec<String>> = BTreeMap::new();
+        for m in &models {
+            let n: usize = m.meshes.iter().map(|s| s.positions.len()).sum();
+            by_count.entry(n).or_default().push(m.name.clone());
+        }
+        // Is a capture-proven offset even a candidate the scan considers?
+        // Absent ⇒ the run scan misses it; present ⇒ selection picked another.
+        let starts: BTreeSet<usize> =
+            sylpheed_formats::mesh::debug_vertex_run_starts(&bytes, 24).into_iter().collect();
+        eprintln!("{} stride-24 candidate starts in this container", starts.len());
+        println!("{:<12} {:>7} {:>9}  {:<44}  our resources with that vcount", "file offset", "vcount", "candidate", "claimed by our decode");
+        for (off, vcount) in &drawn {
+            let who = ours
+                .get(off)
+                .map(|v| {
+                    v.iter().map(|(n, c)| format!("{n}({c})")).collect::<Vec<_>>().join(", ")
+                })
+                .unwrap_or_else(|| "— NOBODY".into());
+            let same = by_count
+                .get(&(*vcount as usize))
+                .map(|v| v.join(", "))
+                .unwrap_or_else(|| "— none".into());
+            // Nearest resource we anchored at or before this offset — the
+            // likely owner of a buffer nobody claims.
+            let near = ours
+                .range(..=*off)
+                .next_back()
+                .map(|(o, v)| format!("{} @ -0x{:x}", v[0].0, off - o))
+                .unwrap_or_default();
+            let cand = if starts.contains(off) { "yes" } else { "NO" };
+            println!("0x{off:<10x} {vcount:>7} {cand:>9}  {who:<44}  {same:<34}  {near}");
+        }
+        return;
+    }
+    let mut groups: BTreeMap<Vec<(i64, i64, i64)>, Vec<String>> = BTreeMap::new();
+    for m in &models {
+        let pos: Vec<(i64, i64, i64)> =
+            m.meshes.iter().flat_map(|s| s.positions.iter().copied()).map(key).collect();
+        if pos.is_empty() {
+            continue;
+        }
+        groups.entry(pos).or_default().push(m.name.clone());
+    }
+    let shared: Vec<_> = groups.iter().filter(|(_, n)| n.len() > 1).collect();
+    eprintln!(
+        "{} models, {} distinct geometries, {} shared by >1 resource",
+        models.len(),
+        groups.len(),
+        shared.len()
+    );
+
+    for (pos, names) in shared {
+        let vcount = pos.len() as u32;
+        // A draw belongs to this geometry if every dumped position is one of
+        // the decoded ones (the log dumps at most the first 64).
+        let want: BTreeSet<(i64, i64, i64)> = pos.iter().copied().collect();
+        println!("\n{}  ({vcount} verts, {} resources)", names.join(" ≡ "), names.len());
+        for (log, draws) in &logs {
+            let hits: Vec<&CapturedDraw> = draws.iter().filter(|d| d.vcount == vcount).collect();
+            let all: BTreeSet<u32> = hits.iter().map(|d| d.vbase).collect();
+            let matching: Vec<&&CapturedDraw> = hits
+                .iter()
+                .filter(|d| !d.pos.is_empty() && d.pos.iter().all(|p| want.contains(&key(*p))))
+                .collect();
+            let ok: BTreeSet<u32> = matching.iter().map(|d| d.vbase).collect();
+            // A buffer we do NOT match may still be the mirrored twin: same
+            // geometry with x negated. That is the case our assembler papers
+            // over with `apply_twin_mirrors`.
+            let mirrored: BTreeSet<u32> = hits
+                .iter()
+                .filter(|d| !ok.contains(&d.vbase))
+                .filter(|d| {
+                    !d.pos.is_empty()
+                        && d.pos.iter().all(|p| want.contains(&key([-p[0], p[1], p[2]])))
+                })
+                .map(|d| d.vbase)
+                .collect();
+            println!(
+                "  {log:32} draws={:<5} vbases@vcount={:<3} ours={} mirrored={} other={}",
+                hits.len(),
+                all.len(),
+                ok.len(),
+                mirrored.len(),
+                all.len() - ok.len() - mirrored.len()
+            );
+            // Where does each captured buffer live in the container? One
+            // representative draw per vbase is enough.
+            let mut done: BTreeSet<u32> = BTreeSet::new();
+            for d in &hits {
+                if d.pos.len() < 8 || !done.insert(d.vbase) {
+                    continue;
+                }
+                let kind = if ok.contains(&d.vbase) {
+                    "ours"
+                } else if mirrored.contains(&d.vbase) {
+                    "mirror"
+                } else {
+                    "other"
+                };
+                let at = locate_run(&bytes, &d.pos);
+                let shown: Vec<String> =
+                    at.iter().take(4).map(|(o, s)| format!("0x{o:x}/stride{s}")).collect();
+                println!(
+                    "      vbase=0x{:08X} [{kind:6}] in container at: {}",
+                    d.vbase,
+                    if shown.is_empty() { "NOT FOUND".into() } else { shown.join(" ") }
+                );
+            }
+        }
+    }
+}

crates/sylpheed-formats/examples/sibling_rule_check.rs

@@ -0,0 +1,61 @@
+//! Does the legacy reader miss a field precisely when its value is shared?
+//!
+//! The corpus records four "sibling default" rules (`Size_Y` inherits `Size_X`,
+//! `FCSRange` inherits `RadarRange`, …) used to recover values for units never
+//! visited at runtime. If the rules are really a *deduplication artefact*, then
+//! the legacy reader should report the field absent exactly when the two values
+//! are equal on disc — and never otherwise.
+use sylpheed_formats::{IdxdObject, PakArchive};
+
+fn main() {
+    let disc = std::env::var("SYLPHEED_DISC").expect("set SYLPHEED_DISC");
+    let arc = PakArchive::open(format!("{disc}/dat/GP_MAIN_GAME_E.pak")).expect("pak");
+    let pairs = [
+        ("Size_Y", "Size_X"),
+        ("FCSRange", "RadarRange"),
+        ("DefencePoint", "AttackVesselPoint"),
+    ];
+    // legacy-absent x equal-on-disc, as a 2x2 table per pair.
+    let mut tally = [[[0usize; 2]; 2]; 3];
+    for e in arc.entries() {
+        let Ok(bytes) = arc.read(e) else { continue };
+        if !IdxdObject::is_idxd(&bytes) {
+            continue;
+        }
+        let Ok(obj) = IdxdObject::parse(&bytes) else { continue };
+        let Some(generic) = obj.record("Generic") else { continue };
+        if generic.get("Size_X").is_none() {
+            continue;
+        }
+        for (i, (field, sibling)) in pairs.iter().enumerate() {
+            let (Some(a), Some(b)) = (generic.get(field), generic.get(sibling)) else {
+                continue;
+            };
+            let legacy_absent = obj.get_f32(field).is_none();
+            tally[i][usize::from(legacy_absent)][usize::from(a == b)] += 1;
+            // The only cases where the rule PREDICTS WRONG: the reader misses
+            // the field and the two values differ, so "inherit the sibling"
+            // substitutes a number the disc contradicts.
+            if legacy_absent && a != b {
+                println!(
+                    "  rule-wrong: {:08x} {field} = {a} but {sibling} = {b} (ID {:?})",
+                    e.name_hash,
+                    obj.get_raw("ID")
+                );
+            }
+        }
+    }
+    println!("{:<14} {:>10} {:>10} {:>10} {:>10}", "pair", "seen+diff", "seen+eq", "MISS+diff", "MISS+eq");
+    for (i, (field, sibling)) in pairs.iter().enumerate() {
+        println!(
+            "{:<14} {:>10} {:>10} {:>10} {:>10}",
+            format!("{field}/{sibling}").chars().take(14).collect::<String>(),
+            tally[i][0][0],
+            tally[i][0][1],
+            tally[i][1][0],
+            tally[i][1][1]
+        );
+    }
+    println!("\n'MISS+diff' > 0 refutes 'the reader only misses shared values'.");
+    println!("'seen+eq'  > 0 refutes 'a shared value is always invisible'.");
+}

crates/sylpheed-formats/examples/slab_screen.rs

@@ -0,0 +1,74 @@
+//! Screen every ship family for a part that is wildly out of scale with its
+//! siblings — the "slab" signature of a mis-anchored block.
+//!
+//! Rendering `e106` found such a part (`bdy_03`, 600×1600×998 beside parts of
+//! ~250) that coverage, cross-container consistency, the capture oracle and the
+//! twin invariant were all blind to. Eyeballing does not scale to 166 containers;
+//! this does the same comparison numerically.
+//!
+//! Usage: slab_screen <resource3d_dir> [factor]
+use sylpheed_formats::mesh::Xbg7Model;
+use sylpheed_formats::ship::{is_base_part, ship_id_of};
+use std::collections::BTreeMap;
+
+fn main() {
+    let dir = std::env::args().nth(1).expect("resource3d dir");
+    let factor: f32 = std::env::args().nth(2).and_then(|s| s.parse().ok()).unwrap_or(4.0);
+    let mut files: Vec<_> = std::fs::read_dir(&dir)
+        .unwrap()
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("xpr"))
+        .collect();
+    files.sort();
+
+    let mut flagged = 0usize;
+    for f in &files {
+        let Ok(bytes) = std::fs::read(f) else { continue };
+        let mut by_ship: BTreeMap<String, Vec<(String, f32)>> = BTreeMap::new();
+        for m in Xbg7Model::anchor_models_cancellable(&bytes, 0.0, &|| false) {
+            if !is_base_part(&m.name) {
+                continue;
+            }
+            let Some(id) = ship_id_of(&m.name) else { continue };
+            let (mut lo, mut hi) = ([f32::MAX; 3], [f32::MIN; 3]);
+            for s in &m.meshes {
+                for q in &s.positions {
+                    for k in 0..3 {
+                        lo[k] = lo[k].min(q[k]);
+                        hi[k] = hi[k].max(q[k]);
+                    }
+                }
+            }
+            if lo[0] == f32::MAX {
+                continue;
+            }
+            // Compare the part's SMALLEST axis span, not its diagonal. A long
+            // thin part (an antenna, a 100 000-unit tether on `f002`) is
+            // legitimately huge in one axis and would swamp a diagonal test; a
+            // mis-anchored block is bulky in all three, which is what the e106
+            // slab looked like (600×1600×998 beside siblings of ~250).
+            let thin = (hi[0] - lo[0]).min(hi[1] - lo[1]).min(hi[2] - lo[2]);
+            by_ship.entry(id.to_string()).or_default().push((m.name.clone(), thin));
+        }
+        for (id, parts) in &by_ship {
+            if parts.len() < 3 {
+                continue; // no meaningful median
+            }
+            let mut d: Vec<f32> = parts.iter().map(|(_, x)| *x).collect();
+            d.sort_by(|a, b| a.partial_cmp(b).unwrap());
+            let median = d[d.len() / 2];
+            for (name, diag) in parts {
+                if *diag > median * factor {
+                    flagged += 1;
+                    println!(
+                        "{:<22} {name:<22} min-axis {diag:>8.0}  vs ship median {median:>8.0}  ({:.1}×)",
+                        f.file_name().unwrap().to_string_lossy(),
+                        diag / median
+                    );
+                }
+            }
+        }
+    }
+    println!("{flagged} parts flagged at {factor}× the ship median");
+}

crates/sylpheed-formats/examples/slb_fmt_probe.rs

@@ -0,0 +1,113 @@
+//! Does the `.slb` leading region decode as XMA1 under ANY plausible format?
+//!
+//! A first attempt at this hand-rolled the `fmt ` chunk and produced 0 PCM bytes
+//! for all 36 combinations — including ones that should have matched the crate's
+//! own working format. So it tested the chunk construction, not the hypothesis.
+//! This version replicates `slb::synth_xma1_fmt`'s exact byte layout and starts
+//! by reproducing its known result as a CONTROL; if the control does not match,
+//! nothing below it means anything.
+use std::io::Write;
+use std::process::{Command, Stdio};
+
+use sylpheed_formats::{movie_subtitle, slb, PakArchive};
+
+/// Byte-for-byte `slb::synth_xma1_fmt` (private there). Note the second
+/// parameter is a **channel mask**, not a stream count — mistaking it is what
+/// made the first probe meaningless.
+fn xma1_fmt(channels: u8, channel_mask: u16, rate: u32) -> Vec<u8> {
+    let mut fmt = Vec::with_capacity(40);
+    fmt.extend_from_slice(b"fmt ");
+    fmt.extend_from_slice(&32u32.to_le_bytes());
+    fmt.extend_from_slice(&0x0165u16.to_le_bytes()); // XMA1
+    fmt.extend_from_slice(&16u16.to_le_bytes()); // BitsPerSample
+    fmt.extend_from_slice(&0u16.to_le_bytes()); // EncodeOptions
+    fmt.extend_from_slice(&0u16.to_le_bytes()); // LargestSkip
+    fmt.extend_from_slice(&1u16.to_le_bytes()); // NumStreams
+    fmt.push(0); // LoopCount
+    fmt.push(3); // Version
+    fmt.extend_from_slice(&(rate * channels as u32 * 2).to_le_bytes());
+    fmt.extend_from_slice(&rate.to_le_bytes());
+    fmt.extend_from_slice(&0u32.to_le_bytes());
+    fmt.extend_from_slice(&0u32.to_le_bytes());
+    fmt.push(4); // SubframeData
+    fmt.push(channels);
+    fmt.extend_from_slice(&channel_mask.to_le_bytes());
+    fmt
+}
+
+fn riff(fmt: &[u8], data: &[u8]) -> Vec<u8> {
+    let mut out = Vec::with_capacity(12 + fmt.len() + 8 + data.len());
+    out.extend_from_slice(b"RIFF");
+    out.extend_from_slice(&((4 + fmt.len() + 8 + data.len()) as u32).to_le_bytes());
+    out.extend_from_slice(b"WAVE");
+    out.extend_from_slice(fmt);
+    out.extend_from_slice(b"data");
+    out.extend_from_slice(&(data.len() as u32).to_le_bytes());
+    out.extend_from_slice(data);
+    out
+}
+
+fn decode_bytes(r: &[u8]) -> usize {
+    let Ok(mut c) = Command::new("ffmpeg")
+        .args(["-v", "error", "-i", "pipe:0", "-f", "s16le", "pipe:1"])
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::null())
+        .spawn()
+    else {
+        return 0;
+    };
+    let buf = r.to_vec();
+    let mut stdin = c.stdin.take().unwrap();
+    std::thread::spawn(move || {
+        let _ = stdin.write_all(&buf);
+    });
+    c.wait_with_output().map(|o| o.stdout.len()).unwrap_or(0)
+}
+
+fn main() {
+    let disc = std::env::var("SYLPHEED_DISC").expect("set SYLPHEED_DISC");
+    let snd = PakArchive::open(format!("{disc}/dat/sound.pak")).expect("sound.pak");
+    let lang = PakArchive::open(format!("{disc}/dat/movie/eng.pak")).expect("eng.pak");
+
+    // The leading region decodes only as MONO. At channels=2 it yields 1792
+    // bytes; at channels=1, 203648 for VOICE_D_453. The decoded SAMPLE COUNT is
+    // independent of the declared rate (the rate only sets playback speed), so
+    // the subtitle cue can be used to solve for the real rate instead.
+    let bound = [
+        ("hokyu_LS_s02A", 450u32),
+        ("hokyu_LS_s09A", 451),
+        ("hokyu_DS_s13A", 452),
+        ("hokyu_LS_s02H", 453),
+        ("hokyu_DS_s07H", 454),
+    ];
+    println!(
+        "{:<16} {:>6} {:>9} {:>9} {:>10} {:>9} {:>12}",
+        "movie", "bank", "stereo B", "mono B", "samples", "cue s", "implied Hz"
+    );
+    for (movie, n) in bound {
+        let path = format!("eng\\etc\\VOICE_D_{n}.slb");
+        let Some(entry) = snd.find_by_name(&path) else { continue };
+        let bytes = snd.read(entry).expect("read");
+        let Some(first_riff) = bytes.windows(4).position(|w| w == b"RIFF") else { continue };
+        if first_riff <= slb::HEADERLESS_DATA_OFFSET {
+            println!("{movie:<16} {:>6}   (no leading region)", format!("D_{n}"));
+            continue;
+        }
+        let lead = &bytes[slb::HEADERLESS_DATA_OFFSET..first_riff];
+        let stereo = decode_bytes(&riff(&xma1_fmt(2, 2, 48000), lead));
+        let mono = decode_bytes(&riff(&xma1_fmt(1, 0, 48000), lead));
+        let samples = mono / 2; // 16-bit mono
+        let cue = movie_subtitle::track_voice_cues(&lang, movie)
+            .iter()
+            .map(|(_, t)| *t)
+            .fold(0.0f32, f32::max);
+        let implied = if cue > 0.0 { samples as f32 / cue } else { f32::NAN };
+        println!(
+            "{movie:<16} {:>6} {stereo:>9} {mono:>9} {samples:>10} {cue:>9.2} {implied:>12.0}",
+            format!("D_{n}")
+        );
+    }
+    println!("\n'implied Hz' = decoded samples / the movie's last subtitle cue.");
+    println!("A consistent value near a standard rate is the real sample rate.");
+}

crates/sylpheed-formats/examples/slb_hybrid_scan.rs

@@ -0,0 +1,31 @@
+//! How many `.slb` banks would a "leading headerless stream" rule affect?
+//!
+//! The rule fires when the first `RIFF` sits at exactly
+//! `HEADERLESS_DATA_OFFSET + n*XMA1_PACKET` with a non-zero leading region.
+//! Before trusting it, count how many banks it would change — including the
+//! `RT*` movie banks that already decode correctly today.
+use sylpheed_formats::{slb, PakArchive};
+
+fn main() {
+    let disc = std::env::var("SYLPHEED_DISC").expect("set SYLPHEED_DISC");
+    let snd = PakArchive::open(format!("{disc}/dat/sound.pak")).expect("sound.pak");
+    let (mut total, mut has_riff, mut hybrid, mut hybrid_nonzero) = (0, 0, 0, 0);
+    for e in snd.entries() {
+        let Ok(b) = snd.read(e) else { continue };
+        total += 1;
+        let Some(ri) = b.windows(4).position(|w| w == b"RIFF") else { continue };
+        has_riff += 1;
+        if ri > slb::HEADERLESS_DATA_OFFSET
+            && (ri - slb::HEADERLESS_DATA_OFFSET) % slb::XMA1_PACKET == 0
+        {
+            hybrid += 1;
+            if b[slb::HEADERLESS_DATA_OFFSET..ri].iter().any(|x| *x != 0) {
+                hybrid_nonzero += 1;
+            }
+        }
+    }
+    println!(
+        "sound.pak entries {total}; with a RIFF {has_riff}; \
+         first RIFF at 1392+n*2048 {hybrid}; of those with a NON-ZERO leading region {hybrid_nonzero}"
+    );
+}

crates/sylpheed-formats/examples/squadrons.rs

@@ -5,7 +5,7 @@ fn main(){
     let sq=game_data::load_squadrons(&pak);
     println!("{} squadron definitions", sq.len());
     for s in sq.iter().filter(|s|s.side.as_deref()==Some("TCAF")).take(6){
-        let mem:Vec<String>=s.members.iter().map(|m|m.trim_start_matches("UN_").chars().take(18).collect()).collect();
-        println!("  {:8} {:22} {:24} x{}  {:?}", s.id.clone().unwrap_or("?".into()), s.formation_id.clone().unwrap_or_default(), s.ai_id.clone().unwrap_or_default(), s.count.unwrap_or(0), mem);
+        let mem:Vec<String>=s.members.iter().map(|m|format!("{}/{}",m.unit.trim_start_matches("UN_").chars().take(18).collect::<String>(),m.pilot.clone().unwrap_or("·".into()))).collect();
+        println!("  {:8} {:22} {:24} x{}  {:?}", s.id.clone(), s.formation_id.clone().unwrap_or_default(), s.ai_id.clone().unwrap_or_default(), s.count.unwrap_or(0), mem);
     }
 }

crates/sylpheed-formats/examples/starts.rs

@@ -0,0 +1,13 @@
+use sylpheed_formats::mesh::{debug_resource_params, debug_vertex_run_starts};
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let bytes = std::fs::read(&a[1]).unwrap();
+    let (markers, stride) = debug_resource_params(&bytes, &a[2]).expect("resource");
+    println!("{}: stride={stride} markers={markers:?}", a[2]);
+    let starts = debug_vertex_run_starts(&bytes, stride);
+    println!("{} candidate starts at stride {stride}", starts.len());
+    for off in &a[3..] {
+        let o = usize::from_str_radix(off.trim_start_matches("0x"), 16).unwrap();
+        println!("  0x{o:x} in candidate list: {}", starts.binary_search(&o).is_ok());
+    }
+}

crates/sylpheed-formats/examples/starts_probe.rs

@@ -0,0 +1,7 @@
+fn main(){let a:Vec<String>=std::env::args().collect();let b=std::fs::read(&a[1]).unwrap();
+let stride:usize=a[2].parse().unwrap(); let want:usize=a[3].parse().unwrap();
+let s=sylpheed_formats::mesh::debug_vertex_run_starts(&b,stride);
+println!("{} candidate starts at stride {}", s.len(), stride);
+println!("contains {:#x}: {}", want, s.contains(&want));
+let near:Vec<String>=s.iter().filter(|&&o| o.abs_diff(want)<0x200).map(|o|format!("{o:#x}")).collect();
+println!("nearby: {}", near.join(" "));}

crates/sylpheed-formats/examples/submesh_dump.rs

@@ -0,0 +1,34 @@
+//! Per-sub-mesh vertex/index/coverage dump for one resource.
+//! Usage: submesh_dump <container.xpr> <resource>...
+use sylpheed_formats::mesh::{debug_resource_params, Xbg7Model};
+use std::collections::HashSet;
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let bytes = std::fs::read(&a[1]).expect("container");
+    let want: HashSet<String> = a[2..].iter().cloned().collect();
+    for m in Xbg7Model::models_named(&bytes, &want, &|| false) {
+        let markers = debug_resource_params(&bytes, &m.name).map(|(mk, _)| mk).unwrap_or_default();
+        println!("{} — {} sub-meshes decoded, {} markers declared", m.name, m.meshes.len(), markers.len());
+        for (i, s) in m.meshes.iter().enumerate() {
+            let max_idx = s.indices.iter().max().copied().unwrap_or(0) as usize;
+            let (mut lo, mut hi) = ([f32::MAX; 3], [f32::MIN; 3]);
+            for q in &s.positions {
+                for k in 0..3 {
+                    lo[k] = lo[k].min(q[k]);
+                    hi[k] = hi[k].max(q[k]);
+                }
+            }
+            println!(
+                "  #{i:<2} at 0x{:<9x} verts {:<6} idx {:<6} max_idx {:<6} slack {} span [{:.0} {:.0} {:.0}]",
+                s.vbuf_offset.unwrap_or(0),
+                s.positions.len(),
+                s.indices.len(),
+                max_idx,
+                s.positions.len() as i64 - 1 - max_idx as i64,
+                hi[0] - lo[0],
+                hi[1] - lo[1],
+                hi[2] - lo[2]
+            );
+        }
+    }
+}

crates/sylpheed-formats/examples/try_anchor.rs

@@ -0,0 +1,17 @@
+//! Does the capture-proven offset validate for the resource that should own it?
+use sylpheed_formats::mesh::debug_try_anchor;
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let bytes = std::fs::read(&a[1]).unwrap();
+    // The production scan tries pads 0..=3; pass a bigger one to ask whether the
+    // block would validate at all with a wider index/vertex gap.
+    let max_pad: usize = std::env::var("MAX_PAD").ok().and_then(|v| v.parse().ok()).unwrap_or(3);
+    for pair in a[2..].iter() {
+        let (name, off) = pair.split_once('@').unwrap();
+        let off = usize::from_str_radix(off.trim_start_matches("0x"), 16).unwrap();
+        match debug_try_anchor(&bytes, name, off, max_pad) {
+            Some((v, i, pad)) => println!("{name:22} @ 0x{off:x}  ACCEPTED  v={v} idx={i} pad={pad}"),
+            None => println!("{name:22} @ 0x{off:x}  rejected"),
+        }
+    }
+}

crates/sylpheed-formats/examples/twin_mirror_audit.rs

@@ -0,0 +1,119 @@
+//! Do port/starboard twins decode to mirror images of each other?
+//!
+//! A runtime capture proved the container stores both halves of the `e106` hull
+//! as separate, X-reflected buffers. That gives a **capture-free invariant**:
+//! a `…_01`/`…_02` pair of equal vertex count should decode to geometry that is
+//! an exact X-mirror — never to identical geometry (that is the collapse the
+//! distinct-assignment fix targets), and never to something unrelated (that is a
+//! mis-anchor no count-based metric can see).
+//!
+//! Usage: twin_mirror_audit <resource3d_dir>
+use sylpheed_formats::mesh::Xbg7Model;
+use std::collections::BTreeMap;
+
+fn key(p: [f32; 3]) -> (i64, i64, i64) {
+    (
+        (p[0] * 1e3).round() as i64,
+        (p[1] * 1e3).round() as i64,
+        (p[2] * 1e3).round() as i64,
+    )
+}
+
+/// Elementwise equality with a tolerance. Truncating keys is too strict for a
+/// mirrored pair: the halves are authored, not bit-negated, so they differ in
+/// the last digits and an exact key test reports them as unrelated.
+fn near(p: [f32; 3], q: [f32; 3]) -> bool {
+    (0..3).all(|c| (p[c] - q[c]).abs() <= 1e-3 * (1.0 + q[c].abs()))
+}
+
+fn main() {
+    let dir = std::env::args().nth(1).expect("resource3d dir");
+    let mut files: Vec<_> = std::fs::read_dir(&dir)
+        .unwrap()
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("xpr"))
+        .collect();
+    files.sort();
+
+    let (mut same, mut mirrored, mut unrelated, mut related) = (0usize, 0usize, 0usize, 0usize);
+    let mut examples: Vec<String> = Vec::new();
+    for f in &files {
+        let Ok(bytes) = std::fs::read(f) else { continue };
+        let models = Xbg7Model::anchor_models_cancellable(&bytes, 0.0, &|| false);
+        let by_name: BTreeMap<&str, &Xbg7Model> =
+            models.iter().map(|m| (m.name.as_str(), m)).collect();
+        for m in &models {
+            let Some(stem) = m.name.strip_suffix("_01") else { continue };
+            let Some(t) = by_name.get(format!("{stem}_02").as_str()) else { continue };
+            let a: Vec<[f32; 3]> = m.meshes.iter().flat_map(|s| s.positions.clone()).collect();
+            let b: Vec<[f32; 3]> = t.meshes.iter().flat_map(|s| s.positions.clone()).collect();
+            if a.len() != b.len() || a.is_empty() {
+                continue;
+            }
+            let ident = a.iter().zip(&b).all(|(p, q)| near(*p, *q));
+            let mirr = a.iter().zip(&b).all(|(p, q)| near([-p[0], p[1], p[2]], *q));
+            // A pair that is neither may still be RELATED: mirrored on another
+            // axis, or the same point cloud in a different vertex order. Only a
+            // pair that is none of these is evidence of a mis-anchor.
+            let mirr_y = a.iter().zip(&b).all(|(p, q)| near([p[0], -p[1], p[2]], *q));
+            let mirr_z = a.iter().zip(&b).all(|(p, q)| near([p[0], p[1], -p[2]], *q));
+            let set = |v: &Vec<[f32; 3]>| {
+                let mut s: Vec<_> = v.iter().map(|p| key(*p)).collect();
+                s.sort_unstable();
+                s
+            };
+            let same_cloud = set(&a) == set(&b);
+            // …and the same point cloud after mirroring, for a pair whose
+            // halves are authored in different vertex order.
+            let mirrored_cloud = {
+                let am: Vec<[f32; 3]> = a.iter().map(|p| [-p[0], p[1], p[2]]).collect();
+                set(&am) == set(&b)
+            };
+            if !ident && !mirr && (mirr_y || mirr_z || same_cloud || mirrored_cloud) {
+                related += 1;
+                continue;
+            }
+            // Identical GEOMETRY is only a collapse if it also comes from the
+            // same buffer: a container may store a part twice unmirrored, and
+            // then two twins on two copies decode identically and correctly.
+            let shared_buffer = m.meshes[0].vbuf_offset.is_some()
+                && m.meshes[0].vbuf_offset == t.meshes[0].vbuf_offset;
+            if ident && !shared_buffer {
+                related += 1;
+                continue;
+            }
+            if ident {
+                same += 1;
+                if examples.len() < 6 {
+                    examples.push(format!(
+                        "identical: {} / {}_02 in {}",
+                        m.name,
+                        stem,
+                        f.file_name().unwrap().to_string_lossy()
+                    ));
+                }
+            } else if mirr {
+                mirrored += 1;
+            } else {
+                unrelated += 1;
+                if examples.len() < 6 {
+                    examples.push(format!(
+                        "unrelated: {} / {}_02 in {}",
+                        m.name,
+                        stem,
+                        f.file_name().unwrap().to_string_lossy()
+                    ));
+                }
+            }
+        }
+    }
+    println!("twin pairs of equal vertex count: {}", same + mirrored + unrelated + related);
+    println!("  exact X-mirror (expected) : {mirrored}");
+    println!("  IDENTICAL, one buffer (collapse) : {same}");
+    println!("  related other way (Y/Z mirror, reordered): {related}");
+    println!("  unrelated  (mis-anchor?)  : {unrelated}");
+    for e in examples {
+        println!("  e.g. {e}");
+    }
+}

crates/sylpheed-formats/examples/undecoded.rs

@@ -0,0 +1,56 @@
+//! Which XBG7 resources never decode, and how big is that population?
+//!
+//! Coverage has been reported as "resources decoded" without a denominator. This
+//! prints both, per container and in total, and names the misses so the gate
+//! attribution (`why_rejected`) has a work list.
+use sylpheed_formats::mesh::{debug_resource_params, xbg7_resource_names, Xbg7Model};
+use std::collections::HashSet;
+
+fn main() {
+    let dir = std::env::args().nth(1).expect("resource3d dir");
+    let show = std::env::args().nth(2).is_some();
+    let mut files: Vec<_> = std::fs::read_dir(&dir)
+        .unwrap()
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("xpr"))
+        .collect();
+    files.sort();
+
+    let (mut total, mut decoded, mut no_decl) = (0usize, 0usize, 0usize);
+    let mut misses: Vec<String> = Vec::new();
+    for f in &files {
+        let Ok(bytes) = std::fs::read(f) else { continue };
+        let names = xbg7_resource_names(&bytes);
+        if names.is_empty() {
+            continue;
+        }
+        let got: HashSet<String> = Xbg7Model::anchor_models_cancellable(&bytes, 0.0, &|| false)
+            .into_iter()
+            .map(|m| m.name)
+            .collect();
+        for n in &names {
+            total += 1;
+            if got.contains(n) {
+                decoded += 1;
+            } else if debug_resource_params(&bytes, n).is_none() {
+                // No vertex declaration / no index markers: the anchor scan
+                // never even considers these, so they are a different question
+                // from "searched and not found".
+                no_decl += 1;
+            } else {
+                misses.push(format!("{}|{n}", f.file_name().unwrap().to_string_lossy()));
+            }
+        }
+    }
+    println!(
+        "XBG7 resources: {total} total, {decoded} decoded ({:.1}%), {no_decl} without a usable descriptor, {} searched-and-missed",
+        100.0 * decoded as f64 / total as f64,
+        misses.len()
+    );
+    if show {
+        for m in &misses {
+            println!("{m}");
+        }
+    }
+}

crates/sylpheed-formats/examples/unit_fields.rs

@@ -0,0 +1,31 @@
+//! Every key/value a named unit record actually sets on disc.
+//!
+//! The live definition object in guest RAM has no field names; to find where a
+//! field like `HQRatio` sits inside it, anchor on a unit whose disc record DOES
+//! set that field and look for the value. This prints those anchors.
+//! Run: unit_fields <disc-root> <substring of ID>...
+use sylpheed_formats::idxd::IdxdObject;
+use sylpheed_formats::pak::PakArchive;
+
+fn main() {
+    let disc = std::env::args().nth(1).expect("disc root");
+    let want: Vec<String> = std::env::args().skip(2).collect();
+    let pak = PakArchive::open(format!("{disc}/dat/GP_MAIN_GAME_E.pak")).expect("pak");
+    for entry in pak.entries() {
+        let Ok(bytes) = pak.read(entry) else { continue };
+        let Ok(obj) = IdxdObject::parse(&bytes) else { continue };
+        let Some(id) = obj.get_raw("ID") else { continue };
+        if !want.iter().any(|w| id.contains(w.as_str())) {
+            continue;
+        }
+        println!("=== {id}   (schema {:08x})", obj.schema_hash);
+        // The pool interleaves VALUE before KEY (see the module docs), so the
+        // pairs read (t[i] = value, t[i+1] = key).
+        let t = obj.tokens();
+        let mut i = 0;
+        while i + 1 < t.len() {
+            println!("    {:<30} {}", t[i + 1], t[i]);
+            i += 2;
+        }
+    }
+}

crates/sylpheed-formats/examples/unit_signatures.rs

@@ -0,0 +1,33 @@
+//! (HP, Size_X, Size_Y, Size_Z) for every craft unit and vessel on the disc.
+//!
+//! A live definition object in guest RAM carries HP at `+0x54` and the sizes at
+//! `+0x30/34/38` but no name in its first words, so identity has to come from the
+//! values themselves: this is the lookup table for that match.
+//! Run: unit_signatures <disc-root>
+use sylpheed_formats::game_data::{load_units, load_vessels};
+use sylpheed_formats::PakArchive;
+fn main() {
+    let disc = std::env::args().nth(1).expect("disc root");
+    let pak = PakArchive::open(format!("{disc}/dat/GP_MAIN_GAME_E.pak")).expect("pak");
+    println!("{:<34} {:>9} {:>8} {:>8} {:>8}  kind", "id", "hp", "size_x", "size_y", "size_z");
+    for u in load_units(&pak) {
+        println!(
+            "{:<34} {:>9} {:>8} {:>8} {:>8}  unit",
+            u.id.unwrap_or_default(),
+            u.hp.map(|v| v.to_string()).unwrap_or("—".into()),
+            u.size_x.map(|v| v.to_string()).unwrap_or("—".into()),
+            u.size_y.map(|v| v.to_string()).unwrap_or("—".into()),
+            u.size_z.map(|v| v.to_string()).unwrap_or("—".into()),
+        );
+    }
+    for v in load_vessels(&pak) {
+        println!(
+            "{:<34} {:>9} {:>8} {:>8} {:>8}  vessel",
+            v.id.unwrap_or_default(),
+            v.hp.map(|x| x.to_string()).unwrap_or("—".into()),
+            v.size_x.map(|x| x.to_string()).unwrap_or("—".into()),
+            v.size_y.map(|x| x.to_string()).unwrap_or("—".into()),
+            v.size_z.map(|x| x.to_string()).unwrap_or("—".into()),
+        );
+    }
+}

crates/sylpheed-formats/examples/unit_values.rs

@@ -0,0 +1,22 @@
+use sylpheed_formats::idxd::IdxdObject;
+use sylpheed_formats::pak::PakArchive;
+fn main() {
+    let disc = std::env::args().nth(1).unwrap();
+    let want = std::env::args().nth(2).unwrap();
+    let pak = PakArchive::open(format!("{disc}/dat/GP_MAIN_GAME_E.pak")).unwrap();
+    for e in pak.entries() {
+        let Ok(b) = pak.read(e) else { continue };
+        let Ok(o) = IdxdObject::parse(&b) else { continue };
+        let Some(id) = o.get_raw("ID") else { continue };
+        if !id.contains(&want) { continue; }
+        println!("=== {id}");
+        let mut seen = std::collections::BTreeSet::new();
+        for k in o.tokens() {
+            if let Some(v) = o.get_f32(k) {
+                if v != 0.0 && seen.insert(k.clone()) {
+                    println!("  {:<28} {:<12} 0x{:08x}", k, v, v.to_bits());
+                }
+            }
+        }
+    }
+}

crates/sylpheed-formats/examples/verify_fieldmap.rs

@@ -0,0 +1,70 @@
+//! Check the code-derived offset→field map against the live dump, then read out
+//! the runtime value of every field the disc record leaves defaulted.
+//! Run: verify_fieldmap <disc-root> <live-dump> <ID=0xVA>...
+use std::collections::BTreeMap;
+use sylpheed_formats::idxd::IdxdObject;
+use sylpheed_formats::pak::PakArchive;
+
+// Offsets read out of sub_82341A20's own key strings (stfs stores only).
+// Offsets and names recovered from `sub_82341A20` itself: each key is built as
+// `addi r4, r30, -N` (r30 = 0x82088f94, so the name is a string in the image),
+// and the value lands in the first store into the object after the accessor
+// call. 125 float-typed fields.
+const MAP: &[(usize, &str)] = &[(48, "Size_X"), (52, "Size_Y"), (56, "Size_Z"), (64, "Color_R"), (68, "Color_G"), (72, "Color_B"), (80, "Size_Radius"), (84, "HP"), (88, "HQRatio"), (92, "ShieldRatio"), (96, "ThrusterRatio"), (116, "ResistanceToOptics"), (120, "ResistanceToShell"), (124, "ResistanceToExplosion"), (128, "ResistanceToPlayer"), (132, "ResistanceParalyze"), (156, "MinimumVelocity"), (160, "MaximumVelocity"), (164, "CruisingVelocity"), (168, "Acceleration"), (172, "Deceleration"), (176, "AV_PitchPlus_Max"), (180, "AV_PitchPlus_Min"), (184, "AA_PitchPlus_Max"), (188, "AA_PitchPlus_Min"), (192, "AV_PitchMinus_Max"), (196, "AV_PitchMinus_Min"), (200, "AA_PitchMinus_Max"), (204, "AA_PitchMinus_Min"), (208, "AV_Yaw_Max"), (212, "AV_Yaw_Min"), (216, "AA_Yaw_Max"), (220, "AA_Yaw_Min"), (224, "AV_Roll_Max"), (228, "AV_Roll_Min"), (232, "AA_Roll_Max"), (236, "AA_Roll_Min"), (248, "SideThrustVelocity_Max"), (252, "SideThrustAcceleration"), (256, "MaximumBank_Normal"), (260, "YawDragFactor"), (264, "PitchDragFactor"), (268, "RollDragFactor"), (272, "DragFactorThreshold"), (276, "ArterBurner_Vc"), (280, "ReverseThrust_Vc"), (284, "ArterBurner_Acc"), (288, "ReverseThrust_Acc"), (292, "AccPitchFactor"), (296, "DecPitchFactor"), (300, "AV_AxisMode_Max"), (304, "AV_AxisMode_Min"), (308, "AA_AxisMode_Max"), (312, "AA_AxisMode_Min"), (316, "PowerCutConsumeShield"), (320, "PowerCutDeceleration"), (324, "AB_ConsumeShield_Begin"), (328, "AB_ConsumeShield"), (332, "AB_AV_PitchPlus"), (336, "AB_AA_PitchPlus"), (340, "AB_AV_PitchMinus"), (344, "AB_AA_PitchMinus"), (348, "AB_AV_Yaw"), (352, "AB_AA_Yaw"), (356, "AB_AV_Roll"), (360, "AB_AA_Roll"), (368, "SideRoll_Time"), (372, "SideRoll_Length"), (380, "BarrelRoll_CountMinimum"), (384, "BarrelRoll_CountMaximum"), (388, "BarrelRoll_Time"), (392, "BarrelRoll_Radius"), (400, "TurnAttack_CutoffRatio"), (404, "TurnAttack_DoubleRatio"), (408, "CutoffTimeMin"), (412, "CutoffTimeMax"), (416, "TurnAttack_DoubleTimeMin"), (420, "TurnAttack_DoubleTimeMax"), (428, "Turn_AngularVelocity"), (432, "TurnAway_Time_Minimum"), (436, "TurnAway_Time_Maximum"), (444, "BoostAway_Time_Minimum"), (448, "BoostAway_Time_Maximum"), (456, "HoldPosition_LengthMin"), (460, "HoldPosition_LengthMax"), (464, "HoldPosition_MinimumTime"), (468, "HoldPosition_MaximumTime"), (472, "HoldPosition_SideRatio"), (476, "HoldPosition_BackRatio"), (480, "HoldPosition_CutoffRatio"), (484, "HoldPosition_CancelTime"), (492, "Slalom_CutoffRatio"), (496, "Slalom_TurnCount_Min"), (500, "Slalom_TurnCount_Max"), (508, "Through_CutoffRatio"), (512, "Through_AngleMinimum"), (516, "Through_AngleMaximum"), (520, "Through_Time1Max"), (524, "Through_Time1Min"), (528, "Through_Time2Max"), (532, "Through_Time2Min"), (536, "Through_LengthMinimum"), (540, "Through_LengthMaximum"), (548, "SolidCutoff_Ratio"), (552, "SolidCutoff_LengthMin"), (556, "SolidCutoff_LengthMax"), (560, "HomingResistAdjustment"), (564, "UsingChaffRatio"), (568, "MaxValue"), (572, "ChargeDelay"), (576, "ChargeDelay_Break"), (580, "ChargeSpeed"), (584, "Delay"), (588, "DelayAdjustment"), (624, "DestroyMotionTime"), (628, "DryMass"), (632, "GrossMass"), (664, "LowerHPThresholdRatio"), (668, "SELength"), (672, "RadarRange"), (676, "FCSRange"), (680, "FiringRange"), (692, "AttackVesselPoint"), (696, "AttackCraftPoint"), (700, "DefencePoint")];
+
+fn main() {
+    let mut a = std::env::args().skip(1);
+    let disc = a.next().unwrap();
+    let dump = a.next().unwrap();
+    let pairs: Vec<(String, String)> =
+        a.filter_map(|s| s.split_once('=').map(|(i, v)| (i.into(), v.into()))).collect();
+
+    let mut live: BTreeMap<String, BTreeMap<usize, f32>> = BTreeMap::new();
+    let mut cur = String::new();
+    for line in std::fs::read_to_string(&dump).unwrap().lines() {
+        if let Some(r) = line.strip_prefix("=== ") { cur = r.trim().into(); continue; }
+        let f: Vec<&str> = line.split_whitespace().collect();
+        // dump columns: addr  +off  hex  u32  f32  -- the float is f[4], not f[3]
+        if f.len() >= 5 && f[1].starts_with('+') {
+            if let (Ok(o), Ok(v)) = (usize::from_str_radix(&f[1][1..], 16), f[4].parse::<f32>()) {
+                live.entry(cur.clone()).or_default().insert(o, v);
+            }
+        }
+    }
+
+    let pak = PakArchive::open(format!("{disc}/dat/GP_MAIN_GAME_E.pak")).unwrap();
+    let (mut agree, mut disagree) = (0, 0);
+    let mut defaults: BTreeMap<String, Vec<(String, f32)>> = BTreeMap::new();
+    for e in pak.entries() {
+        let Ok(b) = pak.read(e) else { continue };
+        let Ok(o) = IdxdObject::parse(&b) else { continue };
+        let Some(id) = o.get_raw("ID") else { continue };
+        let Some((_, va)) = pairs.iter().find(|(i, _)| i == id) else { continue };
+        let Some(w) = live.get(va) else { continue };
+        for (off, key) in MAP {
+            let Some(got) = w.get(off) else { continue };
+            match o.get_f32(key) {
+                Some(want) => {
+                    // Angle fields are stored in RADIANS at runtime and degrees on
+                    // disc, so a match is either the raw value or its conversion.
+                    let rad = want * std::f32::consts::PI / 180.0;
+                    let ok = (want - got).abs() <= want.abs() * 1e-4
+                        || (rad - got).abs() <= rad.abs() * 1e-4;
+                    if ok { agree += 1 } else {
+                        disagree += 1;
+                        println!("  MISMATCH {id} {key}: disc {want}, live +{off} = {got}");
+                    }
+                }
+                None => defaults.entry((*key).into()).or_default().push((id.into(), *got)),
+            }
+        }
+    }
+    println!("\nmap check: {agree} fields agree with the disc, {disagree} disagree\n");
+    println!("runtime value where the disc record DEFAULTS the field:");
+    for (key, hits) in &defaults {
+        let vals: Vec<String> = hits.iter().map(|(_, v)| format!("{v}")).collect();
+        let uniq: std::collections::BTreeSet<&String> = vals.iter().collect();
+        println!("  {:<22} {:<28} ({} units)", key,
+            uniq.iter().map(|s| s.as_str()).collect::<Vec<_>>().join(", "), hits.len());
+    }
+}

crates/sylpheed-formats/examples/voice_bank_dump.rs

@@ -0,0 +1,19 @@
+//! Dump each resupply voice bank's sub-waves to `.xma` RIFFs for decoding.
+use sylpheed_formats::{slb, PakArchive};
+
+fn main() {
+    let disc = std::env::var("SYLPHEED_DISC").expect("set SYLPHEED_DISC");
+    let out = std::env::var("OUT_DIR_X").unwrap_or_else(|_| "/tmp/voicebanks".into());
+    std::fs::create_dir_all(&out).unwrap();
+    let snd = PakArchive::open(format!("{disc}/dat/sound.pak")).expect("sound.pak");
+    for n in 450..=454 {
+        let path = format!("eng\\etc\\VOICE_D_{n}.slb");
+        let Some(entry) = snd.find_by_name(&path) else { continue };
+        let bytes = snd.read(entry).expect("read");
+        for (i, r) in slb::to_xma_riffs(&bytes).iter().enumerate() {
+            let f = format!("{out}/VOICE_D_{n}_{i}.xma");
+            std::fs::write(&f, r).unwrap();
+            println!("{f} {} bytes", r.len());
+        }
+    }
+}

crates/sylpheed-formats/examples/voice_bank_shape.rs

@@ -0,0 +1,85 @@
+//! How many sub-waves does each resupply voice bank hold?
+//!
+//! The corpus records `VOICE_D_452` as the binding the game rejected in-game
+//! ("wrong recording"), and separately notes that `VOICE_D_453`/`454` decode to
+//! 0.14 s / 0.43 s — "far too short for the spoken line". Both observations are
+//! explained if these banks are multi-sub-wave and the extractor plays only the
+//! first. This prints the shape so that stops being a guess.
+use sylpheed_formats::{slb, PakArchive};
+
+fn main() {
+    let disc = std::env::var("SYLPHEED_DISC").expect("set SYLPHEED_DISC");
+    let snd = PakArchive::open(format!("{disc}/dat/sound.pak")).expect("sound.pak");
+    println!(
+        "{:<14} {:>7} {:>6} {:>6} {:>7}  sub-wave data sizes",
+        "bank", "bytes", "RIFFs", "waves", "cover"
+    );
+    for n in 450..=454 {
+        for dir in ["etc", "Voice", "Movie"] {
+            let path = format!("eng\\{dir}\\VOICE_D_{n}.slb");
+            let Some(entry) = snd.find_by_name(&path) else { continue };
+            let bytes = snd.read(entry).expect("read");
+            let riffs = slb::to_xma_riffs(&bytes);
+            let sizes: Vec<usize> = riffs.iter().map(|r| r.len()).collect();
+            // How many RIFF magics does the bank actually contain, versus how
+            // many sub-waves the walker recovered? A gap means the walk stops
+            // early, and the missing bytes are the missing audio.
+            let magics = bytes.windows(4).filter(|w| *w == b"RIFF").count();
+            let covered: usize = sizes.iter().sum();
+            // What are the UNCOVERED bytes? If the tail past the last data
+            // chunk is all zero it is padding and the short duration is real;
+            // if it is high-entropy it is audio the parse is throwing away.
+            let last = bytes
+                .windows(4)
+                .rposition(|w| w == b"data")
+                .map(|i| {
+                    let sz = u32::from_le_bytes(bytes[i + 4..i + 8].try_into().unwrap()) as usize;
+                    (i + 8 + sz).min(bytes.len())
+                })
+                .unwrap_or(0);
+            // Where does the RIFF structure START? If it begins far into the
+            // file, the uncovered bytes are a leading region the parse skips,
+            // not a missed sub-wave.
+            let first_riff = bytes.windows(4).position(|w| w == b"RIFF").unwrap_or(0);
+            let datas = bytes.windows(4).filter(|w| *w == b"data").count();
+            // Is the leading region padding, or content? Padding is nearly all
+            // zero and uses few distinct byte values.
+            let head = &bytes[..first_riff];
+            let head_zero = head.iter().filter(|b| **b == 0).count();
+            let head_distinct = {
+                let mut seen = [false; 256];
+                for b in head {
+                    seen[*b as usize] = true;
+                }
+                seen.iter().filter(|s| **s).count()
+            };
+            let tail = &bytes[last..];
+            let zeros = tail.iter().filter(|b| **b == 0).count();
+            // Dump the first bytes of the leading region so its structure is
+            // visible rather than guessed at.
+            let hex: String = head
+                .iter()
+                .take(48)
+                .map(|b| format!("{b:02x}"))
+                .collect::<Vec<_>>()
+                .join(" ");
+            println!("  head[0..48] {hex}");
+            println!(
+                "{:<14} {:>7} {:>6} {:>6} {:>6.1}%  1st RIFF @{:>6}  data chunks {}  head {:>5.1}% zero/{:>3} distinct  tail {:>5} B ({:>5.1}% zero)  {:?}",
+                format!("VOICE_D_{n}"),
+                bytes.len(),
+                magics,
+                riffs.len(),
+                100.0 * covered as f64 / bytes.len() as f64,
+                first_riff,
+                datas,
+                if head.is_empty() { 0.0 } else { 100.0 * head_zero as f64 / head.len() as f64 },
+                head_distinct,
+                tail.len(),
+                if tail.is_empty() { 0.0 } else { 100.0 * zeros as f64 / tail.len() as f64 },
+                sizes
+            );
+            break;
+        }
+    }
+}

crates/sylpheed-formats/examples/voice_len_vs_subs.rs

@@ -0,0 +1,78 @@
+//! Is audio actually missing from the resupply banks? Ask the subtitles.
+//!
+//! The `.slb` decode of `VOICE_D_453` yields 0.14 s, which "looks too short" —
+//! but that judgement was an impression. The subtitle track for each movie
+//! carries cue times, so it says independently how long the spoken line runs.
+//! If the last cue lands near the decoded length, nothing is missing; if it lands
+//! far past it, audio really is being lost.
+use sylpheed_formats::{movie_subtitle, slb, PakArchive};
+
+/// XMA1 at 48 kHz stereo, 16-bit → bytes per second of PCM.
+const PCM_BYTES_PER_SEC: f32 = 48000.0 * 2.0 * 2.0;
+
+/// Decode one sub-wave with FFmpeg and return its length in seconds. Measured,
+/// not estimated from a compression ratio — the ratio guess was the first version
+/// of this and it is not good enough to hang a conclusion on.
+fn decoded_secs(riff: &[u8]) -> f32 {
+    use std::io::Write;
+    use std::process::{Command, Stdio};
+    let Ok(mut c) = Command::new("ffmpeg")
+        .args(["-v", "error", "-i", "pipe:0", "-f", "s16le", "pipe:1"])
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::null())
+        .spawn()
+    else {
+        return f32::NAN;
+    };
+    let buf = riff.to_vec();
+    let mut stdin = c.stdin.take().unwrap();
+    std::thread::spawn(move || {
+        let _ = stdin.write_all(&buf);
+    });
+    let out = c.wait_with_output().expect("ffmpeg");
+    out.stdout.len() as f32 / PCM_BYTES_PER_SEC
+}
+
+fn main() {
+    let disc = std::env::var("SYLPHEED_DISC").expect("set SYLPHEED_DISC");
+    let snd = PakArchive::open(format!("{disc}/dat/sound.pak")).expect("sound.pak");
+    let lang = PakArchive::open(format!("{disc}/dat/movie/eng.pak")).expect("eng.pak");
+
+    // movie → the bank the record table binds it to.
+    let bound = [
+        ("hokyu_LS_s02A", 450),
+        ("hokyu_LS_s09A", 451),
+        ("hokyu_DS_s13A", 452),
+        ("hokyu_LS_s02H", 453),
+        ("hokyu_DS_s07H", 454),
+    ];
+    println!(
+        "{:<18} {:>6} {:>10} {:>12} {:>12}",
+        "movie", "bank", "last cue s", "decoded s", "verdict"
+    );
+    for (movie, n) in bound {
+        let cues = movie_subtitle::track_voice_cues(&lang, movie);
+        let last = cues.iter().map(|(_, t)| *t).fold(0.0f32, f32::max);
+        let path = format!("eng\\etc\\VOICE_D_{n}.slb");
+        let Some(entry) = snd.find_by_name(&path) else { continue };
+        let bytes = snd.read(entry).expect("read");
+        // Sum the sub-waves' payloads as the decoder currently sees them.
+        let riffs = slb::to_xma_riffs(&bytes);
+        let secs: f32 = riffs.iter().map(|r| decoded_secs(r)).sum();
+        // One-directional: a subtitle that appears at t seconds cannot sit inside
+        // a clip shorter than t. A cue at 0.0 tells us nothing either way.
+        let verdict = if last == 0.0 {
+            "no cue signal"
+        } else if last > secs {
+            "AUDIO MISSING"
+        } else {
+            "consistent"
+        };
+        println!(
+            "{movie:<18} {:>6} {last:>10.2} {secs:>12.2} {verdict:>12}   cues={}",
+            format!("D_{n}"),
+            cues.len()
+        );
+    }
+}

crates/sylpheed-formats/examples/why_missed.rs

@@ -0,0 +1,19 @@
+//! Why does a named resource never decode? Reports the furthest gate its best
+//! candidate reached. Usage: why_missed <container.xpr> [name-substring]
+use sylpheed_formats::mesh::{debug_best_rejection, xbg7_resource_names, Xbg7Model};
+use std::collections::HashSet;
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let bytes = std::fs::read(&a[1]).unwrap();
+    let filter = a.get(2).cloned().unwrap_or_default();
+    let decoded: HashSet<String> = Xbg7Model::stage_models(&bytes).into_iter().map(|m| m.name).collect();
+    for n in xbg7_resource_names(&bytes) {
+        if decoded.contains(&n) || (!filter.is_empty() && !n.contains(&filter)) {
+            continue;
+        }
+        match debug_best_rejection(&bytes, &n) {
+            Some((rank, why)) => println!("{n:<28} rank {rank}  {why}"),
+            None => println!("{n:<28} (no candidate reached any gate / skipped before anchoring)"),
+        }
+    }
+}

crates/sylpheed-formats/examples/why_rejected.rs

@@ -0,0 +1,14 @@
+//! Why does the decoder refuse a grouped-pool resource at a given pool start?
+//! Usage: why_rejected <container.xpr> <resource>@<vb0-hex>...
+use sylpheed_formats::mesh::debug_grouped_report;
+fn main() {
+    let a: Vec<String> = std::env::args().collect();
+    let bytes = std::fs::read(&a[1]).expect("container");
+    for pair in &a[2..] {
+        let (name, off) = pair.split_once('@').expect("name@hex");
+        let vb0 = usize::from_str_radix(off.trim_start_matches("0x"), 16).expect("hex");
+        for line in debug_grouped_report(&bytes, name, vb0) {
+            println!("{line}");
+        }
+    }
+}

crates/sylpheed-formats/src/audio.rs

@@ -1,85 +1,405 @@
-//! Audio format parsing — XMA and XWB handling.
+//! Audio format parsing — WAV/PCM decode + Xbox 360 XMA/XMA2 recognition.
 //!
-//! Xbox 360 games use **XMA** (Xbox Media Audio) as their primary audio codec.
-//! XMA is a proprietary Microsoft codec derived from WMA Pro.
+//! ## What the game actually ships
+//! Project Sylpheed's in-game audio lives in `dat/sound.pak` (IPFB): ~9500
+//! entries of **raw, header-less XMA2** stream data — no per-entry `RIFF`/`fmt `
+//! header, no compression wrapper (identical sound effects are byte-for-byte
+//! duplicate entries). The per-stream format (channel count, sample rate, loop
+//! points) is therefore **not** in the stream data; it lives in a separate
+//! sound-bank descriptor that has not been reverse engineered yet. So this
+//! module can *identify* those streams (and count their XMA packets) but cannot
+//! yet decode them to PCM — that needs (a) the bank descriptor and (b) an XMA2
+//! decoder.
 //!
-//! ## The Challenge
-//! XMA decoding requires Microsoft's proprietary XMA decoder, which is only
-//! available in the Windows DirectX runtime. There are two approaches:
+//! ## What this module does today
+//! - Fully parses **RIFF/WAVE PCM** (8/16/24-bit int, 32-bit float) → `GameAudio`
+//!   (interleaved `f32`), ready for playback/export of any converted audio.
+//! - Reads metadata from **RIFF/WAVE XMA (`0x0165`) / XMA2 (`0x0166`)** headers
+//!   (channels, sample rate) — decode still unsupported.
+//! - Recognizes **raw XMA2** stream blobs by entropy + packet alignment and
+//!   reports the 2048-byte packet count.
 //!
-//! ### Option A: Convert on extraction (recommended for Milestone 1)
-//! Use `xma2encode.exe` (from Xbox 360 SDK) or `ffmpeg` (has partial XMA support)
-//! to pre-convert all audio to OGG/WAV during the extraction step.
-//!
-//! ```bash
-//! # Convert a single XMA file to WAV using ffmpeg
-//! ffmpeg -i audio.xma output.wav
-//!
-//! # Or use VGMStream's test.exe for more accurate XMA decoding
-//! ```
-//!
-//! ### Option B: XMA2 software decoder
-//! The `xma2dec` project provides an open-source XMA2 decoder.
-//! GitHub: https://github.com/koolkdev/xmalib (research-quality)
-//!
-//! ### XWB Wave Bank format
-//! Xbox 360 games typically bundle audio into XWB (Xbox Wave Bank) files.
-//! These are containers that hold multiple XMA streams.
-//! Reference: https://github.com/microsoft/DirectXTK/tree/main/Audio
+//! XMA framing constants are from xenia-canary `src/xenia/apu/xma_context.h`
+//! (`kBytesPerPacket = 2048`, `kSamplesPerFrame = 512`, `kBytesPerSample = 2`).
 
 use thiserror::Error;
 
+// XMA framing (xenia-canary xma_context.h).
+/// One XMA2 packet is 2048 bytes (4-byte header + 2044 bytes of frame data).
+pub const XMA_BYTES_PER_PACKET: usize = 2048;
+/// Decoded PCM samples produced per XMA frame, per channel.
+pub const XMA_SAMPLES_PER_FRAME: u32 = 512;
+
+// WAVE format tags.
+const WAVE_FORMAT_PCM: u16 = 0x0001;
+const WAVE_FORMAT_IEEE_FLOAT: u16 = 0x0003;
+const WAVE_FORMAT_EXTENSIBLE: u16 = 0xFFFE;
+const WAVE_FORMAT_XMA: u16 = 0x0165;
+const WAVE_FORMAT_XMA2: u16 = 0x0166;
+
 #[derive(Debug, Error)]
 pub enum AudioError {
-    #[error("Unknown audio format magic: {0:?}")]
-    UnknownMagic([u8; 4]),
-    #[error("XMA decoding requires pre-conversion. See audio.rs for instructions.")]
-    XmaNotSupported,
-    #[error("Parse error: {0}")]
-    Parse(String),
+    #[error("not a recognized audio container")]
+    Unrecognized,
+    #[error("malformed audio: {0}")]
+    Malformed(&'static str),
+    #[error("codec needs a decoder this crate does not provide: {0:?}")]
+    NeedsDecoder(AudioCodec),
+    #[error("unsupported PCM sample format: tag {tag:#06x}, {bits} bits")]
+    UnsupportedPcm { tag: u16, bits: u16 },
 }
 
-/// An audio clip decoded to raw PCM, ready for Bevy's audio system.
+/// Recognized audio container / codec.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AudioCodec {
+    /// RIFF/WAVE integer PCM (`WAVE_FORMAT_PCM`).
+    Pcm,
+    /// RIFF/WAVE IEEE-float PCM (`WAVE_FORMAT_IEEE_FLOAT`).
+    PcmFloat,
+    /// RIFF/WAVE XMA (`0x0165`).
+    Xma,
+    /// RIFF/WAVE XMA2 (`0x0166`).
+    Xma2,
+    /// Header-less XMA2 stream (the game's `sound.pak` entries), identified
+    /// heuristically — no embedded channel/rate metadata.
+    RawXma2,
+    Unknown,
+}
+
+impl AudioCodec {
+    /// Does decoding this codec require support this crate does not (yet) have?
+    pub fn needs_decoder(&self) -> bool {
+        matches!(self, Self::Xma | Self::Xma2 | Self::RawXma2)
+    }
+
+    pub fn label(&self) -> &'static str {
+        match self {
+            Self::Pcm => "PCM",
+            Self::PcmFloat => "PCM float",
+            Self::Xma => "XMA (RIFF)",
+            Self::Xma2 => "XMA2 (RIFF)",
+            Self::RawXma2 => "XMA2 (raw stream)",
+            Self::Unknown => "unknown",
+        }
+    }
+}
+
+/// Non-decoding metadata describing an audio blob.
+#[derive(Debug, Clone)]
+pub struct AudioInfo {
+    pub codec: AudioCodec,
+    pub channels: Option<u16>,
+    pub sample_rate: Option<u32>,
+    pub bits_per_sample: Option<u16>,
+    /// PCM samples per channel, when derivable (WAV only).
+    pub samples_per_channel: Option<u64>,
+    pub duration_secs: Option<f32>,
+    pub size_bytes: usize,
+    /// 2048-byte XMA packet count, for XMA/raw-XMA streams.
+    pub xma_packets: Option<u32>,
+}
+
+impl AudioInfo {
+    fn empty(codec: AudioCodec, size: usize) -> Self {
+        Self {
+            codec,
+            channels: None,
+            sample_rate: None,
+            bits_per_sample: None,
+            samples_per_channel: None,
+            duration_secs: None,
+            size_bytes: size,
+            xma_packets: None,
+        }
+    }
+
+    /// Best-effort classification of an audio blob. Never fails: unrecognized
+    /// input yields [`AudioCodec::Unknown`].
+    ///
+    /// Order matters: a `RIFF/WAVE` header is authoritative; only header-less,
+    /// high-entropy, packet-sized blobs fall through to the raw-XMA2 heuristic.
+    pub fn probe(bytes: &[u8]) -> Self {
+        if let Some(info) = parse_riff_wave(bytes) {
+            return info;
+        }
+        if looks_like_raw_xma2(bytes) {
+            let mut info = Self::empty(AudioCodec::RawXma2, bytes.len());
+            info.xma_packets = Some(bytes.len().div_ceil(XMA_BYTES_PER_PACKET) as u32);
+            return info;
+        }
+        Self::empty(AudioCodec::Unknown, bytes.len())
+    }
+}
+
+/// True when `bytes` is likely a raw, header-less XMA2 stream: no known audio
+/// magic, but a large, near-incompressible (high-entropy) payload — the shape
+/// of the game's `sound.pak` audio entries. Heuristic: not conclusive, but the
+/// probe runs only after every structured format has been ruled out.
+pub fn looks_like_raw_xma2(bytes: &[u8]) -> bool {
+    // XMA streams are always at least a couple of packets long.
+    if bytes.len() < XMA_BYTES_PER_PACKET * 2 {
+        return false;
+    }
+    if bytes.starts_with(b"RIFF") || bytes.starts_with(b"XMA2") {
+        return false; // handled by the RIFF path
+    }
+    shannon_entropy_bits(&bytes[..bytes.len().min(64 * 1024)]) >= 7.8
+}
+
+/// Shannon entropy in bits/byte over `data` (0.0..=8.0). Compressed audio sits
+/// very close to 8; structured/text data is much lower.
+fn shannon_entropy_bits(data: &[u8]) -> f64 {
+    if data.is_empty() {
+        return 0.0;
+    }
+    let mut counts = [0u32; 256];
+    for &b in data {
+        counts[b as usize] += 1;
+    }
+    let n = data.len() as f64;
+    counts
+        .iter()
+        .filter(|&&c| c > 0)
+        .map(|&c| {
+            let p = c as f64 / n;
+            -p * p.log2()
+        })
+        .sum()
+}
+
+// ── RIFF/WAVE ──────────────────────────────────────────────────────────────────
+
+/// Parse a RIFF/WAVE header for metadata. Returns `None` if `bytes` is not a
+/// `RIFF....WAVE` container. All RIFF fields are little-endian.
+fn parse_riff_wave(bytes: &[u8]) -> Option<AudioInfo> {
+    if bytes.len() < 12 || &bytes[..4] != b"RIFF" || &bytes[8..12] != b"WAVE" {
+        return None;
+    }
+    let le16 = |o: usize| u16::from_le_bytes([bytes[o], bytes[o + 1]]);
+    let le32 =
+        |o: usize| u32::from_le_bytes([bytes[o], bytes[o + 1], bytes[o + 2], bytes[o + 3]]);
+
+    let mut pos = 12;
+    let (mut tag, mut channels, mut rate, mut bits) = (0u16, 0u16, 0u32, 0u16);
+    let mut data_bytes: Option<u64> = None;
+    let mut have_fmt = false;
+
+    while pos + 8 <= bytes.len() {
+        let id = &bytes[pos..pos + 4];
+        let size = le32(pos + 4) as usize;
+        let body = pos + 8;
+        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);
+                }
+                have_fmt = true;
+            }
+            b"data" => data_bytes = Some(size as u64),
+            _ => {}
+        }
+        // Chunks are word-aligned (pad byte when size is odd).
+        pos = body + size + (size & 1);
+    }
+    if !have_fmt {
+        return None;
+    }
+
+    let codec = match tag {
+        WAVE_FORMAT_PCM => AudioCodec::Pcm,
+        WAVE_FORMAT_IEEE_FLOAT => AudioCodec::PcmFloat,
+        WAVE_FORMAT_XMA => AudioCodec::Xma,
+        WAVE_FORMAT_XMA2 => AudioCodec::Xma2,
+        _ => AudioCodec::Unknown,
+    };
+    let mut info = AudioInfo::empty(codec, bytes.len());
+    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);
+
+    match codec {
+        AudioCodec::Pcm | AudioCodec::PcmFloat => {
+            if let (Some(d), true) = (data_bytes, channels > 0 && bits > 0) {
+                let frame = channels as u64 * (bits as u64 / 8);
+                if frame > 0 {
+                    let spc = d / frame;
+                    info.samples_per_channel = Some(spc);
+                    if rate > 0 {
+                        info.duration_secs = Some(spc as f32 / rate as f32);
+                    }
+                }
+            }
+        }
+        AudioCodec::Xma | AudioCodec::Xma2 => {
+            if let Some(d) = data_bytes {
+                info.xma_packets = Some((d / XMA_BYTES_PER_PACKET as u64) as u32);
+            }
+        }
+        _ => {}
+    }
+    Some(info)
+}
+
+// ── PCM decode → GameAudio ─────────────────────────────────────────────────────
+
+/// An audio clip decoded to raw interleaved `f32` PCM (`L R L R …`).
 #[derive(Debug, Clone)]
 pub struct GameAudio {
-    /// Raw PCM samples (interleaved for stereo: L R L R ...)
     pub samples: Vec<f32>,
     pub channels: u16,
     pub sample_rate: u32,
 }
 
 impl GameAudio {
-    /// Parse audio from raw bytes.
-    ///
-    /// Currently only WAV/PCM is supported. For XMA files, pre-convert using:
-    /// `ffmpeg -i file.xma file.wav`
-    pub fn from_bytes(bytes: &[u8]) -> Result<Self, AudioError> {
-        // Check for WAV magic
-        if bytes.len() >= 4 && &bytes[..4] == b"RIFF" {
-            return Self::from_wav(bytes);
+    /// Decode a RIFF/WAVE **PCM** file (int 8/16/24-bit or 32-bit float) to
+    /// interleaved `f32`. XMA/XMA2 return [`AudioError::NeedsDecoder`].
+    pub fn from_wav(bytes: &[u8]) -> Result<Self, AudioError> {
+        let info = parse_riff_wave(bytes).ok_or(AudioError::Unrecognized)?;
+        if info.codec.needs_decoder() {
+            return Err(AudioError::NeedsDecoder(info.codec));
         }
+        let channels = info.channels.ok_or(AudioError::Malformed("no channels"))?;
+        let rate = info.sample_rate.ok_or(AudioError::Malformed("no sample rate"))?;
+        let bits = info.bits_per_sample.ok_or(AudioError::Malformed("no bit depth"))?;
 
-        // XMA magic bytes
-        if bytes.len() >= 4 && (
-            &bytes[..4] == b"XWB\0" || // Wave bank
-            &bytes[..4] == b"XMA2"     // Raw XMA2
-        ) {
-            return Err(AudioError::XmaNotSupported);
-        }
+        // Locate the `data` chunk body.
+        let (off, len) = riff_data_span(bytes).ok_or(AudioError::Malformed("no data chunk"))?;
+        let data = &bytes[off..off + len];
 
-        Err(AudioError::UnknownMagic(
-            bytes[..4.min(bytes.len())].try_into().unwrap_or([0u8; 4])
-        ))
-    }
-
-    fn from_wav(bytes: &[u8]) -> Result<Self, AudioError> {
-        // Minimal WAV parser for PCM files
-        // A proper implementation should use the `hound` crate:
-        // https://crates.io/crates/hound
-        //
-        // TODO: Add `hound = "3"` to Cargo.toml and implement properly
-        Err(AudioError::Parse(
-            "WAV parsing TODO: add `hound` crate and implement".to_string()
-        ))
+        let samples: Vec<f32> = match (info.codec, bits) {
+            (AudioCodec::Pcm, 8) => data.iter().map(|&b| (b as f32 - 128.0) / 128.0).collect(),
+            (AudioCodec::Pcm, 16) => data
+                .chunks_exact(2)
+                .map(|c| i16::from_le_bytes([c[0], c[1]]) as f32 / 32768.0)
+                .collect(),
+            (AudioCodec::Pcm, 24) => data
+                .chunks_exact(3)
+                .map(|c| {
+                    let v = ((c[2] as i32) << 16) | ((c[1] as i32) << 8) | c[0] as i32;
+                    let v = (v << 8) >> 8; // sign-extend 24→32
+                    v as f32 / 8_388_608.0
+                })
+                .collect(),
+            (AudioCodec::PcmFloat, 32) => data
+                .chunks_exact(4)
+                .map(|c| f32::from_le_bytes([c[0], c[1], c[2], c[3]]))
+                .collect(),
+            _ => return Err(AudioError::UnsupportedPcm { tag: 0, bits }),
+        };
+        Ok(Self { samples, channels, sample_rate: rate })
+    }
+}
+
+/// Byte span (offset, length) of the WAVE `data` chunk body, if present.
+fn riff_data_span(bytes: &[u8]) -> Option<(usize, usize)> {
+    if bytes.len() < 12 || &bytes[..4] != b"RIFF" || &bytes[8..12] != b"WAVE" {
+        return None;
+    }
+    let le32 =
+        |o: usize| u32::from_le_bytes([bytes[o], bytes[o + 1], bytes[o + 2], bytes[o + 3]]) as usize;
+    let mut pos = 12;
+    while pos + 8 <= bytes.len() {
+        let size = le32(pos + 4);
+        let body = pos + 8;
+        if &bytes[pos..pos + 4] == b"data" {
+            let len = size.min(bytes.len().saturating_sub(body));
+            return Some((body, len));
+        }
+        pos = body + size + (size & 1);
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Build a minimal 16-bit PCM WAV in memory (stereo, 2 frames).
+    fn tiny_wav() -> Vec<u8> {
+        let mut v = Vec::new();
+        let data: [i16; 4] = [1000, -1000, 32767, -32768]; // L R L R
+        let data_bytes: Vec<u8> = data.iter().flat_map(|s| s.to_le_bytes()).collect();
+        v.extend_from_slice(b"RIFF");
+        v.extend_from_slice(&(36 + data_bytes.len() as u32).to_le_bytes());
+        v.extend_from_slice(b"WAVE");
+        v.extend_from_slice(b"fmt ");
+        v.extend_from_slice(&16u32.to_le_bytes());
+        v.extend_from_slice(&WAVE_FORMAT_PCM.to_le_bytes());
+        v.extend_from_slice(&2u16.to_le_bytes()); // channels
+        v.extend_from_slice(&48000u32.to_le_bytes());
+        v.extend_from_slice(&(48000u32 * 2 * 2).to_le_bytes());
+        v.extend_from_slice(&4u16.to_le_bytes()); // block align
+        v.extend_from_slice(&16u16.to_le_bytes()); // bits
+        v.extend_from_slice(b"data");
+        v.extend_from_slice(&(data_bytes.len() as u32).to_le_bytes());
+        v.extend_from_slice(&data_bytes);
+        v
+    }
+
+    #[test]
+    fn probe_and_decode_pcm_wav() {
+        let wav = tiny_wav();
+        let info = AudioInfo::probe(&wav);
+        assert_eq!(info.codec, AudioCodec::Pcm);
+        assert_eq!(info.channels, Some(2));
+        assert_eq!(info.sample_rate, Some(48000));
+        assert_eq!(info.samples_per_channel, Some(2));
+        let audio = GameAudio::from_wav(&wav).unwrap();
+        assert_eq!(audio.channels, 2);
+        assert_eq!(audio.samples.len(), 4);
+        assert!((audio.samples[2] - 0.99997).abs() < 1e-3); // 32767/32768
+    }
+
+    #[test]
+    fn probe_xma2_riff_reports_metadata_not_decode() {
+        // Minimal RIFF/WAVE with an XMA2 fmt tag.
+        let mut v = Vec::new();
+        v.extend_from_slice(b"RIFF");
+        v.extend_from_slice(&200u32.to_le_bytes());
+        v.extend_from_slice(b"WAVE");
+        v.extend_from_slice(b"fmt ");
+        v.extend_from_slice(&16u32.to_le_bytes());
+        v.extend_from_slice(&WAVE_FORMAT_XMA2.to_le_bytes());
+        v.extend_from_slice(&2u16.to_le_bytes());
+        v.extend_from_slice(&44100u32.to_le_bytes());
+        v.extend_from_slice(&0u32.to_le_bytes());
+        v.extend_from_slice(&0u16.to_le_bytes());
+        v.extend_from_slice(&0u16.to_le_bytes());
+        let info = AudioInfo::probe(&v);
+        assert_eq!(info.codec, AudioCodec::Xma2);
+        assert_eq!(info.channels, Some(2));
+        assert!(info.codec.needs_decoder());
+        assert!(matches!(
+            GameAudio::from_wav(&v),
+            Err(AudioError::NeedsDecoder(AudioCodec::Xma2))
+        ));
+    }
+
+    #[test]
+    fn raw_high_entropy_blob_reads_as_raw_xma2() {
+        // A pseudo-random 8 KB blob (no magic) → RawXma2 with a packet count.
+        let mut b = vec![0u8; 8192];
+        let mut x = 0x2545_F491u32;
+        for v in b.iter_mut() {
+            x ^= x << 13;
+            x ^= x >> 17;
+            x ^= x << 5;
+            *v = (x & 0xFF) as u8;
+        }
+        let info = AudioInfo::probe(&b);
+        assert_eq!(info.codec, AudioCodec::RawXma2);
+        assert_eq!(info.xma_packets, Some(4)); // 8192 / 2048
+    }
+
+    #[test]
+    fn structured_low_entropy_blob_is_unknown_not_audio() {
+        let b = b"IDXD............a bunch of readable ASCII text fields....".repeat(40);
+        assert_eq!(AudioInfo::probe(&b).codec, AudioCodec::Unknown);
     }
 }

crates/sylpheed-formats/src/hash.rs

@@ -20,9 +20,14 @@
 //! i.e. the low 24 bits are a modular polynomial hash and the top byte is an
 //! 8-bit additive checksum of the bytes. The reduction constant `0x8003_1493`
 //! is the reciprocal of the modulus `0x00FF_F9D7` used by the `mulhwu`/`mullw`
-//! Barrett step; there is **no** trailing conditional subtract, so the value is
-//! defined by the exact op sequence (faithfully reproduced below), not by a
-//! textbook `%`.
+//! Barrett step.
+//!
+//! **The reduction is EXACT, not lossy.** An earlier version of this note said
+//! the missing trailing conditional subtract made it something other than `%`.
+//! It does not: `rlwinm r6,r6,9,23,31` is exactly `hi >> 23`, and with
+//! `RECIP == floor(2^55/M) + 1` that is standard Granlund–Montgomery magic
+//! division. Checked at every quotient boundary (`k·M−1, k·M, k·M+1`) across the
+//! whole 32-bit domain: 0 wrong of 770. So the low 24 bits really are `A % M`.
 //!
 //! Verified against the real disc: `name_hash("files.tbl") == 0x8342_1153`
 //! and `name_hash("eng\\weapon.tbl") == 0x900C_8DCD`, both of which are present
@@ -150,3 +155,129 @@ mod tests {
         assert_eq!(name_hash(""), 0);
     }
 }
+
+/// Barrett modulus of the **record/field tag** hash — a different constant from
+/// [`MODULUS`], and the same one the IXUD hash folds down to.
+const TAG_MODULUS: u32 = 0x00FF_FFDF; // 2^24 - 33, prime
+/// The guest's divide magic for [`TAG_MODULUS`] (`floor(2^56/M) + 1`).
+const TAG_MAGIC: u32 = 0x2101;
+/// The IXUD loop modulus, applied in 64-bit arithmetic before [`TAG_MODULUS`].
+const IXUD_M1: u64 = 0xFFFF_FF67; // 2^32 - 153
+
+/// Hash an IDXD **record key / field tag** — `sub_82447DF0`.
+///
+/// This is *not* [`name_hash`]. Same shape — an 8-bit additive checksum over a
+/// 24-bit modular polynomial — but two constants differ:
+///
+/// * modulus `0x00FF_FFDF` (2^24 − 33, prime), not `0x00FF_F9D7`;
+/// * **no lowercasing**, so tags are case-sensitive. The disc relies on this:
+///   17 name pairs differ only in case (`UNIT`/`Unit`, `TYPE`/`Type`, …) and
+///   `name_hash` collides on every one of them.
+///
+/// A record's key is the tag of its **own** name — 190,782/190,782 records
+/// disc-wide — so records are addressable by name without reading a roster.
+///
+/// The guest **sign-extends** each byte (`extsb`), and that is load-bearing:
+/// a version of this using unsigned bytes matched all 1.27M disc names, because
+/// every one is ASCII, while disagreeing on ~90% of random inputs containing a
+/// byte ≥ 0x80. Only the disassembly could catch that.
+pub fn tag_hash(name: &str) -> u32 {
+    tag_hash_bytes(name.as_bytes())
+}
+
+/// [`tag_hash`] over raw bytes — the form that can express a non-UTF-8 name, and
+/// the only way to exercise the `extsb` path.
+pub fn tag_hash_bytes(bytes: &[u8]) -> u32 {
+    let mut a: u32 = 0;
+    let mut b: u32 = 0;
+    for &byte in bytes {
+        let c = byte as i8 as i32 as u32; // extsb
+        a = (a << 8).wrapping_add(c);
+        b = b.wrapping_add(c);
+        // Exact magic division by TAG_MODULUS, in the guest's add-correction form.
+        let hi = ((a as u64 * TAG_MAGIC as u64) >> 32) as u32;
+        let q = hi.wrapping_add(a.wrapping_sub(hi) >> 1) >> 23;
+        a = a.wrapping_sub(q.wrapping_mul(TAG_MODULUS));
+    }
+    ((b << 24) & 0xFF00_0000) | (a & 0x00FF_FFFF)
+}
+
+/// Hash an **IXUD** record key / field tag — `sub_82447E70`.
+///
+/// IXUD is IDXD's wide-string sibling: identical container layout, but strings
+/// are UTF-16BE and `strsize` and every string offset are counted in **16-bit
+/// characters, not bytes** (`STR + 2·strsize == filesize`).
+///
+/// `units` is the name as big-endian UTF-16 code units.
+///
+/// It resisted every single-modulus search because it chains **two** exact
+/// moduli: the loop reduces mod `2^32 − 153` in 64-bit arithmetic, and only the
+/// final value is folded into 24 bits mod `2^24 − 33`. A polynomial mod `M1`
+/// folded through `M2` is not a polynomial mod anything, which is why a gcd over
+/// the observed pairs returns 1 and a Barrett sweep finds nothing.
+///
+/// The checksum byte sums the **full 16-bit code units**, not their low bytes —
+/// indistinguishable on this disc, where every IXUD name is ASCII, but not in
+/// general.
+pub fn ixud_hash(units: &[u16]) -> u32 {
+    let mut a: u64 = 0;
+    let mut b: u32 = 0;
+    for &ch in units {
+        a = ((a << 16) + ch as u64) % IXUD_M1;
+        b = b.wrapping_add(ch as u32);
+    }
+    ((b & 0xFF) << 24) | (a % TAG_MODULUS as u64) as u32
+}
+
+/// Convenience: [`ixud_hash`] for an ASCII/UTF-8 name.
+pub fn ixud_hash_str(name: &str) -> u32 {
+    let units: Vec<u16> = name.encode_utf16().collect();
+    ixud_hash(&units)
+}
+
+#[cfg(test)]
+mod tag_tests {
+    use super::tag_hash;
+
+    #[test]
+    fn known_tags_from_the_disc_tables() {
+        // Field names, from IDXD records in GP_MAIN_GAME_E.pak.
+        assert_eq!(tag_hash("SideID"), 0x1225_E093);
+        assert_eq!(tag_hash("ID"), 0x8D00_4944);
+        assert_eq!(tag_hash("Name"), 0x8161_7773);
+        // Formation record keys, from FormationSet_S02.tbl.
+        assert_eq!(tag_hash("Formation_4_Bird"), 0x22A5_EEED);
+        assert_eq!(tag_hash("Formation_1_only"), 0x6047_EECF);
+        assert_eq!(tag_hash("Formation_ADAN_Turret07_30"), 0x30CE_86BE);
+    }
+
+    #[test]
+    fn ixud_uses_a_different_hash_entirely() {
+        // Verified against real IXUD data: 86/86 record keys and 108,261/108,261
+        // field tags in GP_MAIN_GAME_E.pak.
+        assert_eq!(super::ixud_hash_str("NoRecord"), 0x1C6D_9C96);
+        assert_ne!(super::ixud_hash_str("NoRecord"), tag_hash("NoRecord"));
+    }
+
+    #[test]
+    fn tag_hash_sign_extends_high_bytes() {
+        // The guest uses extsb. Unsigned bytes agree on all-ASCII names but not
+        // here -- this input is the concrete counterexample.
+        let bytes = [0x4eu8, 0x3f, 0xcf, 0xa5, 0x0c, 0x86, 0x4c, 0x2b, 0x41, 0xcf];
+        assert_eq!(super::tag_hash_bytes(&bytes), 0x1AFF_849A);
+    }
+
+    #[test]
+    fn tags_are_case_sensitive_unlike_name_hash() {
+        // name_hash lowercases first; tag_hash must not.
+        assert_ne!(tag_hash("SideID"), tag_hash("sideid"));
+    }
+
+    #[test]
+    fn the_top_byte_is_the_byte_sum() {
+        for s in ["ID", "Formation_4_Bird", "SideID"] {
+            let sum = s.as_bytes().iter().map(|&b| b as u32).sum::<u32>() & 0xFF;
+            assert_eq!(tag_hash(s) >> 24, sum, "{s}");
+        }
+    }
+}

crates/sylpheed-formats/src/idxd.rs

@@ -8,15 +8,44 @@
 //! ## Layout (all fields big-endian)
 //!
 //! ```text
-//! Offset  Size  Field
-//! 0x00    4     Magic: "IDXD"
-//! 0x04    4     count        (number of top-level records; small)
-//! 0x08    4     schema_hash  (identifies the object type; custom hash family, preimage unknown)
-//! 0x0C    ..    NODE / INDEX region — hash-keyed records + (for some schemas) auxiliary
-//!                                     binary tables. Not required for the string values below.
-//! ..      ..    STRING POOL  — the trailing, (almost) all-ASCII region.
+//! Offset  Size    Field
+//! 0x00    4       Magic: "IDXD"
+//! 0x04    4       record_count  n
+//! 0x08    16*n    records     { u32 name_hash, u32 name_off, u32 field_begin, u32 field_end }
+//! ..      4       field_count m  (equals max(field_end))
+//! ..      12*m    fields      { u32 key, u32 name_off, u32 value_off }
+//! ..      4       pool_size   (equals file_len − pool_base)
+//! ..      ..      STRING POOL — every `*_off` above is a byte offset from here.
 //! ```
 //!
+//! Records are sorted ascending by `name_hash` and the guest binary-searches them
+//! (`sub_82448AA0`); fields are sorted ascending by `key` and lower-bounded
+//! (`sub_8244E338`). `name_hash` is [`crate::hash::tag_hash`] of the record's own
+//! name — **not** the pak TOC hash: different modulus, and not lowercased.
+//!
+//! A field's `name_off` points at its own name, so **field names are on the disc**
+//! and never have to be recovered from their hash; `key` is then `tag_hash(name)`.
+//! A `name_off` of `0xFFFF_FFFF` means the field has no name, and its `key` is a
+//! literal positional integer instead — a line-slot index, a movie id
+//! ([`IdxdField::index`]).
+//!
+//! ## There is no schema field
+//!
+//! The word at `0x08` was long read as a `schema_hash` identifying the object
+//! type. It is not: it is simply **record 0's `name_hash`**, the first cell of a
+//! uniform 16-byte record array. `tag_hash(records[0].name)` reproduces it for
+//! **all 7750** IDXD objects on the retail disc. It still works as a type
+//! discriminator — tables of one kind share their lowest-hashed record name — so
+//! [`IdxdObject::schema_hash`] is kept under its established name, but it
+//! identifies a *record name*, not a schema. Nothing on disc names the type.
+//!
+//! Verified across the whole retail disc (`records_roundtrip_disc`,
+//! `field_names_are_stored_disc`): all **7750** objects parse under this layout;
+//! all **190782** records reproduce their stored `name_hash`; all **1271462**
+//! named fields reproduce their `key` from their stored name; the remaining
+//! **1485073** fields are unnamed with literal keys, and just **504** are
+//! hash-keyed with no name stored.
+//!
 //! ## The string pool: **value-before-key, defaults omitted**
 //!
 //! Each property that has an explicit value is serialized as `<value>\0<key>\0` —
@@ -44,14 +73,34 @@
 //! - [`IdxdObject::get_raw`] — the raw preceding token, no validation. Use for fields
 //!   you *know* are identifier-valued (`ID`, `Name`, `Type`, `Model`).
 //!
-//! ## Not yet decoded
+//! ## Two readers, one object
 //!
-//! Default/omitted fields (many ratios, the `…Count` family) carry no value in the
-//! pool — their values live in the binary node/index region (hash-keyed by the same
-//! unrecovered custom hash) or come from schema defaults. Binding those requires
-//! decoding that region per schema; until then the typed getters return `None` for
-//! them (honest "unknown") rather than guessing. See `reference_ipfb_archive_format`
-//! in the project notes.
+//! The record/field table above is exact, so prefer it: [`IdxdObject::records`],
+//! [`record`](IdxdObject::record), [`IdxdRecord::field`]. The older
+//! *value-before-key string-pool* reader ([`get_f32`](IdxdObject::get_f32) and
+//! friends, documented below) predates the decode and is kept because a large
+//! part of the corpus is written in terms of it.
+//!
+//! ## The legacy string-pool reader: **value-before-key, defaults omitted**
+//!
+//! In the pool each property that has an explicit value is laid out as
+//! `<value>\0<key>\0` — the value string comes *immediately before* its field
+//! name. Numbers are stored as ASCII text (`"600.0"`, `"144"`), so they read out
+//! directly:
+//!
+//! ```text
+//! … "1000.0" "HP" "500000.0" "RadarRange" "10.0" "Size_X" …
+//!     value   key    value      key        value   key
+//! ```
+//!
+//! Fields left at their default omit the value string, appearing as a bare key.
+//! So "the token before a key" is a real value *only when that token is itself
+//! value-shaped*, which the typed getters enforce ([`get_f32`](IdxdObject::get_f32),
+//! [`get_i64`](IdxdObject::get_i64), [`get_str`](IdxdObject::get_str) validate;
+//! [`get_raw`](IdxdObject::get_raw) does not). The adjacency is a *consequence* of
+//! the field table — each record's values are emitted next to their keys — not a
+//! rule of the format, and it cannot see a field whose value string is shared or
+//! reordered. Use the record API when correctness matters.
 
 use thiserror::Error;
 
@@ -70,13 +119,75 @@ pub enum IdxdError {
 /// A parsed IDXD object: its schema id plus the decoded string pool.
 #[derive(Debug, Clone)]
 pub struct IdxdObject {
-    /// Object-type id (which kind of definition this is). Custom hash; groups
-    /// entries by schema even though the preimage is unknown.
+    /// The word at `0x08`. Despite the name it is **record 0's `name_hash`**, not
+    /// a schema id — see the module docs. Retained because it does discriminate
+    /// object kinds in practice and the corpus is written in terms of it; prefer
+    /// [`records`](Self::records) when you want meaning rather than a bucket key.
     pub schema_hash: u32,
-    /// The `count` header field (number of top-level records).
+    /// The `record_count` header field.
     pub count: u32,
     /// Ordered string-pool tokens (see module docs; value-before-key).
     tokens: Vec<String>,
+    /// The decoded record/field table. `None` only when the binary region does
+    /// not parse — which no retail object does; see `records_roundtrip_disc`.
+    records: Option<Vec<IdxdRecord>>,
+}
+
+/// One named record of an [`IdxdObject`] — a row of the table.
+#[derive(Debug, Clone)]
+pub struct IdxdRecord {
+    /// The record's name, from the string pool.
+    pub name: String,
+    /// `tag_hash(name)`, as stored.
+    pub name_hash: u32,
+    /// This record's fields, in on-disc order (ascending `key`).
+    pub fields: Vec<IdxdField>,
+}
+
+/// One field of an [`IdxdRecord`] — a key/value cell.
+#[derive(Debug, Clone)]
+pub struct IdxdField {
+    /// `tag_hash(name)` when the field is named, else a literal positional
+    /// integer. See [`IdxdField::index`].
+    pub key: u32,
+    /// The field's own name, when it has one. `None` for positional fields.
+    pub name: Option<String>,
+    /// The field's value, from the string pool. Values are ASCII text, including
+    /// numbers (`"600.0"`).
+    pub value: String,
+}
+
+impl IdxdField {
+    /// The key read as a literal positional index. `None` for a named field.
+    ///
+    /// Keyed off the stored name rather than off the key's magnitude, so it is
+    /// exact: a field is positional precisely when it has no name.
+    pub fn index(&self) -> Option<u32> {
+        self.name.is_none().then_some(self.key)
+    }
+
+    /// Whether this field is named `name`.
+    pub fn is_named(&self, name: &str) -> bool {
+        self.name.as_deref() == Some(name)
+    }
+}
+
+impl IdxdRecord {
+    /// The field named `name` (matched by `tag_hash`), if present.
+    pub fn field(&self, name: &str) -> Option<&IdxdField> {
+        let key = crate::hash::tag_hash(name);
+        self.fields.iter().find(|f| f.key == key)
+    }
+
+    /// The field stored under the literal integer key `index`, if present.
+    pub fn field_at(&self, index: u32) -> Option<&IdxdField> {
+        self.fields.iter().find(|f| f.key == index)
+    }
+
+    /// The value of the field named `name`.
+    pub fn get(&self, name: &str) -> Option<&str> {
+        self.field(name).map(|f| f.value.as_str())
+    }
 }
 
 impl IdxdObject {
@@ -92,10 +203,12 @@ impl IdxdObject {
         let count = be32(bytes, 4);
         let schema_hash = be32(bytes, 8);
         let tokens = extract_string_pool(bytes);
+        let records = parse_records(bytes, count);
         Ok(Self {
             schema_hash,
             count,
             tokens,
+            records,
         })
     }
 
@@ -109,6 +222,25 @@ impl IdxdObject {
         &self.tokens
     }
 
+    /// The decoded record/field table, or `None` if the binary region did not
+    /// parse. Every retail object parses; a `None` here means a malformed or
+    /// synthetic buffer.
+    pub fn records(&self) -> Option<&[IdxdRecord]> {
+        self.records.as_deref()
+    }
+
+    /// The record named `name` (matched by `tag_hash`), if the table parsed.
+    pub fn record(&self, name: &str) -> Option<&IdxdRecord> {
+        let key = crate::hash::tag_hash(name);
+        self.records.as_ref()?.iter().find(|r| r.name_hash == key)
+    }
+
+    /// Record 0 — the one whose hash sits in the header word this crate calls
+    /// [`schema_hash`](Self::schema_hash).
+    pub fn first_record(&self) -> Option<&IdxdRecord> {
+        self.records.as_ref()?.first()
+    }
+
     /// The raw token immediately preceding the first occurrence of `key`.
     ///
     /// No validation: for a defaulted/omitted field this is the *neighbouring key*,
@@ -183,8 +315,91 @@ impl IdxdObject {
         }
         format!("schema {:08x}", self.schema_hash)
     }
+
+    /// Recover this entry's original TOC path (e.g. `unit\rou_f001.tbl`) from its
+    /// identity/pool tokens by re-hashing candidates against `name_hash` with the
+    /// known path schemes. Returns `None` when no scheme reproduces the hash.
+    ///
+    /// Shared by the CLI `pak list` and the GUI pack browser so both surface the
+    /// same recovered names. See [`crate::hash::recover_toc_name`].
+    pub fn recover_toc_path(&self, name_hash: u32) -> Option<String> {
+        let mut cands: Vec<&str> = Vec::new();
+        for key in ["ID", "Name", "Model"] {
+            if let Some(v) = self.get_raw(key) {
+                cands.push(v);
+            }
+        }
+        for t in self.tokens() {
+            if t.contains('_') || t.len() >= 5 {
+                cands.push(t.as_str());
+            }
+        }
+        crate::hash::recover_toc_name(name_hash, &cands)
+    }
 }
 
+/// Decode the record/field table (see module docs). Returns `None` — rather than
+/// erroring — when any bound is inconsistent, so a malformed or synthetic buffer
+/// still yields a usable string-pool reader.
+fn parse_records(b: &[u8], count: u32) -> Option<Vec<IdxdRecord>> {
+    let n = count as usize;
+    if n == 0 || n > b.len() / 16 {
+        return None;
+    }
+    let recs_at = 0x08_usize;
+    let field_count_at = recs_at.checked_add(n.checked_mul(16)?)?;
+    if field_count_at + 4 > b.len() {
+        return None;
+    }
+    let m = be32(b, field_count_at) as usize;
+    let fields_at = field_count_at + 4;
+    let pool_size_at = fields_at.checked_add(m.checked_mul(12)?)?;
+    let pool = pool_size_at.checked_add(4)?;
+    if pool > b.len() {
+        return None;
+    }
+    // The trailing identity: the stored pool size is exactly what is left. This is
+    // what makes the layout self-checking — a wrong record stride lands here.
+    if be32(b, pool_size_at) as usize != b.len() - pool {
+        return None;
+    }
+    let string_at = |off: u32| -> Option<String> {
+        let start = pool.checked_add(off as usize)?;
+        if start >= b.len() {
+            return None;
+        }
+        let end = start + b[start..].iter().position(|&c| c == 0)?;
+        Some(String::from_utf8_lossy(&b[start..end]).into_owned())
+    };
+    let mut out = Vec::with_capacity(n);
+    for i in 0..n {
+        let r = recs_at + 16 * i;
+        let (begin, end) = (be32(b, r + 8) as usize, be32(b, r + 12) as usize);
+        if begin > end || end > m {
+            return None;
+        }
+        let mut fields = Vec::with_capacity(end - begin);
+        for j in begin..end {
+            let f = fields_at + 12 * j;
+            let name_off = be32(b, f + 4);
+            fields.push(IdxdField {
+                key: be32(b, f),
+                name: (name_off != NO_NAME).then(|| string_at(name_off)).flatten(),
+                value: string_at(be32(b, f + 8))?,
+            });
+        }
+        out.push(IdxdRecord {
+            name: string_at(be32(b, r + 4))?,
+            name_hash: be32(b, r),
+            fields,
+        });
+    }
+    Some(out)
+}
+
+/// A field `name_off` of `0xFFFF_FFFF` means the field is positional, not named.
+const NO_NAME: u32 = 0xFFFF_FFFF;
+
 /// Extract the trailing string pool. Finds the smallest offset whose suffix is
 /// ≥98% printable-ASCII-or-NUL (the pool runs to end-of-buffer), then tokenises
 /// into maximal printable runs (NUL *or* any non-printable byte separates tokens,
@@ -261,9 +476,9 @@ fn is_key_like(s: &str) -> bool {
 fn parse_number(s: &str) -> bool {
     !s.is_empty()
         && s.bytes().any(|b| b.is_ascii_digit())
-        && s.bytes().enumerate().all(|(i, b)| {
-            b.is_ascii_digit() || b == b'.' || (i == 0 && (b == b'-' || b == b'+'))
-        })
+        && s.bytes()
+            .enumerate()
+            .all(|(i, b)| b.is_ascii_digit() || b == b'.' || (i == 0 && (b == b'-' || b == b'+')))
 }
 
 #[inline]
@@ -337,7 +552,7 @@ mod tests {
     fn resolved_fields_lists_explicit_values_only() {
         let bytes = synth(&[
             "rou_f001", "Model", // identifier value → excluded
-            "10.0", "Size_X", // explicit → included
+            "10.0", "Size_X",   // explicit → included
             "FCSRange", // defaulted (no value) → excluded
             "Yes", "Mounted", // enum → included
         ]);

crates/sylpheed-formats/src/ixud.rs

@@ -15,16 +15,35 @@
 //! start timecode instead of inline text; the actual string then lives in a
 //! separate global table (not resolved here).
 //!
-//! ## Binary layout (as far as needed)
+//! ## Binary layout — ✅ decoded and verified disc-wide
+//!
 //! ```text
-//! 0x00  4   Magic "IXUD"
-//! 0x04  4   version (1)
-//! 0x08  4   schema/type hash (constant 0x6CC83E70)
-//! ..    ..  record directory { key_hash u32, offset u32, len u32 } × n
-//! ..    ..  UTF-16BE string pool, NUL-terminated entries
+//! 0x00  4       Magic "IXUD"
+//! 0x04  4       record_count n
+//! 0x08  16*n    records  { u32 name_hash, u32 name_off, u32 field_begin, u32 field_end }
+//! ..    4       field_count m
+//! ..    12*m    fields   { u32 key, u32 name_off, u32 value_off }
+//! ..    4       pool_size   (in CHARS)
+//! ..    ..      UTF-16BE string pool
 //! ```
-//! We don't need the directory to *present* the track — decoding the pool and
-//! pairing tokens after the `SUBTITLE` header is enough and robust.
+//!
+//! **Every offset is in 16-bit chars, not bytes** — `pool_base + 2*off`. That
+//! includes record and field *names*, not only values, and it is what makes the
+//! `STR + 2*strsize == filesize` identity hold.
+//!
+//! `name_hash` is [`crate::hash::ixud_hash`] of the record's own name, and a
+//! field's `key` is the same hash of its name; `name_off == 0xFFFF_FFFF` marks a
+//! positional field whose key is a literal index. Verified over every IXUD object
+//! on the disc: **1104/1104** objects parse, **1476/1476** records and
+//! **628 165/628 165** named fields reproduce their stored hash.
+//!
+//! ❌ The layout this comment used to describe — a 12-byte record directory and a
+//! "schema/type hash" at `0x08` — was wrong in the same way IDXD's was. There is
+//! no schema field: the word at `0x08` is record 0's `name_hash`. See
+//! `docs/re/structures/idxd-container.md`.
+//!
+//! The cue reader below still works on the string pool directly, which is fine
+//! for presenting a track; [`IxudObject`] is the addressable route.
 
 /// Magic at the start of every IXUD entry.
 pub const IXUD_MAGIC: [u8; 4] = *b"IXUD";
@@ -185,3 +204,138 @@ mod tests {
         assert!(parse(b"IDXD\0\0\0\0").is_none());
     }
 }
+
+
+/// A parsed IXUD object: its records and their fields, addressable by name.
+///
+/// The counterpart of [`crate::IdxdObject`] for wide strings. Prefer this to the
+/// token-pairing readers when you need a *specific* field: pool adjacency is a
+/// consequence of how records are written, not a rule of the format.
+#[derive(Debug, Clone)]
+pub struct IxudObject {
+    /// The word at `0x08` — record 0's `name_hash`, not a schema id.
+    pub first_record_hash: u32,
+    records: Vec<IxudRecord>,
+}
+
+/// One named record of an [`IxudObject`].
+#[derive(Debug, Clone)]
+pub struct IxudRecord {
+    /// The record's name, decoded from UTF-16BE.
+    pub name: String,
+    /// `ixud_hash(name)`, as stored.
+    pub name_hash: u32,
+    /// This record's fields, in on-disc order.
+    pub fields: Vec<IxudField>,
+}
+
+/// One field of an [`IxudRecord`].
+#[derive(Debug, Clone)]
+pub struct IxudField {
+    /// `ixud_hash(name)` when named, else a literal positional index.
+    pub key: u32,
+    /// The field's own name, when it has one.
+    pub name: Option<String>,
+    /// The field's value.
+    pub value: String,
+}
+
+impl IxudRecord {
+    /// The field named `name` (matched by `ixud_hash`), if present.
+    pub fn field(&self, name: &str) -> Option<&IxudField> {
+        let key = crate::hash::ixud_hash_str(name);
+        self.fields.iter().find(|f| f.key == key)
+    }
+
+    /// The value of the field named `name`.
+    pub fn get(&self, name: &str) -> Option<&str> {
+        self.field(name).map(|f| f.value.as_str())
+    }
+}
+
+impl IxudObject {
+    /// Parse an IXUD object. `None` when the layout does not check out — the
+    /// trailing `pool_size` identity makes that self-verifying.
+    pub fn parse(b: &[u8]) -> Option<Self> {
+        if b.len() < 12 || b[0..4] != IXUD_MAGIC {
+            return None;
+        }
+        let be32 = |o: usize| u32::from_be_bytes([b[o], b[o + 1], b[o + 2], b[o + 3]]);
+        let n = be32(4) as usize;
+        if n == 0 || n > b.len() / 16 {
+            return None;
+        }
+        let field_count_at = 8usize.checked_add(n.checked_mul(16)?)?;
+        if field_count_at + 4 > b.len() {
+            return None;
+        }
+        let m = be32(field_count_at) as usize;
+        let fields_at = field_count_at + 4;
+        let pool_size_at = fields_at.checked_add(m.checked_mul(12)?)?;
+        let pool = pool_size_at.checked_add(4)?;
+        if pool > b.len() {
+            return None;
+        }
+        // pool_size counts CHARS, so this identity also proves the char scaling.
+        if (be32(pool_size_at) as usize).checked_mul(2)? != b.len() - pool {
+            return None;
+        }
+        let wstr = |off: u32| -> Option<String> {
+            if off == NO_NAME {
+                return None;
+            }
+            let start = pool.checked_add((off as usize).checked_mul(2)?)?;
+            let mut units = Vec::new();
+            let mut i = start;
+            while i + 1 < b.len() {
+                let u = u16::from_be_bytes([b[i], b[i + 1]]);
+                if u == 0 {
+                    return Some(String::from_utf16_lossy(&units));
+                }
+                units.push(u);
+                i += 2;
+            }
+            None
+        };
+        let mut records = Vec::with_capacity(n);
+        for i in 0..n {
+            let r = 8 + 16 * i;
+            let (begin, end) = (be32(r + 8) as usize, be32(r + 12) as usize);
+            if begin > end || end > m {
+                return None;
+            }
+            let mut fields = Vec::with_capacity(end - begin);
+            for j in begin..end {
+                let f = fields_at + 12 * j;
+                fields.push(IxudField {
+                    key: be32(f),
+                    name: wstr(be32(f + 4)),
+                    value: wstr(be32(f + 8))?,
+                });
+            }
+            records.push(IxudRecord {
+                name: wstr(be32(r + 4))?,
+                name_hash: be32(r),
+                fields,
+            });
+        }
+        Some(Self {
+            first_record_hash: be32(8),
+            records,
+        })
+    }
+
+    /// Every record, in on-disc order (ascending `name_hash`).
+    pub fn records(&self) -> &[IxudRecord] {
+        &self.records
+    }
+
+    /// The record named `name` (matched by `ixud_hash`).
+    pub fn record(&self, name: &str) -> Option<&IxudRecord> {
+        let key = crate::hash::ixud_hash_str(name);
+        self.records.iter().find(|r| r.name_hash == key)
+    }
+}
+
+/// A field `name_off` of `0xFFFF_FFFF` marks a positional field.
+const NO_NAME: u32 = 0xFFFF_FFFF;

crates/sylpheed-formats/src/lib.rs

@@ -37,6 +37,12 @@ pub mod t8ad;
 // RATC nested resource bundle
 pub mod ratc;
 
+/// UI screen layout (`.rat` / RATC) — reassemble a screen from its pak.
+pub mod ui_layout;
+
+/// The retail `savedata` file: GDHA container, zlib payload, chunk stream.
+pub mod savegame;
+
 // LSTA sprite list (inline T8aD frames)
 pub mod lsta;
 
@@ -61,6 +67,10 @@ pub mod movie_manifest;
 
 pub mod movie_voice;
 
+/// Assembling media whose bytes are not one archive entry — segment-spanning
+/// reads, multi-sub-wave banks, and the continuous cutscene-voice stream.
+pub mod media;
+
 pub mod game_data;
 
 pub mod localization;
@@ -68,13 +78,18 @@ pub mod localization;
 // Whole-ship assembly from XBG7 part families (capital ships as split parts).
 pub mod ship;
 
+/// The runtime layout of a unit / vessel definition object, read out of the
+/// title's loader and verified against a live mission (see the module docs).
+pub mod unit_layout;
+
 // Exact capital-ship placement from a runtime F10 ship-capture (ground truth).
 pub mod ship_capture;
 
 /// Re-export the most commonly used types at the crate root.
+pub use audio::{AudioCodec, AudioInfo, GameAudio};
 pub use font::FontInfo;
 pub use idxd::{IdxdError, IdxdObject};
-pub use ixud::{Cue, Subtitle};
+pub use ixud::{Cue, IxudField, IxudObject, IxudRecord, Subtitle};
 pub use movie_subtitle::{SubCue, SubLang};
 pub use mesh::{GameMesh, Xbg7Model};
 pub use ratc::RatcChild;

crates/sylpheed-formats/src/lsta.rs

@@ -1,9 +1,18 @@
-//! `LSTA` — a sprite list: a header followed by N inline [`T8aD`](crate::t8ad)
-//! frames concatenated back-to-back.
+//! `LSTA` — a display list: a header followed by N inline elements concatenated
+//! back-to-back, each either a [`T8aD`](crate::t8ad) sprite or a `PRMD`
+//! primitive (a flat coloured quad — the same primitive the UI bundles use to
+//! dim a scene).
 //!
-//! A `count` lives at `@0x04`, but a few entries disagree with the actual frame
-//! count, so we walk by the `T8aD` magic instead (robust) and decode each frame
-//! from its slice up to the next frame (or end).
+//! The `count` at `@0x04` is **exact, and counts both kinds**: across all 64
+//! lists on the disc, `count == T8aD frames + PRMD primitives` with no
+//! exceptions (measured 2026-08-11). An earlier note here said "a few entries
+//! disagree with the actual frame count" — they do not; that comparison was
+//! counting sprites against a total that includes primitives.
+//!
+//! [`parse`] walks by magic and returns the **sprites**, deliberately skipping
+//! `PRMD` entries, so its result length is `count` only for lists that hold no
+//! primitives. Six lists do (in `GP_DEBRIEFING_PILOTLOG`, `GP_MISSION_SELECT`),
+//! each with exactly one.
 
 use crate::t8ad::{self, T8adImage, T8AD_MAGIC};
 
@@ -15,8 +24,9 @@ pub fn is_lsta(bytes: &[u8]) -> bool {
     bytes.len() >= 4 && bytes[0..4] == LSTA_MAGIC
 }
 
-/// Decode all inline T8aD frames. Frames that don't decode (unsupported T8aD
-/// variant) are skipped. Returns `None` only for non-LSTA input.
+/// Decode the inline T8aD sprites, skipping `PRMD` primitives. Returns `None`
+/// only for non-LSTA input. Every one of the 1 281 sprite frames on the disc
+/// decodes (measured 2026-08-11, after the T8aD rectangle-list fix).
 pub fn parse(bytes: &[u8]) -> Option<Vec<T8adImage>> {
     if !is_lsta(bytes) {
         return None;
@@ -48,12 +58,21 @@ pub fn parse(bytes: &[u8]) -> Option<Vec<T8adImage>> {
 mod tests {
     use super::*;
 
+    /// A faithful one-rectangle T8aD frame: base header, a 1-entry offset table,
+    /// then the rectangle header (dst 0,0, size w×h) and its pixels. (Before
+    /// 2026-08-11 this fixture wrote no offset-table entry at all and the decoder
+    /// read "pixels" from inside the header — the test only ever checked the
+    /// dimensions, so it passed anyway.)
     fn t8ad_frame(w: u32, h: u32) -> Vec<u8> {
-        let mut b = vec![0u8; 64];
+        let mut b = vec![0u8; 0x2c];
         b[0..4].copy_from_slice(&T8AD_MAGIC);
         b[0x14..0x18].copy_from_slice(&w.to_be_bytes());
         b[0x18..0x1c].copy_from_slice(&h.to_be_bytes());
         b[0x1c..0x20].copy_from_slice(&1u32.to_be_bytes());
+        b.extend_from_slice(&0x30u32.to_be_bytes()); // offset table → rect at 0x30
+        for v in [0u32, 0, w, h] {
+            b.extend_from_slice(&v.to_be_bytes()); // dst X, dst Y, width, height
+        }
         b.extend_from_slice(&vec![0x80u8; (w * h * 4) as usize]);
         b
     }

crates/sylpheed-formats/src/media.rs

@@ -0,0 +1,361 @@
+//! Assembling media that does **not** sit in one place on the disc.
+//!
+//! Most assets are one archive entry and are read with [`crate::pak`] alone.
+//! Audio is not, and this module owns every case where the bytes of one playable
+//! thing have to be gathered from somewhere other than a single entry:
+//!
+//! * **An entry spans segment files.** A `.pak` TOC offset addresses the
+//!   *concatenated* `.p00…​.pNN` stream, so one entry routinely straddles two
+//!   files on disc. [`DiscSource::read_segment_range`] is the seam for that.
+//! * **A bank holds several sub-waves.** A `.slb` is an XACT bank; its sub-waves
+//!   are either alternate takes or sequential segments of one line, and only
+//!   concatenating them all and clamping to the known length gets both right.
+//! * **A cutscene voice is not in its own bank.** The movie voices are one
+//!   continuous XMA stream chunked into `VOICE_*.slb` TOC entries whose
+//!   boundaries do **not** match the cutscene cues. A cue routinely spans two
+//!   chunks, so *a `.slb` need not hold the track its name claims*.
+//!   [`resolve_movie_voice_region`] resolves a movie to a byte region of the
+//!   stream instead, which is the only reading that produces the right audio.
+//!
+//! ## Why this lives in `sylpheed-formats` and not in a viewer
+//!
+//! It used to live in the Bevy viewer, which meant the one piece of logic most
+//! likely to be re-derived incorrectly was in the crate least likely to be
+//! reused. Anything that reads the disc — the viewer, a CLI, an asset exporter
+//! for a port — needs the same answers, and there must be one implementation of
+//! them.
+//!
+//! ## What deliberately stays out
+//!
+//! Decoding. This module returns **XMA `RIFF`s**, not PCM: turning XMA into
+//! samples means shelling out to FFmpeg, which is a native-only dependency and
+//! a policy decision for the consumer. The seam is "here are the bytes that
+//! belong together" — everything up to that point is disc knowledge, everything
+//! after it is a codec choice.
+
+use crate::pak::PakArchive;
+use crate::slb::VoiceLang;
+
+/// Where disc bytes come from. Implemented over an extracted directory, an ISO,
+/// or anything else that can serve the same three questions.
+///
+/// It is a trait rather than a concrete type because the callers differ in ways
+/// this module should not know about: a viewer reads from whichever source the
+/// user opened, a headless exporter reads from a fixed extract, and a test reads
+/// from a fixture.
+pub trait DiscSource {
+    /// Read a whole file by disc-relative path, e.g. `dat/sound.pak`.
+    fn read_file(&self, path: &str) -> Result<Vec<u8>, String>;
+
+    /// Open an IPFB archive by disc-relative path, with its `.pNN` segments.
+    fn open_pak(&self, path: &str) -> Result<PakArchive, String>;
+
+    /// Read `len` bytes at `offset` into the concatenated `<stem>.p00…​.pNN`
+    /// stream, where `stem` is a disc-relative path without extension
+    /// (`dat/sound`). The range may cross a segment boundary; that is the point.
+    fn read_segment_range(&self, stem: &str, offset: u64, len: usize) -> Result<Vec<u8>, String>;
+}
+
+/// Read one `sound.pak` bank by name-hash, taking only its byte range from the
+/// segments rather than inflating the 1.07 GB archive.
+pub fn read_sound_bank<S: DiscSource + ?Sized>(
+    source: &S,
+    name_hash: u32,
+) -> Result<Vec<u8>, String> {
+    let toc = source.read_file("dat/sound.pak")?;
+    let entries = PakArchive::parse_toc(&toc).map_err(|e| e.to_string())?;
+    let idx = entries
+        .binary_search_by_key(&name_hash, |e| e.name_hash)
+        .map_err(|_| "not present in sound.pak".to_string())?;
+    let e = &entries[idx];
+    source.read_segment_range("dat/sound", e.offset as u64, e.comp_size as usize)
+}
+
+/// The XMA `RIFF`s of one named bank, in the order they must be concatenated.
+///
+/// Every sub-wave is returned, not just the first. The two bank shapes need
+/// this for opposite reasons: a **segment** bank (`VOICE_RT07A` = 24 s + 14 s +
+/// 11 s ≈ the 50 s movie) is only complete when all of them are joined, and an
+/// **alternate-take** bank (`VOICE_S00A`, whose sub-wave 0 already spans the
+/// whole movie) is trimmed by the caller's length clamp. Taking sub-wave 0 alone
+/// dropped two thirds of the dialogue on segment banks — that was a real bug.
+pub fn sound_bank_riffs<S: DiscSource + ?Sized>(
+    source: &S,
+    clip_name: &str,
+) -> Result<Vec<Vec<u8>>, String> {
+    let bytes = read_sound_bank(source, crate::hash::name_hash(clip_name))?;
+    Ok(riffs_of(&bytes))
+}
+
+/// One sound-effect wave out of a **delimiter-less** bank, as a decodable `RIFF`.
+///
+/// `Static.slb` — where the menu's cues live — has no `RIFF`, no `seek` chunk and
+/// no XACT container: it is a packed run of whole 2048-byte XMA1 packets. So
+/// [`sound_bank_riffs`] finds nothing to split on, and a wave is defined *only*
+/// by `(offset, packet_count)`. Both come from the running game, not from the
+/// file: launch Canary with `--xma_param_probe=true`, trigger the sound, and the
+/// log prints the stream's packet count and first 32 bytes; searching those bytes
+/// in the bank gives the offset. ⚠️ The file order is **not** cue-id order, so the
+/// index cannot be counted out — see `docs/re/menu-audio-cues.md`.
+///
+/// The three cues a menu needs, all mono 48 kHz:
+///
+/// | event | offset | packets |
+/// |---|---|---|
+/// | d-pad move | `0x1ec0` | 4 |
+/// | Ⓑ back | `0x0ec0` | 2 |
+/// | Ⓐ confirm | `0x5d6c0` | 6 |
+///
+/// Returns an error rather than a short stream if the bank does not actually
+/// hold `packet_count` whole packets at `offset` — a truncated XMA stream decodes
+/// to plausible-sounding garbage, which is the failure worth refusing.
+pub fn se_wave_riff<S: DiscSource + ?Sized>(
+    source: &S,
+    bank: &str,
+    offset: usize,
+    packet_count: usize,
+    channels: u8,
+    rate: u32,
+) -> Result<Vec<u8>, String> {
+    let len = packet_count * crate::slb::XMA1_PACKET;
+    // Read only the packets asked for, not the whole bank. That is not just an
+    // efficiency point: `Static.slb` is 8.97 MB and is the ONE entry in
+    // `sound.pak` whose declared extent runs past the end of the extracted
+    // segments (by 616 768 B), so reading it whole fails outright on a disc
+    // extraction that is short at the tail. Every cue we need sits in the first
+    // few hundred KB. See `docs/re/menu-audio-cues.md`.
+    let toc = source.read_file("dat/sound.pak")?;
+    let entries = PakArchive::parse_toc(&toc).map_err(|e| e.to_string())?;
+    let hash = crate::hash::name_hash(bank);
+    let idx = entries
+        .binary_search_by_key(&hash, |e| e.name_hash)
+        .map_err(|_| format!("{bank}: not present in sound.pak"))?;
+    let e = &entries[idx];
+    if offset + len > e.comp_size as usize {
+        return Err(format!(
+            "{bank}: {packet_count} packets at {offset:#x} need {len} bytes, \
+             but the bank declares only {} bytes",
+            e.comp_size
+        ));
+    }
+    let packets =
+        source.read_segment_range("dat/sound", e.offset as u64 + offset as u64, len)?;
+    Ok(crate::slb::xma1_wave_riff(&packets, channels, rate))
+}
+
+/// The XMA `RIFF`s of a continuous byte region of the voice stream, as returned
+/// by [`resolve_movie_voice_region`].
+pub fn voice_region_riffs<S: DiscSource + ?Sized>(
+    source: &S,
+    start: u64,
+    end: u64,
+) -> Result<Vec<Vec<u8>>, String> {
+    let bytes = source.read_segment_range("dat/sound", start, (end - start) as usize)?;
+    Ok(riffs_of(&bytes))
+}
+
+/// Sub-wave `RIFF`s of a bank's bytes, with the single-stream fallback.
+///
+/// Some banks — the data-before-header `\etc\` radio clips — defeat the
+/// multi-sub-wave scanner, and the robust single-stream reader handles them. An
+/// empty result here means genuinely undecodable, not "scanner confused".
+fn riffs_of(bytes: &[u8]) -> Vec<Vec<u8>> {
+    let riffs = crate::slb::to_xma_riffs(bytes);
+    if riffs.is_empty() {
+        crate::slb::to_xma_riff_best(bytes).into_iter().collect()
+    } else {
+        riffs
+    }
+}
+
+/// Resolve a movie's voice bank **name** through the manifest in `tables.pak`.
+///
+/// Only the manifest's DIRECT bindings are trusted. Extending this to unbound
+/// resupply movies by shared demo line was tried and verified WRONG — it played
+/// the wrong recording — so an unbound movie stays unvoiced rather than play a
+/// guess. `None` therefore means "this cutscene has no voice-over", which is a
+/// real answer for most `hokyu_*` movies.
+pub fn resolve_movie_voice_clip<S: DiscSource + ?Sized>(
+    source: &S,
+    movie: &str,
+    lang: VoiceLang,
+) -> Option<String> {
+    let pak = source.open_pak("dat/tables.pak").ok()?;
+    let manifest = find_manifest(&pak)?;
+    let sounds = pak
+        .read_by_name(&format!("{}\\sounds.tbl", lang.code_pub()))?
+        .ok()?;
+    crate::movie_manifest::resolve_voice_entry(&manifest, &sounds, movie, lang)
+}
+
+/// The manifest has no stable name, so it is found by shape among the entries.
+fn find_manifest(pak: &PakArchive) -> Option<Vec<u8>> {
+    pak.entries().iter().find_map(|e| {
+        pak.read(e)
+            .ok()
+            .filter(|b| crate::movie_manifest::is_manifest(b))
+    })
+}
+
+/// Voice token for a hokyu (resupply) cutscene the manifest leaves unbound.
+///
+/// Only 5 of the 18 hokyu movies carry an explicit `VOICETRACK`; the rest reuse
+/// those recordings. The selector is the cutscene's **demo id** (from its
+/// subtitle track), NOT the ship category: `hokyu_LS_s02A` and `hokyu_LS_s11A`
+/// are both LS/carrier but use demos 600 vs 601, whose lines differ. So the map
+/// is derived from the 5 bound hokyu — each of which has both a subtitle demo id
+/// and a `VOICETRACK` — and the target movie's demo id is looked up in it.
+pub fn hokyu_voice_token<S: DiscSource + ?Sized>(
+    source: &S,
+    movie: &str,
+    lang: VoiceLang,
+    manifest: &[u8],
+) -> Option<String> {
+    use crate::movie_subtitle as ms;
+    if !movie.starts_with("hokyu_") {
+        return None;
+    }
+    let lang_pak = source
+        .open_pak(&format!("dat/movie/{}.pak", lang.code_pub()))
+        .ok()?;
+    let want = ms::track_voice_cues(&lang_pak, movie).first().map(|&(d, _)| d)?;
+    crate::movie_manifest::parse(manifest)
+        .into_iter()
+        .find_map(|e| {
+            let tok = e.voice_token.filter(|_| e.movie.starts_with("hokyu_"))?;
+            ms::track_voice_cues(&lang_pak, &e.movie)
+                .iter()
+                .any(|&(d, _)| d == want)
+                .then_some(tok)
+        })
+}
+
+/// Resolve a movie's cutscene voice to a continuous `[start, end)` byte region
+/// of the voice stream — **the reading that produces the right audio**.
+///
+/// The chain is movie → cue token (manifest) → sound id (master registry) →
+/// region (scan the stream for two trailers). Each cue ends at an inline
+/// `(sound_id, 0x11, …)` trailer, so cue *N* is the bytes between trailer *N-1*
+/// and trailer *N*.
+///
+/// Returns `None` for movies whose voice is not a `\Movie\` bank — the hokyu
+/// `\etc\` clips — which the caller then resolves the per-clip way via
+/// [`resolve_movie_voice_clip`].
+pub fn resolve_movie_voice_region<S: DiscSource + ?Sized>(
+    source: &S,
+    movie: &str,
+    lang: VoiceLang,
+) -> Option<(u64, u64)> {
+    use crate::{hash::name_hash, movie_manifest, movie_voice};
+    let code = lang.code_pub();
+    let tpak = source.open_pak("dat/tables.pak").ok()?;
+    let manifest = find_manifest(&tpak)?;
+    let token = movie_manifest::voice_token(&manifest, movie)
+        .or_else(|| hokyu_voice_token(source, movie, lang, &manifest))?;
+
+    // token → sound id, via the large per-language IDXD entry carrying the
+    // `<lang>\Movie\VOICE_*.slb` paths. Located by content, like the 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()))
+    })?;
+    let id = *movie_voice::registry_voice_ids(&registry).get(&token)?;
+
+    // Physical anchor: the TOC offset of this token's own `.slb` chunk. That is a
+    // start point NEAR the cue's trailers, not the cue itself — the cue may sit
+    // before or after it, which is the whole reason a region is needed. The
+    // token's subdirectory varies by kind.
+    let stoc = source.read_file("dat/sound.pak").ok()?;
+    let entries = PakArchive::parse_toc(&stoc).ok()?;
+    let 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)
+    })?;
+
+    // Scan both directions from the anchor. The window must span the largest
+    // bank (ADV ≈ 3.6 MB) or the predecessor trailer falls outside it.
+    let win_start = anchor.saturating_sub(2 * 1024 * 1024) & !3;
+    let window = source
+        .read_segment_range("dat/sound", win_start, 8 * 1024 * 1024)
+        .ok()?;
+    let end_local = movie_voice::find_descriptor(&window, id)?;
+    let end = win_start + end_local as u64;
+
+    // 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.
+    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)
+        .unwrap_or(anchor);
+    Some((start, end))
+}
+
+/// A [`DiscSource`] over an **extracted** disc directory.
+///
+/// Provided here rather than left to each caller because every headless
+/// consumer — the CLI, the disc tests, an asset exporter for a port — wants
+/// exactly this and would otherwise re-derive the segment-spanning read, which
+/// is the part that is easy to get subtly wrong.
+#[cfg(not(target_arch = "wasm32"))]
+pub struct DirectorySource {
+    root: std::path::PathBuf,
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+impl DirectorySource {
+    pub fn new(root: impl Into<std::path::PathBuf>) -> Self {
+        Self { root: root.into() }
+    }
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+impl DiscSource for DirectorySource {
+    fn read_file(&self, path: &str) -> Result<Vec<u8>, String> {
+        std::fs::read(self.root.join(path)).map_err(|e| format!("{path}: {e}"))
+    }
+
+    fn open_pak(&self, path: &str) -> Result<PakArchive, String> {
+        PakArchive::open(self.root.join(path)).map_err(|e| format!("{path}: {e}"))
+    }
+
+    /// Walks `<stem>.p00`, `.p01`, … skipping whole segments until the offset is
+    /// inside one, then reads across as many as the length needs. A range that
+    /// straddles a boundary is the normal case, not an edge case.
+    fn read_segment_range(&self, stem: &str, offset: u64, len: usize) -> Result<Vec<u8>, String> {
+        use std::io::{Read, Seek, SeekFrom};
+        let mut out = Vec::with_capacity(len);
+        let (mut skip, mut need) = (offset, len);
+        for i in 0..100u32 {
+            if need == 0 {
+                break;
+            }
+            let path = self.root.join(format!("{stem}.p{i:02}"));
+            let Ok(meta) = std::fs::metadata(&path) else { break };
+            let seg_len = meta.len();
+            if skip >= seg_len {
+                skip -= seg_len;
+                continue;
+            }
+            let mut f = std::fs::File::open(&path).map_err(|e| e.to_string())?;
+            f.seek(SeekFrom::Start(skip)).map_err(|e| e.to_string())?;
+            let take = need.min((seg_len - skip) as usize);
+            let start = out.len();
+            out.resize(start + take, 0);
+            f.read_exact(&mut out[start..]).map_err(|e| e.to_string())?;
+            need -= take;
+            skip = 0;
+        }
+        if need != 0 {
+            return Err(format!("segment range short by {need} bytes"));
+        }
+        Ok(out)
+    }
+}

crates/sylpheed-formats/src/movie_manifest.rs

@@ -100,6 +100,61 @@ const FIELD_KEYS: [&str; 4] = ["MOVIE", "VOICETRACK", "SUBTITLE", "TELOP"];
 /// mission/phase; otherwise (a blob without the key array) the kind is inferred
 /// from the movie name and `slot` is empty.
 pub fn parse(bytes: &[u8]) -> Vec<MovieEntry> {
+    if let Some(rows) = parse_records(bytes) {
+        return rows;
+    }
+    parse_string_pool(bytes)
+}
+
+/// Read the manifest out of the IDXD **record table** — the authoritative path.
+///
+/// `BASE_INFO` carries 104 *positional* fields whose keys are the game's own
+/// cutscene ids (`stage*100 + slot`) and whose values name sibling records; each
+/// of those records carries `MOVIE` / `VOICETRACK` / `SUBTITLE` / `TELOP`.
+///
+/// This replaces a string-pool scrape that could not see a **repeat reference**:
+/// the pool stores each distinct string once, so the 13 later references to
+/// `VOICE_D_450..454`, the two to `SUBTITLE_hokyu_LS_s11A.tbl` and `MS01A`'s
+/// share of `pwterop_s01a.prt` produced no token and read as "no binding". That
+/// is why `hokyu_DS_s13A` was recorded as having no voice-over.
+///
+/// Returns `None` for a blob with no usable record table, so the synthetic
+/// fixtures in this module's tests still exercise the old reader.
+fn parse_records(bytes: &[u8]) -> Option<Vec<MovieEntry>> {
+    let obj = crate::IdxdObject::parse(bytes).ok()?;
+    let base = obj.record("BASE_INFO")?;
+    // Ids ascend; the game's own order is play order.
+    let mut ids: Vec<(u32, &str)> = base
+        .fields
+        .iter()
+        .filter_map(|f| f.index().map(|i| (i, f.value.as_str())))
+        .collect();
+    if ids.is_empty() {
+        return None;
+    }
+    ids.sort_unstable();
+    let mut out = Vec::with_capacity(ids.len());
+    for (_, slot) in ids {
+        let Some(rec) = obj.record(slot) else { continue };
+        let Some(movie) = rec.get("MOVIE") else { continue };
+        let (kind, mission, phase) = classify_slot(slot);
+        out.push(MovieEntry {
+            slot: slot.to_string(),
+            kind,
+            mission,
+            phase,
+            movie: movie.trim_end_matches(".wmv").to_string(),
+            voice_token: rec.get("VOICETRACK").map(after_plus),
+            subtitle: rec.get("SUBTITLE").map(after_plus),
+            telop: rec.get("TELOP").map(after_plus),
+        });
+    }
+    (!out.is_empty()).then_some(out)
+}
+
+/// The legacy string-pool reader. Kept for blobs with no record table; see
+/// [`parse_records`] for why it is no longer the primary path.
+fn parse_string_pool(bytes: &[u8]) -> Vec<MovieEntry> {
     let toks = ascii_runs(bytes, 3);
 
     // Locate the slot-key array (`LOGO1` … first `<movie>.wmv`) and the value
@@ -334,7 +389,11 @@ mod tests {
         assert_eq!(m[0].subtitle.as_deref(), Some("SUBTITLE_S13A.tbl"));
         assert_eq!(m[1].voice_token.as_deref(), Some("VOICE_D_450"));
         assert_eq!(m[1].kind, MovieKind::Supply);
-        assert_eq!(m[2].voice_token, None, "hokyu_DS_s13A has no voice-over");
+        // NB: in the synthetic blob below this movie really has no token. On the
+        // retail disc it does — `VOICE_D_452` — which the string-pool reader
+        // cannot see because the pool stores each value once and this is a
+        // repeat reference. The disc test pins the real value.
+        assert_eq!(m[2].voice_token, None);
         assert_eq!(m[2].kind, MovieKind::Supply);
     }
 

crates/sylpheed-formats/src/movie_subtitle.rs

@@ -25,8 +25,10 @@ use crate::pak::PakArchive;
 
 /// Subtitle language. `pak_code` selects `dat/movie/<code>.pak`; `game_code`
 /// selects `dat/GP_MAIN_GAME_<code>.pak` (the caption text).
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub enum SubLang {
+    /// Default only because the disc's own default is English.
+    #[default]
     English,
     Japanese,
     German,
@@ -238,6 +240,76 @@ pub fn build_demo_text(text_pak: &PakArchive) -> BTreeMap<u32, Vec<String>> {
         .collect()
 }
 
+/// Every caption family in the pack, not just the cutscene one.
+///
+/// `build_demo_text` reads `MSG_DEMO_*` — 560 text-bearing keys, the **smallest**
+/// of eight families. The other seven carry the combat chatter and the in-mission
+/// scripted dialogue: 44 019 more lines, or **98.7 %** of the game's text.
+///
+/// Key shapes, measured over every IXUD block in `GP_MAIN_GAME_E.pak`:
+///
+/// | family | shape | text-bearing keys |
+/// |---|---|---|
+/// | `ACRO` `ADAN` `ADPL` `BIRD` `DEMO` `RHIN` `TCAF` | `MSG_<FAM>_<id>_<page>_<line>` | 37 803 |
+/// | `VOICE` | `MSG_VOICE_<letter>_<id>_<page>_<line>` | 6 776 |
+///
+/// `VOICE` is the only family with a letter before the id, and every family is
+/// 100 % consistent with its own shape.
+///
+/// Returns `"<FAM>_<id>" → ordered lines`, e.g. `"ADAN_600"`, `"VOICE_A_150"`.
+///
+/// ⚠️ The id here is the **caption** id. It is *not* the voice-bank id: a message
+/// page binding `VOICE_C_468` carries lines keyed `MSG_VOICE_C_385_*`. Same
+/// family letter, different index space — do not derive one from the other.
+pub fn build_caption_text(text_pak: &PakArchive) -> BTreeMap<String, Vec<String>> {
+    let mut by_id: BTreeMap<String, BTreeMap<(u32, u32), String>> = BTreeMap::new();
+    for entry in text_pak.entries() {
+        let Ok(bytes) = text_pak.read(entry) else {
+            continue;
+        };
+        let Some(obj) = crate::IxudObject::parse(&bytes) else {
+            continue;
+        };
+        // Read the caption as a FIELD -- its key is the `MSG_*` name and its
+        // value is the text. The token-adjacency version of this recovered 8074
+        // lines against the 44579 fields that actually carry text, because pool
+        // adjacency is a consequence of how records are written rather than a
+        // rule of the format. Same mistake the IDXD reader made.
+        for rec in obj.records() {
+            for f in &rec.fields {
+                let Some(key) = f.name.as_deref() else { continue };
+                let Some((id, page, line)) = caption_key(key) else {
+                    continue;
+                };
+                if f.value.trim().is_empty() {
+                    continue;
+                }
+                by_id.entry(id).or_default().insert((page, line), clean(&f.value));
+            }
+        }
+    }
+    by_id
+        .into_iter()
+        .map(|(d, m)| (d, m.into_values().collect()))
+        .collect()
+}
+
+/// `MSG_<FAM>_<id>_<page>_<line>` → `("<FAM>_<id>", page, line)`, with `VOICE`'s
+/// extra family letter folded into the id.
+fn caption_key(t: &str) -> Option<(String, u32, u32)> {
+    let rest = t.strip_prefix("MSG_")?;
+    let mut parts: Vec<&str> = rest.split('_').collect();
+    // Trailing <page>_<line> are always numeric.
+    let line: u32 = parts.pop()?.parse().ok()?;
+    let page: u32 = parts.pop()?.parse().ok()?;
+    // What remains is <FAM> or <FAM>_<letter>, then the numeric id.
+    let id: u32 = parts.pop()?.parse().ok()?;
+    if parts.is_empty() {
+        return None;
+    }
+    Some((format!("{}_{id:03}", parts.join("_")), page, line))
+}
+
 /// Parse a timing track's IXUD payload into `(token, start, end)` triples, where
 /// `token` is either a `MSG_DEMO_<d>` reference or an inline caption string.
 ///

crates/sylpheed-formats/src/pak.rs

@@ -190,6 +190,17 @@ impl PakArchive {
         Ok(Self::from_parts(index, Vec::new())?.entries)
     }
 
+    /// A raw slice of the concatenated segment data, by absolute offset.
+    ///
+    /// Entry windows are **not** wave boundaries in `sound.pak`: a `.slb` wave
+    /// runs to `data_at + declared_size`, which routinely overruns the entry's
+    /// own `comp_size` (see docs/re/structures/slb-data-offset.md). Reading the
+    /// boundary marker therefore needs the flat stream, not the entry slice.
+    /// Returns `None` if the range falls outside the loaded data.
+    pub fn data_at(&self, offset: usize, len: usize) -> Option<&[u8]> {
+        self.data.get(offset..offset.checked_add(len)?)
+    }
+
     /// All TOC entries, in stored order (ascending `name_hash`).
     pub fn entries(&self) -> &[PakEntry] {
         &self.entries
@@ -214,16 +225,34 @@ impl PakArchive {
     }
 
     /// The raw stored bytes for an entry (still `"Z1"`-wrapped / compressed).
+    ///
+    /// One entry on the retail disc declares more bytes than the segments hold:
+    /// `sound.pak`'s `Static.slb` (the SFX bank) claims 8 970 240 bytes at the
+    /// highest offset in the archive, 616 768 past the end of `sound.p04`. It is
+    /// not corruption and it is not our extraction — `sound.p04` is byte-for-byte
+    /// the size the ISO's own directory record gives, and a sweep of **every**
+    /// `.pak` on the disc finds this one entry and no other. So the last entry's
+    /// `comp_size` is an allocation size, not a stored size.
+    ///
+    /// A short read is therefore allowed **only** for the highest-offset entry,
+    /// which is the shape the evidence supports. Any other overrun is still an
+    /// error: that would be real damage, and clamping it would hide the damage
+    /// behind a half-decoded asset.
     pub fn stored_bytes(&self, entry: &PakEntry) -> Result<&[u8], PakError> {
         let start = entry.offset as usize;
         let end = start + entry.comp_size as usize;
-        self.data
-            .get(start..end)
-            .ok_or(PakError::OffsetOutOfRange {
-                offset: entry.offset,
-                size: entry.comp_size,
-                data_len: self.data.len(),
-            })
+        if let Some(b) = self.data.get(start..end) {
+            return Ok(b);
+        }
+        let is_tail = self.entries.iter().all(|e| e.offset <= entry.offset);
+        if is_tail && start < self.data.len() {
+            return Ok(&self.data[start..]);
+        }
+        Err(PakError::OffsetOutOfRange {
+            offset: entry.offset,
+            size: entry.comp_size,
+            data_len: self.data.len(),
+        })
     }
 
     /// Decompress an entry to its raw payload bytes. Handles the `"Z1"` container

crates/sylpheed-formats/src/ratc.rs

@@ -62,7 +62,7 @@ pub fn parse(bytes: &[u8]) -> Option<Vec<RatcChild>> {
     for (idx, &(off, kind)) in offs.iter().enumerate() {
         let next = offs.get(idx + 1).map(|&(o, _)| o).unwrap_or(bytes.len());
         children.push(RatcChild {
-            name: name_before(bytes, off),
+            name: opt_name(bytes, off).unwrap_or_else(|| name_before(bytes, off)),
             kind: kind.to_string(),
             offset: off,
             size: next.saturating_sub(off),
@@ -71,9 +71,51 @@ pub fn parse(bytes: &[u8]) -> Option<Vec<RatcChild>> {
     Some(children)
 }
 
+/// The name a child's own `opt ` block states, if it has one.
+///
+/// The real format is explicit. Immediately before each child sits
+///
+/// ```text
+/// "opt " | BE32 length | name | NUL | 3 bytes | <child magic>
+/// ```
+///
+/// -- the same `opt ` block `ui_layout`'s focus link already reads. Prefer it,
+/// because [`name_before`] is a heuristic and those 3 trailing bytes are
+/// sometimes printable, in which case the heuristic reads THEM as the name.
+/// Measured disc-wide: of 18 002 RATC children, 17 942 carry an `opt ` block,
+/// 17 918 of which agree with the scan and **24 do not** -- every one of the 24
+/// a 3-byte tail (`8AX` x22, `'OX` x2) beating a real name. On the title screens
+/// that cost the whole background: `pteff05.t32` came out as `8AX`, its element
+/// then resolved to no sprite, and `compose` silently dropped it. See
+/// `docs/re/structures/ratc-child-names.md`.
+fn opt_name(bytes: &[u8], off: usize) -> Option<String> {
+    let lo = off.saturating_sub(128);
+    let win = &bytes[lo..off];
+    let pos = lo + win.windows(4).rposition(|w| w == b"opt ")?;
+    let len = u32::from_be_bytes(bytes.get(pos + 4..pos + 8)?.try_into().ok()?) as usize;
+    if len == 0 || len > 64 || pos + 8 + len > off {
+        return None;
+    }
+    // It must be THIS child's block: the name, its NUL and a short run to the
+    // magic. Anything further away is a neighbour's block, so fall back.
+    if off - (pos + 8 + len) > 8 {
+        return None;
+    }
+    let s = String::from_utf8_lossy(&bytes[pos + 8..pos + 8 + len]).to_string();
+    (!s.is_empty() && s.chars().all(|c| c.is_ascii_graphic())).then_some(s)
+}
+
 /// The nearest name string preceding `off`: the *last* printable run (len ≥ 3)
 /// in the 96 bytes before the child magic. A few record-header bytes usually sit
 /// between the name and the magic, so an exact-adjacency scan isn't enough.
+///
+/// Fallback only -- [`opt_name`] is the stated name. 60 of the disc's 18 002
+/// children have no `opt ` block and still rely on this, and all 60 are
+/// accounted for: they are the ten frames of the disc's only `.tan` frame
+/// sequence, in six language copies of one `GP_READY_ROOM` bundle, where a
+/// single `opt ` block names the whole run. See
+/// `docs/re/structures/ratc-tan-frame-sequence.md` -- and note that this means
+/// `parse` OVER-reports there, listing frames as children.
 fn name_before(bytes: &[u8], off: usize) -> String {
     let start = off.saturating_sub(96);
     let window = &bytes[start..off];
@@ -101,6 +143,49 @@ fn name_before(bytes: &[u8], off: usize) -> String {
 mod tests {
     use super::*;
 
+    /// The `opt ` block wins over a printable tail.
+    ///
+    /// This is the `pteff05.t32` / `8AX` case, byte for byte: the name is stated
+    /// with an explicit length, then a NUL, then three payload bytes that happen
+    /// to spell `8AX` in ASCII. The old backwards printable-run scan returned
+    /// `8AX` here, which is what dropped the background from every menu screen.
+    #[test]
+    fn opt_block_beats_a_printable_tail() {
+        let mut b = RATC_MAGIC.to_vec();
+        b.extend_from_slice(&[0u8; 28]);
+        b.extend_from_slice(b"opt ");
+        b.extend_from_slice(&11u32.to_be_bytes()); // len("pteff05.t32")
+        b.extend_from_slice(b"pteff05.t32\0");
+        b.extend_from_slice(b"8AX"); // payload, printable by accident
+        let off = b.len();
+        b.extend_from_slice(b"T8aD");
+        b.extend_from_slice(&[0u8; 16]);
+
+        let kids = parse(&b).expect("parse");
+        assert_eq!(kids.len(), 1);
+        assert_eq!(kids[0].name, "pteff05.t32");
+        assert_eq!(kids[0].offset, off);
+        // And the heuristic on its own really would have said `8AX` -- so this
+        // test fails for the right reason if the preference is ever reversed.
+        assert_eq!(name_before(&b, off), "8AX");
+    }
+
+    /// No `opt ` block: 60 of the disc's 18 002 children are like this, and they
+    /// must keep working off the scan.
+    #[test]
+    fn falls_back_to_the_scan_without_an_opt_block() {
+        let mut b = RATC_MAGIC.to_vec();
+        b.extend_from_slice(&[0u8; 28]);
+        b.extend_from_slice(b"plain.t32");
+        b.extend_from_slice(&[0x0e, 0x10, 0xa4]);
+        let off = b.len();
+        b.extend_from_slice(b"T8aD");
+        b.extend_from_slice(&[0u8; 16]);
+
+        let kids = parse(&b).expect("parse");
+        assert_eq!(kids[0].name, "plain.t32");
+    }
+
     #[test]
     fn lists_named_children() {
         let mut b = RATC_MAGIC.to_vec();

crates/sylpheed-formats/src/savegame.rs

@@ -0,0 +1,604 @@
+//! `savedata` — the retail save file.
+//!
+//! The whole save is **545 bytes**. It lives in the console's content tree as a
+//! single file and there is no second one, so everything the game remembers
+//! between sessions is in here:
+//!
+//! ```text
+//! <content>/<XUID>/535107D4/00000001/game01/savedata
+//! ```
+//!
+//! # Container
+//!
+//! ```text
+//! 'GDHA'  <146-byte header>  <zlib stream, 78 DA>
+//! ```
+//!
+//! Much of the header is **uninitialised memory** — words like `0x828F3DA8` are
+//! guest virtual addresses that leaked out of the struct's padding — so it is not
+//! byte-reproducible and must not be read as meaningful. Three header fields
+//! *are* derived from the payload ([`Header::derived`]), and a handful more are a
+//! **summary copy** of payload fields ([`Header::summary`]) — which matters more
+//! than it sounds: the in-game Details panel reads the *summary*, not the
+//! payload, so editing a payload field alone leaves a stale panel beside it. A
+//! probe that judges "did that field change the display?" without patching the
+//! mirror cannot tell *"wrong field"* from *"the panel never reads the payload"*.
+//!
+//! # Payload
+//!
+//! A chunk stream, read off the title's own serializer at `0x822C00E8` (its
+//! writer primitive is `0x821885A8(stream, buf, len)`) rather than guessed, and
+//! verified by a byte-identical round-trip:
+//!
+//! ```text
+//! 'GDAA'                              payload magic
+//! u32 len, char[len]                  current game phase, e.g. "GP_BUNK"
+//! 'GHAD' + 122 bytes                  the progress block
+//! u32 16, 16 x ('SHAB' + 5 x u32)     the per-stage record table
+//! u32 4, "BUNK", 'NETA', u32          trailer
+//! ```
+//!
+//! The in-memory struct is written field-by-field with no packing changes, so a
+//! payload offset **is** the offset in the live save object: GHAD at `save+8`,
+//! the record table at `save+136`, and the serializer's next access after the
+//! table is `lwz r11,456(save)` — exactly `136 + 16*20`.
+//!
+//! # Confidence
+//!
+//! The container and the chunk layout are ✅ `CONFIRMED`. Individual GHAD fields
+//! are **not** uniformly known — eleven are still ❔ — so every field carries its
+//! own [`Confidence`] and a viewer is expected to show it rather than present the
+//! lot as solved. See `docs/re/structures/savegame-format.md`.
+
+use std::io::Read;
+
+/// How well a field is understood. Mirrors the `docs/re` convention.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Confidence {
+    /// Named and verified against the game.
+    Confirmed,
+    /// A well-supported reading, not proven.
+    Probable,
+    /// Unidentified.
+    Unknown,
+    /// A reading that was tested and **refuted** — recorded so it is not retried.
+    Refuted,
+}
+
+/// How to render a GHAD word.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum FieldKind {
+    /// Plain 32-bit count / enum / id.
+    U32,
+    /// 64-bit word.
+    U64,
+    /// Milliseconds, displayed as `m:ss.mmm`.
+    Millis,
+    /// Percent.
+    Percent,
+    /// Raw bytes.
+    Raw,
+    /// The per-item Arsenal development blob.
+    DevelopBlob,
+}
+
+/// One documented field of the GHAD progress block.
+#[derive(Debug, Clone, Copy)]
+pub struct FieldSpec {
+    /// Offset within the 122-byte GHAD block.
+    pub offset: usize,
+    /// Byte width.
+    pub size: usize,
+    pub kind: FieldKind,
+    pub confidence: Confidence,
+    /// Short name, or `""` when the field is unidentified.
+    pub name: &'static str,
+    /// What is known — including what was ruled out.
+    pub note: &'static str,
+}
+
+/// The GHAD block's layout, read off `0x822BF678`: ten u32, one u64
+/// (`ld r11,40(r30)`), four u32, a raw 4-byte field and a raw 54-byte blob.
+/// 10·4 + 8 + 4·4 + 4 + 54 = **122**, exactly what the file carries — the layout
+/// is closed, with nothing unaccounted for.
+pub const GHAD_LAYOUT: &[FieldSpec] = &[
+    FieldSpec { offset: 0,  size: 4,  kind: FieldKind::U32,     confidence: Confidence::Unknown,   name: "",              note: "" },
+    FieldSpec { offset: 4,  size: 4,  kind: FieldKind::Millis,  confidence: Confidence::Confirmed, name: "FlightTime",    note: "Milliseconds. 324773 ms against the panel's `Flight Time 000:05:24`." },
+    FieldSpec { offset: 8,  size: 4,  kind: FieldKind::Percent, confidence: Confidence::Confirmed, name: "ClearRatio",    note: "Percent. Not a stage counter: developing one Arsenal weapon stepped it 5 → 6, so it counts collection too." },
+    FieldSpec { offset: 12, size: 4,  kind: FieldKind::U32,     confidence: Confidence::Probable,  name: "TimesCleared",  note: "Mirrored to header +0x28; the panel prints `Times Cleared`." },
+    FieldSpec { offset: 16, size: 4,  kind: FieldKind::U32,     confidence: Confidence::Unknown,   name: "",              note: "" },
+    FieldSpec { offset: 20, size: 4,  kind: FieldKind::U32,     confidence: Confidence::Unknown,   name: "",              note: "" },
+    FieldSpec { offset: 24, size: 4,  kind: FieldKind::U32,     confidence: Confidence::Confirmed, name: "Points",        note: "The spendable balance. Separated from +28 by a develop differential: spending 4000 P moved only this field (4101 → 101)." },
+    FieldSpec { offset: 28, size: 4,  kind: FieldKind::U32,     confidence: Confidence::Probable,  name: "PointsTotal?",  note: "Not the displayed Points — it did NOT move when 4000 P was spent. A lifetime/earned total is the obvious read; unproven until a save is taken after earning." },
+    FieldSpec { offset: 32, size: 4,  kind: FieldKind::U32,     confidence: Confidence::Unknown,   name: "",              note: "" },
+    FieldSpec { offset: 36, size: 4,  kind: FieldKind::U32,     confidence: Confidence::Refuted,   name: "",              note: "Tested as difficulty and as stage; probe saves refuted both." },
+    FieldSpec { offset: 40, size: 8,  kind: FieldKind::U64,     confidence: Confidence::Unknown,   name: "",              note: "" },
+    FieldSpec { offset: 48, size: 4,  kind: FieldKind::U32,     confidence: Confidence::Probable,  name: "GameStatus",    note: "Mirrored to header +0x18; 0 renders `At Standby`, matching the screen's STATE_STAND_BY / STATE_STAGE_CLEAR / STATE_GAME_CLEAR list." },
+    FieldSpec { offset: 52, size: 4,  kind: FieldKind::U32,     confidence: Confidence::Confirmed, name: "Stage",         note: "1-based stage number. Set it to 5 (with the header mirror) and the game reads `STAGE 05 — Star System Escape`, loads it, and flies it." },
+    FieldSpec { offset: 56, size: 4,  kind: FieldKind::U32,     confidence: Confidence::Refuted,   name: "",              note: "See +36 — refuted." },
+    FieldSpec { offset: 60, size: 4,  kind: FieldKind::U32,     confidence: Confidence::Unknown,   name: "",              note: "" },
+    FieldSpec { offset: 64, size: 4,  kind: FieldKind::Raw,     confidence: Confidence::Unknown,   name: "",              note: "The trailer's u32 carries the same value." },
+    FieldSpec { offset: 68, size: 54, kind: FieldKind::DevelopBlob, confidence: Confidence::Confirmed, name: "DevelopState", note: "One byte per Arsenal item. Index space is strings.tbl's item order, cut items included, closing at 53." },
+];
+
+/// Size of the GHAD progress block.
+pub const GHAD_SIZE: usize = 122;
+/// Records in the per-stage table.
+pub const RECORD_COUNT: usize = 16;
+/// `u32`s per record, after the `SHAB` tag.
+pub const RECORD_FIELDS: usize = 5;
+/// Length of the Arsenal development blob.
+pub const DEVELOP_BLOB_LEN: usize = 54;
+
+/// State of one Arsenal item in the development blob.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DevelopState {
+    /// `0` — not yet available.
+    Locked,
+    /// `2` — available to develop now. **Re-derived at load**, not stored state.
+    Developable,
+    /// `4` — owned.
+    Developed,
+    /// Anything else, which no save has yet shown.
+    Other(u8),
+}
+
+impl DevelopState {
+    pub fn from_byte(b: u8) -> Self {
+        match b {
+            0 => Self::Locked,
+            2 => Self::Developable,
+            4 => Self::Developed,
+            other => Self::Other(other),
+        }
+    }
+}
+
+/// One `SHAB` record — a per-stage result, record 0 being Stage 01.
+///
+/// These are **not** the UI's 20 save slots, which is what the count of 16
+/// first suggested.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct StageRecord {
+    /// 🟡 difficulty.
+    pub a: u32,
+    /// ❔ a points figure — equals GHAD `+24`/`+28`, so not the displayed high
+    /// score (which is computed at display time and stored nowhere).
+    pub b: u32,
+    /// ✅ best clear time in milliseconds — 324 773 against the screen's
+    /// `05:24.77`.
+    pub best_time_ms: u32,
+    /// Windows FILETIME, high then low word.
+    pub time_hi: u32,
+    pub time_lo: u32,
+}
+
+impl StageRecord {
+    /// Whether the record holds a result at all.
+    pub fn is_used(&self) -> bool {
+        self.a != 0 || self.b != 0 || self.best_time_ms != 0
+    }
+
+    /// The record's FILETIME as 100 ns ticks since 1601, or `None` if unset.
+    pub fn filetime_ticks(&self) -> Option<u64> {
+        let t = (u64::from(self.time_hi) << 32) | u64::from(self.time_lo);
+        (t != 0).then_some(t)
+    }
+}
+
+/// The GDHA container header.
+#[derive(Debug, Clone)]
+pub struct Header {
+    /// The header bytes, verbatim.
+    pub bytes: Vec<u8>,
+}
+
+/// A header word that mirrors a payload field, with where it came from.
+#[derive(Debug, Clone, Copy)]
+pub struct Mirror {
+    pub header_offset: usize,
+    pub value: u32,
+    /// The GHAD offset this copies, if it is a GHAD field.
+    pub ghad_offset: Option<usize>,
+    pub name: &'static str,
+}
+
+impl Header {
+    fn be32(&self, o: usize) -> u32 {
+        if o + 4 > self.bytes.len() {
+            return 0;
+        }
+        u32::from_be_bytes([
+            self.bytes[o],
+            self.bytes[o + 1],
+            self.bytes[o + 2],
+            self.bytes[o + 3],
+        ])
+    }
+
+    /// The summary copy the in-game Details panel actually reads.
+    ///
+    /// This is the trap the format doc records: a payload edit that leaves these
+    /// stale shows no change on the panel, which is *not* evidence that the
+    /// payload field was the wrong one.
+    pub fn summary(&self) -> Vec<Mirror> {
+        vec![
+            Mirror { header_offset: 0x14, value: self.be32(0x14), ghad_offset: Some(52), name: "Stage" },
+            Mirror { header_offset: 0x1c, value: self.be32(0x1c), ghad_offset: Some(24), name: "Points" },
+            Mirror { header_offset: 0x20, value: self.be32(0x20), ghad_offset: Some(4),  name: "FlightTime" },
+            Mirror { header_offset: 0x24, value: self.be32(0x24), ghad_offset: Some(8),  name: "ClearRatio" },
+            Mirror { header_offset: 0x28, value: self.be32(0x28), ghad_offset: Some(12), name: "TimesCleared" },
+        ]
+    }
+
+    /// The three header fields derived from the payload — all that stands between
+    /// a parse and a hand-written save the title will load.
+    pub fn derived(&self) -> Vec<Mirror> {
+        vec![
+            Mirror { header_offset: 0x30, value: self.be32(0x30), ghad_offset: None, name: "deflate length + 10" },
+            Mirror { header_offset: 0x8c, value: u32::from(u16::from_be_bytes([self.bytes.get(0x8c).copied().unwrap_or(0), self.bytes.get(0x8d).copied().unwrap_or(0)])), ghad_offset: None, name: "payload length" },
+            Mirror { header_offset: 0x8e, value: self.be32(0x8e), ghad_offset: None, name: "adler32(payload)" },
+        ]
+    }
+}
+
+/// A fully parsed save.
+#[derive(Debug, Clone)]
+pub struct SaveGame {
+    pub header: Header,
+    /// The inflated payload, verbatim — the round-trip compares against this.
+    pub payload: Vec<u8>,
+    /// Current game phase, e.g. `GP_BUNK`. One of the title's screen ids.
+    pub phase: String,
+    /// The 122-byte progress block.
+    pub ghad: Vec<u8>,
+    /// The per-stage record table.
+    pub records: Vec<StageRecord>,
+    /// Trailer: `(name, tag, value)`.
+    pub trailer: (String, String, u32),
+}
+
+/// What went wrong reading a save.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum SaveError {
+    NotGdha,
+    NoZlibStream,
+    Inflate(String),
+    NotGdaa,
+    Truncated(&'static str),
+    /// A chunk tag was not where the serializer puts it.
+    BadTag { expected: &'static str, at: usize },
+    /// Bytes left over after the trailer — the layout is supposed to close
+    /// exactly, so this means the parse is wrong, not that the file has extras.
+    TrailingBytes(usize),
+}
+
+impl std::fmt::Display for SaveError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::NotGdha => write!(f, "not a GDHA container"),
+            Self::NoZlibStream => write!(f, "no zlib stream in the container"),
+            Self::Inflate(e) => write!(f, "inflate failed: {e}"),
+            Self::NotGdaa => write!(f, "payload is not GDAA"),
+            Self::Truncated(what) => write!(f, "payload truncated reading {what}"),
+            Self::BadTag { expected, at } => write!(f, "expected {expected} at {at:#x}"),
+            Self::TrailingBytes(n) => write!(f, "{n} bytes left after the trailer"),
+        }
+    }
+}
+
+impl std::error::Error for SaveError {}
+
+fn be32(b: &[u8], o: usize) -> Option<u32> {
+    b.get(o..o + 4)
+        .map(|s| u32::from_be_bytes([s[0], s[1], s[2], s[3]]))
+}
+
+/// Split a `GDHA` container into its header and inflated payload.
+pub fn unwrap_container(raw: &[u8]) -> Result<(Header, Vec<u8>), SaveError> {
+    if raw.len() < 4 || &raw[0..4] != b"GDHA" {
+        return Err(SaveError::NotGdha);
+    }
+    let at = raw
+        .windows(2)
+        .position(|w| w == [0x78, 0xDA])
+        .ok_or(SaveError::NoZlibStream)?;
+    let mut out = Vec::new();
+    flate2::read::ZlibDecoder::new(&raw[at..])
+        .read_to_end(&mut out)
+        .map_err(|e| SaveError::Inflate(e.to_string()))?;
+    Ok((
+        Header {
+            bytes: raw[..at].to_vec(),
+        },
+        out,
+    ))
+}
+
+/// Parse an inflated payload.
+pub fn parse_payload(payload: &[u8]) -> Result<SaveGame, SaveError> {
+    if payload.len() < 4 || &payload[0..4] != b"GDAA" {
+        return Err(SaveError::NotGdaa);
+    }
+    let mut o = 4usize;
+    let nlen = be32(payload, o).ok_or(SaveError::Truncated("phase length"))? as usize;
+    o += 4;
+    let phase = payload
+        .get(o..o + nlen)
+        .map(|s| String::from_utf8_lossy(s).to_string())
+        .ok_or(SaveError::Truncated("phase name"))?;
+    o += nlen;
+
+    if payload.get(o..o + 4) != Some(b"GHAD") {
+        return Err(SaveError::BadTag { expected: "GHAD", at: o });
+    }
+    o += 4;
+    let ghad = payload
+        .get(o..o + GHAD_SIZE)
+        .ok_or(SaveError::Truncated("GHAD block"))?
+        .to_vec();
+    o += GHAD_SIZE;
+
+    let count = be32(payload, o).ok_or(SaveError::Truncated("record count"))? as usize;
+    o += 4;
+    let mut records = Vec::with_capacity(count);
+    for _ in 0..count {
+        if payload.get(o..o + 4) != Some(b"SHAB") {
+            return Err(SaveError::BadTag { expected: "SHAB", at: o });
+        }
+        o += 4;
+        let mut v = [0u32; RECORD_FIELDS];
+        for slot in v.iter_mut() {
+            *slot = be32(payload, o).ok_or(SaveError::Truncated("record"))?;
+            o += 4;
+        }
+        records.push(StageRecord {
+            a: v[0],
+            b: v[1],
+            best_time_ms: v[2],
+            time_hi: v[3],
+            time_lo: v[4],
+        });
+    }
+
+    let tlen = be32(payload, o).ok_or(SaveError::Truncated("trailer length"))? as usize;
+    o += 4;
+    let tname = payload
+        .get(o..o + tlen)
+        .map(|s| String::from_utf8_lossy(s).to_string())
+        .ok_or(SaveError::Truncated("trailer name"))?;
+    o += tlen;
+    let ttag = payload
+        .get(o..o + 4)
+        .map(|s| String::from_utf8_lossy(s).to_string())
+        .ok_or(SaveError::Truncated("trailer tag"))?;
+    o += 4;
+    let tval = be32(payload, o).ok_or(SaveError::Truncated("trailer value"))?;
+    o += 4;
+    if o != payload.len() {
+        return Err(SaveError::TrailingBytes(payload.len() - o));
+    }
+
+    Ok(SaveGame {
+        header: Header { bytes: Vec::new() },
+        payload: payload.to_vec(),
+        phase,
+        ghad,
+        records,
+        trailer: (tname, ttag, tval),
+    })
+}
+
+/// Parse a whole `savedata` file.
+pub fn parse(raw: &[u8]) -> Result<SaveGame, SaveError> {
+    let (header, payload) = unwrap_container(raw)?;
+    let mut save = parse_payload(&payload)?;
+    save.header = header;
+    Ok(save)
+}
+
+impl SaveGame {
+    /// Re-serialize the payload.
+    ///
+    /// This is the correctness check for the whole layout: the serializer writes
+    /// the struct field-by-field with no packing, so a correct parse must
+    /// reproduce the payload **byte for byte**. See [`SaveGame::round_trips`].
+    pub fn serialize_payload(&self) -> Vec<u8> {
+        let mut out = Vec::with_capacity(self.payload.len());
+        out.extend_from_slice(b"GDAA");
+        out.extend_from_slice(&(self.phase.len() as u32).to_be_bytes());
+        out.extend_from_slice(self.phase.as_bytes());
+        out.extend_from_slice(b"GHAD");
+        out.extend_from_slice(&self.ghad);
+        out.extend_from_slice(&(self.records.len() as u32).to_be_bytes());
+        for r in &self.records {
+            out.extend_from_slice(b"SHAB");
+            for v in [r.a, r.b, r.best_time_ms, r.time_hi, r.time_lo] {
+                out.extend_from_slice(&v.to_be_bytes());
+            }
+        }
+        let (name, tag, val) = &self.trailer;
+        out.extend_from_slice(&(name.len() as u32).to_be_bytes());
+        out.extend_from_slice(name.as_bytes());
+        out.extend_from_slice(tag.as_bytes());
+        out.extend_from_slice(&val.to_be_bytes());
+        out
+    }
+
+    /// Whether re-serializing reproduces the payload exactly.
+    pub fn round_trips(&self) -> bool {
+        self.serialize_payload() == self.payload
+    }
+
+    /// Read a GHAD field as an unsigned integer. `None` for the raw/blob fields.
+    pub fn ghad_value(&self, spec: &FieldSpec) -> Option<u64> {
+        match spec.size {
+            4 => be32(&self.ghad, spec.offset).map(u64::from),
+            8 => self
+                .ghad
+                .get(spec.offset..spec.offset + 8)
+                .map(|s| u64::from_be_bytes(s.try_into().unwrap())),
+            _ => None,
+        }
+    }
+
+    /// Raw bytes of a GHAD field.
+    pub fn ghad_bytes(&self, spec: &FieldSpec) -> &[u8] {
+        self.ghad
+            .get(spec.offset..spec.offset + spec.size)
+            .unwrap_or(&[])
+    }
+
+    /// The per-item Arsenal development state.
+    ///
+    /// Index space is `strings.tbl`'s item order — the Arsenal's display order
+    /// *plus* the cut items only the localisation file lists — closing at 53.
+    /// `weapon.tbl`'s id list is **not** the index space; that it is also 54 long
+    /// is a coincidence, and the two agree only to index 32.
+    pub fn develop_state(&self) -> Vec<DevelopState> {
+        self.ghad
+            .get(68..68 + DEVELOP_BLOB_LEN)
+            .map(|b| b.iter().copied().map(DevelopState::from_byte).collect())
+            .unwrap_or_default()
+    }
+
+    /// Convenience: the 1-based stage number (GHAD `+52`).
+    pub fn stage(&self) -> Option<u32> {
+        be32(&self.ghad, 52)
+    }
+
+    /// Convenience: the spendable points balance (GHAD `+24`).
+    pub fn points(&self) -> Option<u32> {
+        be32(&self.ghad, 24)
+    }
+
+    /// Convenience: total flight time in milliseconds (GHAD `+4`).
+    pub fn flight_time_ms(&self) -> Option<u32> {
+        be32(&self.ghad, 4)
+    }
+
+    /// Convenience: clear ratio in percent (GHAD `+8`).
+    pub fn clear_ratio_pct(&self) -> Option<u32> {
+        be32(&self.ghad, 8)
+    }
+}
+
+/// Format a millisecond count the way the game's panels do (`m:ss.mmm`).
+pub fn fmt_millis(ms: u32) -> String {
+    let (m, rem) = (ms / 60_000, ms % 60_000);
+    format!("{}:{:02}.{:03}", m, rem / 1000, rem % 1000)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Build a payload with the exact chunk stream the serializer writes.
+    fn synth_payload(phase: &str, stage: u32, points: u32) -> Vec<u8> {
+        let mut ghad = vec![0u8; GHAD_SIZE];
+        ghad[4..8].copy_from_slice(&324_773u32.to_be_bytes()); // flight time
+        ghad[8..12].copy_from_slice(&5u32.to_be_bytes()); // clear ratio
+        ghad[24..28].copy_from_slice(&points.to_be_bytes());
+        ghad[52..56].copy_from_slice(&stage.to_be_bytes());
+        ghad[68] = 4; // item 0 developed
+        ghad[69] = 2; // item 1 developable
+        let mut p = Vec::new();
+        p.extend_from_slice(b"GDAA");
+        p.extend_from_slice(&(phase.len() as u32).to_be_bytes());
+        p.extend_from_slice(phase.as_bytes());
+        p.extend_from_slice(b"GHAD");
+        p.extend_from_slice(&ghad);
+        p.extend_from_slice(&(RECORD_COUNT as u32).to_be_bytes());
+        for i in 0..RECORD_COUNT {
+            p.extend_from_slice(b"SHAB");
+            let vals = if i == 0 {
+                [2u32, 4101, 324_773, 0x01DC_0000, 0x1234_5678]
+            } else {
+                [0, 0, 0, 0, 0]
+            };
+            for v in vals {
+                p.extend_from_slice(&v.to_be_bytes());
+            }
+        }
+        p.extend_from_slice(&4u32.to_be_bytes());
+        p.extend_from_slice(b"BUNK");
+        p.extend_from_slice(b"NETA");
+        p.extend_from_slice(&0x0915_0000u32.to_be_bytes());
+        p
+    }
+
+    #[test]
+    fn parses_the_chunk_stream() {
+        let p = synth_payload("GP_BUNK", 2, 4101);
+        let s = parse_payload(&p).unwrap();
+        assert_eq!(s.phase, "GP_BUNK");
+        assert_eq!(s.ghad.len(), GHAD_SIZE);
+        assert_eq!(s.records.len(), RECORD_COUNT);
+        assert_eq!(s.trailer, ("BUNK".into(), "NETA".into(), 0x0915_0000));
+        assert_eq!(s.stage(), Some(2));
+        assert_eq!(s.points(), Some(4101));
+        assert_eq!(s.flight_time_ms(), Some(324_773));
+        assert_eq!(s.clear_ratio_pct(), Some(5));
+    }
+
+    #[test]
+    fn round_trips_byte_identically() {
+        // The layout is closed, so a correct parse must reproduce the payload
+        // exactly. This is the property the whole spec rests on.
+        let p = synth_payload("GP_BUNK", 2, 4101);
+        let s = parse_payload(&p).unwrap();
+        assert!(s.round_trips());
+        assert_eq!(s.serialize_payload(), p);
+    }
+
+    #[test]
+    fn record_zero_is_stage_one() {
+        let s = parse_payload(&synth_payload("GP_BUNK", 2, 4101)).unwrap();
+        assert!(s.records[0].is_used());
+        assert!(!s.records[1].is_used());
+        assert_eq!(s.records[0].best_time_ms, 324_773);
+        assert!(s.records[0].filetime_ticks().is_some());
+        assert!(s.records[1].filetime_ticks().is_none());
+    }
+
+    #[test]
+    fn develop_blob_alphabet() {
+        let s = parse_payload(&synth_payload("GP_BUNK", 2, 4101)).unwrap();
+        let d = s.develop_state();
+        assert_eq!(d.len(), DEVELOP_BLOB_LEN);
+        assert_eq!(d[0], DevelopState::Developed);
+        assert_eq!(d[1], DevelopState::Developable);
+        assert_eq!(d[2], DevelopState::Locked);
+    }
+
+    #[test]
+    fn ghad_layout_is_closed() {
+        // 10*4 + 8 + 4*4 + 4 + 54 = 122, exactly what the file carries. If this
+        // ever fails the layout has grown a gap and the round-trip is a lie.
+        let total: usize = GHAD_LAYOUT.iter().map(|f| f.size).sum();
+        assert_eq!(total, GHAD_SIZE);
+        let mut at = 0;
+        for f in GHAD_LAYOUT {
+            assert_eq!(f.offset, at, "gap before {:#x}", f.offset);
+            at += f.size;
+        }
+    }
+
+    #[test]
+    fn rejects_a_non_save() {
+        assert_eq!(parse(b"not a save at all").unwrap_err(), SaveError::NotGdha);
+        assert_eq!(parse_payload(b"XXXX").unwrap_err(), SaveError::NotGdaa);
+    }
+
+    #[test]
+    fn trailing_bytes_are_an_error_not_a_shrug() {
+        let mut p = synth_payload("GP_BUNK", 2, 4101);
+        p.push(0);
+        assert_eq!(parse_payload(&p).unwrap_err(), SaveError::TrailingBytes(1));
+    }
+
+    #[test]
+    fn millis_format_matches_the_panel() {
+        assert_eq!(fmt_millis(324_773), "5:24.773");
+    }
+}

crates/sylpheed-formats/src/ship.rs

@@ -615,18 +615,64 @@ mod tests {
                 }
             }
         }
-        // Multi-instance coverage the capture couldn't see (vbase dedup).
-        let count = |res: &str| placed.iter().filter(|p| p.resource == res).count();
-        assert_eq!(count("e106_eng_01"), 2, "both engine nacelles placed");
-        assert_eq!(count("e303_wep_01"), 2, "both shared turrets placed");
-        // The mirrored starboard hull reflects (det < 0), the port one doesn't.
+        // ── Extras: the direction this test could not originally fail in. ──
+        // The loop above walks the CAPTURE's parts and looks each up in ours, so
+        // a static placement with no counterpart is invisible to it — which is
+        // how a resource decoded 100x too large (`e303_wep_01`, 2026-08-12) sat
+        // here unnoticed. Pin the whole **multiset** rather than the set of
+        // names: a set cannot fail on a *duplicated* instance of a resource the
+        // capture already lists, and duplication is exactly what a bad node walk
+        // produces. This subsumes the per-resource counts that used to be
+        // asserted separately below.
+        //
+        // Two deviations from the capture are expected, and only these two:
+        //   * `e303_wep_01` x2 — a turret shared with `e101`, cross-mounted here.
+        //     Absent from the capture because the F10 dump dedups by vertex base
+        //     and both instances draw the one buffer.
+        //   * `e106_eng_01` x2 — the mirrored engine nacelles, same reason.
+        let mut counts: std::collections::BTreeMap<&str, usize> = Default::default();
+        for p in &placed {
+            *counts.entry(p.resource.as_str()).or_default() += 1;
+        }
+        let expected: std::collections::BTreeMap<&str, usize> = [
+            ("e106_bdy_01", 1),
+            ("e106_bdy_02", 1),
+            ("e106_bdy_03", 1),
+            ("e106_bdy_04", 1),
+            ("e106_brg_01", 1),
+            ("e106_eng_01", 2),
+            ("e106_eng_02", 1),
+            ("e106_wep_02_01", 1),
+            ("e303_wep_01", 2),
+        ]
+        .into_iter()
+        .collect();
+        assert_eq!(
+            counts, expected,
+            "the static assembly's placement multiset drifted from the e106 ground truth"
+        );
+        // …and every name the capture lists must be in that table, so editing the
+        // table cannot quietly drop a part the runtime actually draws.
+        for want in &cap.parts {
+            assert!(
+                expected.contains_key(want.part.as_str()),
+                "{} is in the runtime capture but not in the expected multiset",
+                want.part
+            );
+        }
+        // NEITHER hull reflects: the twins' geometry is mirrored on the disc,
+        // so both placements are proper rotations. This flipped on 2026-08-12 —
+        // while both twins decoded to one buffer, `apply_twin_mirrors` had to
+        // synthesise the reflection here; a runtime capture showed the container
+        // holds both halves, and distinct anchor assignment now hands each twin
+        // its own (see docs/re/structures/xbg7-mesh.md).
         let det = |m: &[[f32; 3]; 3]| {
             m[0][0] * (m[1][1] * m[2][2] - m[1][2] * m[2][1])
                 - m[0][1] * (m[1][0] * m[2][2] - m[1][2] * m[2][0])
                 + m[0][2] * (m[1][0] * m[2][1] - m[1][1] * m[2][0])
         };
         let one = |res: &str| placed.iter().find(|p| p.resource == res).unwrap();
-        assert!(det(&one("e106_bdy_02").m) < 0.0, "starboard hull mirrored");
+        assert!(det(&one("e106_bdy_02").m) > 0.0, "starboard hull plain (mirror is in the data)");
         assert!(det(&one("e106_bdy_01").m) > 0.0, "port hull plain");
     }
 

crates/sylpheed-formats/src/ship_capture.rs

@@ -49,6 +49,33 @@ pub struct CapturedDraw {
     /// First few LOCAL vertex positions dumped with the draw (buffer order).
     /// Used to disambiguate same-vcount twins (mirrored port/starboard parts).
     pub pos: Vec<[f32; 3]>,
+    /// The draw's INDEX buffer, when the capture recorded one (`ib base=…`,
+    /// added 2026-08-13): guest base address, index count, and the min/max index
+    /// value the emulator read out of guest memory. `None` for older logs and
+    /// for auto-index draws. This is ground truth for two things the offline
+    /// decoder can only assume — where a block's index buffer lives relative to
+    /// its vertex buffer, and how much of the vertex pool a draw really covers.
+    pub ib: Option<CapturedIndexBuffer>,
+}
+
+/// The index buffer a captured draw used. See [`CapturedDraw::ib`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct CapturedIndexBuffer {
+    /// Guest base address of the index data.
+    pub ibase: u32,
+    /// Number of indices the draw issued (== `VGT_DRAW_INITIATOR.num_indices`).
+    pub icount: u32,
+    /// Lowest index value in the buffer.
+    pub imin: u32,
+    /// Highest index value in the buffer — with `vcount` this says whether the
+    /// draw covers its whole vertex pool or only a sub-range.
+    pub imax: u32,
+    /// The first indices, verbatim (the capture prints up to 24). Byte-level
+    /// ground truth for the offline index decode: a matched block's decoded
+    /// index prefix must equal this run.
+    pub head: [u32; 24],
+    /// How many of `head` the capture actually carried.
+    pub head_len: u8,
 }
 
 /// A ship part to match against the capture. `part` is the **base** part name
@@ -100,13 +127,16 @@ pub fn parse_capture(text: &str) -> Vec<CapturedDraw> {
     let mut vcount = 0u32;
     let mut pos: Vec<[f32; 3]> = Vec::new();
     let mut consts: Vec<(usize, [f64; 4])> = Vec::new();
+    let mut ib: Option<CapturedIndexBuffer> = None;
 
     let flush = |vbase: u32,
                  vcount: u32,
                  pos: &mut Vec<[f32; 3]>,
+                 ib: &mut Option<CapturedIndexBuffer>,
                  consts: &[(usize, [f64; 4])],
                  out: &mut Vec<CapturedDraw>| {
         let pos = std::mem::take(pos);
+        let ib = ib.take();
         if vbase == 0 {
             return;
         }
@@ -115,18 +145,47 @@ pub fn parse_capture(text: &str) -> Vec<CapturedDraw> {
             return; // no WorldView for this draw — skip it
         };
         if let Some((r, t)) = normalize_wvp([c0, c1, c2]) {
-            out.push(CapturedDraw { vbase, vcount, r, t, pos });
+            out.push(CapturedDraw { vbase, vcount, r, t, pos, ib });
         }
     };
 
     for line in text.lines() {
         let l = line.trim();
         if let Some(rest) = l.strip_prefix("DRAW ") {
-            flush(vbase, vcount, &mut pos, &consts, &mut out);
+            flush(vbase, vcount, &mut pos, &mut ib, &consts, &mut out);
             consts.clear();
             let f = |k: &str| rest.split_whitespace().find_map(|t| t.strip_prefix(k));
             vbase = f("vbase=0x").and_then(|s| u32::from_str_radix(s, 16).ok()).unwrap_or(0);
             vcount = f("vcount=").and_then(|s| s.parse().ok()).unwrap_or(0);
+        } else if let Some(rest) = l.strip_prefix("ib base=0x") {
+            // `ib base=0x… count=N fmt=u16 endian=E len=L delta_vb=D min=a max=b idx: …`
+            let f = |k: &str| rest.split_whitespace().find_map(|t| t.strip_prefix(k));
+            let base = rest
+                .split_whitespace()
+                .next()
+                .and_then(|s| u32::from_str_radix(s, 16).ok());
+            if let (Some(ibase), Some(icount)) = (base, f("count=").and_then(|s| s.parse().ok())) {
+                let mut head = [0u32; 24];
+                let mut head_len = 0u8;
+                if let Some((_, list)) = l.split_once("idx:") {
+                    for tok in list.split_whitespace() {
+                        let Ok(v) = tok.parse::<u32>() else { break };
+                        if head_len as usize >= head.len() {
+                            break;
+                        }
+                        head[head_len as usize] = v;
+                        head_len += 1;
+                    }
+                }
+                ib = Some(CapturedIndexBuffer {
+                    ibase,
+                    icount,
+                    imin: f("min=").and_then(|s| s.parse().ok()).unwrap_or(0),
+                    imax: f("max=").and_then(|s| s.parse().ok()).unwrap_or(0),
+                    head,
+                    head_len,
+                });
+            }
         } else if l.starts_with("pos:") || l.starts_with("positions:") {
             pos = parse_pos_line(l, 8);
         } else if l.starts_with("vsconst") {
@@ -147,7 +206,7 @@ pub fn parse_capture(text: &str) -> Vec<CapturedDraw> {
             }
         }
     }
-    flush(vbase, vcount, &mut pos, &consts, &mut out);
+    flush(vbase, vcount, &mut pos, &mut ib, &consts, &mut out);
     out
 }
 
@@ -242,7 +301,9 @@ pub fn parse_drawlog(text: &str) -> Vec<CapturedDraw> {
         let get = |i: usize| consts.iter().find(|(k, _)| *k == i).map(|(_, v)| *v);
         let (Some(c0), Some(c1), Some(c2)) = (get(0), get(1), get(2)) else { return };
         if let Some((r, t)) = normalize_wvp([c0, c1, c2]) {
-            out.push(CapturedDraw { vbase: base, vcount: size / stride, r, t, pos });
+            // The draw-logger format carries an index base too, but it de-dups
+            // by vertex declaration, so it never lines up per part — left None.
+            out.push(CapturedDraw { vbase: base, vcount: size / stride, r, t, pos, ib: None });
         }
     };
 
@@ -717,10 +778,17 @@ mod tests {
         assert_eq!(e106.reference, "e106_bdy_04");
         assert_eq!(e106.parts.len(), 8, "all 8 e106 parts placed");
         let get = |p: &str| e106.parts.iter().find(|x| x.part == p).unwrap();
-        // Port/starboard hull pair: X = ∓264, the starboard copy mirrored.
+        // Port/starboard hull pair: X = ∓264, **both plain**. The mirror is
+        // baked into the disc data, not into the placement: a runtime capture
+        // shows the container carrying two 119-vertex buffers whose contents are
+        // exact X-reflections, each drawn from its own address (see
+        // docs/re/structures/xbg7-mesh.md). Until 2026-08-12 both twins decoded
+        // to ONE buffer and this row carried diag(-1,1,1) to compensate; with
+        // distinct anchor assignment they decode to their own, and re-emitting
+        // from the capture produces identity here.
         assert!((get("e106_bdy_01").t[0] + 264.0).abs() < 0.1);
         assert!((get("e106_bdy_02").t[0] - 264.0).abs() < 0.1);
-        assert_eq!(get("e106_bdy_02").m[0][0], -1.0);
+        assert_eq!(get("e106_bdy_02").m[0][0], 1.0);
         assert_eq!(get("e106_bdy_01").m[0][0], 1.0);
         // Bridge: centreline, above and aft of the hull reference.
         let brg = get("e106_brg_01");

crates/sylpheed-formats/src/slb.rs

@@ -23,15 +23,31 @@
 /// Fixed offset of the raw XMA1 stream in a headerless `.slb` (no `RIFF`).
 pub const HEADERLESS_DATA_OFFSET: usize = 1392;
 
+/// XMA1 packet size. A headerless stream is always a whole number of these, which
+/// is how a leading stream is told apart from arbitrary bytes before a `RIFF`.
+pub const XMA1_PACKET: usize = 2048;
+
 /// Voice language for cutscene audio. Only English and Japanese voice exist on
 /// the disc (subtitles cover more languages, voice does not).
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub enum VoiceLang {
+    /// The default only because the disc's own default audio track is English;
+    /// nothing else about the code should assume it.
+    #[default]
     English,
     Japanese,
 }
 
 impl VoiceLang {
+    pub const ALL: [VoiceLang; 2] = [VoiceLang::English, VoiceLang::Japanese];
+
+    pub fn label(self) -> &'static str {
+        match self {
+            VoiceLang::English => "English",
+            VoiceLang::Japanese => "Japanese",
+        }
+    }
+
     fn code(self) -> &'static str {
         match self {
             VoiceLang::English => "eng",
@@ -63,14 +79,122 @@ pub struct VoiceClip {
     pub display: String,
 }
 
-/// Enumerate the voice/dialog clips named in a decompressed `sounds.tbl` (the
-/// IDXD in `tables.pak`). Extracts every `<lang>\{Voice,etc,Movie,Briefing}\…`
-/// path ending in `.slb` for `lang`, parsed into `(name, speaker, display)`.
-pub fn list_voice_clips(sounds_tbl: &[u8], lang: VoiceLang) -> Vec<VoiceClip> {
+/// What kind of audio a `sounds.tbl` entry names.
+///
+/// The split is the on-disc path shape, not a guess: the 36 language-independent
+/// banks sit at the table root (`BGM_###.slb`, `JNGL_00#.slb`, `Static.slb`),
+/// while everything else is under `<lang>\<dir>\`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum AudioCategory {
+    /// `BGM_###.slb` — 32 music tracks, language-independent.
+    Music,
+    /// `JNGL_00#.slb` — 3 short jingles (mission clear / fail stings).
+    Jingle,
+    /// `Static.slb` — the sound-effect bank, one 9 MB multi-wave bank.
+    Sfx,
+    /// `<lang>\Voice\` — in-mission radio chatter, by speaker.
+    Radio,
+    /// `<lang>\etc\` — the other spoken lines (cutscene dialogue, system).
+    Dialogue,
+    /// `<lang>\Movie\VOICE_<movie>.slb` — a cutscene's continuous voice track.
+    MovieVoice,
+    /// `<lang>\Briefing\BR<NN>_<MM>.slb` — mission briefing lines.
+    Briefing,
+    /// A `.slb` whose path matched no known shape.
+    Other,
+}
+
+impl AudioCategory {
+    pub const ALL: [AudioCategory; 8] = [
+        AudioCategory::Music,
+        AudioCategory::Jingle,
+        AudioCategory::Sfx,
+        AudioCategory::Radio,
+        AudioCategory::Dialogue,
+        AudioCategory::MovieVoice,
+        AudioCategory::Briefing,
+        AudioCategory::Other,
+    ];
+
+    pub fn label(self) -> &'static str {
+        match self {
+            AudioCategory::Music => "Music",
+            AudioCategory::Jingle => "Jingles",
+            AudioCategory::Sfx => "Sound effects",
+            AudioCategory::Radio => "Radio",
+            AudioCategory::Dialogue => "Dialogue",
+            AudioCategory::MovieVoice => "Movie voice",
+            AudioCategory::Briefing => "Briefing",
+            AudioCategory::Other => "Other",
+        }
+    }
+
+    /// True for the categories that are spoken lines — the set
+    /// [`list_voice_clips`] returns.
+    pub fn is_voice(self) -> bool {
+        matches!(
+            self,
+            AudioCategory::Radio
+                | AudioCategory::Dialogue
+                | AudioCategory::MovieVoice
+                | AudioCategory::Briefing
+        )
+    }
+
+    /// True when the bank is language-independent, so it appears whichever
+    /// `<lang>\sounds.tbl` is read.
+    pub fn is_shared(self) -> bool {
+        matches!(
+            self,
+            AudioCategory::Music | AudioCategory::Jingle | AudioCategory::Sfx
+        )
+    }
+
+    fn classify(name: &str) -> AudioCategory {
+        let leaf = name.rsplit('\\').next().unwrap_or(name);
+        if !name.contains('\\') {
+            return if leaf.starts_with("BGM_") {
+                AudioCategory::Music
+            } else if leaf.starts_with("JNGL_") {
+                AudioCategory::Jingle
+            } else if leaf.eq_ignore_ascii_case("Static.slb") {
+                AudioCategory::Sfx
+            } else {
+                AudioCategory::Other
+            };
+        }
+        match name.rsplit('\\').nth(1) {
+            Some("Voice") => AudioCategory::Radio,
+            Some("etc") => AudioCategory::Dialogue,
+            Some("Movie") => AudioCategory::MovieVoice,
+            Some("Briefing") => AudioCategory::Briefing,
+            _ => AudioCategory::Other,
+        }
+    }
+}
+
+/// One playable bank named in `sounds.tbl`, with the category its path implies.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AudioEntry {
+    pub clip: VoiceClip,
+    pub category: AudioCategory,
+}
+
+/// Enumerate **every** `.slb` bank named in a decompressed `sounds.tbl` (the
+/// IDXD in `tables.pak`): the language-independent music/jingle/SFX banks at
+/// the table root, plus every `<lang>\…` spoken line.
+///
+/// Measured on the retail disc: `eng\sounds.tbl` names 4 418 banks (36 shared +
+/// 2 382 Radio + 1 821 Dialogue + 101 Briefing + 78 Movie voice) and
+/// `jpn\sounds.tbl` names 5 136 (the same 36 shared + 5 100 Japanese lines).
+/// Every one of the 36 shared names resolves to a `sound.pak` TOC entry under
+/// [`crate::hash::name_hash`], which is the check that they are real banks and
+/// not stale table text.
+pub fn list_audio_entries(sounds_tbl: &[u8], lang: VoiceLang) -> Vec<AudioEntry> {
     let prefix = format!("{}\\", lang.code());
     let mut seen = std::collections::BTreeSet::new();
     let mut out = Vec::new();
-    // Scan for printable-ASCII runs; keep those that look like a voice path.
+    // Scan for printable-ASCII runs; keep those that name a `.slb`.
     let mut i = 0;
     while i < sounds_tbl.len() {
         let start = i;
@@ -79,15 +203,14 @@ pub fn list_voice_clips(sounds_tbl: &[u8], lang: VoiceLang) -> Vec<VoiceClip> {
         }
         if i - start >= 6 {
             if let Ok(s) = std::str::from_utf8(&sounds_tbl[start..i]) {
-                // Every spoken-line category, so the standalone player covers them
-                // all: in-mission radio (`\Voice\`, `\etc\`) and bound movie voices
-                // (`\Movie\`) all carry `VOICE_`; mission-briefing lines live in
-                // `\Briefing\` as `BR<NN>_<MM>.slb` (no `VOICE` in the name).
-                let is_voice = s.contains("VOICE") || s.contains("\\Briefing\\");
-                if s.starts_with(&prefix) && s.ends_with(".slb") && is_voice {
-                    if seen.insert(s.to_string()) {
-                        out.push(parse_voice_clip(s));
-                    }
+                // Take this language's entries plus the root (shared) banks; a
+                // path under the OTHER language would be a table artefact.
+                let mine = s.starts_with(&prefix) || !s.contains('\\');
+                if mine && s.ends_with(".slb") && seen.insert(s.to_string()) {
+                    out.push(AudioEntry {
+                        category: AudioCategory::classify(s),
+                        clip: parse_voice_clip(s),
+                    });
                 }
             }
         }
@@ -96,6 +219,21 @@ pub fn list_voice_clips(sounds_tbl: &[u8], lang: VoiceLang) -> Vec<VoiceClip> {
     out
 }
 
+/// Enumerate just the spoken-line clips — [`list_audio_entries`] restricted to
+/// [`AudioCategory::is_voice`].
+///
+/// In-mission radio (`\Voice\`, `\etc\`) and bound movie voices (`\Movie\`) all
+/// carry `VOICE_`; mission-briefing lines live in `\Briefing\` as
+/// `BR<NN>_<MM>.slb` and carry no `VOICE` at all, which is why the category —
+/// i.e. the directory — decides this and not the filename.
+pub fn list_voice_clips(sounds_tbl: &[u8], lang: VoiceLang) -> Vec<VoiceClip> {
+    list_audio_entries(sounds_tbl, lang)
+        .into_iter()
+        .filter(|e| e.category.is_voice())
+        .map(|e| e.clip)
+        .collect()
+}
+
 fn parse_voice_clip(name: &str) -> VoiceClip {
     // `<lang>\<cat>\VOICE_<SPK>_<NNN>.slb` or `..\VOICE_<movie>.slb`.
     let stem = name
@@ -127,20 +265,183 @@ fn parse_voice_clip(name: &str) -> VoiceClip {
 /// that yields the full track for segment banks while the clamp drops the
 /// duplicate takes for alternate-take banks. (Dynamic RE via Canary file-I/O
 /// tracing confirmed the movie→voice binding; this fixes the *decode* of `RT*`.)
+/// A bank's channel count, read from its first `RIFF` sub-wave.
+///
+/// `XMASTREAMFORMAT.Channels` sits at `RIFF + 49`. **2.12 % of banks are stereo**
+/// (170 of 8 021), and decoding one of those as mono yields a single frame and
+/// stops — the same signature already recorded for the leading segment. So the
+/// channel count has to be read, not assumed. Returns `None` when there is no
+/// `RIFF` to read it from.
+fn riff_channels(slb: &[u8]) -> Option<u8> {
+    let ri = find(slb, b"RIFF", 0)?;
+    slb.get(ri + 49).copied().filter(|c| *c == 1 || *c == 2)
+}
+
+/// The four data offsets that occur on the disc, in ascending order.
+///
+/// Measured over all 7 358 banks whose offset is *known* (they carry a `RIFF`,
+/// so the offset is forced to `first_riff % XMA1_PACKET`): no other value
+/// occurs. They are all of the form `1392 + 4k`.
+pub const DATA_OFFSET_CANDIDATES: [usize; 4] = [1392, 1468, 1600, 1728];
+
+/// How plausible a candidate offset is, judged by XMA1 packet headers alone.
+///
+/// Each 2048-byte packet opens with a big-endian header: 6 bits frame count,
+/// 15 bits frame-offset-in-bits, 3 bits metadata, 8 bits packet-skip. At the
+/// true offset those fields stay in range packet after packet; one byte off and
+/// they do not. Returns the fraction of the first `LIMIT` packets that look
+/// sane, so 1.0 is a clean stream.
+fn packet_plausibility(slb: &[u8], start: usize) -> f32 {
+    const LIMIT: usize = 24;
+    let (mut seen, mut ok, mut pos) = (0usize, 0usize, start);
+    while pos + XMA1_PACKET <= slb.len() && seen < LIMIT {
+        let h = u32::from_be_bytes([slb[pos], slb[pos + 1], slb[pos + 2], slb[pos + 3]]);
+        let frame_offset_bits = (h >> 11) & 0x7FFF;
+        let metadata = (h >> 8) & 0x7;
+        let packet_skip = h & 0xFF;
+        if frame_offset_bits as usize <= XMA1_PACKET * 8 && metadata <= 1 && packet_skip <= 8 {
+            ok += 1;
+        }
+        seen += 1;
+        pos += XMA1_PACKET;
+    }
+    if seen == 0 {
+        0.0
+    } else {
+        ok as f32 / seen as f32
+    }
+}
+
+/// The data offset implied by the bank's `seek` chunk, if it has one.
+///
+/// A bank's `seek` chunk lands on a packet boundary, so `seek_pos % XMA1_PACKET`
+/// *is* the data offset. Measured on the 6 033 labelled banks that have a
+/// `seek` before their first `RIFF`: **6 031 agree (99.97 %)**, 2 disagree.
+/// This is structural rather than statistical, which is why it is tried first.
+fn seek_chunk_offset(slb: &[u8]) -> Option<usize> {
+    let pos = find(slb, b"seek", 0)?;
+    let residue = pos % XMA1_PACKET;
+    DATA_OFFSET_CANDIDATES.contains(&residue).then_some(residue)
+}
+
+/// Recover a bank's data offset when there is no `RIFF` to derive it from.
+///
+/// Two independent signals, tried in order of how well each is evidenced:
+///
+/// 1. **the `seek` chunk's position** mod the packet size — 99.97 % on the
+///    labelled set, and structural rather than statistical;
+/// 2. **packet-header plausibility** — pick the candidate whose XMA1 headers
+///    stay in range over the first 24 packets. Alone this is 99.62 %, and all
+///    28 of its misses are ties rather than wrong unique winners.
+///
+/// Together, on the 7 358 banks where the answer *is* known from the `RIFF`
+/// position: **7 354 correct (99.95 %)**. The `seek` residue resolves 26 of the
+/// scan's 28 ties correctly and none of them wrongly; the other 2 have no
+/// usable `seek`. Falls back to [`HEADERLESS_DATA_OFFSET`] when neither signal
+/// decides.
+pub fn scan_data_offset(slb: &[u8]) -> usize {
+    if let Some(off) = seek_chunk_offset(slb) {
+        return off;
+    }
+    let mut best = (HEADERLESS_DATA_OFFSET, -1.0f32);
+    let mut tied = false;
+    for &c in &DATA_OFFSET_CANDIDATES {
+        if c >= slb.len() {
+            continue;
+        }
+        let score = packet_plausibility(slb, c);
+        if score > best.1 {
+            best = (c, score);
+            tied = false;
+        } else if (score - best.1).abs() < f32::EPSILON {
+            tied = true;
+        }
+    }
+    if tied {
+        HEADERLESS_DATA_OFFSET
+    } else {
+        best.0
+    }
+}
+
+/// Where a bank's leading headerless packet stream starts.
+///
+/// The stream is a whole number of 2048-byte XMA1 packets ending at the first
+/// `RIFF`, so its start is simply `first_riff % XMA1_PACKET`. Disc-wide that
+/// lands on 1392, 1468, 1600 or 1728 depending on language and subdirectory —
+/// [`HEADERLESS_DATA_OFFSET`] is just the `<lang>\etc\` case. Measured over a
+/// 140-bank sample, deriving the offset instead of assuming 1392 recovers a
+/// median **70×** more decoded audio and never less except in one bank where
+/// neither offset decodes (see `docs/re/structures/slb-data-offset.md`).
+pub fn leading_data_offset(first_riff: usize) -> usize {
+    first_riff % XMA1_PACKET
+}
+
 pub fn to_xma_riffs(slb: &[u8]) -> Vec<Vec<u8>> {
     let mut out = Vec::new();
-    if find(slb, b"RIFF", 0).is_none() {
-        // Headerless single-stream bank.
-        if let Some(data) = slb.get(HEADERLESS_DATA_OFFSET..) {
+    let first_riff = find(slb, b"RIFF", 0);
+    if first_riff.is_none() {
+        // Headerless single-stream bank. Two things here were wrong, and the
+        // corrections are measured (docs/re/structures/slb-data-offset.md):
+        //
+        //   * the offset is not the constant — with no `RIFF` to derive it from,
+        //     scan the four candidates by packet plausibility;
+        //   * the stream is **mono**. At two channels a 48-bank sample yielded
+        //     0..4 816 bytes; at one, 180 000..380 000. There was not one bank
+        //     where the old stereo/1392 pair beat the scanned mono pair, and the
+        //     median gain was 184x.
+        let start = scan_data_offset(slb);
+        if let Some(data) = slb.get(start..) {
             if !data.is_empty() {
-                out.push(build_riff(&synth_xma1_fmt(2, 2, 48000), data));
+                out.push(build_riff(&synth_xma1_fmt(1, 0, 48000), data));
             }
         }
         return out;
     }
+    // HYBRID banks: a headerless packet stream followed by RIFF sub-waves, two
+    // SEQUENTIAL SEGMENTS of one clip. The branch above only fires when there is
+    // no `RIFF` at all, so the leading segment used to be dropped — which is why
+    // `VOICE_D_453` decoded to 0.14 s: its line is in that segment and only the
+    // trailing fragment survived.
+    //
+    // The boundary is arithmetic, not a magic: XMA1 packets are 2048 bytes, so a
+    // leading stream is a whole number of packets ending at the first `RIFF`.
+    // Its START is therefore `first_riff % XMA1_PACKET` — **not** the constant
+    // `HEADERLESS_DATA_OFFSET`, which is only the value that offset happens to
+    // take in `<lang>\etc\`. Disc-wide it takes four values (1392, 1468, 1600,
+    // 1728), varying by language and subdirectory, and assuming 1392 starts the
+    // decode mid-packet everywhere else. See docs/re/structures/slb-data-offset.md.
+    // It decodes as **mono** — at two channels every bank yields exactly 1792
+    // bytes, one frame, whatever its size.
+    //
+    // An earlier version of this was withdrawn for two good reasons, both now
+    // answered: it recovered no audio (it used the stereo format), and it
+    // matched 1524 of the 8021 RIFF-bearing entries. The byte-level reach is
+    // still 1524, but the *audible* reach is not: across the 84 movie-bound
+    // banks the segment adds >1 s to exactly **7** — the `hokyu_*_H` tankers
+    // 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);
+        if ri > start {
+            if let Some(data) = slb.get(start..ri) {
+                if data.iter().any(|b| *b != 0) {
+                    // Channels come from the bank's own `fmt `, not a constant:
+                    // 170 of 8 021 banks are stereo and decode to one frame if
+                    // forced to mono.
+                    let ch = riff_channels(slb).unwrap_or(1);
+                    let mask = if ch == 2 { 2 } else { 0 };
+                    out.push(build_riff(&synth_xma1_fmt(ch, mask, 48000), data));
+                }
+            }
+        }
+    }
     let mut pos = 0usize;
     while let Some(ri) = find(slb, b"RIFF", pos) {
-        // Parse this sub-wave's fmt + data (declared size is honest per sub-wave).
+        // Parse this sub-wave's fmt + data. The declared `data` size is an
+        // UPPER bound, not an exact one: 5 296 of 7 586 banks declare more than
+        // the entry holds and none declares exactly what it holds, so the clamp
+        // below is load-bearing (docs/re/structures/slb-data-offset.md).
         let Some(fi) = find(slb, b"fmt ", ri) else { break };
         let Some(fsz) = le32(slb, fi + 4) else { break };
         let Some(fmt_end) = fi.checked_add(8).and_then(|v| v.checked_add(fsz as usize)) else {
@@ -174,10 +475,12 @@ pub fn to_xma_riff(slb: &[u8]) -> Option<Vec<u8>> {
     if let Some(ri) = find(slb, b"RIFF", 0) {
         // RIFF layout: a `.slb` is an XACT bank of one or more sub-waves, each
         // `[seek][RIFF: fmt + Dmmy pad + data][declared_size XMA bytes]`. Take the
-        // FIRST sub-wave, bounded by its **declared `data` size** (which is
-        // honest per sub-wave). Decoding to end-of-file instead would append the
-        // later sub-waves — for multi-take story movies those are ALTERNATE takes,
-        // which is what made S10–S16 play the wrong audio.
+        // FIRST sub-wave, bounded by its **declared `data` size** — which is an
+        // upper bound only (69.8 % of banks over-declare it, so the clamp
+        // matters), but still the right boundary to cut at. Decoding to
+        // end-of-file instead would append the later sub-waves — for multi-take
+        // story movies those are ALTERNATE takes, which is what made S10–S16
+        // play the wrong audio.
         let fi = find(slb, b"fmt ", ri)?;
         let fsz = le32(slb, fi + 4)? as usize;
         let fmt_end = fi.checked_add(8)?.checked_add(fsz)?;
@@ -232,6 +535,28 @@ pub fn to_xma_riff_best(slb: &[u8]) -> Option<Vec<u8>> {
     (!data.is_empty()).then(|| build_riff(&synth_xma1_fmt(2, 2, 48000), data))
 }
 
+/// Wrap a run of **raw XMA1 packets** as a standalone, decodable `RIFF/WAVE`.
+///
+/// For a bank with no internal delimiters — `Static.slb` is a packed run of whole
+/// 2048-byte packets with no `RIFF`, no `seek` and no `WAVE` — a wave is defined
+/// *only* by `(offset, packet count)`, both of which come from the running game
+/// (`--xma_param_probe`). There is nothing in the file to parse, so the header
+/// has to be synthesized, and that is the step worth doing exactly once, here,
+/// rather than in each consumer.
+///
+/// `packets` must be a whole number of [`XMA1_PACKET`] bytes; anything else is a
+/// short read and produces a stream the decoder will run off the end of.
+/// The `channel_mask` follows the same convention as the rest of this module:
+/// `1` for mono, `2` for stereo.
+///
+/// The three menu cues in `docs/re/menu-audio-cues.md` are
+/// `(0x1ec0, 4)` d-pad move, `(0x0ec0, 2)` Ⓑ back and `(0x5d6c0, 6)` Ⓐ confirm,
+/// all mono 48 kHz.
+pub fn xma1_wave_riff(packets: &[u8], channels: u8, rate: u32) -> Vec<u8> {
+    let mask = if channels == 1 { 1 } else { 2 };
+    build_riff(&synth_xma1_fmt(channels, mask, rate), packets)
+}
+
 /// A minimal `fmt ` chunk carrying an XMA1 `XMAWAVEFORMAT` (one stream).
 fn synth_xma1_fmt(channels: u8, channel_mask: u16, rate: u32) -> Vec<u8> {
     let mut fmt = Vec::with_capacity(40);
@@ -356,6 +681,56 @@ mod tests {
         );
     }
 
+    #[test]
+    fn list_audio_entries_categorises_root_banks_and_keeps_them_language_shared() {
+        // The three root banks carry no language component, so BOTH sounds.tbl
+        // files name them; a language filter that only accepted `<lang>\` would
+        // silently drop all the music, which is what it used to do.
+        let mut tbl = Vec::new();
+        for s in [
+            "BGM_001.slb",
+            "JNGL_002.slb",
+            "Static.slb",
+            "eng\\Voice\\VOICE_ADAN_010.slb",
+            "eng\\etc\\VOICE_D_450.slb",
+            "eng\\Movie\\VOICE_S13A.slb",
+            "eng\\Briefing\\BR01_01.slb",
+        ] {
+            tbl.extend_from_slice(s.as_bytes());
+            tbl.push(0);
+        }
+        let by = |lang| {
+            list_audio_entries(&tbl, lang)
+                .into_iter()
+                .map(|e| (e.clip.name, e.category))
+                .collect::<Vec<_>>()
+        };
+        let eng = by(VoiceLang::English);
+        let want = [
+            ("BGM_001.slb", AudioCategory::Music),
+            ("JNGL_002.slb", AudioCategory::Jingle),
+            ("Static.slb", AudioCategory::Sfx),
+            ("eng\\Voice\\VOICE_ADAN_010.slb", AudioCategory::Radio),
+            ("eng\\etc\\VOICE_D_450.slb", AudioCategory::Dialogue),
+            ("eng\\Movie\\VOICE_S13A.slb", AudioCategory::MovieVoice),
+            ("eng\\Briefing\\BR01_01.slb", AudioCategory::Briefing),
+        ];
+        assert_eq!(eng.len(), want.len());
+        for (n, c) in want {
+            assert!(
+                eng.iter().any(|(en, ec)| en == n && *ec == c),
+                "{n} not categorised as {c:?}"
+            );
+        }
+        // Reading the Japanese table yields the shared banks and none of the
+        // English lines.
+        let jpn = by(VoiceLang::Japanese);
+        assert_eq!(jpn.len(), 3, "only the shared banks: {jpn:?}");
+        assert!(jpn.iter().all(|(_, c)| c.is_shared()));
+        // And the voice view is exactly the non-shared half.
+        assert_eq!(list_voice_clips(&tbl, VoiceLang::English).len(), 4);
+    }
+
     #[test]
     fn rebuilds_riff_from_headerless() {
         let mut slb = vec![0u8; HEADERLESS_DATA_OFFSET];

crates/sylpheed-formats/src/t8ad.rs

@@ -1,20 +1,28 @@
 //! `T8aD` — the game's 2D UI/HUD texture format.
 //!
-//! A 32bpp **A8R8G8B8** (Xbox byte order) surface stored as **256×256 raster
-//! tiles in row-major order** — each tile prefixed by a 16-byte tile header, edge
-//! tiles clipped to the image bounds. Fully reversed 2026-07-17 from the file
-//! header and verified against the running game (title screen).
+//! A 32bpp **A8R8G8B8** (Xbox byte order) surface stored as a list of
+//! **arbitrary sub-rectangles**, each with its own destination origin and size.
+//! Reversed 2026-07-17 (verified against the running game's title screen) and
+//! **corrected 2026-08-11**, when the per-tile header turned out to carry the
+//! rectangle's placement rather than being opaque flags.
 //!
 //! ```text
 //! 0x00  4         Magic "T8aD"
-//! 0x14  4         width  (BE u32)
+//! 0x14  4         width  (BE u32)          the full surface
 //! 0x18  4         height (BE u32)
-//! 0x1c  4         tile count (BE u32) = ceil(w/256) * ceil(h/256)
-//! 0x2c  tiles*4   offset table: absolute byte offset of each row-major tile
-//! <off>  16       per-tile header (flags + tile w/h), then:
-//! <off+16>        tile_w * tile_h * 4 bytes of A8R8G8B8 pixels, row-major
+//! 0x1c  4         rectangle count (BE u32) — NOT ceil(w/256)*ceil(h/256)
+//! 0x2c  count*4   offset table: absolute byte offset of each rectangle
+//! <off>  16       rectangle header, four BE u32: dst X, dst Y, width, height
+//! <off+16>        width * height * 4 bytes of A8R8G8B8 pixels, row-major
 //! ```
 //!
+//! Most surfaces happen to be stored as full-width 256-tall bands, which is why
+//! treating the file as a 256×256 grid decoded 96 % of the disc correctly. It is
+//! not the model, though: a dialogue strip declares 524×63 and stores **one**
+//! 173×25 rectangle at (175,20), and `pdmes010` stores two — (59,6,256,54) and
+//! (315,6,149,54), the second beginning exactly `16 + 256*54*4` bytes after the
+//! first. Anything the rectangles do not cover stays transparent.
+//!
 //! Surfaces ≤256px wide are a single tile column, so the first tile's pixels sit
 //! at `44 + tiles*4 + 16 = 64` — which is why the old "type→header size 64/84/…"
 //! rule (header = 44 + tiles*20) happened to decode small textures correctly: for
@@ -30,6 +38,18 @@ pub struct T8adImage {
     pub width: u32,
     pub height: u32,
     pub rgba: Vec<u8>,
+    /// The header word at `+0x04`. A flag word; **bit `0x02`** is a candidate
+    /// blend selector — it separates the title's effect sprites from its ordinary
+    /// ones exactly, and disc-wide it toggles independently of the rest of the
+    /// word in 27.1 % of 19 216 sprites. See
+    /// `docs/re/structures/ui-paint-order-key.md`.
+    ///
+    /// ⚠️ **Additive was tested and REFUTED.** Blending bit-`0x02` sprites
+    /// additively moved every measure against the title capture the wrong way:
+    /// whole-frame mean diff +0.55 → +1.04, swoosh-band mean +1.83 → +3.98, band
+    /// edge-correlation 0.6971 → 0.5578. The bit is real and independent, but it
+    /// does not select an additive blend. Carried, not acted on.
+    pub flags: u32,
 }
 
 /// Whether `bytes` starts with the T8aD magic.
@@ -43,18 +63,11 @@ fn be32(b: &[u8], off: usize) -> u32 {
 }
 
 /// Side of the square storage tile, in texels, and the per-tile header size.
-const TILE: usize = 256;
-const TILE_HDR: usize = 16;
+/// Bytes of per-rectangle header before its pixels: dst X, dst Y, w, h.
+const RECT_HDR: usize = 16;
 
 /// Decode a T8aD surface from a slice whose first bytes ARE the magic. Returns
-/// `None` for non-T8aD input or a variant we can't decode as RGBA (never guesses).
-///
-/// Layout (reversed from the header + verified against the running game):
-/// a 44-byte base header, then a `tiles`-entry big-endian u32 **offset table** at
-/// `0x2c`, where `tiles` = the field at `0x1c` = `ceil(w/256) * ceil(h/256)`.
-/// Each entry is the absolute byte offset of a **row-major** 256×256 tile; every
-/// tile is a 16-byte tile header followed by `tile_w*tile_h*4` A8R8G8B8 pixels,
-/// edge tiles clipped to the image bounds.
+/// `None` if any rectangle fails to fit the surface or the file — never guesses.
 pub fn parse(bytes: &[u8]) -> Option<T8adImage> {
     if !is_t8ad(bytes) || bytes.len() < 0x40 {
         return None;
@@ -64,45 +77,50 @@ pub fn parse(bytes: &[u8]) -> Option<T8adImage> {
     if !(1..=4096).contains(&width) || !(1..=4096).contains(&height) {
         return None;
     }
-    let tiles = be32(bytes, 0x1c) as usize;
-    let cols = width.div_ceil(TILE);
-    let rows = height.div_ceil(TILE);
-    // The field at 0x1c must be the tile count; otherwise it's a variant we don't
-    // decode (e.g. DXT / palettized) — defer rather than misdecode.
-    if tiles == 0 || tiles != cols * rows {
+    let rects = be32(bytes, 0x1c) as usize;
+    if rects == 0 || rects > 4096 {
         return None;
     }
     const TABLE: usize = 0x2c;
-    if bytes.len() < TABLE + tiles * 4 {
+    if bytes.len() < TABLE + rects * 4 {
         return None;
     }
 
+    // Anything no rectangle covers stays transparent.
     let mut rgba = vec![0u8; width * height * 4];
-    for ty in 0..rows {
-        for tx in 0..cols {
-            let tile = ty * cols + tx;
-            let pixels = be32(bytes, TABLE + tile * 4) as usize + TILE_HDR;
-            let tw = TILE.min(width - tx * TILE);
-            let th = TILE.min(height - ty * TILE);
-            if pixels + tw * th * 4 > bytes.len() {
-                return None; // truncated / not the layout we expect
-            }
-            for row in 0..th {
-                let mut s = pixels + row * tw * 4;
-                let mut d = ((ty * TILE + row) * width + tx * TILE) * 4;
-                for _ in 0..tw {
-                    // A8R8G8B8 → RGBA8.
-                    rgba[d] = bytes[s + 1];
-                    rgba[d + 1] = bytes[s + 2];
-                    rgba[d + 2] = bytes[s + 3];
-                    rgba[d + 3] = bytes[s];
-                    s += 4;
-                    d += 4;
-                }
+    for r in 0..rects {
+        let at = be32(bytes, TABLE + r * 4) as usize;
+        if at + RECT_HDR > bytes.len() {
+            return None;
+        }
+        let dx = be32(bytes, at) as usize;
+        let dy = be32(bytes, at + 4) as usize;
+        let rw = be32(bytes, at + 8) as usize;
+        let rh = be32(bytes, at + 12) as usize;
+        // Never guess: a rectangle must fit the surface and its pixels the file.
+        if rw == 0 || rh == 0 || dx + rw > width || dy + rh > height {
+            return None;
+        }
+        let pixels = at + RECT_HDR;
+        if pixels + rw * rh * 4 > bytes.len() {
+            return None;
+        }
+        for row in 0..rh {
+            let mut s = pixels + row * rw * 4;
+            let mut d = ((dy + row) * width + dx) * 4;
+            for _ in 0..rw {
+                // A8R8G8B8 → RGBA8.
+                rgba[d] = bytes[s + 1];
+                rgba[d + 1] = bytes[s + 2];
+                rgba[d + 2] = bytes[s + 3];
+                rgba[d + 3] = bytes[s];
+                s += 4;
+                d += 4;
             }
         }
     }
     Some(T8adImage {
+        flags: be32(bytes, 4),
         width: width as u32,
         height: height as u32,
         rgba,
@@ -123,7 +141,11 @@ mod tests {
         b[0x18..0x1c].copy_from_slice(&h.to_be_bytes());
         b[0x1c..0x20].copy_from_slice(&1u32.to_be_bytes()); // 1 tile
         b.extend_from_slice(&0x30u32.to_be_bytes()); // offset table: tile 0 @ 0x30
-        b.extend_from_slice(&[0u8; 16]); // 16-byte tile header → pixels at 0x40
+        // rectangle header: dst (0,0), size w×h
+        b.extend_from_slice(&0u32.to_be_bytes());
+        b.extend_from_slice(&0u32.to_be_bytes());
+        b.extend_from_slice(&w.to_be_bytes());
+        b.extend_from_slice(&h.to_be_bytes());
         for i in 0..(w * h) {
             b.extend_from_slice(&[(i & 0xff) as u8, 0x24, 0x63, 0xB2]); // A, R, G, B
         }
@@ -143,8 +165,8 @@ mod tests {
     }
 
     #[test]
-    fn assembles_row_major_tiles_via_offset_table() {
-        // 300×1 → 2 tiles: (0,0)=256×1 red, (1,0)=44×1 blue, each +16-byte header.
+    fn assembles_rectangles_via_offset_table() {
+        // 300×1 → 2 rectangles: (0,0) 256×1 red, then (256,0) 44×1 blue.
         let (w, h): (u32, u32) = (300, 1);
         let mut b = vec![0u8; 0x2c];
         b[0..4].copy_from_slice(&T8AD_MAGIC);
@@ -155,9 +177,9 @@ mod tests {
         let off1 = off0 + 16 + 256 * 4; // tile-0 header + its 256 pixels
         b.extend_from_slice(&(off0 as u32).to_be_bytes());
         b.extend_from_slice(&(off1 as u32).to_be_bytes());
-        b.extend_from_slice(&[0u8; 16]);
+        for v in [0u32, 0, 256, 1] { b.extend_from_slice(&v.to_be_bytes()) } // dst(0,0) 256×1
         b.extend_from_slice(&[0xFF, 0xFF, 0, 0].repeat(256)); // A,R,G,B red
-        b.extend_from_slice(&[0u8; 16]);
+        for v in [256u32, 0, 44, 1] { b.extend_from_slice(&v.to_be_bytes()) } // dst(256,0) 44×1
         b.extend_from_slice(&[0xFF, 0, 0, 0xFF].repeat(44)); // A,R,G,B blue
         let img = parse(&b).expect("decodes");
         assert_eq!((img.width, img.height), (300, 1));
@@ -166,10 +188,11 @@ mod tests {
     }
 
     #[test]
-    fn rejects_wrong_tilecount_and_short() {
-        // tile-count field that isn't ceil(w/256)*ceil(h/256) → None
+    fn rejects_out_of_range_rect_and_short() {
+        // a rectangle that does not fit the declared surface → None, never guess
         let mut b = synth(2, 2);
-        b[0x1c..0x20].copy_from_slice(&7u32.to_be_bytes());
+        let at = 0x2c + 4;
+        b[at + 8..at + 12].copy_from_slice(&99u32.to_be_bytes()); // width 99 > 2
         assert!(parse(&b).is_none());
         // truncated pixel data → None
         let b = synth(64, 64);

crates/sylpheed-formats/src/texture.rs

@@ -52,7 +52,10 @@ pub enum TextureError {
     #[error("No TX2D texture resource found in XPR2 file")]
     NoTextureFound,
 
-    #[error("Unsupported texture format: 0x{0:02X}")]
+    #[error("Unsupported XPR container '{0}' (this reader handles XPR2 only)")]
+    UnsupportedContainer(String),
+
+    #[error("Unsupported texture format: {} (0x{:02X})", gpu_format_name(*.0), .0)]
     UnsupportedFormat(u8),
 
     #[error("Buffer too small: need {needed} bytes, have {have}")]
@@ -125,6 +128,159 @@ impl X360TextureFormat {
     pub fn block_size(&self) -> usize {
         if self.is_block_compressed() { 4 } else { 1 }
     }
+
+    /// Canary's canonical `k_…` GPUTEXTUREFORMAT name (e.g. `k_DXT1`).
+    pub fn gpu_name(&self) -> &'static str {
+        gpu_format_name(*self as u8)
+    }
+
+    /// The full Canary format descriptor (bpp, block dims, compression).
+    pub fn desc(&self) -> &'static GpuFormatDesc {
+        // Every enum value has a valid entry in the 0..=63 table.
+        &GPU_FORMATS[*self as usize]
+    }
+}
+
+// ── GPUTEXTUREFORMAT reference table (ported from xenia-canary) ─────────────────
+
+/// One row of Xenia's GPU texture-format table. `bpp` is bits per pixel; for a
+/// block-compressed format one "block" covers `block_w × block_h` texels.
+/// Source: xenia-canary `src/xenia/gpu/xenos.h` (`enum class TextureFormat`) +
+/// `src/xenia/gpu/texture_info_formats.inl` (`FORMAT_INFO(...)`).
+#[derive(Debug, Clone, Copy)]
+pub struct GpuFormatDesc {
+    /// 6-bit GPUTEXTUREFORMAT code (GPUFC dword_1 bits[5:0]).
+    pub code: u8,
+    /// Canary's canonical name, e.g. `k_8_8_8_8`, `k_DXT4_5`.
+    pub name: &'static str,
+    pub block_w: u8,
+    pub block_h: u8,
+    pub bpp: u16,
+    pub compressed: bool,
+}
+
+impl GpuFormatDesc {
+    /// Bytes per block (or per pixel when `block_w == block_h == 1`).
+    pub fn bytes_per_block(&self) -> usize {
+        self.block_w as usize * self.block_h as usize * self.bpp as usize / 8
+    }
+}
+
+const fn d(
+    code: u8,
+    name: &'static str,
+    block_w: u8,
+    block_h: u8,
+    bpp: u16,
+    compressed: bool,
+) -> GpuFormatDesc {
+    GpuFormatDesc { code, name, block_w, block_h, bpp, compressed }
+}
+
+/// The complete GPUTEXTUREFORMAT table (codes 0..=63), verbatim from
+/// xenia-canary. Lets us name/describe *any* texture format the game uses —
+/// even ones this crate can't yet decode — instead of a bare hex code.
+#[rustfmt::skip]
+pub const GPU_FORMATS: [GpuFormatDesc; 64] = [
+    d(0,  "k_1_REVERSE",                  1, 1, 1,   false),
+    d(1,  "k_1",                          1, 1, 1,   false),
+    d(2,  "k_8",                          1, 1, 8,   false),
+    d(3,  "k_1_5_5_5",                    1, 1, 16,  false),
+    d(4,  "k_5_6_5",                      1, 1, 16,  false),
+    d(5,  "k_6_5_5",                      1, 1, 16,  false),
+    d(6,  "k_8_8_8_8",                    1, 1, 32,  false),
+    d(7,  "k_2_10_10_10",                 1, 1, 32,  false),
+    d(8,  "k_8_A",                        1, 1, 8,   false),
+    d(9,  "k_8_B",                        1, 1, 8,   false),
+    d(10, "k_8_8",                        1, 1, 16,  false),
+    d(11, "k_Cr_Y1_Cb_Y0_REP",           2, 1, 16,  true),
+    d(12, "k_Y1_Cr_Y0_Cb_REP",           2, 1, 16,  true),
+    d(13, "k_16_16_EDRAM",               1, 1, 32,  false),
+    d(14, "k_8_8_8_8_A",                  1, 1, 32,  false),
+    d(15, "k_4_4_4_4",                    1, 1, 16,  false),
+    d(16, "k_10_11_11",                   1, 1, 32,  false),
+    d(17, "k_11_11_10",                   1, 1, 32,  false),
+    d(18, "k_DXT1",                       4, 4, 4,   true),
+    d(19, "k_DXT2_3",                     4, 4, 8,   true),
+    d(20, "k_DXT4_5",                     4, 4, 8,   true),
+    d(21, "k_16_16_16_16_EDRAM",          1, 1, 64,  false),
+    d(22, "k_24_8",                       1, 1, 32,  false),
+    d(23, "k_24_8_FLOAT",                 1, 1, 32,  false),
+    d(24, "k_16",                         1, 1, 16,  false),
+    d(25, "k_16_16",                      1, 1, 32,  false),
+    d(26, "k_16_16_16_16",                1, 1, 64,  false),
+    d(27, "k_16_EXPAND",                  1, 1, 16,  false),
+    d(28, "k_16_16_EXPAND",               1, 1, 32,  false),
+    d(29, "k_16_16_16_16_EXPAND",         1, 1, 64,  false),
+    d(30, "k_16_FLOAT",                   1, 1, 16,  false),
+    d(31, "k_16_16_FLOAT",                1, 1, 32,  false),
+    d(32, "k_16_16_16_16_FLOAT",          1, 1, 64,  false),
+    d(33, "k_32",                         1, 1, 32,  false),
+    d(34, "k_32_32",                      1, 1, 64,  false),
+    d(35, "k_32_32_32_32",                1, 1, 128, false),
+    d(36, "k_32_FLOAT",                   1, 1, 32,  false),
+    d(37, "k_32_32_FLOAT",                1, 1, 64,  false),
+    d(38, "k_32_32_32_32_FLOAT",          1, 1, 128, false),
+    d(39, "k_32_AS_8",                    4, 1, 8,   true),
+    d(40, "k_32_AS_8_8",                  2, 1, 16,  true),
+    d(41, "k_16_MPEG",                    1, 1, 16,  false),
+    d(42, "k_16_16_MPEG",                 1, 1, 32,  false),
+    d(43, "k_8_INTERLACED",               1, 1, 8,   false),
+    d(44, "k_32_AS_8_INTERLACED",         4, 1, 8,   true),
+    d(45, "k_32_AS_8_8_INTERLACED",       1, 1, 16,  true),
+    d(46, "k_16_INTERLACED",              1, 1, 16,  false),
+    d(47, "k_16_MPEG_INTERLACED",         1, 1, 16,  false),
+    d(48, "k_16_16_MPEG_INTERLACED",      1, 1, 32,  false),
+    d(49, "k_DXN",                        4, 4, 8,   true),
+    d(50, "k_8_8_8_8_AS_16_16_16_16",     1, 1, 32,  false),
+    d(51, "k_DXT1_AS_16_16_16_16",        4, 4, 4,   true),
+    d(52, "k_DXT2_3_AS_16_16_16_16",      4, 4, 8,   true),
+    d(53, "k_DXT4_5_AS_16_16_16_16",      4, 4, 8,   true),
+    d(54, "k_2_10_10_10_AS_16_16_16_16",  1, 1, 32,  false),
+    d(55, "k_10_11_11_AS_16_16_16_16",    1, 1, 32,  false),
+    d(56, "k_11_11_10_AS_16_16_16_16",    1, 1, 32,  false),
+    d(57, "k_32_32_32_FLOAT",             1, 1, 96,  false),
+    d(58, "k_DXT3A",                      4, 4, 4,   true),
+    d(59, "k_DXT5A",                      4, 4, 4,   true),
+    d(60, "k_CTX1",                       4, 4, 4,   true),
+    d(61, "k_DXT3A_AS_1_1_1_1",           4, 4, 4,   true),
+    d(62, "k_8_8_8_8_GAMMA_EDRAM",        1, 1, 32,  false),
+    d(63, "k_2_10_10_10_FLOAT_EDRAM",     1, 1, 32,  false),
+];
+
+/// Canary's canonical name for a 6-bit GPUTEXTUREFORMAT code, or
+/// `"unknown(NN)"` when out of the 0..=63 range.
+pub fn gpu_format_name(code: u8) -> &'static str {
+    GPU_FORMATS
+        .get(code as usize)
+        .map(|f| f.name)
+        .unwrap_or("unknown")
+}
+
+/// The full descriptor for a GPUTEXTUREFORMAT code, if in range.
+pub fn gpu_format_desc(code: u8) -> Option<&'static GpuFormatDesc> {
+    GPU_FORMATS.get(code as usize)
+}
+
+/// Identify the XPR container variant from the 4-byte magic (`XPR0`/`XPR2`/
+/// `XPR5`/…), so callers can report `XPR5` clearly instead of "bad magic".
+pub fn xpr_container_kind(bytes: &[u8]) -> Option<String> {
+    if bytes.len() >= 4 && &bytes[..3] == b"XPR" {
+        Some(String::from_utf8_lossy(&bytes[..4]).into_owned())
+    } else {
+        None
+    }
+}
+
+/// Guard the XPR2-only decode paths: turn a non-XPR2 container into a clear
+/// [`TextureError::UnsupportedContainer`] before binrw reports a generic
+/// magic mismatch. (The game also ships some `XPR5` packages, e.g. Common.xpr.)
+fn ensure_xpr2(bytes: &[u8]) -> Result<(), TextureError> {
+    match xpr_container_kind(bytes) {
+        Some(k) if k == "XPR2" => Ok(()),
+        Some(k) => Err(TextureError::UnsupportedContainer(k)),
+        None => Ok(()), // let the normal magic check produce BadMagic
+    }
 }
 
 // ── XPR2 container format ─────────────────────────────────────────────────────
@@ -261,6 +417,7 @@ impl X360Texture {
     /// Decode the `want`-th texture resource (`TX2D` / `TXCM`, directory order).
     pub fn from_xpr2_index(bytes: &[u8], want: usize) -> Result<Self, TextureError> {
         use std::io::Cursor;
+        ensure_xpr2(bytes)?;
         let mut cur = Cursor::new(bytes);
 
         // Parse header — validates "XPR2" magic, reads 3 × u32 (total 16 bytes)
@@ -353,6 +510,7 @@ impl X360Texture {
     /// `BG_Acheron`: `data_size == 6 × 0x400000` and all 6 faces decode cleanly.)
     pub fn cube_faces_from_xpr2(bytes: &[u8]) -> Result<Option<Cubemap>, TextureError> {
         use std::io::Cursor;
+        ensure_xpr2(bytes)?;
         let mut cur = Cursor::new(bytes);
         let header = Xpr2Header::read(&mut cur)?;
         let mut entries = Vec::new();
@@ -640,6 +798,25 @@ fn compact_bits(mut x: u32) -> u32 {
 mod tests {
     use super::*;
 
+    #[test]
+    fn gpu_format_table_is_index_aligned() {
+        // The hand-transcribed Canary table must stay index==code for all 64.
+        for (i, f) in GPU_FORMATS.iter().enumerate() {
+            assert_eq!(f.code as usize, i, "GPU_FORMATS[{i}] has code {}", f.code);
+        }
+        // Spot-check the formats the game actually uses (from xenos.h + .inl).
+        assert_eq!(gpu_format_name(6), "k_8_8_8_8");
+        assert_eq!(gpu_format_name(18), "k_DXT1");
+        assert_eq!(gpu_format_name(59), "k_DXT5A");
+        assert_eq!(gpu_format_name(200), "unknown");
+        // Every decodable enum variant resolves to a compressed/uncompressed
+        // descriptor consistent with its own is_block_compressed().
+        for code in [6u8, 7, 18, 19, 20, 49, 59] {
+            let fmt = X360TextureFormat::from_u8(code).unwrap();
+            assert_eq!(fmt.desc().compressed, fmt.is_block_compressed(), "code {code}");
+        }
+    }
+
     #[test]
     fn morton_decode_corners() {
         assert_eq!(morton_decode(0), (0, 0));

crates/sylpheed-formats/src/unit_layout.rs

@@ -0,0 +1,105 @@
+//! The runtime layout of a unit / vessel definition object.
+//!
+//! The game parses an [`crate::idxd`] record into a fixed 880-byte object whose
+//! field offsets are **not** guessable from the disc data: the record is a
+//! reflective key/value pool, and the loader assigns each key to a member by
+//! name. This table is that assignment, read out of the loader itself
+//! (`sub_82341A20` — every key is built as `addi r4, r30, -N`, so the field name
+//! for each store is a string in the executable image), and verified against
+//! objects dumped from a running mission: **406 values agree with the disc
+//! records, 0 disagree**, over 11 objects covering both schemas.
+//!
+//! Why a reimplementation wants it:
+//!
+//! - it names the field behind every word of a live definition object, so a
+//!   memory snapshot can be read directly;
+//! - it says which fields a record leaves **defaulted**, and what the loader
+//!   leaves there — the float accessor returns `0.0` on a pool miss;
+//! - it carries two conventions that are invisible on disc: **angles are degrees
+//!   in the data and radians in the object**, and **`Size_Y` takes `Size_X`**
+//!   when omitted.
+//!
+//! See `docs/re/live-unit-definitions.md` for the derivation and the measured
+//! default values.
+
+/// How a field is stored in the definition object.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Kind {
+    /// IEEE-754 single, big-endian.
+    F32,
+    /// Pointer to a string.
+    Str,
+    /// 32-bit word (bool / enum / count / id).
+    Word,
+}
+
+/// One field of the definition object.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Field {
+    /// Byte offset from the start of the object.
+    pub offset: usize,
+    /// Field name, exactly as the disc record spells it.
+    pub name: &'static str,
+    /// Storage kind.
+    pub kind: Kind,
+}
+
+const TABLE: &str = include_str!("../data/unit_definition_layout.txt");
+
+/// Every mapped field, in offset order.
+pub fn fields() -> Vec<Field> {
+    TABLE
+        .lines()
+        .filter(|l| !l.trim_start().starts_with('#') && !l.trim().is_empty())
+        .filter_map(|l| {
+            let mut it = l.split_whitespace();
+            let offset = it.next()?.parse().ok()?;
+            let kind = match it.next()? {
+                "f32" => Kind::F32,
+                "str" => Kind::Str,
+                _ => Kind::Word,
+            };
+            // `name` is a &'static str because TABLE is 'static.
+            let name = it.next()?;
+            let name: &'static str = TABLE.get(
+                TABLE.find(name).map(|s| s..s + name.len())?,
+            )?;
+            Some(Field { offset, name, kind })
+        })
+        .collect()
+}
+
+/// The field at `offset`, if one is mapped there.
+pub fn field_at(offset: usize) -> Option<Field> {
+    fields().into_iter().find(|f| f.offset == offset)
+}
+
+/// The offset of `name`, if it is mapped.
+pub fn offset_of(name: &str) -> Option<usize> {
+    fields().into_iter().find(|f| f.name == name).map(|f| f.offset)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn table_parses_and_is_ordered() {
+        let f = fields();
+        assert!(f.len() > 150, "expected the full map, got {}", f.len());
+        assert!(f.windows(2).all(|w| w[0].offset < w[1].offset), "offsets must be strictly increasing");
+    }
+
+    #[test]
+    fn known_fields_sit_where_the_loader_puts_them() {
+        // Spot-checks from the verified map; these four also anchor the
+        // identification of a live object (see docs/re/live-unit-definitions.md).
+        assert_eq!(offset_of("Size_X"), Some(48));
+        assert_eq!(offset_of("Size_Y"), Some(52));
+        assert_eq!(offset_of("Size_Z"), Some(56));
+        assert_eq!(offset_of("HP"), Some(84));
+        assert_eq!(offset_of("HQRatio"), Some(88));
+        assert_eq!(field_at(96).map(|f| f.name), Some("ThrusterRatio"));
+        assert_eq!(field_at(48).map(|f| f.kind), Some(Kind::F32));
+    }
+}

crates/sylpheed-formats/tests/caption_families_disc.rs

@@ -0,0 +1,85 @@
+//! Caption recovery across all eight `MSG_*` families.
+//!
+//! `build_demo_text` reads only `MSG_DEMO_*`, the smallest family.
+//! `build_caption_text` generalises the key parser to all eight.
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use sylpheed_formats::{movie_subtitle, PakArchive};
+
+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 d = Path::new(
+        "/home/fabi/RE - Project Sylpheed/Project Sylpheed - Arc of Deception (USA, Europe) (En,Ja)",
+    );
+    d.join("dat").is_dir().then(|| d.to_path_buf())
+}
+
+macro_rules! skip_without_disc {
+    ($root:ident) => {
+        let Some($root) = disc_root() else {
+            eprintln!("SKIP: set SYLPHEED_DISC");
+            return;
+        };
+    };
+}
+
+#[test]
+fn all_eight_caption_families_are_read() {
+    skip_without_disc!(root);
+    let pak = PakArchive::open(root.join("dat/GP_MAIN_GAME_E.pak")).expect("pak");
+    let all = movie_subtitle::build_caption_text(&pak);
+
+    let mut per: BTreeMap<String, usize> = BTreeMap::new();
+    for (id, lines) in &all {
+        *per.entry(id.split('_').next().unwrap().to_string()).or_default() += lines.len();
+    }
+    let fams: Vec<&str> = per.keys().map(String::as_str).collect();
+    assert_eq!(
+        fams,
+        ["ACRO", "ADAN", "ADPL", "BIRD", "DEMO", "RHIN", "TCAF", "VOICE"],
+        "all eight families must appear"
+    );
+
+    let total: usize = all.values().map(|v| v.len()).sum();
+    // 8800 is ALL of them: every distinct text-bearing MSG_* key on the disc has
+    // the <id>_<page>_<line> shape, and the field reader recovers 8800 of 8800.
+    assert_eq!(total, 8800, "recovered caption lines");
+    assert_eq!(all.len(), 4085, "recovered caption ids");
+
+    // `VOICE` is the only family with a letter before the id; its ids must keep it.
+    assert!(all.contains_key("VOICE_A_150"), "VOICE ids keep their family letter");
+}
+
+/// The control: generalising must not lose anything the DEMO-only reader had.
+/// It does not — it gains, because token adjacency was dropping lines there too.
+#[test]
+fn demo_family_is_not_lost_by_generalising() {
+    skip_without_disc!(root);
+    let pak = PakArchive::open(root.join("dat/GP_MAIN_GAME_E.pak")).expect("pak");
+    let demo = movie_subtitle::build_demo_text(&pak);
+    let all = movie_subtitle::build_caption_text(&pak);
+
+    let old: usize = demo.values().map(|v| v.len()).sum();
+    let new: usize = all
+        .iter()
+        .filter(|(k, _)| k.starts_with("DEMO_"))
+        .map(|(_, v)| v.len())
+        .sum();
+    // The token-adjacency reader misses 4 DEMO lines that the field reader gets,
+    // so the record route is strictly better even on the family it was written
+    // for. It must never be WORSE.
+    assert_eq!(old, 537, "build_demo_text, token adjacency");
+    assert_eq!(new, 541, "build_caption_text, record fields");
+    assert!(new >= old, "the record route must not lose lines");
+
+    // …and 16x more text overall than the DEMO-only path saw.
+    let total: usize = all.values().map(|v| v.len()).sum();
+    assert!(total > old * 16, "expected a large gain, got {total} vs {old}");
+}

crates/sylpheed-formats/tests/game_data_disc.rs

@@ -0,0 +1,309 @@
+//! Real-disc tests for the record-table game-data loaders. Skipped without
+//! `SYLPHEED_DISC`.
+//!
+//! These pin the values that only became readable once the loaders moved off the
+//! string-pool reader (`docs/re/idxd-legacy-reader-audit.md`): the per-hardpoint
+//! stats, the per-difficulty scoring and the per-phase play space. A regression
+//! to the flat reader collapses each of them to one answer and fails here.
+
+use std::collections::BTreeSet;
+
+use sylpheed_formats::game_data::{self as gd, Difficulty, HardpointKind};
+use sylpheed_formats::PakArchive;
+
+fn main_pak() -> Option<PakArchive> {
+    let disc = std::env::var("SYLPHEED_DISC").ok()?;
+    PakArchive::open(format!("{disc}/dat/GP_MAIN_GAME_E.pak")).ok()
+}
+
+fn skip() {
+    eprintln!("SKIP: set SYLPHEED_DISC");
+}
+
+/// The player's craft carries 63 `Turret_NNN` records — one per equippable
+/// weapon — each with its own `HP`, while `StructureCount.TurretCount` says 4.
+/// The flat reader had one `HP` slot for the whole object.
+#[test]
+fn craft_hardpoints_are_per_record() {
+    let Some(pak) = main_pak() else { return skip() };
+    let units = gd::load_units(&pak);
+    let saber = units
+        .iter()
+        .find(|u| u.id.as_deref() == Some("UN_f001_TCAF_DeltaSaber_T"))
+        .expect("Delta Saber present");
+    assert_eq!(saber.hp, Some(1000.0), "hull HP");
+    assert_eq!(saber.turret_count, Some(4), "StructureCount.TurretCount");
+    let turrets: Vec<_> = saber
+        .hardpoints
+        .iter()
+        .filter(|h| h.kind == HardpointKind::Turret)
+        .collect();
+    assert_eq!(turrets.len(), 63, "Turret_NNN records");
+    assert!(turrets.iter().all(|t| t.hp == Some(100.0)), "every mount has HP 100");
+    // Each mount names its own weapon model, `rou_f001_wep_NN`.
+    let mount = turrets.iter().find(|t| t.index == 33).expect("Turret_033");
+    assert_eq!(mount.model.as_deref(), Some("rou_f001_wep_33"));
+    assert_eq!(mount.id.as_deref(), Some("Turret_033"));
+}
+
+/// A capital ship's components each carry their own HP — five distinct values on
+/// the SD-Battleship, where the flat reader returned only the hull's 100000.
+#[test]
+fn vessel_hardpoints_are_per_record() {
+    let Some(pak) = main_pak() else { return skip() };
+    let vessels = gd::load_vessels(&pak);
+    let bs = vessels
+        .iter()
+        .find(|v| v.id.as_deref() == Some("UN_e101_ADAN_SDBattleship"))
+        .expect("SD-Battleship present");
+    assert_eq!(bs.hp, Some(100000.0));
+    let hp_of = |kind: HardpointKind, idx: u32| {
+        bs.hardpoints
+            .iter()
+            .find(|h| h.kind == kind && h.index == idx)
+            .and_then(|h| h.hp)
+    };
+    assert_eq!(hp_of(HardpointKind::Bridge, 0), Some(10000.0));
+    assert_eq!(hp_of(HardpointKind::Thruster, 0), Some(20000.0));
+    assert_eq!(hp_of(HardpointKind::ShieldGenerator, 0), Some(5000.0));
+    assert_eq!(hp_of(HardpointKind::Hatch, 0), Some(100.0));
+    // Distinct HP values across the ship's components.
+    let distinct: BTreeSet<String> = bs
+        .hardpoints
+        .iter()
+        .filter_map(|h| h.hp.map(|v| format!("{v}")))
+        .collect();
+    assert!(distinct.len() >= 4, "distinct component HP values: {distinct:?}");
+    // A main gun names the weapon it fires and the shield generator its share.
+    let asgun = bs
+        .hardpoints
+        .iter()
+        .find(|h| h.weapon_id.as_deref() == Some("Weapon_ADAN_Ship_ASGun"))
+        .expect("an anti-ship gun");
+    assert_eq!(asgun.hp, Some(1500.0));
+    assert_eq!(
+        bs.hardpoints
+            .iter()
+            .find(|h| h.kind == HardpointKind::ShieldGenerator)
+            .and_then(|h| h.power_ratio),
+        Some(0.25)
+    );
+    // The launch bay names the squadron it scrambles.
+    assert_eq!(
+        bs.hardpoints
+            .iter()
+            .find(|h| h.kind == HardpointKind::Hatch)
+            .and_then(|h| h.squadron_id.clone()),
+        Some("Squadron_Test2".to_string())
+    );
+}
+
+/// `MainMissionBonus` lives in `Score_Easy` / `Score_Normal` / `Score_Hard`, one
+/// value each. The flat reader returned the Easy one for every mission.
+#[test]
+fn main_mission_bonus_is_per_difficulty() {
+    let Some(pak) = main_pak() else { return skip() };
+    let cfgs = gd::load_player_configs(&pak);
+    assert_eq!(cfgs.len(), 24);
+    let mut distinct3 = 0;
+    let mut doubling = 0;
+    let mut all_equal = 0;
+    for c in &cfgs {
+        let (e, n, h) = (
+            c.score.easy.main_mission_bonus,
+            c.score.normal.main_mission_bonus,
+            c.score.hard.main_mission_bonus,
+        );
+        let set: BTreeSet<_> = [e, n, h].into_iter().flatten().collect();
+        match set.len() {
+            3 => distinct3 += 1,
+            1 => all_equal += 1,
+            _ => {}
+        }
+        if let (Some(e), Some(n), Some(h)) = (e, n, h) {
+            if n == 2 * e && h == 4 * e {
+                doubling += 1;
+            }
+        }
+    }
+    eprintln!("MainMissionBonus: 3-distinct {distinct3}/24, all-equal {all_equal}, doubling {doubling}");
+    assert_eq!(distinct3, PIN_BONUS_DISTINCT3);
+    assert_eq!(doubling, PIN_BONUS_DOUBLING);
+    // The first config's own numbers.
+    let c = &cfgs[0];
+    assert_eq!(c.score.easy.main_mission_bonus, PIN_C0_EASY);
+    assert_eq!(c.score.normal.main_mission_bonus, PIN_C0_NORMAL);
+    assert_eq!(c.score.hard.main_mission_bonus, PIN_C0_HARD);
+}
+
+/// The rank thresholds repeat identically across the three `Score_*` records —
+/// so the one flat answer happened to be right, but only by coincidence.
+#[test]
+fn rank_scores_repeat_across_difficulties() {
+    let Some(pak) = main_pak() else { return skip() };
+    let cfgs = gd::load_player_configs(&pak);
+    let mut identical = 0;
+    for c in &cfgs {
+        let row = |s: &gd::ScoreRules| {
+            (s.rank_score_s, s.rank_score_a, s.rank_score_b, s.rank_score_c, s.rank_score_d)
+        };
+        if row(&c.score.easy) == row(&c.score.normal) && row(&c.score.normal) == row(&c.score.hard) {
+            identical += 1;
+        }
+    }
+    eprintln!("rank scores identical across difficulties: {identical}/{}", cfgs.len());
+    assert_eq!(identical, cfgs.len());
+    assert_eq!(cfgs[0].score.normal.rank_score_s, Some(10000));
+    assert_eq!(cfgs[0].score.normal.rank_score_d, Some(1000));
+    // The difficulty scaling that *is* per record.
+    assert_eq!(cfgs[0].difficulty_f32(Difficulty::Easy, "DamageAdjustment"), PIN_EASY_DMG);
+    assert_eq!(cfgs[0].difficulty_f32(Difficulty::Hard, "ShieldDamageAdjustment"), PIN_HARD_SHIELD);
+}
+
+/// `SpaceSize` lives in `Phase_1` / `Phase_2` / `Phase_3`, one value each.
+#[test]
+fn space_size_is_per_phase() {
+    let Some(pak) = main_pak() else { return skip() };
+    let cfgs = gd::load_player_configs(&pak);
+    let mut varying = 0;
+    let mut p1_250k = 0;
+    for c in &cfgs {
+        assert_eq!(c.phases.len(), 3, "every mission has three Phase_N records");
+        let sizes: Vec<Option<f32>> = c.phases.iter().map(|p| p.space_size).collect();
+        let shapes: BTreeSet<String> = sizes.iter().map(|v| format!("{v:?}")).collect();
+        if shapes.len() > 1 {
+            varying += 1;
+        }
+        if sizes[0] == Some(250000.0) {
+            p1_250k += 1;
+        }
+    }
+    eprintln!("SpaceSize: varying across phases {varying}/24, phase 1 = 250000 in {p1_250k}");
+    assert_eq!(varying, PIN_SPACE_VARYING);
+    assert_eq!(p1_250k, PIN_SPACE_P1_250K);
+    let c = &cfgs[0];
+    assert_eq!(c.space_size(1), PIN_C0_SPACE1);
+    assert_eq!(c.space_size(2), PIN_C0_SPACE2);
+    assert_eq!(c.space_size(3), PIN_C0_SPACE3);
+}
+
+/// Fields the string-pool reader returned `None` for now have values, disc-wide.
+#[test]
+fn previously_unreadable_stats_are_populated() {
+    let Some(pak) = main_pak() else { return skip() };
+    let units = gd::load_units(&pak);
+    let vessels = gd::load_vessels(&pak);
+    let n = |f: fn(&gd::CraftUnit) -> Option<f32>| units.iter().filter(|u| f(u).is_some()).count();
+    eprintln!(
+        "units={} fcs={} shield_ratio={} cruise={} maxvel={} accel={} decel={} shield_max={}",
+        units.len(),
+        n(|u| u.fcs_range),
+        n(|u| u.shield_ratio),
+        n(|u| u.cruising_velocity),
+        n(|u| u.maximum_velocity),
+        n(|u| u.acceleration),
+        n(|u| u.deceleration),
+        n(|u| u.shield_max),
+    );
+    for (label, count) in [
+        ("fcs_range", n(|u| u.fcs_range)),
+        ("shield_ratio", n(|u| u.shield_ratio)),
+        ("cruising_velocity", n(|u| u.cruising_velocity)),
+        ("maximum_velocity", n(|u| u.maximum_velocity)),
+        ("acceleration", n(|u| u.acceleration)),
+        ("deceleration", n(|u| u.deceleration)),
+    ] {
+        assert_eq!(count, units.len(), "{label} set on every unit");
+    }
+    assert!(vessels.iter().all(|v| v.fcs_range.is_some() && v.shield_ratio.is_some()));
+    // Hardpoint HP is readable for every vessel component.
+    let hp_missing = vessels
+        .iter()
+        .flat_map(|v| &v.hardpoints)
+        .filter(|h| h.hp.is_none())
+        .count();
+    assert_eq!(hp_missing, 0);
+    let total_hardpoints: usize = vessels.iter().map(|v| v.hardpoints.len()).sum();
+    eprintln!("vessel hardpoints: {total_hardpoints}");
+    assert_eq!(total_hardpoints, PIN_VESSEL_HARDPOINTS);
+}
+
+/// The launcher and its projectile are two records with two ids; the tracer has a
+/// third `Interval`.
+#[test]
+fn weapon_launcher_and_shell_stay_separate() {
+    let Some(pak) = main_pak() else { return skip() };
+    let ws = gd::load_weapons(&pak);
+    assert_eq!(ws.len(), 131);
+    let differing = ws
+        .iter()
+        .filter(|w| w.id.is_some() && w.shell_id.is_some() && w.id != w.shell_id)
+        .count();
+    eprintln!("weapons whose shell id differs from the launcher id: {differing}/{}", ws.len());
+    assert_eq!(differing, PIN_WEAPON_SHELL_IDS);
+    // A player missile the corpus quotes through the flat reader — the launcher
+    // fields agree, and `MaximumRange` (a `Shell` field) reads the same.
+    let m26 = ws
+        .iter()
+        .find(|w| w.id.as_deref() == Some("Weapon_DSaber_P_wep_26_Missile"))
+        .expect("Weapon_DSaber_P_wep_26_Missile is in GP_MAIN_GAME_E.pak, not the hangar pak");
+    assert_eq!(m26.target_type.as_deref(), Some("Vessel,Craft"));
+    assert_eq!(m26.loading_count, Some(144));
+    assert_eq!(m26.interval, Some(3.0));
+    assert_eq!(m26.mass, Some(0.77));
+    assert_eq!(m26.trigger_shot_count, Some(12));
+    assert_eq!(m26.max_range, Some(10000.0));
+
+    let with_wake = ws.iter().filter(|w| w.records.record("ShellWake").is_some()).count();
+    eprintln!("weapons with a ShellWake record: {with_wake}");
+    assert_eq!(with_wake, PIN_WEAPON_WAKE);
+    // `Power` is a `Shell` field: every weapon but one has it.
+    let no_power: Vec<&str> =
+        ws.iter().filter(|w| w.power.is_none()).filter_map(|w| w.id.as_deref()).collect();
+    assert_eq!(no_power, ["Weapon_NULL"], "only the placeholder weapon has no Shell.Power");
+}
+
+/// `RecordSet::everywhere` is the API that answers "which record did that come
+/// from" — the question the flat map could not express.
+#[test]
+fn everywhere_enumerates_the_records_that_define_a_field() {
+    let Some(pak) = main_pak() else { return skip() };
+    let vessels = gd::load_vessels(&pak);
+    let bs = vessels
+        .iter()
+        .find(|v| v.id.as_deref() == Some("UN_e101_ADAN_SDBattleship"))
+        .unwrap();
+    let hps = bs.records.everywhere("HP");
+    eprintln!("SDBattleship records defining HP: {}", hps.len());
+    assert_eq!(hps.len(), PIN_BS_HP_RECORDS);
+    assert!(hps.iter().any(|(r, v)| *r == "Generic" && *v == "100000.0"));
+    assert!(hps.iter().any(|(r, _)| r.starts_with("Turret_")));
+}
+
+// Pinned measurements over `GP_MAIN_GAME_E.pak`.
+
+/// 18 of the 24 missions pay a different main-objective bonus per difficulty;
+/// the other 6 pay 0 at every difficulty.
+const PIN_BONUS_DISTINCT3: usize = 18;
+/// …and in all 24 the ratio is easy : normal : hard = 1 : 2 : 4.
+const PIN_BONUS_DOUBLING: usize = 24;
+const PIN_C0_EASY: Option<i64> = Some(1000);
+const PIN_C0_NORMAL: Option<i64> = Some(2000);
+const PIN_C0_HARD: Option<i64> = Some(4000);
+const PIN_EASY_DMG: Option<f32> = Some(1.5);
+const PIN_HARD_SHIELD: Option<f32> = Some(0.5);
+/// `SpaceSize` is stored per phase, but only **one** of the 24 missions actually
+/// varies it across its phases (250000 → 100000 → 100000). The other 23 repeat
+/// one value: 500000 once, 100000 eighteen times, 50000 four times.
+const PIN_SPACE_VARYING: usize = 1;
+const PIN_SPACE_P1_250K: usize = 1;
+const PIN_C0_SPACE1: Option<f32> = Some(250000.0);
+const PIN_C0_SPACE2: Option<f32> = Some(100000.0);
+const PIN_C0_SPACE3: Option<f32> = Some(100000.0);
+/// Destructible components across the 23 capital ships, each with its own HP.
+const PIN_VESSEL_HARDPOINTS: usize = 418;
+/// Every weapon's projectile carries an id of its own (`Shell_…` vs `Weapon_…`).
+const PIN_WEAPON_SHELL_IDS: usize = 131;
+const PIN_WEAPON_WAKE: usize = 40;
+/// Records of the SD-Battleship that define an `HP`: the hull plus 36 components.
+const PIN_BS_HP_RECORDS: usize = 37;

crates/sylpheed-formats/tests/idxd_records_disc.rs

@@ -0,0 +1,348 @@
+//! The IDXD record/field table, checked against every IDXD object on the disc.
+//!
+//! The binary region in front of the string pool was undecoded for a long time
+//! (`idxd.rs` used to say so). It is a record array plus a field array, and the
+//! decisive evidence is that every record reproduces its own stored hash and
+//! every named field reproduces its own key: the layout has no free parameters
+//! left once that holds 1.4 million times.
+//!
+//! `first_header_word_is_record0_hash` is the one that demotes `schema_hash`.
+
+use std::path::{Path, PathBuf};
+
+use sylpheed_formats::hash::tag_hash;
+use sylpheed_formats::{IdxdObject, PakArchive};
+
+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)",
+    );
+    default.join("dat").is_dir().then(|| default.to_path_buf())
+}
+
+macro_rules! skip_without_disc {
+    ($root:ident) => {
+        let Some($root) = disc_root() else {
+            eprintln!("SKIP: extracted disc not found (set SYLPHEED_DISC to enable)");
+            return;
+        };
+    };
+}
+
+/// Every `.pak` on the disc, recursively.
+///
+/// Deliberately the whole disc root, not `dat/`: `hidden/DefTables.pak` holds
+/// another 1425 IDXD objects, and an earlier version of this sweep missed them.
+fn all_paks(root: &Path) -> Vec<PathBuf> {
+    let mut out = Vec::new();
+    let mut stack = vec![root.to_path_buf()];
+    while let Some(dir) = stack.pop() {
+        let Ok(rd) = std::fs::read_dir(&dir) else {
+            continue;
+        };
+        for e in rd.flatten() {
+            let p = e.path();
+            if p.is_dir() {
+                stack.push(p);
+            } else if p.extension().is_some_and(|x| x == "pak") {
+                out.push(p);
+            }
+        }
+    }
+    out.sort();
+    out
+}
+
+#[test]
+fn records_roundtrip_disc() {
+    skip_without_disc!(root);
+
+    let (mut objects, mut hashed, mut unparsed) = (0usize, 0usize, 0usize);
+    let mut bad: Vec<String> = Vec::new();
+
+    for pak in all_paks(&root) {
+        let Ok(ar) = PakArchive::open(&pak) else {
+            continue;
+        };
+        for entry in ar.entries() {
+            let Ok(bytes) = ar.read(entry) else { continue };
+            if !IdxdObject::is_idxd(&bytes) {
+                continue;
+            }
+            let Ok(obj) = IdxdObject::parse(&bytes) else {
+                continue;
+            };
+            objects += 1;
+            let Some(recs) = obj.records() else {
+                unparsed += 1;
+                bad.push(format!(
+                    "{}:{:08x} record region did not parse",
+                    pak.display(),
+                    entry.name_hash
+                ));
+                continue;
+            };
+            assert_eq!(
+                recs.len(),
+                obj.count as usize,
+                "{}:{:08x} record count",
+                pak.display(),
+                entry.name_hash
+            );
+            for r in recs {
+                hashed += 1;
+                if r.name_hash != tag_hash(&r.name) {
+                    if bad.len() < 10 {
+                        bad.push(format!(
+                            "{}:{:08x} record {:?} stored {:08x} != tag_hash {:08x}",
+                            pak.display(),
+                            entry.name_hash,
+                            r.name,
+                            r.name_hash,
+                            tag_hash(&r.name)
+                        ));
+                    }
+                    unparsed += 1;
+                }
+            }
+            // Records are stored sorted by hash so the guest can binary-search.
+            assert!(
+                recs.windows(2).all(|w| w[0].name_hash <= w[1].name_hash),
+                "{}:{:08x} records not sorted by hash",
+                pak.display(),
+                entry.name_hash
+            );
+        }
+    }
+
+    eprintln!("IDXD objects {objects}, hashed records {hashed}, failures {unparsed}");
+    assert!(
+        bad.is_empty(),
+        "{} failures, first few:\n{}",
+        unparsed,
+        bad.join("\n")
+    );
+    // Guard against the sweep silently finding nothing.
+    assert_eq!(objects, 7750, "IDXD object total changed");
+    assert_eq!(hashed, 190_782, "record total changed");
+}
+
+/// A concrete, human-checkable row: the movie table keys its cutscene ids as
+/// *literal integers*, which the string-pool reader could never have told apart
+/// from field names.
+#[test]
+fn movie_table_ids_are_literal_field_keys() {
+    skip_without_disc!(root);
+    let ar = PakArchive::open(root.join("dat/tables.pak")).expect("tables.pak");
+
+    let mut found = false;
+    for entry in ar.entries() {
+        let Ok(bytes) = ar.read(entry) else { continue };
+        if !IdxdObject::is_idxd(&bytes) {
+            continue;
+        }
+        let obj = IdxdObject::parse(&bytes).unwrap();
+        if obj.schema_hash != 0x0670_25B9 {
+            continue;
+        }
+        let base = obj.record("BASE_INFO").expect("BASE_INFO record");
+        // The five named fields the movie GamePart reads.
+        assert_eq!(base.get("PATH"), Some("dat\\movie\\"));
+        assert_eq!(base.get("VERSION"), Some("0x060329"));
+        // …and the numeric ids, which are keys, not names.
+        assert_eq!(
+            base.field_at(105).map(|f| f.value.as_str()),
+            Some("STAGE01_PHASE01")
+        );
+        assert_eq!(
+            base.field_at(205).map(|f| f.value.as_str()),
+            Some("STAGE02_PHASE01")
+        );
+
+        // Each id names a record that carries the actual file names.
+        let rec = obj.record("STAGE02_PHASE01").expect("STAGE02_PHASE01");
+        assert_eq!(rec.get("MOVIE"), Some("RT02A.wmv"));
+        assert_eq!(rec.get("VOICETRACK"), Some("VOICE_RT02A"));
+
+        // Every literal-keyed BASE_INFO field must name a real record.
+        let ids: Vec<u32> = base.fields.iter().filter_map(|f| f.index()).collect();
+        assert!(ids.len() > 90, "only {} literal ids", ids.len());
+        for f in base.fields.iter().filter(|f| f.index().is_some()) {
+            assert!(
+                obj.record(&f.value).is_some(),
+                "id {} -> {:?} has no record",
+                f.key,
+                f.value
+            );
+        }
+        found = true;
+        break;
+    }
+    assert!(
+        found,
+        "movie table (schema 067025b9) not found in tables.pak"
+    );
+}
+
+/// The header word this crate calls `schema_hash` is record 0's name hash. If
+/// that were a coincidence it would not survive 6325 objects.
+#[test]
+fn first_header_word_is_record0_hash() {
+    skip_without_disc!(root);
+    let (mut checked, mut mismatched) = (0usize, 0usize);
+    for pak in all_paks(&root) {
+        let Ok(ar) = PakArchive::open(&pak) else {
+            continue;
+        };
+        for entry in ar.entries() {
+            let Ok(bytes) = ar.read(entry) else { continue };
+            if !IdxdObject::is_idxd(&bytes) {
+                continue;
+            }
+            let Ok(obj) = IdxdObject::parse(&bytes) else {
+                continue;
+            };
+            let Some(first) = obj.first_record() else {
+                continue;
+            };
+            checked += 1;
+            if tag_hash(&first.name) != obj.schema_hash {
+                mismatched += 1;
+                if mismatched <= 5 {
+                    eprintln!(
+                        "{}:{:08x} header {:08x} != tag_hash({:?}) {:08x}",
+                        pak.display(),
+                        entry.name_hash,
+                        obj.schema_hash,
+                        first.name,
+                        tag_hash(&first.name)
+                    );
+                }
+            }
+        }
+    }
+    eprintln!("checked {checked}, mismatched {mismatched}");
+    assert_eq!(mismatched, 0);
+    assert_eq!(checked, 7750);
+}
+
+/// Field names are stored on disc; the key is `tag_hash` of the stored name.
+/// Unnamed fields carry a literal positional key instead.
+#[test]
+fn field_names_are_stored_disc() {
+    skip_without_disc!(root);
+    let (mut named, mut positional, mut hash_keyed_unnamed, mut bad) =
+        (0usize, 0usize, 0usize, 0usize);
+    for pak in all_paks(&root) {
+        let Ok(ar) = PakArchive::open(&pak) else {
+            continue;
+        };
+        for entry in ar.entries() {
+            let Ok(bytes) = ar.read(entry) else { continue };
+            if !IdxdObject::is_idxd(&bytes) {
+                continue;
+            }
+            let Ok(obj) = IdxdObject::parse(&bytes) else {
+                continue;
+            };
+            let Some(recs) = obj.records() else { continue };
+            for r in recs {
+                for f in &r.fields {
+                    match &f.name {
+                        Some(n) => {
+                            named += 1;
+                            if tag_hash(n) != f.key {
+                                bad += 1;
+                                if bad <= 5 {
+                                    eprintln!(
+                                        "{}:{:08x} {:?}.{:?} key {:08x} != {:08x}",
+                                        pak.display(),
+                                        entry.name_hash,
+                                        r.name,
+                                        n,
+                                        f.key,
+                                        tag_hash(n)
+                                    );
+                                }
+                            }
+                        }
+                        None if f.key < 0x1_0000 => positional += 1,
+                        None => hash_keyed_unnamed += 1,
+                    }
+                }
+            }
+        }
+    }
+    eprintln!(
+        "named {named}, positional {positional}, hash-keyed-but-unnamed {hash_keyed_unnamed}, bad {bad}"
+    );
+    assert_eq!(bad, 0, "named fields must reproduce their key");
+    assert_eq!(named, 1_271_462);
+    assert_eq!(positional, 1_485_073);
+    // A small residue keeps a hash-shaped key with no stored name: the only
+    // fields on the disc whose name still has to be recovered by preimage search.
+    assert_eq!(hash_keyed_unnamed, 504);
+}
+
+/// The "sibling default" rules are a string-pool deduplication artefact.
+///
+/// The corpus recorded that `Size_Y` inherits `Size_X` (and three similar pairs)
+/// for units the disc leaves "defaulted". The fields are not defaulted — they are
+/// on disc — and the old reader missed them precisely when the value was shared
+/// with the sibling, which is the condition the rule then "predicted".
+#[test]
+fn sibling_default_rules_are_a_dedup_artefact() {
+    skip_without_disc!(root);
+    let arc = PakArchive::open(root.join("dat/GP_MAIN_GAME_E.pak")).expect("pak");
+
+    let pairs = [
+        ("Size_Y", "Size_X"),
+        ("FCSRange", "RadarRange"),
+        ("DefencePoint", "AttackVesselPoint"),
+    ];
+    // [pair][legacy_absent][equal_on_disc]
+    let mut tally = [[[0usize; 2]; 2]; 3];
+    for e in arc.entries() {
+        let Ok(bytes) = arc.read(e) else { continue };
+        if !IdxdObject::is_idxd(&bytes) {
+            continue;
+        }
+        let Ok(obj) = IdxdObject::parse(&bytes) else { continue };
+        let Some(generic) = obj.record("Generic") else { continue };
+        if generic.get("Size_X").is_none() {
+            continue;
+        }
+        for (i, (field, sibling)) in pairs.iter().enumerate() {
+            let (Some(a), Some(b)) = (generic.get(field), generic.get(sibling)) else {
+                continue;
+            };
+            tally[i][usize::from(obj.get_f32(field).is_none())][usize::from(a == b)] += 1;
+        }
+    }
+
+    // The field is present on disc far more often than it "differs", so the
+    // premise "these fields are defaulted" is simply false.
+    assert_eq!(tally[0][0][0] + tally[0][1][0], 90, "Size_Y differs from Size_X");
+
+    // The mechanism: a value shared with the sibling is ALWAYS invisible to the
+    // legacy reader. If this cell were ever non-zero the dedup story would be
+    // incomplete.
+    for (i, (field, sibling)) in pairs.iter().enumerate() {
+        assert_eq!(
+            tally[i][0][1], 0,
+            "{field}/{sibling}: legacy reader saw a value it shares with its sibling"
+        );
+    }
+
+    // …and it almost never misses a value that differs. Those few cells are
+    // exactly where the rule predicts the wrong number.
+    assert_eq!(tally[0][1][0], 0, "Size_Y: rule never wrong");
+    assert_eq!(tally[1][1][0], 1, "FCSRange: UN_e011_ADAN_Attacker_B_HF_Wayne");
+    assert_eq!(tally[2][1][0], 1, "DefencePoint: UN_e104_ADAN_Carrier");
+}

crates/sylpheed-formats/tests/ixud_records_disc.rs

@@ -0,0 +1,95 @@
+//! The IXUD record/field table, checked against every IXUD object on the disc.
+//!
+//! The decode was verified with a standalone parser hours before it existed in
+//! the crate; this is the same check through `IxudObject`.
+
+use std::path::{Path, PathBuf};
+
+use sylpheed_formats::hash::ixud_hash_str;
+use sylpheed_formats::{IxudObject, PakArchive};
+
+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 d = Path::new(
+        "/home/fabi/RE - Project Sylpheed/Project Sylpheed - Arc of Deception (USA, Europe) (En,Ja)",
+    );
+    d.join("dat").is_dir().then(|| d.to_path_buf())
+}
+
+macro_rules! skip_without_disc {
+    ($root:ident) => {
+        let Some($root) = disc_root() else {
+            eprintln!("SKIP: set SYLPHEED_DISC");
+            return;
+        };
+    };
+}
+
+fn all_paks(root: &Path) -> Vec<PathBuf> {
+    let mut out = Vec::new();
+    let mut stack = vec![root.to_path_buf()];
+    while let Some(dir) = stack.pop() {
+        let Ok(rd) = std::fs::read_dir(&dir) else { continue };
+        for e in rd.flatten() {
+            let p = e.path();
+            if p.is_dir() {
+                stack.push(p);
+            } else if p.extension().is_some_and(|x| x == "pak") {
+                out.push(p);
+            }
+        }
+    }
+    out.sort();
+    out
+}
+
+#[test]
+fn ixud_records_roundtrip_disc() {
+    skip_without_disc!(root);
+    let (mut objects, mut records, mut named, mut positional, mut bad) = (0, 0, 0, 0, 0);
+    for pak in all_paks(&root) {
+        let Ok(ar) = PakArchive::open(&pak) else { continue };
+        for entry in ar.entries() {
+            let Ok(bytes) = ar.read(entry) else { continue };
+            if bytes.len() < 4 || bytes[0..4] != *b"IXUD" {
+                continue;
+            }
+            let Some(obj) = IxudObject::parse(&bytes) else {
+                bad += 1;
+                continue;
+            };
+            objects += 1;
+            // The header word is record 0's hash, not a schema id.
+            assert_eq!(
+                obj.first_record_hash,
+                obj.records()[0].name_hash,
+                "{}: header word is record 0's hash",
+                pak.display()
+            );
+            for r in obj.records() {
+                records += 1;
+                assert_eq!(r.name_hash, ixud_hash_str(&r.name), "{}", pak.display());
+                for f in &r.fields {
+                    match &f.name {
+                        Some(n) => {
+                            named += 1;
+                            assert_eq!(f.key, ixud_hash_str(n), "{}", pak.display());
+                        }
+                        None => positional += 1,
+                    }
+                }
+            }
+        }
+    }
+    eprintln!("objects {objects}, records {records}, named {named}, positional {positional}");
+    assert_eq!(bad, 0, "every IXUD object must parse");
+    assert_eq!(objects, 1104);
+    assert_eq!(records, 1476);
+    assert_eq!(named, 628_165);
+    assert_eq!(positional, 48);
+}

crates/sylpheed-formats/tests/media_disc.rs

@@ -0,0 +1,88 @@
+//! Real-disc tests for media assembly. Skipped without `SYLPHEED_DISC`.
+//!
+//! This logic used to live in the Bevy viewer, where it had no test at all. It
+//! is the trickiest reading on the disc — a cutscene's voice is a byte region of
+//! a continuous stream, not the bank its name points at — so it gets pinned here
+//! before anything else is built on top of it.
+
+use std::path::PathBuf;
+
+use sylpheed_formats::media::{self, DirectorySource, DiscSource};
+use sylpheed_formats::slb::VoiceLang;
+
+fn disc() -> Option<DirectorySource> {
+    let p = PathBuf::from(std::env::var("SYLPHEED_DISC").ok()?);
+    p.join("dat").is_dir().then(|| DirectorySource::new(p))
+}
+
+/// A segment-spanning read returns the same bytes as slicing the whole archive.
+///
+/// The control that matters: `sound.pak`'s data is five segments, so a TOC
+/// offset late in the archive addresses a position no single file has. If the
+/// walk were off by a segment this would return plausible-looking wrong bytes
+/// rather than fail, which is exactly why it is asserted against the archive's
+/// own read rather than against a length.
+#[test]
+fn segment_range_matches_the_archive_read() {
+    let Some(src) = disc() else {
+        eprintln!("SKIP: set SYLPHEED_DISC");
+        return;
+    };
+    let name = "BGM_020.slb";
+    let hash = sylpheed_formats::hash::name_hash(name);
+    let via_range = media::read_sound_bank(&src, hash).expect("segment range read");
+
+    let toc = src.read_file("dat/sound.pak").unwrap();
+    let entries = sylpheed_formats::PakArchive::parse_toc(&toc).unwrap();
+    let e = entries
+        .iter()
+        .find(|e| e.name_hash == hash)
+        .expect("BGM_020 in the TOC");
+    assert_eq!(via_range.len(), e.comp_size as usize);
+
+    // And it decodes, which a misaligned read would not do.
+    let riffs = media::sound_bank_riffs(&src, name).expect("riffs");
+    assert!(!riffs.is_empty(), "no sub-waves recovered");
+}
+
+/// A movie's voice resolves to a byte region, and the region is sane.
+///
+/// `RT01A` is one of the cutscenes whose voice spans more than one `.slb`
+/// chunk — the case that motivated regions over per-bank reads in the first
+/// place. The assertions are deliberately about *shape* (ordered, non-empty,
+/// smaller than one bank) rather than exact offsets, because the offsets are
+/// disc facts we have no independent oracle for here; a regression that
+/// reversed or emptied the region would still be caught.
+#[test]
+fn movie_voice_resolves_to_a_region_that_decodes() {
+    let Some(src) = disc() else {
+        eprintln!("SKIP: set SYLPHEED_DISC");
+        return;
+    };
+    let (start, end) = media::resolve_movie_voice_region(&src, "RT01A", VoiceLang::English)
+        .expect("RT01A has a bound voice track");
+    assert!(start < end, "region is inverted: {start}..{end}");
+    assert!(end - start > 4096, "region is implausibly small");
+    assert!(end - start < 1_500_000, "region spans more than one bank");
+
+    let riffs = media::voice_region_riffs(&src, start, end).expect("region riffs");
+    assert!(!riffs.is_empty(), "region decoded to no audio");
+}
+
+/// An unbound movie stays unvoiced rather than borrowing a neighbour's clip.
+///
+/// This is a *negative* the corpus paid for: extending resolution to unbound
+/// resupply movies by shared demo line played the WRONG recording. The guard
+/// keeps that door shut.
+#[test]
+fn manifest_binding_is_the_only_route() {
+    let Some(src) = disc() else {
+        eprintln!("SKIP: set SYLPHEED_DISC");
+        return;
+    };
+    // A movie the manifest does not bind must resolve to nothing, not to a guess.
+    assert_eq!(
+        media::resolve_movie_voice_clip(&src, "no_such_movie_xyz", VoiceLang::English),
+        None
+    );
+}

crates/sylpheed-formats/tests/mesh_consistency_disc.rs

@@ -0,0 +1,144 @@
+//! Cross-container consistency for XBG7 geometry.
+//!
+//! A geometry resource shared by several stage containers must decode to the
+//! same bounds in each. This needs no ground truth, and on 2026-08-11 it found
+//! **125 of 681** shared resources decoding to different bounds while reporting
+//! identical vertex and triangle counts — the anchor scan locating a different
+//! buffer of the same size (see `docs/re/structures/xbg7-mesh.md`).
+//!
+//! The test is `#[ignore]`d because the decoder does not satisfy it yet. It is
+//! written as the *target* state so that fixing the anchor scan makes it pass,
+//! rather than as a snapshot of the bug.
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use sylpheed_formats::mesh::Xbg7Model;
+
+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
+}
+
+/// Rounded (w, h, d) of a model's own geometry.
+fn span(m: &Xbg7Model) -> Option<[i64; 3]> {
+    let (mut lo, mut hi) = ([f32::MAX; 3], [f32::MIN; 3]);
+    for s in &m.meshes {
+        for q in &s.positions {
+            for k in 0..3 {
+                lo[k] = lo[k].min(q[k]);
+                hi[k] = hi[k].max(q[k]);
+            }
+        }
+    }
+    if lo[0] == f32::MAX {
+        return None;
+    }
+    Some([
+        (hi[0] - lo[0]).round() as i64,
+        (hi[1] - lo[1]).round() as i64,
+        (hi[2] - lo[2]).round() as i64,
+    ])
+}
+
+#[test]
+#[ignore = "known-failing: 62 of 714 shared resources decode inconsistently (was 125 of 681; distinct anchor assignment + the 0.42 connectivity cap fixed the rest). Note this metric is the WEAKER witness — a systematic mis-anchor is consistent — see docs/re/structures/xbg7-mesh.md"]
+fn shared_resources_decode_identically_in_every_container() {
+    let Some(root) = disc_root() else {
+        eprintln!("SKIP: extracted disc not found (set SYLPHEED_DISC to enable)");
+        return;
+    };
+    let dir = root.join("hidden/resource3d");
+    let mut files: Vec<PathBuf> = std::fs::read_dir(&dir)
+        .expect("resource3d/")
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("xpr"))
+        .collect();
+    files.sort();
+
+    // name -> (verts, tris) -> set of spans seen
+    let mut seen: BTreeMap<String, Vec<([i64; 3], usize, usize, String)>> = BTreeMap::new();
+    for f in &files {
+        let Ok(bytes) = std::fs::read(f) else { continue };
+        let where_ = f.file_name().unwrap().to_string_lossy().to_string();
+        for m in Xbg7Model::anchor_models_cancellable(&bytes, 0.0, &|| false) {
+            let Some(sp) = span(&m) else { continue };
+            let v: usize = m.meshes.iter().map(|s| s.positions.len()).sum();
+            let t: usize = m.meshes.iter().map(|s| s.indices.len() / 3).sum();
+            seen.entry(m.name.clone()).or_default().push((sp, v, t, where_.clone()));
+        }
+    }
+
+    let mut bad: Vec<String> = Vec::new();
+    for (name, list) in &seen {
+        if list.len() < 2 {
+            continue;
+        }
+        // Only compare decodes that agree on how much geometry they found;
+        // a differing vertex/triangle count is a different question.
+        if !list.iter().all(|e| e.1 == list[0].1 && e.2 == list[0].2) {
+            continue;
+        }
+        let spans: std::collections::BTreeSet<[i64; 3]> = list.iter().map(|e| e.0).collect();
+        if spans.len() > 1 && bad.len() < 10 {
+            bad.push(format!("{name}: {spans:?}"));
+        }
+    }
+    assert!(
+        bad.is_empty(),
+        "{} shared resources decode to different bounds; first: {bad:?}",
+        bad.len()
+    );
+}
+
+/// Port/starboard twins must not decode to the *same* buffer.
+///
+/// A runtime capture showed the container stores both halves of the `e106` hull
+/// as separate X-reflected buffers, so a `…_01`/`…_02` pair of equal vertex
+/// count should come out mirrored (or related by another axis / vertex order) —
+/// never identical, which is the collapse distinct assignment fixes. Since that
+/// fix reached grouped pools too, this holds for **every** twin pair on the disc
+/// — including `n206`, which was the last exception.
+#[test]
+fn twin_pairs_do_not_share_a_buffer() {
+    let Some(root) = disc_root() else {
+        eprintln!("SKIP: extracted disc not found (set SYLPHEED_DISC to enable)");
+        return;
+    };
+    let mut files: Vec<PathBuf> = std::fs::read_dir(root.join("hidden/resource3d"))
+        .expect("resource3d/")
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("xpr"))
+        .collect();
+    files.sort();
+
+    let mut collapsed: Vec<String> = Vec::new();
+    for f in &files {
+        let Ok(bytes) = std::fs::read(f) else { continue };
+        let models = Xbg7Model::anchor_models_cancellable(&bytes, 0.0, &|| false);
+        let by_name: BTreeMap<&str, &Xbg7Model> =
+            models.iter().map(|m| (m.name.as_str(), m)).collect();
+        for m in &models {
+            let Some(stem) = m.name.strip_suffix("_01") else { continue };
+            let Some(t) = by_name.get(format!("{stem}_02").as_str()) else { continue };
+            let (a, b) = (m.meshes[0].vbuf_offset, t.meshes[0].vbuf_offset);
+            if a.is_some() && a == b {
+                collapsed.push(format!("{}/{stem}_02 in {}", m.name, f.file_name().unwrap().to_string_lossy()));
+            }
+        }
+    }
+    assert!(collapsed.is_empty(), "twin pairs sharing one buffer: {collapsed:?}");
+}

crates/sylpheed-formats/tests/mesh_disc.rs

@@ -17,7 +17,7 @@ fn res3d_dir() -> Option<PathBuf> {
         }
     }
     let default =
-        PathBuf::from("/home/fabi/RE Project Sylpheed/sylph_extract/hidden/resource3d");
+        PathBuf::from("/home/fabi/RE - Project Sylpheed/sylph_extract/hidden/resource3d");
     default.is_dir().then_some(default)
 }
 
@@ -321,7 +321,7 @@ fn hero_ship_grouped_pool_decodes() {
 fn stage_models_decode() {
     use sylpheed_formats::mesh::Xbg7Model;
     let dir = std::env::var("SYLPHEED_RES3D").unwrap_or_else(|_| {
-        "/home/fabi/RE Project Sylpheed/sylph_extract/hidden/resource3d".to_string()
+        "/home/fabi/RE - Project Sylpheed/sylph_extract/hidden/resource3d".to_string()
     });
     let path = format!("{dir}/Stage_S10.xpr");
     let bytes = std::fs::read(&path).expect("read Stage_S10");
@@ -359,7 +359,7 @@ fn stage_models_sweep() {
     use sylpheed_formats::mesh::Xbg7Model;
     use std::time::Instant;
     let dir = std::env::var("SYLPHEED_RES3D").unwrap_or_else(|_| {
-        "/home/fabi/RE Project Sylpheed/sylph_extract/hidden/resource3d".to_string()
+        "/home/fabi/RE - Project Sylpheed/sylph_extract/hidden/resource3d".to_string()
     });
     let mut names: Vec<_> = std::fs::read_dir(&dir)
         .unwrap()
@@ -386,7 +386,7 @@ fn stage_models_sweep() {
 fn stage_models_quality_audit() {
     use sylpheed_formats::mesh::Xbg7Model;
     let dir = std::env::var("SYLPHEED_RES3D").unwrap_or_else(|_| {
-        "/home/fabi/RE Project Sylpheed/sylph_extract/hidden/resource3d".to_string()
+        "/home/fabi/RE - Project Sylpheed/sylph_extract/hidden/resource3d".to_string()
     });
     let bytes = std::fs::read(format!("{dir}/Stage_S07.xpr")).unwrap();
     let models = Xbg7Model::stage_models(&bytes);
@@ -424,3 +424,59 @@ fn stage_models_quality_audit() {
     assert!(huge < models.len() / 20, "few huge (skybox-plane) models");
     assert!(worst_deg < 0.35, "no model should be mostly-degenerate");
 }
+
+/// A correctly located index run has **no degenerate triangles**. That is the
+/// signature the 2026-08-13 pad-scoring fix keys on: an index list read one
+/// element late still passes every count-based gate but wires arbitrary
+/// vertices, which produces triangles with a repeated index. Before the fix
+/// **579** decoded runs on the disc carried such triangles (and a runtime
+/// capture confirmed 17 of 93 index batches disagreed with the GPU); after it and
+/// the two follow-ups (pad scoring in the grouped path, and preferring a
+/// degenerate-free candidate over an earlier dirty one), exactly **one** does.
+/// Locking the
+/// number in, because the defect is invisible to coverage and to the anchor
+/// oracle: every count stays correct while the geometry is mis-wired.
+#[test]
+#[ignore = "requires extracted disc models — set SYLPHEED_RES3D"]
+fn decoded_index_runs_have_almost_no_degenerate_triangles() {
+    let Some(dir) = res3d_dir() else {
+        eprintln!("SKIP: resource3d dir not found (set SYLPHEED_RES3D)");
+        return;
+    };
+    let mut files: Vec<PathBuf> = std::fs::read_dir(&dir)
+        .expect("resource3d/")
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("xpr"))
+        .collect();
+    files.sort();
+
+    let mut offenders: Vec<(String, String, usize)> = Vec::new();
+    for f in &files {
+        let Ok(bytes) = std::fs::read(f) else { continue };
+        let where_ = f.file_name().unwrap().to_string_lossy().to_string();
+        for m in Xbg7Model::stage_models(&bytes) {
+            for sm in &m.meshes {
+                let d = sm
+                    .indices
+                    .chunks_exact(3)
+                    .filter(|t| t[0] == t[1] || t[1] == t[2] || t[0] == t[2])
+                    .count();
+                if d > 0 {
+                    offenders.push((m.name.clone(), where_.clone(), d));
+                }
+            }
+        }
+    }
+    // The one at default settings: `_rou_f402_dead` in `Stage_S09`, whose
+    // degenerate-free block is claimed by `e_rou_f003_Near` — both 24-vertex
+    // bounding boxes, the identity class that needs descriptor-level data. (With
+    // `XBG7_SUBMESH_DECLS=1` four newly decoded `ptc_pack` `.dat` composites join
+    // it; that knob is off by default.) Anything else here is a regression.
+    assert!(
+        offenders.len() <= 1,
+        "{} decoded index runs contain degenerate triangles (expected ≤ 1): {:?}",
+        offenders.len(),
+        &offenders[..offenders.len().min(20)]
+    );
+}