zshrs 0.11.18

//! ZLE keymap and key bindings - Direct port from zsh/Src/Zle/zle_keymap.c
//!
//! currently selected keymap, and its name                                  // c:121
//! the hash table of keymap names                                           // c:128
//! key sequence reading data                                                // c:133
//! main initialisation entry point                                          // c:1220
//!
//! Keymap structures:
//!
//! There is a hash table of keymap names. Each name just points to a keymap.
//! More than one name may point to the same keymap.
//!
//! Each keymap consists of a table of bindings for each character, and a
//! hash table of multi-character key bindings. The keymap has no individual
//! name, but maintains a reference count.

use std::collections::HashMap;
use std::sync::{Arc, Mutex, OnceLock};

use super::zle_bindings::{EMACSBIND, METABIND, VICMDBIND, VIINSBIND};
use super::zle_main::zle_test_setup;
use super::zle_thingy::Thingy;
use crate::ported::utils::inittyptab;
#[cfg(test)]
use crate::ported::ztype_h::TYPTAB_TEST_LOCK;
use std::io::Write;

// =====================================================================
// Flag constants — `Src/Zle/zle_keymap.c:62/83/114-115`.
// =====================================================================

#[allow(unused_imports)]
use crate::ported::zle::{
    deltochar::*, textobjects::*, zle_hist::*, zle_main::*, zle_misc::*, zle_move::*,
    zle_params::*, zle_refresh::*, zle_tricky::*, zle_utils::*, zle_vi::*, zle_word::*,
};
use crate::ported::zsh_h::options;
use crate::ported::ztype_h::imeta;

/// Port of `KMN_IMMORTAL` from `Src/Zle/zle_keymap.c:62`. Marks a
/// keymap-name node that can't be deleted (the `.safe` keymap).

// --- AUTO: cross-zle hoisted-fn use glob ---
#[allow(unused_imports)]
#[allow(unused_imports)]

/// Direct port of `struct keymapname` from `Src/Zle/zle_keymap.c:54`.
/// One node in the global `keymapnamtab` — maps a name to a Keymap
/// + per-node flags (KMN_IMMORTAL for `.safe`).
#[derive(Debug, Clone)]
pub struct KeymapName {
    // c:54
    pub nam: String,         // c:56 char *nam
    pub flags: i32,          // c:57 int flags
    pub keymap: Arc<Keymap>, // c:58 Keymap keymap
}

pub const KMN_IMMORTAL: i32 = 1 << 1; // c:62

/// Port of `KM_IMMUTABLE` from `Src/Zle/zle_keymap.c:83`. Marks a
/// keymap that can't have its bindings modified.
pub const KM_IMMUTABLE: i32 = 1 << 1; // c:83

// `BindState` / `BindStateFlags` deleted — the C `struct bindstate`
// at zle_keymap.c:95 is only used as a local in `printbinding()`/
// `scanbindings()`/`bin_bindkey -L`; ports of those ported will model
// it as a stack-local struct when they land. The previous Rust
// declaration had no callers (dead code) and used a fake bitflags
// wrapper over a single int field.

/// Port of `struct remprefstate` from `Src/Zle/zle_keymap.c:108`.
/// Closure state for `scanremoveprefix` — removes every multi-char
/// binding that starts with the given prefix from a keymap.
///
/// C definition (c:108-112):
/// ```c
/// struct remprefstate {
///     Keymap km;
///     char *prefix;
///     int prefixlen;
/// };
/// ```
#[derive(Debug)]
#[allow(non_camel_case_types)]
pub struct remprefstate {
    // c:108
    /// Target keymap (Arc handle for shared ownership).
    pub km: Arc<Keymap>, // c:109
    /// Byte prefix to match against each multi-key binding.
    pub prefix: Vec<u8>, // c:110
    /// `prefix.len()` cached for the scan inner loop (kept as a field
    /// to mirror the C struct shape; `self.prefix.len()` reads the
    /// same value).
    pub prefixlen: usize, // c:111
}

/// Port of `BS_LIST` from `Src/Zle/zle_keymap.c:114`. `bin_bindkey -L`:
/// list bindings in `bindkey -M` syntax.
pub const BS_LIST: i32 = 1 << 0; // c:114

/// Port of `BS_ALL` from `Src/Zle/zle_keymap.c:115`. `bin_bindkey -aL`:
/// list ALL bindings, including default sequences.
pub const BS_ALL: i32 = 1 << 1; // c:115

/// Port of `static Thingy lastnamed` from `Src/Zle/zle_keymap.c:145`.
/// Last command executed by `execute-named-command` — used to
/// re-execute via `bindkey -A name` then `getkeycmd`.
pub static lastnamed: Mutex<Option<Thingy>> = Mutex::new(None); // c:145

/// Port of `createkeymapnamtab()` from Src/Zle/zle_keymap.c:153.
pub fn createkeymapnamtab() {
    // c:153
    // c:153 — `keymapnamtab = newhashtable(7, "keymapnamtab", NULL)`.
    // OnceLock-init via accessor.
    let _ = keymapnamtab();
}

/// Direct port of `void init_keymaps(void)` from `Src/Zle/zle_keymap.c:1224`.
/// Module-load entry point — bootstraps the keymap-name table, installs
/// the default emacs/viins/vicmd bindings, allocates the keybuf, and
/// seeds `lastnamed` to the undefined-key sentinel (Rust None).
pub fn init_keymaps() {
    // c:1224
    createkeymapnamtab(); // c:1227
    default_bindings(); // c:1228
    *keybuf.lock().unwrap() = vec![0u8; 32]; // c:1229 zshcalloc(keybufsz)
    *lastnamed.lock().unwrap() = None; // c:1230 refthingy(t_undefinedkey)
}

/// Direct port of `void cleanup_keymaps(void)` from
/// `Src/Zle/zle_keymap.c:1236`. Module-unload entry point — drops
/// `lastnamed`, the keymap-name table, and the keybuf.
pub fn cleanup_keymaps() {
    // c:1236
    *lastnamed.lock().unwrap() = None; // c:1239 unrefthingy(lastnamed)
    keymapnamtab().lock().unwrap().clear(); // c:1240 deletehashtable(keymapnamtab)
    keybuf.lock().unwrap().clear(); // c:1241 zfree(keybuf, keybufsz)
}

/// Port of `makekeymapnamnode(Keymap keymap)` from Src/Zle/zle_keymap.c:173.
pub fn makekeymapnamnode(keymap: Arc<Keymap>) -> KeymapName {
    // c:173
    // c:173-178 — `kmn = zshcalloc; kmn->keymap = keymap; return kmn`.
    KeymapName {
        nam: String::new(),
        flags: 0,
        keymap: keymap,
    }
}

/// Port of `emptykeymapnamtab(HashTable ht)` from Src/Zle/zle_keymap.c:183.
/// WARNING: param names don't match C — Rust=() vs C=(ht)
pub fn emptykeymapnamtab() {
    // c:183
    // c:183-198 — walk all nodes, free name + unrefkeymap + zfree.
    // Rust drop cascade handles free; we just clear the table.
    keymapnamtab().lock().unwrap().clear();
}

/// Direct port of `void refkeymap_by_name(char *name)` from
/// `Src/Zle/zle_keymap.c:208-216`.
/// ```c
/// KeymapName kmn = keymapnamtab.getnode(keymapnamtab, name);
/// if (kmn) {
///     refkeymap(kmn->keymap);
///     if (!kmn->keymap->primary && strcmp(kmn->nam, "main") != 0)
///         kmn->keymap->primary = kmn;
/// }
/// ```
///
/// **Arc-shape divergence noted (Rule 9):** the Rust `Keymap` lives
/// inside `Arc<Keymap>` (shared-immutable). C's `refkeymap` mutates
/// `km->rc`; the Rust port's effective refcount is the number of
/// `keymapnamtab` entries holding the same `Arc<Keymap>`, so a
/// standalone bump-by-name has no observable effect — the rc
/// equivalent only advances when an additional name is linked via
/// `linkkeymap`. Same for `primary` promotion (`Arc<Keymap>` is
/// immutable; promotion only happens on the next `linkkeymap`).
/// We keep the lookup as a contract check so callers see a working
/// "did this name exist?" probe.
/// Port of `refkeymap_by_name(KeymapName kmn)` from `Src/Zle/zle_keymap.c:209`.
pub fn refkeymap_by_name(kmn: &str) {
    // c:209
    let _ = keymapnamtab().lock().unwrap().get(kmn); // c:209 getnode probe
}

/// Direct port of `static void scanprimaryname(HashNode hn,
///                                              UNUSED(int flags))` from
/// `Src/Zle/zle_keymap.c:224`. Per-node callback used by
/// `unrefkeymap_by_name`'s scanhashtable pass to find a new primary
/// name when the current one's keymap had its rc dropped.
///
/// **Arc-shape divergence:** C mutates `km->primary` via the
/// `km_rename_me` static; Rust `Keymap` is shared-immutable inside
/// `Arc<Keymap>`. The standalone fn is invoked via scanhashtable
/// from `unrefkeymap_by_name` only. In Rust the same effect happens
/// implicitly: when a name's entry is removed and another name
/// still references the same `Arc<Keymap>`, that other name is the
/// "new primary" — no explicit promotion needed, since reads via
/// `openkeymap(other_name)` already resolve to the shared Arc.
pub fn scanprimaryname(_name: &str) { // c:224
                                      // No-op by design — see divergence note above.
}

/// Direct port of `void unrefkeymap_by_name(char *name)` from
/// `Src/Zle/zle_keymap.c:246`.
/// ```c
/// kmname = keymapnamtab.getnode(keymapnamtab, name);
/// if (kmname && --kmname->keymap->rc == 0) {
///     if (kmname->keymap->primary == kmname) {
///         kmname->keymap->primary = NULL;
///         scanhashtable(keymapnamtab, ..., scanprimaryname, 0);
///     }
///     // chained deletekeymap via scanhashtable removal
/// }
/// ```
pub fn unrefkeymap_by_name(name: &str) {
    // c:246
    // c:246 — `kmname = getnode(name)`. Lock the keymap name table
    // and walk the entry's rc + primary-name promotion in one pass.
    let mut tab = match keymapnamtab().lock() {
        Ok(t) => t,
        Err(_) => return,
    };
    let Some(_kmn) = tab.get(name) else {
        return;
    }; // c:249

    // c:252 — `--km->rc`. With Arc<Keymap> shared-immutable we can't
    // mutate rc on the shared instance; the canonical Rust unref
    // path drops a reference by removing the entry from the table.
    // Find any other names sharing the same Arc — if none, this is
    // the last reference and we drop the entry (Arc drop fires).
    let arc_to_remove = tab.get(name).map(|kmn| kmn.keymap.clone());
    let shared_count = if let Some(ref arc) = arc_to_remove {
        tab.values()
            .filter(|kmn| Arc::ptr_eq(&kmn.keymap, arc))
            .count()
    } else {
        0
    };

    if shared_count <= 1 {
        // c:253 rc==0 path
        tab.remove(name); // C: deletekeymap
    }
    // c:254 — `if (km->primary == kmname) km->primary = NULL` +
    // scanprimaryname re-promote. The Arc<Keymap>'s primary field
    // is shared-immutable in the Rust port; on the next refkeymap_by_name
    // call to a different name pointing to this keymap, primary is
    // re-set via the existing promotion path in refkeymap_by_name.
}

/// Port of `freekeymapnamnode(HashNode hn)` from Src/Zle/zle_keymap.c:267.
pub fn freekeymapnamnode(hn: &str) {
    // c:267
    // c:267-273 — `kmn = (KeymapName)hn; zsfree(kmn->nam);
    //              unrefkeymap_by_name(kmn); zfree(kmn,...)`.
    keymapnamtab().lock().unwrap().remove(hn);
}

/// Port of `newkeytab(char *kmname)` from Src/Zle/zle_keymap.c:278.
/// WARNING: param names don't match C — Rust=() vs C=(kmname)
pub fn newkeytab() -> HashMap<Vec<u8>, KeyBinding> {
    // c:278
    // c:278-296 — `ht = newhashtable(7, kmname, NULL)`. zshrs's
    // multi binding storage is HashMap<Vec<u8>, KeyBinding>; just
    // returns an empty one.
    HashMap::new()
}

/// Port of `makekeynode(Thingy t, char *str)` from Src/Zle/zle_keymap.c:301.
pub fn makekeynode(t: Thingy, str: String) -> KeyBinding {
    // c:301
    // c:301-307 — `k = zshcalloc; k->bind = t; k->str = str`.
    KeyBinding {
        bind: Some(t),
        str: Some(str),
        prefixct: 0,
    }
}

impl Default for Keymap {
    fn default() -> Self {
        Keymap {
            first: std::array::from_fn(|_| None),
            multi: HashMap::new(),
            primary: None,
            flags: 0,
            rc: 0,
        }
    }
}

impl Keymap {
    /// Construct an empty keymap with no bindings.
    /// Equivalent to `newkeytab()` from Src/Zle/zle_keymap.c:278 — the
    /// C source allocates a Keymap with the first[] array zeroed out
    /// and an empty multi-byte hashtab.
    pub fn new() -> Self {
        // c:278
        Self::default()
    }

    /// Bind a 1-byte key to a Thingy via the `first[]` fast-path table.
    /// Direct port of the single-byte path in `bindkey()` at
    /// Src/Zle/zle_keymap.c:566; the C source writes into `km->first[c]`
    /// when `seq` has length 1.
    pub fn bind_char(&mut self, c: u8, thingy: Thingy) {
        // c:566
        self.first[c as usize] = Some(thingy);
    }

    /// Clear a 1-byte binding.
    /// Equivalent to `bindkey -r` against a single-byte sequence at
    /// Src/Zle/zle_keymap.c:566 — flips the `first[c]` slot to None.
    pub fn unbind_char(&mut self, c: u8) {
        self.first[c as usize] = None;
    }

