diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e45de1a60d1..f92639353a7 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -238,6 +238,10 @@ jobs:
           cargo uninstall forc-mcp || true
           rm -f "${CARGO_HOME:-$HOME/.cargo}/bin/forc-mcp"
           for dir in ./forc-plugins/*/; do
+                # Dev-only plugins are not installed for docs / release tooling.
+                case "$(basename "$dir")" in
+                  forc-ir-inspect) continue ;;
+                esac
                 cargo install --locked --path "$dir"
           done
           cargo install --locked --debug --git https://github.com/FuelLabs/forc forc-crypto
diff --git a/Cargo.lock b/Cargo.lock
index b1de31b38d1..feeed3856f0 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -235,6 +235,26 @@ version = "1.0.102"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
 
+[[package]]
+name = "arboard"
+version = "3.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0348a1c054491f4bfe6ab86a7b6ab1e44e45d899005de92f58b3df180b36ddaf"
+dependencies = [
+ "clipboard-win",
+ "image",
+ "log",
+ "objc2",
+ "objc2-app-kit",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+ "objc2-foundation",
+ "parking_lot",
+ "percent-encoding",
+ "windows-sys 0.60.2",
+ "x11rb",
+]
+
 [[package]]
 name = "arc-swap"
 version = "1.9.1"
@@ -786,12 +806,24 @@ dependencies = [
  "syn 1.0.109",
 ]
 
+[[package]]
+name = "bytemuck"
+version = "1.25.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95832e849adfb21180ccb6826a99da14e5d266ae5c2e668e1602cf234f153797"
+
 [[package]]
 name = "byteorder"
 version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
 
+[[package]]
+name = "byteorder-lite"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495"
+
 [[package]]
 name = "bytes"
 version = "1.11.1"
@@ -822,12 +854,27 @@ dependencies = [
  "unicode-normalization",
 ]
 
+[[package]]
+name = "cassowary"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df8670b8c7b9dae1793364eafadf7239c40d669904660c5960d74cfd80b46a53"
+
 [[package]]
 name = "cast"
 version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "37b2a672a2cb129a2e41c10b1224bb368f9f37a2b16b612598138befd7b37eb5"
 
+[[package]]
+name = "castaway"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dec551ab6e7578819132c713a93c022a05d60159dc86e7a7050223577484c55a"
+dependencies = [
+ "rustversion",
+]
+
 [[package]]
 name = "cc"
 version = "1.2.62"
@@ -1126,6 +1173,20 @@ version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "55b672471b4e9f9e95499ea597ff64941a309b2cdbffcc46f2cc5e2d971fd335"
 
+[[package]]
+name = "compact_str"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7fd622ebbb56a5b2ccb651b32b911cdeb2a9b4b11776b2473bf26a26a286244e"
+dependencies = [
+ "castaway",
+ "cfg-if",
+ "itoa",
+ "rustversion",
+ "ryu",
+ "static_assertions",
+]
+
 [[package]]
 name = "completest"
 version = "0.4.2"
@@ -1378,6 +1439,31 @@ version = "0.8.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
 
+[[package]]
+name = "crossterm"
+version = "0.28.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "829d955a0bb380ef178a640b91779e3987da38c9aea133b20614cfed8cdea9c6"
+dependencies = [
+ "bitflags 2.11.1",
+ "crossterm_winapi",
+ "mio",
+ "parking_lot",
+ "rustix 0.38.44",
+ "signal-hook",
+ "signal-hook-mio",
+ "winapi",
+]
+
+[[package]]
+name = "crossterm_winapi"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "acdd7c62a3665c7f6830a51635d9ac9b23ed385797f70a83bb8bafe9c572ab2b"
+dependencies = [
+ "winapi",
+]
+
 [[package]]
 name = "crunchy"
 version = "0.2.4"
@@ -1540,6 +1626,16 @@ dependencies = [
  "darling_macro 0.23.0",
 ]
 
+[[package]]
+name = "darling"
+version = "0.24.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed17f5901b6630b993ca003def43f2f8ef4014fc13b047b57aad617ff32bc2ec"
+dependencies = [
+ "darling_core 0.24.1",
+ "darling_macro 0.24.1",
+]
+
 [[package]]
 name = "darling_core"
 version = "0.20.11"
@@ -1567,6 +1663,19 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "darling_core"
+version = "0.24.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6837e2cf7485aaae18f86181d2f0e9a7ed297a025e220aeabf63fdebd3a2ddff"
+dependencies = [
+ "ident_case",
+ "proc-macro2",
+ "quote",
+ "strsim 0.11.1",
+ "syn 3.0.3",
+]
+
 [[package]]
 name = "darling_macro"
 version = "0.20.11"
@@ -1589,6 +1698,17 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "darling_macro"
+version = "0.24.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ac7135c3ef02b2f7833bbeb1be5ba7f966dcde8a87c6b87f65a778d71a02785"
+dependencies = [
+ "darling_core 0.24.1",
+ "quote",
+ "syn 3.0.3",
+]
+
 [[package]]
 name = "dashmap"
 version = "5.5.3"
@@ -1881,6 +2001,16 @@ dependencies = [
  "winapi",
 ]
 
+[[package]]
+name = "dispatch2"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e0e367e4e7da84520dedcac1901e4da967309406d1e51017ae1abfb97adbd38"
+dependencies = [
+ "bitflags 2.11.1",
+ "objc2",
+]
+
 [[package]]
 name = "displaydoc"
 version = "0.2.5"
@@ -2329,6 +2459,12 @@ dependencies = [
  "bytes",
 ]
 
+[[package]]
+name = "fax"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "caf1079563223d5d59d83c85886a56e586cfd5c1a26292e971a0fa266531ac5a"
+
 [[package]]
 name = "fd-lock"
 version = "4.0.4"
@@ -2340,6 +2476,15 @@ dependencies = [
  "windows-sys 0.59.0",
 ]
 
+[[package]]
+name = "fdeflate"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c"
+dependencies = [
+ "simd-adler32",
+]
+
 [[package]]
 name = "ff"
 version = "0.13.1"
@@ -2549,6 +2694,22 @@ dependencies = [
  "tracing",
 ]
 
+[[package]]
+name = "forc-ir-inspect"
+version = "0.72.0"
+dependencies = [
+ "anyhow",
+ "arboard",
+ "clap",
+ "crossterm",
+ "dirs",
+ "prettydiff",
+ "ratatui",
+ "serde",
+ "serde_json",
+ "walkdir",
+]
+
 [[package]]
 name = "forc-lsp"
 version = "0.72.0"
@@ -3382,6 +3543,16 @@ dependencies = [
  "zeroize",
 ]
 
+[[package]]
+name = "gethostname"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bd49230192a3797a9a4d6abe9b3eed6f7fa4c8a8a4947977c6f80025f92cbd8"
+dependencies = [
+ "rustix 1.1.4",
+ "windows-link",
+]
+
 [[package]]
 name = "getrandom"
 version = "0.2.17"
@@ -3644,6 +3815,8 @@ version = "0.15.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
 dependencies = [
+ "allocator-api2",
+ "equivalent",
  "foldhash",
 ]
 
@@ -4078,6 +4251,20 @@ dependencies = [
  "version_check",
 ]
 
+[[package]]
+name = "image"
+version = "0.25.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85ab80394333c02fe689eaf900ab500fbd0c2213da414687ebf995a65d5a6104"
+dependencies = [
+ "bytemuck",
+ "byteorder-lite",
+ "moxcms",
+ "num-traits",
+ "png",
+ "tiff",
+]
+
 [[package]]
 name = "impl-codec"
 version = "0.6.0"
@@ -4212,6 +4399,19 @@ dependencies = [
  "tempfile",
 ]
 
+[[package]]
+name = "instability"
+version = "0.3.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2bf84e73fa6f27f299dec58e13223cf70db80da872eb921d4f6138342a0eabc8"
+dependencies = [
+ "darling 0.24.1",
+ "indoc",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
 [[package]]
 name = "ipnet"
 version = "2.12.0"
@@ -4640,6 +4840,15 @@ dependencies = [
  "logos-codegen",
 ]
 
+[[package]]
+name = "lru"
+version = "0.12.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "234cf4f4a04dc1f57e24b96cc0cd600cf2af460d4161ac5ecdd0af8e1f3b2a38"
+dependencies = [
+ "hashbrown 0.15.5",
+]
+
 [[package]]
 name = "lru-slab"
 version = "0.1.2"
@@ -4796,10 +5005,21 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "50b7e5b27aa02a74bac8c3f23f448f8d87ff11f92d3aac1a6ed369ee08cc56c1"
 dependencies = [
  "libc",
+ "log",
  "wasi",
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "moxcms"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb85c154ba489f01b25c0d36ae69a87e4a1c73a72631fc6c0eb6dde34a73e44b"
+dependencies = [
+ "num-traits",
+ "pxfm",
+]
+
 [[package]]
 name = "multibase"
 version = "0.9.2"
@@ -5046,6 +5266,79 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "objc2"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a12a8ed07aefc768292f076dc3ac8c48f3781c8f2d5851dd3d98950e8c5a89f"
+dependencies = [
+ "objc2-encode",
+]
+
+[[package]]
+name = "objc2-app-kit"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d49e936b501e5c5bf01fda3a9452ff86dc3ea98ad5f283e1455153142d97518c"
+dependencies = [
+ "bitflags 2.11.1",
+ "objc2",
+ "objc2-core-graphics",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "objc2-core-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536"
+dependencies = [
+ "bitflags 2.11.1",
+ "dispatch2",
+ "objc2",
+]
+
+[[package]]
+name = "objc2-core-graphics"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e022c9d066895efa1345f8e33e584b9f958da2fd4cd116792e15e07e4720a807"
+dependencies = [
+ "bitflags 2.11.1",
+ "dispatch2",
+ "objc2",
+ "objc2-core-foundation",
+ "objc2-io-surface",
+]
+
+[[package]]
+name = "objc2-encode"
+version = "4.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef25abbcd74fb2609453eb695bd2f860d389e457f67dc17cafc8b8cbc89d0c33"
+
+[[package]]
+name = "objc2-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3e0adef53c21f888deb4fa59fc59f7eb17404926ee8a6f59f5df0fd7f9f3272"
+dependencies = [
+ "bitflags 2.11.1",
+ "objc2",
+ "objc2-core-foundation",
+]
+
+[[package]]
+name = "objc2-io-surface"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "180788110936d59bab6bd83b6060ffdfffb3b922ba1396b312ae795e1de9d81d"
+dependencies = [
+ "bitflags 2.11.1",
+ "objc2",
+ "objc2-core-foundation",
+]
+
 [[package]]
 name = "object"
 version = "0.36.7"
@@ -5568,6 +5861,19 @@ dependencies = [
  "plotters-backend",
 ]
 
+[[package]]
+name = "png"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61"
+dependencies = [
+ "bitflags 2.11.1",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide",
+]
+
 [[package]]
 name = "portable-atomic"
 version = "1.13.1"
@@ -5887,12 +6193,24 @@ version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bd348ff538bc9caeda7ee8cad2d1d48236a1f443c1fa3913c6a02fe0043b1dd3"
 
+[[package]]
+name = "pxfm"
+version = "0.1.30"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea"
+
 [[package]]
 name = "quick-error"
 version = "1.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0"
 
+[[package]]
+name = "quick-error"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
+
 [[package]]
 name = "quick-xml"
 version = "0.39.4"
@@ -6072,6 +6390,27 @@ dependencies = [
  "rand_core 0.6.4",
 ]
 
+[[package]]
+name = "ratatui"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eabd94c2f37801c20583fc49dd5cd6b0ba68c716787c2dd6ed18571e1e63117b"
+dependencies = [
+ "bitflags 2.11.1",
+ "cassowary",
+ "compact_str",
+ "crossterm",
+ "indoc",
+ "instability",
+ "itertools 0.13.0",
+ "lru",
+ "paste",
+ "strum 0.26.3",
+ "unicode-segmentation",
+ "unicode-truncate",
+ "unicode-width 0.2.0",
+]
+
 [[package]]
 name = "rayon"
 version = "1.12.0"
@@ -6787,7 +7126,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cc6bf79ff24e648f6da1f8d1f011e9cac26491b619e6b9280f2b47f1774e6ee2"
 dependencies = [
  "fnv",
- "quick-error",
+ "quick-error 1.2.3",
  "tempfile",
  "wait-timeout",
 ]
@@ -6809,7 +7148,7 @@ dependencies = [
  "nix 0.29.0",
  "radix_trie",
  "unicode-segmentation",
- "unicode-width 0.2.2",
+ "unicode-width 0.2.0",
  "utf8parse",
  "windows-sys 0.59.0",
 ]
@@ -7285,6 +7624,17 @@ dependencies = [
  "signal-hook-registry",
 ]
 
+[[package]]
+name = "signal-hook-mio"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b75a19a7a740b25bc7944bdee6172368f988763b744e3d4dfe753f6b4ece40cc"
+dependencies = [
+ "libc",
+ "mio",
+ "signal-hook",
+]
+
 [[package]]
 name = "signal-hook-registry"
 version = "1.4.8"
@@ -7658,7 +8008,6 @@ name = "sway-ir"
 version = "0.72.0"
 dependencies = [
  "anyhow",
- "clap",
  "downcast-rs",
  "filecheck",
  "indexmap 2.14.0",
@@ -7841,6 +8190,17 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "syn"
+version = "3.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
 [[package]]
 name = "sync_wrapper"
 version = "1.0.2"
@@ -8092,7 +8452,7 @@ checksum = "c13547615a44dc9c452a8a534638acdf07120d4b6847c8178705da06306a3057"
 dependencies = [
  "smawk",
  "unicode-linebreak",
- "unicode-width 0.2.2",
+ "unicode-width 0.2.0",
 ]
 
 [[package]]
@@ -8159,6 +8519,20 @@ dependencies = [
  "num_cpus",
 ]
 
+[[package]]
+name = "tiff"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b63feaf3343d35b6ca4d50483f94843803b0f51634937cc2ec519fc32232bc52"
+dependencies = [
+ "fax",
+ "flate2",
+ "half",
+ "quick-error 2.0.1",
+ "weezl",
+ "zune-jpeg",
+]
+
 [[package]]
 name = "tikv-jemalloc-sys"
 version = "0.6.1+5.3.0-1-ge13ca993e8ccb9ba9847cc330696e02839f328f7"
@@ -8707,6 +9081,17 @@ version = "1.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9629274872b2bfaf8d66f5f15725007f635594914870f65218920345aa11aa8c"
 
+[[package]]
+name = "unicode-truncate"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b3644627a5af5fa321c95b9b235a72fd24cd29c648c2c379431e6628655627bf"
+dependencies = [
+ "itertools 0.13.0",
+ "unicode-segmentation",
+ "unicode-width 0.1.14",
+]
+
 [[package]]
 name = "unicode-width"
 version = "0.1.14"
@@ -8715,9 +9100,9 @@ checksum = "7dd6e30e90baa6f72411720665d41d89b9a3d039dc45b8faea1ddd07f617f6af"
 
 [[package]]
 name = "unicode-width"
-version = "0.2.2"
+version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
+checksum = "1fc81956842c57dac11422a97c3b8195a1ff727f06e85c84ed2e8aa277c9a0fd"
 
 [[package]]
 name = "unicode-xid"
@@ -9055,6 +9440,12 @@ version = "0.25.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5f20c57d8d7db6d3b86154206ae5d8fba62dd39573114de97c2cb0578251f8e1"
 
+[[package]]
+name = "weezl"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a28ac98ddc8b9274cb41bb4d9d4d5c425b6020c50c46f25559911905610b4a88"
+
 [[package]]
 name = "which"
 version = "6.0.3"
@@ -9575,6 +9966,23 @@ dependencies = [
  "tap",
 ]
 
+[[package]]
+name = "x11rb"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9993aa5be5a26815fe2c3eacfc1fde061fc1a1f094bf1ad2a18bf9c495dd7414"
+dependencies = [
+ "gethostname",
+ "rustix 1.1.4",
+ "x11rb-protocol",
+]
+
+[[package]]
+name = "x11rb-protocol"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea6fc2961e4ef194dcbfe56bb845534d0dc8098940c7e5c012a258bfec6701bd"
+
 [[package]]
 name = "xattr"
 version = "1.6.1"
@@ -9728,3 +10136,18 @@ name = "zmij"
 version = "1.0.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
+
+[[package]]
+name = "zune-core"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d56377fd46368984a170bc5aac5567e52ca5da874caa60bea39fcbca78fb658b"
+
+[[package]]
+name = "zune-jpeg"
+version = "0.5.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27bc9d5b815bc103f142aa054f561d9187d191692ec7c2d1e2b4737f8dbd7296"
+dependencies = [
+ "zune-core",
+]
diff --git a/Cargo.toml b/Cargo.toml
index b30095707ec..80fa7071e66 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -109,6 +109,7 @@ fuel-vm = "0.66"
 annotate-snippets = "0.10"
 ansiterm = "0.12"
 anyhow = "1.0"
+arboard = "3.4"
 assert-json-diff = "2.0"
 assert_matches = "1.5"
 async-trait = "0.1"
@@ -126,6 +127,7 @@ completest-pty = "0.5"
 comrak = "0.28"
 criterion = "0.5"
 crossbeam-channel = "0.5"
+crossterm = "0.28"
 dap = "0.4.1-alpha"
 dashmap = "6.1"
 devault = "0.2"
@@ -189,6 +191,7 @@ prettydiff = "0.7"
 proc-macro2 = "1.0"
 quote = "1.0"
 rand = "0.8"
+ratatui = "0.29"
 rayon = "1.7"
 rayon-cond = "0.3"
 regex = "1.10"
diff --git a/forc-plugins/forc-ir-inspect/Cargo.toml b/forc-plugins/forc-ir-inspect/Cargo.toml
new file mode 100644
index 00000000000..ded0b200b44
--- /dev/null
+++ b/forc-plugins/forc-ir-inspect/Cargo.toml
@@ -0,0 +1,29 @@
+[package]
+name = "forc-ir-inspect"
+version.workspace = true
+description = "Dev-only forc plugin for browsing Sway IR dumps (not released)."
+authors.workspace = true
+edition.workspace = true
+homepage.workspace = true
+license.workspace = true
+repository.workspace = true
+publish = false
+
+[[bin]]
+name = "forc-ir-inspect"
+path = "src/main.rs"
+
+[dependencies]
+anyhow.workspace = true
+arboard.workspace = true
+clap = { workspace = true, features = ["derive"] }
+crossterm.workspace = true
+dirs.workspace = true
+prettydiff.workspace = true
+ratatui.workspace = true
+serde = { workspace = true, features = ["derive"] }
+serde_json.workspace = true
+walkdir.workspace = true
+
+[lints]
+workspace = true
diff --git a/forc-plugins/forc-ir-inspect/src/classic.rs b/forc-plugins/forc-ir-inspect/src/classic.rs
new file mode 100644
index 00000000000..2e4e3b90cbc
--- /dev/null
+++ b/forc-plugins/forc-ir-inspect/src/classic.rs
@@ -0,0 +1,86 @@
+//! Classic (non-TUI) printer — the original inspect output path.
+
+use std::io::{IsTerminal, Write};
+
+use anyhow::{bail, Result};
+
+use crate::parse::{
+    diff_stats, has_metadata_defs, parse_source_map, prepare_ir_text, print_diff, print_diff_stats,
+    print_final_ir, FuncStats, MdMode, ParsedIr, PrintMode, VersionMode,
+};
+
+pub(crate) fn run(
+    irs: &[ParsedIr],
+    cleaned: &str,
+    filter_fn: &[String],
+    mode: PrintMode,
+    metadata: MdMode,
+    version: VersionMode,
+    source: bool,
+) -> Result<()> {
+    if source && !has_metadata_defs(cleaned) {
+        eprintln!(
+            "warning: `--print source` was requested but the input contains no metadata \
+             definitions (`!N = ...`).\n  \
+             Regenerate the IR dump with the `print-md` flag, e.g. \
+             `forc build --ir all,print-md`, so the span/file metadata is emitted."
+        );
+    }
+
+    let stdout = std::io::stdout();
+    let is_terminal = stdout.is_terminal();
+    let mut out = stdout.lock();
+
+    let mut previous_ir: Option<String> = None;
+
+    for ir in irs {
+        if ir.is_initial() {
+            previous_ir = None;
+        }
+
+        let Some(final_ir) = prepare_ir_text(filter_fn, metadata, version, ir) else {
+            continue;
+        };
+
+        let mut source_map = if source {
+            Some(parse_source_map(&ir.body))
+        } else {
+            None
+        };
+
+        writeln!(out, "// IR: {}", ir.pass_name)?;
+
+        if mode == PrintMode::Diff {
+            if let Some(prev_text) = previous_ir.as_ref() {
+                let changeset = prettydiff::diff_lines(prev_text, &final_ir);
+                let ops = changeset.diff();
+                let (adds, removes) = diff_stats(&ops);
+                if adds == 0 && removes == 0 {
+                    print_diff_stats(&mut out, adds, removes)?;
+                } else {
+                    let cur_stats = FuncStats::compute_stats(&final_ir);
+                    let prev_stats = previous_ir.as_ref().map(|p| FuncStats::compute_stats(p));
+                    cur_stats.print_fn_stats(&mut out, prev_stats.as_ref())?;
+                    print_diff_stats(&mut out, adds, removes)?;
+                    print_diff(&mut out, &ops, is_terminal)?;
+                }
+            } else {
+                let cur_stats = FuncStats::compute_stats(&final_ir);
+                cur_stats.print_fn_stats(&mut out, None)?;
+                print_final_ir(&mut out, &final_ir, source_map.as_mut())?;
+            }
+        } else {
+            let cur_stats = FuncStats::compute_stats(&final_ir);
+            cur_stats.print_fn_stats(&mut out, None)?;
+            print_final_ir(&mut out, &final_ir, source_map.as_mut())?;
+        }
+
+        previous_ir = Some(final_ir);
+    }
+
+    if irs.is_empty() {
+        bail!("no `// IR:` dumps found in input");
+    }
+
+    Ok(())
+}
diff --git a/forc-plugins/forc-ir-inspect/src/config.rs b/forc-plugins/forc-ir-inspect/src/config.rs
new file mode 100644
index 00000000000..e060b050bf4
--- /dev/null
+++ b/forc-plugins/forc-ir-inspect/src/config.rs
@@ -0,0 +1,239 @@
+//! Persistent TUI session state under the OS config directory.
+//!
+//! - macOS / Linux: `~/.config/forc-ir-inspect/` (or `$XDG_CONFIG_HOME`)
+//! - Windows: `%APPDATA%\forc-ir-inspect\`
+
+use std::collections::BTreeMap;
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+
+use crate::parse::{MdMode, VersionMode};
+
+const CONFIG_VERSION: u32 = 1;
+const CONFIG_FILE: &str = "tui.json";
+const LEGACY_SOURCE_ROOT: &str = "source_root";
+
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub(crate) struct TuiConfigFile {
+    #[serde(default = "default_version")]
+    pub version: u32,
+    #[serde(default)]
+    pub source_root: Option<PathBuf>,
+    #[serde(default)]
+    pub sessions: BTreeMap<String, SessionState>,
+}
+
+fn default_version() -> u32 {
+    CONFIG_VERSION
+}
+
+fn default_true() -> bool {
+    true
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub(crate) struct SessionState {
+    #[serde(default)]
+    pub focus: FocusName,
+    #[serde(default)]
+    pub pass_filter: String,
+    #[serde(default)]
+    pub fn_filter: String,
+    #[serde(default)]
+    pub search: String,
+    #[serde(default)]
+    pub scroll: u16,
+    #[serde(default)]
+    pub h_scroll: u16,
+    #[serde(default)]
+    pub show_diff: bool,
+    #[serde(default = "default_true")]
+    pub show_line_numbers: bool,
+    #[serde(default = "default_true")]
+    pub syntax_highlight: bool,
+    #[serde(default)]
+    pub metadata: MdModeName,
+    #[serde(default)]
+    pub version: VersionModeName,
+    #[serde(default)]
+    pub show_source: bool,
+    #[serde(default)]
+    pub selected_project: Option<String>,
+    #[serde(default)]
+    pub selected_pass: Option<String>,
+    #[serde(default)]
+    pub expanded_projects: Vec<String>,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, Default, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum FocusName {
+    #[default]
+    Tree,
+    Main,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, Default, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum MdModeName {
+    #[default]
+    AsParsed,
+    With,
+    Without,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, Default, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum VersionModeName {
+    #[default]
+    AsParsed,
+    With,
+    Without,
+}
+
+impl From<MdMode> for MdModeName {
+    fn from(m: MdMode) -> Self {
+        match m {
+            MdMode::AsParsed => Self::AsParsed,
+            MdMode::With => Self::With,
+            MdMode::Without => Self::Without,
+        }
+    }
+}
+
+impl From<MdModeName> for MdMode {
+    fn from(m: MdModeName) -> Self {
+        match m {
+            MdModeName::AsParsed => Self::AsParsed,
+            MdModeName::With => Self::With,
+            MdModeName::Without => Self::Without,
+        }
+    }
+}
+
+impl From<VersionMode> for VersionModeName {
+    fn from(m: VersionMode) -> Self {
+        match m {
+            VersionMode::AsParsed => Self::AsParsed,
+            VersionMode::With => Self::With,
+            VersionMode::Without => Self::Without,
+        }
+    }
+}
+
+impl From<VersionModeName> for VersionMode {
+    fn from(m: VersionModeName) -> Self {
+        match m {
+            VersionModeName::AsParsed => Self::AsParsed,
+            VersionModeName::With => Self::With,
+            VersionModeName::Without => Self::Without,
+        }
+    }
+}
+
+/// Prefer XDG-style `~/.config` on all Unix platforms (including macOS).
+/// Windows keeps `%APPDATA%` via `dirs::config_dir`.
+pub(crate) fn config_dir() -> Option<PathBuf> {
+    #[cfg(windows)]
+    {
+        Some(dirs::config_dir()?.join("forc-ir-inspect"))
+    }
+    #[cfg(not(windows))]
+    {
+        let base = std::env::var_os("XDG_CONFIG_HOME")
+            .map(PathBuf::from)
+            .filter(|p| !p.as_os_str().is_empty())
+            .or_else(|| dirs::home_dir().map(|h| h.join(".config")))?;
+        Some(base.join("forc-ir-inspect"))
+    }
+}
+
+pub(crate) fn config_path() -> Option<PathBuf> {
+    Some(config_dir()?.join(CONFIG_FILE))
+}
+
+pub(crate) fn session_key(cmd: Option<&str>, input_path: Option<&str>) -> String {
+    if let Some(cmd) = cmd {
+        format!("cmd:{cmd}")
+    } else if let Some(path) = input_path {
+        let p = PathBuf::from(path);
+        let abs = p
+            .canonicalize()
+            .unwrap_or_else(|_| std::env::current_dir().map(|c| c.join(&p)).unwrap_or(p));
+        format!("path:{}", abs.display())
+    } else {
+        String::from("default")
+    }
+}
+
+pub(crate) fn load_config() -> TuiConfigFile {
+    let mut cfg: TuiConfigFile = config_path()
+        .and_then(|path| fs::read_to_string(path).ok())
+        .and_then(|raw| serde_json::from_str(&raw).ok())
+        .unwrap_or_default();
+    cfg.version = CONFIG_VERSION;
+
+    // Migrate the previous single-file source-root setting.
+    if cfg.source_root.is_none() {
+        if let Some(legacy) = load_legacy_source_root() {
+            cfg.source_root = Some(legacy);
+        }
+    }
+    if let Some(root) = &cfg.source_root {
+        if !root.is_dir() {
+            cfg.source_root = None;
+        }
+    }
+    cfg
+}
+
+fn load_legacy_source_root() -> Option<PathBuf> {
+    let path = config_dir()?.join(LEGACY_SOURCE_ROOT);
+    let raw = fs::read_to_string(path).ok()?;
+    let trimmed = raw.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    let p = PathBuf::from(trimmed);
+    p.is_dir().then_some(p)
+}
+
+pub(crate) fn save_config(cfg: &TuiConfigFile) -> std::io::Result<()> {
+    let path = config_path().ok_or_else(|| {
+        std::io::Error::new(std::io::ErrorKind::NotFound, "no OS config directory")
+    })?;
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent)?;
+    }
+    let raw = serde_json::to_string_pretty(cfg)
+        .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;
+    let tmp = path.with_extension("json.tmp");
+    fs::write(&tmp, raw)?;
+    fs::rename(&tmp, &path)?;
+    Ok(())
+}
+
+pub(crate) fn load_session(
+    cmd: Option<&str>,
+    input_path: Option<&str>,
+) -> (TuiConfigFile, Option<SessionState>) {
+    let cfg = load_config();
+    let key = session_key(cmd, input_path);
+    let session = cfg.sessions.get(&key).cloned();
+    (cfg, session)
+}
+
+/// Update `source_root` and the session for this input, then write to disk.
+pub(crate) fn persist(
+    cmd: Option<&str>,
+    input_path: Option<&str>,
+    source_root: Option<&Path>,
+    session: SessionState,
+) -> std::io::Result<()> {
+    let mut cfg = load_config();
+    cfg.source_root = source_root.map(Path::to_path_buf);
+    cfg.sessions.insert(session_key(cmd, input_path), session);
+    save_config(&cfg)
+}
diff --git a/forc-plugins/forc-ir-inspect/src/highlight.rs b/forc-plugins/forc-ir-inspect/src/highlight.rs
new file mode 100644
index 00000000000..177cda9fd2f
--- /dev/null
+++ b/forc-plugins/forc-ir-inspect/src/highlight.rs
@@ -0,0 +1,1088 @@
+//! Basic Sway-IR syntax highlighting for the TUI main panel.
+
+use ratatui::style::{Color, Modifier, Style};
+use ratatui::text::{Line, Span};
+
+/// Token styles used by the highlighter.
+#[derive(Clone, Copy)]
+enum Kind {
+    Comment,
+    Keyword,
+    Opcode,
+    Type,
+    Number,
+    String,
+    Metadata,
+    Label,
+    Ident,
+    Punct,
+    DiffAdd,
+    DiffRemove,
+    DiffContext,
+    /// Embedded Sway source lines (`  | …`) from the source overlay.
+    Source,
+    Plain,
+}
+
+impl Kind {
+    fn style(self) -> Style {
+        match self {
+            Kind::Comment => Style::default().fg(Color::DarkGray),
+            Kind::Keyword => Style::default()
+                .fg(Color::Magenta)
+                .add_modifier(Modifier::BOLD),
+            Kind::Opcode => Style::default().fg(Color::Cyan),
+            Kind::Type => Style::default().fg(Color::Yellow),
+            Kind::Number => Style::default().fg(Color::LightGreen),
+            Kind::String => Style::default().fg(Color::Green),
+            Kind::Metadata => Style::default().fg(Color::LightBlue),
+            Kind::Label => Style::default()
+                .fg(Color::LightYellow)
+                .add_modifier(Modifier::BOLD),
+            Kind::Ident => Style::default().fg(Color::White),
+            Kind::Punct => Style::default().fg(Color::Gray),
+            // Very dark backgrounds so syntax colors stay readable.
+            Kind::DiffAdd => Style::default()
+                .fg(Color::Rgb(160, 230, 160))
+                .bg(Color::Rgb(0, 32, 0)),
+            Kind::DiffRemove => Style::default()
+                .fg(Color::Rgb(230, 160, 160))
+                .bg(Color::Rgb(32, 0, 0)),
+            Kind::DiffContext => Style::default().fg(Color::DarkGray),
+            Kind::Source => Style::default().fg(Color::Rgb(120, 200, 140)),
+            Kind::Plain => Style::default(),
+        }
+    }
+}
+
+const DIFF_ADD_BG: Color = Color::Rgb(0, 32, 0);
+const DIFF_REMOVE_BG: Color = Color::Rgb(32, 0, 0);
+
+const KEYWORDS: &[&str] = &[
+    "fn",
+    "pub",
+    "entry",
+    "entry_orig",
+    "fallback",
+    "local",
+    "mut",
+    "script",
+    "contract",
+    "predicate",
+    "library",
+    "global",
+    "configurable",
+    "storage_key",
+    "true",
+    "false",
+    "to",
+    "key",
+    "x",
+    "wide",
+    "inline",
+    "span",
+];
+
+const TYPES: &[&str] = &[
+    "bool", "u8", "u16", "u32", "u64", "u256", "b256", "unit", "string", "__ptr", "ptr",
+];
+
+const OPCODES: &[&str] = &[
+    "add",
+    "sub",
+    "mul",
+    "div",
+    "and",
+    "or",
+    "xor",
+    "lsh",
+    "rsh",
+    "mod",
+    "not",
+    "eq",
+    "lt",
+    "gt",
+    "asm",
+    "bitcast",
+    "br",
+    "call",
+    "cast_ptr",
+    "cbr",
+    "cmp",
+    "const",
+    "contract_call",
+    "get_elem_ptr",
+    "get_local",
+    "get_global",
+    "get_config",
+    "get_storage_key",
+    "gtf",
+    "int_to_ptr",
+    "alloc",
+    "load",
+    "log",
+    "mem_copy_bytes",
+    "mem_copy_val",
+    "mem_clear_val",
+    "nop",
+    "ptr_to_int",
+    "read_register",
+    "ret",
+    "retd",
+    "revert",
+    "jmp_mem",
+    "smo",
+    "state_clear",
+    "state_clear_slots",
+    "state_load_quad_word",
+    "state_read_slot",
+    "state_load_word",
+    "state_store_quad_word",
+    "state_write_slot",
+    "state_update_slot",
+    "state_preload",
+    "state_store_word",
+    "store",
+    "init_aggr",
+];
+
+/// Highlight a full IR (or diff) document into styled lines.
+pub(crate) fn highlight_ir(text: &str, is_diff: bool) -> Vec<Line<'static>> {
+    text.lines()
+        .map(|line| highlight_line(line, is_diff))
+        .collect()
+}
+
+fn highlight_line(line: &str, is_diff: bool) -> Line<'static> {
+    // Diff prefixes from prettydiff-style output.
+    let (prefix, rest, diff_kind) = if is_diff {
+        if let Some(r) = line.strip_prefix("+ ") {
+            ("+ ", r, Some(Kind::DiffAdd))
+        } else if let Some(r) = line.strip_prefix("- ") {
+            ("- ", r, Some(Kind::DiffRemove))
+        } else if let Some(r) = line.strip_prefix("  ") {
+            ("  ", r, Some(Kind::DiffContext))
+        } else {
+            ("", line, None)
+        }
+    } else {
+        ("", line, None)
+    };
+
+    // Full-line comments / embedded source lines from the source overlay.
+    let trimmed = rest.trim_start();
+    let built = if trimmed.starts_with("//") {
+        let mut spans = Vec::new();
+        if !prefix.is_empty() {
+            spans.push(Span::styled(
+                prefix.to_string(),
+                diff_kind.unwrap_or(Kind::Plain).style(),
+            ));
+        }
+        spans.push(Span::styled(rest.to_string(), Kind::Comment.style()));
+        Line::from(spans)
+    } else if rest.starts_with("  |") || trimmed.starts_with("| ") {
+        // `  | <source>` lines inserted by the source overlay.
+        let mut spans = Vec::new();
+        if !prefix.is_empty() {
+            spans.push(Span::styled(
+                prefix.to_string(),
+                diff_kind.unwrap_or(Kind::Plain).style(),
+            ));
+        }
+        spans.push(Span::styled(rest.to_string(), Kind::Source.style()));
+        Line::from(spans)
+    } else if looks_like_label(trimmed) {
+        // Block labels: `name():` or `name:`
+        let mut spans = Vec::new();
+        if !prefix.is_empty() {
+            spans.push(Span::styled(
+                prefix.to_string(),
+                diff_kind.unwrap_or(Kind::Plain).style(),
+            ));
+        }
+        let lead = rest.len() - trimmed.len();
+        if lead > 0 {
+            spans.push(Span::raw(rest[..lead].to_string()));
+        }
+        spans.push(Span::styled(trimmed.to_string(), Kind::Label.style()));
+        Line::from(spans)
+    } else {
+        let mut spans = Vec::new();
+        if !prefix.is_empty() {
+            spans.push(Span::styled(
+                prefix.to_string(),
+                diff_kind.unwrap_or(Kind::Plain).style(),
+            ));
+        }
+        spans.extend(tokenize(rest));
+        Line::from(spans)
+    };
+
+    apply_diff_background(built, diff_kind)
+}
+
+/// Paint the whole line with a very dark red/green background for diffs.
+fn apply_diff_background(line: Line<'static>, diff_kind: Option<Kind>) -> Line<'static> {
+    let bg = match diff_kind {
+        Some(Kind::DiffAdd) => DIFF_ADD_BG,
+        Some(Kind::DiffRemove) => DIFF_REMOVE_BG,
+        _ => return line,
+    };
+    let spans: Vec<Span<'static>> = line
+        .spans
+        .into_iter()
+        .map(|s| Span::styled(s.content.to_string(), s.style.bg(bg)))
+        .collect();
+    Line::from(spans).style(Style::default().bg(bg))
+}
+
+fn looks_like_label(trimmed: &str) -> bool {
+    if !trimmed.ends_with(':') {
+        return false;
+    }
+    let name = trimmed.trim_end_matches(':').trim_end_matches("()");
+    !name.is_empty()
+        && name
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '_')
+}
+
+fn tokenize(s: &str) -> Vec<Span<'static>> {
+    let bytes = s.as_bytes();
+    let mut spans = Vec::new();
+    let mut i = 0usize;
+
+    while i < bytes.len() {
+        // Keep `i` on a char boundary at the top of every iteration.
+        debug_assert!(s.is_char_boundary(i));
+
+        // Whitespace (ASCII only; Unicode whitespace is emitted below).
+        if bytes[i].is_ascii_whitespace() {
+            let start = i;
+            while i < bytes.len() && bytes[i].is_ascii_whitespace() {
+                i += 1;
+            }
+            spans.push(Span::raw(s[start..i].to_string()));
+            continue;
+        }
+
+        // Line comment
+        if bytes[i] == b'/' && i + 1 < bytes.len() && bytes[i + 1] == b'/' {
+            spans.push(Span::styled(s[i..].to_string(), Kind::Comment.style()));
+            break;
+        }
+
+        // String literal
+        if bytes[i] == b'"' {
+            let start = i;
+            i += 1;
+            while i < bytes.len() {
+                if bytes[i] == b'\\' {
+                    // Skip the backslash and the next Unicode scalar. Using
+                    // `i + 2` can land mid-UTF-8 and panic on a later slice.
+                    i += 1;
+                    if i < bytes.len() {
+                        i = next_char_boundary(s, i);
+                    }
+                    continue;
+                }
+                if bytes[i] == b'"' {
+                    i += 1;
+                    break;
+                }
+                i = next_char_boundary(s, i);
+            }
+            spans.push(Span::styled(s[start..i].to_string(), Kind::String.style()));
+            continue;
+        }
+
+        // Metadata `!123`
+        if bytes[i] == b'!' && i + 1 < bytes.len() && bytes[i + 1].is_ascii_digit() {
+            let start = i;
+            i += 1;
+            while i < bytes.len() && bytes[i].is_ascii_digit() {
+                i += 1;
+            }
+            spans.push(Span::styled(
+                s[start..i].to_string(),
+                Kind::Metadata.style(),
+            ));
+            continue;
+        }
+
+        // Number (decimal or hex)
+        if bytes[i].is_ascii_digit() {
+            let start = i;
+            if i + 1 < bytes.len()
+                && bytes[i] == b'0'
+                && (bytes[i + 1] == b'x' || bytes[i + 1] == b'X')
+            {
+                i += 2;
+                while i < bytes.len() && bytes[i].is_ascii_hexdigit() {
+                    i += 1;
+                }
+            } else {
+                while i < bytes.len() && bytes[i].is_ascii_digit() {
+                    i += 1;
+                }
+            }
+            spans.push(Span::styled(s[start..i].to_string(), Kind::Number.style()));
+            continue;
+        }
+
+        // Identifier / keyword / opcode / type
+        if is_ident_start(bytes[i]) {
+            let start = i;
+            i += 1;
+            while i < bytes.len() && is_ident_cont(bytes[i]) {
+                i += 1;
+            }
+            let word = &s[start..i];
+            let kind = classify_word(word);
+            spans.push(Span::styled(word.to_string(), kind.style()));
+            continue;
+        }
+
+        // One Unicode scalar (ASCII punct or any non-ASCII). Never slice a
+        // single byte out of a multi-byte UTF-8 character — that panics.
+        let next = next_char_boundary(s, i);
+        spans.push(Span::styled(
+            s[i..next].to_string(),
+            Kind::Punct.style(),
+        ));
+        i = next;
+    }
+
+    spans
+}
+
+/// Advance from a char boundary to the start of the following character.
+fn next_char_boundary(s: &str, i: usize) -> usize {
+    s[i..]
+        .chars()
+        .next()
+        .map(|c| i + c.len_utf8())
+        .unwrap_or(s.len())
+}
+
+fn is_ident_start(b: u8) -> bool {
+    b.is_ascii_alphabetic() || b == b'_'
+}
+
+fn is_ident_cont(b: u8) -> bool {
+    b.is_ascii_alphanumeric() || b == b'_'
+}
+
+fn classify_word(word: &str) -> Kind {
+    if KEYWORDS.contains(&word) {
+        Kind::Keyword
+    } else if OPCODES.contains(&word) {
+        Kind::Opcode
+    } else if TYPES.contains(&word) {
+        Kind::Type
+    } else {
+        Kind::Ident
+    }
+}
+
+/// Background palette for multi-SSA focus highlights (overrides syntax bg).
+/// Shared palette for SSA / local / method focus highlights.
+pub(crate) const SYMBOL_PALETTE: &[Color] = &[
+    Color::Rgb(120, 70, 0),   // amber
+    Color::Rgb(0, 90, 110),   // teal
+    Color::Rgb(110, 0, 110),  // purple
+    Color::Rgb(0, 100, 40),   // green
+    Color::Rgb(130, 30, 30),  // red
+    Color::Rgb(30, 50, 140),  // blue
+    Color::Rgb(110, 100, 0),  // olive
+    Color::Rgb(130, 50, 80),  // rose
+];
+
+/// Back-compat alias.
+pub(crate) const SSA_PALETTE: &[Color] = SYMBOL_PALETTE;
+
+/// True for Sway-IR value names like `v0`, `v12`, `v3v1`.
+pub(crate) fn is_ssa_name(s: &str) -> bool {
+    let b = s.as_bytes();
+    if b.len() < 2 || b[0] != b'v' {
+        return false;
+    }
+    let mut i = 1;
+    if i >= b.len() || !b[i].is_ascii_digit() {
+        return false;
+    }
+    while i < b.len() && b[i].is_ascii_digit() {
+        i += 1;
+    }
+    if i == b.len() {
+        return true;
+    }
+    if b[i] != b'v' {
+        return false;
+    }
+    i += 1;
+    if i >= b.len() || !b[i].is_ascii_digit() {
+        return false;
+    }
+    while i < b.len() && b[i].is_ascii_digit() {
+        i += 1;
+    }
+    i == b.len()
+}
+
+fn is_ident_byte(b: u8) -> bool {
+    b.is_ascii_alphanumeric() || b == b'_'
+}
+
+/// SSA register covering character column `col` (0-based), if any.
+pub(crate) fn ssa_at_col(line: &str, col: usize) -> Option<String> {
+    let chars: Vec<(usize, char)> = line.char_indices().collect();
+    if chars.is_empty() || col >= chars.len() {
+        return None;
+    }
+    let byte_pos = chars[col].0;
+    let bytes = line.as_bytes();
+    if !is_ident_byte(bytes[byte_pos]) {
+        return None;
+    }
+    let mut start = byte_pos;
+    while start > 0 && is_ident_byte(bytes[start - 1]) {
+        start -= 1;
+    }
+    let mut end = byte_pos + chars[col].1.len_utf8();
+    while end < bytes.len() && is_ident_byte(bytes[end]) {
+        end += 1;
+    }
+    let tok = line.get(start..end)?;
+    is_ssa_name(tok).then(|| tok.to_string())
+}
+
+
+/// Identifier token covering character column `col` (0-based), if any.
+pub(crate) fn ident_at_col(line: &str, col: usize) -> Option<String> {
+    let chars: Vec<(usize, char)> = line.char_indices().collect();
+    if chars.is_empty() || col >= chars.len() {
+        return None;
+    }
+    let byte_pos = chars[col].0;
+    let bytes = line.as_bytes();
+    if !is_ident_byte(bytes[byte_pos]) {
+        return None;
+    }
+    let mut start = byte_pos;
+    while start > 0 && is_ident_byte(bytes[start - 1]) {
+        start -= 1;
+    }
+    let mut end = byte_pos + chars[col].1.len_utf8();
+    while end < bytes.len() && is_ident_byte(bytes[end]) {
+        end += 1;
+    }
+    line.get(start..end).map(str::to_string)
+}
+
+fn is_ident_name(s: &str) -> bool {
+    let mut chars = s.chars();
+    match chars.next() {
+        Some(c) if c.is_ascii_alphabetic() || c == '_' => {
+            chars.all(|c| c.is_ascii_alphanumeric() || c == '_')
+        }
+        _ => false,
+    }
+}
+
+/// Skip one IR type (`u64`, `__ptr T`, `{…}`, `[…; N]`) and return the remainder.
+fn skip_ir_type(s: &str) -> Option<&str> {
+    let s = s.trim_start();
+    if s.is_empty() {
+        return None;
+    }
+    if s.starts_with('{') {
+        return skip_balanced(s, b'{', b'}');
+    }
+    if s.starts_with('[') {
+        return skip_balanced(s, b'[', b']');
+    }
+    // Leading ident (e.g. u64, __ptr, b256).
+    let bytes = s.as_bytes();
+    let mut i = 0usize;
+    if !is_ident_byte(bytes[0]) {
+        return None;
+    }
+    while i < bytes.len() && is_ident_byte(bytes[i]) {
+        i += 1;
+    }
+    let head = &s[..i];
+    let rest = s[i..].trim_start();
+    if head == "__ptr" || head == "ptr" {
+        return skip_ir_type(rest);
+    }
+    Some(rest)
+}
+
+fn skip_balanced<'a>(s: &'a str, open: u8, close: u8) -> Option<&'a str> {
+    let bytes = s.as_bytes();
+    if bytes.first() != Some(&open) {
+        return None;
+    }
+    let mut depth = 0i32;
+    for (i, &b) in bytes.iter().enumerate() {
+        if b == open {
+            depth += 1;
+        } else if b == close {
+            depth -= 1;
+            if depth == 0 {
+                return Some(s[i + 1..].trim_start());
+            }
+        }
+    }
+    None
+}
+
+/// Name declared by a `local [mut] <ty> <name>` line.
+pub(crate) fn local_decl_name(line: &str) -> Option<&str> {
+    let (body, _) = line_instruction_body(line);
+    let rest = body.strip_prefix("local")?.trim_start();
+    let rest = match rest.strip_prefix("mut") {
+        Some(r) => r.trim_start(),
+        None => rest,
+    };
+    let after_ty = skip_ir_type(rest)?;
+    let name = after_ty
+        .split(|c: char| c == ' ' || c == '=' || c == ',' || c == '!')
+        .next()
+        .unwrap_or("");
+    if is_ident_name(name) && !is_ssa_name(name) {
+        Some(name)
+    } else {
+        None
+    }
+}
+
+/// Local name after the comma in `get_local …, name`.
+pub(crate) fn get_local_name(line: &str) -> Option<&str> {
+    let (body, _) = line_instruction_body(line);
+    // Match both `get_local` opcode forms, including after `= `.
+    let idx = body.find("get_local")?;
+    let after = &body[idx + "get_local".len()..];
+    let after_comma = after.rsplit_once(',')?.1.trim();
+    let name = after_comma
+        .split(|c: char| c == ' ' || c == '!' || c == ',')
+        .next()
+        .unwrap_or("");
+    if is_ident_name(name) && !is_ssa_name(name) {
+        Some(name)
+    } else {
+        None
+    }
+}
+
+/// Function name from `fn name(` / `pub entry fn name(`.
+pub(crate) fn fn_def_name(line: &str) -> Option<&str> {
+    let (body, _) = line_instruction_body(line);
+    let idx = body.find("fn ")?;
+    let after = body[idx + 3..].trim_start();
+    let name = after.split(|c: char| c == '(' || c == ' ' || c == '!').next()?;
+    if is_ident_name(name) && !is_ssa_name(name) {
+        Some(name)
+    } else {
+        None
+    }
+}
+
+/// Callee from `call name(` / `= call name(`.
+pub(crate) fn call_name(line: &str) -> Option<&str> {
+    let (body, _) = line_instruction_body(line);
+    let idx = body.find("call ")?;
+    let after = body[idx + 5..].trim_start();
+    let name = after.split(|c: char| c == '(' || c == ' ' || c == '!' || c == ',').next()?;
+    if is_ident_name(name) && !is_ssa_name(name) {
+        Some(name)
+    } else {
+        None
+    }
+}
+
+pub(crate) fn text_has_local(text: &str, name: &str) -> bool {
+    text.lines().any(|line| {
+        local_decl_name(line) == Some(name) || get_local_name(line) == Some(name)
+    })
+}
+
+pub(crate) fn text_has_method(text: &str, name: &str) -> bool {
+    text.lines().any(|line| fn_def_name(line) == Some(name) || call_name(line) == Some(name))
+}
+
+/// Highlightable symbol under the cursor: SSA register, local, or method/function name.
+pub(crate) fn symbol_at_col(line: &str, col: usize, full_text: &str) -> Option<String> {
+    let tok = ident_at_col(line, col)?;
+    if is_ssa_name(&tok) {
+        return Some(tok);
+    }
+    if !is_ident_name(&tok) {
+        return None;
+    }
+    // Prefer context on this line, then dump-wide recognition.
+    if local_decl_name(line) == Some(tok.as_str())
+        || get_local_name(line) == Some(tok.as_str())
+        || fn_def_name(line) == Some(tok.as_str())
+        || call_name(line) == Some(tok.as_str())
+        || text_has_local(full_text, &tok)
+        || text_has_method(full_text, &tok)
+    {
+        return Some(tok);
+    }
+    None
+}
+
+/// Count whole-token occurrences of `name` above `view_start` / at-or-after `view_end`.
+pub(crate) fn count_token_offscreen(
+    text: &str,
+    name: &str,
+    view_start: usize,
+    view_end: usize,
+) -> (usize, usize) {
+    if name.is_empty() {
+        return (0, 0);
+    }
+    let name_bytes = name.as_bytes();
+    let mut above = 0usize;
+    let mut below = 0usize;
+    for (line_idx, line) in text.lines().enumerate() {
+        let bytes = line.as_bytes();
+        let mut start = 0usize;
+        let mut n = 0usize;
+        while start + name_bytes.len() <= bytes.len() {
+            if bytes[start..].starts_with(name_bytes)
+                && (start == 0 || !is_ident_byte(bytes[start - 1]))
+                && {
+                    let end = start + name_bytes.len();
+                    end == bytes.len() || !is_ident_byte(bytes[end])
+                }
+            {
+                n += 1;
+                start += name_bytes.len();
+            } else {
+                start += 1;
+            }
+        }
+        if line_idx < view_start {
+            above += n;
+        } else if line_idx >= view_end {
+            below += n;
+        }
+    }
+    (above, below)
+}
+
+/// Highlight IR with optional syntax coloring and search overlay.
+/// SSA focus highlights are applied separately via [`apply_ssa_highlights`].
+pub(crate) fn highlight_ir_with_search(
+    text: &str,
+    is_diff: bool,
+    search: &str,
+    current_match_line: Option<usize>,
+    syntax: bool,
+) -> Vec<Line<'static>> {
+    let mut lines: Vec<Line<'static>> = if syntax {
+        highlight_ir(text, is_diff)
+    } else if is_diff {
+        text.lines()
+            .map(|line| {
+                let style = if line.starts_with("+ ") {
+                    Kind::DiffAdd.style()
+                } else if line.starts_with("- ") {
+                    Kind::DiffRemove.style()
+                } else {
+                    Style::default().fg(Color::White)
+                };
+                Line::from(Span::styled(line.to_string(), style))
+            })
+            .collect()
+    } else {
+        text.lines()
+            .map(|line| {
+                Line::from(Span::styled(
+                    line.to_string(),
+                    Style::default().fg(Color::White),
+                ))
+            })
+            .collect()
+    };
+
+    if search.is_empty() {
+        return lines;
+    }
+
+    let needle = search.to_ascii_lowercase();
+    for (idx, styled) in lines.iter_mut().enumerate() {
+        let line_text: String = styled.spans.iter().map(|s| s.content.as_ref()).collect();
+        if !line_text.to_ascii_lowercase().contains(&needle) {
+            continue;
+        }
+        let mark = if Some(idx) == current_match_line {
+            Style::default()
+                .bg(Color::Yellow)
+                .fg(Color::Black)
+                .add_modifier(Modifier::BOLD)
+        } else {
+            Style::default().bg(Color::Rgb(60, 60, 20))
+        };
+        let content: Vec<Span> = styled
+            .spans
+            .drain(..)
+            .map(|s| {
+                let mut st = s.style;
+                if let Some(bg) = mark.bg {
+                    st = st.bg(bg);
+                }
+                if let Some(fg) = mark.fg {
+                    if Some(idx) == current_match_line {
+                        st = st.fg(fg);
+                    }
+                }
+                Span::styled(s.content.to_string(), st)
+            })
+            .collect();
+        *styled = Line::from(content);
+    }
+    lines
+}
+
+/// Paint SSA token backgrounds. Always overrides whatever bg syntax/search set.
+pub(crate) fn apply_symbol_highlights(lines: &mut [Line<'static>], highlights: &[(String, Color)]) {
+    apply_ssa_highlights(lines, highlights);
+}
+
+pub(crate) fn apply_ssa_highlights(lines: &mut [Line<'static>], highlights: &[(String, Color)]) {
+    if highlights.is_empty() {
+        return;
+    }
+    for line in lines {
+        apply_ssa_to_line(line, highlights);
+    }
+}
+
+fn apply_ssa_to_line(line: &mut Line<'static>, highlights: &[(String, Color)]) {
+    let text: String = line.spans.iter().map(|s| s.content.as_ref()).collect();
+    if text.is_empty() {
+        return;
+    }
+
+    let mut styles: Vec<Style> = Vec::new();
+    for span in &line.spans {
+        for _ in span.content.chars() {
+            styles.push(span.style);
+        }
+    }
+    if styles.len() != text.chars().count() {
+        return;
+    }
+
+    let chars: Vec<char> = text.chars().collect();
+    let bytes = text.as_bytes();
+    let mut char_of_byte = vec![0usize; bytes.len() + 1];
+    {
+        let mut ci = 0usize;
+        for (bi, _ch) in text.char_indices() {
+            char_of_byte[bi] = ci;
+            ci += 1;
+        }
+        char_of_byte[bytes.len()] = ci;
+    }
+
+    for (name, bg) in highlights {
+        let name_bytes = name.as_bytes();
+        let mut start = 0usize;
+        while start + name_bytes.len() <= bytes.len() {
+            if bytes[start..].starts_with(name_bytes)
+                && (start == 0 || !is_ident_byte(bytes[start - 1]))
+                && {
+                    let end = start + name_bytes.len();
+                    end == bytes.len() || !is_ident_byte(bytes[end])
+                }
+            {
+                let c0 = char_of_byte[start];
+                let c1 = char_of_byte[start + name_bytes.len()];
+                for style in styles.iter_mut().take(c1).skip(c0) {
+                    *style = style.bg(*bg).fg(Color::White);
+                }
+                start += name_bytes.len();
+            } else {
+                start += 1;
+            }
+        }
+    }
+
+    let mut out = Vec::new();
+    let mut i = 0usize;
+    while i < chars.len() {
+        let st = styles[i];
+        let mut j = i + 1;
+        while j < chars.len() && styles[j] == st {
+            j += 1;
+        }
+        out.push(Span::styled(chars[i..j].iter().collect::<String>(), st));
+        i = j;
+    }
+    *line = Line::from(out);
+}
+
+/// Drop the first `skip` characters from styled spans, preserving styles.
+pub(crate) fn skip_line_chars(line: &Line<'static>, skip: usize) -> Line<'static> {
+    if skip == 0 {
+        return line.clone();
+    }
+    let mut remaining = skip;
+    let mut out = Vec::new();
+    for span in &line.spans {
+        if remaining == 0 {
+            out.push(span.clone());
+            continue;
+        }
+        let len = span.content.chars().count();
+        if remaining >= len {
+            remaining -= len;
+            continue;
+        }
+        let kept: String = span.content.chars().skip(remaining).collect();
+        remaining = 0;
+        out.push(Span::styled(kept, span.style));
+    }
+    Line::from(out)
+}
+
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum SsaRefKind {
+    Def,
+    Use,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct SsaRef {
+    pub line: usize,
+    pub kind: SsaRefKind,
+}
+
+fn strip_diff_prefix(line: &str) -> &str {
+    if let Some(r) = line.strip_prefix("+ ") {
+        r
+    } else if let Some(r) = line.strip_prefix("- ") {
+        r
+    } else if let Some(r) = line.strip_prefix("  ") {
+        r
+    } else {
+        line
+    }
+}
+
+/// Instruction text after diff prefix + indent, and its byte offset in `line`.
+fn line_instruction_body(line: &str) -> (&str, usize) {
+    let after_diff = strip_diff_prefix(line);
+    let diff_len = line.len() - after_diff.len();
+    let trimmed = after_diff.trim_start();
+    let ws = after_diff.len() - trimmed.len();
+    (trimmed, diff_len + ws)
+}
+
+/// All whole-token defs/uses of `name` in `text` (0-based line indices).
+pub(crate) fn find_ssa_refs(text: &str, name: &str) -> Vec<SsaRef> {
+    if name.is_empty() || !is_ssa_name(name) {
+        return Vec::new();
+    }
+    let name_bytes = name.as_bytes();
+    let mut out = Vec::new();
+    for (line_idx, line) in text.lines().enumerate() {
+        let (body, body_byte_offset) = line_instruction_body(line);
+        let def_here = body.starts_with(name) && body[name.len()..].starts_with(" = ");
+
+        let bytes = line.as_bytes();
+        let mut start = 0usize;
+        let mut saw_def = false;
+        while start + name_bytes.len() <= bytes.len() {
+            if bytes[start..].starts_with(name_bytes)
+                && (start == 0 || !is_ident_byte(bytes[start - 1]))
+                && {
+                    let end = start + name_bytes.len();
+                    end == bytes.len() || !is_ident_byte(bytes[end])
+                }
+            {
+                let is_def = def_here && !saw_def && start == body_byte_offset;
+                if is_def {
+                    saw_def = true;
+                }
+                out.push(SsaRef {
+                    line: line_idx,
+                    kind: if is_def {
+                        SsaRefKind::Def
+                    } else {
+                        SsaRefKind::Use
+                    },
+                });
+                start += name_bytes.len();
+            } else {
+                start += 1;
+            }
+        }
+    }
+    out
+}
+
+#[derive(Debug, Clone, Copy, Default)]
+pub(crate) struct SsaOffscreen {
+    pub above_defs: usize,
+    pub above_uses: usize,
+    pub below_defs: usize,
+    pub below_uses: usize,
+}
+
+/// Count defs/uses of `name` strictly above `view_start` or at/after `view_end`.
+pub(crate) fn count_ssa_offscreen(
+    text: &str,
+    name: &str,
+    view_start: usize,
+    view_end: usize,
+) -> SsaOffscreen {
+    let mut c = SsaOffscreen::default();
+    for r in find_ssa_refs(text, name) {
+        if r.line < view_start {
+            match r.kind {
+                SsaRefKind::Def => c.above_defs += 1,
+                SsaRefKind::Use => c.above_uses += 1,
+            }
+        } else if r.line >= view_end {
+            match r.kind {
+                SsaRefKind::Def => c.below_defs += 1,
+                SsaRefKind::Use => c.below_uses += 1,
+            }
+        }
+    }
+    c
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn find_ssa_refs_distinguishes_def_and_use() {
+        let text = "    v0 = const u64 1\n    v1 = add v0, v0\n";
+        let refs = find_ssa_refs(text, "v0");
+        assert_eq!(refs.len(), 3);
+        assert_eq!(refs[0].kind, SsaRefKind::Def);
+        assert_eq!(refs[0].line, 0);
+        assert_eq!(refs[1].kind, SsaRefKind::Use);
+        assert_eq!(refs[2].kind, SsaRefKind::Use);
+        let off = count_ssa_offscreen(text, "v0", 1, 2);
+        assert_eq!(off.above_defs, 1);
+        assert_eq!(off.above_uses, 0);
+        assert_eq!(off.below_defs, 0);
+        assert_eq!(off.below_uses, 0);
+        let off2 = count_ssa_offscreen(text, "v0", 0, 1);
+        assert_eq!(off2.below_uses, 2);
+    }
+
+    #[test]
+    fn symbol_at_col_finds_local_and_method() {
+        assert!(!SSA_PALETTE.is_empty());
+        assert_eq!(SSA_PALETTE.len(), SYMBOL_PALETTE.len());
+        let text = "    fn main() -> u64 {\n        local u64 x\n        entry():\n        v0 = get_local __ptr u64, x\n        v1 = call foo(v0)\n    }\n    fn foo(a: u64) -> u64 {\n        ret u64 a\n    }\n";
+        assert_eq!(local_decl_name("        local u64 x").as_deref(), Some("x"));
+        assert_eq!(get_local_name("        v0 = get_local __ptr u64, x").as_deref(), Some("x"));
+        assert_eq!(fn_def_name("    fn main() -> u64 {").as_deref(), Some("main"));
+        assert_eq!(call_name("        v1 = call foo(v0)").as_deref(), Some("foo"));
+        assert_eq!(symbol_at_col("        local u64 x", 18, text).as_deref(), Some("x"));
+        assert_eq!(symbol_at_col("    fn main() -> u64 {", 7, text).as_deref(), Some("main"));
+        assert_eq!(symbol_at_col("        v1 = call foo(v0)", 18, text).as_deref(), Some("foo"));
+        let (above, below) = count_token_offscreen(text, "x", 2, 3);
+        assert!(above >= 1);
+        assert!(below >= 1);
+    }
+
+    #[test]
+    fn ssa_at_col_finds_register() {
+        assert_eq!(ssa_at_col("    v0 = const u64 1", 4).as_deref(), Some("v0"));
+        assert_eq!(ssa_at_col("    v12v1 = add v0, v1", 6).as_deref(), Some("v12v1"));
+        // "    add v0" → 'v' is at column 8
+        assert_eq!(ssa_at_col("    add v0, v1", 8).as_deref(), Some("v0"));
+        assert!(ssa_at_col("    local u64 x", 4).is_none());
+    }
+
+    #[test]
+    fn ssa_highlight_overrides_syntax_background() {
+        let mut lines = highlight_ir_with_search("v0 = add v0, v1\n", false, "", None, true);
+        apply_ssa_highlights(&mut lines, &[("v0".into(), Color::Rgb(1, 2, 3))]);
+        let has_bg = lines[0].spans.iter().any(|s| {
+            s.content.contains('v') && s.style.bg == Some(Color::Rgb(1, 2, 3))
+        });
+        assert!(has_bg, "expected v0 spans to carry SSA background");
+    }
+
+    #[test]
+    fn unicode_in_comment_does_not_panic() {
+        let _ = highlight_ir("// comment → … ● 日本語\n", false);
+    }
+
+    #[test]
+    fn unicode_in_code_does_not_panic() {
+        let _ = highlight_ir("v0 = const u64 1 // →\nfn 日本語() {\n}\n", false);
+    }
+
+    #[test]
+    fn unicode_string_escape_does_not_panic() {
+        let _ = highlight_ir("v0 = const string \"a\\→b\"\n", false);
+    }
+
+    #[test]
+    fn diff_with_unicode_does_not_panic() {
+        let _ = highlight_ir("+   // added →\n-   // removed …\n  // context ●\n", true);
+    }
+}
+
+#[cfg(test)]
+mod version_toggle_tests {
+    use super::*;
+    use crate::parse::{strip_metadata_and_version, strip_version_suffix, MdMode, VersionMode};
+
+    #[test]
+    fn highlighting_after_version_strip_does_not_panic() {
+        let sample = r#"
+script {
+    fn main() -> () {
+        entry_block():
+        v0v0 = const u64 1, !1
+        v1v2 = add v0v0, v0v0, !2
+        ret ()
+    }
+}
+!1 = span 0 1 2
+"#;
+        let stripped = strip_version_suffix(sample);
+        let _ = highlight_ir(&stripped, false);
+        let both = strip_metadata_and_version(sample, MdMode::Without, VersionMode::Without);
+        let _ = highlight_ir(&both, false);
+        let _ = highlight_ir_with_search(&stripped, false, "v0", Some(0), true);
+    }
+
+    #[test]
+    fn highlighting_real_ir_after_version_strip() {
+        use std::path::PathBuf;
+        let root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests");
+        if !root.exists() {
+            return;
+        }
+        for entry in std::fs::read_dir(&root).into_iter().flatten().flatten() {
+            let p = entry.path();
+            if p.extension().and_then(|s| s.to_str()) != Some("ir") {
+                continue;
+            }
+            let Ok(text) = std::fs::read_to_string(&p) else {
+                continue;
+            };
+            let stripped = strip_version_suffix(&text);
+            let _ = highlight_ir(&stripped, false);
+            let _ = highlight_ir(&stripped, true);
+        }
+    }
+}
diff --git a/forc-plugins/forc-ir-inspect/src/main.rs b/forc-plugins/forc-ir-inspect/src/main.rs
new file mode 100644
index 00000000000..51b2e1ec013
--- /dev/null
+++ b/forc-plugins/forc-ir-inspect/src/main.rs
@@ -0,0 +1,217 @@
+//! ```text
+//! > forc ir-inspect --help
+//! > cargo r -p forc-ir-inspect -- --help
+//!
+//! Interactive TUI (default on a TTY):
+//!   forc ir-inspect dump.txt
+//!   forc ir-inspect --cmd 'forc build --ir all,print-md'
+//!
+//! Classic stream output:
+//!   forc ir-inspect --classic dump.txt --print diff,without-md
+//!   forc ir-inspect --classic --cmd 'forc build --ir all,print-md' --print ir
+//! ```
+
+mod classic;
+mod config;
+mod highlight;
+mod parse;
+mod tui;
+
+use std::io::IsTerminal;
+
+use anyhow::{bail, Result};
+use clap::Parser;
+
+use parse::{MdMode, PrintMode, VersionMode};
+
+fn main() -> Result<()> {
+    let cli = Cli::parse();
+    let mode = cli.mode()?;
+    let metadata = cli.metadata()?;
+    let version = cli.version()?;
+    let source = cli.source();
+    let filter_fn: Vec<String> = cli
+        .filter_fn
+        .iter()
+        .map(|s| s.trim().to_string())
+        .filter(|s| !s.is_empty())
+        .collect();
+
+    if cli.input_path.is_none() && cli.cmd.is_none() {
+        bail!("provide an INPUT_PATH or --cmd");
+    }
+    if cli.input_path.is_some() && cli.cmd.is_some() {
+        bail!("provide either an INPUT_PATH or --cmd, not both");
+    }
+
+    let use_tui = if cli.classic {
+        false
+    } else if cli.tui {
+        true
+    } else {
+        std::io::stdout().is_terminal()
+    };
+
+    if use_tui {
+        return tui::run(tui::TuiOptions {
+            input_path: cli.input_path,
+            cmd: cli.cmd,
+            filter_fn,
+            metadata,
+            version,
+            source,
+            start_diff: mode == PrintMode::Diff,
+        });
+    }
+
+    let raw = load_raw(cli.input_path.as_deref(), cli.cmd.as_deref())?;
+    let cleaned = parse::strip_ansi(&raw);
+    let irs = parse::parse(&cleaned);
+    if irs.is_empty() {
+        let src = cli
+            .input_path
+            .as_deref()
+            .or(cli.cmd.as_deref())
+            .unwrap_or("input");
+        bail!("no `// IR:` dumps found in {src}");
+    }
+    classic::run(
+        &irs, &cleaned, &filter_fn, mode, metadata, version, source,
+    )
+}
+
+fn load_raw(path: Option<&str>, cmd: Option<&str>) -> Result<String> {
+    if let Some(cmd) = cmd {
+        parse::capture_shell(cmd)
+    } else if let Some(path) = path {
+        std::fs::read_to_string(path)
+            .map_err(|e| anyhow::anyhow!("failed to read {path}: {e}"))
+    } else {
+        bail!("no input")
+    }
+}
+
+/// Browse or print Sway IR dumps from `forc build --ir all,print-md`.
+#[derive(Debug, Parser)]
+#[command(
+    name = "forc-ir-inspect",
+    about = "Forc plugin for browsing or printing Sway IR dumps from `forc build --ir all,print-md`",
+    after_help = "Source overlay (`s`) needs metadata defs: use `--ir all,print-md`.\nTUI keys: F5 reload · y copy · Ctrl-C kill/quit · Tab focus · / search · p/f filters · d diff · m metadata · s source · S source-root · v version · ? help · q quit"
+)]
+struct Cli {
+    /// Path to an IR dump file (output of `forc build --ir all,print-md`).
+    /// Mutually exclusive with `--cmd`.
+    input_path: Option<String>,
+
+    /// Shell command to spawn; stdout and stderr are captured and parsed as the
+    /// IR dump. No input file is needed. In the TUI, press F5 to re-run.
+    #[arg(long = "cmd", short = 'c')]
+    cmd: Option<String>,
+
+    /// Force the classic (non-interactive) printer.
+    #[arg(long)]
+    classic: bool,
+
+    /// Force the interactive TUI.
+    #[arg(long)]
+    tui: bool,
+
+    /// Filter in functions whose name contains one of the given substrings
+    /// (comma separated).
+    #[arg(long, value_delimiter = ',')]
+    filter_fn: Vec<String>,
+
+    /// Comma separated list of items to print / TUI defaults.
+    #[arg(long, value_delimiter = ',')]
+    print: Vec<PrintItem>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, clap::ValueEnum)]
+enum PrintItem {
+    Ir,
+    Diff,
+    WithMd,
+    WithoutMd,
+    WithVersion,
+    WithoutVersion,
+    /// Print the original source code on top of each IR line that has metadata.
+    Source,
+}
+
+impl Cli {
+    fn mode(&self) -> Result<PrintMode> {
+        let mut explicit = None::<PrintMode>;
+        for item in &self.print {
+            match item {
+                PrintItem::Ir => {
+                    if explicit == Some(PrintMode::Diff) {
+                        bail!("--print items 'ir' and 'diff' are mutually exclusive");
+                    }
+                    explicit = Some(PrintMode::Ir);
+                }
+                PrintItem::Diff => {
+                    if explicit == Some(PrintMode::Ir) {
+                        bail!("--print items 'ir' and 'diff' are mutually exclusive");
+                    }
+                    explicit = Some(PrintMode::Diff);
+                }
+                _ => {}
+            }
+        }
+        Ok(explicit.unwrap_or_default())
+    }
+
+    fn metadata(&self) -> Result<MdMode> {
+        let mut metadata = MdMode::default();
+        for item in &self.print {
+            match item {
+                PrintItem::WithMd => {
+                    if metadata == MdMode::Without {
+                        bail!("--print items 'with-md' and 'without-md' are mutually exclusive");
+                    }
+                    metadata = MdMode::With;
+                }
+                PrintItem::WithoutMd => {
+                    if metadata == MdMode::With {
+                        bail!("--print items 'with-md' and 'without-md' are mutually exclusive");
+                    }
+                    metadata = MdMode::Without;
+                }
+                _ => {}
+            }
+        }
+        Ok(metadata)
+    }
+
+    fn version(&self) -> Result<VersionMode> {
+        let mut version = VersionMode::default();
+        for item in &self.print {
+            match item {
+                PrintItem::WithVersion => {
+                    if version == VersionMode::Without {
+                        bail!(
+                            "--print items 'with-version' and 'without-version' are mutually exclusive"
+                        );
+                    }
+                    version = VersionMode::With;
+                }
+                PrintItem::WithoutVersion => {
+                    if version == VersionMode::With {
+                        bail!(
+                            "--print items 'with-version' and 'without-version' are mutually exclusive"
+                        );
+                    }
+                    version = VersionMode::Without;
+                }
+                _ => {}
+            }
+        }
+        Ok(version)
+    }
+
+    fn source(&self) -> bool {
+        self.print
+            .iter()
+            .any(|item| matches!(item, PrintItem::Source))
+    }
+}
diff --git a/sway-ir/src/bin/inspect.rs b/forc-plugins/forc-ir-inspect/src/parse.rs
similarity index 69%
rename from sway-ir/src/bin/inspect.rs
rename to forc-plugins/forc-ir-inspect/src/parse.rs
index d675499b795..292dbe45d12 100644
--- a/sway-ir/src/bin/inspect.rs
+++ b/forc-plugins/forc-ir-inspect/src/parse.rs
@@ -1,117 +1,33 @@
-//! ```
-//! > cargo r --bin inspect -r -- --help
-//! Reads the output of `forc build --ir all` and prints diffs, stats and other helpful information
-//!
-//! Usage: inspect [OPTIONS] <INPUT_PATH>
-//!
-//! Arguments:
-//!   <INPUT_PATH>  Path to the input file (output of `forc build --ir all`)
-//!
-//! Options:
-//!       --filter-fn <FILTER_FN>  Filter in functions whose name contains one of the given substrings (comma separated)
-//!       --print <PRINT>          Comma separated list of items to print [possible values: ir, diff, with-md, without-md,
-//!                                with-version, without-version, source]
-//!   -h, --help                   Print help
-//! ```
+//! Parsing and IR text utilities shared by classic and TUI modes.
 
 use std::collections::{BTreeMap, BTreeSet};
-use std::io::{IsTerminal, Write};
-
-use anyhow::{anyhow, bail, Result};
-use clap::Parser;
-
-fn main() -> Result<()> {
-    let cli = Cli::parse();
-    let mode = cli.mode()?;
-    let metadata = cli.metadata()?;
-    let version = cli.version()?;
-    let source = cli.source();
-    let filter_fn: Vec<String> = cli
-        .filter_fn
-        .iter()
-        .map(|s| s.trim().to_string())
-        .filter(|s| !s.is_empty())
-        .collect();
-
-    let raw_forc_output = std::fs::read_to_string(&cli.input_path)
-        .map_err(|e| anyhow!("failed to read {}: {e}", cli.input_path))?;
-    let cleaned_forc_output = strip_ansi(&raw_forc_output);
-
-    let irs = parse(&cleaned_forc_output);
-    if irs.is_empty() {
-        bail!("no `// IR:` dumps found in {}", cli.input_path);
-    }
-
-    if source && !has_metadata_defs(&cleaned_forc_output) {
-        eprintln!(
-            "warning: `--print source` was requested but the input contains no metadata \
-             definitions (`!N = ...`).\n  \
-             Regenerate the IR dump with the `print-md` flag, e.g. \
-             `forc build --ir all print-md`, so the span/file metadata is emitted."
-        );
-    }
-
-    let stdout = std::io::stdout();
-    let is_terminal = stdout.is_terminal();
-    let mut out = stdout.lock();
-
-    // Diff baseline: the rendered text of the previous printed dump. Reset to
-    // `None` at the start of every compilation unit.
-    let mut previous_ir: Option<String> = None;
-
-    for ir in &irs {
-        // A new compilation unit starts here; reset the diff baseline.
-        if ir.is_initial() {
-            previous_ir = None;
-        }
-
-        let Some(final_ir) = prepare_ir_text(&filter_fn, metadata, version, ir) else {
-            continue;
-        };
-
-        // The source map is parsed from the raw body (which always contains
-        // the `!N = ...` definitions), independent of metadata/version
-        // stripping applied to `final_ir`.
-        let mut source_map = if source {
-            Some(parse_source_map(&ir.body))
-        } else {
-            None
-        };
-
-        writeln!(out, "// IR: {}", ir.pass_name)?;
+use std::io::Write;
+use std::path::{Component, Path, PathBuf};
 
-        if mode == PrintMode::Diff {
-            if let Some(prev_text) = previous_ir.as_ref() {
-                let changeset = prettydiff::diff_lines(prev_text, &final_ir);
-                let ops = changeset.diff();
-                let (adds, removes) = diff_stats(&ops);
-                if adds == 0 && removes == 0 {
-                    print_diff_stats(&mut out, adds, removes)?;
-                } else {
-                    let cur_stats = FuncStats::compute_stats(&final_ir);
-                    let prev_stats = previous_ir.as_ref().map(|p| FuncStats::compute_stats(p));
-                    cur_stats.print_fn_stats(&mut out, prev_stats.as_ref())?;
-                    print_diff_stats(&mut out, adds, removes)?;
-                    print_diff(&mut out, &ops, is_terminal)?;
-                }
-            } else {
-                let cur_stats = FuncStats::compute_stats(&final_ir);
-                cur_stats.print_fn_stats(&mut out, None)?;
-                print_final_ir(&mut out, &final_ir, source_map.as_mut())?;
-            }
-        } else {
-            let cur_stats = FuncStats::compute_stats(&final_ir);
-            cur_stats.print_fn_stats(&mut out, None)?;
-            print_final_ir(&mut out, &final_ir, source_map.as_mut())?;
-        }
+#[derive(Debug, Default, PartialEq, Eq, Clone, Copy)]
+pub(crate) enum PrintMode {
+    #[default]
+    Ir,
+    Diff,
+}
 
-        previous_ir = Some(final_ir);
-    }
+#[derive(Debug, Default, PartialEq, Eq, Clone, Copy)]
+pub(crate) enum MdMode {
+    #[default]
+    AsParsed,
+    With,
+    Without,
+}
 
-    Ok(())
+#[derive(Debug, Default, PartialEq, Eq, Clone, Copy)]
+pub(crate) enum VersionMode {
+    #[default]
+    AsParsed,
+    With,
+    Without,
 }
 
-fn prepare_ir_text(
+pub(crate) fn prepare_ir_text(
     filter_fn: &[String],
     metadata: MdMode,
     version: VersionMode,
@@ -141,135 +57,8 @@ fn prepare_ir_text(
     }
 }
 
-#[derive(Debug, Default, PartialEq, Eq, Clone, Copy)]
-enum PrintMode {
-    #[default]
-    Ir,
-    Diff,
-}
-
-#[derive(Debug, Default, PartialEq, Eq, Clone, Copy)]
-enum MdMode {
-    #[default]
-    AsParsed,
-    With,
-    Without,
-}
-
-#[derive(Debug, Default, PartialEq, Eq, Clone, Copy)]
-enum VersionMode {
-    #[default]
-    AsParsed,
-    With,
-    Without,
-}
-
-/// Reads the output of `forc build --ir all` and prints diffs, stats and other helpful information.
-#[derive(Debug, Parser)]
-struct Cli {
-    /// Path to the input file (output of `forc build --ir all`).
-    input_path: String,
-
-    /// Filter in functions whose name contains one of the given substrings (comma separated).
-    #[arg(long, value_delimiter = ',')]
-    filter_fn: Vec<String>,
-
-    /// Comma separated list of items to print.
-    #[arg(long, value_delimiter = ',')]
-    print: Vec<PrintItem>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, clap::ValueEnum)]
-enum PrintItem {
-    Ir,
-    Diff,
-    WithMd,
-    WithoutMd,
-    WithVersion,
-    WithoutVersion,
-    /// Print the original source code on top of each IR line that has metadata.
-    Source,
-}
 
-impl Cli {
-    fn mode(&self) -> Result<PrintMode> {
-        let mut explicit = None::<PrintMode>;
-        for item in &self.print {
-            match item {
-                PrintItem::Ir => {
-                    if explicit == Some(PrintMode::Diff) {
-                        bail!("--print items 'ir' and 'diff' are mutually exclusive");
-                    }
-                    explicit = Some(PrintMode::Ir);
-                }
-                PrintItem::Diff => {
-                    if explicit == Some(PrintMode::Ir) {
-                        bail!("--print items 'ir' and 'diff' are mutually exclusive");
-                    }
-                    explicit = Some(PrintMode::Diff);
-                }
-                _ => {}
-            }
-        }
-        Ok(explicit.unwrap_or_default())
-    }
-
-    fn metadata(&self) -> Result<MdMode> {
-        let mut metadata = MdMode::default();
-        for item in &self.print {
-            match item {
-                PrintItem::WithMd => {
-                    if metadata == MdMode::Without {
-                        bail!("--print items 'with-md' and 'without-md' are mutually exclusive");
-                    }
-                    metadata = MdMode::With;
-                }
-                PrintItem::WithoutMd => {
-                    if metadata == MdMode::With {
-                        bail!("--print items 'with-md' and 'without-md' are mutually exclusive");
-                    }
-                    metadata = MdMode::Without;
-                }
-                _ => {}
-            }
-        }
-        Ok(metadata)
-    }
-
-    fn version(&self) -> Result<VersionMode> {
-        let mut version = VersionMode::default();
-        for item in &self.print {
-            match item {
-                PrintItem::WithVersion => {
-                    if version == VersionMode::Without {
-                        bail!(
-                            "--print items 'with-version' and 'without-version' are mutually exclusive"
-                        );
-                    }
-                    version = VersionMode::With;
-                }
-                PrintItem::WithoutVersion => {
-                    if version == VersionMode::With {
-                        bail!(
-                            "--print items 'with-version' and 'without-version' are mutually exclusive"
-                        );
-                    }
-                    version = VersionMode::Without;
-                }
-                _ => {}
-            }
-        }
-        Ok(version)
-    }
-
-    fn source(&self) -> bool {
-        self.print
-            .iter()
-            .any(|item| matches!(item, PrintItem::Source))
-    }
-}
-
-fn strip_metadata_and_version(body: &str, metadata: MdMode, version: VersionMode) -> String {
+pub(crate) fn strip_metadata_and_version(body: &str, metadata: MdMode, version: VersionMode) -> String {
     let mut s = body.to_string();
     if version == VersionMode::Without {
         s = strip_version_suffix(&s);
@@ -280,73 +69,85 @@ fn strip_metadata_and_version(body: &str, metadata: MdMode, version: VersionMode
     s.trim_end().to_string()
 }
 
-struct ParsedIr {
-    pass_name: String,
-    body: String,
+pub(crate) struct ParsedIr {
+    /// Package / compilation unit label from the nearest preceding
+    /// `Compiling …` / `Building …` line (or `"(unknown)"`).
+    pub project: String,
+    pub pass_name: String,
+    pub body: String,
 }
 
 impl ParsedIr {
     /// The `// IR: Initial` header marks the start of a new compilation unit.
-    fn is_initial(&self) -> bool {
+    pub(crate) fn is_initial(&self) -> bool {
         self.pass_name == "Initial"
     }
 }
 
-fn parse(cleaned: &str) -> Vec<ParsedIr> {
+fn push_parsed(out: &mut Vec<ParsedIr>, project: String, pass_name: String, body: Vec<&str>) {
+    out.push(ParsedIr {
+        project,
+        pass_name,
+        body: body.join("\n"),
+    });
+}
+
+pub(crate) fn parse(cleaned: &str) -> Vec<ParsedIr> {
     let mut parsed_irs = Vec::new();
-    let mut current: Option<(String, Vec<&str>)> = None;
+    // (project, pass_name, body lines)
+    let mut current: Option<(String, String, Vec<&str>)> = None;
+    let mut current_project = String::from("(unknown)");
 
     for line in cleaned.lines() {
+        let trimmed = line.trim_start();
+
+        // Track package boundaries even between dumps (when `current` is None).
+        if let Some(rest) = trimmed
+            .strip_prefix("Compiling ")
+            .or_else(|| trimmed.strip_prefix("Building "))
+        {
+            current_project = rest.trim().to_string();
+            if let Some((project, name, body)) = current.take() {
+                push_parsed(&mut parsed_irs, project, name, body);
+            }
+            continue;
+        }
+
         // The `// IR:` header may be indented (some dumps pad every line with
         // leading whitespace), so match against the trimmed-start line rather
         // than requiring the line to begin exactly with `// IR: `.  The body
         // lines below are still pushed verbatim, preserving their indentation.
-        if let Some(rest) = line.trim_start().strip_prefix("// IR: ") {
-            if let Some((name, body)) = current.take() {
-                parsed_irs.push(ParsedIr {
-                    pass_name: name,
-                    body: body.join("\n"),
-                });
+        if let Some(rest) = trimmed.strip_prefix("// IR: ") {
+            if let Some((project, name, body)) = current.take() {
+                push_parsed(&mut parsed_irs, project, name, body);
             }
-            current = Some((rest.trim().to_string(), Vec::new()));
+            current = Some((
+                current_project.clone(),
+                rest.trim().to_string(),
+                Vec::new(),
+            ));
             continue;
         }
 
-        let Some((_, body)) = current.as_mut() else {
-            continue;
-        };
-
-        let trimmed = line.trim_start();
-        if trimmed.starts_with("Compiling ") || trimmed.starts_with("Building ") {
-            // A new compilation unit is about to start
-            if let Some((name, body)) = current.take() {
-                parsed_irs.push(ParsedIr {
-                    pass_name: name,
-                    body: body.join("\n"),
-                });
-            }
-        } else {
+        if let Some((_, _, body)) = current.as_mut() {
             body.push(line);
         }
     }
 
-    if let Some((name, body)) = current {
-        parsed_irs.push(ParsedIr {
-            pass_name: name,
-            body: body.join("\n"),
-        });
+    if let Some((project, name, body)) = current {
+        push_parsed(&mut parsed_irs, project, name, body);
     }
 
     parsed_irs
 }
 
-struct FuncDecl {
-    name: String,
-    start: usize,
-    end: usize,
+pub(crate) struct FuncDecl {
+    pub name: String,
+    pub start: usize,
+    pub end: usize,
 }
 
-fn find_functions(body: &str) -> Vec<FuncDecl> {
+pub(crate) fn find_functions(body: &str) -> Vec<FuncDecl> {
     let lines: Vec<&str> = body.lines().collect();
     let mut decls = Vec::new();
 
@@ -376,7 +177,7 @@ fn find_functions(body: &str) -> Vec<FuncDecl> {
 }
 
 /// If `line` is a function declaration, return the declared function name.
-fn function_decl_name(line: &str) -> Option<String> {
+pub(crate) fn function_decl_name(line: &str) -> Option<String> {
     let mut rest = line.trim_start();
 
     loop {
@@ -410,16 +211,17 @@ fn is_id_byte(b: u8) -> bool {
     b.is_ascii_alphanumeric() || b == b'_'
 }
 
-#[derive(Default)]
-struct FuncStats {
-    args: usize,
-    blocks: usize,
-    instructions: usize,
-    ops: BTreeMap<String, usize>,
+#[derive(Default, Clone)]
+pub(crate) struct FuncStats {
+    pub args: usize,
+    pub locals: usize,
+    pub blocks: usize,
+    pub instructions: usize,
+    pub ops: BTreeMap<String, usize>,
 }
 
 impl FuncStats {
-    fn compute_stats(text: &str) -> FuncStats {
+    pub(crate) fn compute_stats(text: &str) -> FuncStats {
         let lines: Vec<&str> = text.lines().collect();
         let mut stats = FuncStats::default();
         for decl in find_functions(text) {
@@ -436,7 +238,11 @@ impl FuncStats {
                     }
                     continue;
                 }
-                if t == "}" || t.starts_with("local ") {
+                if t == "}" {
+                    continue;
+                }
+                if t.starts_with("local ") {
+                    stats.locals += 1;
                     continue;
                 }
                 if t.ends_with(':') {
@@ -514,7 +320,7 @@ impl FuncStats {
         }
     }
 
-    fn print_fn_stats<W: Write>(
+    pub(crate) fn print_fn_stats<W: Write>(
         self,
         out: &mut W,
         prev: Option<&FuncStats>,
@@ -524,6 +330,10 @@ impl FuncStats {
             " args={}",
             Self::stat_with_delta(self.args, prev.map(|p| p.args))
         ));
+        line.push_str(&format!(
+            " locals={}",
+            Self::stat_with_delta(self.locals, prev.map(|p| p.locals))
+        ));
         line.push_str(&format!(
             " blocks={}",
             Self::stat_with_delta(self.blocks, prev.map(|p| p.blocks))
@@ -551,7 +361,7 @@ impl FuncStats {
     }
 }
 
-fn strip_version_suffix(input: &str) -> String {
+pub(crate) fn strip_version_suffix(input: &str) -> String {
     let bytes = input.as_bytes();
     let mut out = String::with_capacity(input.len());
     let mut copy_from = 0usize;
@@ -588,7 +398,7 @@ fn strip_version_suffix(input: &str) -> String {
     out
 }
 
-fn strip_metadata(input: &str) -> String {
+pub(crate) fn strip_metadata(input: &str) -> String {
     let mut out = String::with_capacity(input.len());
 
     for line in input.lines() {
@@ -605,7 +415,7 @@ fn strip_metadata(input: &str) -> String {
     out.trim_end_matches('\n').to_string()
 }
 
-fn is_metadata_def_line(line: &str) -> bool {
+pub(crate) fn is_metadata_def_line(line: &str) -> bool {
     let bytes = line.as_bytes();
     let mut i = 0;
     if bytes.first() != Some(&b'!') {
@@ -661,7 +471,7 @@ fn strip_inline_metadata(line: &str) -> String {
     out
 }
 
-fn print_diff<W: Write>(
+pub(crate) fn print_diff<W: Write>(
     out: &mut W,
     ops: &[prettydiff::basic::DiffOp<&str>],
     color: bool,
@@ -696,7 +506,7 @@ fn print_diff<W: Write>(
     Ok(())
 }
 
-fn diff_stats(ops: &[prettydiff::basic::DiffOp<&str>]) -> (usize, usize) {
+pub(crate) fn diff_stats(ops: &[prettydiff::basic::DiffOp<&str>]) -> (usize, usize) {
     let mut adds = 0;
     let mut removes = 0;
     for op in ops {
@@ -713,11 +523,52 @@ fn diff_stats(ops: &[prettydiff::basic::DiffOp<&str>]) -> (usize, usize) {
     (adds, removes)
 }
 
-fn print_diff_stats<W: Write>(out: &mut W, adds: usize, removes: usize) -> std::io::Result<()> {
+pub(crate) fn print_diff_stats<W: Write>(out: &mut W, adds: usize, removes: usize) -> std::io::Result<()> {
     writeln!(out, "// Diff Stats: adds={adds} removes={removes}")
 }
 
-fn strip_ansi(input: &str) -> String {
+/// Spawn `cmd` under a shell with stdout piped (stderr merged via `2>&1`).
+///
+/// The caller owns the [`std::process::Child`] and can kill it (e.g. on Ctrl-C).
+pub(crate) fn spawn_shell(cmd: &str) -> anyhow::Result<std::process::Child> {
+    use std::process::{Command, Stdio};
+
+    Command::new("bash")
+        .arg("-lc")
+        .arg(format!("{{ {cmd}\n}} 2>&1"))
+        .stdout(Stdio::piped())
+        .stderr(Stdio::null())
+        .spawn()
+        .map_err(|e| anyhow::anyhow!("failed to spawn shell for `--cmd`: {e}"))
+}
+
+/// Spawn `cmd` under a shell and capture merged stdout + stderr.
+///
+/// Used for `--cmd` in classic mode. Stderr is redirected into stdout by the
+/// shell (`2>&1`) so both streams are captured in order as a single pipe.
+pub(crate) fn capture_shell(cmd: &str) -> anyhow::Result<String> {
+    use std::io::Read;
+
+    let mut child = spawn_shell(cmd)?;
+    let mut text = String::new();
+    if let Some(mut stdout) = child.stdout.take() {
+        stdout
+            .read_to_string(&mut text)
+            .map_err(|e| anyhow::anyhow!("failed to read `--cmd` output: {e}"))?;
+    }
+    let status = child
+        .wait()
+        .map_err(|e| anyhow::anyhow!("failed to wait for `--cmd`: {e}"))?;
+
+    if text.trim().is_empty() && !status.success() {
+        let code = status.code().unwrap_or(-1);
+        anyhow::bail!("`--cmd` exited with status {code} and produced no output");
+    }
+
+    Ok(text)
+}
+
+pub(crate) fn strip_ansi(input: &str) -> String {
     let bytes = input.as_bytes();
     let mut out: Vec<u8> = Vec::with_capacity(bytes.len());
     let mut copy_from = 0usize;
@@ -768,7 +619,7 @@ fn strip_ansi(input: &str) -> String {
 
 /// Prints the final IR text, optionally prefixing each line that carries
 /// metadata with the original source code it refers to (see `--print source`).
-fn print_final_ir<W: Write>(
+pub(crate) fn print_final_ir<W: Write>(
     out: &mut W,
     text: &str,
     source_map: Option<&mut SourceMap>,
@@ -798,16 +649,89 @@ fn print_final_ir<W: Write>(
 
 /// Parsed metadata definitions from a single IR dump, used to resolve inline
 /// `!N` references on IR lines back to the source spans they point at.
-struct SourceMap {
+pub(crate) struct SourceMap {
     entries: BTreeMap<u64, MdValue>,
     /// Metadata file index -> resolved source contents (or `None` if the file
     /// could not be read).  Keyed by index so each file/inline blob is read at
     /// most once, regardless of how many spans reference it.
     content_cache: BTreeMap<u64, Option<String>>,
+    /// Extra directories to search when a `SourceId` path is missing on disk
+    /// (e.g. the dump was produced on another machine).
+    source_roots: Vec<PathBuf>,
+    /// Absolute/original paths that could not be resolved even with roots.
+    missing_paths: BTreeSet<String>,
+    /// True if at least one `SourceId` file was successfully read from disk.
+    resolved_files: usize,
+}
+
+impl SourceMap {
+    pub(crate) fn empty() -> Self {
+        Self {
+            entries: BTreeMap::new(),
+            content_cache: BTreeMap::new(),
+            source_roots: Vec::new(),
+            missing_paths: BTreeSet::new(),
+            resolved_files: 0,
+        }
+    }
+
+    /// Merge every `!N = …` definition from `body` into this map.
+    /// Existing indices are kept (first wins) so earlier dumps win over later
+    /// reprints of the same index.
+    pub(crate) fn merge_from_text(&mut self, body: &str) {
+        for line in body.lines() {
+            if let Some((idx, value)) = parse_metadata_def(line) {
+                self.entries.entry(idx).or_insert(value);
+            }
+        }
+        // New defs may point at different files; drop stale lookups.
+        self.content_cache.clear();
+        self.missing_paths.clear();
+        self.resolved_files = 0;
+    }
+
+    /// Clone the metadata table for a fresh lookup (empty content cache).
+    pub(crate) fn clone_for_lookup(&self) -> Self {
+        Self {
+            entries: self.entries.clone(),
+            content_cache: BTreeMap::new(),
+            source_roots: self.source_roots.clone(),
+            missing_paths: BTreeSet::new(),
+            resolved_files: 0,
+        }
+    }
+
+    pub(crate) fn entry_count(&self) -> usize {
+        self.entries.len()
+    }
+
+    /// Directories searched when a metadata file path is not found as-is.
+    pub(crate) fn set_source_roots(&mut self, roots: impl IntoIterator<Item = PathBuf>) {
+        self.source_roots = roots.into_iter().collect();
+        // Invalidate disk lookups so new roots take effect.
+        self.content_cache.clear();
+        self.missing_paths.clear();
+        self.resolved_files = 0;
+    }
+
+    pub(crate) fn missing_paths(&self) -> &BTreeSet<String> {
+        &self.missing_paths
+    }
+
+    pub(crate) fn resolved_files(&self) -> usize {
+        self.resolved_files
+    }
+
+    /// Whether this dump references any on-disk source files (vs only inline).
+    pub(crate) fn has_source_ids(&self) -> bool {
+        self.entries
+            .values()
+            .any(|v| matches!(v, MdValue::SourceId(_)))
+    }
 }
 
 #[derive(Debug, Clone)]
-enum MdValue {
+pub(crate) enum MdValue {
     /// `!N = "/path/to/file.sw"` — a source file location.
     SourceId(String),
     /// `!N = inline "<code>"` — the source text inlined directly (emitted by
@@ -825,22 +749,15 @@ enum MdValue {
     Other,
 }
 
-fn parse_source_map(body: &str) -> SourceMap {
-    let mut entries = BTreeMap::new();
-    for line in body.lines() {
-        if let Some((idx, value)) = parse_metadata_def(line) {
-            entries.insert(idx, value);
-        }
-    }
-    SourceMap {
-        entries,
-        content_cache: BTreeMap::new(),
-    }
+pub(crate) fn parse_source_map(body: &str) -> SourceMap {
+    let mut sm = SourceMap::empty();
+    sm.merge_from_text(body);
+    sm
 }
 
 /// Whether the input contains any `!N = ...` metadata definition lines.
 /// Without them, `--print source` cannot resolve inline `!N` references.
-fn has_metadata_defs(cleaned: &str) -> bool {
+pub(crate) fn has_metadata_defs(cleaned: &str) -> bool {
     cleaned.lines().any(is_metadata_def_line)
 }
 
@@ -1007,13 +924,23 @@ impl SourceMap {
     }
 
     /// Resolve the source content for a metadata file index, caching the
-    /// result.  For `SourceId` the file is read from disk; for `Inline` the
-    /// embedded text is used directly.  Returns `None` if unreadable.
+    /// result.  For `SourceId` the file is read from disk (trying `source_roots`
+    /// when the recorded path is missing); for `Inline` the embedded text is
+    /// used directly.  Returns `None` if unreadable.
     fn content_for_idx(&mut self, file_idx: u64) -> Option<&String> {
         if !self.content_cache.contains_key(&file_idx) {
-            let content = match self.entries.get(&file_idx) {
-                Some(MdValue::SourceId(path)) => std::fs::read_to_string(path).ok(),
-                Some(MdValue::Inline(code)) => Some(code.clone()),
+            let content = match self.entries.get(&file_idx).cloned() {
+                Some(MdValue::SourceId(path)) => match self.read_source_file(&path) {
+                    Some(text) => {
+                        self.resolved_files += 1;
+                        Some(text)
+                    }
+                    None => {
+                        self.missing_paths.insert(path);
+                        None
+                    }
+                },
+                Some(MdValue::Inline(code)) => Some(code),
                 _ => None,
             };
             self.content_cache.insert(file_idx, content);
@@ -1021,6 +948,47 @@ impl SourceMap {
         self.content_cache.get(&file_idx).and_then(|c| c.as_ref())
     }
 
+    /// Try the recorded path, then each configured source root.
+    fn read_source_file(&self, path: &str) -> Option<String> {
+        let p = Path::new(path);
+        if let Ok(text) = std::fs::read_to_string(p) {
+            return Some(text);
+        }
+        for root in &self.source_roots {
+            if !root.is_dir() {
+                continue;
+            }
+            // root + full path (absolute paths are joined carefully below)
+            if p.is_relative() {
+                if let Ok(text) = std::fs::read_to_string(root.join(p)) {
+                    return Some(text);
+                }
+            }
+            // Strip leading components until a suffix exists under root
+            // (handles CI absolute paths like `/home/runner/.../src/foo.sw`).
+            let normals: Vec<_> = p
+                .components()
+                .filter(|c| matches!(c, Component::Normal(_)))
+                .collect();
+            for start in 0..normals.len() {
+                let rel: PathBuf = normals[start..].iter().collect();
+                let candidate = root.join(&rel);
+                if let Ok(text) = std::fs::read_to_string(&candidate) {
+                    return Some(text);
+                }
+            }
+            // Last resort: walk the root for a matching file name.
+            if let Some(name) = p.file_name() {
+                if let Some(found) = find_named_under(root, name) {
+                    if let Ok(text) = std::fs::read_to_string(&found) {
+                        return Some(text);
+                    }
+                }
+            }
+        }
+        None
+    }
+
     /// A human-readable label for the source of a span, used in the `// src:`
     /// header.  For `SourceId` this is the path; for `Inline` there is no path,
     /// so a placeholder is shown.
@@ -1081,11 +1049,24 @@ impl SourceMap {
     }
 }
 
+/// Depth-first search under `root` for a file whose name equals `name`.
+/// Caps the walk so a bad root cannot hang the UI.
+fn find_named_under(root: &Path, name: &std::ffi::OsStr) -> Option<PathBuf> {
+    walkdir::WalkDir::new(root)
+        .follow_links(false)
+        .max_depth(16)
+        .into_iter()
+        .filter_map(|e| e.ok())
+        .filter(|e| e.file_type().is_file())
+        .find(|e| e.file_name() == name)
+        .map(|e| e.into_path())
+}
+
 /// Expand a `[start, end)` byte range to whole-line boundaries of `content`,
 /// returning the full source line(s) that intersect the span (trailing newline
 /// excluded).  This gives readable context around a span that may otherwise be
 /// just a few tokens (e.g. an inline-asm mnemonic).
-fn expand_to_lines(content: &str, start: usize, end: usize) -> Option<&str> {
+pub(crate) fn expand_to_lines(content: &str, start: usize, end: usize) -> Option<&str> {
     if end < start || start > content.len() || end > content.len() {
         return None;
     }
@@ -1104,7 +1085,7 @@ fn expand_to_lines(content: &str, start: usize, end: usize) -> Option<&str> {
 }
 
 /// Find all inline `!N` metadata references in a line.
-fn find_md_refs(line: &str) -> Vec<u64> {
+pub(crate) fn find_md_refs(line: &str) -> Vec<u64> {
     let bytes = line.as_bytes();
     let mut refs = Vec::new();
     let mut i = 0;
@@ -1127,3 +1108,65 @@ fn find_md_refs(line: &str) -> Vec<u64> {
     }
     refs
 }
+
+
+
+#[cfg(test)]
+mod strip_tests {
+    use super::*;
+    use std::path::PathBuf;
+
+    #[test]
+    fn strip_version_suffix_basic() {
+        assert_eq!(strip_version_suffix("v0v1"), "v0");
+        assert_eq!(strip_version_suffix("foo_v0v1"), "foo_v0v1");
+        assert_eq!(strip_version_suffix("a v10v20 b"), "a v10 b");
+    }
+
+    #[test]
+    fn strip_version_suffix_unicode() {
+        assert_eq!(strip_version_suffix("→ v0v1"), "→ v0");
+        let _ = strip_version_suffix("日本語 v12v3");
+        let _ = strip_version_suffix("●v1v2");
+    }
+
+    #[test]
+    fn strip_version_on_repo_ir_files_does_not_panic() {
+        let roots = [
+            PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests"),
+            PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../test/src/ir_generation/tests"),
+        ];
+        let mut n = 0usize;
+        for root in roots {
+            if !root.exists() {
+                continue;
+            }
+            for entry in walkdir(&root) {
+                let Ok(text) = std::fs::read_to_string(&entry) else { continue };
+                let _ = strip_version_suffix(&text);
+                let _ = strip_metadata(&text);
+                let _ = strip_metadata_and_version(&text, MdMode::Without, VersionMode::Without);
+                n += 1;
+            }
+        }
+        // Sample IR fixtures are optional depending on checkout layout.
+        let _ = n;
+    }
+
+    fn walkdir(root: &std::path::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().and_then(|s| s.to_str()) == Some("ir") {
+                    out.push(p);
+                }
+            }
+        }
+        out
+    }
+}
diff --git a/forc-plugins/forc-ir-inspect/src/tui.rs b/forc-plugins/forc-ir-inspect/src/tui.rs
new file mode 100644
index 00000000000..4f9a930e1e6
--- /dev/null
+++ b/forc-plugins/forc-ir-inspect/src/tui.rs
@@ -0,0 +1,2562 @@
+//! Interactive TUI for browsing IR pass dumps.
+
+use std::collections::BTreeMap;
+use std::io::{self, Read, Stdout, Write};
+use std::process::Child;
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+use std::sync::mpsc::{self, Receiver, TryRecvError};
+use std::sync::{Arc, Mutex};
+use std::thread;
+use std::path::PathBuf;
+use std::time::{Duration, Instant};
+
+use anyhow::{bail, Result};
+use crossterm::event::{
+    self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind, KeyModifiers,
+    MouseButton, MouseEventKind,
+};
+use crossterm::execute;
+use crossterm::terminal::{
+    disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen,
+};
+use ratatui::backend::CrosstermBackend;
+use ratatui::layout::{Constraint, Direction, Layout, Margin, Rect};
+use ratatui::style::{Color, Modifier, Style};
+use ratatui::text::{Line, Span};
+use ratatui::widgets::{Block, Borders, Clear, List, ListItem, ListState, Paragraph, Wrap};
+use ratatui::{Frame, Terminal};
+
+use crate::config::{self, FocusName, SessionState};
+use crate::highlight;
+use crate::parse::{
+    diff_stats, find_functions, find_md_refs, parse, parse_source_map, prepare_ir_text,
+    print_final_ir, spawn_shell, strip_ansi, strip_metadata, FuncStats, MdMode, ParsedIr,
+    SourceMap, VersionMode,
+};
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum Focus {
+    Tree,
+    Main,
+}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum InputMode {
+    PassFilter,
+    FnFilter,
+    Search,
+    /// Prompt for a directory used to resolve missing source files.
+    SourceRoot,
+}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum LoadKind {
+    Input,
+    Diff,
+}
+
+struct PassEntry {
+    project: String,
+    /// Full `// IR:` header, e.g. `[dce] Dead Code Elimination`.
+    name: String,
+    body: String,
+    changed: bool,
+    /// Stats for the prepared IR of this pass (current filters/metadata/version).
+    stats: FuncStats,
+}
+
+struct ProjectGroup {
+    name: String,
+    expanded: bool,
+    passes: Vec<usize>,
+}
+
+#[derive(Clone, Copy)]
+enum TreeRow {
+    Project(usize),
+    Pass(usize),
+}
+
+enum LoadOutcome {
+    Ir(String),
+    Diff { text: String, pass_idx: usize },
+    Err(String),
+    Cancelled,
+}
+
+struct LoadingJob {
+    kind: LoadKind,
+    started: Instant,
+    rx: Receiver<LoadOutcome>,
+    /// Full command / path shown in the loading modal (not truncated).
+    label: String,
+    child: Arc<Mutex<Option<Child>>>,
+    cancelled: Arc<AtomicBool>,
+    /// Bytes read from the command/file so far (updated by the worker).
+    bytes_received: Arc<AtomicUsize>,
+}
+
+pub(crate) struct TuiOptions {
+    pub input_path: Option<String>,
+    pub cmd: Option<String>,
+    pub filter_fn: Vec<String>,
+    pub metadata: MdMode,
+    pub version: VersionMode,
+    pub source: bool,
+    pub start_diff: bool,
+}
+
+struct App {
+    opts: TuiOptions,
+    passes: Vec<PassEntry>,
+    projects: Vec<ProjectGroup>,
+    tree_rows: Vec<TreeRow>,
+    list_state: ListState,
+    focus: Focus,
+    input_mode: Option<InputMode>,
+    input_buf: String,
+    pass_filter: String,
+    fn_filter: String,
+    search: String,
+    search_matches: Vec<usize>,
+    search_idx: usize,
+    scroll: u16,
+    h_scroll: u16,
+    show_diff: bool,
+    show_help: bool,
+    show_line_numbers: bool,
+    metadata: MdMode,
+    version: VersionMode,
+    show_source: bool,
+    /// Extra directory searched when IR metadata paths are missing on disk.
+    source_root: Option<PathBuf>,
+    /// All `!N = …` defs seen in the loaded dump (survives function filters).
+    cached_source_map: SourceMap,
+    status: String,
+    status_ttl: Option<Instant>,
+    main_text: String,
+    main_is_diff: bool,
+    stats_line: String,
+    cached_lines: Vec<Line<'static>>,
+    dirty: bool,
+    loading: Option<LoadingJob>,
+    tree_area: Rect,
+    main_area: Rect,
+    /// Visible text rows in the main panel (excluding borders).
+    main_view_rows: u16,
+    /// When false, main panel shows plain text (SSA highlights still apply).
+    syntax_highlight: bool,
+    /// SSA name → palette index. Background always overrides syntax.
+    ssa_highlights: BTreeMap<String, usize>,
+    /// Next palette slot to assign when focusing a new SSA.
+    ssa_next_slot: usize,
+    /// Cursor into main-panel text (line, char col), set by mouse click/move.
+    main_cursor_line: usize,
+    main_cursor_col: usize,
+    /// Navigation/view restore applied once after the first successful load.
+    pending_restore: Option<SessionState>,
+    needs_persist: bool,
+}
+
+impl App {
+    fn new(opts: TuiOptions) -> Self {
+        let (cfg, session) = config::load_session(opts.cmd.as_deref(), opts.input_path.as_deref());
+        let restored = session.is_some();
+        let s = session.unwrap_or_default();
+
+        let metadata = if restored {
+            MdMode::from(s.metadata)
+        } else {
+            opts.metadata
+        };
+        let version = if restored {
+            VersionMode::from(s.version)
+        } else {
+            opts.version
+        };
+        let show_source = if restored { s.show_source } else { opts.source };
+        let show_diff = if restored { s.show_diff } else { opts.start_diff };
+        let fn_filter = if restored {
+            s.fn_filter.clone()
+        } else {
+            opts.filter_fn.join(",")
+        };
+        let focus = match s.focus {
+            FocusName::Tree => Focus::Tree,
+            FocusName::Main => Focus::Main,
+        };
+        let show_line_numbers = if restored { s.show_line_numbers } else { true };
+        let syntax_highlight = if restored { s.syntax_highlight } else { true };
+        let pending_restore = restored.then_some(s.clone());
+
+        Self {
+            metadata,
+            version,
+            show_source,
+            source_root: cfg.source_root,
+            cached_source_map: SourceMap::empty(),
+            show_diff,
+            fn_filter,
+            opts,
+            passes: Vec::new(),
+            projects: Vec::new(),
+            tree_rows: Vec::new(),
+            list_state: ListState::default(),
+            focus,
+            input_mode: None,
+            input_buf: String::new(),
+            pass_filter: if restored {
+                s.pass_filter.clone()
+            } else {
+                String::new()
+            },
+            search: if restored {
+                s.search.clone()
+            } else {
+                String::new()
+            },
+            search_matches: Vec::new(),
+            search_idx: 0,
+            scroll: if restored { s.scroll } else { 0 },
+            h_scroll: if restored { s.h_scroll } else { 0 },
+            show_help: false,
+            show_line_numbers,
+            syntax_highlight,
+            ssa_highlights: BTreeMap::new(),
+            ssa_next_slot: 0,
+            main_cursor_line: 0,
+            main_cursor_col: 0,
+            status: String::new(),
+            status_ttl: None,
+            main_text: String::from("(waiting for IR…)"),
+            main_is_diff: false,
+            stats_line: String::new(),
+            cached_lines: Vec::new(),
+            dirty: true,
+            loading: None,
+            tree_area: Rect::default(),
+            main_area: Rect::default(),
+            main_view_rows: 1,
+            pending_restore,
+            needs_persist: false,
+        }
+    }
+
+    fn mark_persist(&mut self) {
+        self.needs_persist = true;
+    }
+
+    fn flush_persist(&mut self) {
+        if !self.needs_persist {
+            return;
+        }
+        self.needs_persist = false;
+        let session = self.snapshot_session();
+        let _ = config::persist(
+            self.opts.cmd.as_deref(),
+            self.opts.input_path.as_deref(),
+            self.source_root.as_deref(),
+            session,
+        );
+    }
+
+    fn snapshot_session(&self) -> SessionState {
+        let focus = match self.focus {
+            Focus::Tree => FocusName::Tree,
+            Focus::Main => FocusName::Main,
+        };
+        let (selected_project, selected_pass) = match self.selected_pass() {
+            Some(p) => (Some(p.project.clone()), Some(p.name.clone())),
+            None => (None, None),
+        };
+        SessionState {
+            focus,
+            pass_filter: self.pass_filter.clone(),
+            fn_filter: self.fn_filter.clone(),
+            search: self.search.clone(),
+            scroll: self.scroll,
+            h_scroll: self.h_scroll,
+            show_diff: self.show_diff,
+            show_line_numbers: self.show_line_numbers,
+            syntax_highlight: self.syntax_highlight,
+            metadata: self.metadata.into(),
+            version: self.version.into(),
+            show_source: self.show_source,
+            selected_project,
+            selected_pass,
+            expanded_projects: self
+                .projects
+                .iter()
+                .filter(|p| p.expanded)
+                .map(|p| p.name.clone())
+                .collect(),
+        }
+    }
+
+    fn apply_pending_restore(&mut self) {
+        let Some(r) = self.pending_restore.take() else {
+            return;
+        };
+        for p in &mut self.projects {
+            p.expanded = r.expanded_projects.iter().any(|n| n == &p.name);
+        }
+        self.select_pass_by_project_and_name(
+            r.selected_project.as_deref(),
+            r.selected_pass.as_deref(),
+        );
+        self.scroll = r.scroll;
+        self.h_scroll = r.h_scroll;
+    }
+
+    fn is_loading(&self) -> bool {
+        self.loading.is_some()
+    }
+
+    fn spinner(&self) -> &'static str {
+        const FRAMES: &[&str] = &["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+        let Some(job) = &self.loading else {
+            return FRAMES[0];
+        };
+        let i = (job.started.elapsed().as_millis() / 80) as usize % FRAMES.len();
+        FRAMES[i]
+    }
+
+    fn set_status(&mut self, msg: impl Into<String>, secs: u64) {
+        self.status = msg.into();
+        self.status_ttl = Some(Instant::now() + Duration::from_secs(secs));
+    }
+
+    fn fn_filters(&self) -> Vec<String> {
+        self.fn_filter
+            .split(',')
+            .map(|s| s.trim().to_string())
+            .filter(|s| !s.is_empty())
+            .collect()
+    }
+
+    fn start_load(&mut self) {
+        if self.is_loading() {
+            return;
+        }
+        let cmd = self.opts.cmd.clone();
+        let path = self.opts.input_path.clone();
+        // Keep the full command — the loading modal wraps as needed.
+        let label = if let Some(c) = &cmd {
+            format!("running `{c}`")
+        } else if let Some(p) = &path {
+            format!("reading `{p}`")
+        } else {
+            String::from("loading")
+        };
+
+        let (tx, rx) = mpsc::channel();
+        let child_slot = Arc::new(Mutex::new(None));
+        let cancelled = Arc::new(AtomicBool::new(false));
+        let bytes_received = Arc::new(AtomicUsize::new(0));
+        let child_w = Arc::clone(&child_slot);
+        let cancel_w = Arc::clone(&cancelled);
+        let bytes_w = Arc::clone(&bytes_received);
+
+        thread::spawn(move || {
+            let outcome = match (cmd, path) {
+                (Some(cmd), _) => match spawn_shell(&cmd) {
+                    Ok(mut child) => {
+                        let mut out = match child.stdout.take() {
+                            Some(s) => s,
+                            None => {
+                                let _ = tx.send(LoadOutcome::Err(
+                                    "failed to capture `--cmd` stdout".into(),
+                                ));
+                                return;
+                            }
+                        };
+                        if let Ok(mut slot) = child_w.lock() {
+                            *slot = Some(child);
+                        }
+                        let mut data = Vec::new();
+                        let mut buf = [0u8; 64 * 1024];
+                        let read_res = loop {
+                            if cancel_w.load(Ordering::SeqCst) {
+                                break Ok(());
+                            }
+                            match out.read(&mut buf) {
+                                Ok(0) => break Ok(()),
+                                Ok(n) => {
+                                    bytes_w.fetch_add(n, Ordering::Relaxed);
+                                    data.extend_from_slice(&buf[..n]);
+                                }
+                                Err(e) if e.kind() == io::ErrorKind::Interrupted => continue,
+                                Err(e) => break Err(e),
+                            }
+                        };
+                        let status = child_w
+                            .lock()
+                            .ok()
+                            .and_then(|mut s| s.take())
+                            .and_then(|mut c| c.wait().ok());
+                        let text = String::from_utf8_lossy(&data).into_owned();
+                        if cancel_w.load(Ordering::SeqCst) {
+                            LoadOutcome::Cancelled
+                        } else if let Err(e) = read_res {
+                            LoadOutcome::Err(format!("failed to read `--cmd` output: {e}"))
+                        } else if text.trim().is_empty() && status.is_some_and(|s| !s.success()) {
+                            let code = status.and_then(|s| s.code()).unwrap_or(-1);
+                            LoadOutcome::Err(format!(
+                                "`--cmd` exited with status {code} and produced no output"
+                            ))
+                        } else {
+                            LoadOutcome::Ir(text)
+                        }
+                    }
+                    Err(e) => LoadOutcome::Err(format!("{e:#}")),
+                },
+                (None, Some(path)) => match std::fs::File::open(&path) {
+                    Ok(mut f) => {
+                        let mut data = Vec::new();
+                        let mut buf = [0u8; 64 * 1024];
+                        let read_res = loop {
+                            if cancel_w.load(Ordering::SeqCst) {
+                                break Ok(());
+                            }
+                            match f.read(&mut buf) {
+                                Ok(0) => break Ok(()),
+                                Ok(n) => {
+                                    bytes_w.fetch_add(n, Ordering::Relaxed);
+                                    data.extend_from_slice(&buf[..n]);
+                                }
+                                Err(e) if e.kind() == io::ErrorKind::Interrupted => continue,
+                                Err(e) => break Err(e),
+                            }
+                        };
+                        if cancel_w.load(Ordering::SeqCst) {
+                            LoadOutcome::Cancelled
+                        } else if let Err(e) = read_res {
+                            LoadOutcome::Err(format!("failed to read {path}: {e}"))
+                        } else {
+                            LoadOutcome::Ir(String::from_utf8_lossy(&data).into_owned())
+                        }
+                    }
+                    Err(e) => LoadOutcome::Err(format!("failed to read {path}: {e}")),
+                },
+                _ => LoadOutcome::Err("no input path or --cmd provided".into()),
+            };
+            let _ = tx.send(outcome);
+        });
+
+        self.loading = Some(LoadingJob {
+            kind: LoadKind::Input,
+            started: Instant::now(),
+            rx,
+            label,
+            child: child_slot,
+            cancelled,
+            bytes_received,
+        });
+        self.status.clear();
+        self.status_ttl = None;
+    }
+
+    fn cancel_load(&mut self) {
+        let Some(job) = &self.loading else {
+            return;
+        };
+        job.cancelled.store(true, Ordering::SeqCst);
+        if let Ok(mut slot) = job.child.lock() {
+            if let Some(mut child) = slot.take() {
+                let _ = child.kill();
+                let _ = child.wait();
+            }
+        }
+        self.set_status("Cancelled…", 2);
+    }
+
+    fn poll_loading(&mut self) -> bool {
+        let Some(job) = &self.loading else {
+            return false;
+        };
+        match job.rx.try_recv() {
+            Ok(outcome) => {
+                let elapsed = job.started.elapsed();
+                let kind = job.kind;
+                self.loading = None;
+                match outcome {
+                    LoadOutcome::Ir(raw) => match self.apply_raw(&raw) {
+                        Ok(()) => self.set_status(
+                            format!(
+                                "Loaded {} passes in {:.1}s",
+                                self.passes.len(),
+                                elapsed.as_secs_f32()
+                            ),
+                            3,
+                        ),
+                        Err(e) => {
+                            self.main_text = format!("(load failed)\n{e:#}");
+                            self.main_is_diff = false;
+                            self.dirty = true;
+                            self.set_status(format!("Load failed: {e:#}"), 8);
+                        }
+                    },
+                    LoadOutcome::Diff { text, pass_idx } => {
+                        if self.selected_pass_idx() == Some(pass_idx) && self.show_diff {
+                            self.main_text = text;
+                            self.main_is_diff = true;
+                            self.dirty = true;
+                            self.recompute_search();
+                            self.set_status(
+                                format!("Diff ready in {:.1}s", elapsed.as_secs_f32()),
+                                2,
+                            );
+                        }
+                    }
+                    LoadOutcome::Err(e) => {
+                        if self.passes.is_empty() {
+                            self.main_text = format!("(load failed)\n{e}");
+                            self.main_is_diff = false;
+                            self.dirty = true;
+                        }
+                        self.set_status(format!("Load failed: {e}"), 8);
+                    }
+                    LoadOutcome::Cancelled => {
+                        if kind == LoadKind::Input && self.passes.is_empty() {
+                            self.main_text =
+                                String::from("(cancelled — press F5 to retry)");
+                            self.main_is_diff = false;
+                            self.dirty = true;
+                        }
+                        self.set_status("Cancelled", 3);
+                    }
+                }
+                true
+            }
+            Err(TryRecvError::Empty) => false,
+            Err(TryRecvError::Disconnected) => {
+                self.loading = None;
+                self.set_status("Load worker disconnected", 8);
+                true
+            }
+        }
+    }
+
+    fn apply_raw(&mut self, raw: &str) -> Result<()> {
+        let keep_project = self
+            .selected_pass()
+            .map(|p| p.project.clone())
+            .or_else(|| {
+                self.pending_restore
+                    .as_ref()
+                    .and_then(|r| r.selected_project.clone())
+            });
+        let keep_pass = self
+            .selected_pass()
+            .map(|p| p.name.clone())
+            .or_else(|| {
+                self.pending_restore
+                    .as_ref()
+                    .and_then(|r| r.selected_pass.clone())
+            })
+            .unwrap_or_default();
+        let restoring = self.pending_restore.is_some();
+        let cleaned = strip_ansi(raw);
+        // Cache every metadata definition from the full dump up front. Function
+        // filters later drop the `!N = …` decl section from the view, but
+        // source overlay still needs those defs to resolve spans.
+        let mut sm = SourceMap::empty();
+        if let Some(root) = &self.source_root {
+            sm.set_source_roots([root.clone()]);
+        }
+        sm.merge_from_text(&cleaned);
+        self.cached_source_map = sm;
+        let irs = parse(&cleaned);
+        if irs.is_empty() {
+            bail!("no `// IR:` dumps found in input");
+        }
+        self.rebuild_passes(&irs);
+        if restoring {
+            self.apply_pending_restore();
+        } else {
+            self.recompute_tree();
+            self.select_pass_by_project_and_name(keep_project.as_deref(), Some(&keep_pass));
+            self.scroll = 0;
+            self.h_scroll = 0;
+        }
+        self.refresh_main();
+        // Clamp scroll after content is known.
+        let max = self.main_text.lines().count().saturating_sub(1) as u16;
+        self.scroll = self.scroll.min(max);
+        self.mark_persist();
+        Ok(())
+    }
+
+    fn request_reload(&mut self) {
+        if self.is_loading() {
+            self.set_status("Already loading…", 2);
+            return;
+        }
+        self.start_load();
+    }
+
+    fn rebuild_passes(&mut self, irs: &[ParsedIr]) {
+        let filters = self.fn_filters();
+        let mut previous: Option<String> = None;
+        let mut entries = Vec::with_capacity(irs.len());
+        for ir in irs {
+            if ir.is_initial() {
+                previous = None;
+            }
+            let prepared =
+                prepare_ir_text(&filters, self.metadata, self.version, ir).unwrap_or_default();
+            let changed = previous.as_ref().map(|p| p != &prepared).unwrap_or(true);
+            let stats = FuncStats::compute_stats(&prepared);
+            previous = Some(prepared);
+            entries.push(PassEntry {
+                project: ir.project.clone(),
+                name: ir.pass_name.clone(),
+                body: ir.body.clone(),
+                changed,
+                stats,
+            });
+        }
+        self.passes = entries;
+        self.rebuild_projects();
+    }
+
+    fn rebuild_projects(&mut self) {
+        let mut projects = Vec::<ProjectGroup>::new();
+        for (i, entry) in self.passes.iter().enumerate() {
+            match projects.last_mut() {
+                Some(p) if p.name == entry.project => p.passes.push(i),
+                _ => projects.push(ProjectGroup {
+                    name: entry.project.clone(),
+                    expanded: false,
+                    passes: vec![i],
+                }),
+            }
+        }
+        for p in &mut projects {
+            if let Some(old) = self.projects.iter().find(|o| o.name == p.name) {
+                p.expanded = old.expanded;
+            }
+        }
+        self.projects = projects;
+    }
+
+    fn recompute_tree(&mut self) {
+        let pf = self.pass_filter.to_ascii_lowercase();
+        let prev = self.selected_pass_idx();
+        self.tree_rows.clear();
+        for (pi, proj) in self.projects.iter().enumerate() {
+            let visible: Vec<usize> = proj
+                .passes
+                .iter()
+                .copied()
+                .filter(|&i| {
+                    if pf.is_empty() {
+                        return true;
+                    }
+                    let name = &self.passes[i].name;
+                    name.to_ascii_lowercase().contains(&pf)
+                        || pass_short_label(name).to_ascii_lowercase().contains(&pf)
+                })
+                .collect();
+            if visible.is_empty() {
+                continue;
+            }
+            self.tree_rows.push(TreeRow::Project(pi));
+            if proj.expanded {
+                for pass_idx in visible {
+                    self.tree_rows.push(TreeRow::Pass(pass_idx));
+                }
+            }
+        }
+        if let Some(pass_idx) = prev {
+            if let Some(row) = self
+                .tree_rows
+                .iter()
+                .position(|r| matches!(r, TreeRow::Pass(i) if *i == pass_idx))
+            {
+                self.list_state.select(Some(row));
+                return;
+            }
+        }
+        let first = self
+            .tree_rows
+            .iter()
+            .position(|r| matches!(r, TreeRow::Pass(_)))
+            .or_else(|| (!self.tree_rows.is_empty()).then_some(0));
+        self.list_state.select(first);
+    }
+
+    fn select_pass_by_project_and_name(
+        &mut self,
+        project: Option<&str>,
+        name: Option<&str>,
+    ) {
+        let name = name.unwrap_or("").trim();
+        if name.is_empty() {
+            self.recompute_tree();
+            if let Some(row) = self
+                .tree_rows
+                .iter()
+                .position(|r| matches!(r, TreeRow::Pass(_)))
+            {
+                self.list_state.select(Some(row));
+            }
+            return;
+        }
+        let pass_idx = self
+            .passes
+            .iter()
+            .position(|p| {
+                p.name == name && project.map(|pr| pr == p.project).unwrap_or(true)
+            })
+            .or_else(|| self.passes.iter().position(|p| p.name == name));
+        let Some(pass_idx) = pass_idx else {
+            self.recompute_tree();
+            return;
+        };
+        if let Some(proj) = self
+            .projects
+            .iter_mut()
+            .find(|p| p.passes.contains(&pass_idx))
+        {
+            proj.expanded = true;
+        }
+        self.recompute_tree();
+        if let Some(row) = self
+            .tree_rows
+            .iter()
+            .position(|r| matches!(r, TreeRow::Pass(i) if *i == pass_idx))
+        {
+            self.list_state.select(Some(row));
+        }
+    }
+
+    fn selected_tree_row(&self) -> Option<TreeRow> {
+        self.list_state
+            .selected()
+            .and_then(|i| self.tree_rows.get(i).copied())
+    }
+
+    fn selected_pass_idx(&self) -> Option<usize> {
+        match self.selected_tree_row()? {
+            TreeRow::Pass(i) => Some(i),
+            TreeRow::Project(_) => None,
+        }
+    }
+
+    fn selected_pass(&self) -> Option<&PassEntry> {
+        self.selected_pass_idx().map(|i| &self.passes[i])
+    }
+
+    fn toggle_selected_project(&mut self) {
+        let Some(TreeRow::Project(pi)) = self.selected_tree_row() else {
+            return;
+        };
+        if let Some(p) = self.projects.get_mut(pi) {
+            p.expanded = !p.expanded;
+        }
+        self.recompute_tree();
+    }
+
+    fn cancel_diff_only(&mut self) {
+        let Some(job) = &self.loading else {
+            return;
+        };
+        if job.kind != LoadKind::Diff {
+            return;
+        }
+        job.cancelled.store(true, Ordering::SeqCst);
+        self.loading = None;
+    }
+
+    fn start_diff_job(
+        &mut self,
+        pass_idx: usize,
+        prev_text: String,
+        text: String,
+        prev_name: String,
+    ) -> bool {
+        if self
+            .loading
+            .as_ref()
+            .is_some_and(|j| j.kind == LoadKind::Input)
+        {
+            return false;
+        }
+        self.cancel_diff_only();
+        let label = format!("diff vs `{prev_name}`");
+        let (tx, rx) = mpsc::channel();
+        let cancelled = Arc::new(AtomicBool::new(false));
+        let cancel_w = Arc::clone(&cancelled);
+        thread::spawn(move || {
+            if cancel_w.load(Ordering::SeqCst) {
+                let _ = tx.send(LoadOutcome::Cancelled);
+                return;
+            }
+            let changeset = prettydiff::diff_lines(&prev_text, &text);
+            let ops = changeset.diff();
+            if cancel_w.load(Ordering::SeqCst) {
+                let _ = tx.send(LoadOutcome::Cancelled);
+                return;
+            }
+            let (adds, removes) = diff_stats(&ops);
+            let mut rendered =
+                format!("// Diff vs {prev_name}: adds={adds} removes={removes}\n");
+            rendered.push_str(&render_diff(&ops));
+            let _ = tx.send(LoadOutcome::Diff {
+                text: rendered,
+                pass_idx,
+            });
+        });
+        self.loading = Some(LoadingJob {
+            kind: LoadKind::Diff,
+            started: Instant::now(),
+            rx,
+            label,
+            child: Arc::new(Mutex::new(None)),
+            cancelled,
+            bytes_received: Arc::new(AtomicUsize::new(0)),
+        });
+        true
+    }
+
+    /// Prepare a pass body for the main panel, optionally embedding source.
+    ///
+    /// When source overlay is on, metadata references are kept long enough to
+    /// resolve spans (even if metadata display is off), then stripped again if
+    /// the user has metadata toggled off.
+    ///
+    /// Returns `(text, needs_source_root, sample_missing_path)`.
+    fn prepare_pass_view(&self, pass_idx: usize) -> Option<(String, bool, Option<String>)> {
+        let filters = self.fn_filters();
+        let pass = &self.passes[pass_idx];
+        let ir = ParsedIr {
+            project: pass.project.clone(),
+            pass_name: pass.name.clone(),
+            body: pass.body.clone(),
+        };
+        let md = if self.show_source && self.metadata == MdMode::Without {
+            // Need inline `!N` refs to resolve source spans.
+            MdMode::AsParsed
+        } else {
+            self.metadata
+        };
+        let mut text = prepare_ir_text(&filters, md, self.version, &ir)?;
+        let mut needs_source_root = false;
+        let mut sample_missing = None;
+        if self.show_source {
+            // Prefer the dump-wide cache so function filters can't hide defs.
+            let mut sm = if self.cached_source_map.entry_count() > 0 {
+                self.cached_source_map.clone_for_lookup()
+            } else {
+                parse_source_map(&ir.body)
+            };
+            // Also merge this pass body in case it has newer/extra defs.
+            sm.merge_from_text(&ir.body);
+            if let Some(root) = &self.source_root {
+                sm.set_source_roots([root.clone()]);
+            }
+            let mut buf = Vec::new();
+            let _ = print_final_ir(&mut buf, &text, Some(&mut sm));
+            text = String::from_utf8_lossy(&buf).into_owned();
+            if self.metadata == MdMode::Without {
+                text = strip_metadata(&text);
+            }
+            needs_source_root = sm.has_source_ids() && sm.resolved_files() == 0;
+            sample_missing = sm.missing_paths().iter().next().cloned();
+        }
+        Some((text, needs_source_root, sample_missing))
+    }
+
+    fn open_source_root_modal(&mut self, hint: &str) {
+        self.input_mode = Some(InputMode::SourceRoot);
+        self.input_buf = self
+            .source_root
+            .as_ref()
+            .map(|p| p.display().to_string())
+            .unwrap_or_default();
+        if !hint.is_empty() {
+            self.set_status(hint, 6);
+        }
+    }
+
+    fn apply_source_root(&mut self, raw: &str) -> bool {
+        let trimmed = raw.trim();
+        if trimmed.is_empty() {
+            self.set_status("source root: empty path", 3);
+            return false;
+        }
+        let path = PathBuf::from(trimmed);
+        let path = if path.is_absolute() {
+            path
+        } else {
+            std::env::current_dir()
+                .map(|cwd| cwd.join(&path))
+                .unwrap_or(path)
+        };
+        if !path.is_dir() {
+            self.set_status(
+                format!("source root: not a directory: {}", path.display()),
+                5,
+            );
+            return false;
+        }
+        self.source_root = Some(path.clone());
+        self.cached_source_map.set_source_roots([path.clone()]);
+        self.mark_persist();
+        self.flush_persist();
+        self.set_status(format!("source root: {}", path.display()), 3);
+        true
+    }
+
+    fn refresh_main(&mut self) {
+        self.cancel_diff_only();
+        let Some(idx) = self.selected_pass_idx() else {
+            self.main_text = if matches!(self.selected_tree_row(), Some(TreeRow::Project(_))) {
+                String::from("(select a pass under the project)")
+            } else {
+                String::from("(no pass selected)")
+            };
+            self.main_is_diff = false;
+            self.stats_line.clear();
+            self.dirty = true;
+            return;
+        };
+
+        let Some((text, needs_root, missing)) = self.prepare_pass_view(idx) else {
+            self.main_text = String::from("(no functions match the current filter)");
+            self.main_is_diff = false;
+            self.stats_line.clear();
+            self.dirty = true;
+            return;
+        };
+        if needs_root && self.input_mode.is_none() {
+            let hint = match missing {
+                Some(p) => format!(
+                    "missing `{p}` — enter the project root that contains your .sw sources"
+                ),
+                None => String::from(
+                    "source files not found — enter the project root directory"
+                ),
+            };
+            self.open_source_root_modal(&hint);
+        }
+
+        // Stats from IR without the source overlay so comment lines don't
+        // inflate instruction counts.
+        let stats_src = {
+            let filters = self.fn_filters();
+            let ir = ParsedIr {
+                project: self.passes[idx].project.clone(),
+                pass_name: self.passes[idx].name.clone(),
+                body: self.passes[idx].body.clone(),
+            };
+            prepare_ir_text(&filters, self.metadata, self.version, &ir)
+                .unwrap_or_else(|| text.clone())
+        };
+        let stats = FuncStats::compute_stats(&stats_src);
+        let prev_stats = if idx > 0 && self.passes[idx - 1].project == self.passes[idx].project {
+            Some(self.passes[idx - 1].stats.clone())
+        } else {
+            None
+        };
+        self.stats_line = format_full_stats(&stats, prev_stats.as_ref());
+        self.passes[idx].stats = stats;
+
+        if self.show_diff && idx > 0 {
+            let prev_project = self.passes[idx - 1].project.clone();
+            let prev_name = self.passes[idx - 1].name.clone();
+            if prev_project == self.passes[idx].project {
+                if let Some((prev_text, _, _)) = self.prepare_pass_view(idx - 1) {
+                    if self.start_diff_job(idx, prev_text.clone(), text.clone(), prev_name.clone())
+                    {
+                        self.main_text = String::from("(computing diff…)");
+                        self.main_is_diff = false;
+                        self.dirty = true;
+                        return;
+                    }
+                    let changeset = prettydiff::diff_lines(&prev_text, &text);
+                    let ops = changeset.diff();
+                    let (adds, removes) = diff_stats(&ops);
+                    let mut rendered =
+                        format!("// Diff vs {prev_name}: adds={adds} removes={removes}\n");
+                    rendered.push_str(&render_diff(&ops));
+                    self.main_text = rendered;
+                    self.main_is_diff = true;
+                    self.dirty = true;
+                    self.recompute_search();
+                    return;
+                }
+            }
+        }
+
+        self.main_text = text;
+        self.main_is_diff = false;
+        self.dirty = true;
+        self.recompute_search();
+    }
+    fn recompute_search(&mut self) {
+        self.search_matches.clear();
+        if self.search.is_empty() {
+            return;
+        }
+        let needle = self.search.to_ascii_lowercase();
+        for (i, line) in self.main_text.lines().enumerate() {
+            if line.to_ascii_lowercase().contains(&needle) {
+                self.search_matches.push(i);
+            }
+        }
+        self.search_idx = 0;
+        if let Some(&line) = self.search_matches.first() {
+            self.scroll = line as u16;
+        }
+    }
+
+    fn ensure_cache(&mut self) {
+        if !self.dirty {
+            self.clamp_scroll();
+            return;
+        }
+        let cur = self.search_matches.get(self.search_idx).copied();
+        let mut lines = highlight::highlight_ir_with_search(
+            &self.main_text,
+            self.main_is_diff,
+            &self.search,
+            cur,
+            self.syntax_highlight,
+        );
+        let ssa: Vec<(String, ratatui::style::Color)> = self
+            .ssa_highlights
+            .iter()
+            .map(|(name, &slot)| {
+                (
+                    name.clone(),
+                    highlight::SYMBOL_PALETTE[slot % highlight::SYMBOL_PALETTE.len()],
+                )
+            })
+            .collect();
+        highlight::apply_symbol_highlights(&mut lines, &ssa);
+        self.cached_lines = lines;
+        self.dirty = false;
+        self.clamp_scroll();
+    }
+
+    fn line_number_gutter_width(&self) -> u16 {
+        if self.show_line_numbers {
+            7 // "{:>4} │ "
+        } else {
+            0
+        }
+    }
+
+    /// Map a screen cell inside the main panel to (line, col) in `main_text`.
+    fn main_pos_from_screen(&self, col: u16, row: u16) -> Option<(usize, usize)> {
+        let inner = self.main_area.inner(Margin {
+            horizontal: 1,
+            vertical: 1,
+        });
+        if col < inner.x
+            || row < inner.y
+            || col >= inner.x.saturating_add(inner.width)
+            || row >= inner.y.saturating_add(inner.height)
+        {
+            return None;
+        }
+        let rel_row = (row - inner.y) as usize;
+        let line = self.scroll as usize + rel_row;
+        let gutter = self.line_number_gutter_width();
+        let rel_col = col.saturating_sub(inner.x);
+        if rel_col < gutter {
+            return Some((line, 0));
+        }
+        let col_in_text = (rel_col - gutter) as usize + self.h_scroll as usize;
+        Some((line, col_in_text))
+    }
+
+    fn set_main_cursor_from_screen(&mut self, col: u16, row: u16) {
+        if let Some((line, c)) = self.main_pos_from_screen(col, row) {
+            self.main_cursor_line = line;
+            self.main_cursor_col = c;
+        }
+    }
+
+    fn toggle_syntax_highlight(&mut self) {
+        self.syntax_highlight = !self.syntax_highlight;
+        self.dirty = true;
+        self.mark_persist();
+        self.set_status(
+            if self.syntax_highlight {
+                "syntax highlight: ON"
+            } else {
+                "syntax highlight: OFF"
+            },
+            2,
+        );
+    }
+
+    fn toggle_symbol_at_cursor(&mut self) {
+        if self.focus != Focus::Main {
+            self.set_status("F2: focus the IR panel first", 3);
+            return;
+        }
+        let line = self.main_text.lines().nth(self.main_cursor_line).unwrap_or("");
+        let Some(name) = highlight::symbol_at_col(line, self.main_cursor_col, &self.main_text)
+        else {
+            self.set_status(
+                "F2: cursor is not on an SSA / local / method name",
+                3,
+            );
+            return;
+        };
+        if self.ssa_highlights.remove(&name).is_some() {
+            self.set_status(format!("highlight OFF: {name}"), 3);
+        } else {
+            let slot = self.ssa_next_slot;
+            self.ssa_next_slot = self.ssa_next_slot.wrapping_add(1);
+            self.ssa_highlights.insert(name.clone(), slot);
+            self.set_status(
+                format!(
+                    "highlight ON: {name} (color {})",
+                    (slot % highlight::SYMBOL_PALETTE.len()) + 1
+                ),
+                3,
+            );
+        }
+        self.dirty = true;
+    }
+
+    /// Keep vertical scroll inside the current main-panel content. Toggles like
+    /// metadata/version rewrite the text in place and can otherwise leave
+    /// `scroll` past the last line, which panics when slicing `cached_lines`.
+    fn clamp_scroll(&mut self) {
+        let max = self.main_text.lines().count().saturating_sub(1) as u16;
+        if self.scroll > max {
+            self.scroll = max;
+        }
+    }
+
+    fn select_next(&mut self) {
+        let len = self.tree_rows.len();
+        if len == 0 {
+            return;
+        }
+        let i = self.list_state.selected().unwrap_or(0);
+        self.list_state.select(Some((i + 1).min(len - 1)));
+        self.scroll = 0;
+        self.refresh_main();
+    }
+
+    fn select_prev(&mut self) {
+        if self.tree_rows.is_empty() {
+            return;
+        }
+        let i = self.list_state.selected().unwrap_or(0);
+        self.list_state.select(Some(i.saturating_sub(1)));
+        self.scroll = 0;
+        self.refresh_main();
+    }
+
+    fn activate_selection(&mut self) {
+        match self.selected_tree_row() {
+            Some(TreeRow::Project(_)) => self.toggle_selected_project(),
+            Some(TreeRow::Pass(_)) => {
+                self.scroll = 0;
+                self.refresh_main();
+            }
+            None => {}
+        }
+    }
+
+    fn click_tree_at(&mut self, row: usize) {
+        if row >= self.tree_rows.len() {
+            return;
+        }
+        self.focus = Focus::Tree;
+        self.list_state.select(Some(row));
+        self.activate_selection();
+    }
+
+    fn scroll_by(&mut self, delta: i32, step: u16) {
+        let max = self.main_text.lines().count().saturating_sub(1) as u16;
+        if delta < 0 {
+            self.scroll = self.scroll.saturating_sub(step);
+        } else {
+            self.scroll = self.scroll.saturating_add(step).min(max);
+        }
+    }
+
+    fn jump_next_fn(&mut self) {
+        let decls = find_functions(&self.main_text);
+        if decls.is_empty() {
+            self.set_status("No functions in view", 2);
+            return;
+        }
+        let cur = self.scroll as usize;
+        if let Some(d) = decls.iter().find(|d| d.start > cur).or_else(|| decls.first()) {
+            self.scroll = d.start as u16;
+            self.set_status(format!("→ fn {}", d.name), 2);
+        }
+    }
+
+    fn jump_prev_fn(&mut self) {
+        let decls = find_functions(&self.main_text);
+        if decls.is_empty() {
+            return;
+        }
+        let cur = self.scroll as usize;
+        if let Some(d) = decls
+            .iter()
+            .rev()
+            .find(|d| d.start < cur)
+            .or_else(|| decls.last())
+        {
+            self.scroll = d.start as u16;
+            self.set_status(format!("→ fn {}", d.name), 2);
+        }
+    }
+
+    fn copy_main(&mut self) {
+        match copy_text(&self.main_text) {
+            Ok(via) => self.set_status(
+                format!("Copied {} bytes via {via}", self.main_text.len()),
+                3,
+            ),
+            Err(e) => self.set_status(format!("Clipboard error: {e}"), 5),
+        }
+    }
+
+    /// Toggle metadata display on/off (`AsParsed` ↔ `Without`).
+    fn toggle_metadata(&mut self) {
+        let on = self.metadata != MdMode::Without;
+        self.metadata = if on {
+            MdMode::Without
+        } else {
+            MdMode::AsParsed
+        };
+        self.rederive_changed();
+        self.refresh_main();
+        self.set_status(
+            if on {
+                "metadata: OFF"
+            } else {
+                "metadata: ON"
+            },
+            2,
+        );
+    }
+
+    /// Toggle version suffixes on/off (`AsParsed` ↔ `Without`).
+    fn toggle_version(&mut self) {
+        let on = self.version != VersionMode::Without;
+        self.version = if on {
+            VersionMode::Without
+        } else {
+            VersionMode::AsParsed
+        };
+        self.rederive_changed();
+        self.refresh_main();
+        self.set_status(
+            if on {
+                "version: OFF"
+            } else {
+                "version: ON"
+            },
+            2,
+        );
+    }
+
+    fn rederive_changed(&mut self) {
+        let filters = self.fn_filters();
+        let mut previous: Option<String> = None;
+        for entry in &mut self.passes {
+            if entry.name == "Initial" {
+                previous = None;
+            }
+            let ir = ParsedIr {
+                project: entry.project.clone(),
+                pass_name: entry.name.clone(),
+                body: entry.body.clone(),
+            };
+            let prepared =
+                prepare_ir_text(&filters, self.metadata, self.version, &ir).unwrap_or_default();
+            entry.changed = previous.as_ref().map(|p| p != &prepared).unwrap_or(true);
+            entry.stats = FuncStats::compute_stats(&prepared);
+            previous = Some(prepared);
+        }
+    }
+
+    fn handle_mouse(&mut self, col: u16, row: u16, kind: MouseEventKind) {
+        let in_tree = contains(self.tree_area, col, row);
+        let in_main = contains(self.main_area, col, row);
+        match kind {
+            MouseEventKind::Down(MouseButton::Left) if in_tree => {
+                let inner = self.tree_area.inner(Margin {
+                    horizontal: 1,
+                    vertical: 1,
+                });
+                if row >= inner.y {
+                    let rel = (row - inner.y) as usize;
+                    let idx = self.list_state.offset().saturating_add(rel);
+                    self.click_tree_at(idx);
+                } else {
+                    self.focus = Focus::Tree;
+                }
+            }
+            MouseEventKind::Down(MouseButton::Left) if in_main => {
+                self.focus = Focus::Main;
+                self.set_main_cursor_from_screen(col, row);
+            }
+            MouseEventKind::Moved if in_main => {
+                self.set_main_cursor_from_screen(col, row);
+            }
+            MouseEventKind::Drag(MouseButton::Left) if in_main => {
+                self.focus = Focus::Main;
+                self.set_main_cursor_from_screen(col, row);
+            }
+            MouseEventKind::ScrollDown if in_tree => self.select_next(),
+            MouseEventKind::ScrollUp if in_tree => self.select_prev(),
+            MouseEventKind::ScrollDown => self.scroll_by(1, 3),
+            MouseEventKind::ScrollUp => self.scroll_by(-1, 3),
+            _ => {}
+        }
+    }
+}
+
+fn contains(area: Rect, col: u16, row: u16) -> bool {
+    col >= area.x
+        && row >= area.y
+        && col < area.x.saturating_add(area.width)
+        && row < area.y.saturating_add(area.height)
+}
+
+/// Full function stats for the status bar, with optional deltas vs the previous pass.
+fn format_full_stats(s: &FuncStats, prev: Option<&FuncStats>) -> String {
+    format_full_stats_spans(s, prev)
+        .into_iter()
+        .map(|s| s.content.to_string())
+        .collect()
+}
+
+fn append_stat_delta_spans(spans: &mut Vec<Span<'static>>, label: &str, cur: usize, prev: Option<usize>) {
+    if !spans.is_empty() {
+        spans.push(Span::styled(" ", Style::default().fg(Color::DarkGray)));
+    }
+    spans.push(Span::styled(
+        format!("{label}={cur}"),
+        Style::default().fg(Color::DarkGray),
+    ));
+    if let Some(p) = prev {
+        if p != cur {
+            let d = cur as isize - p as isize;
+            let style = if d > 0 {
+                Style::default().fg(Color::Green)
+            } else {
+                Style::default().fg(Color::Red)
+            };
+            spans.push(Span::styled(format!("({d:+})"), style));
+        }
+    }
+}
+
+/// Styled status-bar stats: absolute counts in gray, `+` deltas green, `-` deltas red.
+fn format_full_stats_spans(s: &FuncStats, prev: Option<&FuncStats>) -> Vec<Span<'static>> {
+    let mut spans = Vec::new();
+    append_stat_delta_spans(&mut spans, "args", s.args, prev.map(|p| p.args));
+    append_stat_delta_spans(&mut spans, "locals", s.locals, prev.map(|p| p.locals));
+    append_stat_delta_spans(&mut spans, "blocks", s.blocks, prev.map(|p| p.blocks));
+    append_stat_delta_spans(
+        &mut spans,
+        "instr",
+        s.instructions,
+        prev.map(|p| p.instructions),
+    );
+
+    let mut names: std::collections::BTreeSet<&str> = s.ops.keys().map(String::as_str).collect();
+    if let Some(p) = prev {
+        for k in p.ops.keys() {
+            names.insert(k.as_str());
+        }
+    }
+    for name in names {
+        let cur = s.ops.get(name).copied().unwrap_or(0);
+        let p = prev.and_then(|ps| ps.ops.get(name).copied());
+        append_stat_delta_spans(&mut spans, name, cur, p);
+    }
+    spans
+}
+
+/// Short pass label for the tree: keep `[name]`, drop the long description.
+/// Headers without brackets (`Initial`, `Final`) are kept as-is.
+fn pass_short_label(full: &str) -> &str {
+    let trimmed = full.trim();
+    if let Some(open) = trimmed.find('[') {
+        if let Some(close) = trimmed[open..].find(']') {
+            return &trimmed[open..open + close + 1];
+        }
+    }
+    trimmed
+}
+
+/// Signed delta only (no absolute count). `None` when unchanged or no previous.
+fn format_diff_only(cur: usize, prev: Option<usize>) -> Option<String> {
+    let p = prev?;
+    if p == cur {
+        return None;
+    }
+    let d = cur as isize - p as isize;
+    Some(format!("{d:+}"))
+}
+
+/// Compact stats shown beside each pass in the tree: deltas vs previous pass only.
+fn format_tree_stats(s: &FuncStats, prev: Option<&FuncStats>) -> String {
+    let mut parts = Vec::new();
+    if let Some(d) = format_diff_only(s.args, prev.map(|p| p.args)) {
+        parts.push(format!("a={d}"));
+    }
+    if let Some(d) = format_diff_only(s.locals, prev.map(|p| p.locals)) {
+        parts.push(format!("l={d}"));
+    }
+    if let Some(d) = format_diff_only(s.blocks, prev.map(|p| p.blocks)) {
+        parts.push(format!("b={d}"));
+    }
+    if let Some(d) = format_diff_only(s.instructions, prev.map(|p| p.instructions)) {
+        parts.push(format!("i={d}"));
+    }
+
+    // Include every opcode that changed (including removals).
+    let mut names: std::collections::BTreeSet<&str> = s.ops.keys().map(String::as_str).collect();
+    if let Some(p) = prev {
+        for k in p.ops.keys() {
+            names.insert(k.as_str());
+        }
+    }
+    for name in names {
+        let cur = s.ops.get(name).copied().unwrap_or(0);
+        let p = prev.and_then(|ps| ps.ops.get(name).copied());
+        if let Some(d) = format_diff_only(cur, p) {
+            parts.push(format!("{name}={d}"));
+        }
+    }
+
+    if parts.is_empty() {
+        String::new()
+    } else {
+        parts.join(" ")
+    }
+}
+
+fn render_diff(ops: &[prettydiff::basic::DiffOp<&str>]) -> String {
+    let mut out = String::new();
+    for op in ops {
+        match op {
+            prettydiff::basic::DiffOp::Equal(lines) => {
+                for l in *lines {
+                    out.push_str("  ");
+                    out.push_str(l);
+                    out.push('\n');
+                }
+            }
+            prettydiff::basic::DiffOp::Insert(lines) => {
+                for l in *lines {
+                    out.push_str("+ ");
+                    out.push_str(l);
+                    out.push('\n');
+                }
+            }
+            prettydiff::basic::DiffOp::Remove(lines) => {
+                for l in *lines {
+                    out.push_str("- ");
+                    out.push_str(l);
+                    out.push('\n');
+                }
+            }
+            prettydiff::basic::DiffOp::Replace(removed, inserted) => {
+                for l in *removed {
+                    out.push_str("- ");
+                    out.push_str(l);
+                    out.push('\n');
+                }
+                for l in *inserted {
+                    out.push_str("+ ");
+                    out.push_str(l);
+                    out.push('\n');
+                }
+            }
+        }
+    }
+    out
+}
+
+fn copy_text(text: &str) -> Result<&'static str> {
+    match arboard::Clipboard::new().and_then(|mut c| {
+        c.set_text(text.to_string())?;
+        Ok(())
+    }) {
+        Ok(()) => Ok("clipboard"),
+        Err(_) => {
+            let encoded = base64_encode(text.as_bytes());
+            let seq = format!("\x1b]52;c;{encoded}\x07");
+            let mut stdout = io::stdout();
+            stdout.write_all(seq.as_bytes())?;
+            stdout.flush()?;
+            Ok("OSC52")
+        }
+    }
+}
+
+fn base64_encode(data: &[u8]) -> String {
+    const TABLE: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    let mut out = String::with_capacity(data.len().div_ceil(3) * 4);
+    for chunk in data.chunks(3) {
+        let mut buf = [0u8; 3];
+        for (i, b) in chunk.iter().enumerate() {
+            buf[i] = *b;
+        }
+        let n = chunk.len();
+        let triple = ((buf[0] as u32) << 16) | ((buf[1] as u32) << 8) | (buf[2] as u32);
+        out.push(TABLE[((triple >> 18) & 0x3f) as usize] as char);
+        out.push(TABLE[((triple >> 12) & 0x3f) as usize] as char);
+        out.push(if n > 1 {
+            TABLE[((triple >> 6) & 0x3f) as usize] as char
+        } else {
+            '='
+        });
+        out.push(if n > 2 {
+            TABLE[(triple & 0x3f) as usize] as char
+        } else {
+            '='
+        });
+    }
+    out
+}
+
+pub(crate) fn run(opts: TuiOptions) -> Result<()> {
+    let mut app = App::new(opts);
+    app.start_load();
+
+    enable_raw_mode()?;
+    let mut stdout = io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend)?;
+
+    let result = event_loop(&mut terminal, &mut app);
+
+    disable_raw_mode()?;
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )?;
+    terminal.show_cursor()?;
+    result
+}
+
+fn event_loop(
+    terminal: &mut Terminal<CrosstermBackend<Stdout>>,
+    app: &mut App,
+) -> Result<()> {
+    loop {
+        if let Some(deadline) = app.status_ttl {
+            if Instant::now() >= deadline {
+                app.status.clear();
+                app.status_ttl = None;
+            }
+        }
+        let _ = app.poll_loading();
+        terminal.draw(|f| draw(f, app))?;
+        app.flush_persist();
+
+        let poll_ms = if app.is_loading() { 80 } else { 200 };
+        if !event::poll(Duration::from_millis(poll_ms))? {
+            continue;
+        }
+
+        match event::read()? {
+            Event::Key(key) if key.kind == KeyEventKind::Press => {
+                if app.show_help {
+                    app.show_help = false;
+                    continue;
+                }
+                if app.input_mode.is_none() {
+                    if matches!(key.code, KeyCode::Char('q') | KeyCode::Esc) {
+                        if app.is_loading() {
+                            app.cancel_load();
+                        }
+                        app.mark_persist();
+                        app.flush_persist();
+                        return Ok(());
+                    }
+                    if key.code == KeyCode::Char('c')
+                        && key.modifiers.contains(KeyModifiers::CONTROL)
+                    {
+                        if app.is_loading() {
+                            app.cancel_load();
+                            continue;
+                        }
+                        app.mark_persist();
+                        app.flush_persist();
+                        return Ok(());
+                    }
+                }
+                if app.is_loading() {
+                    continue;
+                }
+                if let Some(mode) = app.input_mode {
+                    match key.code {
+                        KeyCode::Esc => {
+                            app.input_mode = None;
+                            app.input_buf.clear();
+                        }
+                        KeyCode::Enter => {
+                            match mode {
+                                InputMode::PassFilter => {
+                                    app.pass_filter = app.input_buf.clone();
+                                    app.recompute_tree();
+                                    app.scroll = 0;
+                                    app.refresh_main();
+                                }
+                                InputMode::FnFilter => {
+                                    app.fn_filter = app.input_buf.clone();
+                                    app.rederive_changed();
+                                    app.scroll = 0;
+                                    app.refresh_main();
+                                    app.set_status(format!("fn filter: {}", app.fn_filter), 2);
+                                }
+                                InputMode::Search => {
+                                    app.search = app.input_buf.clone();
+                                    app.dirty = true;
+                                    app.recompute_search();
+                                }
+                                InputMode::SourceRoot => {
+                                    let raw = app.input_buf.clone();
+                                    if app.apply_source_root(&raw) {
+                                        app.input_mode = None;
+                                        app.input_buf.clear();
+                                        app.refresh_main();
+                                    }
+                                    // Keep modal open on invalid path.
+                                    continue;
+                                }
+                            }
+                            app.input_mode = None;
+                            app.input_buf.clear();
+                        }
+                        KeyCode::Backspace => {
+                            app.input_buf.pop();
+                        }
+                        KeyCode::Char(c) => app.input_buf.push(c),
+                        _ => {}
+                    }
+                    continue;
+                }
+
+                match key.code {
+                    KeyCode::Char('q') | KeyCode::Esc => return Ok(()),
+                    KeyCode::F(1) => app.toggle_syntax_highlight(),
+                    KeyCode::F(2) => app.toggle_symbol_at_cursor(),
+                    KeyCode::F(5) => app.request_reload(),
+                    KeyCode::Char('r') if key.modifiers.contains(KeyModifiers::CONTROL) => {
+                        app.request_reload();
+                    }
+                    KeyCode::Tab => {
+                        app.focus = match app.focus {
+                            Focus::Tree => Focus::Main,
+                            Focus::Main => Focus::Tree,
+                        };
+                    }
+                    KeyCode::Char('?') => app.show_help = true,
+                    KeyCode::Char('y') => app.copy_main(),
+                    KeyCode::Char('d') => {
+                        app.show_diff = !app.show_diff;
+                        app.scroll = 0;
+                        app.refresh_main();
+                        app.set_status(
+                            if app.show_diff {
+                                "Diff view ON"
+                            } else {
+                                "Diff view OFF"
+                            },
+                            2,
+                        );
+                    }
+                    KeyCode::Char('m') => app.toggle_metadata(),
+                    KeyCode::Char('v') => app.toggle_version(),
+                    KeyCode::Char('s') => {
+                        app.show_source = !app.show_source;
+                        if !app.show_source {
+                            app.set_status("source: OFF", 2);
+                        } else if app.cached_source_map.entry_count() == 0 {
+                            let has_refs = app
+                                .selected_pass()
+                                .is_some_and(|p| ir_has_inline_md_refs(&p.body));
+                            if has_refs {
+                                app.set_status(
+                                    "source: ON — IR has !N refs but no defs; re-run with `--ir all,print-md`",
+                                    8,
+                                );
+                            } else {
+                                app.set_status(
+                                    "source: ON (no metadata — use `--ir all,print-md`)",
+                                    6,
+                                );
+                            }
+                        } else {
+                            app.set_status(
+                                format!(
+                                    "source: ON ({} metadata defs cached)",
+                                    app.cached_source_map.entry_count()
+                                ),
+                                3,
+                            );
+                        }
+                        app.refresh_main();
+                    }
+                    KeyCode::Char('S') => {
+                        app.open_source_root_modal(
+                            "enter the directory that contains your .sw sources",
+                        );
+                    }
+                    KeyCode::Char('l') => {
+                        app.show_line_numbers = !app.show_line_numbers;
+                        app.dirty = true;
+                    }
+                    KeyCode::Char('/') => {
+                        app.input_mode = Some(InputMode::Search);
+                        app.input_buf = app.search.clone();
+                    }
+                    KeyCode::Char('p') => {
+                        app.input_mode = Some(InputMode::PassFilter);
+                        app.input_buf = app.pass_filter.clone();
+                    }
+                    KeyCode::Char('f') => {
+                        app.input_mode = Some(InputMode::FnFilter);
+                        app.input_buf = app.fn_filter.clone();
+                    }
+                    KeyCode::Char('n') if !app.search_matches.is_empty() => {
+                        app.search_idx = (app.search_idx + 1) % app.search_matches.len();
+                        app.scroll = app.search_matches[app.search_idx] as u16;
+                        app.dirty = true;
+                    }
+                    KeyCode::Char('N') if !app.search_matches.is_empty() => {
+                        app.search_idx = if app.search_idx == 0 {
+                            app.search_matches.len() - 1
+                        } else {
+                            app.search_idx - 1
+                        };
+                        app.scroll = app.search_matches[app.search_idx] as u16;
+                        app.dirty = true;
+                    }
+                    KeyCode::Char(']') => app.jump_next_fn(),
+                    KeyCode::Char('[') => app.jump_prev_fn(),
+                    KeyCode::Char('g') => app.scroll = 0,
+                    KeyCode::Char('G') => {
+                        app.scroll = app.main_text.lines().count().saturating_sub(1) as u16;
+                    }
+                    KeyCode::Down | KeyCode::Char('j') => match app.focus {
+                        Focus::Tree => app.select_next(),
+                        Focus::Main => app.scroll_by(1, 1),
+                    },
+                    KeyCode::Up | KeyCode::Char('k') => match app.focus {
+                        Focus::Tree => app.select_prev(),
+                        Focus::Main => app.scroll_by(-1, 1),
+                    },
+                    KeyCode::PageDown => {
+                        let h = terminal.size()?.height.saturating_sub(6);
+                        app.scroll_by(1, h);
+                    }
+                    KeyCode::PageUp => {
+                        let h = terminal.size()?.height.saturating_sub(6);
+                        app.scroll_by(-1, h);
+                    }
+                    KeyCode::Char(' ') | KeyCode::Enter if app.focus == Focus::Tree => {
+                        app.activate_selection();
+                    }
+                    KeyCode::Char(' ') if app.focus == Focus::Main => {
+                        let h = terminal.size()?.height.saturating_sub(6);
+                        app.scroll_by(1, h);
+                    }
+                    KeyCode::Left | KeyCode::Char('h') if app.focus == Focus::Tree => {
+                        match app.selected_tree_row() {
+                            Some(TreeRow::Project(_)) => {
+                                if matches!(
+                                    app.selected_tree_row(),
+                                    Some(TreeRow::Project(pi))
+                                        if app.projects.get(pi).is_some_and(|p| p.expanded)
+                                ) {
+                                    app.toggle_selected_project();
+                                }
+                            }
+                            Some(TreeRow::Pass(pass_idx)) => {
+                                if let Some((row, pi)) =
+                                    app.tree_rows.iter().enumerate().rev().find_map(|(row, r)| {
+                                        match r {
+                                            TreeRow::Project(pi)
+                                                if app.projects[*pi].passes.contains(&pass_idx) =>
+                                            {
+                                                Some((row, *pi))
+                                            }
+                                            _ => None,
+                                        }
+                                    })
+                                {
+                                    app.projects[pi].expanded = false;
+                                    app.recompute_tree();
+                                    if !app.tree_rows.is_empty() {
+                                        app.list_state
+                                            .select(Some(row.min(app.tree_rows.len() - 1)));
+                                    }
+                                }
+                            }
+                            None => {}
+                        }
+                    }
+                    KeyCode::Right if app.focus == Focus::Tree => {
+                        if let Some(TreeRow::Project(pi)) = app.selected_tree_row() {
+                            if app.projects.get(pi).is_some_and(|p| !p.expanded) {
+                                app.toggle_selected_project();
+                            } else if let Some(sel) = app.list_state.selected() {
+                                if sel + 1 < app.tree_rows.len() {
+                                    app.list_state.select(Some(sel + 1));
+                                    app.activate_selection();
+                                }
+                            }
+                        }
+                    }
+                    KeyCode::Left | KeyCode::Char('h') => {
+                        app.h_scroll = app.h_scroll.saturating_sub(4);
+                    }
+                    KeyCode::Right => {
+                        app.h_scroll = app.h_scroll.saturating_add(4);
+                    }
+                    KeyCode::Home => {
+                        if app.focus == Focus::Tree && !app.tree_rows.is_empty() {
+                            app.list_state.select(Some(0));
+                            app.activate_selection();
+                        } else {
+                            app.scroll = 0;
+                        }
+                    }
+                    KeyCode::End => {
+                        if app.focus == Focus::Tree && !app.tree_rows.is_empty() {
+                            app.list_state.select(Some(app.tree_rows.len() - 1));
+                            app.activate_selection();
+                        } else {
+                            app.scroll =
+                                app.main_text.lines().count().saturating_sub(1) as u16;
+                        }
+                    }
+                    _ => {}
+                }
+                app.mark_persist();
+            }
+            Event::Mouse(m) if !app.is_loading() => {
+                app.handle_mouse(m.column, m.row, m.kind);
+                app.mark_persist();
+            }
+            _ => {}
+        }
+    }
+}
+
+fn draw(f: &mut Frame, app: &mut App) {
+    let status_h = status_panel_height(app, f.area());
+    let chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Min(5),
+            Constraint::Length(status_h),
+            Constraint::Length(1),
+        ])
+        .split(f.area());
+
+    let body = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Percentage(28), Constraint::Percentage(72)])
+        .split(chunks[0]);
+
+    app.tree_area = body[0];
+    app.main_area = body[1];
+
+    draw_tree(f, app, body[0]);
+    draw_main(f, app, body[1]);
+    draw_status(f, app, chunks[1]);
+    draw_keys(f, chunks[2]);
+
+    if app.is_loading() {
+        draw_loading(f, app);
+    }
+    if let Some(mode) = app.input_mode {
+        draw_input(f, app, mode);
+    }
+    if app.show_help {
+        draw_help(f);
+    }
+}
+
+/// How many terminal rows a single logical line needs when wrapped to `width`.
+fn wrapped_line_count(text: &str, width: u16) -> u16 {
+    let width = width.max(1) as usize;
+    if text.is_empty() {
+        return 1;
+    }
+    let chars = text.chars().count().max(1);
+    ((chars + width - 1) / width) as u16
+}
+
+
+fn main_view_range(app: &App) -> (usize, usize) {
+    let start = app.scroll as usize;
+    let rows = app.main_view_rows.max(1) as usize;
+    (start, start.saturating_add(rows))
+}
+
+fn ssa_offscreen_plain(app: &App) -> String {
+    if app.ssa_highlights.is_empty() || app.is_loading() {
+        return String::new();
+    }
+    let (start, end) = main_view_range(app);
+    let mut parts = Vec::new();
+    for name in app.ssa_highlights.keys() {
+        let (above, below) = highlight::count_token_offscreen(&app.main_text, name, start, end);
+        parts.push(format!("{name} ↑{above} ↓{below}"));
+    }
+    parts.join("  ")
+}
+
+fn ssa_offscreen_spans(app: &App) -> Line<'static> {
+    if app.ssa_highlights.is_empty() {
+        return Line::from("");
+    }
+    let (start, end) = main_view_range(app);
+    let mut spans = vec![Span::raw(" ")];
+    let mut first = true;
+    for (name, &slot) in &app.ssa_highlights {
+        if !first {
+            spans.push(Span::styled("  ", Style::default().fg(Color::DarkGray)));
+        }
+        first = false;
+        let bg = highlight::SYMBOL_PALETTE[slot % highlight::SYMBOL_PALETTE.len()];
+        let (above, below) = highlight::count_token_offscreen(&app.main_text, name, start, end);
+        spans.push(Span::styled(
+            name.clone(),
+            Style::default().bg(bg).fg(Color::White).add_modifier(Modifier::BOLD),
+        ));
+        spans.push(Span::styled(
+            format!(" ↑{above} ↓{below}"),
+            Style::default().fg(Color::DarkGray),
+        ));
+    }
+    Line::from(spans)
+}
+
+fn status_stats_plain(app: &App) -> String {
+    if app.is_loading() {
+        return String::new();
+    }
+    if let Some(pass) = app.selected_pass() {
+        let idx = app.selected_pass_idx().unwrap();
+        let prev = if idx > 0 && app.passes[idx - 1].project == pass.project {
+            Some(&app.passes[idx - 1].stats)
+        } else {
+            None
+        };
+        format_full_stats(&pass.stats, prev)
+    } else {
+        app.stats_line.clone()
+    }
+}
+
+fn status_header_plain(app: &App) -> String {
+    if app.is_loading() {
+        return String::from(" waiting for cmd output");
+    }
+    let pos = app
+        .list_state
+        .selected()
+        .map(|i| format!("{}/{}", i + 1, app.tree_rows.len()))
+        .unwrap_or_else(|| "-".into());
+    let search = if app.search.is_empty() {
+        String::new()
+    } else if app.search_matches.is_empty() {
+        format!("  search:\"{}\" (0)", app.search)
+    } else {
+        format!(
+            "  search:\"{}\" ({}/{})",
+            app.search,
+            app.search_idx + 1,
+            app.search_matches.len()
+        )
+    };
+    let fn_f = if app.fn_filter.is_empty() {
+        String::new()
+    } else {
+        format!("  fn:{}", app.fn_filter)
+    };
+    let status = if app.status.is_empty() {
+        String::new()
+    } else {
+        format!(" │ {}", app.status)
+    };
+    let pass = app
+        .selected_pass()
+        .map(|p| format!("  {}", pass_short_label(&p.name)))
+        .unwrap_or_default();
+    format!(" {pos}{pass}{fn_f}{search}{status}")
+}
+
+/// Borders + header (+ wrapped stats). Grows with content; leaves room for body + keys.
+fn status_panel_height(app: &App, frame: Rect) -> u16 {
+    const KEYS: u16 = 1;
+    const MIN_BODY: u16 = 5;
+    const BORDERS: u16 = 2;
+
+    let inner_w = frame.width.saturating_sub(2);
+    let header_lines = wrapped_line_count(&status_header_plain(app), inner_w);
+    let content = if app.is_loading() {
+        header_lines
+    } else {
+        let stats = status_stats_plain(app);
+        // Leading space matches what we render in the panel.
+        let stats_lines = if stats.is_empty() {
+            1
+        } else {
+            wrapped_line_count(&format!(" {stats}"), inner_w)
+        };
+        let ssa = ssa_offscreen_plain(app);
+        let ssa_lines = if ssa.is_empty() {
+            0
+        } else {
+            wrapped_line_count(&format!(" {ssa}"), inner_w)
+        };
+        header_lines + stats_lines + ssa_lines
+    };
+
+    let needed = content.saturating_add(BORDERS);
+    let max = frame.height.saturating_sub(MIN_BODY.saturating_add(KEYS)).max(3);
+    needed.min(max).max(3)
+}
+
+fn draw_tree(f: &mut Frame, app: &mut App, area: Rect) {
+    let pass_rows = app
+        .tree_rows
+        .iter()
+        .filter(|r| matches!(r, TreeRow::Pass(_)))
+        .count();
+    let title = if app.pass_filter.is_empty() {
+        format!(" Tree ({pass_rows}/{}) ", app.passes.len())
+    } else {
+        format!(
+            " Tree ({pass_rows}/{}) [{}] ",
+            app.passes.len(),
+            app.pass_filter
+        )
+    };
+    let border = if app.focus == Focus::Tree {
+        Style::default().fg(Color::Cyan)
+    } else {
+        Style::default().fg(Color::DarkGray)
+    };
+
+    let items: Vec<ListItem> = app
+        .tree_rows
+        .iter()
+        .map(|row| match row {
+            TreeRow::Project(pi) => {
+                let p = &app.projects[*pi];
+                let glyph = if p.expanded { "▼" } else { "▶" };
+                let n = p.passes.len();
+                ListItem::new(Line::from(vec![
+                    Span::styled(
+                        format!("{glyph} "),
+                        Style::default()
+                            .fg(Color::Cyan)
+                            .add_modifier(Modifier::BOLD),
+                    ),
+                    Span::styled(
+                        p.name.clone(),
+                        Style::default()
+                            .fg(Color::Cyan)
+                            .add_modifier(Modifier::BOLD),
+                    ),
+                    Span::styled(format!(" ({n})"), Style::default().fg(Color::DarkGray)),
+                ]))
+            }
+            TreeRow::Pass(i) => {
+                let p = &app.passes[*i];
+                let marker = if p.changed { "●" } else { "○" };
+                let style = if p.changed {
+                    Style::default().fg(Color::White)
+                } else {
+                    Style::default().fg(Color::DarkGray)
+                };
+                let prev_stats = if *i > 0 && app.passes[*i - 1].project == p.project {
+                    Some(&app.passes[*i - 1].stats)
+                } else {
+                    None
+                };
+                let label = pass_short_label(&p.name);
+                let stats = format_tree_stats(&p.stats, prev_stats);
+                let mut spans = vec![
+                    Span::raw("  "),
+                    Span::styled(format!("{marker} "), style),
+                    Span::styled(
+                        label.to_string(),
+                        style.add_modifier(Modifier::BOLD),
+                    ),
+                ];
+                if !stats.is_empty() {
+                    spans.push(Span::styled(
+                        format!("  {stats}"),
+                        Style::default().fg(Color::DarkGray),
+                    ));
+                }
+                ListItem::new(Line::from(spans))
+            }
+        })
+        .collect();
+
+    let list = List::new(items)
+        .block(
+            Block::default()
+                .borders(Borders::ALL)
+                .title(title)
+                .border_style(border),
+        )
+        .highlight_style(
+            Style::default()
+                .bg(Color::Rgb(40, 60, 90))
+                .add_modifier(Modifier::BOLD),
+        )
+        .highlight_symbol("▸ ");
+
+    f.render_stateful_widget(list, area, &mut app.list_state);
+}
+
+fn draw_main(f: &mut Frame, app: &mut App, area: Rect) {
+    app.ensure_cache();
+    let pass_name = app
+        .selected_pass()
+        .map(|p| pass_short_label(&p.name))
+        .unwrap_or("-");
+    let mode = if app.main_is_diff { "DIFF" } else { "IR" };
+    let src = if app.show_source { " +src" } else { "" };
+    let title = format!(" {mode}{src}: {pass_name} ");
+    let border = if app.focus == Focus::Main {
+        Style::default().fg(Color::Cyan)
+    } else {
+        Style::default().fg(Color::DarkGray)
+    };
+
+    let inner_h = area.height.saturating_sub(2) as usize;
+    app.main_view_rows = inner_h.max(1) as u16;
+    let len = app.cached_lines.len();
+    let start = if len == 0 {
+        0
+    } else {
+        (app.scroll as usize).min(len - 1)
+    };
+    let end = (start + inner_h).min(len);
+
+    let mut lines = Vec::with_capacity(end.saturating_sub(start));
+    for (i, line) in app.cached_lines[start..end].iter().enumerate() {
+        let abs = start + i;
+        let content = highlight::skip_line_chars(line, app.h_scroll as usize);
+        if app.show_line_numbers {
+            let mut spans = vec![Span::styled(
+                format!("{:>4} │ ", abs + 1),
+                Style::default().fg(Color::DarkGray),
+            )];
+            spans.extend(content.spans.iter().cloned());
+            lines.push(Line::from(spans));
+        } else {
+            lines.push(content);
+        }
+    }
+
+    let para = Paragraph::new(lines).block(
+        Block::default()
+            .borders(Borders::ALL)
+            .title(title)
+            .border_style(border),
+    );
+    f.render_widget(para, area);
+}
+
+fn draw_status(f: &mut Frame, app: &App, area: Rect) {
+    let pos = app
+        .list_state
+        .selected()
+        .map(|i| format!("{}/{}", i + 1, app.tree_rows.len()))
+        .unwrap_or_else(|| "-".into());
+    let search = if app.search.is_empty() {
+        String::new()
+    } else if app.search_matches.is_empty() {
+        format!("  search:\"{}\" (0)", app.search)
+    } else {
+        format!(
+            "  search:\"{}\" ({}/{})",
+            app.search,
+            app.search_idx + 1,
+            app.search_matches.len()
+        )
+    };
+    let fn_f = if app.fn_filter.is_empty() {
+        String::new()
+    } else {
+        format!("  fn:{}", app.fn_filter)
+    };
+
+    let (line1, style1) = if app.is_loading() {
+        (
+            String::from(" waiting for cmd output"),
+            Style::default()
+                .fg(Color::Yellow)
+                .add_modifier(Modifier::BOLD),
+        )
+    } else {
+        let status = if app.status.is_empty() {
+            String::new()
+        } else {
+            format!(" │ {}", app.status)
+        };
+        let pass = app
+            .selected_pass()
+            .map(|p| format!("  {}", pass_short_label(&p.name)))
+            .unwrap_or_default();
+        (
+            format!(" {pos}{pass}{fn_f}{search}{status}"),
+            Style::default().fg(Color::White),
+        )
+    };
+
+    // Prefer live stats from the selected pass (with deltas vs previous).
+    // Fall back to `stats_line` only when no pass is selected.
+    let line2 = if app.is_loading() {
+        Line::from("")
+    } else if let Some(pass) = app.selected_pass() {
+        let idx = app.selected_pass_idx().unwrap();
+        let prev = if idx > 0 && app.passes[idx - 1].project == pass.project {
+            Some(&app.passes[idx - 1].stats)
+        } else {
+            None
+        };
+        let mut spans = vec![Span::styled(" ", Style::default().fg(Color::DarkGray))];
+        spans.extend(format_full_stats_spans(&pass.stats, prev));
+        Line::from(spans)
+    } else {
+        Line::from(Span::styled(
+            format!(" {}", app.stats_line),
+            Style::default().fg(Color::DarkGray),
+        ))
+    };
+
+    let mut status_lines = vec![
+        Line::from(Span::styled(line1, style1)),
+        line2,
+    ];
+    if !app.ssa_highlights.is_empty() && !app.is_loading() {
+        status_lines.push(ssa_offscreen_spans(app));
+    }
+    let para = Paragraph::new(status_lines)
+    .wrap(Wrap { trim: false })
+    .block(
+        Block::default()
+            .borders(Borders::ALL)
+            .title(if app.is_loading() {
+                " Loading "
+            } else if app.selected_pass().is_some() {
+                " Stats "
+            } else {
+                " Status "
+            })
+            .border_style(if app.is_loading() {
+                Style::default().fg(Color::Yellow)
+            } else {
+                Style::default().fg(Color::DarkGray)
+            }),
+    );
+    f.render_widget(para, area);
+}
+
+fn draw_loading(f: &mut Frame, app: &App) {
+    let label = app
+        .loading
+        .as_ref()
+        .map(|j| j.label.as_str())
+        .unwrap_or("loading");
+    let secs = app
+        .loading
+        .as_ref()
+        .map(|j| j.started.elapsed().as_secs_f32())
+        .unwrap_or(0.0);
+    let bytes = app
+        .loading
+        .as_ref()
+        .map(|j| j.bytes_received.load(Ordering::Relaxed))
+        .unwrap_or(0);
+    let bytes_label = format_byte_count(bytes);
+
+    // Size the modal to fit the full command (wrapped), not a truncated label.
+    let width = f.area().width.saturating_sub(4).clamp(40, 100);
+    let inner_w = width.saturating_sub(4).max(20) as usize;
+    let label_lines = wrapped_line_count(label, inner_w as u16).max(1);
+    // borders(2) + blank + spinner/label lines + stats line
+    let height = (4u16).saturating_add(label_lines).min(f.area().height.saturating_sub(2));
+    let area = centered(
+        ((width as u32 * 100) / f.area().width.max(1) as u32) as u16,
+        height,
+        f.area(),
+    );
+
+    let spin = app.spinner();
+    let mut text = vec![Line::from("")];
+    // First line of the command with spinner; remaining wrapped lines indented.
+    let mut remaining = label;
+    let mut first = true;
+    while !remaining.is_empty() {
+        let take = remaining
+            .chars()
+            .take(if first {
+                inner_w.saturating_sub(4)
+            } else {
+                inner_w.saturating_sub(6)
+            })
+            .count();
+        // Find a byte index at a char boundary.
+        let mut end = 0;
+        for (i, _) in remaining.char_indices().take(take) {
+            end = i;
+        }
+        if end == 0 {
+            // Single very wide char or empty take — consume one char.
+            end = remaining
+                .char_indices()
+                .nth(1)
+                .map(|(i, _)| i)
+                .unwrap_or(remaining.len());
+            if end == 0 {
+                end = remaining.len();
+            }
+        } else {
+            // Advance past the last included char.
+            let last = remaining[end..].chars().next().map(|c| c.len_utf8()).unwrap_or(0);
+            end += last;
+        }
+        let chunk = &remaining[..end.min(remaining.len())];
+        remaining = &remaining[end.min(remaining.len())..];
+        if first {
+            text.push(Line::from(vec![
+                Span::styled(
+                    format!("  {spin}  "),
+                    Style::default()
+                        .fg(Color::Yellow)
+                        .add_modifier(Modifier::BOLD),
+                ),
+                Span::styled(chunk.to_string(), Style::default().fg(Color::White)),
+            ]));
+            first = false;
+        } else {
+            text.push(Line::from(Span::styled(
+                format!("      {chunk}"),
+                Style::default().fg(Color::White),
+            )));
+        }
+    }
+    text.push(Line::from(Span::styled(
+        format!("      {secs:.1}s  ·  {bytes_label} received  ·  Ctrl-C cancels  ·  q quits"),
+        Style::default().fg(Color::DarkGray),
+    )));
+
+    let para = Paragraph::new(text)
+        .wrap(Wrap { trim: false })
+        .block(
+            Block::default()
+                .borders(Borders::ALL)
+                .title(" Working ")
+                .border_style(
+                    Style::default()
+                        .fg(Color::Yellow)
+                        .add_modifier(Modifier::BOLD),
+                ),
+        );
+    f.render_widget(Clear, area);
+    f.render_widget(para, area);
+}
+
+fn ir_has_inline_md_refs(text: &str) -> bool {
+    text.lines().any(|line| !find_md_refs(line).is_empty())
+}
+
+fn format_byte_count(n: usize) -> String {
+    const KB: f64 = 1024.0;
+    const MB: f64 = KB * 1024.0;
+    const GB: f64 = MB * 1024.0;
+    let n = n as f64;
+    if n >= GB {
+        format!("{:.2} GiB", n / GB)
+    } else if n >= MB {
+        format!("{:.2} MiB", n / MB)
+    } else if n >= KB {
+        format!("{:.1} KiB", n / KB)
+    } else {
+        format!("{n:.0} B")
+    }
+}
+
+fn draw_keys(f: &mut Frame, area: Rect) {
+    let keys = " Tab:focus  j/k:nav  Enter/←/→:tree  /:search  p/f:filter  d:diff  m:metadata  v:version  s:source  S:src-root  y:copy  F1:syntax  F2:symbol  F5:reload  ?:help  q:quit ";
+    f.render_widget(
+        Paragraph::new(Line::from(Span::styled(
+            keys,
+            Style::default().fg(Color::Rgb(140, 140, 160)),
+        ))),
+        area,
+    );
+}
+
+fn draw_input(f: &mut Frame, app: &App, mode: InputMode) {
+    let (area, title, body) = match mode {
+        InputMode::PassFilter => (
+            centered(60, 3, f.area()),
+            " Filter passes (substring) ",
+            format!("> {}", app.input_buf),
+        ),
+        InputMode::FnFilter => (
+            centered(60, 3, f.area()),
+            " Filter functions (comma-separated) ",
+            format!("> {}", app.input_buf),
+        ),
+        InputMode::Search => (
+            centered(60, 3, f.area()),
+            " Search IR ",
+            format!("> {}", app.input_buf),
+        ),
+        InputMode::SourceRoot => {
+            let current = app
+                .source_root
+                .as_ref()
+                .map(|p| format!("current: {}
+", p.display()))
+                .unwrap_or_else(|| String::from("current: (none)
+"));
+            (
+                centered(72, 7, f.area()),
+                " Source root directory ",
+                format!(
+                    "{current}IR metadata paths were not found on disk.
+\
+                     Enter the project/workspace root that contains the .sw files:
+\
+                     > {}",
+                    app.input_buf
+                ),
+            )
+        }
+    };
+    let para = Paragraph::new(body)
+        .block(
+            Block::default()
+                .borders(Borders::ALL)
+                .title(title)
+                .border_style(Style::default().fg(Color::Yellow)),
+        )
+        .wrap(Wrap { trim: false });
+    f.render_widget(Clear, area);
+    f.render_widget(para, area);
+}
+
+fn draw_help(f: &mut Frame) {
+    let area = centered(86, 42, f.area());
+    if area.width < 10 || area.height < 5 {
+        return;
+    }
+    let text = vec![
+        Line::from("Sway IR Inspect — keybindings & features"),
+        Line::from(""),
+        Line::from("Navigation"),
+        Line::from("  Tab             Focus tree ↔ IR panel"),
+        Line::from("  j/k ↑/↓         Navigate tree / scroll IR"),
+        Line::from("  Enter / Space     Expand project or select pass"),
+        Line::from("  ← / →           Collapse / expand project"),
+        Line::from("  PgUp/PgDn       Page scroll IR"),
+        Line::from("  g / G           Top / bottom of IR"),
+        Line::from("  Click / Wheel   Select tree rows / scroll IR"),
+        Line::from(""),
+        Line::from("Search & filters"),
+        Line::from("  p / f / /       Filter passes / functions / search text"),
+        Line::from("  n / N           Next / previous search match"),
+        Line::from(""),
+        Line::from("View toggles"),
+        Line::from("  F1              Toggle syntax highlighting (SSA/local/method colors still apply)"),
+        Line::from("  d               Toggle diff vs previous pass"),
+        Line::from("  m               Toggle metadata on/off"),
+        Line::from("  v               Toggle version suffixes on/off"),
+        Line::from("  s               Toggle source overlay (needs `--ir …,print-md`)"),
+        Line::from("  S               Set/change source root directory (persisted)"),
+        Line::from("  l               Toggle line numbers"),
+        Line::from(""),
+        Line::from("Symbol focus (F2) — IR panel focused"),
+        Line::from("  Click/move on an SSA (`v0`), local (`x` in `local u64 x` / `get_local …, x`),"),
+        Line::from("  or method/function name (`fn foo` / `call foo`), then press F2 to toggle."),
+        Line::from("  Multiple symbols can be focused at once; each gets a distinct palette color."),
+        Line::from("  Focus colors always override syntax highlighting (F1 on or off)."),
+        Line::from("  Status bar shows each focused symbol with ↑N ↓M = occurrences above/below"),
+        Line::from("  the visible IR window (defs + uses combined)."),
+        Line::from(""),
+        Line::from("Session / IO"),
+        Line::from("  F5 / Ctrl-R     Reload dump / re-run `--cmd`"),
+        Line::from("  y               Copy main panel to clipboard"),
+        Line::from("  Ctrl-C          Cancel load/diff, or quit if idle"),
+        Line::from("  q / Esc         Quit"),
+        Line::from("  (auto-save)     Filters, view, selection, source root → `~/.config/forc-ir-inspect/`"),
+        Line::from(""),
+        Line::from("Tree markers"),
+        Line::from("  ● white         Pass changed the IR vs the previous pass"),
+        Line::from("  ○ gray          Pass left the IR unchanged"),
+        Line::from(""),
+        Line::from("Stats (status bar & tree)"),
+        Line::from("  args/locals/blocks/instr   Function shape counts (+/− vs previous pass)"),
+        Line::from("  <opcode>=N                 Opcode frequency (tree shows deltas only)"),
+        Line::from(""),
+        Line::from("  Press any key to close"),
+    ];
+    let para = Paragraph::new(text)
+        .style(Style::default().fg(Color::White))
+        .block(
+            Block::default()
+                .borders(Borders::ALL)
+                .title(" Help ")
+                .border_style(
+                    Style::default()
+                        .fg(Color::Yellow)
+                        .add_modifier(Modifier::BOLD),
+                )
+                .style(Style::default().bg(Color::Black)),
+        );
+    f.render_widget(Clear, area);
+    f.render_widget(para, area);
+}
+
+fn centered(percent_x: u16, height: u16, r: Rect) -> Rect {
+    // Clamp so a short terminal still gets a visible popup.
+    let height = height.min(r.height.saturating_sub(2)).max(3);
+    let percent_x = percent_x.min(100);
+    let vert = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([
+            Constraint::Length(r.height.saturating_sub(height) / 2),
+            Constraint::Length(height),
+            Constraint::Min(0),
+        ])
+        .split(r);
+    Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([
+            Constraint::Percentage((100 - percent_x) / 2),
+            Constraint::Percentage(percent_x),
+            Constraint::Percentage((100 - percent_x) / 2),
+        ])
+        .split(vert[1])[1]
+}
+
diff --git a/sway-ir/Cargo.toml b/sway-ir/Cargo.toml
index 8e03f7ec03d..7f2982d262f 100644
--- a/sway-ir/Cargo.toml
+++ b/sway-ir/Cargo.toml
@@ -10,7 +10,6 @@ repository.workspace = true
 
 [dependencies]
 anyhow.workspace = true
-clap = { workspace = true, features = ["derive"] }
 downcast-rs.workspace = true
 filecheck.workspace = true
 indexmap = { workspace = true, features = ["rayon"] }