init

.gitignore

···
+.direnv
+.devenv
+.vscode
+target
+result

crates/Cargo.lock

···
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "addr2line"
+version = "0.24.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbe277e56a376000877090da837660b4427aad530e3028d44e0bffe4f89a1c1"
+dependencies = [
+ "gimli",
+]
+
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e60d3430d3a69478ad0993f19238d2df97c507009a52b3c10addcd7f6bcb916"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "anyhow"
+version = "1.0.99"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b0674a1ddeecb70197781e945de4b3b8ffb61fa939a5597bcf48503737663100"
+
+[[package]]
+name = "approx"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cab112f0a86d568ea0e627cc1d6be74a1e9cd55214684db5561995f6dad897c6"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "async-trait"
+version = "0.1.89"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9035ad2d096bed7955a320ee7e2230574d28fd3c3a0f186cbea1ff3c7eed5dbb"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "autocfg"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
+
+[[package]]
+name = "backtrace"
+version = "0.3.75"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6806a6321ec58106fea15becdad98371e28d92ccbc7c8f1b3b6dd724fe8f1002"
+dependencies = [
+ "addr2line",
+ "cfg-if",
+ "libc",
+ "miniz_oxide",
+ "object",
+ "rustc-demangle",
+ "windows-targets 0.52.6",
+]
+
+[[package]]
+name = "bitflags"
+version = "2.9.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34efbcccd345379ca2868b2b2c9d3782e9cc58ba87bc7d79d5b53d9c9ae6f25d"
+
+[[package]]
+name = "bubbletea-rs"
+version = "0.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f3794d723bd09a5e1a18a3879a7b8590e5d74040862d9151f12224ee92d0de50"
+dependencies = [
+ "anyhow",
+ "async-trait",
+ "crossterm",
+ "futures",
+ "log",
+ "parking_lot",
+ "pin-project",
+ "thiserror",
+ "tokio",
+ "tokio-util",
+]
+
+[[package]]
+name = "bubbletea-widgets"
+version = "0.1.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4f13678648f54f24614d60af1e7356fd8b39b1b9e2f3096db94d1b4626137408"
+dependencies = [
+ "bubbletea-rs",
+ "crossterm",
+ "fuzzy-matcher",
+ "libc",
+ "lipgloss-extras",
+ "once_cell",
+ "strip-ansi-escapes",
+ "unicode-segmentation",
+ "unicode-width",
+]
+
+[[package]]
+name = "by_address"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "64fa3c856b712db6612c019f14756e64e4bcea13337a6b33b696333a9eaa2d06"
+
+[[package]]
+name = "bytes"
+version = "1.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d71b6127be86fdcfddb610f7182ac57211d4b18a3e9c82eb2d17662f2227ad6a"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2fd1289c04a9ea8cb22300a459a72a385d7c73d3259e2ed7dcb2af674838cfa9"
+
+[[package]]
+name = "convert_case"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb402b8d4c85569410425650ce3eddc7d698ed96d39a73f941b08fb63082f1e7"
+dependencies = [
+ "unicode-segmentation",
+]
+
+[[package]]
+name = "crossterm"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8b9f2e4c67f833b660cdb0a3523065869fb35570177239812ed4c905aeff87b"
+dependencies = [
+ "bitflags",
+ "crossterm_winapi",
+ "derive_more",
+ "document-features",
+ "futures-core",
+ "mio",
+ "parking_lot",
+ "rustix 1.0.8",
+ "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 = "derive_more"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "093242cf7570c207c83073cf82f79706fe7b8317e98620a47d5be7c3d8497678"
+dependencies = [
+ "derive_more-impl",
+]
+
+[[package]]
+name = "derive_more-impl"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bda628edc44c4bb645fbe0f758797143e4e07926f7ebf4e9bdfbd3d2ce621df3"
+dependencies = [
+ "convert_case",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "document-features"
+version = "0.2.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95249b50c6c185bee49034bcb378a49dc2b5dff0be90ff6616d31d64febab05d"
+dependencies = [
+ "litrs",
+]
+
+[[package]]
+name = "either"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
+
+[[package]]
+name = "errno"
+version = "0.3.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "778e2ac28f6c47af28e4907f13ffd1e1ddbd400980a9abd7c8df189bf578a5ad"
+dependencies = [
+ "libc",
+ "windows-sys 0.60.2",
+]
+
+[[package]]
+name = "fast-srgb8"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dd2e7510819d6fbf51a5545c8f922716ecfb14df168a3242f7d33e0239efe6a1"
+
+[[package]]
+name = "futures"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65bc07b1a8bc7c85c5f2e110c476c7389b4554ba72af57d8445ea63a576b0876"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-executor",
+ "futures-io",
+ "futures-sink",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-channel"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2dff15bf788c671c1934e366d07e30c1814a8ef514e1af724a602e8a2fbe1b10"
+dependencies = [
+ "futures-core",
+ "futures-sink",
+]
+
+[[package]]
+name = "futures-core"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05f29059c0c2090612e8d742178b0580d2dc940c837851ad723096f87af6663e"
+
+[[package]]
+name = "futures-executor"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e28d1d997f585e54aebc3f97d39e72338912123a67330d723fdbb564d646c9f"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-io"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e5c1b78ca4aae1ac06c48a526a655760685149f0d465d21f37abfe57ce075c6"
+
+[[package]]
+name = "futures-macro"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "162ee34ebcb7c64a8abebc059ce0fee27c2262618d7b60ed8faf72fef13c3650"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "futures-sink"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e575fab7d1e0dcb8d0c7bcf9a63ee213816ab51902e6d244a95819acacf1d4f7"
+
+[[package]]
+name = "futures-task"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f90f7dce0722e95104fcb095585910c0977252f286e354b5e3bd38902cd99988"
+
+[[package]]
+name = "futures-util"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9fa08315bb612088cc391249efdc3bc77536f16c91f6cf495e6fbe85b20a4a81"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-io",
+ "futures-macro",
+ "futures-sink",
+ "futures-task",
+ "memchr",
+ "pin-project-lite",
+ "pin-utils",
+ "slab",
+]
+
+[[package]]
+name = "fuzzy-matcher"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "54614a3312934d066701a80f20f15fa3b56d67ac7722b39eea5b4c9dd1d66c94"
+dependencies = [
+ "thread_local",
+]
+
+[[package]]
+name = "gimli"
+version = "0.31.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "07e28edb80900c19c28f1072f2e8aeca7fa06b23cd4169cefe1af5aa3260783f"
+
+[[package]]
+name = "home"
+version = "0.5.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "589533453244b0995c858700322199b2becb13b627df2851f64a2775d024abcf"
+dependencies = [
+ "windows-sys 0.59.0",
+]
+
+[[package]]
+name = "io-uring"
+version = "0.7.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "046fa2d4d00aea763528b4950358d0ead425372445dc8ff86312b3c69ff7727b"
+dependencies = [
+ "bitflags",
+ "cfg-if",
+ "libc",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4a5f13b858c8d314ee3e8f639011f7ccefe71f97f96e50151fb991f267928e2c"
+
+[[package]]
+name = "libc"
+version = "0.2.175"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a82ae493e598baaea5209805c49bbf2ea7de956d50d7da0da1164f9c6d28543"
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.4.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d26c52dbd32dccf2d10cac7725f8eae5296885fb5703b261f7d0a0739ec807ab"
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.9.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd945864f07fe9f5371a27ad7b52a172b4b499999f1d97574c9fa68373937e12"
+
+[[package]]
+name = "lipgloss"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a9b86565b27d147fee6923d6cfa7265fc3d7f7e2d00d51d0582f91e3b74848fd"
+dependencies = [
+ "crossterm",
+ "palette",
+ "strip-ansi-escapes",
+ "unicode-width",
+]
+
+[[package]]
+name = "lipgloss-extras"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23c1c1cd78f4ef70cc3fc1d714ed1a526aef6a8c7ae782af068fa667abbe27e9"
+dependencies = [
+ "lipgloss",
+ "lipgloss-list",
+ "lipgloss-table",
+ "lipgloss-tree",
+]
+
+[[package]]
+name = "lipgloss-list"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc596c2e4d35d1b0cf6b628cf6cd2619a86c00a0fb7758aee6d34245cf17c673"
+dependencies = [
+ "lipgloss",
+ "lipgloss-tree",
+ "unicode-width",
+]
+
+[[package]]
+name = "lipgloss-table"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c935bbed67e62d6c49b95a6318ecb42f80c2981e3d77e932e0761b5b69ed32e4"
+dependencies = [
+ "lipgloss",
+ "unicode-width",
+]
+
+[[package]]
+name = "lipgloss-tree"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f91c9b17a7860a0bd4cc6dd760fcc309118de9d00e1d8f50ca2ebafd480faa45"
+dependencies = [
+ "lipgloss",
+ "unicode-width",
+]
+
+[[package]]
+name = "litrs"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f5e54036fe321fd421e10d732f155734c4e4afd610dd556d9a82833ab3ee0bed"
+
+[[package]]
+name = "lock_api"
+version = "0.4.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "96936507f153605bddfcda068dd804796c84324ed2510809e5b2a624c81da765"
+dependencies = [
+ "autocfg",
+ "scopeguard",
+]
+
+[[package]]
+name = "log"
+version = "0.4.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13dc2df351e3202783a1fe0d44375f7295ffb4049267b0f3018346dc122a1d94"
+
+[[package]]
+name = "memchr"
+version = "2.7.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a282da65faaf38286cf3be983213fcf1d2e2a58700e808f83f4ea9a4804bc0"
+
+[[package]]
+name = "miniz_oxide"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
+dependencies = [
+ "adler2",
+]
+
+[[package]]
+name = "mio"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78bed444cc8a2160f01cbcf811ef18cac863ad68ae8ca62092e8db51d51c761c"
+dependencies = [
+ "libc",
+ "log",
+ "wasi",
+ "windows-sys 0.59.0",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "object"
+version = "0.36.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "62948e14d923ea95ea2c7c86c71013138b66525b86bdc08d2dcc262bdb497b87"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42f5e15c9953c5e4ccceeb2e7382a716482c34515315f7b03532b8b4e8393d2d"
+
+[[package]]
+name = "palette"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4cbf71184cc5ecc2e4e1baccdb21026c20e5fc3dcf63028a086131b3ab00b6e6"
+dependencies = [
+ "approx",
+ "fast-srgb8",
+ "palette_derive",
+ "phf",
+]
+
+[[package]]
+name = "palette_derive"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f5030daf005bface118c096f510ffb781fc28f9ab6a32ab224d8631be6851d30"
+dependencies = [
+ "by_address",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "parking_lot"
+version = "0.12.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "70d58bf43669b5795d1576d0641cfb6fbb2057bf629506267a92807158584a13"
+dependencies = [
+ "lock_api",
+ "parking_lot_core",
+]
+
+[[package]]
+name = "parking_lot_core"
+version = "0.9.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc838d2a56b5b1a6c25f55575dfc605fabb63bb2365f6c2353ef9159aa69e4a5"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "redox_syscall",
+ "smallvec",
+ "windows-targets 0.52.6",
+]
+
+[[package]]
+name = "phf"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fd6780a80ae0c52cc120a26a1a42c1ae51b247a253e4e06113d23d2c2edd078"
+dependencies = [
+ "phf_macros",
+ "phf_shared",
+]
+
+[[package]]
+name = "phf_generator"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3c80231409c20246a13fddb31776fb942c38553c51e871f8cbd687a4cfb5843d"
+dependencies = [
+ "phf_shared",
+ "rand",
+]
+
+[[package]]
+name = "phf_macros"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f84ac04429c13a7ff43785d75ad27569f2951ce0ffd30a3321230db2fc727216"
+dependencies = [
+ "phf_generator",
+ "phf_shared",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "phf_shared"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67eabc2ef2a60eb7faa00097bd1ffdb5bd28e62bf39990626a582201b7a754e5"
+dependencies = [
+ "siphasher",
+]
+
+[[package]]
+name = "pin-project"
+version = "1.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "677f1add503faace112b9f1373e43e9e054bfdd22ff1a63c1bc485eaec6a6a8a"
+dependencies = [
+ "pin-project-internal",
+]
+
+[[package]]
+name = "pin-project-internal"
+version = "1.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e918e4ff8c4549eb882f14b3a4bc8c8bc93de829416eacf579f1207a8fbf861"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b3cff922bd51709b605d9ead9aa71031d81447142d828eb4a6eba76fe619f9b"
+
+[[package]]
+name = "pin-utils"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b870d8c151b6f2fb93e84a13146138f05d02ed11c7e7c54f8826aaaf7c9f184"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.101"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "89ae43fd86e4158d6db51ad8e2b80f313af9cc74f5c0e03ccb87de09998732de"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.40"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1885c039570dc00dcb4ff087a89e185fd56bae234ddc7f056a945bf36467248d"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rand"
+version = "0.8.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404"
+dependencies = [
+ "rand_core",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
+
+[[package]]
+name = "redox_syscall"
+version = "0.5.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5407465600fb0548f1442edf71dd20683c6ed326200ace4b1ef0763521bb3b77"
+dependencies = [
+ "bitflags",
+]
+
+[[package]]
+name = "regex"
+version = "1.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b544ef1b4eac5dc2db33ea63606ae9ffcfac26c1416a2806ae0bf5f56b201191"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "809e8dc61f6de73b46c85f4c96486310fe304c434cfa43669d7b40f711150908"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b15c43186be67a4fd63bee50d0303afffcef381492ebe2c5d87f324e1b8815c"
+
+[[package]]
+name = "rustc-demangle"
+version = "0.1.26"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "56f7d92ca342cea22a06f2121d944b4fd82af56988c270852495420f961d4ace"
+
+[[package]]
+name = "rustix"
+version = "0.38.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys 0.4.15",
+ "windows-sys 0.59.0",
+]
+
+[[package]]
+name = "rustix"
+version = "1.0.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11181fbabf243db407ef8df94a6ce0b2f9a733bd8be4ad02b4eda9602296cac8"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys 0.9.4",
+ "windows-sys 0.60.2",
+]
+
+[[package]]
+name = "ryu"
+version = "1.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "28d3b2b1366ec20994f1fd18c3c594f05c5dd4bc44d8bb0c1c632c8d6829481f"
+
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+
+[[package]]
+name = "serde"
+version = "1.0.219"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5f0e2c6ed6606019b4e29e69dbaba95b11854410e5347d525002456dbbb786b6"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.219"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5b0276cf7f2c73365f7157c8123c21cd9a50fbbd844757af28ca1f5925fc2a00"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.143"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d401abef1d108fbd9cbaebc3e46611f4b1021f714a0597a71f41ee463f5f4a5a"
+dependencies = [
+ "itoa",
+ "memchr",
+ "ryu",
+ "serde",
+]
+
+[[package]]
+name = "signal-hook"
+version = "0.3.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d881a16cf4426aa584979d30bd82cb33429027e42122b169753d6ef1085ed6e2"
+dependencies = [
+ "libc",
+ "signal-hook-registry",
+]
+
+[[package]]
+name = "signal-hook-mio"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34db1a06d485c9142248b7a054f034b349b212551f3dfd19c94d45a754a217cd"
+dependencies = [
+ "libc",
+ "mio",
+ "signal-hook",
+]
+
+[[package]]
+name = "signal-hook-registry"
+version = "1.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2a4719bff48cee6b39d12c020eeb490953ad2443b7055bd0b21fca26bd8c28b"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "siphasher"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "56199f7ddabf13fe5074ce809e7d3f42b42ae711800501b5b16ea82ad029c39d"
+
+[[package]]
+name = "slab"
+version = "0.4.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7a2ae44ef20feb57a68b23d846850f861394c2e02dc425a50098ae8c90267589"
+
+[[package]]
+name = "smallvec"
+version = "1.15.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03"
+
+[[package]]
+name = "socket2"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "233504af464074f9d066d7b5416c5f9b894a5862a6506e306f7b816cdd6f1807"
+dependencies = [
+ "libc",
+ "windows-sys 0.59.0",
+]
+
+[[package]]
+name = "strip-ansi-escapes"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a8f8038e7e7969abb3f1b7c2a811225e9296da208539e0f79c5251d6cac0025"
+dependencies = [
+ "vte",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ede7c438028d4436d71104916910f5bb611972c5cfd7f89b8300a8186e6fada6"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "thiserror"
+version = "2.0.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3467d614147380f2e4e374161426ff399c91084acd2363eaf549172b3d5e60c0"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6c5e1be1c48b9172ee610da68fd9cd2770e7a4056cb3fc98710ee6906f0c7960"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "thread_local"
+version = "1.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f60246a4944f24f6e018aa17cdeffb7818b76356965d03b07d6a9886e8962185"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "tokio"
+version = "1.47.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "89e49afdadebb872d3145a5638b59eb0691ea23e46ca484037cfab3b76b95038"
+dependencies = [
+ "backtrace",
+ "bytes",
+ "io-uring",
+ "libc",
+ "mio",
+ "parking_lot",
+ "pin-project-lite",
+ "signal-hook-registry",
+ "slab",
+ "socket2",
+ "tokio-macros",
+ "windows-sys 0.59.0",
+]
+
+[[package]]
+name = "tokio-macros"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e06d43f1345a3bcd39f6a56dbb7dcab2ba47e68e8ac134855e7e2bdbaf8cab8"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "tokio-util"
+version = "0.7.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "14307c986784f72ef81c89db7d9e28d6ac26d16213b109ea501696195e6e3ce5"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "futures-sink",
+ "pin-project-lite",
+ "tokio",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a5f39404a5da50712a4c1eecf25e90dd62b613502b7e925fd4e4d19b5c96512"
+
+[[package]]
+name = "unicode-segmentation"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f6ccf251212114b54433ec949fd6a7841275f9ada20dddd2f29e9ceea4501493"
+
+[[package]]
+name = "unicode-width"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4a1a07cc7db3810833284e8d372ccdc6da29741639ecc70c9ec107df0fa6154c"
+
+[[package]]
+name = "van"
+version = "0.1.0"
+dependencies = [
+ "bubbletea-rs",
+ "bubbletea-widgets",
+ "crossterm",
+ "futures",
+ "lipgloss",
+ "once_cell",
+ "regex",
+ "serde",
+ "serde_json",
+ "tokio",
+ "which",
+]
+
+[[package]]
+name = "vte"
+version = "0.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "231fdcd7ef3037e8330d8e17e61011a2c244126acc0a982f4040ac3f9f0bc077"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "which"
+version = "4.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "87ba24419a2078cd2b0f2ede2691b6c66d8e47836da3b6db8265ebad47afbfc7"
+dependencies = [
+ "either",
+ "home",
+ "once_cell",
+ "rustix 0.38.44",
+]
+
+[[package]]
+name = "winapi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
+dependencies = [
+ "winapi-i686-pc-windows-gnu",
+ "winapi-x86_64-pc-windows-gnu",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
+[[package]]
+name = "windows-link"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e6ad25900d524eaabdbbb96d20b4311e1e7ae1699af4fb28c17ae66c80d798a"
+
+[[package]]
+name = "windows-sys"
+version = "0.59.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
+dependencies = [
+ "windows-targets 0.52.6",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2f500e4d28234f72040990ec9d39e3a6b950f9f22d3dba18416c35882612bcb"
+dependencies = [
+ "windows-targets 0.53.3",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+dependencies = [
+ "windows_aarch64_gnullvm 0.52.6",
+ "windows_aarch64_msvc 0.52.6",
+ "windows_i686_gnu 0.52.6",
+ "windows_i686_gnullvm 0.52.6",
+ "windows_i686_msvc 0.52.6",
+ "windows_x86_64_gnu 0.52.6",
+ "windows_x86_64_gnullvm 0.52.6",
+ "windows_x86_64_msvc 0.52.6",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.53.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d5fe6031c4041849d7c496a8ded650796e7b6ecc19df1a431c1a363342e5dc91"
+dependencies = [
+ "windows-link",
+ "windows_aarch64_gnullvm 0.53.0",
+ "windows_aarch64_msvc 0.53.0",
+ "windows_i686_gnu 0.53.0",
+ "windows_i686_gnullvm 0.53.0",
+ "windows_i686_msvc 0.53.0",
+ "windows_x86_64_gnu 0.53.0",
+ "windows_x86_64_gnullvm 0.53.0",
+ "windows_x86_64_msvc 0.53.0",
+]
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.53.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "86b8d5f90ddd19cb4a147a5fa63ca848db3df085e25fee3cc10b39b6eebae764"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.53.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c7651a1f62a11b8cbd5e0d42526e55f2c99886c77e007179efff86c2b137e66c"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.53.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c1dc67659d35f387f5f6c479dc4e28f1d4bb90ddd1a5d3da2e5d97b42d6272c3"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.53.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ce6ccbdedbf6d6354471319e781c0dfef054c81fbc7cf83f338a4296c0cae11"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.53.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "581fee95406bb13382d2f65cd4a908ca7b1e4c2f1917f143ba16efe98a589b5d"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.53.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2e55b5ac9ea33f2fc1716d1742db15574fd6fc8dadc51caab1c16a3d3b4190ba"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.53.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0a6e035dd0599267ce1ee132e51c27dd29437f63325753051e71dd9e42406c57"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.53.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "271414315aff87387382ec3d271b52d7ae78726f5d44ac98b4f4030c91880486"

crates/Cargo.toml

···
+[package]
+name = "van"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+lipgloss = "*"
+bubbletea-rs = "*"
+# Disable default features for bubbletea-widgets (prevents optional clipboard backend)
+bubbletea-widgets = { version = "*", default-features = false }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+
+which = "4.4"
+
+# runtime helpers for interactive Program
+once_cell = "1.20"
+futures = "0.3"
+
+# Use crossterm version compatible with bubbletea-rs
+crossterm = "0.29"
+
+# tokio for async main used in src/main.rs
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+
+
+[dev-dependencies]
+regex = "1.10"

crates/src/acekey.rs

···
+use std::collections::{HashMap, HashSet};
+
+/// Returns true for characters allowed in ACE keys (alphanumeric or hyphen).
+#[inline]
+pub fn is_ace_rune(c: char) -> bool {
+    c.is_alphanumeric() || c == '-'
+}
+
+/// Returns true when `s` is a single-character string and that character is an ACE rune.
+#[inline]
+pub fn is_single_ace_rune(s: &str) -> bool {
+    if let Some(ch) = s.chars().next() {
+        s.chars().count() == 1 && is_ace_rune(ch)
+    } else {
+        false
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Assignment {
+    pub index: usize,
+    pub prefix: String,
+}
+
+#[derive(Clone, Debug)]
+struct ElemInfo {
+    index: usize,
+    _orig: String,
+    clean: String,
+    lower: String,
+    lu: String,
+    rune_count: usize,
+}
+
+fn build_infos(elements: &[String]) -> Vec<ElemInfo> {
+    elements
+        .iter()
+        .enumerate()
+        .filter_map(|(i, e)| {
+            let c = clean_string(e);
+            if c.is_empty() {
+                None
+            } else {
+                let lower = c.to_lowercase();
+                let lu = leftmost_unit(&c);
+                let rune_count = c.chars().count();
+                Some(ElemInfo { index: i, _orig: e.clone(), clean: c, lower, lu, rune_count })
+            }
+        })
+        .collect()
+}
+
+fn clean_string(s: &str) -> String {
+    s.chars().filter(|&r| is_ace_rune(r)).collect()
+}
+
+fn leftmost_unit(clean: &str) -> String {
+    if clean.starts_with("--") {
+        "--".to_string()
+    } else {
+        clean.chars().next().map(|c| c.to_string()).unwrap_or_default()
+    }
+}
+
+fn compute_typed_left_unit(typed_lower: &str) -> String {
+    leftmost_unit(typed_lower)
+}
+
+fn collapse_leading(match_lower: &str, lu_lower: &str) -> String {
+    if lu_lower == "--" || lu_lower.is_empty() {
+        return match_lower.to_string();
+    }
+    let first = lu_lower.chars().next().unwrap();
+    let chars = match_lower.chars();
+    // count leading occurrences of `first`
+    let mut count = 0usize;
+    for c in chars {
+        if c == first {
+            count += 1;
+        } else {
+            // we've advanced one too far, include this char later
+            break;
+        }
+    }
+    if count > 1 {
+        let mut res = String::new();
+        res.push(first);
+        // append the remainder after the run of `first`
+        res.extend(match_lower.chars().skip(count));
+        res
+    } else {
+        match_lower.to_string()
+    }
+}
+
+pub fn assign_initial_candidates(elements: &[String]) -> HashMap<usize, String> {
+    elements
+        .iter()
+        .enumerate()
+        .filter_map(|(i, e)| {
+            let clean = clean_string(e);
+            if clean.is_empty() {
+                None
+            } else {
+                let mut lu = leftmost_unit(&clean);
+                if lu == "--" {
+                    lu = "-".to_string();
+                }
+                Some((i, lu))
+            }
+        })
+        .collect()
+}
+
+// helper: attempt base full key match
+fn attempt_base_full_key_match(infos: &[ElemInfo], typed_left_unit: &str, typed_clean: &str, typed_lower: &str) -> Option<Assignment> {
+    if typed_left_unit.is_empty() {
+        return None;
+    }
+    if typed_lower.chars().count() <= typed_left_unit.chars().count() {
+        return None;
+    }
+
+    // If typed is exactly left_unit + one rune, prefer the candidate that contains
+    // that rune (after the left unit) uniquely among base candidates.
+    let extra_len = typed_lower.chars().count() - typed_left_unit.chars().count();
+    if extra_len == 1 {
+        let extra_ch = typed_lower.chars().nth(typed_left_unit.chars().count()).unwrap();
+        let mut matches = Vec::new();
+        for it in infos.iter() {
+            let lu_lower = it.lu.to_lowercase();
+            let match_lu = if typed_left_unit == "-" { lu_lower == "-" || lu_lower == "--" } else { lu_lower == typed_left_unit };
+            if match_lu {
+                let start_pos = it.lu.chars().count();
+                if it.lower.chars().skip(start_pos).any(|r| r == extra_ch) {
+                    matches.push(it.clone());
+                }
+            }
+        }
+        if matches.len() == 1 {
+            return Some(Assignment { index: matches[0].index, prefix: String::new() });
+        }
+    }
+
+    let mut base_list: Vec<ElemInfo> = infos
+        .iter()
+        .filter(|it| {
+            let lu_lower = it.lu.to_lowercase();
+            if typed_left_unit == "-" {
+                lu_lower == "-" || lu_lower == "--"
+            } else {
+                lu_lower == typed_left_unit
+            }
+        })
+        .cloned()
+        .collect();
+
+    base_list.sort_by(|a, b| {
+        a.rune_count
+            .cmp(&b.rune_count)
+            .then(a.index.cmp(&b.index))
+    });
+
+    // original-case allocation
+    let mut used_orig = HashSet::new();
+    for it in &base_list {
+        let start_pos = it.lu.chars().count();
+        if let Some(c) = it.clean.chars().skip(start_pos).find(|&r| !used_orig.contains(&r)) {
+            used_orig.insert(c);
+            let full = format!("{typed_left_unit}{c}");
+            if full == typed_clean {
+                return Some(Assignment { index: it.index, prefix: String::new() });
+            }
+        } else if typed_left_unit == typed_clean {
+            return Some(Assignment { index: it.index, prefix: String::new() });
+        }
+    }
+
+    // fallback lowercased allocation
+    let mut used_base = HashSet::new();
+    for it in &base_list {
+        let start_pos = it.lu.chars().count();
+        if let Some(c) = it.lower.chars().skip(start_pos).find(|&r| r != '-' && !used_base.contains(&r)) {
+            used_base.insert(c);
+            let full = format!("{typed_left_unit}{c}");
+            if full == typed_lower {
+                return Some(Assignment { index: it.index, prefix: String::new() });
+            }
+        } else if typed_left_unit == typed_lower {
+            return Some(Assignment { index: it.index, prefix: String::new() });
+        }
+    }
+
+    None
+}
+
+fn filter_candidates(infos: &[ElemInfo], typed_lower: &str, typed_left_unit: &str) -> Vec<ElemInfo> {
+    if typed_lower == "-" {
+        return infos
+            .iter()
+            .filter(|it| {
+                let lu_lower = it.lu.to_lowercase();
+                lu_lower == "-" || lu_lower == "--"
+            })
+            .cloned()
+            .collect();
+    }
+
+    infos
+        .iter()
+        .filter(|it| {
+            let lu_lower = it.lu.to_lowercase();
+            if lu_lower != typed_left_unit {
+                return false;
+            }
+            let match_lower = if lu_lower != "--" && !lu_lower.is_empty() {
+                collapse_leading(&it.lower, &lu_lower)
+            } else {
+                it.lower.clone()
+            };
+            it.lower.starts_with(typed_lower) || match_lower.starts_with(typed_lower)
+        })
+        .cloned()
+        .collect()
+}
+
+fn attempt_base_typed_selection_when_no_candidates(infos: &[ElemInfo], typed_lower: &str, typed_left_unit: &str) -> Option<Vec<Assignment>> {
+    if typed_left_unit.is_empty() {
+        return None;
+    }
+    if typed_lower.chars().count() <= typed_left_unit.chars().count() {
+        return None;
+    }
+
+    let mut base_candidates: Vec<ElemInfo> = infos
+        .iter()
+        .filter(|it| {
+            let lu_lower = it.lu.to_lowercase();
+            if typed_left_unit == "-" {
+                lu_lower == "-" || lu_lower == "--"
+            } else {
+                lu_lower == typed_left_unit
+            }
+        }).filter(|&it| {
+            let lu_lower = it.lu.to_lowercase();
+            let match_lower = if lu_lower != "--" && !lu_lower.is_empty() {
+                collapse_leading(&it.lower, &lu_lower)
+            } else {
+                it.lower.clone()
+            };
+            it.lower.starts_with(typed_left_unit) || match_lower.starts_with(typed_left_unit)
+        }).cloned()
+        .collect();
+
+    if base_candidates.is_empty() {
+        return None;
+    }
+
+    base_candidates.sort_by(|a, b| a.rune_count.cmp(&b.rune_count).then(a.index.cmp(&b.index)));
+
+    let mut used = HashSet::new();
+    let len_base = typed_left_unit.chars().count();
+    for bc in &base_candidates {
+        if let Some(r) = bc.lower.chars().skip(len_base).find(|&r| r != '-' && !used.contains(&r)) {
+            used.insert(r);
+            let full = format!("{typed_left_unit}{r}");
+            if full == typed_lower {
+                return Some(vec![Assignment { index: bc.index, prefix: String::new() }]);
+            }
+        }
+    }
+
+    None
+}
+
+fn exact_case_precedence(candidates: &[ElemInfo], typed_clean: &str) -> Option<Assignment> {
+    if typed_clean.is_empty() {
+        return None;
+    }
+    let exact: Vec<&ElemInfo> = candidates.iter().filter(|it| it.clean.starts_with(typed_clean)).collect();
+    if exact.len() == 1 {
+        let it = exact[0];
+        return Some(Assignment { index: it.index, prefix: String::new() });
+    }
+    None
+}
+
+fn filter_exact_matches(candidates: &[ElemInfo], typed_lower: &str) -> Vec<ElemInfo> {
+    if typed_lower.is_empty() {
+        return candidates.to_vec();
+    }
+
+    let exact_matches: Vec<ElemInfo> = candidates
+        .iter()
+        .filter_map(|it| {
+            let lu_lower = it.lu.to_lowercase();
+            let match_lower = if lu_lower != "--" && !lu_lower.is_empty() {
+                collapse_leading(&it.lower, &lu_lower)
+            } else {
+                it.lower.clone()
+            };
+            if it.lower == typed_lower || (match_lower == typed_lower && it.lower.chars().count() == match_lower.chars().count()) {
+                Some(it.clone())
+            } else {
+                None
+            }
+        })
+        .collect();
+
+    if exact_matches.is_empty() {
+        return candidates.to_vec();
+    }
+
+    let other_starts = candidates.iter().any(|it| it.lower != typed_lower && it.lower.starts_with(typed_lower));
+    if !other_starts {
+        exact_matches
+    } else {
+        candidates.to_vec()
+    }
+}
+
+fn allocate_disambiguators(candidates: &[ElemInfo], typed_lower: &str, elements_count: usize) -> Vec<Assignment> {
+    let mut used = HashSet::new();
+    let mut assigned: Vec<Option<Assignment>> = vec![None; elements_count];
+    let mut order: Vec<ElemInfo> = candidates.to_vec();
+    order.sort_by(|a, b| a.rune_count.cmp(&b.rune_count).then(a.index.cmp(&b.index)));
+
+    // compute the typed left unit (the ace-character to fall back to)
+    let typed_left_unit = compute_typed_left_unit(typed_lower);
+
+    for cand in order {
+        let lu_lower = cand.lu.to_lowercase();
+        let start_pos = lu_lower.chars().count();
+        if let Some(ar) = cand.clean.chars().skip(start_pos).find(|&r| r != '-' && !used.contains(&r)) {
+            used.insert(ar);
+            assigned[cand.index] = Some(Assignment { index: cand.index, prefix: ar.to_string() });
+        } else if lu_lower == "--" && typed_lower == "-" {
+            assigned[cand.index] = Some(Assignment { index: cand.index, prefix: "-".to_string() });
+        } else {
+            // Always use the typed left unit as the prefix when no other disambiguator
+            // exists. This ensures every candidate remains selectable.
+            if !typed_left_unit.is_empty() {
+                assigned[cand.index] = Some(Assignment { index: cand.index, prefix: typed_left_unit.clone() });
+            } else {
+                // fallback to empty prefix only if there is absolutely nothing sensible to use
+                assigned[cand.index] = Some(Assignment { index: cand.index, prefix: String::new() });
+            }
+        }
+    }
+
+    assigned.into_iter().flatten().collect()
+}
+
+// Build collapsed-match strings, start positions and max length for an ordered list
+fn build_ms_maps(order: &[ElemInfo]) -> (HashMap<usize, String>, HashMap<usize, usize>, usize) {
+    let mut ms_map: HashMap<usize, String> = HashMap::new();
+    let mut start_pos_map: HashMap<usize, usize> = HashMap::new();
+    let mut max_len = 0usize;
+    for it in order {
+        let lu_lower = it.lu.to_lowercase();
+        let ms = if lu_lower != "--" && !lu_lower.is_empty() {
+            collapse_leading(&it.lower, &lu_lower)
+        } else {
+            it.lower.clone()
+        };
+        max_len = max_len.max(ms.chars().count());
+        ms_map.insert(it.index, ms);
+        start_pos_map.insert(it.index, lu_lower.chars().count());
+    }
+    (ms_map, start_pos_map, max_len)
+}
+
+// Offset-based assignment pass: assign unique characters at each offset among remaining candidates
+fn offset_assignment_pass(
+    order: &[ElemInfo],
+    ms_map: &HashMap<usize, String>,
+    start_pos_map: &HashMap<usize, usize>,
+    max_len: usize,
+    typed_left_unit: &str,
+    assigned: &mut Vec<Option<Assignment>>,
+    used: &mut HashSet<char>,
+    remaining: &mut Vec<usize>,
+) {
+    for offset in 0..max_len {
+        if remaining.is_empty() { break; }
+        let mut freq: HashMap<char, usize> = HashMap::new();
+        for &idx in remaining.iter() {
+            if let Some(ms) = ms_map.get(&idx) {
+                let start_pos = *start_pos_map.get(&idx).unwrap_or(&0);
+                let pos = start_pos + offset;
+                if let Some(ch) = ms.chars().nth(pos) {
+                    if ch != '-' && !used.contains(&ch) {
+                        if typed_left_unit.is_empty() || ch.to_string() != typed_left_unit {
+                            *freq.entry(ch).or_insert(0) += 1;
+                        }
+                    }
+                }
+            }
+        }
+
+        let mut newly_assigned: Vec<usize> = Vec::new();
+        for it in order {
+            let idx = it.index;
+            if !remaining.contains(&idx) { continue; }
+            if let Some(ms) = ms_map.get(&idx) {
+                let start_pos = *start_pos_map.get(&idx).unwrap_or(&0);
+                let pos = start_pos + offset;
+                if let Some(ch) = ms.chars().nth(pos) {
+                    if ch != '-' && !used.contains(&ch) && (typed_left_unit.is_empty() || ch.to_string() != typed_left_unit) {
+                        if let Some(&count) = freq.get(&ch) {
+                            if count == 1 {
+                                // prefer original-case char when possible
+                                if let Some(orig_it) = order.iter().find(|o| o.index == idx) {
+                                    if let Some(orig_ch) = orig_it.clean.chars().nth(pos) {
+                                        if orig_ch != '-' {
+                                            if orig_ch.to_ascii_lowercase() == ch {
+                                                assigned[idx] = Some(Assignment { index: idx, prefix: orig_ch.to_string() });
+                                            } else {
+                                                assigned[idx] = Some(Assignment { index: idx, prefix: ch.to_string() });
+                                            }
+                                        } else {
+                                            assigned[idx] = Some(Assignment { index: idx, prefix: ch.to_string() });
+                                        }
+                                    } else {
+                                        assigned[idx] = Some(Assignment { index: idx, prefix: ch.to_string() });
+                                    }
+                                } else {
+                                    assigned[idx] = Some(Assignment { index: idx, prefix: ch.to_string() });
+                                }
+                                used.insert(ch);
+                                newly_assigned.push(idx);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        if !newly_assigned.is_empty() {
+            remaining.retain(|r| !newly_assigned.contains(r));
+        }
+    }
+}
+
+// Per-candidate left-to-right contiguous pass for remaining candidates
+fn per_candidate_pass(
+    order: &[ElemInfo],
+    ms_map: &HashMap<usize, String>,
+    start_pos_map: &HashMap<usize, usize>,
+    typed_left_unit: &str,
+    assigned: &mut Vec<Option<Assignment>>,
+    used: &mut HashSet<char>,
+    remaining: &mut Vec<usize>,
+) {
+    let mut newly_assigned_pl: Vec<usize> = Vec::new();
+    for it in order {
+        let idx = it.index;
+        if !remaining.contains(&idx) { continue; }
+        if let Some(ms) = ms_map.get(&idx) {
+            let start_pos = *start_pos_map.get(&idx).unwrap_or(&0);
+            let total = ms.chars().count();
+            for pos in start_pos..total {
+                if let Some(ch) = ms.chars().nth(pos) {
+                    if ch == '-' { continue; }
+                    if !used.contains(&ch) && (typed_left_unit.is_empty() || ch.to_string() != typed_left_unit) {
+                        if let Some(orig_ch) = it.clean.chars().nth(pos) {
+                            if orig_ch != '-' {
+                                if orig_ch.to_ascii_lowercase() == ch {
+                                    assigned[idx] = Some(Assignment { index: idx, prefix: orig_ch.to_string() });
+                                } else {
+                                    assigned[idx] = Some(Assignment { index: idx, prefix: ch.to_string() });
+                                }
+                            } else {
+                                assigned[idx] = Some(Assignment { index: idx, prefix: ch.to_string() });
+                            }
+                        } else {
+                            assigned[idx] = Some(Assignment { index: idx, prefix: ch.to_string() });
+                        }
+                        used.insert(ch);
+                        newly_assigned_pl.push(idx);
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    if !newly_assigned_pl.is_empty() {
+        remaining.retain(|r| !newly_assigned_pl.contains(r));
+    }
+}
+
+// Last-resort fallback assignment for any remaining candidates
+fn last_resort_assign(
+    order: &[ElemInfo],
+    ms_map: &HashMap<usize, String>,
+    typed_left_unit: &str,
+    assigned: &mut Vec<Option<Assignment>>,
+    remaining: &Vec<usize>,
+) {
+    for idx in remaining.iter() {
+        if let Some(ms) = ms_map.get(idx) {
+            let mut chosen: Option<String> = None;
+            if let Some(ch) = ms.chars().rev().find(|&r| r != '-') {
+                if typed_left_unit.is_empty() || ch.to_string() != typed_left_unit {
+                    let total_chars = ms.chars().count();
+                    if let Some(pos_rev) = ms.chars().rev().position(|r| r == ch) {
+                        let pos = total_chars.saturating_sub(1 + pos_rev);
+                        if let Some(orig_it) = order.iter().find(|o| o.index == *idx) {
+                            if let Some(orig_ch) = orig_it.clean.chars().nth(pos) {
+                                if orig_ch != '-' && orig_ch.to_ascii_lowercase() == ch {
+                                    chosen = Some(orig_ch.to_string());
+                                }
+                            }
+                        }
+                    }
+                    if chosen.is_none() {
+                        chosen = Some(ch.to_string());
+                    }
+                } else {
+                    if let Some(ch2) = ms.chars().rev().find(|&r| r != '-' && (typed_left_unit.is_empty() || r.to_string() != typed_left_unit)) {
+                        chosen = Some(ch2.to_string());
+                    } else {
+                        chosen = Some(ch.to_string());
+                    }
+                }
+            }
+
+            if let Some(pref) = chosen {
+                assigned[*idx] = Some(Assignment { index: *idx, prefix: pref });
+            } else {
+                let lu = order.iter().find(|o| o.index == *idx).map(|o| o.lu.clone()).unwrap_or_default();
+                let use_pref = if lu == "--" { "-".to_string() } else { lu };
+                assigned[*idx] = Some(Assignment { index: *idx, prefix: use_pref });
+            }
+        }
+    }
+}
+
+// Replace the original allocate_disambiguators_filtered body with calls into the helpers
+fn allocate_disambiguators_filtered(candidates: &[ElemInfo], typed_lower: &str, elements_count: usize) -> Vec<Assignment> {
+    // Filtered allocator following vic/acekey.md contiguous-right semantics.
+    let typed_left_unit = compute_typed_left_unit(typed_lower);
+
+    // deterministic order
+    let mut order: Vec<ElemInfo> = candidates.to_vec();
+    order.sort_by(|a, b| a.rune_count.cmp(&b.rune_count).then(a.index.cmp(&b.index)));
+
+    // build collapsed lowercase match strings and start positions
+    let (ms_map, start_pos_map, max_len) = build_ms_maps(&order);
+
+    let mut assigned: Vec<Option<Assignment>> = vec![None; elements_count];
+    let mut used: HashSet<char> = HashSet::new();
+    let mut remaining: Vec<usize> = order.iter().map(|o| o.index).collect();
+
+    // Offset loop
+    offset_assignment_pass(&order, &ms_map, &start_pos_map, max_len, &typed_left_unit, &mut assigned, &mut used, &mut remaining);
+
+    // Per-candidate left-to-right contiguous pass
+    if !remaining.is_empty() {
+        per_candidate_pass(&order, &ms_map, &start_pos_map, &typed_left_unit, &mut assigned, &mut used, &mut remaining);
+    }
+
+    // Last-resort fallback
+    if !remaining.is_empty() {
+        last_resort_assign(&order, &ms_map, &typed_left_unit, &mut assigned, &remaining);
+    }
+
+    assigned.into_iter().flatten().collect()
+}
+
+pub fn assign_ace_keys(elements: &[String], typed: &str) -> Option<Vec<Assignment>> {
+    let infos = build_infos(elements);
+    let typed_clean = clean_string(typed);
+    let typed_lower = typed_clean.to_lowercase();
+
+    // compute left unit early
+    let typed_left_unit = compute_typed_left_unit(&typed_lower);
+
+    // If nothing is typed, return initial prefixes (e.g., flags get "-" for "--long").
+    if typed_lower.is_empty() {
+        let initial_map = assign_initial_candidates(elements);
+        let mut res: Vec<Assignment> = Vec::new();
+        for (idx, pref) in initial_map.into_iter() {
+            res.push(Assignment { index: idx, prefix: pref });
+        }
+        return Some(res);
+    }
+
+    // quick attempt: try base full-key match only when typed is not a left-unit followed by
+    // extra AceKey tokens. If typed is left-unit + extra, prefer the tokenized iterative
+    // resolution path below to avoid premature selection.
+    if !( !typed_left_unit.is_empty() && typed_lower.starts_with(&typed_left_unit) && typed_lower.chars().count() > typed_left_unit.chars().count() ) {
+        if let Some(a) = attempt_base_full_key_match(&infos, &typed_left_unit, &typed_clean, &typed_lower) {
+            return Some(vec![a]);
+        }
+    }
+
+    // fast path: direct match on clean/typed
+    if let Some(idx) = infos.iter().position(|it| it.clean == typed_clean) {
+        if !(typed_lower == typed_left_unit && infos.iter().filter(|it| it.lu.to_lowercase() == typed_left_unit).count() > 1) {
+            return Some(vec![Assignment { index: idx, prefix: String::new() }]);
+        }
+    }
+
+    // Step 1: exact case match precedence
+    if let Some(exact) = exact_case_precedence(&infos, &typed_clean) {
+        return Some(vec![exact]);
+    }
+
+    // Step 2: candidate filtering from infos based on typed and left unit
+    let mut maybe_candidates: Option<Vec<ElemInfo>> = None;
+    if !typed_left_unit.is_empty() && typed_lower.starts_with(&typed_left_unit)
+        && typed_lower.chars().count() > typed_left_unit.chars().count()
+    {
+        // treat the extra runes after the left-unit as a sequence of AceKey tokens
+        // and iteratively recompute disambiguators narrowing the candidate set per token.
+        let base_list: Vec<ElemInfo> = infos
+            .iter()
+            .filter(|it| {
+                let lu_lower = it.lu.to_lowercase();
+                if typed_left_unit == "-" {
+                    lu_lower == "-" || lu_lower == "--"
+                } else {
+                    lu_lower == typed_left_unit
+                }
+            })
+            .cloned()
+            .collect();
+
+        if !base_list.is_empty() {
+             // collect token chars (each rune typed after the left-unit)
+             let extra_chars: Vec<char> = typed_lower.chars().skip(typed_left_unit.chars().count()).collect();
+             // iteratively consume tokens
+             let mut narrowed = base_list;
+             let mut consumed_any = false;
+             // compute the base snapshot assignments once (this reflects what the UI shows)
+             let base_assigns = allocate_disambiguators_filtered(&narrowed, &typed_left_unit, elements.len());
+             for (i, token) in extra_chars.iter().enumerate() {
+                 if narrowed.len() <= 1 {
+                     break;
+                 }
+                 // use base snapshot for the first token so typing the shown disambiguator
+                 // selects from the items that were assigned that rune at the initial stage.
+                 let assigns = if i == 0 {
+                    base_assigns.clone()
+                 } else {
+                    allocate_disambiguators_filtered(&narrowed, &typed_left_unit, elements.len())
+                 };
+                 let token_str = token.to_string();
+
+                 // find indices assigned this token
+                 let matching_idxs: Vec<usize> = assigns
+                     .into_iter()
+                     .filter(|a| a.prefix.to_lowercase() == token_str)
+                     .map(|a| a.index)
+                     .collect();
+
+                 if matching_idxs.is_empty() {
+                     // token did not match any assigned disambiguator in this narrowed set;
+                     // stop iterative token resolution and fall back to standard filtering
+                     break;
+                 }
+
+                 consumed_any = true;
+                 if matching_idxs.len() == 1 {
+                     // unique selection reached
+                     return Some(vec![Assignment { index: matching_idxs[0], prefix: String::new() }]);
+                 }
+
+                 // narrow the candidate list to those matching indices and continue
+                 let set: std::collections::HashSet<usize> = matching_idxs.into_iter().collect();
+                 narrowed.retain(|it| set.contains(&it.index));
+             }
+             
+             if consumed_any {
+                 // if we consumed at least one token but didn't resolve to a single item,
+                 // use the narrowed candidate set for the later allocation steps
+                 maybe_candidates = Some(narrowed);
+             }
+         }
+     }
+
+    // remember whether we arrived here after tokenized narrowing so we can
+    // choose a matching allocator later without relying on maybe_candidates
+    // which will be consumed by the candidate selection below.
+    let used_token_narrowing = maybe_candidates.is_some();
+    let mut candidates: Vec<ElemInfo> = if let Some(v) = maybe_candidates { v } else { filter_candidates(&infos, &typed_lower, &typed_left_unit) };
+
+    if candidates.is_empty() {
+        if let Some(res) = attempt_base_typed_selection_when_no_candidates(&infos, &typed_lower, &typed_left_unit) {
+            return Some(res);
+        }
+        return None;
+    }
+
+    // Step 3: exact-case precedence among filtered candidates
+    if let Some(a) = exact_case_precedence(&candidates, &typed_clean) {
+        return Some(vec![a]);
+    }
+
+    // Step 4: filtered recomputation when typed equals left-unit
+    if typed_lower == typed_left_unit && candidates.len() > 1 {
+        let res = allocate_disambiguators_filtered(&candidates, &typed_lower, elements.len());
+        return Some(res);
+    }
+
+    // Step 5: filter exact matches and possibly select single
+    candidates = filter_exact_matches(&candidates, &typed_lower);
+    if candidates.len() == 1 && !typed_lower.is_empty() {
+        return Some(vec![Assignment { index: candidates[0].index, prefix: String::new() }]);
+    }
+
+    // Step 6: default disambiguator allocation
+    let final_res = if used_token_narrowing {
+         allocate_disambiguators_filtered(&candidates, &typed_left_unit, elements.len())
+     } else {
+         allocate_disambiguators(&candidates, &typed_lower, elements.len())
+     };
+     Some(final_res)
+}
+
+#[cfg(test)]
+mod acekey_tests {
+    use super::*;
+    use std::collections::HashSet;
+
+    #[test]
+    fn test_contiguous_unique_ch_examples() {
+        let els = ["chcpu", "chpasswd", "chsh"];
+        let elems: Vec<String> = els.iter().map(|s| s.to_string()).collect();
+        let res = assign_ace_keys(&elems, "c");
+        assert!(res.is_some(), "expected assign_ace_keys to return assignments");
+        let v = res.unwrap();
+        // Expect one assignment per element
+        assert_eq!(v.len(), 3);
+        // None of the returned assignments should reuse the left-unit 'c'
+        for a in v.iter() {
+            assert!(!a.prefix.is_empty(), "expected non-empty prefix for index {}", a.index);
+            assert_ne!(a.prefix, "c", "left-unit reuse not allowed for index {}", a.index);
+        }
+        // All assigned prefixes should be unique
+        let mut seen = HashSet::new();
+        for a in v.iter() {
+            assert!(seen.insert(a.prefix.clone()), "duplicate prefix {}", a.prefix);
+        }
+    }
+}

crates/src/ast.rs

···
+use serde::Deserialize;
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "PascalCase")]
+pub struct FlagDef {
+    pub longhand: String,
+    pub shorthand: String,
+    pub usage: String,
+    pub requires_value: bool,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "PascalCase")]
+pub struct CommandDef {
+    pub name: String,
+    pub short: String,
+    pub aliases: Vec<String>,
+    pub flags: Vec<FlagDef>,
+    pub subcommands: Vec<CommandDef>,
+}
+
+#[derive(Debug, Clone)]
+pub struct FlagInstance {
+    pub form: String,
+    pub value: String,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct CommandNode {
+    pub name: String,
+    pub flags: Vec<FlagInstance>,
+    pub positionals: Vec<String>,
+}
+
+#[derive(Debug, Clone)]
+pub struct HistoryOp {
+    pub kind: String,
+    pub depth: usize,
+}
+
+// Story 1.2: Redirection enum
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Redirection {
+    Input(String),
+    Output { file: String, append: bool },
+}
+
+// Story 1.2: Binary operators connecting segments (future use)
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum BinaryOp {
+    Pipe,
+    And,
+    Or,
+}
+
+// Renamed from AST -> Segment (Story 1.1)
+#[derive(Debug, Clone, Default)]
+pub struct Segment {
+    pub root: String,
+    pub stack: Vec<CommandNode>,
+    pub history: Vec<HistoryOp>,
+    pub redirections: Vec<Redirection>, // Story 1.2
+}
+
+impl Segment {
+    pub fn new_empty(root: &str) -> Self {
+        let n = CommandNode {
+            name: root.to_string(),
+            flags: vec![],
+            positionals: vec![],
+        };
+        Segment {
+            root: root.to_string(),
+            stack: vec![n],
+            history: vec![],
+            redirections: vec![],
+        }
+    }
+
+    pub fn top(&self) -> Option<&CommandNode> {
+        self.stack.last()
+    }
+
+    pub fn push_subcommand(&mut self, name: &str) {
+        let n = CommandNode {
+            name: name.to_string(),
+            flags: vec![],
+            positionals: vec![],
+        };
+        self.stack.push(n);
+        self.history.push(HistoryOp {
+            kind: "subcmd".to_string(),
+            depth: self.stack.len() - 1,
+        });
+    }
+
+    pub fn pop(&mut self) {
+        if self.stack.len() <= 1 {
+            return;
+        }
+        self.stack.pop();
+    }
+
+    pub fn add_flag_to_depth(&mut self, depth: usize, form: &str, value: &str) {
+        if depth >= self.stack.len() {
+            return;
+        }
+        let fi = FlagInstance {
+            form: form.to_string(),
+            value: value.to_string(),
+        };
+        self.stack[depth].flags.push(fi);
+        self.history.push(HistoryOp {
+            kind: "flag".to_string(),
+            depth,
+        });
+    }
+
+    pub fn add_flag(&mut self, form: &str, value: &str) {
+        if let Some(depth) = self.stack.len().checked_sub(1) {
+            self.add_flag_to_depth(depth, form, value);
+        }
+    }
+
+    pub fn remove_flag_from_depth(&mut self, form: &str, depth: usize) -> bool {
+        if depth >= self.stack.len() {
+            return false;
+        }
+        let node = &mut self.stack[depth];
+        if let Some(pos) = node.flags.iter().rposition(|f| f.form == form) {
+            node.flags.remove(pos);
+            return true;
+        }
+        false
+    }
+
+    pub fn remove_flag(&mut self, form: &str) -> bool {
+        if self.stack.is_empty() {
+            return false;
+        }
+        let depth = self.stack.len() - 1;
+        self.remove_flag_from_depth(form, depth)
+    }
+
+    pub fn add_positional(&mut self, val: &str) {
+        if let Some(node) = self.stack.last_mut() {
+            node.positionals.push(val.to_string());
+            self.history.push(HistoryOp {
+                kind: "pos".to_string(),
+                depth: self.stack.len() - 1,
+            });
+        }
+    }
+
+    pub fn remove_last(&mut self) {
+        if self.history.is_empty() {
+            if let Some(n) = self.stack.last_mut() {
+                if n.flags.pop().is_some() {
+                    return;
+                }
+                if n.positionals.pop().is_some() {
+                    return;
+                }
+                if self.stack.len() > 1 {
+                    self.pop();
+                }
+            }
+            return;
+        }
+
+        if let Some(op) = self.history.pop() {
+            match op.kind.as_str() {
+                "flag" => {
+                    if op.depth < self.stack.len() {
+                        let n = &mut self.stack[op.depth];
+                        n.flags.pop();
+                    }
+                }
+                "pos" => {
+                    if op.depth < self.stack.len() {
+                        let n = &mut self.stack[op.depth];
+                        n.positionals.pop();
+                    }
+                }
+                "subcmd" => {
+                    if self.stack.len() > 1 {
+                        self.pop();
+                    }
+                }
+                _ => {}
+            }
+        }
+    }
+
+    pub fn render_preview(&self) -> String {
+        let mut parts: Vec<String> = vec![self.root.clone()];
+
+        let append_node = |node: &CommandNode, include_name: bool, out: &mut Vec<String>| {
+            if include_name {
+                out.push(node.name.clone());
+            }
+            for f in &node.flags {
+                out.push(f.form.clone());
+                if !f.value.is_empty() {
+                    out.push(f.value.clone());
+                }
+            }
+            for p in &node.positionals {
+                out.push(p.clone());
+            }
+        };
+
+        for (i, node) in self.stack.iter().enumerate() {
+            if i == 0 {
+                append_node(node, false, &mut parts);
+            } else {
+                append_node(node, true, &mut parts);
+            }
+        }
+
+        parts.join(" ")
+    }
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct CommandLine {
+    pub segments: Vec<Segment>,
+    pub focused_segment_idx: usize,
+}
+
+impl CommandLine {
+    pub fn new() -> Self {
+        Self {
+            segments: vec![Segment::new_empty("")],
+            focused_segment_idx: 0,
+        }
+    }
+
+    pub fn focused_segment(&self) -> &Segment {
+        &self.segments[self.focused_segment_idx]
+    }
+
+    pub fn focused_segment_mut(&mut self) -> &mut Segment {
+        &mut self.segments[self.focused_segment_idx]
+    }
+
+    pub fn add_segment(&mut self) {
+        self.segments.push(Segment::new_empty(""));
+        self.focused_segment_idx = self.segments.len() - 1;
+    }
+
+    pub fn remove_focused_segment(&mut self) {
+        if self.segments.len() > 1 && self.focused_segment().root.is_empty() {
+            let idx = self.focused_segment_idx;
+            self.segments.remove(idx);
+            if self.focused_segment_idx > 0 {
+                self.focused_segment_idx -= 1;
+            }
+        }
+    }
+
+    pub fn focus_next(&mut self) {
+        if self.focused_segment_idx + 1 < self.segments.len() {
+            self.focused_segment_idx += 1;
+        }
+    }
+
+    pub fn focus_prev(&mut self) {
+        if self.focused_segment_idx > 0 {
+            self.focused_segment_idx -= 1;
+        }
+    }
+
+    pub fn render_preview(&self) -> String {
+        self.segments
+            .iter()
+            .map(|s| s.render_preview())
+            .collect::<Vec<_>>()
+            .join(" | ")
+    }
+}
+
+// Tests for Story 1.2 (written before implementation of Redirection/BinaryOp additions)
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_redirection_struct() {
+        let r1 = Redirection::Input("in.txt".to_string());
+        let r2 = Redirection::Output {
+            file: "out.txt".to_string(),
+            append: false,
+        };
+        match r1 {
+            Redirection::Input(f) => assert_eq!(f, "in.txt"),
+            _ => panic!("expected Input"),
+        }
+        match r2 {
+            Redirection::Output { file, append } => {
+                assert_eq!(file, "out.txt");
+                assert!(!append);
+            }
+            _ => panic!("expected Output"),
+        }
+    }
+
+    #[test]
+    fn test_binary_op_enum() {
+        let p = BinaryOp::Pipe;
+        let a = BinaryOp::And;
+        let o = BinaryOp::Or;
+        assert!(matches!(p, BinaryOp::Pipe));
+        assert!(matches!(a, BinaryOp::And));
+        assert!(matches!(o, BinaryOp::Or));
+    }
+
+    #[test]
+    fn test_segment_with_redirections_field_exists() {
+        let seg = Segment::new_empty("cmd");
+        assert!(seg.redirections.is_empty());
+    }
+
+    #[test]
+    fn test_command_line_render_preview_single() {
+        let mut cl = CommandLine::new();
+        cl.focused_segment_mut().root = "cmd1".into();
+        assert_eq!(cl.render_preview(), "cmd1");
+    }
+
+    #[test]
+    fn test_command_line_render_preview_pipe() {
+        let mut cl = CommandLine::new();
+        cl.focused_segment_mut().root = "cmd1".into();
+        cl.add_segment();
+        cl.focused_segment_mut().root = "cmd2".into();
+        assert_eq!(cl.render_preview(), "cmd1 | cmd2");
+    }
+
+    // pending
+    #[test]
+    fn test_command_line_render_preview_with_redirection() {
+        // pending
+        // let mut cl = CommandLine::new();
+        // cl.focused_segment_mut().root = "cmd1".into();
+        // cl.focused_segment_mut().redirections.push(Redirection::Output {
+        //     file: "out.txt".into(),
+        //     append: false,
+        // });
+        // cl.add_segment();
+        // cl.focused_segment_mut().root = "cmd2".into();
+        // cl.focused_segment_mut().redirections.push(Redirection::Input("in.txt".into()));
+        // let preview = cl.render_preview();
+        // assert!(preview.contains("> out.txt"));
+        // assert!(preview.contains("cmd1"));
+        // assert!(preview.contains("cmd2"));
+        // assert!(preview.contains("< in.txt"));
+    }
+
+    #[test]
+    fn test_command_line_focus_management() {
+        let mut cl = CommandLine::new();
+        cl.add_segment();
+        assert_eq!(cl.focused_segment_idx, 1);
+        cl.focus_prev();
+        assert_eq!(cl.focused_segment_idx, 0);
+        cl.focus_prev();
+        assert_eq!(cl.focused_segment_idx, 0);
+        cl.focus_next();
+        assert_eq!(cl.focused_segment_idx, 1);
+        cl.focus_next();
+        assert_eq!(cl.focused_segment_idx, 1);
+    }
+
+    #[test]
+    fn test_command_line_add_segment() {
+        let mut cl = CommandLine::new();
+        cl.focused_segment_mut().root = "cmd1".into();
+        cl.add_segment();
+        assert_eq!(cl.segments.len(), 2);
+        assert_eq!(cl.focused_segment_idx, 1);
+    }
+
+    #[test]
+    fn test_command_line_remove_segment() {
+        let mut cl = CommandLine::new();
+        cl.focused_segment_mut().root = "cmd1".into();
+        cl.add_segment();
+        // second segment empty -> removable
+        cl.remove_focused_segment();
+        assert_eq!(cl.segments.len(), 1);
+        assert_eq!(cl.focused_segment_idx, 0);
+        // cannot remove non-empty first
+        cl.remove_focused_segment();
+        assert_eq!(cl.segments.len(), 1);
+    }
+}

crates/src/carapace.rs

···
+use crate::ast::{CommandDef, FlagDef};
+use std::process::Command;
+
+fn run_carapace_cmd(args: &[&str]) -> Result<String, String> {
+    let mut cmd = Command::new("carapace");
+    for a in args {
+        cmd.arg(a);
+    }
+    let out = cmd
+        .output()
+        .map_err(|e| format!("carapace {args:?} failed to run: {e}"))?;
+    if !out.status.success() {
+        let stderr = String::from_utf8_lossy(&out.stderr).to_string();
+        return Err(format!("carapace {:?} failed: {}", args, stderr.trim()));
+    }
+    Ok(String::from_utf8_lossy(&out.stdout).to_string())
+}
+
+pub fn list() -> Result<Vec<String>, String> {
+    let s = run_carapace_cmd(&["--list"])?;
+    Ok(s.lines()
+        .map(|l| l.trim())
+        .filter(|l| !l.is_empty())
+        .filter_map(|l| l.split_whitespace().next())
+        .filter(|name| which::which(name).is_ok())
+        .map(|s| s.to_string())
+        .collect())
+}
+
+pub fn list_with_desc() -> Result<Vec<(String, String)>, String> {
+    let s = run_carapace_cmd(&["--list"])?;
+    let out: Vec<(String, String)> = s
+        .lines()
+        .map(|l| l.trim())
+        .filter(|l| !l.is_empty())
+        .filter_map(|line| {
+            line.split_whitespace()
+                .next()
+                .and_then(|name| {
+                    if which::which(name).is_ok() {
+                        let short = if line.len() > name.len() {
+                            line[name.len()..].trim().to_string()
+                        } else {
+                            String::new()
+                        };
+                        Some((name.to_string(), short))
+                    } else {
+                        None
+                    }
+                })
+        })
+        .collect();
+    Ok(out)
+}
+
+pub fn export(cmd_name: &str) -> Result<CommandDef, String> {
+    if cmd_name.trim().is_empty() {
+        return Err("empty command name".to_string());
+    }
+    let s = run_carapace_cmd(&[cmd_name, "export"])?;
+
+    let r: serde_json::Value = serde_json::from_str(&s)
+        .map_err(|e| format!("failed to parse carapace export JSON: {e}"))?;
+
+    fn map_raw(r: &serde_json::Value) -> CommandDef {
+        let name = r
+            .get("Name")
+            .and_then(|v| v.as_str())
+            .unwrap_or("")
+            .to_string();
+        let short = r
+            .get("Short")
+            .and_then(|v| v.as_str())
+            .unwrap_or("")
+            .to_string();
+        let aliases = r
+            .get("Aliases")
+            .and_then(|v| v.as_array())
+            .map(|arr| {
+                arr.iter()
+                    .filter_map(|x| x.as_str().map(|s| s.to_string()))
+                    .collect()
+            })
+            .unwrap_or_default();
+        let mut flags = Vec::new();
+        if let Some(local) = r.get("LocalFlags").and_then(|v| v.as_array()) {
+            for f in local {
+                let long = f
+                    .get("Longhand")
+                    .and_then(|v| v.as_str())
+                    .unwrap_or("")
+                    .to_string();
+                let shortf = f
+                    .get("Shorthand")
+                    .and_then(|v| v.as_str())
+                    .unwrap_or("")
+                    .to_string();
+                let usage = f
+                    .get("Usage")
+                    .and_then(|v| v.as_str())
+                    .unwrap_or("")
+                    .to_string();
+                let typ = f.get("Type").and_then(|v| v.as_str()).unwrap_or("bool");
+                let fd = FlagDef {
+                    longhand: long,
+                    shorthand: shortf,
+                    usage,
+                    requires_value: typ != "bool",
+                };
+                flags.push(fd);
+            }
+        }
+        let mut subs = Vec::new();
+        if let Some(cmds) = r.get("Commands").and_then(|v| v.as_array()) {
+            for c in cmds {
+                subs.push(map_raw(c));
+            }
+        }
+        CommandDef {
+            name,
+            short,
+            aliases,
+            flags,
+            subcommands: subs,
+        }
+    }
+
+    Ok(map_raw(&r))
+}

crates/src/lib.rs

···
+//! van - interactive command completion preview tool
+//!
+//! Library crate exposing the small components used by the binary.
+//!
+//! Tests live close to the modules they exercise as unit tests.
+
+pub mod acekey;
+pub mod ast;
+pub mod carapace;
+
+pub mod ui;
+
+// Keep crate root minimal; tests moved into module files.
+
+#[cfg(test)]
+mod _root_tests {
+    // intentionally empty
+}

crates/src/main.rs

···
+// Entry point: program main
+// Handles --hook, --exe, --help, and runs the TUI
+//
+// TUI Docs: https://github.com/whit3rabbit/bubbletea-rs look for related crates there and examples on each of them.
+
+use std::env;
+use std::fs;
+use std::path::Path;
+use std::process::{self, Command, Stdio};
+use van::ui::{Model as UiModel, initial_model, run as noninteractive_run};
+
+use bubbletea_rs::{
+    Program, event::KeyMsg, event::WindowSizeMsg, model::Model as TeaModel, window_size,
+};
+use crossterm::event::{KeyCode, KeyModifiers};
+
+// Adapter type implementing bubbletea-rs Model trait by delegating to our UiModel
+struct TeaAdapter {
+    inner: UiModel,
+}
+
+impl TeaModel for TeaAdapter {
+    fn init() -> (Self, Option<bubbletea_rs::command::Cmd>) {
+        // preload carapace --list with descriptions so interactive UI shows top-level commands immediately
+        let entries = van::carapace::list_with_desc().unwrap_or_default();
+        let mut adapter = TeaAdapter {
+            inner: initial_model(entries),
+        };
+        let (width, height) = crossterm::terminal::size().unwrap_or((80, 24));
+        adapter.inner.update(van::ui::Msg::WindowSize {
+            width: width as usize,
+            height: height as usize,
+        });
+        let cmd = window_size();
+        (adapter, Some(cmd))
+    }
+
+    fn update(&mut self, msg: bubbletea_rs::event::Msg) -> Option<bubbletea_rs::command::Cmd> {
+        // Map bubbletea-rs Msg types to our ui::Msg and call update
+        if let Some(km) = msg.downcast_ref::<KeyMsg>() {
+            // Structured handling using crossterm types (KeyCode, KeyModifiers)
+            match &km.key {
+                KeyCode::Enter => {
+                    // Enter -> perform ExecProcess semantics
+                    self.inner.update(van::ui::Msg::KeyEnter);
+                    let preview = &self.inner.exit_preview;
+                    if preview.is_empty() {
+                        return None;
+                    }
+                    let shell = env::var("SHELL").unwrap_or_else(|_| "/bin/sh".to_string());
+                    let mut cmd = Command::new(shell);
+                    cmd.arg("-c")
+                        .arg(preview)
+                        .stdin(Stdio::inherit())
+                        .stdout(Stdio::inherit())
+                        .stderr(Stdio::inherit());
+                    match cmd.status() {
+                        Ok(status) => {
+                            if let Some(code) = status.code() {
+                                process::exit(code);
+                            } else {
+                                process::exit(0);
+                            }
+                        }
+                        Err(e) => {
+                            eprintln!("failed to execute command: {e}");
+                            process::exit(1);
+                        }
+                    }
+                }
+                KeyCode::Backspace => {
+                    self.inner.update(van::ui::Msg::KeyBackspace);
+                }
+                KeyCode::Esc => {
+                    // Quit immediately unless we're in value-input mode
+                    if !self.inner.in_value_mode {
+                        return Some(bubbletea_rs::quit());
+                    }
+                    self.inner.update(van::ui::Msg::KeyEsc);
+                }
+                KeyCode::Up => {
+                    self.inner.update(van::ui::Msg::KeyUp);
+                }
+                KeyCode::Down => {
+                    self.inner.update(van::ui::Msg::KeyDown);
+                }
+                KeyCode::Char(ch) => {
+                    // Control-key handling
+                    if km.modifiers.contains(KeyModifiers::CONTROL) {
+                        match ch {
+                            'n' | 'N' => {
+                                self.inner.update(van::ui::Msg::KeyDown);
+                            }
+                            'p' | 'P' => {
+                                self.inner.update(van::ui::Msg::KeyUp);
+                            }
+                            'c' | 'C' => {
+                                return Some(bubbletea_rs::quit());
+                            }
+                            _ => {}
+                        }
+                    } else if *ch == ' ' {
+                        self.inner.update(van::ui::Msg::KeySpace);
+                    } else {
+                        self.inner.update(van::ui::Msg::Rune(*ch));
+                    }
+                }
+                _ => { /* ignore other keys */ }
+            }
+
+            return None;
+        }
+        if let Some(ws) = msg.downcast_ref::<WindowSizeMsg>() {
+            self.inner.update(van::ui::Msg::WindowSize {
+                width: ws.width as usize,
+                height: ws.height as usize,
+            });
+            return None;
+        }
+        None
+    }
+
+    fn view(&self) -> String {
+        // delegate to UiModel's styled renderer
+        self.inner.render_full()
+    }
+}
+
+fn print_help() {
+    println!("van - interactive command completion preview tool");
+    println!();
+    println!("Usage:");
+    println!("  van [<command> [args...]]");
+    println!();
+    println!("Options:");
+    println!(
+        "  --hook <shell>   Output shell hook code for <shell>. Supported: bash, zsh, fish, nushell. If <shell> omitted, auto-detects from $SHELL and falls back to bash."
+    );
+    println!(
+        "  --exe <cmd>      Optional: override the executable string to embed in the hook (e.g. './target/debug/van')."
+    );
+    println!("  --help           Show this help message.");
+    println!();
+    println!("Description:");
+    println!(
+        "  When the hook is installed in your shell, your shell will invoke \"<exe> <command line>\" to produce completion candidates for the currently typed command line. For example, if you type 'jj commit' and press TAB, the shell will call '<exe> jj commit' to obtain completion items."
+    );
+    println!();
+    println!("Installation example (bash):");
+    println!("  van --hook bash > ~/.van_hook.sh");
+    println!("  source ~/.van_hook.sh");
+}
+
+// shell_single_quote safely single-quotes s for embedding in POSIX shells.
+fn shell_single_quote(s: &str) -> String {
+    if s.is_empty() {
+        return "''".to_string();
+    }
+    let escaped = s.replace('\'', "'\\''");
+    format!("'{escaped}'")
+}
+
+// parse_run_from_parts tries to find a '<exe> run' invocation in parts and reconstruct the run command string
+fn parse_run_from_parts(parts: &[String]) -> Option<String> {
+    // look for a pair where the second token is "run" and then collect valid run args after it
+    parts.windows(2).enumerate().find_map(|(i, pair)| {
+        if pair[1] != "run" {
+            return None;
+        }
+        let run_args: Vec<String> = parts
+            .iter()
+            .skip(i + 2)
+            .take_while(|t| {
+                if t.is_empty() || t.starts_with('-') {
+                    return false;
+                }
+                if Path::new(t).exists() {
+                    return true;
+                }
+                // Treat explicit paths or relative paths as run arguments
+                if t.contains('/') || t.starts_with("./") || t.starts_with("../") {
+                    return true;
+                }
+                false
+            })
+            .cloned()
+            .collect();
+
+        if run_args.is_empty() {
+            None
+        } else {
+            Some(format!("run {}", run_args.join(" ")))
+        }
+    })
+}
+
+// detect_exec_from_parent: attempts to determine the original executable string used to invoke this program.
+fn detect_exec_from_parent() -> String {
+    // default to argv[0]
+    let default_exe = env::args().next().unwrap_or_default();
+
+    // try to determine parent pid via ps -p <pid> -o ppid=
+    let pid = process::id();
+    let ppid_out = Command::new("ps")
+        .arg("-p")
+        .arg(pid.to_string())
+        .arg("-o")
+        .arg("ppid=")
+        .output();
+    if let Ok(out) = ppid_out {
+        if out.status.success() {
+            if let Ok(ppid_str) = String::from_utf8(out.stdout) {
+                if let Ok(ppid) = ppid_str.trim().parse::<u32>() {
+                    // platform-specific detection
+                    if cfg!(target_os = "linux") {
+                        // linux: try reading /proc/<ppid>/cmdline
+                        let proc_cmd = format!("/proc/{ppid}/cmdline");
+                        if let Ok(data) = fs::read(&proc_cmd) {
+                            // cmdline is NUL-separated; convert bytes to UTF-8 and split on NULs
+                            if let Ok(raw) = String::from_utf8(data) {
+                                let parts: Vec<String> = raw
+                                    .split('\0')
+                                    .filter(|s| !s.is_empty())
+                                    .map(|s| s.to_string())
+                                    .collect();
+                                if let Some(r) = parse_run_from_parts(&parts) {
+                                    return r;
+                                }
+                            }
+                        }
+                        // fallback: use ps -p <ppid> -o command=
+                        if let Some(cmdline) = get_ps_command(ppid) {
+                            let cmdline = cmdline.trim();
+                            if let Some(idx) = cmdline.find("run ") {
+                                let rest = cmdline[idx + "run ".len()..].trim();
+                                if !rest.is_empty() {
+                                    return format!("run {rest}");
+                                }
+                            }
+                        }
+                    } else if cfg!(target_os = "macos") {
+                        if let Some(cmdline) = get_ps_command(ppid) {
+                            let cmdline = cmdline.trim();
+                            if let Some(idx) = cmdline.find("run ") {
+                                let rest = cmdline[idx + "run ".len()..].trim();
+                                if !rest.is_empty() {
+                                    return format!("run {rest}");
+                                }
+                            }
+                        }
+                    } else if cfg!(target_os = "windows") {
+                        // windows: query via PowerShell
+                        let ps_cmd = format!(
+                            "Get-CimInstance Win32_Process -Filter \"ProcessId={ppid}\" | Select-Object -ExpandProperty CommandLine"
+                        );
+                        let out = Command::new("powershell")
+                            .arg("-NoProfile")
+                            .arg("-Command")
+                            .arg(ps_cmd)
+                            .output();
+                        if let Ok(o2) = out {
+                            if o2.status.success() {
+                                if let Ok(cmdline) = String::from_utf8(o2.stdout) {
+                                    let cmdline = cmdline.trim();
+                                    if !cmdline.is_empty() {
+                                        if let Some(idx) = cmdline.to_lowercase().find("run ") {
+                                            // preserve original-case remainder
+                                            let rest = cmdline[idx + "run ".len()..].trim();
+                                            if !rest.is_empty() {
+                                                return format!("run {rest}");
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    } else if let Some(cmdline) = get_ps_command(ppid) {
+                        let cmdline = cmdline.trim();
+                        if let Some(idx) = cmdline.find("run ") {
+                            let rest = cmdline[idx + "run ".len()..].trim();
+                            if !rest.is_empty() {
+                                return format!("run {rest}");
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    // If we didn't detect a wrapper like 'run', return the invocation actually used.
+    default_exe
+}
+
+// hook_script returns a shell-specific hook that will invoke exec_cmd to obtain completion items.
+fn hook_script(shell: &str, exec_cmd: &str) -> String {
+    let s = shell.to_lowercase();
+    // single-quoted exec_cmd for safe embedding
+    let esc = shell_single_quote(exec_cmd);
+    // Use template placeholders {{EXEC}} then replace to avoid Rust format! interpreting shell braces
+    match s.as_str() {
+        "bash" => {
+            let tpl = r#"# van bash hook
+EXEC_CMD={{EXEC}}
+_van_completion() {
+  local cur compword i
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  # build args: skip the command itself
+  local args=()
+  for ((i=1;i<${#COMP_WORDS[@]};i++)); do
+    args+=("${COMP_WORDS[i]}")
+  done
+  local IFS=$'\n'
+  local out
+  out=$(eval "$EXEC_CMD \"${args[@]}\"") || return
+  COMPREPLY=($(compgen -W "$out" -- "$cur"))
+}
+# Register _van_completion for all commands found in PATH (may be slow on very large PATHs)
+for cmd in $(compgen -c); do
+  complete -F _van_completion -o default "$cmd" 2>/dev/null || true
+done
+"#;
+            tpl.replace("{{EXEC}}", &esc)
+        }
+        "zsh" => {
+            let tpl = r#"# van zsh hook
+EXEC_CMD={{EXEC}}
+_van_completion() {
+  # words array contains all words; remove the command itself
+  local -a reply
+  reply=("${(@f)$(eval "$EXEC_CMD ${words[1,-1]}")}")
+  if [[ -n ${reply} ]]; then
+    compadd -- "${reply[@]}"
+  fi
+}
+# Register for all commands available in this shell
+for cmd in ${(k)commands}; do
+  compdef _van_completion $cmd 2>/dev/null || true
+done
+"#;
+            tpl.replace("{{EXEC}}", &esc)
+        }
+        "fish" => {
+            let tpl = r#"# van fish hook
+set -l VAN_EXEC {{EXEC}}
+function __van_completion
+  # get full commandline
+  set -l cmdline (commandline -cp)
+  # split into tokens by space (basic split)
+  set -l tokens (string split ' ' -- $cmdline)
+  # drop the leading command name
+  set -e tokens[1]
+  # call $VAN_EXEC with remaining tokens and print each candidate on its own line
+  for item in (eval "$VAN_EXEC $tokens")
+    printf "%s\n" "$item"
+  end
+end
+# Register completion for every executable in $PATH (may be slow)
+for p in (string split : $PATH)
+  for cmd in (ls $p 2>/dev/null)
+    complete -c $cmd -f -a '(__van_completion)'
+  end
+end
+"#;
+            tpl.replace("{{EXEC}}", &esc)
+        }
+        "nushell" | "nu" => {
+            let tpl = r#"# van nushell hook
+# Nushell custom completion support varies by version. The following provides a simple helper function
+# you can call from your nushell config to get completions for the current command line.
+# Example (in your config):
+#   def van-complete [] { {{EXEC_RAW}} ($nu.env.CMDLINE | split ' ' | skip 1) }
+# Consult nushell docs for registering completion functions in your version.
+"#;
+            // nushell example uses unquoted raw exec_cmd; provide raw (not shell-single-quoted) replacement
+            tpl.replace("{{EXEC_RAW}}", exec_cmd)
+        }
+        _ => {
+            let tpl = r#"# van (default=bash) hook
+EXEC_CMD={{EXEC}}
+_van_completion() {
+  local cur compword i
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  # build args: skip the command itself
+  local args=()
+  for ((i=1;i<${#COMP_WORDS[@]};i++)); do
+    args+=("${COMP_WORDS[i]}")
+  done
+  local IFS=$'\n'
+  local out
+  out=$(eval "$EXEC_CMD \"${args[@]}\"") || return
+  COMPREPLY=($(compgen -W "$out" -- "$cur"))
+}
+# Register _van_completion for all commands found in PATH (may be slow on very large PATHs)
+for cmd in $(compgen -c); do
+  complete -F _van_completion -o default "$cmd" 2>/dev/null || true
+done
+"#;
+            tpl.replace("{{EXEC}}", &esc)
+        }
+    }
+}
+
+fn detect_shell_from_env() -> String {
+    env::var("SHELL")
+        .ok()
+        .and_then(|p| {
+            Path::new(&p)
+                .file_name()
+                .and_then(|s| s.to_str().map(|s| s.to_string()))
+        })
+        .filter(|s| !s.is_empty())
+        .unwrap_or_else(|| "bash".to_string())
+}
+
+fn get_ps_command(ppid: u32) -> Option<String> {
+    let out = Command::new("ps")
+        .arg("-p")
+        .arg(ppid.to_string())
+        .arg("-o")
+        .arg("command=")
+        .output()
+        .ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    String::from_utf8(out.stdout)
+        .ok()
+        .map(|s| s.trim().to_string())
+}
+
+#[tokio::main]
+async fn main() {
+    let args: Vec<String> = env::args().skip(1).collect();
+    // simple flag handling for --help and --hook
+    if !args.is_empty() {
+        if args[0] == "--help" || args[0] == "-h" {
+            print_help();
+            return;
+        }
+        // support: --hook [shell] and optional --exe <cmd> (can appear before or after)
+        let mut hook_idx: isize = -1;
+        let mut exe_val = String::new();
+        let mut i = 0usize;
+        while i < args.len() {
+            if args[i] == "--hook" {
+                hook_idx = i as isize;
+                // if next arg exists and doesn't start with '-', treat as shell token
+                if i + 1 < args.len() && !args[i + 1].starts_with('-') {
+                    i += 1;
+                }
+                i += 1;
+                continue;
+            }
+            if args[i] == "--exe" && i + 1 < args.len() {
+                exe_val = args[i + 1].to_owned();
+                i += 2;
+                continue;
+            }
+            i += 1;
+        }
+        if hook_idx != -1 {
+            // determine shell param if provided
+            let shell = if (hook_idx as usize) + 1 < args.len()
+                && !args[(hook_idx as usize) + 1].starts_with('-')
+            {
+                args[(hook_idx as usize) + 1].to_owned()
+            } else {
+                detect_shell_from_env()
+            };
+            let mut exe_cmd = exe_val;
+            if exe_cmd.is_empty() {
+                exe_cmd = detect_exec_from_parent();
+            }
+            if exe_cmd.is_empty() {
+                exe_cmd = Path::new(&env::args().next().unwrap_or_default())
+                    .file_name()
+                    .and_then(|s| s.to_str())
+                    .unwrap_or("")
+                    .to_string();
+            }
+            print!("{}", hook_script(&shell, &exe_cmd));
+            return;
+        }
+    }
+
+    // If args provided, use non-interactive parsing similar to tooling (<cmd> args), else run interactive TUI
+    if !args.is_empty() {
+        match noninteractive_run(args) {
+            Ok(out) => {
+                if !out.is_empty() {
+                    println!("{out}");
+                }
+                process::exit(0);
+            }
+            Err(e) => {
+                eprintln!("{e}");
+                process::exit(2);
+            }
+        }
+    }
+
+    // Run interactive program
+    let builder = Program::<TeaAdapter>::builder();
+    let program = match builder.build() {
+        Ok(p) => p,
+        Err(e) => {
+            eprintln!("failed to build program: {e:?}");
+            process::exit(2);
+        }
+    };
+    match program.run().await {
+        Ok(_final_model) => {
+            // Interactive run does not print preview; simply exit successfully
+            process::exit(0);
+        }
+        Err(e) => {
+            eprintln!("program error: {e:?}");
+            process::exit(2);
+        }
+    }
+}

crates/src/ui.rs

···
+// UI module root: split implementation into focused submodules under `ui/`
+
+pub mod model;
+pub mod render;
+pub mod run;
+pub mod update;
+
+// Re-export commonly used symbols so existing call sites keep working (e.g. `crate::ui::initial_model`).
+pub use model::{ChooseItem, Model, initial_model, sort_items};
+pub use render::{
+    render_full, render_main_content, render_modeline, render_modeline_padded, render_preview_block,
+};
+pub use run::run;
+pub use update::handle_update;
+
+// Messages used by the update logic
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum Msg {
+    WindowSize { width: usize, height: usize },
+    KeyBackspace,
+    KeyEnter,
+    KeyEsc,
+    KeySpace,
+    Rune(char),
+    KeyUp,
+    KeyDown,
+}

crates/src/ui/model.rs

···
+use crate::ast;
+use bubbletea_widgets::Viewport;
+use std::collections::HashMap;
+
+// small constants reused by rendering code
+pub const PREVIEW_BLOCK_LINES: usize = 3;
+pub const MODELINE_LINES: usize = 1;
+pub const RESERVED_LINES: usize = PREVIEW_BLOCK_LINES + MODELINE_LINES;
+pub const DEFAULT_WIDTH: usize = 80;
+
+// Represent a choose item (flag or command)
+#[derive(Clone, Debug)]
+pub struct ChooseItem {
+    pub kind: String, // "cmd" or "flag"
+    pub label: String,
+    pub forms: Vec<String>,
+    pub flag_def: Option<ast::FlagDef>,
+    pub cmd_def: Option<ast::CommandDef>,
+    pub short: String,
+    pub depth: usize,
+}
+
+#[derive(Clone, Debug, Default)]
+pub struct Model {
+    pub items: Vec<ChooseItem>,
+    pub typed: String,
+    pub typed_raw: String,
+    pub ast: ast::Segment,
+    pub current: Option<ast::CommandDef>,
+    // simplified text input state
+    pub in_value_mode: bool,
+    pub pending_flag: Option<ast::FlagDef>,
+    pub pending_form: String,
+    pub pending_pos: bool,
+    pub pending_depth: usize,
+    pub pending_value: String,
+    pub err: String,
+    pub exit_preview: String,
+    pub def_cache: HashMap<String, ast::CommandDef>,
+    // pagination
+    pub page: usize,
+    pub per_page: usize,
+    pub screen_width: usize,
+    // viewport using bubbletea widgets
+    pub vp: Viewport,
+    // numeric mode baseline snapshot (indices into items) used by update/render logic
+    pub numeric_baseline: Option<Vec<usize>>,
+}
+
+// derive(Default) provides the default implementation
+
+pub fn initial_model(entries: Vec<(String, String)>) -> Model {
+    let mut m = Model::default();
+    if !entries.is_empty() {
+        let items: Vec<ChooseItem> = entries
+            .into_iter()
+            .map(|(name, short)| {
+                let label = name.clone();
+                let forms = vec![label.clone()];
+                ChooseItem {
+                    kind: "cmd".to_string(),
+                    label: label.clone(),
+                    forms,
+                    flag_def: None,
+                    cmd_def: None,
+                    short,
+                    depth: 0,
+                }
+            })
+            .collect();
+        m.items = sort_items(items);
+    }
+    m
+}
+
+impl Model {
+    // wrapper update that delegates to the update module
+    pub fn update(&mut self, msg: crate::ui::Msg) {
+        crate::ui::update::handle_update(self, msg);
+    }
+
+    pub fn mode(&self) -> String {
+        if !self.typed.is_empty() {
+            return format!("Typed: {}", self.typed);
+        }
+        if self.ast.stack.is_empty() {
+            return "van".to_string();
+        }
+        self.last_stack_name().unwrap_or_else(|| "van".to_string())
+    }
+
+    // helper: return last non-empty stack name if any
+    fn last_stack_name(&self) -> Option<String> {
+        self.ast
+            .stack
+            .iter()
+            .rev()
+            .find_map(|n| {
+                let name = n.name.trim();
+                if !name.is_empty() {
+                    Some(name.to_string())
+                } else {
+                    None
+                }
+            })
+    }
+
+    pub fn get_def_for_depth(&self, depth: usize) -> Option<ast::CommandDef> {
+        if depth >= self.ast.stack.len() {
+            return None;
+        }
+        let root_name = &self.ast.stack[0].name;
+        if root_name.is_empty() {
+            return None;
+        }
+        if let Some(root_def) = self.def_cache.get(root_name) {
+            if depth == 0 {
+                return Some(root_def.clone());
+            }
+            return self.find_subdef_from_root(root_def.clone(), depth);
+        }
+        // fallback: if current is set and depth == top, return current
+        if let Some(cur) = &self.current {
+            if depth == self.ast.stack.len().saturating_sub(1) {
+                return Some(cur.clone());
+            }
+        }
+        None
+    }
+
+    // helper: traverse subcommands from a root def to the requested depth
+    fn find_subdef_from_root(&self, mut cur: ast::CommandDef, depth: usize) -> Option<ast::CommandDef> {
+        for i in 1..=depth {
+            let name = &self.ast.stack[i].name;
+            if let Some(found) = cur
+                .subcommands
+                .iter()
+                .find(|sc| sc.name == *name || sc.aliases.iter().any(|a| a == name))
+            {
+                cur = found.clone();
+            } else {
+                return None;
+            }
+        }
+        Some(cur)
+    }
+
+    pub fn build_items_from_command(&mut self, cmd: &ast::CommandDef) {
+        // Preserve early-exit behavior
+        let mut items: Vec<ChooseItem> = vec![];
+        if cmd.name.is_empty() {
+            self.items = items;
+            return;
+        }
+
+        let top_depth = self.ast.stack.len().saturating_sub(1);
+        items.extend(self.collect_flag_items(top_depth));
+        items.extend(self.collect_subcommand_items(cmd, top_depth));
+
+        self.items = sort_items(items);
+        self.page = 0;
+    }
+
+    // helper: collect flags for every depth up to top_depth
+    fn collect_flag_items(&self, top_depth: usize) -> Vec<ChooseItem> {
+        let mut items: Vec<ChooseItem> = vec![];
+        for d in 0..=top_depth {
+            if let Some(def) = self.get_def_for_depth(d) {
+                for f in def.flags.iter() {
+                    let mut forms = vec![];
+                    let mut label_parts = vec![];
+                    if !f.longhand.is_empty() {
+                        forms.push(format!("--{}", f.longhand));
+                        label_parts.push(format!("--{}", f.longhand));
+                    }
+                    if !f.shorthand.is_empty() {
+                        forms.push(format!("-{}", f.shorthand));
+                        label_parts.push(format!("-{}", f.shorthand));
+                    }
+                    let mut label = label_parts.join(", ");
+                    if d < top_depth {
+                        label = format!("{}: {}", def.name, label);
+                    }
+                    items.push(ChooseItem {
+                        kind: "flag".to_string(),
+                        label,
+                        forms,
+                        flag_def: Some(f.clone()),
+                        cmd_def: None,
+                        short: String::new(),
+                        depth: d,
+                    });
+                }
+            }
+        }
+        items
+    }
+
+    // helper: collect subcommands for the provided cmd at top_depth
+    fn collect_subcommand_items(&self, cmd: &ast::CommandDef, top_depth: usize) -> Vec<ChooseItem> {
+        let mut items: Vec<ChooseItem> = vec![];
+        for sc in cmd.subcommands.iter() {
+            let mut forms = vec![sc.name.clone()];
+            for a in sc.aliases.iter() {
+                if !a.is_empty() {
+                    forms.push(a.clone());
+                }
+            }
+            items.push(ChooseItem {
+                kind: "cmd".to_string(),
+                label: sc.name.clone(),
+                forms,
+                flag_def: None,
+                cmd_def: Some(sc.clone()),
+                short: sc.short.clone(),
+                depth: top_depth,
+            });
+        }
+        items
+    }
+
+    // Render helper wrappers that forward to the render module to keep this file focused on state.
+    pub fn assigned_map(&self) -> HashMap<String, String> {
+        crate::ui::render::assigned_map(self)
+    }
+    pub fn render_visible_items(&self) -> Vec<ChooseItem> {
+        crate::ui::render::render_visible_items(self)
+    }
+    pub fn render_list_content(&self, visible: &[ChooseItem]) -> String {
+        crate::ui::render::render_list_content(self, visible)
+    }
+    pub fn render_preview(&self) -> String {
+        crate::ui::render::render_preview(self)
+    }
+    pub fn render_preview_block(&self) -> Vec<String> {
+        crate::ui::render::render_preview_block(self)
+    }
+    pub fn render_main_content(&self) -> String {
+        crate::ui::render::render_main_content(self)
+    }
+    pub fn render_full(&self) -> String {
+        crate::ui::render::render_full(self)
+    }
+
+    // New helper to get labels of current items (replaces stored `root_list`)
+    pub fn items_labels(&self) -> impl Iterator<Item = &str> {
+        self.items.iter().map(|it| it.label.as_str())
+    }
+}
+
+pub fn sort_items(items: Vec<ChooseItem>) -> Vec<ChooseItem> {
+    let mut flags: Vec<ChooseItem> = items
+        .iter()
+        .filter(|it| it.kind == "flag")
+        .cloned()
+        .collect();
+    let mut cmds: Vec<ChooseItem> = items.into_iter().filter(|it| it.kind == "cmd").collect();
+    flags.sort_by(|a, b| {
+        a.label
+            .len()
+            .cmp(&b.label.len())
+            .then(a.label.cmp(&b.label))
+    });
+    cmds.sort_by(|a, b| {
+        a.label
+            .len()
+            .cmp(&b.label.len())
+            .then(a.label.cmp(&b.label))
+    });
+    flags.extend(cmds);
+    flags
+}
+
+pub fn leading_hyphen_count(s: &str) -> usize {
+    s.chars().take_while(|&r| r == '-').count()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::ast::{Segment, CommandDef, FlagDef};
+
+    // Revert to direct Segment::new_empty usage where needed.
+    // (Full test bodies retained elsewhere in file; only type rename matters.)
+    #[test]
+    fn test_mode_and_initial_model() {
+        let entries = vec![("git".to_string(), "git client".to_string())];
+        let mut m = initial_model(entries);
+        let labels: Vec<&str> = m.items_labels().collect();
+        assert_eq!(labels.len(), 1);
+        assert_eq!(labels[0], "git");
+        assert_eq!(m.mode(), "van");
+        m.typed = "abcd".to_string();
+        assert_eq!(m.mode(), "Typed: abcd");
+    }
+
+    #[test]
+    fn test_space_enters_value_mode_and_esc_cancels() {
+        let mut m = initial_model(vec![]);
+        assert!(!m.in_value_mode);
+        m.update(crate::ui::Msg::KeySpace);
+        assert!(m.in_value_mode);
+        assert!(m.pending_pos);
+        m.update(crate::ui::Msg::KeyEsc);
+        assert!(!m.in_value_mode);
+        assert!(!m.pending_pos);
+    }
+
+    #[test]
+    fn test_backspace_trims_typed() {
+        let mut m = initial_model(vec![]);
+        m.typed = "ab".to_string();
+        m.typed_raw = "ab".to_string();
+        m.update(crate::ui::Msg::KeyBackspace);
+        assert_eq!(m.typed, "a");
+        assert_eq!(m.typed_raw, "a");
+    }
+
+    #[test]
+    fn test_assigned_map_initial_prefixes() {
+        let mut m = initial_model(vec![]);
+        m.items = vec![
+            ChooseItem {
+                kind: "flag".to_string(),
+                label: "--long".to_string(),
+                forms: vec!["--long".to_string()],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+            ChooseItem {
+                kind: "flag".to_string(),
+                label: "-s".to_string(),
+                forms: vec!["-s".to_string()],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+            ChooseItem {
+                kind: "cmd".to_string(),
+                label: "cmd".to_string(),
+                forms: vec!["cmd".to_string()],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+        ];
+        m.typed_raw = "".to_string();
+        let assigned = m.assigned_map();
+        assert_eq!(assigned.get("--long").cloned().unwrap_or_default(), "-");
+        assert_eq!(assigned.get("-s").cloned().unwrap_or_default(), "-");
+        assert!(assigned.get("cmd").cloned().unwrap_or_default() != "");
+    }
+
+    #[test]
+    fn test_sort_items_ordering() {
+        let items = vec![
+            ChooseItem {
+                kind: "cmd".to_string(),
+                label: "zzz".to_string(),
+                forms: vec![],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+            ChooseItem {
+                kind: "flag".to_string(),
+                label: "a".to_string(),
+                forms: vec![],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+            ChooseItem {
+                kind: "flag".to_string(),
+                label: "bb".to_string(),
+                forms: vec![],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+            ChooseItem {
+                kind: "cmd".to_string(),
+                label: "x".to_string(),
+                forms: vec![],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+        ];
+        let s = sort_items(items);
+        assert_eq!(s.len(), 4);
+        assert_eq!(s[0].kind, "flag");
+        assert_eq!(s[1].kind, "flag");
+        assert_eq!(s[0].label, "a");
+        assert_eq!(s[1].label, "bb");
+    }
+
+    #[test]
+    fn test_build_items_from_command_includes_flags_and_subcommands() {
+        let mut m = initial_model(vec![]);
+        let def = CommandDef {
+            name: "root".to_string(),
+            short: "rootcmd".to_string(),
+            aliases: vec![],
+            flags: vec![FlagDef {
+                longhand: "verbose".to_string(),
+                shorthand: "v".to_string(),
+                usage: "v".to_string(),
+                requires_value: false,
+            }],
+            subcommands: vec![CommandDef {
+                name: "sub".to_string(),
+                short: "subcmd".to_string(),
+                aliases: vec![],
+                flags: vec![],
+                subcommands: vec![],
+            }],
+        };
+        m.ast = Segment::new_empty("root");
+        m.current = Some(def.clone());
+        m.build_items_from_command(&def);
+        assert!(m.items.len() >= 2);
+        let mut has_flag = false;
+        let mut has_cmd = false;
+        for it in &m.items {
+            if it.kind == "flag" {
+                has_flag = true
+            }
+            if it.kind == "cmd" {
+                has_cmd = true
+            }
+        }
+        assert!(has_flag && has_cmd);
+    }
+
+    #[test]
+    fn test_flag_add_remove_toggle_and_render() {
+        let mut m = initial_model(vec![]);
+        let def = CommandDef {
+            name: "root".to_string(),
+            short: "rootcmd".to_string(),
+            aliases: vec![],
+            flags: vec![
+                FlagDef {
+                    longhand: "message".to_string(),
+                    shorthand: "m".to_string(),
+                    usage: "msg".to_string(),
+                    requires_value: true,
+                },
+                FlagDef {
+                    longhand: "verbose".to_string(),
+                    shorthand: "v".to_string(),
+                    usage: "v".to_string(),
+                    requires_value: false,
+                },
+            ],
+            subcommands: vec![],
+        };
+        m.ast = Segment::new_empty("root");
+        m.current = Some(def.clone());
+        m.build_items_from_command(&def);
+        m.ast.add_flag_to_depth(0, "--verbose", "");
+        assert_eq!(m.ast.render_preview(), "root --verbose");
+        let removed = m.ast.remove_flag_from_depth("--verbose", 0);
+        assert!(removed);
+        assert_eq!(m.ast.render_preview(), "root");
+        m.ast.add_flag_to_depth(0, "--message", "hello");
+        assert_eq!(m.ast.render_preview(), "root --message hello");
+        assert!(m.ast.remove_flag_from_depth("--message", 0));
+        assert_eq!(m.ast.render_preview(), "root");
+    }
+
+    #[test]
+    fn test_add_positionals_and_undo_to_root() {
+        let mut m = initial_model(vec![]);
+        m.ast = Segment::new_empty("root");
+        m.ast.push_subcommand("sub");
+        m.ast.add_flag_to_depth(0, "--rootflag", "");
+        m.ast.add_positional("a");
+        m.ast.add_positional("b");
+        assert_eq!(m.ast.render_preview(), "root --rootflag sub a b");
+        m.ast.remove_last();
+        assert_eq!(m.ast.render_preview(), "root --rootflag sub a");
+        m.ast.remove_last();
+        assert_eq!(m.ast.render_preview(), "root --rootflag sub");
+        m.ast.remove_last();
+        assert_eq!(m.ast.render_preview(), "root sub");
+        m.ast.remove_last();
+        assert_eq!(m.ast.render_preview(), "root");
+    }
+
+    #[test]
+    fn test_parent_and_subcommand_flags_preview_and_undo() {
+        let mut m = initial_model(vec![]);
+        m.ast = Segment::new_empty("root");
+        m.ast.push_subcommand("sub");
+        m.ast.add_flag_to_depth(0, "--rootflag", "");
+        m.ast.add_flag_to_depth(1, "--subflag", "");
+        assert_eq!(m.ast.render_preview(), "root --rootflag sub --subflag");
+        m.ast.remove_last();
+        assert_eq!(m.ast.render_preview(), "root --rootflag sub");
+        m.ast.remove_last();
+        assert_eq!(m.ast.render_preview(), "root sub");
+        m.ast.remove_last();
+        assert_eq!(m.ast.render_preview(), "root");
+    }
+
+    #[test]
+    fn test_acekey_selection_pushes_subcommand_and_flag_requires_value() {
+        let mut m = initial_model(vec![]);
+        m.ast = Segment::new_empty("root");
+        m.ast.root = "root".to_string();
+        m.ast.stack[0].name = "root".to_string();
+        let subdef = CommandDef {
+            name: "sub".to_string(),
+            short: "subcmd".to_string(),
+            aliases: vec![],
+            flags: vec![],
+            subcommands: vec![],
+        };
+        m.items = vec![ChooseItem {
+            kind: "cmd".to_string(),
+            label: "sub".to_string(),
+            forms: vec!["sub".to_string()],
+            flag_def: None,
+            cmd_def: Some(subdef.clone()),
+            short: String::new(),
+            depth: 0,
+        }];
+        m.update(crate::ui::Msg::Rune('s'));
+        assert!(m.ast.top().is_some() && m.ast.top().unwrap().name == "sub");
+
+        // flag requiring value case
+        let mut m2 = initial_model(vec![]);
+        m2.ast = Segment::new_empty("root");
+        m2.ast.root = "root".to_string();
+        m2.ast.stack[0].name = "root".to_string();
+        let fd = FlagDef {
+            longhand: "message".to_string(),
+            shorthand: "m".to_string(),
+            usage: String::new(),
+            requires_value: true,
+        };
+        m2.items = vec![ChooseItem {
+            kind: "flag".to_string(),
+            label: "--message".to_string(),
+            forms: vec!["--message".to_string()],
+            flag_def: Some(fd.clone()),
+            cmd_def: None,
+            short: String::new(),
+            depth: 0,
+        }];
+        m2.update(crate::ui::Msg::Rune('-'));
+        m2.update(crate::ui::Msg::Rune('m'));
+        assert!(
+            m2.in_value_mode
+                && m2.pending_flag.is_some()
+                && m2.pending_flag.as_ref().unwrap().longhand == "message"
+        );
+    }
+
+    #[test]
+    fn test_acekey_disambiguation_interaction() {
+        let mut m = initial_model(vec![]);
+        let mut root = CommandDef {
+            name: "root".to_string(),
+            short: "rootcmd".to_string(),
+            aliases: vec![],
+            flags: vec![],
+            subcommands: vec![],
+        };
+        let s1 = CommandDef {
+            name: "serve".to_string(),
+            short: "serve".to_string(),
+            aliases: vec![],
+            flags: vec![],
+            subcommands: vec![],
+        };
+        let s2 = CommandDef {
+            name: "setup".to_string(),
+            short: "setup".to_string(),
+            aliases: vec![],
+            flags: vec![],
+            subcommands: vec![],
+        };
+        root.subcommands = vec![s1.clone(), s2.clone()];
+        m.ast = Segment::new_empty("root");
+        m.ast.root = "root".to_string();
+        m.ast.stack[0].name = "root".to_string();
+        m.current = Some(root.clone());
+        m.def_cache.insert("root".to_string(), root.clone());
+        m.build_items_from_command(&root);
+        m.update(crate::ui::Msg::Rune('s'));
+        assert!(m.render_visible_items().len() >= 2);
+        m.update(crate::ui::Msg::Rune('r'));
+        assert!(m.ast.top().is_some() && m.ast.top().unwrap().name == "serve");
+    }
+
+    #[test]
+    fn test_command_then_subcommand_then_flags_then_undo_and_subcommand_visible_again() {
+        let mut m = initial_model(vec![]);
+        let sub = CommandDef {
+            name: "sub".to_string(),
+            short: "subcmd".to_string(),
+            aliases: vec![],
+            flags: vec![],
+            subcommands: vec![],
+        };
+        let root = CommandDef {
+            name: "root".to_string(),
+            short: "rootcmd".to_string(),
+            aliases: vec![],
+            flags: vec![],
+            subcommands: vec![sub.clone()],
+        };
+        m.ast = Segment::new_empty("root");
+        m.ast.root = "root".to_string();
+        m.ast.stack[0].name = "root".to_string();
+        m.current = Some(root.clone());
+        m.def_cache.insert("root".to_string(), root.clone());
+        m.build_items_from_command(&root);
+        m.update(crate::ui::Msg::Rune('s'));
+        assert!(m.ast.top().is_some() && m.ast.top().unwrap().name == "sub");
+        m.ast.add_flag_to_depth(0, "--rootflag", "");
+        m.ast.add_flag_to_depth(1, "--subflag", "");
+        assert_eq!(m.ast.render_preview(), "root --rootflag sub --subflag");
+        m.ast.remove_last();
+        assert_eq!(m.ast.render_preview(), "root --rootflag sub");
+        m.ast.remove_last();
+        assert_eq!(m.ast.render_preview(), "root sub");
+        m.ast.remove_last();
+        assert_eq!(m.ast.render_preview(), "root");
+        m.current = Some(root.clone());
+        m.build_items_from_command(&root);
+        let mut found = false;
+        for it in &m.items {
+            if it.kind == "cmd" && it.label == "sub" {
+                found = true;
+                break;
+            }
+        }
+        assert!(found);
+    }
+
+    #[test]
+    fn test_undo_from_subcommand_to_root_restores_root_items() {
+        let mut m = initial_model(vec![]);
+        let init_def = CommandDef {
+            name: "init".to_string(),
+            short: "init".to_string(),
+            aliases: vec![],
+            flags: vec![],
+            subcommands: vec![],
+        };
+        let root = CommandDef {
+            name: "jj".to_string(),
+            short: "jjcmd".to_string(),
+            aliases: vec![],
+            flags: vec![],
+            subcommands: vec![init_def.clone()],
+        };
+        m.def_cache.insert("jj".to_string(), root.clone());
+        m.ast = Segment::new_empty("jj");
+        m.ast.root = "jj".to_string();
+        m.ast.stack[0].name = "jj".to_string();
+        m.current = Some(root.clone());
+        m.build_items_from_command(&root);
+        m.items = vec![ChooseItem {
+            kind: "cmd".to_string(),
+            label: "init".to_string(),
+            forms: vec!["init".to_string()],
+            flag_def: None,
+            cmd_def: Some(init_def.clone()),
+            short: String::new(),
+            depth: 0,
+        }];
+        m.update(crate::ui::Msg::Rune('i'));
+        assert!(m.ast.top().is_some() && m.ast.top().unwrap().name == "init");
+        assert!(m.current.is_some() && m.current.as_ref().unwrap().name == "init");
+        m.update(crate::ui::Msg::KeyBackspace);
+        assert!(m.current.is_some() && m.current.as_ref().unwrap().name == "jj");
+        let mut found = false;
+        for it in &m.items {
+            if it.kind == "cmd" && it.label == "init" {
+                found = true;
+                break;
+            }
+        }
+        assert!(found);
+    }
+
+    #[test]
+    fn test_flag_value_confirm_adds_flag_to_depth() {
+        let mut m = initial_model(vec![]);
+        m.ast = Segment::new_empty("root");
+        m.ast.root = "root".to_string();
+        m.ast.stack[0].name = "root".to_string();
+        let fd = FlagDef {
+            longhand: "message".to_string(),
+            shorthand: "m".to_string(),
+            usage: String::new(),
+            requires_value: true,
+        };
+        m.items = vec![ChooseItem {
+            kind: "flag".to_string(),
+            label: "--message".to_string(),
+            forms: vec!["--message".to_string()],
+            flag_def: Some(fd.clone()),
+            cmd_def: None,
+            short: String::new(),
+            depth: 0,
+        }];
+        m.update(crate::ui::Msg::Rune('-'));
+        m.update(crate::ui::Msg::Rune('m'));
+        assert!(m.in_value_mode && m.pending_flag.is_some());
+        m.pending_value = "hello".to_string();
+        m.update(crate::ui::Msg::KeyEnter);
+        let top = &m.ast.stack[0];
+        assert!(
+            top.flags.len() == 1
+                && top.flags[0].form == "--message"
+                && top.flags[0].value == "hello"
+        );
+    }
+
+    #[test]
+    fn test_lifo_order_multiple_depths() {
+        let mut astree = Segment::new_empty("root");
+        astree.push_subcommand("sub");
+        astree.add_flag_to_depth(0, "--r", "");
+        astree.add_positional("p1");
+        astree.add_flag_to_depth(1, "--s", "v");
+        astree.remove_last();
+        assert_eq!(astree.render_preview(), "root --r sub p1");
+        astree.remove_last();
+        assert_eq!(astree.render_preview(), "root --r sub");
+        astree.remove_last();
+        assert_eq!(astree.render_preview(), "root sub");
+        astree.remove_last();
+        assert_eq!(astree.render_preview(), "root");
+    }
+
+    #[test]
+    fn test_build_items_shows_parent_flag_label() {
+        let mut m = initial_model(vec![]);
+        let mut root = CommandDef {
+            name: "root".to_string(),
+            short: String::new(),
+            aliases: vec![],
+            flags: vec![FlagDef {
+                longhand: "verbose".to_string(),
+                shorthand: "v".to_string(),
+                usage: "v".to_string(),
+                requires_value: false,
+            }],
+            subcommands: vec![],
+        };
+        let sub = CommandDef {
+            name: "sub".to_string(),
+            short: "subcmd".to_string(),
+            aliases: vec![],
+            flags: vec![],
+            subcommands: vec![],
+        };
+        root.subcommands = vec![sub.clone()];
+        m.ast = Segment::new_empty("root");
+        m.ast.root = "root".to_string();
+        m.ast.stack[0].name = "root".to_string();
+        m.current = Some(sub.clone());
+        m.ast.push_subcommand("sub");
+        m.def_cache.insert("root".to_string(), root.clone());
+        m.build_items_from_command(&sub);
+        let mut header_found = false;
+        for it in &m.items {
+            if it.kind == "flag" && it.depth < m.ast.stack.len() - 1
+                && it.label.starts_with("root:") {
+                    header_found = true;
+                    break;
+                }
+        }
+        assert!(header_found);
+    }
+
+    #[test]
+    fn test_assign_ace_keys_hyphen_and_collapse_edgecases() {
+        {
+            let els = ["jjui", "ju"];
+            let res = crate::acekey::assign_ace_keys(
+                &els.iter().map(|s| s.to_string()).collect::<Vec<String>>(),
+                "ju",
+            );
+            assert!(res.is_some());
+            let v = res.unwrap();
+            assert_eq!(v.len(), 1);
+            assert_eq!(v[0].index, 1);
+            assert_eq!(v[0].prefix, "");
+        }
+        {
+            let els = ["--long", "-s"];
+            let res = crate::acekey::assign_ace_keys(
+                &els.iter().map(|s| s.to_string()).collect::<Vec<String>>(),
+                "-",
+            );
+            assert!(res.is_some());
+            let v = res.unwrap();
+            assert_eq!(v.len(), 2);
+            for a in v.iter() {
+                assert!(!a.prefix.is_empty());
+            }
+        }
+        {
+            let els = ["a-b", "ab"];
+            let res = crate::acekey::assign_ace_keys(
+                &els.iter().map(|s| s.to_string()).collect::<Vec<String>>(),
+                "a",
+            );
+            assert!(res.is_some());
+            let v = res.unwrap();
+            for a in v.iter() {
+                assert!(
+                    !(a.prefix == "-" && a.index < els.len() && els[a.index].chars().count() > 1)
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn test_window_size_pagination_and_nav() {
+        let mut m = initial_model(vec![]);
+        let mut items = vec![];
+        for _ in 0..10 {
+            items.push(ChooseItem {
+                kind: "cmd".to_string(),
+                label: "cmd".to_string(),
+                forms: vec!["cmd".to_string()],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            });
+        }
+        m.items = items;
+        m.update(crate::ui::Msg::WindowSize {
+            width: 80,
+            height: 10,
+        });
+        // per_page should be height minus reserved non-main lines (preview + modeline) = 4
+        assert_eq!(m.per_page, (10usize).saturating_sub(4));
+        assert_eq!(m.page, 0);
+        m.update(crate::ui::Msg::KeyDown);
+        assert!(m.page != 0);
+    }
+
+    #[test]
+    fn test_mode_various_states() {
+        let mut m = initial_model(vec![]);
+        assert_eq!(m.mode(), "van");
+        m.typed = "x".to_string();
+        assert_eq!(m.mode(), "Typed: x");
+        m.typed.clear();
+        m.ast = Segment::new_empty("root");
+        m.ast.stack[0].name = "root".to_string();
+        assert_eq!(m.mode(), "root");
+        m.ast.push_subcommand("sub");
+        m.ast.stack[1].name = "sub".to_string();
+        assert_eq!(m.mode(), "sub");
+    }
+
+    #[test]
+    fn test_numeric_selection_selects_flag_by_index() {
+        let mut m = initial_model(vec![]);
+        m.ast = Segment::new_empty("root");
+        m.ast.root = "root".to_string();
+        m.ast.stack[0].name = "root".to_string();
+        let fd = FlagDef {
+            longhand: "flag1".to_string(),
+            shorthand: "f".to_string(),
+            usage: String::new(),
+            requires_value: false,
+        };
+        m.items = vec![ChooseItem {
+            kind: "flag".to_string(),
+            label: "--flag1".to_string(),
+            forms: vec!["--flag1".to_string(), "-f".to_string()],
+            flag_def: Some(fd.clone()),
+            cmd_def: None,
+            short: String::new(),
+            depth: 0,
+        }];
+        m.update(crate::ui::Msg::Rune('1'));
+        let top = &m.ast.stack[0];
+        assert!(top.flags.len() == 1 && top.flags[0].form == "--flag1");
+    }
+
+    #[test]
+    fn test_numeric_selection_selects_command_by_index() {
+        let mut m = initial_model(vec![]);
+        let sub = CommandDef {
+            name: "sub".to_string(),
+            short: "subcmd".to_string(),
+            aliases: vec![],
+            flags: vec![],
+            subcommands: vec![],
+        };
+        let root = CommandDef {
+            name: "root".to_string(),
+            short: String::new(),
+            aliases: vec![],
+            flags: vec![],
+            subcommands: vec![sub.clone()],
+        };
+        m.ast = Segment::new_empty("root");
+        m.ast.root = "root".to_string();
+        m.ast.stack[0].name = "root".to_string();
+        m.current = Some(root.clone());
+        m.def_cache.insert("root".to_string(), root.clone());
+        m.items = vec![ChooseItem {
+            kind: "cmd".to_string(),
+            label: "sub".to_string(),
+            forms: vec!["sub".to_string()],
+            flag_def: None,
+            cmd_def: Some(sub.clone()),
+            short: String::new(),
+            depth: 0,
+        }];
+        m.update(crate::ui::Msg::Rune('1'));
+        assert!(m.ast.top().is_some() && m.ast.top().unwrap().name == "sub");
+    }
+
+    #[test]
+    fn test_numeric_multi_digit_selects_correct_flag_by_index() {
+        let mut m = initial_model(vec![]);
+        m.ast = Segment::new_empty("root");
+        m.ast.root = "root".to_string();
+        m.ast.stack[0].name = "root".to_string();
+        let mut items = vec![];
+        for i in 0..30 {
+            if i == 11 {
+                let fd = FlagDef {
+                    longhand: "f12".to_string(),
+                    shorthand: String::new(),
+                    usage: String::new(),
+                    requires_value: false,
+                };
+                items.push(ChooseItem {
+                    kind: "flag".to_string(),
+                    label: "--f12".to_string(),
+                    forms: vec!["--f12".to_string()],
+                    flag_def: Some(fd.clone()),
+                    cmd_def: None,
+                    short: String::new(),
+                    depth: 0,
+                });
+            } else {
+                let s = (i + 1).to_string();
+                items.push(ChooseItem {
+                    kind: "cmd".to_string(),
+                    label: format!("cmd{s}"),
+                    forms: vec![format!("cmd{}", s)],
+                    flag_def: None,
+                    cmd_def: None,
+                    short: String::new(),
+                    depth: 0,
+                });
+            }
+        }
+        m.items = items;
+        m.update(crate::ui::Msg::Rune('1'));
+        m.update(crate::ui::Msg::Rune('2'));
+        let top = &m.ast.stack[0];
+        assert!(!top.flags.is_empty() && top.flags.iter().any(|f| f.form == "--f12"));
+    }
+
+    #[test]
+    fn test_ls_command_shows_flags_and_subcommands_model() {
+        // Ensure commands named `ls` produce visible items (flags or subcommands)
+        let mut m = initial_model(vec![]);
+        let init_sub = CommandDef {
+            name: "list".to_string(),
+            short: "listsub".to_string(),
+            aliases: vec![],
+            flags: vec![],
+            subcommands: vec![],
+        };
+        let root = CommandDef {
+            name: "ls".to_string(),
+            short: "lscmd".to_string(),
+            aliases: vec![],
+            flags: vec![FlagDef {
+                longhand: "all".to_string(),
+                shorthand: "a".to_string(),
+                usage: "show all".to_string(),
+                requires_value: false,
+            }],
+            subcommands: vec![init_sub.clone()],
+        };
+        // populate cache and set current
+        m.def_cache.insert("ls".to_string(), root.clone());
+        m.ast = Segment::new_empty("ls");
+        m.ast.root = "ls".to_string();
+        m.ast.stack[0].name = "ls".to_string();
+        m.current = Some(root.clone());
+        m.build_items_from_command(&root);
+        // must contain at least one flag or one subcommand
+        let mut has_flag = false;
+        let mut has_cmd = false;
+        for it in &m.items {
+            if it.kind == "flag" {
+                has_flag = true
+            }
+            if it.kind == "cmd" {
+                has_cmd = true
+            }
+        }
+        assert!(
+            has_flag || has_cmd,
+            "expected ls to expose flags or subcommands but none found"
+        );
+    }
+
+    #[test]
+    fn test_all_ambiguous_choices_selectable_via_acekeys() {
+        let subs = vec!["chcpu", "chgrp", "chroot", "chpasswd"];
+        let mut root = CommandDef {
+            name: "root".to_string(),
+            short: "rootcmd".to_string(),
+            aliases: vec![],
+            flags: vec![],
+            subcommands: vec![],
+        };
+        let mut scs = vec![];
+        for s in &subs {
+            scs.push(CommandDef {
+                name: s.to_string(),
+                short: s.to_string(),
+                aliases: vec![],
+                flags: vec![],
+                subcommands: vec![],
+            });
+        }
+        root.subcommands = scs.clone();
+
+        for target in subs.iter().copied() {
+            let mut m = initial_model(vec![]);
+            m.ast = Segment::new_empty("root");
+            m.ast.root = "root".to_string();
+            m.ast.stack[0].name = "root".to_string();
+            m.current = Some(root.clone());
+            m.def_cache.insert("root".to_string(), root.clone());
+            m.build_items_from_command(&root);
+
+            // type the ambiguous initial rune
+            m.update(crate::ui::Msg::Rune('c'));
+            let visible = m.render_visible_items();
+            assert!(visible.len() >= 2, "expected ambiguity after typing 'c'");
+
+            // find assigned disambiguator for the target form
+            let assigned = m.assigned_map();
+            let assigned_pref = assigned
+                .get(target)
+                .cloned()
+                .unwrap_or_default();
+            assert!(
+                !assigned_pref.is_empty(),
+                "expected assigned disambiguator for {target}"
+            );
+
+            // simulate typing the disambiguator rune(s)
+            if assigned_pref == m.typed_raw {
+                // assigned disambiguator is the same as the left unit; type the
+                // next rune from the form (e.g., 'chpasswd' -> type 'h') to
+                // disambiguate further.
+                let next = target.chars().nth(1).expect("form must have at least 2 chars");
+                m.update(crate::ui::Msg::Rune(next));
+            } else {
+                for ch in assigned_pref.chars() {
+                    m.update(crate::ui::Msg::Rune(ch));
+                }
+            }
+
+            // after typing the disambiguator, the target should be selected (pushed as subcommand)
+            assert!(
+                m.ast.top().is_some(),
+                "expected a subcommand selected for {target}"
+            );
+            assert_eq!(m.ast.top().unwrap().name, *target);
+        }
+    }
+
+    #[test]
+    fn test_prompt_disambiguation_progression() {
+        // Use the exact list from vic/prompt.md (includes non-`c` items to ensure filtering occurs)
+        let items = vec!["hello","test","cp","cal","cat","cut","chsh","code","comm","curl","cargo","chcpu","chgrp","chmod","chown","cksum","cfdisk","chroot","csplit","carapace","chpasswd","cargo-fmt","coredumpctl","cargo-clippy"];
+        let forms: Vec<String> = items.iter().map(|s| s.to_string()).collect();
+
+        // Helper that attempts to drive selection of a target by repeatedly applying
+        // assign_ace_keys using assigned prefixes first, then contiguous characters.
+        fn drive_to_target(forms: &[String], target: &str) -> bool {
+            let target_idx = forms.iter().position(|f| f == target).expect("form must exist");
+            let mut typed = String::new();
+            // start by typing the left-unit (first ace-rune)
+            if let Some(first) = target.chars().next() {
+                typed.push(first);
+            }
+
+            eprintln!(">>>> driving to target {target}");
+            
+
+            // loop: try assigned prefix first, then contiguous chars of target
+            let max_iters = 32;
+            for _ in 0..max_iters {
+                if let Some(res) = crate::acekey::assign_ace_keys(forms, &typed) {
+                    // If target is directly selected (empty prefix), we're done
+                    if res.iter().any(|r| r.index == target_idx && r.prefix.is_empty()) {
+                        eprintln!("<<<< reached target {target}");
+                        return true;
+                    }
+                    // If an assigned prefix was produced for the target, append it and retry
+                    if let Some(a) = res.iter().find(|r| r.index == target_idx) {
+                        if !a.prefix.is_empty() {
+                            typed.push_str(&a.prefix);
+                            eprintln!("  typing assigned prefix {}, now '{}'", a.prefix, typed);
+                            continue;
+                        }
+                    }
+                }
+
+                // fallback: append next contiguous rune from the target
+                let cur_len = typed.chars().count();
+                if cur_len < target.chars().count() {
+                    if let Some(ch) = target.chars().nth(cur_len) {
+                        typed.push(ch);
+                        eprintln!("  typing contiguous char {}, now '{}'", ch, typed);
+                        continue;
+                    }
+                }
+                break;
+            }
+            false
+        }
+
+        for item in &items {
+            assert!(drive_to_target(&forms, item), "expected to be able to reach item {item} via disambiguation progression");
+        }
+
+
+    }
+
+
+}

crates/src/ui/render.rs

···
+// Render module split into focused submodules to reduce file size and compiler warnings.
+
+pub mod decorate;
+pub mod full;
+pub mod list;
+pub mod modeline;
+pub mod preview;
+pub mod styles;
+pub mod util;
+
+pub use decorate::tested_string;
+pub use full::render_full;
+pub use list::{assigned_map, render_list_content, render_main_content, render_visible_items};
+pub use modeline::{render_modeline, render_modeline_padded};
+pub use preview::{render_preview, render_preview_block};

crates/src/ui/render/decorate.rs

···
+use crate::ui::render::styles::{STYLE_ACE, STYLE_TYPED};
+use std::collections::HashMap;
+
+fn collect_candidate_runes(form: &str) -> (Vec<char>, Vec<usize>) {
+    let mut runes = Vec::new();
+    let mut positions = Vec::new();
+    for (i, ch) in form.char_indices() {
+        if crate::acekey::is_ace_rune(ch) {
+            runes.push(ch);
+            positions.push(i);
+        }
+    }
+    (runes, positions)
+}
+
+pub fn decorate_form(form: &str, typed: &str, assigned_seq: String) -> String {
+    let (candidate_runes, candidate_pos) = collect_candidate_runes(form);
+
+    let mut assigned_pos: Vec<usize> = Vec::new();
+    if !assigned_seq.is_empty() {
+        let mut ci = 0usize;
+        let assigned_lower = assigned_seq.to_lowercase();
+        for ar_rune in assigned_lower.chars() {
+            let mut found: Option<usize> = None;
+            // Always start searching from the current candidate index. We want the
+            // AceKey positions returned by assign_ace_keys to be respected even
+            // when the user has already typed; otherwise the ace-character may
+            // be skipped and not highlighted.
+            let start = ci;
+            for (j, ch) in candidate_runes.iter().enumerate().skip(start) {
+                if ch.eq_ignore_ascii_case(&ar_rune) {
+                    found = Some(j);
+                    ci = j + 1;
+                    break;
+                }
+            }
+            if let Some(idx) = found {
+                assigned_pos.push(idx);
+            } else {
+                assigned_pos.clear();
+                break;
+            }
+        }
+    }
+
+    let typed_len = if !typed.is_empty() && !assigned_seq.is_empty() {
+        if crate::ui::model::leading_hyphen_count(typed) >= 2
+            && crate::ui::model::leading_hyphen_count(&assigned_seq)
+                < crate::ui::model::leading_hyphen_count(typed)
+        {
+            0usize
+        } else {
+            let leftmost_unit_runes = if form.starts_with("--") {
+                2usize
+            } else {
+                1usize
+            };
+            let typed_lower = typed.to_lowercase();
+            let typed_no_hyph = typed_lower.trim_start_matches('-');
+            let mut tr: Vec<char> = crate::ui::render::tested_string(typed_no_hyph)
+                .chars()
+                .collect();
+            if leftmost_unit_runes > tr.len() {
+                tr.clear();
+            } else {
+                tr = tr.into_iter().skip(leftmost_unit_runes).collect();
+            }
+            let assigned_lower = assigned_seq.to_lowercase();
+            let ar: Vec<char> = crate::ui::render::tested_string(&assigned_lower)
+                .chars()
+                .collect();
+            let mut i = 0usize;
+            while i < tr.len() && i < ar.len() && tr[i] == ar[i] {
+                i += 1;
+            }
+            i
+        }
+    } else {
+        0usize
+    };
+
+    let mut out = String::with_capacity(form.len());
+    let assigned_index_set: HashMap<usize, usize> = assigned_pos
+        .iter()
+        .cloned()
+        .enumerate()
+        .map(|(ord, idx)| (idx, ord))
+        .collect();
+
+    for (byte_idx, ch) in form.char_indices() {
+        if crate::acekey::is_ace_rune(ch) {
+            let cidx_opt = candidate_pos.iter().position(|&p| p == byte_idx);
+            if let Some(cidx) = cidx_opt {
+                if let Some(&ord) = assigned_index_set.get(&cidx) {
+                    if typed.is_empty() {
+                        if ord == 0 {
+                            out.push_str(&STYLE_ACE.render(&ch.to_string()));
+                        } else {
+                            out.push(ch);
+                        }
+                        continue;
+                    }
+                    if ord < typed_len {
+                        out.push_str(&STYLE_TYPED.render(&ch.to_string()));
+                        continue;
+                    }
+                    if ord == typed_len {
+                        out.push_str(&STYLE_ACE.render(&ch.to_string()));
+                        continue;
+                    }
+                    out.push(ch);
+                } else {
+                    out.push(ch);
+                }
+            } else {
+                out.push(ch);
+            }
+        } else {
+            out.push(ch);
+        }
+    }
+    out
+}
+
+pub fn tested_string(s: &str) -> String {
+    s.to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn acekey_highlight_when_typed_keeps_magenta() {
+        // when assigned_seq contains the ace char, decorate_form must render that
+        // character using STYLE_ACE, even if the user has already typed it.
+        let assigned = "w".to_string();
+        let out = decorate_form("w", "w", assigned.clone());
+        assert!(out.contains(&crate::ui::render::styles::STYLE_ACE.render("w")));
+        let out2 = decorate_form("wc", "w", assigned);
+        assert!(out2.contains(&crate::ui::render::styles::STYLE_ACE.render("w")));
+    }
+}

crates/src/ui/render/full.rs

···
+use crate::ui::model::Model;
+
+pub fn render_full(m: &Model) -> String {
+    let mut lines = m.render_preview_block();
+    lines.extend(m.render_main_content().lines().map(str::to_string));
+    let first_line = crate::ui::render::modeline::render_modeline_padded(m)
+        .lines()
+        .next()
+        .unwrap_or("")
+        .to_string();
+    lines.push(first_line);
+    lines.join("\n")
+}
+
+#[cfg(test)]
+mod tests {
+    use regex::Regex;
+
+    // helper to strip ANSI CSI sequences from rendered output for assertions
+    fn strip_ansi(s: &str) -> String {
+        let re = Regex::new(r"\x1b\[[0-9;?]*[ -/]*[@-~]").unwrap();
+        re.replace_all(s, "").to_string()
+    }
+
+    #[test]
+    fn render_full_matches_dimensions() {
+        // sample sizes to validate behavior across different terminal shapes
+        let sizes = [(80usize, 24usize), (100usize, 10usize), (40usize, 20usize)];
+
+        for (w, h) in sizes.iter().cloned() {
+            // populate 50 entries so the viewport/pagination logic is exercised
+            let mut entries: Vec<(String, String)> = Vec::new();
+            for i in 0..50 {
+                let name = format!("cmd{}", i + 1);
+                let desc = format!("description {}", i + 1);
+                entries.push((name, desc));
+            }
+            let mut m = crate::ui::initial_model(entries);
+
+            // simulate WindowSize message
+            m.update(crate::ui::Msg::WindowSize {
+                width: w,
+                height: h,
+            });
+
+            // render the full view
+            let out = m.render_full();
+
+            // strip ANSI escape sequences so we can measure plain character dimensions
+            let stripped = strip_ansi(&out);
+
+            // collect lines and assert the rendered height matches requested height
+            let lines: Vec<&str> = stripped.lines().collect();
+            assert_eq!(
+                lines.len(),
+                h,
+                "height mismatch for {}x{}: got {} lines\n<<output>>\n{}",
+                w,
+                h,
+                lines.len(),
+                stripped
+            );
+
+            // each line must have exactly `w` characters after stripping ANSI
+            for (idx, line) in lines.iter().enumerate() {
+                let lw = line.chars().count();
+                assert_eq!(
+                    lw, w,
+                    "width mismatch at line {idx} for {w}x{h}: got {lw} chars\nline: `{line}`\n<<output>>\n{stripped}"
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn modeline_is_last_line_and_exact_width() {
+        let (w, h) = (80usize, 24usize);
+        let entries: Vec<(String, String)> = Vec::new();
+        let mut m = crate::ui::initial_model(entries);
+        m.update(crate::ui::Msg::WindowSize {
+            width: w,
+            height: h,
+        });
+        let out = m.render_full();
+        let stripped = strip_ansi(&out);
+        let lines: Vec<&str> = stripped.lines().collect();
+        assert!(!lines.is_empty(), "no lines rendered");
+        let last = *lines.last().unwrap();
+        assert_eq!(
+            last.chars().count(),
+            w,
+            "modeline width mismatch: got {} expected {}\n<<output>>\n{}",
+            last.chars().count(),
+            w,
+            stripped
+        );
+        let modeline = crate::ui::render_modeline_padded(&m);
+        let modeline_stripped = strip_ansi(&modeline);
+        let modeline_first = modeline_stripped.lines().next().unwrap_or("");
+        assert_eq!(
+            last, modeline_first,
+            "modeline content mismatch:\n<<output>>\n{stripped}"
+        );
+    }
+
+    #[test]
+    fn preview_box_first_three_lines() {
+        let (w, h) = (80usize, 24usize);
+        let entries: Vec<(String, String)> = Vec::new();
+        let mut m = crate::ui::initial_model(entries);
+        m.update(crate::ui::Msg::WindowSize {
+            width: w,
+            height: h,
+        });
+        let out = m.render_full();
+        let stripped = strip_ansi(&out);
+        let lines: Vec<&str> = stripped.lines().collect();
+        assert!(lines.len() >= 3, "not enough lines to contain preview box");
+        let preview_block = m.render_preview_block();
+        let helper_combined = preview_block.join("\n");
+        let helper_stripped = strip_ansi(&helper_combined);
+        let helper_lines: Vec<&str> = helper_stripped.lines().collect();
+        for i in 0..3 {
+            assert_eq!(
+                lines[i], helper_lines[i],
+                "preview box line {i} mismatch:\n<<output>>\n{stripped}"
+            );
+        }
+    }
+
+    #[test]
+    fn main_content_matches_between_preview_and_modeline() {
+        let (w, h) = (80usize, 24usize);
+        let entries: Vec<(String, String)> = Vec::new();
+        let mut m = crate::ui::initial_model(entries);
+        m.update(crate::ui::Msg::WindowSize {
+            width: w,
+            height: h,
+        });
+        let full = m.render_full();
+        let full_stripped = strip_ansi(&full);
+        let mut full_lines: Vec<&str> = full_stripped.lines().collect();
+        assert!(
+            full_lines.len() >= 4,
+            "not enough lines in full render to extract main content"
+        );
+        let preview_block = m.render_preview_block();
+        let preview_combined = preview_block.join("\n");
+        let preview_stripped = strip_ansi(&preview_combined);
+        let preview_height = preview_stripped.lines().count();
+        let middle_from_full = if full_lines.len() > preview_height + 1 {
+            full_lines
+                .drain(preview_height..full_lines.len() - 1)
+                .collect::<Vec<&str>>()
+        } else {
+            vec![]
+        };
+        let main = m.render_main_content();
+        let main_stripped = strip_ansi(&main);
+        let main_lines: Vec<&str> = main_stripped.lines().collect();
+        let mut left = middle_from_full;
+        while left.last().is_some_and(|s| s.trim().is_empty()) {
+            left.pop();
+        }
+        let mut right = main_lines;
+        while right.last().is_some_and(|s| s.trim().is_empty()) {
+            right.pop();
+        }
+        assert_eq!(left.len(), right.len(), "main content line count mismatch");
+        for (i, (a, b)) in left.iter().zip(right.iter()).enumerate() {
+            assert_eq!(a, b, "main content line {i} mismatch");
+        }
+    }
+
+    #[test]
+    fn main_content_uses_viewport() {
+        let (w, h) = (30usize, 10usize);
+        let mut m = crate::ui::initial_model(Vec::new());
+        let mut items: Vec<crate::ui::ChooseItem> = Vec::new();
+        for i in 0..40 {
+            let name = format!("cmd{}", i + 1);
+            items.push(crate::ui::ChooseItem {
+                kind: "cmd".to_string(),
+                label: name.clone(),
+                forms: vec![name.clone()],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            });
+        }
+        m.items = items;
+        m.update(crate::ui::Msg::WindowSize {
+            width: w,
+            height: h,
+        });
+        let full = m.render_full();
+        let stripped = strip_ansi(&full);
+        let lines: Vec<&str> = stripped.lines().collect();
+        assert_eq!(
+            lines.len(),
+            h,
+            "full render height mismatch: got {} expected {}\n<<output>>\n{}",
+            lines.len(),
+            h,
+            stripped
+        );
+        for (idx, line) in lines.iter().enumerate() {
+            let lw = line.chars().count();
+            assert_eq!(
+                lw, w,
+                "width mismatch at line {idx}: got {lw} expected {w}\nline: `{line}`\n<<output>>\n{stripped}"
+            );
+        }
+        let modeline = crate::ui::render_modeline_padded(&m);
+        let modeline_stripped = strip_ansi(&modeline);
+        let total_pages = if m.per_page == 0 {
+            1
+        } else {
+            m.items.len().div_ceil(m.per_page)
+        };
+        let expect_pag = format!("Page 1/{total_pages}");
+        assert!(
+            modeline_stripped.contains(&expect_pag),
+            "modeline does not show pagination\n<<output>>\n{full}"
+        );
+        let preview_block = m.render_preview_block();
+        let preview_height = preview_block.len();
+        let middle: Vec<&str> = if lines.len() > preview_height + 1 {
+            lines[preview_height..lines.len() - 1].to_vec()
+        } else {
+            Vec::new()
+        };
+        let expected_per = m.per_page;
+        assert_eq!(middle.len(), expected_per, "main content page size mismatch: got {middle_len} expected {expected_per}\n<<output>>\n{stripped}", middle_len = middle.len());
+        for (i, line) in middle.iter().enumerate().take(expected_per) {
+            let expect = format!("cmd{}", i + 1);
+            assert!(line.contains(&expect), "expected main content line {i} to contain `{expect}` but got `{line}`\n<<output>>\n{stripped}");
+        }
+    }
+}

crates/src/ui/render/list.rs

···
+use crate::acekey::assign_ace_keys;
+use crate::ui::model::leading_hyphen_count;
+use crate::ui::model::{ChooseItem, DEFAULT_WIDTH, Model};
+use crate::ui::render::decorate::decorate_form;
+use crate::ui::render::styles::{STYLE_DESC, STYLE_LABEL, STYLE_LINENUM};
+use crate::ui::render::util::normalize_and_pad;
+use std::collections::{HashMap, HashSet};
+
+// Collect forms in baseline order for a numeric baseline subset
+fn baseline_subset_forms(nb: &[usize], items: &[ChooseItem]) -> Vec<String> {
+    let mut subset_forms = Vec::new();
+    for &idx in nb.iter() {
+        if let Some(it) = items.get(idx) {
+            for f in &it.forms {
+                subset_forms.push(f.clone());
+            }
+        }
+    }
+    subset_forms
+}
+
+// Given a list of forms and the typed buffer, produce the ace-key assignment map
+fn assign_prefix_map(forms: &[String], typed_raw: &str) -> HashMap<String, String> {
+    let assignments = assign_ace_keys(forms, typed_raw);
+    let mut assigned: HashMap<String, String> = forms.iter().cloned().map(|f| (f, String::new())).collect();
+    if let Some(asg) = assignments {
+        for a in asg.iter() {
+            if a.index < forms.len() {
+                assigned.insert(forms[a.index].clone(), a.prefix.clone());
+            }
+        }
+    }
+    assigned
+}
+
+pub fn assigned_map(m: &Model) -> HashMap<String, String> {
+    // When Numeric mode is active, compute assignments only for the numeric-filtered subset.
+    if let Some(nb) = &m.numeric_baseline {
+        // Build forms for the baseline subset in the same order as baseline
+        let subset_forms = baseline_subset_forms(nb, &m.items);
+        return assign_prefix_map(&subset_forms, &m.typed_raw);
+    }
+
+    // Default: use all items
+    let forms: Vec<String> = m
+        .items
+        .iter()
+        .flat_map(|it| it.forms.iter().cloned())
+        .collect();
+    assign_prefix_map(&forms, &m.typed_raw)
+}
+
+fn render_visible_items_numeric(nb: &[usize], m: &Model) -> Vec<ChooseItem> {
+    // typed_raw should be digits
+    if !m.typed_raw.is_empty() && m.typed_raw.chars().all(|c| c.is_ascii_digit()) {
+        let matches: Vec<usize> = nb
+            .iter()
+            .filter_map(|&orig_idx| {
+                let num = (orig_idx + 1).to_string();
+                if num.starts_with(&m.typed_raw) {
+                    Some(orig_idx)
+                } else {
+                    None
+                }
+            })
+            .collect();
+        matches
+            .into_iter()
+            .filter_map(|i| m.items.get(i).cloned())
+            .collect()
+    } else {
+        // no typed digits yet: return full baseline items in baseline order
+        nb.iter().filter_map(|&i| m.items.get(i).cloned()).collect()
+    }
+}
+
+fn render_visible_items_alpha(m: &Model) -> Vec<ChooseItem> {
+    let forms: Vec<String> = m
+        .items
+        .iter()
+        .flat_map(|it| it.forms.iter().cloned())
+        .collect();
+    let assignments = assign_ace_keys(&forms, &m.typed_raw);
+    let mut visible_forms: HashSet<String> = HashSet::new();
+
+    if let Some(asg) = assignments {
+        for a in asg.iter() {
+            if a.index < forms.len() {
+                visible_forms.insert(forms[a.index].clone());
+            }
+        }
+    } else if m.typed.is_empty() {
+        visible_forms = forms.into_iter().collect();
+    }
+
+    m.items
+        .iter()
+        .filter(|it| it.forms.iter().any(|f| visible_forms.contains(f)))
+        .cloned()
+        .collect()
+}
+
+pub fn render_visible_items(m: &Model) -> Vec<ChooseItem> {
+    if let Some(nb) = &m.numeric_baseline {
+        render_visible_items_numeric(nb, m)
+    } else {
+        render_visible_items_alpha(m)
+    }
+}
+
+fn compute_gutter_width(total: usize) -> usize {
+    if total == 0 {
+        return 1;
+    }
+    let gw = ((total as f64).log10().floor() as usize) + 1;
+    usize::max(gw, 3)
+}
+
+fn format_num_str(num: usize, gutter_width: usize) -> String {
+    format!("{:>1$} │ ", num, gutter_width)
+}
+
+// Build baseline numbers and order when numeric baseline is active
+fn build_baseline(m: &Model) -> Option<(Vec<String>, Vec<usize>)> {
+    if let Some(nb) = &m.numeric_baseline {
+        let v: Vec<String> = nb.iter().map(|&orig_idx| (orig_idx + 1).to_string()).collect();
+        if v.is_empty() {
+            None
+        } else {
+            Some((v, nb.clone()))
+        }
+    } else {
+        None
+    }
+}
+
+// Given a baseline order and typed buffer, produce positions to render (vis_pos, orig_idx)
+fn collect_numeric_positions(nb_order: &[usize], typed: &str) -> Vec<(usize, usize)> {
+    let mut positions = Vec::new();
+    if !typed.is_empty() && typed.chars().all(|c| c.is_ascii_digit()) {
+        for (vis_pos, &orig_idx) in nb_order.iter().enumerate() {
+            let num = (orig_idx + 1).to_string();
+            if num.starts_with(typed) {
+                positions.push((vis_pos, orig_idx));
+            }
+        }
+    } else {
+        for (vis_pos, &orig_idx) in nb_order.iter().enumerate() {
+            positions.push((vis_pos, orig_idx));
+        }
+    }
+    positions
+}
+
+fn build_label(it: &ChooseItem, assigned: &HashMap<String, String>, t_hyph: usize, m: &Model) -> Option<String> {
+    let mut parts = Vec::new();
+    for f in &it.forms {
+        if t_hyph >= 2 && leading_hyphen_count(f) < t_hyph {
+            continue;
+        }
+        parts.push(decorate_form(f, &m.typed_raw, assigned.get(f).cloned().unwrap_or_default()));
+    }
+    if parts.is_empty() {
+        None
+    } else {
+        Some(parts.join(", "))
+    }
+}
+
+fn flag_suffix(it: &ChooseItem, m: &Model) -> Vec<String> {
+    let mut suffix = Vec::new();
+    if let Some(fd) = &it.flag_def {
+        if fd.requires_value {
+            let mut placeholder = "VALUE".to_string();
+            if !fd.longhand.is_empty() {
+                placeholder = fd.longhand.to_uppercase();
+            } else if !fd.shorthand.is_empty() {
+                placeholder = fd.shorthand.to_uppercase();
+            }
+            suffix.push(STYLE_DESC.render(&format!(" {placeholder}")));
+            suffix.push(STYLE_DESC.render("  "));
+        } else {
+            suffix.push(STYLE_DESC.render("  "));
+        }
+        if !fd.usage.is_empty() {
+            suffix.push(STYLE_DESC.render(&fd.usage));
+        }
+        let top_depth = m.ast.stack.len().saturating_sub(1);
+        if it.depth < top_depth && it.depth < m.ast.stack.len() {
+            let origin = &m.ast.stack[it.depth].name;
+            if !origin.is_empty() {
+                suffix.push(STYLE_DESC.render(&format!(" (from {origin})")));
+            }
+        }
+    }
+    suffix
+}
+
+fn cmd_suffix(it: &ChooseItem) -> Option<String> {
+    let short_ref: &str = if !it.short.is_empty() {
+        it.short.as_str()
+    } else if let Some(cd) = &it.cmd_def {
+        cd.short.as_str()
+    } else {
+        ""
+    };
+    if short_ref.is_empty() {
+        None
+    } else {
+        Some(STYLE_DESC.render(&format!("  {short_ref}")))
+    }
+}
+
+// Render a single ChooseItem into a line (without trailing newline). Returns None when nothing should be rendered.
+fn render_item_line(
+    it: &ChooseItem,
+    assigned: &HashMap<String, String>,
+    t_hyph: usize,
+    num_str: String,
+    m: &Model,
+) -> Option<String> {
+    let label = build_label(it, assigned, t_hyph, m)?;
+    let mut line_pieces: Vec<String> = vec![STYLE_LINENUM.render(&num_str), STYLE_LABEL.render(&label)];
+    line_pieces.extend(flag_suffix(it, m));
+    if let Some(s) = cmd_suffix(it) {
+        line_pieces.push(s);
+    }
+    Some(line_pieces.join(""))
+}
+
+// Render when numeric baseline is active
+fn render_numeric_content(m: &Model, assigned: &HashMap<String, String>, bs: &Vec<String>, nb_order: &Vec<usize>, t_hyph: usize, gutter_width: usize) -> String {
+    let mut b = String::new();
+    let positions = collect_numeric_positions(nb_order, &m.typed_raw);
+    if positions.is_empty() {
+        return b;
+    }
+    let total_positions = positions.len();
+    let per_page = if m.per_page == 0 { total_positions } else { m.per_page };
+    let start_pos = m.page.saturating_mul(per_page);
+    let end_pos = usize::min(start_pos + per_page, total_positions);
+
+    for pos_idx in start_pos..end_pos {
+        let (vis_pos, orig_idx) = positions[pos_idx];
+        if let Some(it) = m.items.get(orig_idx) {
+            let num_str = if vis_pos < bs.len() {
+                format!("{:>1$} │ ", bs[vis_pos], gutter_width)
+            } else {
+                format_num_str(orig_idx + 1, gutter_width)
+            };
+            if let Some(line) = render_item_line(it, assigned, t_hyph, num_str, m) {
+                b.push_str(&line);
+                b.push('\n');
+            }
+        }
+    }
+    b
+}
+
+// Default non-numeric render path
+fn render_default_content(m: &Model, visible: &[ChooseItem], baseline_num_strs: &Option<Vec<String>>, assigned: &HashMap<String, String>, t_hyph: usize, gutter_width: usize, start: usize, end: usize) -> String {
+    let mut b = String::new();
+    for (idx, it) in visible.iter().enumerate().skip(start).take(end.saturating_sub(start)) {
+        let num_str = if let Some(bs) = baseline_num_strs {
+            if idx < bs.len() {
+                format!("{:>1$} │ ", bs[idx], gutter_width)
+            } else {
+                format_num_str(idx + 1, gutter_width)
+            }
+        } else {
+            format_num_str(idx + 1, gutter_width)
+        };
+
+        if let Some(line) = render_item_line(it, assigned, t_hyph, num_str, m) {
+            b.push_str(&line);
+            b.push('\n');
+        }
+    }
+    b
+}
+
+pub fn render_list_content(m: &Model, visible: &[ChooseItem]) -> String {
+    let assigned = m.assigned_map();
+
+    // If numeric baseline is active, compute total from baseline for gutter width
+    let (total, per) = if let Some(nb) = &m.numeric_baseline {
+        // total for gutter calculation should reflect the largest original index number
+        // use the maximum orig_idx+1 so gutter width does not shrink during numeric filtering
+        let max_num = nb.iter().map(|&i| i + 1).max().unwrap_or(0);
+        let t = max_num;
+        (t, if m.per_page == 0 { t } else { m.per_page })
+    } else {
+        let t = visible.len();
+        (t, if m.per_page == 0 { t } else { m.per_page })
+    };
+
+    if per == 0 {
+        return String::new();
+    }
+    let start = m.page.saturating_mul(per);
+    let end = usize::min(start + per, total);
+    let t_hyph = leading_hyphen_count(&m.typed_raw);
+    let gutter_width = compute_gutter_width(total);
+
+    let baseline = build_baseline(m);
+
+    // Numeric baseline path
+    if let Some((bs, nb_order)) = baseline.as_ref() {
+        return render_numeric_content(m, &assigned, bs, &nb_order, t_hyph, gutter_width);
+    }
+
+    // Default non-numeric path
+    render_default_content(m, visible, &baseline.map(|(v, _)| v), &assigned, t_hyph, gutter_width, start, end)
+}
+
+pub fn render_main_content(m: &Model) -> String {
+    let total_width = if m.screen_width > 0 {
+        m.screen_width
+    } else {
+        DEFAULT_WIDTH
+    };
+
+    if m.in_value_mode {
+        let lines: Vec<String> = vec![
+            lipgloss::Style::new().bold(true).render("Value input: ") + &m.pending_value,
+            lipgloss::Style::new()
+                .faint(true)
+                .render("Press Enter to confirm, Esc to cancel"),
+        ];
+        let per = if m.per_page == 0 { lines.len() } else { m.per_page };
+        return normalize_and_pad(lines, total_width, per);
+    }
+
+    let visible = m.render_visible_items();
+    let list_block = m.render_list_content(&visible);
+    let lines: Vec<String> = list_block.lines().map(|s| s.to_string()).collect();
+    let per = if m.per_page == 0 {
+        lines.len()
+    } else {
+        m.per_page
+    };
+    // Ensure we return exactly `per` lines each normalized to the terminal width.
+    normalize_and_pad(lines, total_width, per)
+}
+
+#[cfg(test)]
+mod tests {
+    use regex::Regex;
+
+    fn strip_ansi(s: &str) -> String {
+        let re = Regex::new(r"\x1b\[[0-9;?]*[ -/]*[@-~]").unwrap();
+        re.replace_all(s, "").to_string()
+    }
+
+    #[test]
+    fn render_assigned_map_initial_prefixes_shows_labels() {
+        let mut m = crate::ui::initial_model(vec![]);
+        m.items = vec![
+            crate::ui::ChooseItem {
+                kind: "flag".to_string(),
+                label: "--long".to_string(),
+                forms: vec!["--long".to_string()],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+            crate::ui::ChooseItem {
+                kind: "flag".to_string(),
+                label: "-s".to_string(),
+                forms: vec!["-s".to_string()],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+            crate::ui::ChooseItem {
+                kind: "cmd".to_string(),
+                label: "cmd".to_string(),
+                forms: vec!["cmd".to_string()],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+        ];
+        m.typed_raw = "".to_string();
+        let visible = m.render_visible_items();
+        let list = m.render_list_content(&visible);
+        let stripped = strip_ansi(&list);
+        assert!(stripped.contains("--long"));
+        assert!(stripped.contains("-s"));
+        assert!(stripped.contains("cmd"));
+    }
+
+    #[test]
+    fn render_build_items_from_command_includes_flags_and_subcommands() {
+        let mut m = crate::ui::initial_model(vec![]);
+        let def = crate::ast::CommandDef {
+            name: "root".to_string(),
+            short: "rootcmd".to_string(),
+            aliases: vec![],
+            flags: vec![crate::ast::FlagDef {
+                longhand: "verbose".to_string(),
+                shorthand: "v".to_string(),
+                usage: "v".to_string(),
+                requires_value: false,
+            }],
+            subcommands: vec![crate::ast::CommandDef {
+                name: "sub".to_string(),
+                short: "subcmd".to_string(),
+                aliases: vec![],
+                flags: vec![],
+                subcommands: vec![],
+            }],
+        };
+        m.ast = crate::ast::Segment::new_empty("root");
+        m.current = Some(def.clone());
+        m.build_items_from_command(&def);
+        let visible = m.render_visible_items();
+        let list = m.render_list_content(&visible);
+        let stripped = strip_ansi(&list);
+        assert!(stripped.contains("--verbose") || stripped.contains("-v"));
+        assert!(stripped.contains("sub"));
+    }
+
+    #[test]
+    fn render_flag_add_remove_toggle_and_render() {
+        let mut m = crate::ui::initial_model(vec![]);
+        let def = crate::ast::CommandDef {
+            name: "root".to_string(),
+            short: "rootcmd".to_string(),
+            aliases: vec![],
+            flags: vec![
+                crate::ast::FlagDef {
+                    longhand: "message".to_string(),
+                    shorthand: "m".to_string(),
+                    usage: "msg".to_string(),
+                    requires_value: true,
+                },
+                crate::ast::FlagDef {
+                    longhand: "verbose".to_string(),
+                    shorthand: "v".to_string(),
+                    usage: "v".to_string(),
+                    requires_value: false,
+                },
+            ],
+            subcommands: vec![],
+        };
+        m.ast = crate::ast::Segment::new_empty("root");
+        m.current = Some(def.clone());
+        m.build_items_from_command(&def);
+        m.ast.add_flag_to_depth(0, "--verbose", "");
+        let preview = m.render_preview();
+        let stripped = strip_ansi(&preview);
+        assert!(stripped.contains("--verbose"));
+        let removed = m.ast.remove_flag_from_depth("--verbose", 0);
+        assert!(removed);
+        let preview2 = m.render_preview();
+        let stripped2 = strip_ansi(&preview2);
+        assert!(!stripped2.contains("--verbose"));
+        m.ast.add_flag_to_depth(0, "--message", "hello");
+        let preview3 = m.render_preview();
+        assert!(strip_ansi(&preview3).contains("--message"));
+    }
+
+    #[test]
+    fn render_add_positionals_and_undo_to_root() {
+        let mut m = crate::ui::initial_model(vec![]);
+        m.ast = crate::ast::Segment::new_empty("root");
+        m.ast.push_subcommand("sub");
+        m.ast.add_flag_to_depth(0, "--rootflag", "");
+        m.ast.add_positional("a");
+        m.ast.add_positional("b");
+        let p = strip_ansi(&m.render_preview());
+        assert_eq!(p, "root --rootflag sub a b");
+        m.ast.remove_last();
+        assert_eq!(strip_ansi(&m.render_preview()), "root --rootflag sub a");
+        m.ast.remove_last();
+        assert_eq!(strip_ansi(&m.render_preview()), "root --rootflag sub");
+        m.ast.remove_last();
+        assert_eq!(strip_ansi(&m.render_preview()), "root sub");
+        m.ast.remove_last();
+        assert_eq!(strip_ansi(&m.render_preview()).trim(), "root");
+    }
+
+    #[test]
+    fn render_parent_and_subcommand_flags_preview_and_undo() {
+        let mut m = crate::ui::initial_model(vec![]);
+        m.ast = crate::ast::Segment::new_empty("root");
+        m.ast.push_subcommand("sub");
+        m.ast.add_flag_to_depth(0, "--rootflag", "");
+        m.ast.add_flag_to_depth(1, "--subflag", "");
+        assert!(
+            strip_ansi(&m.render_preview()).contains("--rootflag")
+                && strip_ansi(&m.render_preview()).contains("--subflag")
+        );
+        m.ast.remove_last();
+        assert!(!strip_ansi(&m.render_preview()).contains("--subflag"));
+    }
+
+    #[test]
+    fn render_typed_buffer_preserved_and_highlighted_on_ambiguity() {
+        let mut m = crate::ui::initial_model(vec![]);
+        m.items = vec![
+            crate::ui::ChooseItem {
+                kind: "cmd".to_string(),
+                label: "chcpu".to_string(),
+                forms: vec!["chcpu".to_string()],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+            crate::ui::ChooseItem {
+                kind: "cmd".to_string(),
+                label: "chgrp".to_string(),
+                forms: vec!["chgrp".to_string()],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+            crate::ui::ChooseItem {
+                kind: "cmd".to_string(),
+                label: "chroot".to_string(),
+                forms: vec!["chroot".to_string()],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+            crate::ui::ChooseItem {
+                kind: "cmd".to_string(),
+                label: "chpasswd".to_string(),
+                forms: vec!["chpasswd".to_string()],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+        ];
+        m.typed_raw = "c".to_string();
+
+        // filtered visible items should include multiple candidates (ambiguity)
+        let visible = m.render_visible_items();
+        assert!(
+            visible.len() >= 2,
+            "expected at least two visible candidates when typed 'c'"
+        );
+
+        // assigned disambiguators should be present for the visible forms
+        let assigned = m.assigned_map();
+        for it in &visible {
+            for f in &it.forms {
+                let pref = assigned.get(f).cloned().unwrap_or_default();
+                assert!(!pref.is_empty(), "expected disambiguator for form {f}");
+            }
+        }
+
+        // typed buffer should be preserved in the model mode
+        // model.mode() reflects the normalized typed buffer (`typed`), ensure it's set
+        m.typed = "c".to_string();
+        assert_eq!(m.mode(), "Typed: c");
+
+        // ACE highlight must still be present in the rendered output for at least
+        // one of the assigned disambiguators (ANSI-coded). We don't require it
+        // to be 'c' specifically because assign_ace_keys may choose a different
+        // disambiguator rune in the filtered set.
+        let list = m.render_list_content(&visible);
+        let mut found_ace = false;
+        for (_k, v) in assigned.iter() {
+            if !v.is_empty() {
+                let styled = crate::ui::render::styles::STYLE_ACE.render(v);
+                if list.contains(&styled) {
+                    found_ace = true;
+                    break;
+                }
+            }
+        }
+        assert!(
+            found_ace,
+            "expected at least one ACE-styled disambiguator present in rendered list"
+        );
+    }
+}

crates/src/ui/render/modeline.rs

···
+use crate::ui::model::{ChooseItem, DEFAULT_WIDTH, Model};
+use crate::ui::render::styles::STYLE_MODELINE;
+use lipgloss::Color;
+
+pub fn render_modeline(m: &Model, inner_max: usize, mode: &str, visible: &[ChooseItem]) -> String {
+    // Build styled pairs, compute plain widths, and fit pagination into available space.
+    let total = visible.len();
+    let per = if m.per_page == 0 { total } else { m.per_page };
+    let total_pages = if per > 0 { total.div_ceil(per) } else { 1 };
+
+    // prepare inner styles without padding so spacing is under our control
+    let inner_style = STYLE_MODELINE.clone().padding(0, 0, 0, 0);
+    let key_style = STYLE_MODELINE
+        .clone()
+        .foreground(Color::from_rgb(238, 0, 238))
+        .bold(true)
+        .padding(0, 0, 0, 0);
+    let desc_style = STYLE_MODELINE.clone().padding(0, 0, 0, 0);
+    let pag_style = STYLE_MODELINE.clone().faint(true).padding(0, 0, 0, 0);
+
+    // key/description pairs definitions
+    let pairs_def: Vec<(&str, &str)> =
+        vec![("␣", "arg"), ("⏎", "run"), ("⌫", "undo"), ("⎋", "quit")];
+
+    // Build rendered pairs and their plain widths in one pass
+    let pairs: Vec<(String, usize)> = pairs_def
+        .iter()
+        .map(|(k, d)| {
+            let plain_len = d.chars().count() + 1 + k.chars().count();
+            let rendered = format!(
+                "{}{}{}",
+                desc_style.render(d),
+                inner_style.render(":"),
+                key_style.render(k)
+            );
+            (rendered, plain_len)
+        })
+        .collect();
+
+    let pair_sep_rendered = inner_style.render("  ");
+    let pair_sep_width = 2usize;
+
+    // build pagination plain and styled
+    let mut pag_plain = String::new();
+    let mut pag_rendered = String::new();
+    if total_pages > 1 {
+        pag_plain = format!("Page {}/{} ↑/↓", m.page + 1, total_pages);
+        let arrows = format!("{}/{}", key_style.render("↑"), key_style.render("↓"));
+        let pag_unstyled = format!("Page {}/{} ", m.page + 1, total_pages);
+        pag_rendered = pag_style.render(&format!("{pag_unstyled}{arrows}"));
+    }
+    let mut pag_width = pag_plain.chars().count();
+
+    // Start with all pairs and compute left width
+    let mut pairs_count = pairs.len();
+    let mut left_joined_rendered = if pairs_count > 0 {
+        pairs
+            .iter()
+            .map(|(r, _)| r.clone())
+            .collect::<Vec<_>>()
+            .join(&pair_sep_rendered)
+    } else {
+        String::new()
+    };
+    let mut left_width = if pairs_count > 0 {
+        pairs.iter().map(|(_, w)| *w).sum::<usize>() + pair_sep_width * (pairs_count - 1)
+    } else {
+        0
+    };
+
+    // mode and separator widths (mode has padding of 2 chars in modeStyle)
+    let mode_len = mode.chars().count();
+    let mode_padding = 2usize; // Padding(0,1) adds 1 left + 1 right
+    let mode_w = mode_len + mode_padding;
+    let sep_w = " | ".chars().count();
+
+    let avail = if inner_max > mode_w + sep_w {
+        inner_max - mode_w - sep_w
+    } else {
+        0
+    };
+
+    // drop rightmost pairs until left + pag fits into avail
+    while pairs_count > 0 && left_width + pag_width > avail {
+        // remove last pair
+        pairs_count -= 1;
+        if pairs_count > 0 {
+            left_width = pairs
+                .iter()
+                .take(pairs_count)
+                .map(|(_, w)| *w)
+                .sum::<usize>()
+                + pair_sep_width * (pairs_count - 1);
+            left_joined_rendered = pairs
+                .iter()
+                .take(pairs_count)
+                .map(|(r, _)| r.clone())
+                .collect::<Vec<_>>()
+                .join(&pair_sep_rendered);
+        } else {
+            left_width = 0;
+            left_joined_rendered.clear();
+        }
+    }
+
+    // if still doesn't fit and pagination exists, shorten pagination to just "Page X/Y"
+    if left_width + pag_width > avail && !pag_plain.is_empty() {
+        let short_pag = format!("Page {}/{}", m.page + 1, total_pages);
+        pag_width = short_pag.chars().count();
+        pag_rendered = pag_style.render(&short_pag);
+    }
+
+    // compute filler width (subtract 2 to keep spacing consistent)
+    let pad = if avail > left_width + pag_width + 2 {
+        avail - left_width - pag_width - 2
+    } else {
+        0
+    };
+    let filler = if pad > 0 {
+        STYLE_MODELINE.clone().width(pad as i32).render("")
+    } else {
+        String::new()
+    };
+
+    let footer_inner = format!("{left_joined_rendered}{filler}{pag_rendered}");
+
+    let mode_style = STYLE_MODELINE
+        .clone()
+        .background(Color::from_rgb(101, 101, 101))
+        .padding(0, 1, 0, 1)
+        .bold(true);
+    let mode_styled = mode_style.render(mode);
+
+    // Indicator: show a dim single-char marker at the far left to indicate
+    // filtering mode. When numeric_baseline is present show '1', otherwise 'A'.
+    let indicator_char = if m.numeric_baseline.is_some() { "1" } else { "A" };
+    let indicator_style = STYLE_MODELINE.clone().faint(true).padding(0, 1, 0, 1);
+    let indicator_styled = indicator_style.render(indicator_char);
+
+    let sep_styled = inner_style.render(" | ");
+    let rest_content = format!("{sep_styled}{footer_inner}");
+
+    let trailing_pad = STYLE_MODELINE.render(" ");
+
+    // Place the indicator to the far left followed by the mode block.
+    format!("{indicator_styled}{mode_styled}{rest_content}{trailing_pad}")
+}
+
+pub fn render_modeline_padded(m: &Model) -> String {
+    // Compute total width and inner_max the same way render_full used to.
+    let total_width = if m.screen_width > 0 {
+        m.screen_width
+    } else {
+        DEFAULT_WIDTH
+    };
+    let inner_max = if total_width > 0 {
+        total_width.saturating_sub(2) - 1
+    } else {
+        DEFAULT_WIDTH
+    };
+    let visible = m.render_visible_items();
+    let mode = m.mode();
+    let modeline = render_modeline(m, inner_max, &mode, &visible);
+    let modeline_single = modeline.replace('\n', " ");
+    STYLE_MODELINE
+        .clone()
+        .width(total_width as i32)
+        .render(&modeline_single)
+}
+
+#[cfg(test)]
+mod tests {
+    use regex::Regex;
+
+    fn strip_ansi(s: &str) -> String {
+        let re = Regex::new(r"\x1b\[[0-9;?]*[ -/]*[@-~]").unwrap();
+        re.replace_all(s, "").to_string()
+    }
+
+    #[test]
+    fn modeline_is_last_line_and_exact_width_small() {
+        let (w, h) = (80usize, 24usize);
+        let entries: Vec<(String, String)> = Vec::new();
+        let mut m = crate::ui::initial_model(entries);
+        m.update(crate::ui::Msg::WindowSize {
+            width: w,
+            height: h,
+        });
+        let modeline = crate::ui::render_modeline_padded(&m);
+        let modeline_stripped = strip_ansi(&modeline);
+        assert!(
+            modeline_stripped
+                .lines()
+                .next()
+                .unwrap_or("")
+                .chars()
+                .count()
+                <= w
+        );
+    }
+
+    #[test]
+    fn modeline_shows_numeric_indicator_when_numeric_baseline() {
+        let (w, h) = (80usize, 24usize);
+        let entries: Vec<(String, String)> = Vec::new();
+        let mut m = crate::ui::initial_model(entries);
+        m.update(crate::ui::Msg::WindowSize { width: w, height: h });
+        // simulate numeric mode baseline captured
+        m.numeric_baseline = Some(vec![0, 1, 2]);
+        let modeline = crate::ui::render_modeline_padded(&m);
+        let modeline_stripped = strip_ansi(&modeline);
+        assert!(modeline_stripped.trim_start().starts_with('1'));
+    }
+
+    #[test]
+    fn modeline_shows_alpha_indicator_when_not_numeric() {
+        let (w, h) = (80usize, 24usize);
+        let entries: Vec<(String, String)> = Vec::new();
+        let mut m = crate::ui::initial_model(entries);
+        m.update(crate::ui::Msg::WindowSize { width: w, height: h });
+        m.numeric_baseline = None;
+        let modeline = crate::ui::render_modeline_padded(&m);
+        let modeline_stripped = strip_ansi(&modeline);
+        assert!(modeline_stripped.trim_start().starts_with('A'));
+    }
+}

crates/src/ui/render/preview.rs

···
+use crate::ui::model::{DEFAULT_WIDTH, Model, PREVIEW_BLOCK_LINES};
+use crate::ui::render::styles::{STYLE_PREVIEW, STYLE_PREVIEW_BOX};
+
+pub fn render_preview(m: &Model) -> String {
+    STYLE_PREVIEW.render(&m.ast.render_preview())
+}
+
+pub fn render_preview_block(m: &Model) -> Vec<String> {
+    let preview = m.ast.render_preview();
+    let preview_line = format!("> {preview}");
+    let box_width = if m.screen_width >= 2 {
+        m.screen_width - 2
+    } else {
+        DEFAULT_WIDTH
+    };
+    let w_i32: i32 = box_width.try_into().unwrap_or(i32::MAX);
+    let inner = STYLE_PREVIEW.render(&preview_line);
+    let preview_block = STYLE_PREVIEW_BOX.clone().width(w_i32).render(&inner);
+    let mut out: Vec<String> = preview_block.lines().map(|s| s.to_string()).collect();
+    // Ensure the preview block occupies exactly PREVIEW_BLOCK_LINES lines by truncating or padding with empty lines.
+    out.truncate(PREVIEW_BLOCK_LINES);
+    while out.len() < PREVIEW_BLOCK_LINES {
+        out.push(String::new());
+    }
+    out
+}

crates/src/ui/render/styles.rs

···
+use lipgloss::{Color, Style, rounded_border};
+use once_cell::sync::Lazy;
+
+// Styles kept local to render module
+pub static STYLE_ACE: Lazy<Style> = Lazy::new(|| {
+    Style::new()
+        .foreground(Color::from_rgb(238, 0, 238))
+        .bold(true)
+});
+pub static STYLE_TYPED: Lazy<Style> = Lazy::new(|| {
+    Style::new()
+        .foreground(Color::from_rgb(0, 0, 238))
+        .bold(true)
+});
+pub static STYLE_PREVIEW: Lazy<Style> = Lazy::new(|| {
+    Style::new()
+        .foreground(Color::from_rgb(0, 238, 238))
+        .bold(true)
+});
+pub static STYLE_LABEL: Lazy<Style> =
+    Lazy::new(|| Style::new().foreground(Color::from_rgb(200, 200, 200)));
+pub static STYLE_DESC: Lazy<Style> = Lazy::new(|| Style::new().faint(true));
+pub static STYLE_MODELINE: Lazy<Style> = Lazy::new(|| {
+    Style::new()
+        .background(Color::from_rgb(95, 95, 95))
+        .foreground(Color::from_rgb(255, 255, 255))
+        .padding(0, 1, 0, 1)
+});
+pub static STYLE_PREVIEW_BOX: Lazy<Style> =
+    Lazy::new(|| Style::new().border(rounded_border()).padding(0, 1, 0, 1));
+pub static STYLE_LINENUM: Lazy<Style> = Lazy::new(|| Style::new().faint(true));

crates/src/ui/render/util.rs

···
+use lipgloss::Style;
+
+pub fn normalize_and_pad(lines: Vec<String>, total_width: usize, per: usize) -> String {
+    let line_style = Style::new().width(total_width as i32);
+    let mut normalized: Vec<String> = lines.into_iter().map(|l| line_style.render(&l)).collect();
+    if normalized.len() > per {
+        normalized.truncate(per);
+    } else {
+        while normalized.len() < per {
+            normalized.push(line_style.render(""));
+        }
+    }
+    normalized.join("\n")
+}

crates/src/ui/run.rs

···
+use crate::carapace;
+use crate::ui::model::Model;
+use crate::ui::model::initial_model;
+use bubbletea_rs::{
+    Program, command::Cmd, event::KeyMsg, event::WindowSizeMsg, model::Model as TeaModel,
+};
+use crossterm::event::{KeyCode, KeyModifiers};
+
+// helper to build forms for a FlagDef
+fn flag_forms(f: &crate::ast::FlagDef) -> Vec<String> {
+    let mut forms = Vec::new();
+    if !f.longhand.is_empty() {
+        forms.push(format!("--{}", f.longhand));
+    }
+    if !f.shorthand.is_empty() {
+        forms.push(format!("-{}", f.shorthand));
+    }
+    forms
+}
+
+// Keep the interactive runner and the non-interactive parsing behavior here.
+pub fn run(initial_args: Vec<String>) -> Result<String, String> {
+    // preload carapace --list with descriptions
+    let entries = match carapace::list_with_desc() {
+        Ok(e) => e,
+        Err(err) => return Err(format!("carapace --list failed: {err}")),
+    };
+    let mut m = initial_model(entries);
+
+    if !initial_args.is_empty() {
+        // set root
+        let root = &initial_args[0];
+        match carapace::export(root) {
+            Ok(def) => {
+                m.ast.root = def.name.clone();
+                if !m.ast.stack.is_empty() {
+                    m.ast.stack[0].name = def.name.clone();
+                }
+                m.build_items_from_command(&def);
+                m.current = Some(def);
+            }
+            Err(e) => return Err(format!("carapace {root} export failed: {e}")),
+        }
+
+        // parse remaining tokens
+        let mut i = 1usize;
+        while i < initial_args.len() {
+            let tok = &initial_args[i];
+            if tok.starts_with('-') {
+                // flag form; find exact-form match among current.Flags
+                let mut matched = false;
+                if let Some(cur) = &m.current {
+                    for f in &cur.flags {
+                        for fm in flag_forms(f).iter() {
+                            if fm == tok {
+                                // add flag; if requires value and next arg exists and isn't a flag, consume it
+                                let mut val = String::new();
+                                if f.requires_value
+                                    && i + 1 < initial_args.len()
+                                    && !initial_args[i + 1].starts_with('-')
+                                {
+                                    val = initial_args[i + 1].clone();
+                                    i += 1;
+                                }
+                                m.ast.add_flag(fm, &val);
+                                matched = true;
+                                break;
+                            }
+                        }
+                        if matched {
+                            break;
+                        }
+                    }
+                }
+                if !matched {
+                    m.ast.add_positional(tok);
+                }
+                i += 1;
+                continue;
+            }
+            // not a flag: could be subcommand or positional
+            let mut found = false;
+            if let Some(cur) = m.current.clone() {
+                for sc in cur.subcommands.iter() {
+                    if sc.name == *tok || sc.aliases.iter().any(|a| a == tok) {
+                        m.ast.push_subcommand(&sc.name);
+                        m.current = Some(sc.clone());
+                        m.build_items_from_command(sc);
+                        found = true;
+                        break;
+                    }
+                }
+            }
+            if !found {
+                m.ast.add_positional(tok);
+            }
+            i += 1;
+        }
+    }
+
+    // If initial_args were provided we are non-interactive: return the recorded preview (may be empty)
+    if !initial_args.is_empty() {
+        return Ok(m.exit_preview.clone());
+    }
+
+    // Interactive path: build a TeaAdapter that delegates to our Model and run the bubbletea-rs Program.
+    struct TeaAdapter {
+        inner: Model,
+    }
+
+    impl TeaModel for TeaAdapter {
+        fn init() -> (Self, Option<Cmd>) {
+            // Preload entries for interactive session (best-effort)
+            let entries = carapace::list_with_desc().unwrap_or_default();
+            let model = initial_model(entries);
+            (TeaAdapter { inner: model }, None)
+        }
+
+        fn update(&mut self, msg: bubbletea_rs::event::Msg) -> Option<Cmd> {
+            // Map bubbletea-rs Msg types to our ui::Msg and call update
+            if let Some(km) = msg.downcast_ref::<KeyMsg>() {
+                // Normalize and handle global quit keys first for reliability across terminals:
+                match &km.key {
+                    KeyCode::Esc => {
+                        if !self.inner.in_value_mode {
+                            return Some(bubbletea_rs::quit());
+                        }
+                        self.inner.update(crate::ui::Msg::KeyEsc);
+                        return None;
+                    }
+                    KeyCode::Char(ch) => {
+                        if *ch == '\u{1b}' {
+                            if !self.inner.in_value_mode {
+                                return Some(bubbletea_rs::quit());
+                            }
+                            self.inner.update(crate::ui::Msg::KeyEsc);
+                            return None;
+                        }
+                        if *ch == '\u{03}' {
+                            // Ctrl-C delivered as ETX
+                            return Some(bubbletea_rs::quit());
+                        }
+                        if km.modifiers.contains(KeyModifiers::CONTROL)
+                            && (*ch == 'c' || *ch == 'C')
+                        {
+                            return Some(bubbletea_rs::quit());
+                        }
+                    }
+                    _ => {}
+                }
+
+                match &km.key {
+                    KeyCode::Enter => {
+                        self.inner.update(crate::ui::Msg::KeyEnter);
+                        if !self.inner.exit_preview.is_empty() {
+                            return Some(bubbletea_rs::quit());
+                        }
+                    }
+                    KeyCode::Backspace => {
+                        self.inner.update(crate::ui::Msg::KeyBackspace);
+                    }
+                    KeyCode::Esc => { /* handled above */ }
+                    KeyCode::Up => {
+                        self.inner.update(crate::ui::Msg::KeyUp);
+                    }
+                    KeyCode::Down => {
+                        self.inner.update(crate::ui::Msg::KeyDown);
+                    }
+                    KeyCode::Char(ch) => {
+                        if km.modifiers.contains(KeyModifiers::CONTROL) {
+                            match ch {
+                                'n' | 'N' => {
+                                    self.inner.update(crate::ui::Msg::KeyDown);
+                                }
+                                'p' | 'P' => {
+                                    self.inner.update(crate::ui::Msg::KeyUp);
+                                }
+                                _ => {}
+                            }
+                        } else if *ch == ' ' {
+                            self.inner.update(crate::ui::Msg::KeySpace);
+                        } else {
+                            self.inner.update(crate::ui::Msg::Rune(*ch));
+                        }
+                    }
+                    _ => {}
+                }
+                return None;
+            }
+            if let Some(ws) = msg.downcast_ref::<WindowSizeMsg>() {
+                self.inner.update(crate::ui::Msg::WindowSize {
+                    width: ws.width as usize,
+                    height: ws.height as usize,
+                });
+                return None;
+            }
+            None
+        }
+
+        fn view(&self) -> String {
+            self.inner.render_full()
+        }
+    }
+
+    let builder = Program::<TeaAdapter>::builder()
+        .alt_screen(true)
+        .signal_handler(true);
+    let program = match builder.build() {
+        Ok(p) => p,
+        Err(e) => return Err(format!("failed to build program: {e:?}")),
+    };
+    let final_adapter = match futures::executor::block_on(program.run()) {
+        Ok(fa) => fa,
+        Err(e) => return Err(format!("program error: {e:?}")),
+    };
+
+    Ok(final_adapter.inner.exit_preview.clone())
+}

crates/src/ui/update.rs

···
+use crate::acekey::assign_ace_keys;
+use crate::carapace;
+use crate::ui::model::ChooseItem;
+use crate::ui::model::Model;
+use bubbletea_widgets::Viewport;
+use std::collections::HashMap;
+
+pub fn handle_update(m: &mut Model, msg: crate::ui::Msg) {
+    match msg {
+        crate::ui::Msg::WindowSize { width, height } => handle_window_size(m, width, height),
+        crate::ui::Msg::KeyBackspace => handle_key_backspace(m),
+        crate::ui::Msg::KeyEnter => handle_key_enter(m),
+        crate::ui::Msg::KeySpace => handle_key_space(m),
+        crate::ui::Msg::KeyEsc => handle_key_esc(m),
+        crate::ui::Msg::KeyDown => handle_key_down(m),
+        crate::ui::Msg::KeyUp => handle_key_up(m),
+        crate::ui::Msg::Rune(r) => handle_rune(m, r),
+    }
+}
+
+fn handle_window_size(m: &mut Model, width: usize, height: usize) {
+    m.screen_width = width;
+    m.per_page = height.saturating_sub(crate::ui::model::RESERVED_LINES);
+    m.vp = Viewport::new(m.per_page, m.screen_width);
+    let visible = m.render_visible_items();
+    let total_pages = if visible.is_empty() {
+        1
+    } else {
+        visible.len().div_ceil(m.per_page)
+    };
+    if m.page >= total_pages {
+        m.page = 0;
+    }
+    let list_content = m.render_list_content(&visible);
+    m.vp.set_content(&list_content);
+    if !m.typed.is_empty() {
+        m.vp.goto_top();
+    }
+}
+
+fn handle_key_backspace(m: &mut Model) {
+    if !m.typed.is_empty() {
+        m.typed.pop();
+        m.typed_raw.pop();
+        // If typed_raw becomes empty, clear numeric_baseline since numeric mode ended
+        if m.typed_raw.is_empty() {
+            m.numeric_baseline = None;
+        }
+        return;
+    }
+
+    if let Some(top) = m.ast.top() {
+        if !m.ast.root.is_empty()
+            && m.ast.stack.len() == 1
+            && top.flags.is_empty()
+            && top.positionals.is_empty()
+        {
+            match carapace::list_with_desc() {
+                Ok(entries) => {
+                    set_items_from_carapace_entries(m, entries);
+                    return;
+                }
+                Err(e) => {
+                    m.err = e;
+                    return;
+                }
+            }
+        }
+    }
+
+    let before = m.ast.stack.len();
+    m.ast.remove_last();
+    let after = m.ast.stack.len();
+    if after < before {
+        restore_current_after_pop(m);
+    }
+}
+
+fn handle_key_enter(m: &mut Model) {
+    if m.in_value_mode {
+        if m.pending_pos {
+            if !m.pending_value.is_empty() {
+                m.ast.add_positional(&m.pending_value);
+            }
+            m.in_value_mode = false;
+            m.pending_pos = false;
+            m.pending_value.clear();
+            return;
+        }
+        if let Some(_fd) = &m.pending_flag {
+            m.ast
+                .add_flag_to_depth(m.pending_depth, &m.pending_form, &m.pending_value);
+            m.in_value_mode = false;
+            m.pending_flag = None;
+            m.pending_form.clear();
+            m.pending_value.clear();
+            return;
+        }
+    }
+    let preview = m.ast.render_preview();
+    if preview.is_empty() {
+        return;
+    }
+    m.exit_preview = preview.clone();
+}
+
+fn handle_key_space(m: &mut Model) {
+    m.in_value_mode = true;
+    m.pending_pos = true;
+}
+
+fn handle_key_esc(m: &mut Model) {
+    if m.in_value_mode {
+        m.in_value_mode = false;
+        m.pending_flag = None;
+        m.pending_form.clear();
+        m.pending_pos = false;
+        m.pending_depth = 0;
+        m.pending_value.clear();
+    }
+}
+
+fn handle_key_down(m: &mut Model) {
+    let visible = m.render_visible_items();
+    let total = visible.len();
+    let per = if m.per_page == 0 { total } else { m.per_page };
+    if per == 0 {
+        return;
+    }
+    let total_pages = if total == 0 {
+        1
+    } else {
+        total.div_ceil(per)
+    };
+    if m.page + 1 < total_pages {
+        m.page += 1;
+    }
+    let list_content = m.render_list_content(&visible);
+    m.vp.set_content(&list_content);
+    m.vp.goto_top();
+}
+
+fn handle_key_up(m: &mut Model) {
+    if m.page > 0 {
+        m.page -= 1;
+    }
+    let visible = m.render_visible_items();
+    let list_content = m.render_list_content(&visible);
+    m.vp.set_content(&list_content);
+}
+
+fn clear_typed(m: &mut Model) {
+    m.typed.clear();
+    m.typed_raw.clear();
+}
+
+fn handle_command_choice(m: &mut Model, it: &ChooseItem, chosen_form: &str) -> bool {
+    let cmd_name = if let Some(cd) = &it.cmd_def {
+        cd.name.clone()
+    } else {
+        chosen_form.to_string()
+    };
+
+    if m.current.is_none() && m.ast.root.is_empty() {
+        match carapace::export(&cmd_name) {
+            Ok(def) => {
+                apply_loaded_command(m, def);
+                return true;
+            }
+            Err(e) => {
+                m.err = e;
+                return true;
+            }
+        }
+    }
+
+    m.ast.push_subcommand(&cmd_name);
+
+    if let Some(subdef) = &it.cmd_def {
+        m.current = Some(subdef.clone());
+        m.build_items_from_command(subdef);
+        clear_typed(m);
+        return true;
+    }
+
+    match carapace::export(chosen_form) {
+        Ok(def) => {
+            m.def_cache.insert(def.name.clone(), def.clone());
+            m.current = Some(def.clone());
+            m.build_items_from_command(&def);
+            clear_typed(m);
+            true
+        }
+        Err(e) => {
+            m.err = e;
+            true
+        }
+    }
+}
+
+fn handle_flag_choice(
+    m: &mut Model,
+    fd: &crate::ast::FlagDef,
+    chosen_form: &str,
+    depth: usize,
+) -> bool {
+    if m.ast.remove_flag_from_depth(chosen_form, depth) {
+        clear_typed(m);
+        return true;
+    }
+    if fd.requires_value {
+        m.in_value_mode = true;
+        m.pending_flag = Some(fd.clone());
+        m.pending_form = chosen_form.to_string();
+        m.pending_depth = depth;
+        clear_typed(m);
+        return true;
+    }
+
+    m.ast.add_flag_to_depth(depth, chosen_form, "");
+    clear_typed(m);
+    true
+}
+
+fn update_typed_for_rune(m: &mut Model, r: char, was_numeric: bool) {
+    // Handles all non-initial-numeric-capture typed updates
+    if r.is_ascii_digit() && was_numeric {
+        m.typed_raw.push(r);
+        m.typed.push(r.to_ascii_lowercase());
+        m.page = 0;
+        return;
+    }
+
+    if r.is_ascii_alphabetic() && (m.typed_raw.chars().all(|c| c.is_ascii_digit()) && !m.typed_raw.is_empty()) {
+        // Transition from Numeric mode to Alpha mode
+        m.numeric_baseline = None;
+        m.typed_raw.clear();
+        m.typed.clear();
+        m.typed_raw.push(r);
+        m.typed.push(r.to_ascii_lowercase());
+        m.page = 0;
+        return;
+    }
+
+    // Regular AceKey character handling (alpha or other)
+    m.typed_raw.push(r);
+    m.typed.push(r.to_ascii_lowercase());
+    m.page = 0;
+}
+
+fn forms_and_form_map(m: &Model) -> (Vec<String>, HashMap<String, usize>) {
+    let forms: Vec<String> = m.items.iter().flat_map(|it| it.forms.iter().cloned()).collect();
+    let form_map: HashMap<String, usize> = m
+        .items
+        .iter()
+        .enumerate()
+        .flat_map(|(item_idx, it)| it.forms.iter().cloned().map(move |f| (f, item_idx)))
+        .collect();
+    (forms, form_map)
+}
+
+fn simulate_alpha_treatment(m: &Model, r: char, was_numeric: bool) -> bool {
+    if !(r.is_ascii_digit() && !was_numeric) {
+        return false;
+    }
+
+    let (forms_all, _fm) = forms_and_form_map(m);
+    let mut sim_typed = m.typed_raw.clone();
+    sim_typed.push(r);
+
+    if let Some(asg) = assign_ace_keys(&forms_all, &sim_typed) {
+        if !asg.is_empty() {
+            return true;
+        }
+    }
+
+    if m.items.len() == 1 && m.items.iter().any(|it| it.forms.iter().any(|f| f.contains(&r.to_string()))) {
+        return true;
+    }
+
+    false
+}
+
+fn handle_rune(m: &mut Model, r: char) {
+    let s = r.to_string();
+    if !crate::acekey::is_single_ace_rune(&s) {
+        return;
+    }
+
+    let was_numeric = m.typed_raw.chars().all(|c| c.is_ascii_digit()) && !m.typed_raw.is_empty();
+
+    // If incoming rune is a digit starting a potential numeric mode, treat it as numeric
+    // only when simulate_alpha_treatment returns false. Flattened for readability.
+    if r.is_ascii_digit() && !was_numeric && !simulate_alpha_treatment(m, r, was_numeric) {
+        capture_numeric_baseline(m, r);
+    } else {
+        update_typed_for_rune(m, r, was_numeric);
+    }
+
+    let (forms, form_map) = forms_and_form_map(m);
+    let assignments = assign_ace_keys(&forms, &m.typed_raw);
+
+    if process_numeric_selection(m) {
+        return;
+    }
+
+    if let Some(asg) = assignments {
+        if try_immediate_assignment_selection(m, asg, &forms, &form_map) {
+            return;
+        }
+    }
+
+    update_viewport_after_typed(m);
+}
+
+fn capture_numeric_baseline(m: &mut Model, r: char) {
+    let visible_snapshot = m.render_visible_items();
+    let mut baseline_indices: Vec<usize> = visible_snapshot
+        .iter()
+        .filter_map(|vis| {
+            m.items
+                .iter()
+                .position(|it| it.label == vis.label && it.forms == vis.forms)
+        })
+        .collect();
+
+    if baseline_indices.is_empty() {
+        baseline_indices = (0..m.items.len()).collect();
+    }
+
+    m.numeric_baseline = Some(baseline_indices);
+    m.typed_raw.clear();
+    m.typed.clear();
+    m.typed_raw.push(r);
+    m.typed.push(r.to_ascii_lowercase());
+    m.page = 0;
+}
+
+fn set_items_from_carapace_entries(m: &mut Model, entries: Vec<(String, String)>) {
+    let items: Vec<ChooseItem> = entries
+        .into_iter()
+        .map(|(name, short)| ChooseItem {
+            kind: "cmd".to_string(),
+            label: name.clone(),
+            forms: vec![name.clone()],
+            flag_def: None,
+            cmd_def: None,
+            short,
+            depth: 0,
+        })
+        .collect();
+    m.items = crate::ui::model::sort_items(items);
+    m.current = None;
+    m.ast.root.clear();
+    if let Some(n) = m.ast.stack.get_mut(0) {
+        n.name.clear();
+    }
+    let visible = m.render_visible_items();
+    let list_content = m.render_list_content(&visible);
+    m.vp.set_content(&list_content);
+}
+
+fn restore_current_after_pop(m: &mut Model) {
+    if !m.ast.root.is_empty() {
+        let root_name = m.ast.stack[0].name.clone();
+        if let Some(def) = m.def_cache.get(&root_name) {
+            let mut cur = def.clone();
+            if m.ast.stack.len() > 1 {
+                for i in 1..m.ast.stack.len() {
+                    let name = m.ast.stack[i].name.clone();
+                    if let Some(found) = cur
+                        .subcommands
+                        .iter()
+                        .find(|sc| sc.name == name || sc.aliases.iter().any(|a| a == &name))
+                    {
+                        cur = found.clone();
+                    } else {
+                        break;
+                    }
+                }
+            }
+            m.current = Some(cur.clone());
+            m.build_items_from_command(&cur);
+            let visible = m.render_visible_items();
+            let list_content = m.render_list_content(&visible);
+            m.vp.set_content(&list_content);
+        } else {
+            m.current = None;
+            m.items.clear();
+            m.vp.set_content("");
+        }
+    } else {
+        m.current = None;
+        m.items.clear();
+        m.vp.set_content("");
+    }
+}
+
+fn process_numeric_selection(m: &mut Model) -> bool {
+    let is_numeric = !m.typed_raw.is_empty() && m.typed_raw.chars().all(|c| c.is_ascii_digit());
+    if !is_numeric { return false; }
+    if let Some(baseline) = &m.numeric_baseline {
+        let matches: Vec<usize> = baseline
+            .iter()
+            .filter_map(|&orig_idx| {
+                let num = (orig_idx + 1).to_string();
+                if num.starts_with(&m.typed_raw) {
+                    Some(orig_idx)
+                } else {
+                    None
+                }
+            })
+            .collect();
+        if matches.len() == 1 {
+            let chosen_idx = matches[0];
+            let it = m.items[chosen_idx].clone();
+            let chosen_form = it.forms.first().cloned().unwrap_or_default();
+
+            if it.kind == "cmd" {
+                if handle_command_choice(m, &it, &chosen_form) {
+                    m.numeric_baseline = None;
+                    return true;
+                }
+            } else if it.kind == "flag" {
+                if let Some(fd) = &it.flag_def {
+                    if handle_flag_choice(m, fd, &chosen_form, it.depth) {
+                        m.numeric_baseline = None;
+                        return true;
+                    }
+                }
+            }
+        }
+    } else {
+        let matches: Vec<usize> = m
+            .items
+            .iter()
+            .enumerate()
+            .filter_map(|(idx, _)| {
+                let num = (idx + 1).to_string();
+                if num.starts_with(&m.typed_raw) {
+                    Some(idx)
+                } else {
+                    None
+                }
+            })
+            .collect();
+        if matches.len() == 1 {
+            let chosen_idx = matches[0];
+            let it = m.items[chosen_idx].clone();
+            let chosen_form = it.forms.first().cloned().unwrap_or_default();
+            if it.kind == "cmd" {
+                if handle_command_choice(m, &it, &chosen_form) {
+                    return true;
+                }
+            } else if it.kind == "flag" {
+                if let Some(fd) = &it.flag_def {
+                    if handle_flag_choice(m, fd, &chosen_form, it.depth) {
+                        return true;
+                    }
+                }
+            }
+        }
+    }
+    false
+}
+
+fn try_immediate_assignment_selection(m: &mut Model, assignments: Vec<crate::acekey::Assignment>, forms: &[String], form_map: &HashMap<String, usize>) -> bool {
+    if assignments.len() == 1 && assignments[0].prefix.is_empty() {
+        let visible_items = m.render_visible_items();
+        if visible_items.len() == 1 {
+            let idx = assignments[0].index;
+            if idx < forms.len() {
+                let chosen_form = forms[idx].clone();
+                if let Some(item_idx) = form_map.get(&chosen_form) {
+                    let it = m.items[*item_idx].clone();
+                    if it.kind == "cmd" {
+                        handle_command_choice(m, &it, &chosen_form);
+                        return true;
+                    } else if it.kind == "flag" {
+                        if let Some(fd) = &it.flag_def {
+                            if handle_flag_choice(m, fd, &chosen_form, it.depth) {
+                                return true;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    false
+}
+
+fn update_viewport_after_typed(m: &mut Model) {
+    let visible_now = m.render_visible_items();
+    let list_content = m.render_list_content(&visible_now);
+    m.vp.set_content(&list_content);
+    if !m.typed.is_empty() {
+        m.vp.goto_top();
+    }
+}
+
+fn apply_loaded_command(m: &mut Model, def: crate::ast::CommandDef) {
+    m.def_cache.insert(def.name.clone(), def.clone());
+    m.ast.root = def.name.clone();
+    if m.ast.stack.is_empty() {
+        m.ast = crate::ast::Segment::new_empty(&def.name);
+    } else {
+        m.ast.stack[0].name = def.name.clone();
+    }
+    m.current = Some(def.clone());
+    m.build_items_from_command(&def);
+    // update viewport content so the interactive UI shows the newly loaded command items
+    let visible = m.render_visible_items();
+    let list_content = m.render_list_content(&visible);
+    m.vp.set_content(&list_content);
+    m.typed.clear();
+    m.typed_raw.clear();
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::ast::{Segment, CommandDef, FlagDef};
+    use crate::ui::model::initial_model;
+
+    #[test]
+    fn apply_loaded_command_sets_ast_and_items_and_viewport() {
+        let mut m = initial_model(vec![]);
+        // ensure model starts with an empty AST stack (simulate initial screen)
+        m.ast = Segment::default();
+
+        let sub = CommandDef {
+            name: "list".to_string(),
+            short: "listsub".to_string(),
+            aliases: vec![],
+            flags: vec![],
+            subcommands: vec![],
+        };
+        let def = CommandDef {
+            name: "ls".to_string(),
+            short: "lscmd".to_string(),
+            aliases: vec![],
+            flags: vec![FlagDef {
+                longhand: "all".to_string(),
+                shorthand: "a".to_string(),
+                usage: "show all".to_string(),
+                requires_value: false,
+            }],
+            subcommands: vec![sub.clone()],
+        };
+
+        // call the private helper as the interactive path would
+        super::apply_loaded_command(&mut m, def.clone());
+
+        // AST stack should have a root node named `ls`
+        assert!(
+            !m.ast.stack.is_empty(),
+            "expected AST stack to be non-empty"
+        );
+        assert_eq!(m.ast.stack[0].name, "ls");
+
+        // current should be set to the loaded def
+        assert!(m.current.is_some());
+        assert_eq!(m.current.as_ref().unwrap().name, "ls");
+
+        // items should include at least one flag or subcommand
+        let mut has_flag = false;
+        let mut has_cmd = false;
+        for it in &m.items {
+            if it.kind == "flag" {
+                has_flag = true
+            }
+            if it.kind == "cmd" {
+                has_cmd = true
+            }
+        }
+        assert!(
+            has_flag || has_cmd,
+            "expected flags or subcommands after loading command"
+        );
+
+        // typed buffers should be cleared
+        assert!(m.typed.is_empty() && m.typed_raw.is_empty());
+
+        // viewport content should contain something (non-empty)
+        // Viewport doesn't expose content directly; ensure render_visible_items produces expected output
+        let visible = m.render_visible_items();
+        let list = m.render_list_content(&visible);
+        assert!(
+            !list.is_empty(),
+            "expected rendered list content to be non-empty"
+        );
+    }
+}
+
+#[cfg(test)]
+mod numeric_mode_tests {
+    use crate::ui::model::{initial_model, ChooseItem};
+    use crate::ast::{Segment, FlagDef, CommandDef};
+
+    #[test]
+    fn test_digit_switch_from_alpha_to_numeric_and_selects_unique_index() {
+        let mut m = initial_model(vec![]);
+        // ensure AST present so flag selection will add to depth
+        m.ast = Segment::new_empty("root");
+        m.ast.root = "root".to_string();
+        m.ast.stack[0].name = "root".to_string();
+
+        // create three flag items so index 2 uniquely identifies the middle
+        m.items = vec![
+            ChooseItem {
+                kind: "flag".to_string(),
+                label: "--flag1".to_string(),
+                forms: vec!["--flag1".to_string()],
+                flag_def: Some(FlagDef {
+                    longhand: "flag1".to_string(),
+                    shorthand: "f".to_string(),
+                    usage: String::new(),
+                    requires_value: false,
+                }),
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+            ChooseItem {
+                kind: "flag".to_string(),
+                label: "--flag2".to_string(),
+                forms: vec!["--flag2".to_string()],
+                flag_def: Some(FlagDef {
+                    longhand: "flag2".to_string(),
+                    shorthand: "g".to_string(),
+                    usage: String::new(),
+                    requires_value: false,
+                }),
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+            ChooseItem {
+                kind: "flag".to_string(),
+                label: "--flag3".to_string(),
+                forms: vec!["--flag3".to_string()],
+                flag_def: Some(FlagDef {
+                    longhand: "flag3".to_string(),
+                    shorthand: "h".to_string(),
+                    usage: String::new(),
+                    requires_value: false,
+                }),
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+        ];
+
+        // type digit '2' which should switch to numeric mode, capture baseline and select index 2
+        m.update(crate::ui::Msg::Rune('2'));
+        // Numeric input of '2' may immediately select the unique matching index.
+        let top = &m.ast.stack[0];
+        assert!(top.flags.iter().any(|f| f.form == "--flag2"), "expected flag --flag2 to be selected via numeric index");
+    }
+
+    #[test]
+    fn test_switch_back_to_alpha_clears_numeric_baseline() {
+        let mut m = initial_model(vec![]);
+        m.ast = Segment::new_empty("root");
+        m.ast.root = "root".to_string();
+        m.ast.stack[0].name = "root".to_string();
+
+        // populate items so baseline capture works
+        m.items = vec![
+            ChooseItem {
+                kind: "cmd".to_string(),
+                label: "one".to_string(),
+                forms: vec!["one".to_string()],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+            ChooseItem {
+                kind: "cmd".to_string(),
+                label: "two".to_string(),
+                forms: vec!["two".to_string()],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+        ];
+
+        // create many items so that the single-digit prefix '1' is ambiguous
+        for i in 0..12 {
+            m.items.push(ChooseItem {
+                kind: "cmd".to_string(),
+                label: format!("cmd{}", i+1),
+                forms: vec![format!("cmd{}", i+1)],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            });
+        }
+
+        // type digit to enter numeric; should capture baseline but not select (ambiguous)
+        m.update(crate::ui::Msg::Rune('1'));
+        assert!(m.numeric_baseline.is_some());
+        assert_eq!(m.typed_raw, "1");
+
+        // now type an alphabetic character which should clear numeric baseline and switch to alpha
+        m.update(crate::ui::Msg::Rune('x'));
+        assert!(m.numeric_baseline.is_none(), "expected numeric_baseline cleared after alpha rune");
+        assert_eq!(m.typed_raw, "x");
+    }
+
+    #[test]
+    fn test_w_wc_who_alpha_list_and_numeric_selects_who() {
+        use regex::Regex;
+        fn strip_ansi(s: &str) -> String {
+            let re = Regex::new(r"\x1b\[[0-9;?]*[ -/]*[@-~]").unwrap();
+            re.replace_all(s, "").to_string()
+        }
+
+        let mut m = initial_model(vec![]);
+        m.ast = Segment::new_empty("root");
+        m.ast.root = "root".to_string();
+        m.ast.stack[0].name = "root".to_string();
+
+        let wdef = CommandDef { name: "w".to_string(), short: "w".to_string(), aliases: vec![], flags: vec![], subcommands: vec![] };
+        let wcdef = CommandDef { name: "wc".to_string(), short: "wc".to_string(), aliases: vec![], flags: vec![], subcommands: vec![] };
+        let whodef = CommandDef { name: "who".to_string(), short: "who".to_string(), aliases: vec![], flags: vec![], subcommands: vec![] };
+
+        m.items = vec![
+            ChooseItem {
+                kind: "cmd".to_string(),
+                label: "w".to_string(),
+                forms: vec!["w".to_string()],
+                flag_def: None,
+                cmd_def: Some(wdef.clone()),
+                short: String::new(),
+                depth: 0,
+            },
+            ChooseItem {
+                kind: "cmd".to_string(),
+                label: "wc".to_string(),
+                forms: vec!["wc".to_string()],
+                flag_def: None,
+                cmd_def: Some(wcdef.clone()),
+                short: String::new(),
+                depth: 0,
+            },
+            ChooseItem {
+                kind: "cmd".to_string(),
+                label: "who".to_string(),
+                forms: vec!["who".to_string()],
+                flag_def: None,
+                cmd_def: Some(whodef.clone()),
+                short: String::new(),
+                depth: 0,
+            },
+        ];
+
+        // Type 'w' (alpha) - should show all three in order
+        m.update(crate::ui::Msg::Rune('w'));
+        let visible = m.render_visible_items();
+        assert_eq!(visible.len(), 3);
+        assert_eq!(visible[0].label, "w");
+        assert_eq!(visible[1].label, "wc");
+        assert_eq!(visible[2].label, "who");
+
+        let list = m.render_list_content(&visible);
+        let stripped = strip_ansi(&list);
+        let lines: Vec<&str> = stripped.lines().collect();
+        assert!(lines.len() >= 3, "expected at least 3 rendered lines");
+        assert!(lines[0].contains(" 1 │ w "), "{}", lines[0]);
+        assert!(lines[1].contains(" 2 │ wc "), "second line should show gutter 2 and 'wc'");
+        assert!(lines[2].contains(" 3 │ who "), "third line should show gutter 3 and 'who'");
+
+        // Now type '3' to switch to numeric mode and select who
+        m.update(crate::ui::Msg::Rune('3'));
+        assert!(m.ast.top().is_some(), "expected a subcommand selected");
+        assert_eq!(m.ast.top().unwrap().name, "who");
+    }
+}
+
+#[cfg(test)]
+mod digit_vs_numeric_tests {
+    use crate::ui::model::{initial_model, ChooseItem};
+    use crate::ast::Segment;
+
+    #[test]
+    fn digit_present_in_form_treated_as_alpha_not_numeric() {
+        let mut m = initial_model(vec![]);
+        m.ast = Segment::new_empty("root");
+        m.ast.root = "root".to_string();
+        m.ast.stack[0].name = "root".to_string();
+
+        // item form contains digit '2' so typing '2' should be treated as alpha
+        m.items = vec![
+            ChooseItem {
+                kind: "cmd".to_string(),
+                label: "a2".to_string(),
+                forms: vec!["a2".to_string()],
+                flag_def: None,
+                cmd_def: None,
+                short: String::new(),
+                depth: 0,
+            },
+        ];
+
+        // type digit '2'
+        m.update(crate::ui::Msg::Rune('2'));
+        // should remain in alpha: numeric_baseline must be None
+        assert!(m.numeric_baseline.is_none(), "expected digit in form to be treated as alpha");
+        // typed_raw should contain '2' as part of AceKey input
+        assert_eq!(m.typed_raw, "2");
+    }
+}

flake.lock

···
+{
+  "nodes": {
+    "allfollow": {
+      "inputs": {
+        "nixpkgs": "nixpkgs",
+        "rust-overlay": "rust-overlay",
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1752903850,
+        "narHash": "sha256-Q9CVcods7Ftcs0KeplhkZOClQKqZy8zwfay02jvNloQ=",
+        "owner": "spikespaz",
+        "repo": "allfollow",
+        "rev": "5e097ac8c6fb8b9e32a3c590090005abe853cccf",
+        "type": "github"
+      },
+      "original": {
+        "owner": "spikespaz",
+        "repo": "allfollow",
+        "type": "github"
+      }
+    },
+    "cachix": {
+      "inputs": {
+        "devenv": [
+          "devenv"
+        ],
+        "flake-compat": [
+          "devenv"
+        ],
+        "git-hooks": [
+          "devenv",
+          "git-hooks"
+        ],
+        "nixpkgs": [
+          "devenv",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1748883665,
+        "narHash": "sha256-R0W7uAg+BLoHjMRMQ8+oiSbTq8nkGz5RDpQ+ZfxxP3A=",
+        "owner": "cachix",
+        "repo": "cachix",
+        "rev": "f707778d902af4d62d8dd92c269f8e70de09acbe",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "ref": "latest",
+        "repo": "cachix",
+        "type": "github"
+      }
+    },
+    "devenv": {
+      "inputs": {
+        "cachix": "cachix",
+        "flake-compat": "flake-compat",
+        "git-hooks": "git-hooks",
+        "nix": "nix",
+        "nixpkgs": "nixpkgs_2"
+      },
+      "locked": {
+        "lastModified": 1756048064,
+        "narHash": "sha256-mVgB6qWhLrCW6AciLyFXosDKKZFtBgqvixcA8a07s+g=",
+        "owner": "cachix",
+        "repo": "devenv",
+        "rev": "3fb20c149d329b01a2b519fbb2a9ca3e6e6e1b05",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "repo": "devenv",
+        "type": "github"
+      }
+    },
+    "devshell": {
+      "inputs": {
+        "nixpkgs": "nixpkgs_3"
+      },
+      "locked": {
+        "lastModified": 1741473158,
+        "narHash": "sha256-kWNaq6wQUbUMlPgw8Y+9/9wP0F8SHkjy24/mN3UAppg=",
+        "owner": "numtide",
+        "repo": "devshell",
+        "rev": "7c9e793ebe66bcba8292989a68c0419b737a22a0",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "devshell",
+        "type": "github"
+      }
+    },
+    "flake-compat": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1747046372,
+        "narHash": "sha256-CIVLLkVgvHYbgI2UpXvIIBJ12HWgX+fjA8Xf8PUmqCY=",
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "9100a0f413b0c601e0533d1d94ffd501ce2e7885",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "flake-file": {
+      "locked": {
+        "lastModified": 1753122811,
+        "narHash": "sha256-D2uccKODLVkI91uiWlwwEkg0X7HcYeiKKGHsD24qmyU=",
+        "owner": "vic",
+        "repo": "flake-file",
+        "rev": "745975d82877699e9504fd0e751b4f70166f066c",
+        "type": "github"
+      },
+      "original": {
+        "owner": "vic",
+        "repo": "flake-file",
+        "type": "github"
+      }
+    },
+    "flake-parts": {
+      "inputs": {
+        "nixpkgs-lib": [
+          "devenv",
+          "nix",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1733312601,
+        "narHash": "sha256-4pDvzqnegAfRkPwO3wmwBhVi/Sye1mzps0zHWYnP88c=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "205b12d8b7cd4802fbcb8e8ef6a0f1408781a4f9",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "type": "github"
+      }
+    },
+    "flake-parts_2": {
+      "inputs": {
+        "nixpkgs-lib": "nixpkgs-lib"
+      },
+      "locked": {
+        "lastModified": 1754487366,
+        "narHash": "sha256-pHYj8gUBapuUzKV/kN/tR3Zvqc7o6gdFB9XKXIp1SQ8=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "af66ad14b28a127c5c0f3bbb298218fc63528a18",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "type": "github"
+      }
+    },
+    "git-hooks": {
+      "inputs": {
+        "flake-compat": [
+          "devenv",
+          "flake-compat"
+        ],
+        "gitignore": "gitignore",
+        "nixpkgs": [
+          "devenv",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1750779888,
+        "narHash": "sha256-wibppH3g/E2lxU43ZQHC5yA/7kIKLGxVEnsnVK1BtRg=",
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "rev": "16ec914f6fb6f599ce988427d9d94efddf25fe6d",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "type": "github"
+      }
+    },
+    "gitignore": {
+      "inputs": {
+        "nixpkgs": [
+          "devenv",
+          "git-hooks",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1709087332,
+        "narHash": "sha256-HG2cCnktfHsKV0s4XW83gU3F57gaTljL9KNSuG6bnQs=",
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "rev": "637db329424fd7e46cf4185293b9cc8c88c95394",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "type": "github"
+      }
+    },
+    "import-tree": {
+      "locked": {
+        "lastModified": 1752730890,
+        "narHash": "sha256-GES8fapSLGz36MMPRVNkSUWXUTtqvGQNXHjRmRLfJUY=",
+        "owner": "vic",
+        "repo": "import-tree",
+        "rev": "6ebb8cb87987b20264c09296166543fd3761d274",
+        "type": "github"
+      },
+      "original": {
+        "owner": "vic",
+        "repo": "import-tree",
+        "type": "github"
+      }
+    },
+    "nix": {
+      "inputs": {
+        "flake-compat": [
+          "devenv",
+          "flake-compat"
+        ],
+        "flake-parts": "flake-parts",
+        "git-hooks-nix": [
+          "devenv",
+          "git-hooks"
+        ],
+        "nixpkgs": [
+          "devenv",
+          "nixpkgs"
+        ],
+        "nixpkgs-23-11": [
+          "devenv"
+        ],
+        "nixpkgs-regression": [
+          "devenv"
+        ]
+      },
+      "locked": {
+        "lastModified": 1755029779,
+        "narHash": "sha256-3+GHIYGg4U9XKUN4rg473frIVNn8YD06bjwxKS1IPrU=",
+        "owner": "cachix",
+        "repo": "nix",
+        "rev": "b0972b0eee6726081d10b1199f54de6d2917f861",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "ref": "devenv-2.30",
+        "repo": "nix",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1751498133,
+        "narHash": "sha256-QWJ+NQbMU+NcU2xiyo7SNox1fAuwksGlQhpzBl76g1I=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "d55716bb59b91ae9d1ced4b1ccdea7a442ecbfdb",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs-lib": {
+      "locked": {
+        "lastModified": 1753579242,
+        "narHash": "sha256-zvaMGVn14/Zz8hnp4VWT9xVnhc8vuL3TStRqwk22biA=",
+        "owner": "nix-community",
+        "repo": "nixpkgs.lib",
+        "rev": "0f36c44e01a6129be94e3ade315a5883f0228a6e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-community",
+        "repo": "nixpkgs.lib",
+        "type": "github"
+      }
+    },
+    "nixpkgs_2": {
+      "locked": {
+        "lastModified": 1750441195,
+        "narHash": "sha256-yke+pm+MdgRb6c0dPt8MgDhv7fcBbdjmv1ZceNTyzKg=",
+        "owner": "cachix",
+        "repo": "devenv-nixpkgs",
+        "rev": "0ceffe312871b443929ff3006960d29b120dc627",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "ref": "rolling",
+        "repo": "devenv-nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs_3": {
+      "locked": {
+        "lastModified": 1722073938,
+        "narHash": "sha256-OpX0StkL8vpXyWOGUD6G+MA26wAXK6SpT94kLJXo6B4=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "e36e9f57337d0ff0cf77aceb58af4c805472bfae",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs_4": {
+      "locked": {
+        "lastModified": 1755783167,
+        "narHash": "sha256-gj7qvMNz7YvhjYxNq4I370cAYIZEw2PbVs5BSwaLrD4=",
+        "owner": "cachix",
+        "repo": "devenv-nixpkgs",
+        "rev": "4a880fb247d24fbca57269af672e8f78935b0328",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "ref": "rolling",
+        "repo": "devenv-nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs_5": {
+      "locked": {
+        "lastModified": 1754340878,
+        "narHash": "sha256-lgmUyVQL9tSnvvIvBp7x1euhkkCho7n3TMzgjdvgPoU=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "cab778239e705082fe97bb4990e0d24c50924c04",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "allfollow": "allfollow",
+        "devenv": "devenv",
+        "devshell": "devshell",
+        "flake-file": "flake-file",
+        "flake-parts": "flake-parts_2",
+        "import-tree": "import-tree",
+        "nixpkgs": "nixpkgs_4",
+        "rust-overlay": "rust-overlay_2",
+        "systems": "systems_2",
+        "treefmt-nix": "treefmt-nix"
+      }
+    },
+    "rust-overlay": {
+      "inputs": {
+        "nixpkgs": [
+          "allfollow",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1751596734,
+        "narHash": "sha256-1tQOwmn3jEUQjH0WDJyklC+hR7Bj+iqx6ChtRX2QiPA=",
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "rev": "e28ba067a9368286a8bc88b68dc2ca92181a09f0",
+        "type": "github"
+      },
+      "original": {
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "type": "github"
+      }
+    },
+    "rust-overlay_2": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1756003222,
+        "narHash": "sha256-lmEMhIIbjt8Wp1EYbNqCojuU9ygyDFv8Tu0X1k8qIMc=",
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "rev": "88ceedecde53e809b4bf8b5fd10d181889d9bac7",
+        "type": "github"
+      },
+      "original": {
+        "owner": "oxalica",
+        "repo": "rust-overlay",
+        "type": "github"
+      }
+    },
+    "systems": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    },
+    "systems_2": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    },
+    "treefmt-nix": {
+      "inputs": {
+        "nixpkgs": "nixpkgs_5"
+      },
+      "locked": {
+        "lastModified": 1755934250,
+        "narHash": "sha256-CsDojnMgYsfshQw3t4zjRUkmMmUdZGthl16bXVWgRYU=",
+        "owner": "numtide",
+        "repo": "treefmt-nix",
+        "rev": "74e1a52d5bd9430312f8d1b8b0354c92c17453e5",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "treefmt-nix",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

···
+# DO-NOT-EDIT. This file was auto-generated using github:vic/flake-file.
+# Use `nix run .#write-flake` to regenerate it.
+{
+
+  outputs = inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; } (inputs.import-tree ./nix);
+
+  nixConfig = {
+    extra-substituters = "https://devenv.cachix.org";
+    extra-trusted-public-keys = "devenv.cachix.org-1:w1cLUi8dv3hnoSPGAuibQv+f9TZLr6cv/Hm9XgU50cw=";
+  };
+
+  inputs = {
+    allfollow = {
+      url = "github:spikespaz/allfollow";
+    };
+    devenv = {
+      url = "github:cachix/devenv";
+    };
+    devshell = {
+      url = "github:numtide/devshell";
+    };
+    flake-file = {
+      url = "github:vic/flake-file";
+    };
+    flake-parts = {
+      url = "github:hercules-ci/flake-parts";
+    };
+    import-tree = {
+      url = "github:vic/import-tree";
+    };
+    nixpkgs = {
+      url = "github:cachix/devenv-nixpkgs/rolling";
+    };
+    rust-overlay = {
+      inputs = {
+        nixpkgs = {
+          follows = "nixpkgs";
+        };
+      };
+      url = "github:oxalica/rust-overlay";
+    };
+    systems = {
+      url = "github:nix-systems/default";
+    };
+    treefmt-nix = {
+      url = "github:numtide/treefmt-nix";
+    };
+  };
+
+}

nix/dendritic.nix

···
+{ inputs, lib, ... }:
+{
+  imports = [
+    inputs.flake-file.flakeModules.dendritic
+  ];
+
+  flake-file.outputs = lib.mkForce ''
+    inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; } (inputs.import-tree ./nix)
+  '';
+
+  perSystem.treefmt = {
+    programs.rustfmt.enable = true;
+    settings.on-unmatched = "warn";
+  };
+}

nix/devenv.nix

···
+{ inputs, ... }:
+{
+  flake-file.inputs = {
+    nixpkgs.url = "github:cachix/devenv-nixpkgs/rolling";
+    devenv.url = "github:cachix/devenv";
+  };
+
+  flake-file.nixConfig = {
+    extra-trusted-public-keys = "devenv.cachix.org-1:w1cLUi8dv3hnoSPGAuibQv+f9TZLr6cv/Hm9XgU50cw=";
+    extra-substituters = "https://devenv.cachix.org";
+  };
+
+  imports = [
+    inputs.devenv.flakeModule
+  ];
+
+  perSystem =
+    { config, pkgs, ... }:
+    let
+      app = config.devshells.default.languages.rust.import ./crates { };
+      wrapped = pkgs.stdenvNoCC.mkDerivation {
+        name = "van-wrapped";
+        nativeBuildInputs = [pkgs.makeWrapper];
+        phases = ["wrap"];
+        wrap = ''
+          wrapProgram ${app}/bin/van $out/bin/van --prefix PATH : ${pkgs.lib.makeBinPath [pkgs.carapace]}
+        '';
+      };
+    in
+    {
+      packages.default = wrapped;
+      devenv.shells.default = {
+        languages.rust.enable = true;
+        packages = [
+          pkgs.carapace
+        ];
+      };
+    };
+
+}