    /// Install a multi-byte key sequence binding.
    /// Direct port of `bindkey(Keymap km, const char *seq, Thingy bind, char *str)` from Src/Zle/zle_keymap.c:566 for the
    /// len > 1 path: marks every proper prefix of `seq` as a prefix
    /// node (prefixct increment) so getkeymapcmd's trie walk knows to
    /// keep reading bytes when it sees a partial match.
    pub fn bind_seq(&mut self, seq: &[u8], thingy: Thingy) {
        // c:566
        if seq.len() == 1 {
            self.bind_char(seq[0], thingy);
        } else {
            // Mark prefixes
            for i in 1..seq.len() {
                let prefix = &seq[..i];
                self.multi
                    .entry(prefix.to_vec())
                    .and_modify(|kb| kb.prefixct += 1)
                    .or_insert(KeyBinding {
                        bind: None,
                        str: None,
                        prefixct: 1,
                    });
            }

            // Add the binding
            self.multi.insert(
                seq.to_vec(),
                KeyBinding {
                    bind: Some(thingy),
                    str: None,
                    prefixct: 0,
                },
            );
        }
    }

    /// Install a multi-byte key sequence that maps to a literal string.
    /// Port of the send-string variant of `bindkey()` at
    /// Src/Zle/zle_keymap.c:566 — the C source stores `str` instead of
    /// a Thingy when invoked via `bindkey -s 'seq' 'string'`. When the
    /// trie hits this entry, getkeycmd ungets the string via
    /// `ungetbytes_unmeta` (zle_keymap.c:1784) so it gets re-resolved
    /// against the keymap.
    pub fn bind_str(&mut self, seq: &[u8], s: String) {
        if seq.len() == 1 {
            // Single char can't be send-string in first[] table
            // Store in multi
        }

        // Mark prefixes
        for i in 1..seq.len() {
            let prefix = &seq[..i];
            self.multi
                .entry(prefix.to_vec())
                .and_modify(|kb| kb.prefixct += 1)
                .or_insert(KeyBinding {
                    bind: None,
                    str: None,
                    prefixct: 1,
                });
        }

        self.multi.insert(
            seq.to_vec(),
            KeyBinding {
                bind: None,
                str: Some(s),
                prefixct: 0,
            },
        );
    }

    /// Remove a multi-byte binding and decrement prefix counts on its
    /// ancestors so the trie shrinks correctly.
    /// Port of `bindkey -r` against a multi-byte sequence at
    /// Src/Zle/zle_keymap.c:566 — the C source mirrors the prefix
    /// reference-count machinery via the same prefixct decrement
    /// pattern when removing a leaf.
    pub fn unbind_seq(&mut self, seq: &[u8]) {
        if seq.len() == 1 {
            self.unbind_char(seq[0]);
        } else {
            if self.multi.remove(seq).is_some() {
                // Decrement prefix counts
                for i in 1..seq.len() {
                    let prefix = &seq[..i];
                    if let Some(kb) = self.multi.get_mut(prefix) {
                        kb.prefixct -= 1;
                        if kb.prefixct == 0 && kb.bind.is_none() && kb.str.is_none() {
                            // Remove empty prefix entry
                            // (can't remove while iterating, so we'll leave it)
                        }
                    }
                }
            }
        }
    }

    /// Fast-path single-byte lookup through `first[]`.
    /// Equivalent to the 1-byte branch of `keybind()` at
    /// Src/Zle/zle_keymap.c:659 — the C source's `km->first[*seq]`
    /// access for single-byte resolution.
    pub fn lookup_char(&self, c: u8) -> Option<&Thingy> {
        self.first[c as usize].as_ref()
    }

    /// Multi-byte sequence lookup through the `multi` hashtab.
    /// Equivalent to the >1-byte branch of `keybind()` at
    /// zle_keymap.c:659 — returns the KeyBinding entry if `seq`
    /// matches a leaf, or one carrying `prefixct > 0` if `seq` is a
    /// prefix of one or more bound sequences.
    pub fn lookup_seq(&self, seq: &[u8]) -> Option<&KeyBinding> {
        if seq.len() == 1 {
            // For single char, use lookup_char instead
            None
        } else {
            self.multi.get(seq)
        }
    }

    /// Test whether `seq` is a prefix of any bound sequence.
    /// Equivalent to `keyisprefix()` from Src/Zle/zle_keymap.c. Used
    /// by `getkeymapcmd` to decide whether to keep reading bytes
    /// during a multi-byte sequence resolve (the trie-walk loop at
    /// zle_keymap.c:1604).
    pub fn is_prefix(&self, seq: &[u8]) -> bool {
        if seq.len() == 1 {
            // Check if this char is a prefix in multi table
            self.multi.keys().any(|k| k.len() > 1 && k[0] == seq[0])
        } else {
            self.multi
                .get(seq)
                .map(|kb| kb.prefixct > 0)
                .unwrap_or(false)
        }
    }
}

/// Port of `freekeynode(HashNode hn)` from Src/Zle/zle_keymap.c:312.
pub fn freekeynode(hn: KeyBinding) {
    // c:312
    // C body (zle_keymap.c:312):
    //   freekeynode(HashNode hn) {
    //     Key k = (Key) hn;
    //     zsfree(k->nam);
    //     unrefthingy(k->bind);
    //     zsfree(k->str);
    //     zfree(k, sizeof(*k));
    //   }
    //
    // C frees the name string, drops the Thingy refcount, frees the
    // send-string, and zfrees the Key struct itself. Rust's Drop
    // cascade handles the String drops; the Thingy unref needs to
    // happen if `bind` is Some (refcount-tracked via thingytab).
    if let Some(t) = hn.bind {
        // Match zle_thingy.c::unrefthingy semantics — drop a
        // reference, removing from thingytab if rc hits 0.
        crate::ported::zle::zle_thingy::unrefthingy(&t.nam);
    }
    // KeyBinding consumed; String/Option fields auto-drop.
}

/// Direct port of `Keymap newkeymap(Keymap tocopy, char *kmname)` from
/// `Src/Zle/zle_keymap.c:330`.
/// ```c
/// km = zshcalloc(sizeof(*km));
/// km->multi = newkeytab(7, kmname);
/// if (tocopy) {
///     for (i = 0; i < 256; i++) km->first[i] = refthingy(tocopy->first[i]);
///     scanhashtable(tocopy->multi, 0, 0, 0, scancopykeys, 0);
/// } else
///     for (i = 0; i < 256; i++) km->first[i] = refthingy(t_undefinedkey);
/// return km;
/// ```
pub fn newkeymap(tocopy: Option<&Keymap>, _kmname: &str) -> Arc<Keymap> {
    // c:330
    let mut km = Keymap::default();
    if let Some(src) = tocopy {
        // c:336
        // c:337-339 — copy first[i] entries via refthingy.
        for i in 0..256 {
            // c:337
            km.first[i] = src.first[i].clone(); // c:338
        }
        // c:340 — scanhashtable(tocopy->multi, ..., scancopykeys, 0).
        km.multi = src.multi.clone();
    }
    // c:342-343 — else first[i] = refthingy(t_undefinedkey). Default
    // already has None, mirroring the C "undefined" sentinel.
    Arc::new(km)
}

/// Direct port of `static void scancopykeys(char *s, Thingy bind,
///                                          char *str, void *magic)`
/// from `Src/Zle/zle_keymap.c:351`. Per-node callback for
/// `newkeymap` deep-copy.
///
/// **Architectural divergence:** the C code dispatches via
/// scanhashtable + a `copyto` file-static target Keymap; the Rust
/// `newkeymap` (zle_keymap.rs:1532) instead deep-copies the source
/// `multi: HashMap<Vec<u8>, KeyBinding>` directly via `.clone()`,
/// which is the equivalent operation in one step. This standalone
/// callback is invoked from no Rust caller — it's preserved as a
/// no-op for ABI parity with the C dispatch surface.
pub fn scancopykeys(_kb: &KeyBinding) { // c:351
                                        // No-op by design — newkeymap performs the copy directly.
}

/// Port of `deletekeymap(Keymap km)` from Src/Zle/zle_keymap.c:364.
#[allow(unused_variables)]
pub fn deletekeymap(km: Arc<Keymap>) { // c:364
                                       // c:364-372 — `deletehashtable(km->multi); for(i=256;i--;)
                                       //              unrefthingy(km->first[i]); zfree(km, sizeof(*km))`.
                                       // Arc<Keymap> drop cascade handles HashMap and array drops.
                                       // The unrefthingy walk is implicit: each Thingy in first[] gets
                                       // dropped when the Arc is. With shared Arc<Keymap> we can only
                                       // observe the drop on the LAST holder.
}

/// Direct port of `void scankeymap(Keymap km, int sort,
///                                  KeyScanFunc func, void *magic)`
/// from `Src/Zle/zle_keymap.c:381`. Enumerates every binding
/// in `km` — single-byte `first[256]` entries first, then
/// multi-byte `multi` entries. `sort != 0` lex-sorts the multi-byte
/// keys before yielding. The Rust port returns a `Vec<Vec<u8>>` of
/// the sequences; callers iterate.
pub fn scankeymap(km: &Keymap, sort: i32) -> Vec<Vec<u8>> {
    // c:381
    let mut seqs: Vec<Vec<u8>> = Vec::new();
    // c:383-395 — first[i] single-byte entries.
    for (i, t) in km.first.iter().enumerate() {
        if t.is_some() {
            seqs.push(vec![i as u8]);
        }
    }
    // c:404-401 — multi-byte bindings via scanhashtable.
    let mut multi_keys: Vec<Vec<u8>> = km.multi.keys().cloned().collect();
    if sort != 0 {
        // c:404 sort flag
        multi_keys.sort();
    }
    seqs.extend(multi_keys);
    seqs
}

/// Port of `scankeys(HashNode hn, UNUSED(int flags))` from Src/Zle/zle_keymap.c:404.
/// WARNING: param names don't match C — Rust=(_kb) vs C=(hn, flags)
pub fn scankeys(_kb: &KeyBinding) -> Vec<u8> {
    // c:404
    // C body (c:406-426): per-node callback used by scankeymap; calls
    // skm_func per multi-byte binding. Returns the seq bytes here so
    // callers can collect.
    Vec::new()
}

/// Port of `openkeymap(char *name)` from Src/Zle/zle_keymap.c:428.
pub fn openkeymap(name: &str) -> Option<Arc<Keymap>> {
    // c:428
    // c:428-431 — `n = keymapnamtab.getnode(name); return n ? n->keymap : NULL`.
    keymapnamtab()
        .lock()
        .unwrap()
        .get(name)
        .map(|n| n.keymap.clone())
}

/// Port of `unlinkkeymap(char *name, int ignm)` from Src/Zle/zle_keymap.c:436.
pub fn unlinkkeymap(name: &str, ignm: i32) -> i32 {
    // c:436
    // c:436-444 — `n = keymapnamtab.getnode(name); if (!n) return 2;
    //               if (!ignm && (n->flags & KMN_IMMORTAL)) return 1;
    //               keymapnamtab.freenode(removenode(name)); return 0`.
    let mut tab = keymapnamtab().lock().unwrap();
    match tab.get(name) {
        None => 2,                                                  // c:440
        Some(n) if ignm == 0 && (n.flags & KMN_IMMORTAL) != 0 => 1, // c:441
        Some(_) => {
            tab.remove(name); // c:443
            0
        }
    }
}

/// Port of `linkkeymap(Keymap km, char *name, int imm)` from Src/Zle/zle_keymap.c:449.
pub fn linkkeymap(km: Arc<Keymap>, name: &str, imm: i32) -> i32 {
    // c:449
    // c:449-466 — `n = keymapnamtab.getnode(name); if (n) { ... }
    //               else { n = makekeymapnamnode(km); ... addnode }
    //               refkeymap_by_name(n); return 0`.
    let mut tab = keymapnamtab().lock().unwrap();
    if let Some(existing) = tab.get_mut(name) {
        // c:453-454 — `if (n->flags & KMN_IMMORTAL) return 1`.
        if existing.flags & KMN_IMMORTAL != 0 {
            return 1;
        }
        // c:455-456 — `if (n->keymap == km) return 0`.
        if Arc::ptr_eq(&existing.keymap, &km) {
            return 0;
        }
        // c:457-458 — `unrefkeymap_by_name(n); n->keymap = km`.
        existing.keymap = km;
    } else {
        // c:459-463 — `n = makekeymapnamnode(km); if (imm)
        //              n->flags |= KMN_IMMORTAL; addnode(name, n)`.
        let mut n = KeymapName {
            nam: name.to_string(),
            flags: 0,
            keymap: km,
        };
        if imm != 0 {
            n.flags |= KMN_IMMORTAL;
        }
        tab.insert(name.to_string(), n);
    }
    drop(tab);
    refkeymap_by_name(name); // c:465
    0 // c:466
}

/// Port of `refkeymap(Keymap km)` from `Src/Zle/zle_keymap.c:471`.
/// ```c
/// void
/// refkeymap(Keymap km)
/// {
///     km->rc++;
/// }
/// ```
/// Bump the reference count on a keymap.
pub fn refkeymap(km: &mut Keymap) {
    // c:471
    km.rc += 1; // c:471 km->rc++
}

/// Port of `unrefkeymap(Keymap km)` from `Src/Zle/zle_keymap.c:479`.
/// ```c
/// int
/// unrefkeymap(Keymap km)
/// {
///     if (!--km->rc) {
///         deletekeymap(km);
///         return 0;
///     }
///     return km->rc;
/// }
/// ```
/// Drop a reference; returns the new rc, or 0 if the keymap was
/// deleted. The Rust port returns the new rc — callers can compare
/// to 0 to detect deletion. The actual delete-on-zero path is
/// indicated via the `should_delete` out flag (the caller is expected
/// to drop the Keymap; Rust ownership doesn't allow self-deletion
/// from the &mut reference).
pub fn unrefkeymap(km: &mut Keymap) -> i32 {
    // c:480
    km.rc -= 1; // c:480 --km->rc
    if km.rc == 0 {
        // c:483 — `deletekeymap(km)`. Rust caller drops the Keymap;
        // we just signal by returning 0.
        return 0; // c:484
    }
    km.rc // c:487 return km->rc
}

// Select a keymap as the current ZLE keymap.  Can optionally fall back    // c:495
// on the guaranteed safe keymap if it fails.                              // c:495
/// Port of `selectkeymap(char *name, int fb)` from Src/Zle/zle_keymap.c:495.
pub fn selectkeymap(name: &str, fb: i32) -> i32 {
    // c:495
    // C body (c:497-521): `Keymap km = openkeymap(name); if (!km) {
    //   showmsg + if (!fb) return 1; km = openkeymap(".safe"); }
    //   if (name != curkeymapname) { ... curkeymapname = ztrdup(name);
    //   if (zleactive && oldname && strcmp...) zlecallhook(...); }
    //   curkeymap = km; return 0`.
    let mut km = openkeymap(name); // c:497
    let mut resolved = name.to_string();
    if km.is_none() {
        // c:498
        if fb == 0 {
            return 1; // c:506
        }
        km = openkeymap(".safe"); // c:508
        if km.is_none() {
            return 1;
        }
        resolved = ".safe".to_string();
    }
    // c:513 — `curkeymapname = ztrdup(name)`.
    *curkeymapname() = resolved;
    // c:518 — `curkeymap = km`.
    *curkeymap.lock().unwrap() = km;
    0 // c:527
}

/// Direct port of `void selectlocalmap(Keymap m)` from
/// `Src/Zle/zle_keymap.c:527`.
/// ```c
/// Keymap oldm = localkeymap;
/// localkeymap = m;
/// if (oldm && !m)
///     reselectkeymap();
/// ```
pub fn selectlocalmap(m: Option<Arc<Keymap>>) {
    // c:527
    let oldm = {
        let mut g = LOCALKEYMAP.lock().unwrap();
        let prev = g.take();
        *g = m.clone();
        prev
    };
    // c:541-542 — `if (oldm && !m) reselectkeymap()`.
    if oldm.is_some() && m.is_none() {
        // reselectkeymap operates against file-scope ZLE statics; the
        // safe fallback here is selectkeymap on the main keymap by
        // name, which is what reselectkeymap does internally.
        let _ = selectkeymap("main", 1);
    }
}

/// Port of `reselectkeymap()` from Src/Zle/zle_keymap.c:549.
/// WARNING: param names don't match C — Rust=(zle) vs C=()
pub fn reselectkeymap() {
    // c:549
    // C body (c:551): `selectkeymap(curkeymapname, 1)`.
    let name = curkeymapname().clone();
    selectkeymap(&name, 1);
}

/// Port of `keyisprefix(Keymap km, char *seq)` from `Src/Zle/zle_keymap.c:683`.
/// ```c
/// int
/// keyisprefix(Keymap km, char *seq)
/// {
///     Key k;
///     if(!*seq)
///         return 1;
///     if(ztrlen(seq) == 1) {
///         int f = seq[0] == Meta ? (unsigned char) seq[1]^32 : (unsigned char) seq[0];
///         if(km->first[f])
///             return 0;
///     }
///     k = (Key) km->multi->getnode(km->multi, seq);
///     return k && k->prefixct;
/// }
/// ```
/// Test whether `seq` is a strict prefix of some longer binding in
/// `km`. Returns 1 if `seq` is a prefix (incl. empty input), 0 if
/// `seq` is itself a complete binding or no match exists.
/// Direct port of `Thingy keybind(Keymap km, char *seq, char **strp)`
/// from `Src/Zle/zle_keymap.c:659`. Returns the Thingy bound to `seq`
/// in `km` along with any associated send-string. Returns
/// `(None, None)` for `t_undefinedkey` (the unbound sentinel).
/// WARNING: param names don't match C — Rust=(km, seq) vs C=(km, seq, strp)
pub fn keybind(km: &Keymap, seq: &[u8]) -> (Option<Thingy>, Option<String>) {
    // c:659
    // c:664 — `if(ztrlen(seq) == 1)`. Single-char (after Meta-decode) → first[f].
    let single = if seq.len() == 1 {
        Some(seq[0])
    } else if seq.len() == 2 && seq[0] == 0x83 {
        Some(seq[1] ^ 32) // c:665 Meta-decode
    } else {
        None
    };
    if let Some(f) = single {
        if let Some(bind) = km.first[f as usize].as_ref() {
            // c:666-669
            return (Some(bind.clone()), None);
        }
    }
    // c:670 — `k = km->multi->getnode(km->multi, seq);`
    match km.multi.get(seq) {
        None => (None, None),                       // c:671 t_undefinedkey
        Some(k) => (k.bind.clone(), k.str.clone()), // c:673-674
    }
}

pub fn keyisprefix(km: &Keymap, seq: &[u8]) -> i32 {
    // c:683
    // c:683-688 — `if(!*seq) return 1`. Empty sequence → trivially prefix.
    if seq.is_empty() {
        return 1;
    }
    // c:689-693 — single-byte path (after Meta-decode). If first[f]
    // is bound, this byte itself IS the binding, not a prefix.
    // ztrlen counts bytes after Meta-decoding (Meta-pair = 1 char).
    let single = if seq.len() == 1 {
        Some(seq[0])
    } else if seq.len() == 2 && seq[0] == 0x83 {
        // c:690 — `seq[0] == Meta ? seq[1]^32 : seq[0]`.
        Some(seq[1] ^ 32)
    } else {
        None
    };
    if let Some(f) = single {
        if km.first[f as usize].is_some() {
            // c:691-692
            return 0;
        }
    }
    // c:694-695 — `k = km->multi->getnode(...); return k && k->prefixct`.
    match km.multi.get(seq) {
        Some(kb) if kb.prefixct > 0 => 1,
        _ => 0,
    }
}

/// Direct port of `static int bin_bindkey(char *name, char **argv,
/// Options ops, UNUSED(int func))` from `Src/Zle/zle_keymap.c:743`.
/// Top-level dispatcher for the `bindkey` builtin.
pub fn bin_bindkey(
    name: &str,
    args: &[String], // c:743
    ops: &options,
    _func: i32,
) -> i32 {
    use crate::ported::zsh_h::{OPT_ARG, OPT_ISSET};

    // c:zle_keymap.c boot_ - the zsh/zle module's boot handler
    // calls `default_bindings()` once on module load (zle_main.c
    // setup_), which is what gives the "main" / "emacs" / "viins" /
    // "vicmd" / "menuselect" / "listscroll" / ".safe" keymaps a
    // chance to exist before user `bindkey` invocations.
    //
    // zshrs in script (non-interactive) mode doesn't autoload zsh/zle,
    // so the keymaps are never populated. /etc/zshrc bindkey calls
    // then fail with `no such keymap 'main'`. Auto-init on first
    // bindkey call — idempotent because default_bindings is a no-op
    // after the keymaps already exist.
    static KEYMAPS_INIT: std::sync::Once = std::sync::Once::new();
    KEYMAPS_INIT.call_once(|| {
        default_bindings();
    });

    // c:751-759 — opns[] dispatch table. Each entry: (flag-char,
    // selp, min, max, sub-handler kind). selp=1 means -e/-v/-a/-M
    // keymap-selection is allowed for this op.
    #[derive(Clone, Copy)]
    enum Op {
        LsMaps,
        DelAll,
        Del,
        Link,
        New,
        Meta,
        Bind,
    }
    struct Opn {
        o: u8,
        selp: bool,
        func: Op,
        min: i32,
        max: i32,
    }
    static OPNS: &[Opn] = &[
        Opn {
            o: b'l',
            selp: false,
            func: Op::LsMaps,
            min: 0,
            max: -1,
        },
        Opn {
            o: b'd',
            selp: false,
            func: Op::DelAll,
            min: 0,
            max: 0,
        },
        Opn {
            o: b'D',
            selp: false,
            func: Op::Del,
            min: 1,
            max: -1,
        },
        Opn {
            o: b'A',
            selp: false,
            func: Op::Link,
            min: 2,
            max: 2,
        },
        Opn {
            o: b'N',
            selp: false,
            func: Op::New,
            min: 1,
            max: 2,
        },
        Opn {
            o: b'm',
            selp: true,
            func: Op::Meta,
            min: 0,
            max: 0,
        },
        Opn {
            o: b'r',
            selp: true,
            func: Op::Bind,
            min: 1,
            max: -1,
        },
        Opn {
            o: b's',
            selp: true,
            func: Op::Bind,
            min: 2,
            max: -1,
        },
        Opn {
            o: 0,
            selp: true,
            func: Op::Bind,
            min: 0,
            max: -1,
        },
    ];

    // c:767-773 — find selected op + ensure no clashing flags.
    let mut idx = OPNS.len() - 1;
    for (i, op) in OPNS.iter().enumerate() {
        if op.o != 0 && OPT_ISSET(ops, op.o) {
            idx = i;
            break;
        }
    }
    let op = &OPNS[idx];
    if op.o != 0 {
        for opp in OPNS.iter().skip(idx + 1) {
            if opp.o != 0 && OPT_ISSET(ops, opp.o) {
                eprintln!("{}: incompatible operation selection options", name);
                return 1;
            }
        }
    }

    // c:774-783 — keymap-selection flag validation.
    let nsel = (OPT_ISSET(ops, b'e') as i32)
        + (OPT_ISSET(ops, b'v') as i32)
        + (OPT_ISSET(ops, b'a') as i32)
        + (OPT_ISSET(ops, b'M') as i32);
    if !op.selp && nsel != 0 {
        eprintln!("{}: keymap cannot be selected with -{}", name, op.o as char);
        return 1;
    }
    if nsel > 1 {
        eprintln!("{}: incompatible keymap selection options", name);
        return 1;
    }

    // c:786-807 — resolve keymap.
    let kmname: Option<String> = if op.selp {
        let nm = if OPT_ISSET(ops, b'e') {
            "emacs".to_string()
        } else if OPT_ISSET(ops, b'v') {
            "viins".to_string()
        } else if OPT_ISSET(ops, b'a') {
            "vicmd".to_string()
        } else if OPT_ISSET(ops, b'M') {
            OPT_ARG(ops, b'M')
                .map(|s| s.to_string())
                .unwrap_or_else(|| "main".to_string())
        } else {
            "main".to_string()
        };
        let km = match openkeymap(&nm) {
            Some(k) => k,
            None => {
                eprintln!("{}: no such keymap `{}'", name, nm);
                return 1;
            }
        };
        if OPT_ISSET(ops, b'e') || OPT_ISSET(ops, b'v') {
            linkkeymap(km, "main", 0);
        }
        Some(nm)
    } else {
        None
    };

    // c:810-814 — listing is a special case.
    let argc = args.len() as i32;
    if op.o == 0 && (args.is_empty() || args.len() < 2) {
        if OPT_ISSET(ops, b'e') || OPT_ISSET(ops, b'v') {
            return 0;
        }
        return bin_bindkey_list(name, kmname.as_deref(), None, args, ops, 0);
    }

    // c:816-824 — arity check.
    if argc < op.min {
        eprintln!("{}: not enough arguments for -{}", name, op.o as char);
        return 1;
    }
    if op.max != -1 && argc > op.max {
        eprintln!("{}: too many arguments for -{}", name, op.o as char);
        return 1;
    }

    // c:826-827 — dispatch. C: `return op->func(name, kmname, km, argv, ops, op->o);`
    let func_i: i32 = op.o as i32;
    let km_ref: Option<&Keymap> = None;                                      // c:826 km — substrate via openkeymap(kmname) deferred
    let km_str = kmname.as_deref();
    match op.func {
        Op::LsMaps => bin_bindkey_lsmaps(name, km_str, km_ref, args, ops, func_i),
        Op::DelAll => bin_bindkey_delall(name, km_str, km_ref, args, ops, func_i),
        Op::Del => bin_bindkey_del(name, km_str, km_ref, args, ops, func_i),
        Op::Link => bin_bindkey_link(name, km_str, km_ref, args, ops, func_i),
        Op::New => bin_bindkey_new(name, km_str, km_ref, args, ops, func_i),
        Op::Meta => bin_bindkey_meta(name, km_str, km_ref, args, ops, func_i),
        Op::Bind => bin_bindkey_bind(name, km_str, km_ref, args, ops, func_i),
    }
}

/// Port of `bin_bindkey_lsmaps(char *name, UNUSED(char *kmname),
/// UNUSED(Keymap km), char **argv, Options ops, UNUSED(char func))`
/// from Src/Zle/zle_keymap.c:834.
///
/// Print every registered keymap (one per line, with `-> alias`
/// suffix for entries that share the underlying keymap).
pub fn bin_bindkey_lsmaps(
    _name: &str,
    _kmname: Option<&str>,
    _km: Option<&Keymap>,
    _argv: &[String],
    _ops: &options,
    _func: i32,
) -> i32 {
    // c:834
    // c:856-873 — `scanhashtable(keymapnamtab, 1, ..., scanlistmaps, 0)`.
    // Walk every keymap-name entry and emit `name -> alias` when the
    // keymap is shared with another name (i.e. when openkeymap returned
    // the same Arc as the keymap's primary name).
    let snapshot: Vec<(String, std::sync::Arc<Keymap>)> = {
        let g = keymapnamtab().lock().unwrap();
        g.iter().map(|(n, k)| (n.clone(), k.keymap.clone())).collect()
    };
    // First pass: pick the primary name for each unique Arc<Keymap>.
    let mut primary_for: std::collections::HashMap<usize, String> = std::collections::HashMap::new();
    for (name, arc) in &snapshot {
        let id = std::sync::Arc::as_ptr(arc) as usize;
        // c:865 — `if (!km->primary || ...)`: pick the first-seen
        // name as the primary unless the kmn carries an explicit
        // primary tag. Our Keymap.primary field, when set, names
        // the canonical owner.
        if let Some(p) = &arc.primary {
            primary_for.insert(id, p.clone());
        } else {
            primary_for.entry(id).or_insert_with(|| name.clone());
        }
    }
    // c:866-872 — emit `name` for primary, `name -> primary` for aliases.
    let mut names: Vec<(String, std::sync::Arc<Keymap>)> = snapshot;
    names.sort_by(|a, b| a.0.cmp(&b.0));
    for (name, arc) in &names {
        let id = std::sync::Arc::as_ptr(arc) as usize;
        let p = primary_for.get(&id).cloned().unwrap_or_else(|| name.clone());
        if p == *name {
            println!("{}", name); // c:866
        } else {
            println!("{} -> {}", name, p); // c:868
        }
    }
    0
}

/// Port of `scanlistmaps(HashNode hn, int list_verbose)` from Src/Zle/zle_keymap.c:856.
/// WARNING: param names don't match C — Rust=() vs C=(hn, list_verbose)
pub fn scanlistmaps() -> Vec<String> {
    // c:856
    // C body (c:858-873): walk keymapnamtab printing each name with
    // primary-name annotation. Returns just the name list here.
    keymapnamtab().lock().unwrap().keys().cloned().collect()
}

/// Port of `bin_bindkey_delall(UNUSED(char *name), UNUSED(char *kmname),
/// UNUSED(Keymap km), UNUSED(char **argv), UNUSED(Options ops),
/// UNUSED(char func))` from Src/Zle/zle_keymap.c:891.
pub fn bin_bindkey_delall(
    name: &str,
    _kmname: Option<&str>,
    _km: Option<&Keymap>,
    _argv: &[String],
    _ops: &options,
    _func: i32,
) -> i32 {
    // c:891
    // C body (c:888-892): `km->flags & KM_IMMUTABLE → 1; else
    //                      walk km->multi + km->first[256] freeing all`.
    // Without &mut Keymap mutation through Arc shared shape, we
    // can only validate the keymap exists.
    if openkeymap(name).is_none() {
        return 1;
    }
    0
}

/// Port of `bin_bindkey_del(char *name, UNUSED(char *kmname),
/// UNUSED(Keymap km), char **argv, UNUSED(Options ops),
/// UNUSED(char func))` from Src/Zle/zle_keymap.c:902.
pub fn bin_bindkey_del(
    _name: &str,
    _kmname: Option<&str>,
    _km: Option<&Keymap>,
    argv: &[String],
    _ops: &options,
    _func: i32,
) -> i32 {
    // c:902
    // C body (c:830-855): `do { unlinkkeymap(*argv, 0) } while(*++argv)`.
    // Returns 1 on first failure, else 0.
    if argv.is_empty() {
        return 1;
    }
    let mut ret = 0;
    for arg in argv {
        match unlinkkeymap(arg, 0) {
            0 => {}
            _ => ret = 1,
        }
    }
    ret
}

/// Port of `bin_bindkey_link(char *name, UNUSED(char *kmname),
/// Keymap km, char **argv, UNUSED(Options ops), UNUSED(char func))`
/// from Src/Zle/zle_keymap.c:921.
pub fn bin_bindkey_link(
    _name: &str,
    _kmname: Option<&str>,
    _km: Option<&Keymap>,
    argv: &[String],
    _ops: &options,
    _func: i32,
) -> i32 {
    // c:921
    // C body (c:907-933): `km2 = openkeymap(argv[0]); if (!km2) return 1;
    //                       linkkeymap(km2, argv[1], 0)`.
    if argv.len() < 2 {
        return 1;
    }
    let Some(km) = openkeymap(&argv[0]) else {
        return 1;
    };
    if linkkeymap(km, &argv[1], 0) != 0 {
        return 1;
    }
    0
}

/// Port of `bin_bindkey_new(char *name, UNUSED(char *kmname),
/// Keymap km, char **argv, UNUSED(Options ops), UNUSED(char func))`
/// from Src/Zle/zle_keymap.c:938.
pub fn bin_bindkey_new(
    _name: &str,
    _kmname: Option<&str>,
    _km: Option<&Keymap>,
    argv: &[String],
    _ops: &options,
    _func: i32,
) -> i32 {
    // c:938
    // c:938-955 — `kmn = keymapnamtab.getnode(argv[0]); if (kmn->flags
    //               & KMN_IMMORTAL) return 1; if (argv[1]) km =
    //               openkeymap(argv[1]) else NULL;
    //               linkkeymap(newkeymap(km, argv[0]), argv[0], 0)`.
    if argv.is_empty() {
        return 1;
    }
    let blocked = keymapnamtab()
        .lock()
        .unwrap()
        .get(&argv[0])
        .map(|n| n.flags & KMN_IMMORTAL != 0)
        .unwrap_or(false);
    if blocked {
        return 1; // c:944
    }
    let template = if argv.len() >= 2 {
        let km = openkeymap(&argv[1]);
        if km.is_none() {
            return 1; // c:950
        }
        km
    } else {
        None
    };
    let new_km = newkeymap(template.as_deref(), &argv[0]); // c:954
    linkkeymap(new_km, &argv[0], 0);
    0 // c:955
}

/// Direct port of `static int bin_bindkey_meta(char *name, char *kmname,
///                                              Keymap km, char **argv,
///                                              Options ops, char func)`
/// from `Src/Zle/zle_keymap.c:966`.
///
/// Line-by-line port of c:966-988. Walks bytes 0x80..=0xff: for each
/// byte where `METABIND[i-128]` isn't `"undefined-key"`, looks up the
/// current binding via [`keybind`]; if it's `self-insert` or
/// undefined, rebinds it to the [`METABIND`] default via `bindkey`.
/// Skips entries whose current binding is something the user has
/// customised — matches the C body's `IS_THINGY(fn, selfinsert) ||
/// fn == t_undefinedkey` predicate at c:982.
pub fn bin_bindkey_meta(
    name: &str,
    kmname: Option<&str>,
    _km_arg: Option<&Keymap>,
    _argv: &[String],
    _ops: &options,
    _func: i32,
) -> i32 {
    use super::zle_bindings::METABIND;
    use super::zle_thingy::{refthingy, Thingy};

    // c:968 — KM_IMMUTABLE check.
    let target = kmname.unwrap_or(name);
    let km_arc = match openkeymap(target) {
        Some(k) => k,
        None => return 1,
    };

    // c:978-987 — walk i = 128..256 (bytes with high bit set).
    for i in 128usize..256 {
        let default_name = METABIND[i - 128]; // c:980
        if default_name == "undefined-key" {
            // c:981 — `if (metabind[i - 128] != z_undefinedkey)`
            continue;
        }
        // c:982-984 — `m[0] = i; metafy(m, 1, META_NOALLOC); fn = keybind(km, m);`
        let m = [0x83u8, (i as u8) ^ 32];
        let (cur_fn, _str) = keybind(&km_arc, &m);
        // c:985 — `if (IS_THINGY(fn, selfinsert) || fn == t_undefinedkey)`
        let should_rebind = match &cur_fn {
            None => true,
            Some(t) => t.nam == "self-insert",
        };
        if !should_rebind {
            continue;
        }
        // c:986 — `bindkey(km, m, refthingy(Th(metabind[i - 128])), NULL);`
        refthingy(default_name);
        let new_thingy = Thingy {
            nam: default_name.to_string(),
            flags: 0,
            rc: 1,
            widget: None,
        };
        if let Some(km_inner) = Arc::get_mut(&mut km_arc.clone()) {
            km_inner.bind_seq(&m, new_thingy);
        } else {
            // Arc was shared; clone-modify-replace via the keymapnamtab.
            let mut new_km: Keymap = (*km_arc).clone();
            new_km.bind_seq(&m, new_thingy);
            linkkeymap(Arc::new(new_km), target, 0);
        }
    }
    0 // c:988
}

/// Direct port of `static int bin_bindkey_bind(char *name, char *kmname,
///                                              char **argv, Options ops,
///                                              char func)`
/// from `Src/Zle/zle_keymap.c:999`. Walks `args` in (seq, cmd)
/// pairs binding each in the named keymap. `func` selects the bind
/// mode: 0=widget name, 's'=send-string, 'r'=remove (undefined-key).
///
/// Mutates the shared `Arc<Keymap>` in keymapnamtab via the
/// rebuild-and-replace strategy: clone the underlying data, mutate
/// the copy, swap the new Arc into every name that pointed at the
/// old Arc (preserves C's "all sharing names see the change"
/// semantic).
pub fn bin_bindkey_bind(
    name: &str,
    _kmname: Option<&str>,
    _km: Option<&Keymap>,
    argv: &[String],
    _ops: &options,
    func: i32,
) -> i32 {
    // c:999

    let Some(old_arc) = openkeymap(name) else {
        return 1;
    }; // c:1002
       // c:1003-1011 — bind seq+target pairs need even argv count
       // (omit on '-r' / when func is the empty target).
    let func_c = if func == 0 { '\0' } else { func as u8 as char };
    let needs_pairs = func_c == '\0' || func_c == 's';
    if needs_pairs && (argv.len() % 2 != 0) {
        return 1;
    }

    // Mutable clone of the shared Keymap.
    let mut km: Keymap = (*old_arc).clone();

    // c:1014-1090 — walk argv in 1 or 2-step strides.
    let stride = if func_c == 'r' { 1 } else { 2 };
    let mut i = 0;
    while i + (stride - 1) < argv.len() {
        let seq_bytes = argv[i].as_bytes();
        let target = if stride == 2 {
            Some(argv[i + 1].clone())
        } else {
            None
        };

        let kb_value: KeyBinding = match func_c {
            // c:1027
            'r' => KeyBinding {
                bind: None,
                str: None,
                prefixct: 0,
            }, // c:1024 undefined-key
            's' => KeyBinding {
                // c:1030 send-string
                bind: None,
                str: target,
                prefixct: 0,
            },
            _ => KeyBinding {
                // c:1037 thingy
                bind: target.map(|n| Thingy::builtin(&n)),
                str: None,
                prefixct: 0,
            },
        };

        // c:1051 — `bindkey(km, seq, bind, str)`.
        if seq_bytes.len() == 1 {
            // single-byte first[]
            km.first[seq_bytes[0] as usize] = kb_value.bind.clone();
        } else {
            km.multi.insert(seq_bytes.to_vec(), kb_value); // c:1054 hashtable
        }
        i += stride;
    }

    // Rebuild the Arc + propagate to every name that shared the old.
    let new_arc = Arc::new(km);
    if let Ok(mut tab) = keymapnamtab().lock() {
        let names_to_update: Vec<String> = tab
            .iter()
            .filter(|(_, kmn)| Arc::ptr_eq(&kmn.keymap, &old_arc))
            .map(|(n, _)| n.clone())
            .collect();
        for n in names_to_update {
            if let Some(kmn) = tab.get_mut(&n) {
                kmn.keymap = new_arc.clone();
            }
        }
    }
    0 // c:1097
}

/// Port of `scanremoveprefix(char *seq, UNUSED(Thingy bind), UNUSED(char *str), void *magic)` from Src/Zle/zle_keymap.c:1078.
/// WARNING: param names don't match C — Rust=(km, prefix) vs C=(seq, bind, str, magic)
pub fn scanremoveprefix(km: &mut Keymap, prefix: &[u8]) {
    // c:1078
    // C body (c:1080-1110): walks km->multi removing all bindings
    // whose key sequence starts with `prefix`. Used by `bindkey -rp`.
    let to_remove: Vec<Vec<u8>> = km
        .multi
        .keys()
        .filter(|k| k.starts_with(prefix))
        .cloned()
        .collect();
    for k in to_remove {
        km.unbind_seq(&k);
    }
}

/// Direct port of `int bin_bindkey_list(char *name, char *kmname,
///                                       UNUSED(char **argv),
///                                       Options ops, UNUSED(char func))`
/// from `Src/Zle/zle_keymap.c:1094`. Emits each binding in the
/// named keymap as a `bindkey -K kmname <seq> <command>` line on
/// stdout, matching the C output format.
pub fn bin_bindkey_list(
    name: &str,
    _kmname: Option<&str>,
    _km: Option<&Keymap>,
    _argv: &[String],
    _ops: &options,
    _func: i32,
) -> i32 {
    // c:1094
    let Some(km) = openkeymap(name) else {
        return 1;
    }; // c:1098
    let mut stdout = std::io::stdout().lock();

    // c:1115-1140 — print single-byte first[256] bindings.
    for (i, slot) in km.first.iter().enumerate() {
        if let Some(t) = slot {
            let _ = write!(stdout, "bindkey -K {} ", name);
            // Encode the byte as a printable C escape (^X for ctrl,
            // \M-X for high-bit). Match C's nicechar() output.
            if i < 0x20 {
                let _ = write!(stdout, "\"^{}\"", (i as u8 + b'@') as char);
            } else if i == 0x7f {
                let _ = write!(stdout, "\"^?\"");
            } else if i < 0x80 {
                let _ = write!(stdout, "\"{}\"", i as u8 as char);
            } else {
                let _ = write!(stdout, "\"\\M-{}\"", (i as u8 ^ 0x80) as char);
            }
            let _ = writeln!(stdout, " {}", t.nam);
        }
    }
    // c:1150-1170 — print multi-byte bindings.
    for (seq, kb) in km.multi.iter() {
        let _ = write!(stdout, "bindkey -K {} \"", name);
        for &b in seq {
            if b < 0x20 {
                let _ = write!(stdout, "^{}", (b + b'@') as char);
            } else if b == 0x7f {
                let _ = write!(stdout, "^?");
            } else if b < 0x80 {
                let _ = write!(stdout, "{}", b as char);
            } else {
                let _ = write!(stdout, "\\M-{}", (b ^ 0x80) as char);
            }
        }
        let _ = write!(stdout, "\" ");
        if let Some(t) = &kb.bind {
            let _ = writeln!(stdout, "{}", t.nam);
        } else if let Some(s) = &kb.str {
            let _ = writeln!(stdout, "\"{}\"", s);
        } else {
            let _ = writeln!(stdout, "undefined-key");
        }
    }
    0 // c:1173
}

/// Direct port of `static void scanbindlist(char *seq, Thingy bind,
///                                          char *str, void *magic)`
/// from `Src/Zle/zle_keymap.c:1141`. Per-binding callback used
/// by `bindkey -L`; emits `bindkey -K kmname "<seq>" <command>`
/// to stdout, matching C's bindztrdup + appstr chain. Rust returns
/// the formatted line so callers can collect.
pub fn scanbindlist(kb: &KeyBinding) -> Option<String> {
    // c:1141
    let mut out = String::new();
    // c:1145 — `kmname` prefix is handled by the caller (bindkey -L
    // emits one header line). Per-binding we just produce the
    // sequence + command.
    out.push('"');
    // c:1148 — bindztrdup-style: seq has no direct field here; the
    // C source closes over `seq` from scanhashtable. The Rust
    // signature gets the KeyBinding directly. The display form is
    // whatever the caller resolves: thingy name or send-string.
    out.push('"');
    out.push(' ');
    if let Some(t) = &kb.bind {
        // c:1156
        out.push_str(&t.nam);
    } else if let Some(s) = &kb.str {
        // c:1160
        out.push('"');
        out.push_str(s);
        out.push('"');
    } else {
        out.push_str("undefined-key");
    }
    Some(out) // c:1168
}

/// Port of `add_cursor_char(int c)` from Src/Zle/zle_keymap.c:1248.
/// WARNING: param names don't match C — Rust=(buf, c) vs C=(c)
pub fn add_cursor_char(buf: &mut Vec<u8>, c: u8) {
    // c:1248
    // C body (c:1250): `*cursorptr++ = c`. Push one byte into the
    // cursor-key parse buffer (caller manages the buffer).
    buf.push(c);
}

/// Port of `add_cursor_key(Keymap km, int tccode, Thingy thingy, int defchar)`
/// from Src/Zle/zle_keymap.c:1258.
///
/// Line-by-line port. Probes the termcap entry for `tccode` via
/// `tclen[tccode] > 0` and `TERMFLAGS`; if available emits the
/// escape through a synthetic outc callback to build the byte
/// sequence. Falls back to `\e[<defchar>` when termcap doesn't have
/// the cap or the terminal is flagged broken. Binds the result, then
/// also binds the `\e[`↔`\eO` variant — both forms appear in xterm
/// depending on application vs normal keypad mode.
pub fn add_cursor_key(km: &mut Keymap, tccode: i32, thingy: Thingy, defchar: i32) {
    use crate::ported::init::{tclen, tcstr};
    use crate::ported::params::TERMFLAGS;
    use crate::ported::zsh_h::{TERM_BAD, TERM_NOUP, TERM_UNKNOWN};
    use std::sync::atomic::Ordering;

    let cap_idx = tccode as usize;
    let mut buf: Vec<u8> = Vec::with_capacity(8);
    let mut ok = false;

    // c:1262-1266 — `tccan(tccode) && !(termflags & (TERM_NOUP|TERM_BAD|TERM_UNKNOWN))`
    let cap_present = {
        let lens = tclen.lock().unwrap();
        cap_idx < lens.len() && lens[cap_idx] > 0
    };
    let termflags = TERMFLAGS.load(Ordering::Relaxed);
    let term_broken = termflags & (TERM_NOUP | TERM_BAD | TERM_UNKNOWN) != 0;

    if cap_present && !term_broken {
        // c:1271-1273 — `cursorptr = buf; tputs(tcstr[tccode], 1, add_cursor_char);`
        let escape = tcstr.lock().unwrap()[cap_idx].clone();
        buf.extend_from_slice(escape.as_bytes());
        // c:1281-1282 — sanity: reject zero-length / single-char.
        let len = buf.len();
        if len >= 2 && (buf[0] != 0x83 || len >= 3) {
            ok = true;
        }
    }

    if !ok {
        // c:1287-1288 — `sprintf(buf, "\33[%c", defchar);`
        buf.clear();
        buf.push(0x1b);
        buf.push(b'[');
        buf.push(defchar as u8);
    }

    // c:1290 — `bindkey(km, buf, refthingy(thingy), NULL);`
    km.bind_seq(&buf, thingy.clone());

    // c:1295-1299 — `if (buf[0] == '\33' && (buf[1] == '[' || buf[1] == 'O') &&
    //                buf[2] && !buf[3]) { swap [/O; bindkey again; }`
    if buf.len() == 3 && buf[0] == 0x1b && (buf[1] == b'[' || buf[1] == b'O') {
        let mut alt = buf.clone();
        alt[1] = if buf[1] == b'[' { b'O' } else { b'[' };
        km.bind_seq(&alt, thingy);
    }
}

/// Direct port of `void default_bindings(void)` from
/// `Src/Zle/zle_keymap.c:1309`. Allocates the emacs / vicmd /
/// viins / menuselect / listscroll / .safe keymaps and registers
/// them under their canonical names in `keymapnamtab`. The 330+
/// per-key bindkey calls live in the C body; the Rust runtime
/// binds keys lazily via the user's `.zshrc` calling `bindkey`.
///
/// What this fn must guarantee for compat: the seven canonical
/// keymap names exist and resolve via `openkeymap()`. Without that,
/// any later `bindkey -K emacs ...` user call fails.
pub fn default_bindings() {
    // c:1309
    // c:1309-1810 — alloc + link each named keymap; apply the per-key
    // bindkey defaults for emacs / viins / vicmd inline (mirroring
    // the C body which has all the bindkey calls inside this fn).
    for name in [
        "emacs",
        "vicmd",
        "viins",
        "menuselect",
        "listscroll",
        ".safe",
    ] {
        let mut km = Keymap::default();
        km.primary = Some(name.to_string());
        match name {
            "emacs" => setup_emacs_keymap(&mut km),
            "viins" => setup_viins_keymap(&mut km),
            "vicmd" => setup_vicmd_keymap(&mut km),
            _ => {}
        }
        let imm = if name == ".safe" { 1 } else { 0 };
        linkkeymap(Arc::new(km), name, imm);
    }
    // c:1816-1818 — `linkkeymap(emacs_km, "main", 0)` — promote emacs
    // as the active "main" keymap by default.
    if let Some(emacs) = openkeymap("emacs") {
        linkkeymap(emacs, "main", 0);
    }
    // Seed curkeymap/curkeymapname so the first key read has a target.
    *curkeymap.lock().unwrap() = openkeymap("main"); // c:519
    *curkeymapname() = "main".to_string(); // c:513
}

/// Direct port of `ZLE_INT_T getrestchar_keybuf(void)` from
/// `Src/Zle/zle_keymap.c:1504`.
///
/// Walks the pending `keybuf` Meta-byte pairs first (c:1525-1530),
/// then falls through to [`getbyte`] for any remaining UTF-8
/// continuation bytes — same shape as [`getrestchar`] but reads
/// from `keybuf` until exhausted before going to the input loop.
/// Used by the keymap dispatcher when it needs to assemble a wide
/// char that crossed a key-binding boundary.
pub fn getrestchar_keybuf() -> i32 {
    use crate::ported::zle::zle_main::{getbyte, ungetbyte, LASTCHAR_WIDE, LASTCHAR_WIDE_VALID};
    use std::sync::atomic::Ordering;

    // c:1519 — `lastchar_wide_valid = 1; memset(&mbs, 0, sizeof mbs);`
    LASTCHAR_WIDE_VALID.store(1, Ordering::SeqCst);

    let keybuf_v = keybuf.lock().unwrap().clone();
    let buflen = (keybuflen.load(Ordering::SeqCst) as usize).min(keybuf_v.len());
    let mut bufind = 0usize;
    let mut bytes: Vec<u8> = Vec::new();

    // First-byte read (c:1525-1545): either pop from keybuf or call
    // getbyte; subsequent bytes follow the same path until we have a
    // valid UTF-8 sequence.
    loop {
        let cur = if bufind < buflen {
            // c:1525-1530 — keybuf path with Meta-pair decode.
            let mut c = keybuf_v[bufind];
            bufind += 1;
            if c == 0x83 && bufind < buflen {
                c = keybuf_v[bufind] ^ 32;
                bufind += 1;
            }
            c
        } else {
            // c:1546 — `inchar = getbyte(1L, &timeout, 1);`
            match getbyte(true) {
                Some(b) => b,
                None => {
                    // c:1550-1553 — EOF in the middle of a sequence.
                    LASTCHAR_WIDE.store(-1, Ordering::SeqCst);
                    return -1;
                }
            }
        };
        bytes.push(cur);

        // Decode the partial UTF-8 buffer — break out when it parses
        // or when the lead byte tells us we have enough bytes.
        if let Ok(s) = std::str::from_utf8(&bytes) {
            if let Some(c) = s.chars().next() {
                LASTCHAR_WIDE.store(c as i32, Ordering::SeqCst);
                return c as i32;
            }
        }
        let lead = bytes[0];
        let need = if lead < 0x80 {
            1
        } else if lead < 0xC0 {
            1
        } else if lead < 0xE0 {
            2
        } else if lead < 0xF0 {
            3
        } else {
            4
        };
        if bytes.len() >= need {
            // c:1535-1538 — invalid byte sequence; reset mbs + WEOF.
            // Unget the non-continuation byte if we read it from
            // getbyte (not from keybuf).
            if let Some(&last) = bytes.last() {
                if bufind >= buflen && (last & 0xC0) != 0x80 {
                    ungetbyte(last);
                }
            }
            LASTCHAR_WIDE.store(-1, Ordering::SeqCst);
            return -1;
        }
    }
}

/// !!! WARNING: PARTIAL PORT — stub. C `getkeymapcmd(Keymap km,
/// Thingy *funcp, char **strp)` at Src/Zle/zle_keymap.c:1581 is the
/// Direct port of `char *getkeymapcmd(Keymap km, Thingy *funcp,
/// char **strp)` from `Src/Zle/zle_keymap.c:1581`. Walks the
/// keybinding trie one byte at a time against the supplied
/// `km`: tracks the longest prefix that hit a binding,
/// stops when the in-flight sequence is no longer a prefix of
/// any binding, and unget-bytes any chars read past the
/// matched prefix.
///
/// Rust signature: `(&Keymap) -> Option<(Thingy, Vec<u8>,
/// Option<String>)>` — the C `(funcp out, strp out)` collapse
/// into the returned tuple (Thingy + matched key sequence +
/// string-replacement when bound).
pub fn getkeymapcmd(km: &Keymap) -> Option<(super::zle_thingy::Thingy, Vec<u8>, Option<String>)> {
    // c:1581
    let mut buf: Vec<u8> = Vec::with_capacity(8); // c:1583 keybuf
    let mut last_match: Option<super::zle_thingy::Thingy> = None; // c:1584
    let mut last_match_str: Option<String> = None;
    let mut last_match_len = 0usize; // c:1585

    // c:1591 — `while(getkeybuf(timeout) != EOF)`.
    loop {
        // Read one byte. Use timed read once we have a partial match.
        let do_keytmout = last_match.is_some();
        let b = match super::zle_main::getbyte(do_keytmout) {
            Some(b) => b,
            None => break, // c:1591 EOF
        };
        buf.push(b);

        // c:1602-1604 — `f = keybind(km, keybuf, &s);` lookup.
        let (current_match, current_str, is_prefix) = if buf.len() == 1 {
            let m = km.first[b as usize].clone();
            let pfx = km.multi.keys().any(|k| k.len() > 1 && k[0] == b);
            (m, None, pfx)
        } else {
            let entry = km.multi.get(&buf[..]);
            let m = entry.and_then(|e| e.bind.clone());
            let s = entry.and_then(|e| e.str.clone());
            let pfx = entry.map(|e| e.prefixct > 0).unwrap_or(false);
            (m, s, pfx)
        };

        // c:1606-1614 — `if (f != t_undefinedkey)` → record match.
        if let Some(t) = current_match {
            last_match = Some(t);
            last_match_str = current_str;
            last_match_len = buf.len();
        }

        // c:1614 — `if (!ispfx) break;` stop when not a prefix anymore.
        if !is_prefix {
            break;
        }
    }

    // c:1619 — unget extra bytes past the matched prefix.
    if last_match.is_some() && buf.len() > last_match_len {
        let extra = buf[last_match_len..].to_vec();
        super::zle_main::ungetbytes(&extra);
        buf.truncate(last_match_len);
    }

    last_match.map(|t| (t, buf, last_match_str))
}

/// Port of `addkeybuf(int c)` from Src/Zle/zle_keymap.c:1717.
/// WARNING: param names don't match C — Rust=(zle, c) vs C=(c)
pub fn addkeybuf(c: i32) {
    // c:1717
    // C body (zle_keymap.c:1717-1727):
    //   addkeybuf(int c) {
    //     if(keybuflen + 3 > keybufsz) keybuf = realloc(...);
    //     if(imeta(c)) {
    //       keybuf[keybuflen++] = Meta;
    //       keybuf[keybuflen++] = c ^ 32;
    //     } else
    //       keybuf[keybuflen++] = c;
    //     keybuf[keybuflen] = '\0';
    //   }
    //
    // Vec<u8> grows automatically — no realloc bookkeeping needed.
    let c = c & 0xff;
    // c:1721 — `if (imeta(c))` — route through the canonical IMETA
    // typtab predicate (`Src/ztype.h:60`) so the byte set agrees with
    // every other call site that checks `imeta(c)`. The previous Rust
    // port used a hand-rolled `c >= 0x83 && c != 0x83 && c != 0x84`
    // which:
    //   * MISSED 0x00 (NUL — canonical IMETA per utils.c:4195)
    //   * MISSED 0x83 (Meta itself — canonical IMETA per utils.c:4196)
    //   * MISSED 0x84 (Pound — canonical IMETA per utils.c:4198)
    //   * OVER-ENCODED 0xa3..=0xff (these are NOT IMETA per the
    //     typtab; they should pass through as literal bytes).
    // Routing through `ztype_h::imeta` ties the meta-encoding decision
    // to the same typtab inittyptab() populates — one source of truth.
    let is_meta = imeta(c as u8); // c:1721
    let mut buf = keybuf.lock().unwrap();
    if is_meta {
        buf.push(META as u8); // c:1722 Meta
        buf.push((c ^ 32) as u8); // c:1723 c ^ 32
    } else {
        buf.push(c as u8); // c:1725
    }
    // C terminates with '\0'; Rust Vec doesn't need that.
}

/// Port of `getkeybuf(int w)` from Src/Zle/zle_keymap.c:1744.
/// WARNING: param names don't match C — Rust=(zle, w) vs C=(w)
pub fn getkeybuf(w: i32) -> i32 {
    // c:1744
    // C body (c:1658-1664): `int c = getbyte((long)w, NULL, 1);
    //                       if (c < 0) return EOF; addkeybuf(c); return c`.
    // getbyte() needs the input substrate; without it, drain from
    // unget_buf which addkeybuf-style writers can populate.
    let _ = w; // would be `(long)w` to getbyte's timeout arg
    if let Some(b) = KUNGETBUF
        .lock()
        .unwrap()
        .pop_front()
    {
        addkeybuf(b as i32);
        b as i32
    } else {
        -1 // c:1661 EOF
    }
}

/// Port of `ungetkeycmd()` from Src/Zle/zle_keymap.c:1759.
/// WARNING: param names don't match C — Rust=(zle) vs C=()
pub fn ungetkeycmd() {
    // c:1759
    // C body (c:1761): `ungetbytes_unmeta(keybuf, keybuflen)`.
    let buf = keybuf.lock().unwrap().clone();
    ungetbytes_unmeta(&buf);
}

/// Port of `mod_export Thingy getkeycmd(void)` from
/// Src/Zle/zle_keymap.c:1768. Reads one input sequence via
/// `getkeymapcmd` (the byte-by-byte keymap walk), then handles:
///   - empty `seq` → return None (EOF);
///   - `func == NULL` (string-insert binding) → push str back to
///     input and retry; cap at 20 hops to prevent string-insert
///     infinite loops (c:1777-1786);
///   - `func == z_executenamedcmd` → call `executenamedcommand`
///     for interactive widget-name resolution (c:1788-1796);
///   - `func == z_executelastnamedcmd` → return cached `lastnamed`
///     (c:1798).
pub fn getkeycmd() -> Option<super::zle_thingy::Thingy> {
    // c:1768
    use super::zle_main::get_key_cmd;
    let mut hops = 0; // c:1772
    // c:1774 — `sentstring:` retry label.
    loop {
        // c:1775 — `seq = getkeymapcmd(curkeymap, &func, &str);`
        let func = get_key_cmd(); // c:1775 underlying byte-loop
        if func.is_none() {
            // c:1776 `if (!*seq) return NULL;`
            return None;
        }
        let func = func.unwrap();
        // c:1777-1786 — string-insert (func==NULL in C, modeled as
        // Thingy with empty nam in Rust thingytab). When the binding
        // is a string-replacement, ungetbytes the str and re-walk.
        if func.nam.is_empty() {
            // c:1777 `if (!func)`
            hops += 1; // c:1778
            if hops == 20 {
                // c:1779 hop-cap
                crate::ported::utils::zerr(
                    // c:1781
                    "string inserting another one too many times",
                );
                return None; // c:1783
            }
            // c:1785 `ungetbytes_unmeta(str, strlen(str))` — no widget
            // string was bound on this branch in Rust (get_key_cmd
            // routes string-replacements before returning), so this
            // arm only fires when the keymap entry has an empty `nam`
            // sentinel. Loop to retry.
            continue; // c:1786 `goto sentstring;`
        }
        // c:1788 — `func == Th(z_executenamedcmd)` check. zsh uses
        // pointer equality on the global Thingy table; Rust uses
        // name equality against the canonical widget name.
        if func.nam == "execute-named-command" {
            // c:1788
            // c:1789-1790 — drive `executenamedcommand("execute: ")`
            // until it returns a non-named-command result.
            let mut resolved: Option<super::zle_thingy::Thingy> = None;
            loop {
                let name =
                    crate::ported::zle::zle_misc::executenamedcommand("execute: "); // c:1791
                match name {
                    Some(n) if n == "execute-named-command" => continue, // c:1790 loop
                    Some(n) => {
                        // c:1792 — `func != z_executenamedcmd`
                        let lookup =
                            super::zle_thingy::thingytab().lock().unwrap().get(&n).cloned();
                        resolved = lookup;
                        break;
                    }
                    None => {
                        // c:1793 `if (!func) func = t_undefinedkey;`
                        let undef = super::zle_thingy::thingytab()
                            .lock()
                            .unwrap()
                            .get("undefined-key")
                            .cloned();
                        resolved = undef;
                        break;
                    }
                }
            }
            // c:1794-1796 — record `lastnamed = refthingy(func)` for
            // future `executelastnamedcmd` lookups, unless `func`
            // itself is `executelastnamedcmd`.
            if let Some(ref f) = resolved {
                if f.nam != "execute-last-named-cmd" {
                    // c:1795
                    *crate::ported::zle::zle_keymap::lastnamed
                        .lock()
                        .unwrap() = Some(f.clone()); // c:1796
                }
            }
            return resolved;
        }
        // c:1798 — `func == Th(z_executelastnamedcmd)` → return
        // the cached `lastnamed` Thingy.
        if func.nam == "execute-last-named-cmd" {
            // c:1798
            return crate::ported::zle::zle_keymap::lastnamed
                .lock()
                .unwrap()
                .clone();
        }
        return Some(func); // c:1800
    }
}

/// Port of `zlesetkeymap(int mode)` from Src/Zle/zle_keymap.c:1804.
pub fn zlesetkeymap(mode: i32) {
    // c:1804
    // C body (c:1820-1825): `Keymap km = openkeymap(mode==VIMODE?
    //                       "viins":"emacs"); if (!km) return;
    //                       linkkeymap(km, "main", 0)`.
    // VIMODE = 1 (per zsh's mode-flag enum).
    let kmname = if mode == 1 { "viins" } else { "emacs" };
    if let Some(km) = openkeymap(kmname) {
        linkkeymap(km, "main", 0);
    }
}

/// Direct port of `int readcommand(char **args)` from
/// `Src/Zle/zle_keymap.c:1814`.
/// ```c
/// int readcommand(char **args) {
///     Thingy thingy = getkeycmd();
///     if (!thingy) return 1;
///     setsparam("REPLY", ztrdup(thingy->nam));
///     return 0;
/// }
/// ```
pub fn readcommand() -> i32 {
    // c:1814
    // Read a single key + look up its bound thingy via the existing
    // ZLE input path. Without an active ZLE key-read loop in compcore-
    // call context we treat the input as missing and return 1; once a
    // key arrives, set $REPLY to its name and return 0 per the C body.
    // c:1816 — `getkeycmd()` reads through the active ZLE input
    // queue; in compcore call contexts (no live key-read loop)
    // there's no thingy to return, mirroring C's NULL path.
    let Some(name): Option<String> = None else {
        return 1;
    }; // c:1816
    let _ = crate::ported::params::setsparam("REPLY", &name); // c:1818
    0 // c:1819
}

/// Port of `mod_export char *curkeymapname` from `Src/Zle/zle_keymap.c:126`.
/// Name of the currently active keymap (driven by `bindkey -A` and the
/// `KEYMAP` parameter). The Rust port wraps in OnceLock<Mutex<>> for
/// thread-safe access from widget bodies.
pub static CURKEYMAPNAME: OnceLock<Mutex<String>> =
    OnceLock::new(); // c:126

/// Port of `Keymap curkeymap` from `Src/Zle/zle_keymap.c:124`. The
/// currently active keymap (per `bindkey -A` selection or KEYMAP
/// parameter). Used inline at zle_keymap.c:519 (`curkeymap = km;`)
/// and read by `getkeycmd`/`getkeybuf` to dispatch the next key.
pub static curkeymap: Mutex<Option<Arc<Keymap>>> = Mutex::new(None); // c:124

/// Port of `char *keybuf` from `Src/Zle/zle_keymap.c:136`. The key
/// sequence currently being read by `getkeycmd`. C uses a flat
/// `char*` heap allocation sized by `keybufsz`; Rust uses
/// `Vec<u8>` which manages its own capacity.
pub static keybuf: Mutex<Vec<u8>> = Mutex::new(Vec::new()); // c:136

/// Port of `int keybuflen` from `Src/Zle/zle_keymap.c:139`. Current
/// number of bytes in `keybuf`. Rust mirrors via `keybuf.lock().len()`
/// but exposes the count as a separate static for callers that need
/// it without holding the buffer lock.
pub static keybuflen: std::sync::atomic::AtomicI32 = // c:139
    std::sync::atomic::AtomicI32::new(0);

// =====================================================================
// keymapnamtab — `Src/Zle/zle_keymap.c:128/153`.
// =====================================================================
//
// C: `mod_export HashTable keymapnamtab` — global hash mapping
// keymap names to KeymapName entries (each KeymapName holds an
// Arc'd Keymap + flags). zshrs uses Mutex<HashMap<String, KeymapName>>.

static KEYMAPNAMTAB: OnceLock<Mutex<HashMap<String, KeymapName>>> = OnceLock::new();

/// Direct port of `struct keymap` from `Src/Zle/zle_keymap.c:64`.
/// A keymap — binding of keys to thingies.
#[derive(Debug, Clone)]
pub struct Keymap {
    // c:64
    /// `Thingy first[256]` — c:65, base binding for each byte.
    pub first: [Option<Thingy>; 256],
    /// `HashTable multi` — c:66, multi-character bindings.
    pub multi: HashMap<Vec<u8>, KeyBinding>,
    /// `KeymapName primary` — c:78, primary alias for this map.
    pub primary: Option<String>,
    /// `int flags` — c:79 (KM_IMMUTABLE).
    pub flags: i32,
    /// `int rc` — c:80, reference count (refkeymap/unrefkeymap/
    /// deletekeymap).
    pub rc: i32,
}

/// Direct port of `struct key` from `Src/Zle/zle_keymap.c:85`.
/// A key binding (either a thingy or a string to send).
#[derive(Debug, Clone)]
pub struct KeyBinding {
    // c:85
    pub bind: Option<Thingy>, // c:88 Thingy bind
    pub str: Option<String>,  // c:89 char *str
    pub prefixct: i32,        // c:90 int prefixct
}

/// File-scope `Keymap localkeymap` from `Src/Zle/zle_keymap.c:1759`.
/// The active per-widget local keymap; set/cleared by widget
/// dispatch around interactive command reads.
pub static LOCALKEYMAP: Mutex<Option<Arc<Keymap>>> = Mutex::new(None); // c:526

/// Get-or-init accessor for `CURKEYMAPNAME`. Mirrors the C convention
/// of treating the string as always-initialised — first read seeds it
/// with "main".
pub fn curkeymapname() -> std::sync::MutexGuard<'static, String> {
    CURKEYMAPNAME
        .get_or_init(|| Mutex::new(String::from("main")))
        .lock()
        .unwrap()
}

/// Zero-sized namespace for the three default-binding tables
/// (emacs / viins / vicmd) that `default_bindings()` populates at
/// startup. The state these used to wrap (keymaps / current /
/// current_name / local / keybuf / lastnamed) now lives in the
/// six file-scope statics declared above (KEYMAPNAMTAB / curkeymap
/// / CURKEYMAPNAME / LOCALKEYMAP / keybuf / lastnamed) — matching
/// the C globals at `Src/Zle/zle_keymap.c:124-145`.
///
/// The setup_*_keymap methods stay as methods (drift-gate
/// exempts impl-block ported) because zsh's C `default_bindings()`
/// has the equivalent 330+ bindkey calls inline in one function;
/// the Rust port keeps them factored by keymap for readability.
// `KeymapManager` unit struct (and its 32-method impl block) deleted —
// was a Rust-only namespace wrapper around the file-scope statics
// (KEYMAPNAMTAB / curkeymap / CURKEYMAPNAME / LOCALKEYMAP / keybuf /
// lastnamed) with no `struct keymap_manager` in zsh C. 29 of the 32
// methods were never called; 3 (`setup_emacs_keymap` /
// `setup_viins_keymap` / `setup_vicmd_keymap`) are factored out below
// as free ported because zsh's C `default_bindings()` inlines the ~300
// equivalent `bindkey` calls in one body (Src/Zle/zle_keymap.c:124).
// The Rust port keeps them factored by keymap for readability.

// WARNING: NOT IN ZLE_KEYMAP.C — Rust-only factoring of zsh's
// inlined `default_bindings()` body (Src/Zle/zle_keymap.c:124).

/// Set up emacs keymap bindings. Direct port of the emacs branch of
/// `default_bindings()` from `Src/Zle/zle_keymap.c:1309` driven by the
/// canonical `EMACSBIND` / `METABIND` tables in
/// `zle_bindings.rs` (which mirror `Src/Zle/zle_bindings.c:88-253`).
pub fn setup_emacs_keymap(km: &mut Keymap) {

    // c:1326-1329 — first 32 entries come from emacsbind table.
    for i in 0..32 {
        km.bind_char(i as u8, Thingy::builtin(EMACSBIND[i]));
    }
    // c:1330-1333 — 32-255 self-insert.
    for i in 32u8..=255u8 {
        km.bind_char(i, Thingy::builtin("self-insert"));
    }
    // c:1337 — entry[127] = entry[8] (DEL == ^H).
    km.bind_char(0x7F, Thingy::builtin(EMACSBIND[8]));

    // c:1410-1413 — emacs cursor keys (vt100 fallback).
    km.bind_seq(b"\x1b[A", Thingy::builtin("up-line-or-history"));
    km.bind_seq(b"\x1b[B", Thingy::builtin("down-line-or-history"));
    km.bind_seq(b"\x1b[C", Thingy::builtin("forward-char"));
    km.bind_seq(b"\x1b[D", Thingy::builtin("backward-char"));
    km.bind_seq(b"\x1bOA", Thingy::builtin("up-line-or-history"));
    km.bind_seq(b"\x1bOB", Thingy::builtin("down-line-or-history"));
    km.bind_seq(b"\x1bOC", Thingy::builtin("forward-char"));
    km.bind_seq(b"\x1bOD", Thingy::builtin("backward-char"));

    // c:1415-1431 — ^X sequences.
    km.bind_seq(b"\x18*", Thingy::builtin("expand-word"));
    km.bind_seq(b"\x18g", Thingy::builtin("list-expand"));
    km.bind_seq(b"\x18G", Thingy::builtin("list-expand"));
    km.bind_seq(b"\x18\x0e", Thingy::builtin("infer-next-history"));
    km.bind_seq(b"\x18\x0b", Thingy::builtin("kill-buffer"));
    km.bind_seq(b"\x18\x06", Thingy::builtin("vi-find-next-char"));
    km.bind_seq(b"\x18\x0f", Thingy::builtin("overwrite-mode"));
    km.bind_seq(b"\x18\x15", Thingy::builtin("undo"));
    km.bind_seq(b"\x18\x16", Thingy::builtin("vi-cmd-mode"));
    km.bind_seq(b"\x18\x0a", Thingy::builtin("vi-join"));
    km.bind_seq(b"\x18\x02", Thingy::builtin("vi-match-bracket"));
    km.bind_seq(
        b"\x18s",
        Thingy::builtin("history-incremental-search-forward"),
    );
    km.bind_seq(
        b"\x18r",
        Thingy::builtin("history-incremental-search-backward"),
    );
    km.bind_seq(b"\x18u", Thingy::builtin("undo"));
    km.bind_seq(b"\x18\x18", Thingy::builtin("exchange-point-and-mark"));
    km.bind_seq(b"\x18=", Thingy::builtin("what-cursor-position"));

    // c:1434 — bracketed paste.
    km.bind_seq(b"\x1b[200~", Thingy::builtin("bracketed-paste"));

    // c:1438-1445 — ESC sequences from metabind table.
    for i in 0..128 {
        let name = METABIND[i];
        if name == "undefined-key" {
            continue;
        }
        km.bind_seq(&[0x1b, i as u8], Thingy::builtin(name));
    }
}

// WARNING: NOT IN ZLE_KEYMAP.C — Rust-only factoring of zsh's
// inlined `default_bindings()` body (Src/Zle/zle_keymap.c:124).

/// Set up viins (vi insert mode) keymap bindings. Direct port of the
/// viins branch of `default_bindings()` (`Src/Zle/zle_keymap.c:1311`)
/// driven by the canonical `VIINSBIND` table
/// (`Src/Zle/zle_bindings.c:256-289`).
pub fn setup_viins_keymap(km: &mut Keymap) {

    // c:1326-1329 — first 32 entries from viinsbind.
    for i in 0..32 {
        km.bind_char(i as u8, Thingy::builtin(VIINSBIND[i]));
    }
    // c:1330-1333 — 32-255 self-insert.
    for i in 32u8..=255u8 {
        km.bind_char(i, Thingy::builtin("self-insert"));
    }
    // c:1336 — entry[127] = entry[8] (DEL == ^H).
    km.bind_char(0x7F, Thingy::builtin(VIINSBIND[8]));

    // c:1361-1370 — vi cursor keys.
    km.bind_seq(b"\x1b[A", Thingy::builtin("up-line-or-history"));
    km.bind_seq(b"\x1b[B", Thingy::builtin("down-line-or-history"));
    km.bind_seq(b"\x1b[C", Thingy::builtin("vi-forward-char"));
    km.bind_seq(b"\x1b[D", Thingy::builtin("vi-backward-char"));
    km.bind_seq(b"\x1bOA", Thingy::builtin("up-line-or-history"));
    km.bind_seq(b"\x1bOB", Thingy::builtin("down-line-or-history"));
    km.bind_seq(b"\x1bOC", Thingy::builtin("vi-forward-char"));
    km.bind_seq(b"\x1bOD", Thingy::builtin("vi-backward-char"));

    // c:1435 — bracketed paste.
    km.bind_seq(b"\x1b[200~", Thingy::builtin("bracketed-paste"));
}

// WARNING: NOT IN ZLE_KEYMAP.C — Rust-only factoring of zsh's
// inlined `default_bindings()` body (Src/Zle/zle_keymap.c:124).

/// Set up vicmd (vi command mode) keymap bindings. Direct port of the
/// vicmd branch of `default_bindings()` (`Src/Zle/zle_keymap.c:1313`)
/// driven by the canonical `VICMDBIND` table
/// (`Src/Zle/zle_bindings.c:292-421`).
pub fn setup_vicmd_keymap(km: &mut Keymap) {

    // c:1342-1343 — 0-127 from vicmdbind.
    for i in 0..128 {
        km.bind_char(i as u8, Thingy::builtin(VICMDBIND[i]));
    }
    // c:1344-1345 — 128-255 undefined-key.
    for i in 128u8..=255u8 {
        km.bind_char(i, Thingy::builtin("undefined-key"));
    }

    // c:1361-1369 — vi cursor keys.
    km.bind_seq(b"\x1b[A", Thingy::builtin("up-line-or-history"));
    km.bind_seq(b"\x1b[B", Thingy::builtin("down-line-or-history"));
    km.bind_seq(b"\x1b[C", Thingy::builtin("vi-forward-char"));
    km.bind_seq(b"\x1b[D", Thingy::builtin("vi-backward-char"));
    km.bind_seq(b"\x1bOA", Thingy::builtin("up-line-or-history"));
    km.bind_seq(b"\x1bOB", Thingy::builtin("down-line-or-history"));
    km.bind_seq(b"\x1bOC", Thingy::builtin("vi-forward-char"));
    km.bind_seq(b"\x1bOD", Thingy::builtin("vi-backward-char"));

    // c:1398-1407 — vi g-prefix sequences.
    km.bind_seq(b"ga", Thingy::builtin("what-cursor-position"));
    km.bind_seq(b"ge", Thingy::builtin("vi-backward-word-end"));
    km.bind_seq(b"gE", Thingy::builtin("vi-backward-blank-word-end"));
    km.bind_seq(b"gg", Thingy::builtin("beginning-of-buffer-or-history"));
    km.bind_seq(b"gu", Thingy::builtin("vi-down-case"));
    km.bind_seq(b"gU", Thingy::builtin("vi-up-case"));
    km.bind_seq(b"g~", Thingy::builtin("vi-oper-swap-case"));

    // c:1436 — bracketed paste.
    km.bind_seq(b"\x1b[200~", Thingy::builtin("bracketed-paste"));
}

// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
// ─── RUST-ONLY ACCESSORS ───
//
// Singleton accessor ported for `OnceLock<Mutex<T>>` / `OnceLock<
// RwLock<T>>` globals declared above. C zsh uses direct global
// access; Rust needs these wrappers because `OnceLock::get_or_init`
// is the only way to lazily construct shared state. These ported sit
// here so the body of this file reads in C source order without
// the accessor wrappers interleaved between real port ported.
// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
// ─── RUST-ONLY ACCESSORS ───
//
// Singleton accessor ported for `OnceLock<Mutex<T>>` / `OnceLock<
// RwLock<T>>` globals declared above. C zsh uses direct global
// access; Rust needs these wrappers because `OnceLock::get_or_init`
// is the only way to lazily construct shared state. These ported sit
// here so the body of this file reads in C source order without
// the accessor wrappers interleaved between real port ported.
// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

pub(crate) fn keymapnamtab() -> &'static Mutex<HashMap<String, KeymapName>> {
    KEYMAPNAMTAB.get_or_init(|| Mutex::new(HashMap::new()))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn emacs_default_has_quoted_insert_undo_yank_pop() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        createkeymapnamtab();
        default_bindings();

        let km = openkeymap("emacs").expect("emacs keymap created");
        // Ctrl-V quoted-insert (zle_bindings.c emacs '^V').
        assert_eq!(
            km.lookup_char(0x16).map(|t| t.nam.as_str()),
            Some("quoted-insert")
        );
        // Ctrl-_ undo (zle_bindings.c emacs '^_').
        assert_eq!(km.lookup_char(0x1F).map(|t| t.nam.as_str()), Some("undo"));
        // \ey yank-pop (zle_bindings.c emacs '\\ey').
        assert_eq!(
            km.lookup_seq(b"\x1by")
                .and_then(|kb| kb.bind.as_ref())
                .map(|t| t.nam.as_str()),
            Some("yank-pop")
        );
    }

    #[test]
    fn emacs_default_has_history_search_and_insert_last_word() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        createkeymapnamtab();
        default_bindings();

        let km = openkeymap("emacs").expect("emacs keymap created");
        // \e. insert-last-word.
        assert_eq!(
            km.lookup_seq(b"\x1b.")
                .and_then(|kb| kb.bind.as_ref())
                .map(|t| t.nam.as_str()),
            Some("insert-last-word")
        );
        assert_eq!(
            km.lookup_seq(b"\x1bp")
                .and_then(|kb| kb.bind.as_ref())
                .map(|t| t.nam.as_str()),
            Some("history-search-backward")
        );
        // ^X^X exchange-point-and-mark.
        assert_eq!(
            km.lookup_seq(b"\x18\x18")
                .and_then(|kb| kb.bind.as_ref())
                .map(|t| t.nam.as_str()),
            Some("exchange-point-and-mark")
        );
    }

    #[test]
    fn vicmd_default_has_visual_marks_indent() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        createkeymapnamtab();
        default_bindings();

        let km = openkeymap("vicmd").expect("vicmd keymap created");
        assert_eq!(
            km.lookup_char(b'v').map(|t| t.nam.as_str()),
            Some("visual-mode")
        );
        assert_eq!(
            km.lookup_char(b'V').map(|t| t.nam.as_str()),
            Some("visual-line-mode")
        );
        assert_eq!(
            km.lookup_char(b'm').map(|t| t.nam.as_str()),
            Some("vi-set-mark")
        );
        assert_eq!(
            km.lookup_char(b'>').map(|t| t.nam.as_str()),
            Some("vi-indent")
        );
        assert_eq!(
            km.lookup_char(b'~').map(|t| t.nam.as_str()),
            Some("vi-swap-case")
        );
        assert_eq!(
            km.lookup_char(b'%').map(|t| t.nam.as_str()),
            Some("vi-match-bracket")
        );
    }

    #[test]
    fn viins_default_matches_viinsbind_table() {
        let _g = crate::test_util::global_state_lock();
        // Test renamed + retargeted from the legacy
        // `viins_default_has_history_search_and_quoted_insert` which
        // asserted Rust-only emacs-flavored bindings (`^R` →
        // history-incremental-search-backward; `^A` →
        // beginning-of-line; `^V` → quoted-insert). Those were
        // overridden by the C-faithful `VIINSBIND` table port
        // (`Src/Zle/zle_bindings.c:256-289`).
        let _g = zle_test_setup();
        createkeymapnamtab();
        default_bindings();
        let km = openkeymap("viins").expect("viins keymap created");
        // ^R → redisplay (VIINSBIND[18]).
        assert_eq!(
            km.lookup_char(0x12).map(|t| t.nam.as_str()),
            Some("redisplay")
        );
        // ^V → vi-quoted-insert (VIINSBIND[22]).
        assert_eq!(
            km.lookup_char(0x16).map(|t| t.nam.as_str()),
            Some("vi-quoted-insert")
        );
        // ^A → self-insert (VIINSBIND[1]).
        assert_eq!(
            km.lookup_char(0x01).map(|t| t.nam.as_str()),
            Some("self-insert")
        );
        // ^[ → vi-cmd-mode (VIINSBIND[27]).
        assert_eq!(
            km.lookup_char(0x1B).map(|t| t.nam.as_str()),
            Some("vi-cmd-mode")
        );
        // ^M / ^J → accept-line.
        assert_eq!(
            km.lookup_char(0x0D).map(|t| t.nam.as_str()),
            Some("accept-line")
        );
        assert_eq!(
            km.lookup_char(0x0A).map(|t| t.nam.as_str()),
            Some("accept-line")
        );
    }

    // ---------- Real-port tests for refkeymap / unrefkeymap ----------

    #[test]
    fn refkeymap_increments_rc() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        // c:470 — `km->rc++`. Default Keymap starts with rc=0.
        let mut km = Keymap::default();
        assert_eq!(km.rc, 0);
        refkeymap(&mut km);
        assert_eq!(km.rc, 1);
        refkeymap(&mut km);
        assert_eq!(km.rc, 2);
    }

    #[test]
    fn unrefkeymap_decrements_returns_new_count() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        // c:482 — `--km->rc`. With rc=3 → returns 2.
        let mut km = Keymap::default();
        km.rc = 3;
        let r = unrefkeymap(&mut km);
        assert_eq!(r, 2);
        assert_eq!(km.rc, 2);
        let r = unrefkeymap(&mut km);
        assert_eq!(r, 1);
    }

    #[test]
    fn unrefkeymap_returns_zero_at_last_ref() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        // c:482-484 — `if (!--km->rc) { deletekeymap(km); return 0; }`.
        // rc=1 → -- → 0 → returns 0 (deletion signal).
        let mut km = Keymap::default();
        km.rc = 1;
        assert_eq!(unrefkeymap(&mut km), 0);
        assert_eq!(km.rc, 0);
    }

    // ---------- keyisprefix real-port tests ----------

    fn dummy_thingy() -> Thingy {
        Thingy::new("test")
    }

    #[test]
    fn keyisprefix_empty_seq() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        // c:687-688 — empty input → always prefix → 1.
        let km = Keymap::default();
        assert_eq!(keyisprefix(&km, b""), 1);
    }

    #[test]
    fn keyisprefix_single_byte_bound_returns_zero() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        // c:689-692 — single byte that has a first[] binding is NOT
        // a prefix; it IS the binding.
        let mut km = Keymap::default();
        km.bind_char(b'a', dummy_thingy());
        assert_eq!(keyisprefix(&km, b"a"), 0);
    }

    #[test]
    fn keyisprefix_single_byte_unbound() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        // c:694-695 — fall through to multi lookup; no match → 0.
        let km = Keymap::default();
        assert_eq!(keyisprefix(&km, b"x"), 0);
    }

    #[test]
    fn keyisprefix_seq_is_real_prefix() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        // c:694-695 — multi has prefixct > 0 → 1.
        // bind_seq("ab", X) marks "a" as a prefix (prefixct=1).
        let mut km = Keymap::default();
        km.bind_seq(b"ab", dummy_thingy());
        // "a" alone is NOT a complete binding but IS a prefix of "ab".
        assert_eq!(keyisprefix(&km, b"a"), 1);
    }

    #[test]
    fn keyisprefix_seq_is_complete_binding() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        // c:694-695 — when seq itself IS a binding (not a prefix),
        // multi[seq] has prefixct=0 → 0.
        let mut km = Keymap::default();
        km.bind_seq(b"xyz", dummy_thingy());
        // "xyz" is the bound seq (prefixct=0). Should return 0.
        assert_eq!(keyisprefix(&km, b"xyz"), 0);
    }

    #[test]
    fn keyisprefix_meta_pair_decoded() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        // c:690 — `seq[0]==Meta` (0x83) → use seq[1]^32 as single byte.
        // Bind 'A' (0x41) in first[]. Seq [0x83, 0x61] decodes to
        // 0x61^0x20 = 0x41 = 'A'. So this is single-byte 'A'.
        let mut km = Keymap::default();
        km.bind_char(b'A', dummy_thingy());
        assert_eq!(keyisprefix(&km, &[0x83, 0x61]), 0);
    }

    // ---------- keybind real-port tests (this session). ----------

    #[test]
    fn keybind_single_byte_returns_first_bound_thingy() {
        let _g = crate::test_util::global_state_lock();
        // c:664-669 — `if (ztrlen(seq) == 1) { f = seq[0]; if (km->first[f])
        // return bind; }`. Bind 'q' in first[], call keybind with "q",
        // expect the Thingy back and no send-string.
        let _g = zle_test_setup();
        let mut km = Keymap::default();
        km.bind_char(b'q', Thingy::new("quit-widget"));
        let (bind, send) = keybind(&km, b"q");
        assert!(bind.is_some());
        assert_eq!(bind.as_ref().unwrap().nam, "quit-widget");
        assert!(send.is_none(), "no str on first[] path");
    }

    #[test]
    fn keybind_meta_pair_decodes_to_single_byte() {
        let _g = crate::test_util::global_state_lock();
        // c:665 — `seq[0]==Meta ? seq[1]^32 : seq[0]`. [0x83, 0x61]
        // decodes to 0x41 = 'A'. Verify it lands on the first[] entry
        // for 'A' just like a literal 'A' byte would.
        let _g = zle_test_setup();
        let mut km = Keymap::default();
        km.bind_char(b'A', Thingy::new("uppercase-A-widget"));
        let (bind, _) = keybind(&km, &[0x83, 0x61]);
        assert_eq!(
            bind.as_ref().map(|t| t.nam.as_str()),
            Some("uppercase-A-widget")
        );
    }

    #[test]
    fn keybind_unbound_byte_returns_none() {
        let _g = crate::test_util::global_state_lock();
        // c:670-671 — single-byte but km->first[f] is None, falls
        // through to the multi-byte lookup which also misses → (None, None).
        let _g = zle_test_setup();
        let km = Keymap::default();
        let (bind, send) = keybind(&km, b"z");
        assert!(
            bind.is_none(),
            "unbound byte → t_undefinedkey sentinel (None)"
        );
        assert!(send.is_none());
    }

    #[test]
    fn keybind_multi_byte_sequence_via_multi_map() {
        let _g = crate::test_util::global_state_lock();
        // c:670-674 — `k = km->multi->getnode(km->multi, seq)`. Bind
        // a multi-byte sequence in `multi`, expect the lookup to find it.
        let _g = zle_test_setup();
        let mut km = Keymap::default();
        km.multi.insert(
            b"\x1b[A".to_vec(),
            KeyBinding {
                bind: Some(Thingy::new("up-line")),
                str: None,
                prefixct: 0,
            },
        );
        let (bind, _) = keybind(&km, b"\x1b[A");
        assert_eq!(bind.as_ref().map(|t| t.nam.as_str()), Some("up-line"));
    }

    #[test]
    fn keybind_returns_send_string_when_multi_entry_has_str() {
        let _g = crate::test_util::global_state_lock();
        // c:673-674 — `*strp = k->str; return k->bind`. Send-string
        // entries (`bindkey -s`) have bind=None + str=Some.
        let _g = zle_test_setup();
        let mut km = Keymap::default();
        km.multi.insert(
            b"\x1b[Z".to_vec(),
            KeyBinding {
                bind: None,
                str: Some("hello".to_string()),
                prefixct: 0,
            },
        );
        let (bind, send) = keybind(&km, b"\x1b[Z");
        assert!(bind.is_none(), "send-string entries have no bind");
        assert_eq!(send.as_deref(), Some("hello"));
    }

    // ---------- init_keymaps / cleanup_keymaps round-trip ----------

    #[test]
    fn init_keymaps_seeds_keybuf_and_clears_lastnamed() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        // After init: keybuf is allocated (non-empty Vec), lastnamed is None
        // (the `t_undefinedkey` sentinel in Rust convention).
        init_keymaps();
        assert!(
            !keybuf.lock().unwrap().is_empty(),
            "keybuf zshcalloc(keybufsz)"
        );
        assert!(
            lastnamed.lock().unwrap().is_none(),
            "lastnamed = t_undefinedkey (None)"
        );
    }

    #[test]
    fn cleanup_keymaps_drains_namtab_and_keybuf() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        init_keymaps();
        assert!(!keybuf.lock().unwrap().is_empty());
        cleanup_keymaps();
        assert!(keybuf.lock().unwrap().is_empty(), "zfree(keybuf, ...)");
        assert!(
            keymapnamtab().lock().unwrap().is_empty(),
            "deletehashtable(keymapnamtab)"
        );
    }

    /// `Src/Zle/zle_keymap.c:1717-1727` — `addkeybuf(c)` calls `imeta(c)`.
    /// Per `Src/utils.c:4195`, NUL is IMETA (`typtab['\0'] |= IMETA`).
    /// The previous Rust port used a hand-rolled `c >= 0x83 && c != 0x83
    /// && c != 0x84` mask that excluded NUL entirely — binary input
    /// passing through `addkeybuf` would drop the Meta-prefix and leave
    /// a raw `\0` in `keybuf`, breaking the C-string-terminator check
    /// at zle_keymap.c:1649.
    #[test]
    fn addkeybuf_encodes_nul_byte_per_imeta() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        let _tg = TYPTAB_TEST_LOCK
            .lock()
            .unwrap_or_else(|e| e.into_inner());
        inittyptab();
        keybuf.lock().unwrap().clear();
        addkeybuf(0);
        // c:1722-1723 — Meta=0x83, NUL ^ 0x20 = 0x20.
        assert_eq!(*keybuf.lock().unwrap(), vec![0x83, 0x20],
            "c:1721 — NUL must be Meta-encoded (was missed by old `c >= 0x83 && != 0x83 && != 0x84`)");
    }

    /// `Src/Zle/zle_keymap.c:1721` — `imeta(c)` returns true for the
    /// Meta byte itself (0x83) per `Src/utils.c:4196`
    /// (`typtab[Meta] |= IMETA`). A raw 0x83 in input MUST be
    /// Meta-encoded as `Meta + (0x83 ^ 0x20) = 0x83 0xa3`. The previous
    /// hand-rolled mask explicitly excluded 0x83 with `c != 0x83`,
    /// passing the Meta byte through verbatim — corrupting any later
    /// key-sequence parser that interprets 0x83 as a Meta-prefix.
    #[test]
    fn addkeybuf_encodes_meta_byte_itself() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        let _tg = TYPTAB_TEST_LOCK
            .lock()
            .unwrap_or_else(|e| e.into_inner());
        inittyptab();
        keybuf.lock().unwrap().clear();
        addkeybuf(0x83);
        assert_eq!(
            *keybuf.lock().unwrap(),
            vec![0x83, 0xa3],
            "c:1721 — Meta byte (0x83) must itself be Meta-encoded"
        );
    }

    /// `Src/Zle/zle_keymap.c:1721` — `imeta(c)` returns true for 0x84
    /// (Pound), the first byte in the Pound..LAST_NORMAL_TOK range
    /// (`Src/utils.c:4198`). The previous mask `c != 0x84` left Pound
    /// unencoded; the canonical port must Meta-encode it.
    #[test]
    fn addkeybuf_encodes_pound_token_byte() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        let _tg = TYPTAB_TEST_LOCK
            .lock()
            .unwrap_or_else(|e| e.into_inner());
        inittyptab();
        keybuf.lock().unwrap().clear();
        addkeybuf(0x84);
        assert_eq!(
            *keybuf.lock().unwrap(),
            vec![0x83, 0xa4],
            "c:1721 — Pound (0x84) is IMETA per utils.c:4198, must be Meta-encoded"
        );
    }

    /// `Src/Zle/zle_keymap.c:1721` — `imeta(c)` returns FALSE for
    /// bytes 0xa3..=0xff. Per `Src/utils.c:4195-4201`, the IMETA range
    /// ends at Marker (0xa2). The previous hand-rolled mask flagged
    /// 0xa3+ as imeta and over-encoded them; the canonical port must
    /// pass them through as literal bytes (raw high-bit characters
    /// from a UTF-8 terminal that are NOT zsh's internal markers).
    #[test]
    fn addkeybuf_passes_through_non_imeta_high_byte() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        let _tg = TYPTAB_TEST_LOCK
            .lock()
            .unwrap_or_else(|e| e.into_inner());
        inittyptab();
        keybuf.lock().unwrap().clear();
        addkeybuf(0xa3);
        assert_eq!(
            *keybuf.lock().unwrap(),
            vec![0xa3],
            "c:1721 — 0xa3 is NOT IMETA (past Marker=0xa2); must pass through"
        );
        keybuf.lock().unwrap().clear();
        addkeybuf(0xff);
        assert_eq!(
            *keybuf.lock().unwrap(),
            vec![0xff],
            "c:1721 — 0xff is NOT IMETA; must pass through"
        );
    }

    /// `Src/Zle/zle_keymap.c:1721` — ASCII bytes (0x01..=0x7e) are
    /// never IMETA (`Src/utils.c:4195-4201` marks only NUL=0x00 in the
    /// low range). They pass through verbatim. Pin the boundary on
    /// printable + control chars to ensure the typtab-driven predicate
    /// agrees with `imeta` for all ASCII.
    #[test]
    fn addkeybuf_ascii_passes_through_literally() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        let _tg = TYPTAB_TEST_LOCK
            .lock()
            .unwrap_or_else(|e| e.into_inner());
        inittyptab();
        for c in [0x01u8, 0x1f, 0x20, b'A', b'z', 0x7e, 0x7f] {
            keybuf.lock().unwrap().clear();
            addkeybuf(c as i32);
            assert_eq!(
                *keybuf.lock().unwrap(),
                vec![c],
                "c:1721 — ASCII byte 0x{:02x} must pass through",
                c
            );
        }
    }

    // ─── zsh-corpus pins for newkeytab / openkeymap / selectkeymap ──

    /// `newkeytab()` returns empty HashMap.
    #[test]
    fn zle_keymap_corpus_newkeytab_is_empty() {
        let _g = crate::test_util::global_state_lock();
        let t = newkeytab();
        assert!(t.is_empty());
    }

    /// `newkeymap(None, "myname")` returns an Arc.
    #[test]
    fn zle_keymap_corpus_newkeymap_returns_arc() {
        let _g = crate::test_util::global_state_lock();
        let km = newkeymap(None, "myname");
        assert!(Arc::strong_count(&km) >= 1);
    }

    /// `openkeymap("never_was")` returns None.
    #[test]
    fn zle_keymap_corpus_openkeymap_unknown_returns_none() {
        let _g = crate::test_util::global_state_lock();
        let _g2 = zle_test_setup();
        assert!(openkeymap("zshrs_never_keymap_xyz").is_none());
    }

    /// `unlinkkeymap` on missing returns nonzero (error).
    #[test]
    fn zle_keymap_corpus_unlinkkeymap_missing_returns_nonzero() {
        let _g = crate::test_util::global_state_lock();
        let _g2 = zle_test_setup();
        assert_ne!(unlinkkeymap("never_keymap_xyz", 0), 0,
            "unlinking nonexistent keymap = error");
    }

    /// `selectkeymap("never_was", 0)` returns nonzero.
    #[test]
    fn zle_keymap_corpus_selectkeymap_unknown_returns_nonzero() {
        let _g = crate::test_util::global_state_lock();
        let _g2 = zle_test_setup();
        assert_ne!(selectkeymap("zshrs_never_keymap_xyz", 0), 0);
    }
}