zsh/ported/modules/

curses.rs

//! Curses module — port of `Src/Modules/curses.c`.
//!
//! Window is permanent (probably "stdscr")                                  // c:55
//! Scrolling enabled                                                        // c:57
//! Autogenerated keypad string/number mapping                               // c:209
//!
//! Implements the `zcurses` builtin: terminal UI windowing.
//!
//! The C source links libncurses for real curses primitives;
//! zshrs doesn't yet take that dependency, so the per-window
//! buffering and refresh emit ANSI escape sequences directly. The
//! function names, signatures, control flow, validation pipeline,
//! error-numbering, and module-static layout mirror `curses.c`
//! line-by-line; the ncurses calls are the only deviation, marked
//! with WARNING comments where they occur.
//!
//! Structure mirrors the C source:
//!   - `enum zc_win_flags` (curses.c:54)
//!   - `struct zc_win` (curses.c:63)
//!   - `struct zcurses_namenumberpair` (curses.c:71)
//!   - `struct zcurses_subcommand` (curses.c:83)
//!   - module-statics `zcurses_windows` / `zcurses_colorpairs` /
//!     `zc_errno` / `zc_color_phase` / `next_cp` (curses.c:90-113)
//!   - error constants `ZCURSES_E{INVALID,DEFINED,UNDEFINED}`
//!     (curses.c:102-104) and validation criteria `ZCURSES_UNUSED`/
//!     `ZCURSES_USED` (curses.c:106-107)
//!   - tables `zcurses_attributes[]` / `zcurses_colors[]`
//!     (curses.c:120-143)
//!   - validation helpers `zcurses_strerror` /
//!     `zcurses_getwindowbyname` / `zcurses_validate_window` /
//!     `zcurses_attrget` / `zcurses_color` (curses.c:233-328)
//!   - `zccmd_*` family (curses.c:434-1567)
//!   - `bin_zcurses()` dispatch table (curses.c:1568)
//!   - module entries (curses.c:1744+)

#![allow(non_camel_case_types)]
#![allow(non_upper_case_globals)]
#![allow(non_snake_case)]

use std::collections::HashMap;
use std::io::{self, Read, Write};
use std::sync::{Mutex, OnceLock};

use crate::ported::params::{getiparam, setaparam, setsparam};
use crate::ported::utils::{zerrnam, zwarnnam};
use crate::ported::zsh_h::{features, module, options};
// =====================================================================
// Port of `struct zc_win` from `Src/Modules/curses.c:63`.
//
// ```c
// struct zc_win {
//     WINDOW *win;       // ncurses window handle
//     char *name;
//     int flags;
//     LinkList children;
//     ZCWin parent;
// };
// ```
//
// `WINDOW *win` is replaced by an explicit cell buffer + cursor
// position because libncurses isn't linked. The `children`/`parent`
// chain is kept (subwin support per `zccmd_addwin` args[5]).
// =====================================================================

/// Per-window state. Port of `struct zc_win`.
#[derive(Debug)]
pub struct zc_win {
    /// `name` field.
    pub name: String,
    /// `flags` field.
    pub flags: u32,
    /// `rows` field.
    pub rows: usize,
    /// `cols` field.
    pub cols: usize,
    /// `y` field.
    pub y: usize,
    /// `x` field.
    pub x: usize,
    /// `cursor_y` field.
    pub cursor_y: usize,
    /// `cursor_x` field.
    pub cursor_x: usize,
    /// `keypad` field.
    pub keypad: bool,
    /// `fg` field.
    pub fg: i32,
    /// `bg` field.
    pub bg: i32,
    /// `attrs` field.
    pub attrs: u32,
    /// Background `chtype` set by `zccmd_bg` (curses.c:908). Holds
    /// the OR'd attribute / color-pair / character mask C `wbkgd`
    /// receives.
    pub bg_chtype: u32,
    /// Per-window timeout in milliseconds. Port of the `wtimeout()`
    /// state set by `zccmd_timeout` (curses.c:1255). `-1` = blocking.
    pub timeout_ms: i32,
    /// `parent` field.
    pub parent: Option<String>,
    /// `children` field.
    pub children: Vec<String>,
    /// `buffer` field.
    buffer: Vec<Vec<char>>,
}

// =====================================================================
// Port of `struct zcurses_namenumberpair` from `curses.c:71`.
// =====================================================================

/// Name → number pair entry. Used by attributes and colors lookup
/// tables.
#[derive(Debug, Clone, Copy)]
pub struct zcurses_namenumberpair {
    /// `name` field.
    pub name: &'static str,
    /// `number` field.
    pub number: i32,
}

// =====================================================================
// Port of `struct colorpairnode` from `Src/Modules/curses.c:76`.
// =====================================================================

/// Hash-table node mapping a color-pair name to its allocated short.
/// C uses `struct hashnode` as the first field to support direct
/// HashTable insertion; Rust uses (name → colorpairnode) HashMap so
/// the node carries only the colorpair short here.
///
/// C definition (c:76-79):
/// ```c
/// struct colorpairnode {
///     struct hashnode node;
///     short colorpair;
/// };
/// typedef struct colorpairnode *Colorpairnode;
/// ```
#[derive(Debug, Clone, Copy)]
pub struct colorpairnode {
    // c:76
    /// Color pair index (libncurses `init_pair` slot).
    pub colorpair: i16, // c:78
}

// =====================================================================
// Port of `struct zcurses_subcommand` (curses.c:83) + dispatch
// table inside `bin_zcurses` (curses.c:1574).
// =====================================================================

/// Subcommand table entry. Port of `struct zcurses_subcommand`
/// from `Src/Modules/curses.c:83`.
struct zcurses_subcommand {
    name: &'static str,
    cmd: fn(&str, &[String]) -> i32, // c:84-85
    minargs: i32,
    maxargs: i32,
}

// =====================================================================
// Module-static state — port of `curses.c:90-113`.
//
// Per PORT_PLAN.md these are bucket 2 (shell-wide) since multiple
// callers (foreground evaluator + worker threads) may dispatch
// `zcurses` simultaneously.
// =====================================================================

/// Port of `static LinkList zcurses_windows` from `curses.c:92`.
/// HashMap keyed by window name; C uses an ordered linked list,
/// the Rust port keeps insertion order in `WINDOW_ORDER` so
/// `refresh` (no-arg) replays the same draw order.
static zcurses_windows: OnceLock<Mutex<HashMap<String, zc_win>>> = OnceLock::new();

/// Port of `static HashTable zcurses_colorpairs` from `curses.c:93`.
/// Maps `"fg/bg"` → pair index.
static zcurses_colorpairs: OnceLock<Mutex<HashMap<String, i16>>> = OnceLock::new();

// =====================================================================
// Port of `zccmd_mouse(const char *nam, char **args)` from `Src/Modules/curses.c:1294`.
// =====================================================================

/// `static int zcurses_flags` mouse mask, port of `curses.c:99`.
static zcurses_flags: OnceLock<Mutex<u32>> = OnceLock::new();

// =====================================================================
// Error constants — port of `curses.c:102-110`.
// =====================================================================

/// `zc_errno` value: window name invalid (NULL or empty).
pub const ZCURSES_EINVALID: i32 = 1;
/// `zc_errno` value: window already defined (failed UNUSED check).
pub const ZCURSES_EDEFINED: i32 = 2;
/// `zc_errno` value: window undefined (failed USED check).
pub const ZCURSES_EUNDEFINED: i32 = 3;

impl zc_win {
    /// WARNING: NOT IN CURSES.C — method on Rust-only `zc_win` wrapper.
    /// C inlines this pattern at every callsite; Rust factors it onto the wrapper.
    /// WARNING: NOT IN CURSES.C — Rust-only ctor; C uses
    /// `(ZCWin)zshcalloc(sizeof(struct zc_win))` then field-by-field
    /// assignment inside `zccmd_addwin` (curses.c:519).
    fn new(name: &str, rows: usize, cols: usize, y: usize, x: usize) -> Self {
        Self {
            name: name.to_string(),
            flags: 0,
            rows,
            cols,
            y,
            x,
            cursor_y: 0,
            cursor_x: 0,
            keypad: false,
            fg: -1,
            bg: -1,
            attrs: 0,
            bg_chtype: 0,
            timeout_ms: -1,
            parent: None,
            children: Vec::new(),
            buffer: vec![vec![' '; cols]; rows],
        }
    }

    /// WARNING: NOT IN CURSES.C — method on Rust-only `zc_win` wrapper.
    /// C inlines this pattern at every callsite; Rust factors it onto the wrapper.
    fn refresh(&self) -> io::Result<()> {
        let mut stdout = io::stdout();
        write!(stdout, "\x1b[{};{}H", self.y + 1, self.x + 1)?;
        let attr_sgr = sgr_for_attrs(self.attrs);
        write!(stdout, "{}", attr_sgr)?;
        for (row_idx, row) in self.buffer.iter().enumerate() {
            write!(stdout, "\x1b[{};{}H", self.y + row_idx + 1, self.x + 1)?;
            let line: String = row.iter().collect();
            write!(stdout, "{}", line)?;
        }
        write!(
            stdout,
            "\x1b[{};{}H",
            self.y + self.cursor_y + 1,
            self.x + self.cursor_x + 1
        )?;
        stdout.flush()
    }
}

/// `zcurses_validate_window` criterion: must NOT already exist.
pub const ZCURSES_UNUSED: i32 = 1;
/// `zcurses_validate_window` criterion: must already exist.
pub const ZCURSES_USED: i32 = 2;

/// `zccmd_attr` mode: turn attribute on.
pub const ZCURSES_ATTRON: i32 = 1;
/// `zccmd_attr` mode: turn attribute off.
pub const ZCURSES_ATTROFF: i32 = 2;

/// Port of `static short next_cp` from `curses.c:113`. Counter for
/// `init_pair()` allocations.
static next_cp: OnceLock<Mutex<i16>> = OnceLock::new();

/// Port of `struct zcurses_mouse_event` from `Src/Modules/curses.c:163`.
/// Maps a libncurses button bit to a (button-number, event-kind) pair.
///
/// C definition (c:163-167):
/// ```c
/// struct zcurses_mouse_event {
///     int button;
///     int what;
///     mmask_t event;
/// };
/// ```
#[derive(Debug, Clone, Copy)]
pub struct zcurses_mouse_event {
    // c:163
    /// Mouse button number (1..=5).
    pub button: i32, // c:164
    /// Event kind (`ZCME_*` from above).
    pub what: i32, // c:165
    /// libncurses mmask_t event bit (BUTTON1_PRESSED etc.).
    pub event: u64, // c:166
}

/// `static mmask_t zcurses_mouse_mask`, port of `curses.c:205`.
static zcurses_mouse_mask: OnceLock<Mutex<u32>> = OnceLock::new();

// =====================================================================
// Special-parameter accessors — `Src/Modules/curses.c:213`.
// Each backs one of zsh's `$zcurses_*` magic-assoc/array params.
// =====================================================================

/// Direct port of `zcurses_pairs_to_array(nnps)` from `Src/Modules/
/// curses.c:213`. C body (c:215-228): walk the namenumberpair table,
/// allocate a `char **` of length+1, fill with `dupstring(name)` per
/// entry, NULL-terminate. Rust returns `Vec<String>` directly.
pub fn zcurses_pairs_to_array(nnps: &[zcurses_namenumberpair]) -> Vec<String> {
    nnps.iter().map(|p| p.name.to_string()).collect() // c:222 dupstring
}

// =====================================================================
// Port of `zcurses_strerror(int err)` from `Src/Modules/curses.c:233`.
// =====================================================================

/// Port of `zcurses_strerror(int err)` from `Src/Modules/curses.c:233`.
///
/// Map a `zc_errno` value to its human-readable message. C uses a
/// static `errs[]` array keyed by errno; Rust port mirrors with
/// the same four messages in the same index order.
/// WARNING: param names don't match C — Rust=() vs C=(err)
pub(crate) fn zcurses_strerror(err: i32) -> &'static str {
    static ERRS: &[&str] = &[
        "unknown error",
        "window name invalid",
        "window already defined",
        "window undefined",
    ];
    let idx = if !(1..=3).contains(&err) {
        0
    } else {
        err as usize
    };
    ERRS[idx]
}

// =====================================================================
// Port of `zcurses_getwindowbyname(const char *name)` from `Src/Modules/curses.c:246`.
// =====================================================================

/// Port of `zcurses_getwindowbyname()` from
/// `Src/Modules/curses.c:246`. Linear-search the windows list for a
/// matching name. C returns the `LinkNode`; Rust port returns
/// `bool` (presence) since the HashMap-backed lookup doesn't expose
/// node iterators.
/// WARNING: param names don't match C — Rust=() vs C=(name)
pub(crate) fn zcurses_getwindowbyname(name: &str) -> bool {
    windows_lock().lock().unwrap().contains_key(name)
}

// =====================================================================
// Port of `zcurses_validate_window(char *win, int criteria)` from `Src/Modules/curses.c:259`.
// =====================================================================

/// Port of `zcurses_validate_window()` from
/// `Src/Modules/curses.c:259`. Validate `win` per the criteria
/// (`ZCURSES_UNUSED` = must not exist, `ZCURSES_USED` = must
/// exist), set `zc_errno`, return `true` on success / `false` on
/// failure.
///
/// Note: C returns the `LinkNode` (NULL = failure or
/// not-yet-defined); the Rust port returns a bool because the
/// HashMap doesn't expose a positional handle. Callers that need
/// the existing window get it via `zcurses_getwindowbyname` after a
/// successful USED check.
/// WARNING: param names don't match C — Rust=(criteria) vs C=(win, criteria)
pub(crate) fn zcurses_validate_window(win: &str, criteria: i32) -> bool {
    if win.is_empty() {
        zc_errno_set(ZCURSES_EINVALID);
        return false;
    }
    let target_present = zcurses_getwindowbyname(win);
    if target_present && (criteria & ZCURSES_UNUSED) != 0 {
        zc_errno_set(ZCURSES_EDEFINED);
        return false;
    }
    if !target_present && (criteria & ZCURSES_USED) != 0 {
        zc_errno_set(ZCURSES_EUNDEFINED);
        return false;
    }
    zc_errno_set(0);
    target_present
}

// =====================================================================
// Port of `zcurses_free_window(ZCWin w)` from `Src/Modules/curses.c:285`.
// =====================================================================

/// Port of `zcurses_free_window(ZCWin w)` from `Src/Modules/curses.c:285`.
///
/// Refuses to free permanent (`ZCWF_PERMANENT`) windows. Removes
/// from the windows map and the order tracker.
/// WARNING: param names don't match C — Rust=() vs C=(w)
pub(crate) fn zcurses_free_window(name: &str) -> i32 {
    let mut wins = windows_lock().lock().unwrap();
    if let Some(w) = wins.get(name) {
        if w.flags & ZCWF_PERMANENT != 0 {
            return 1;
        }
    }
    wins.remove(name);
    let mut order = order_lock().lock().unwrap();
    order.retain(|n| n != name);
    0
}

// =====================================================================
// Port of `zcurses_attrget(UNUSED(WINDOW *w), char *attr)` from `Src/Modules/curses.c:302`.
// =====================================================================

/// Port of `zcurses_attrget(UNUSED(WINDOW *w), char *attr)` from `Src/Modules/curses.c:302`.
///
/// Look up an attribute by user-facing name. Returns the matching
/// table entry (with `name`, `number`) on hit, `None` on miss.
/// WARNING: param names don't match C — Rust=(attr) vs C=(w, attr)
pub(crate) fn zcurses_attrget(_w: &zc_win, attr: &str) -> Option<&'static zcurses_namenumberpair> {
    if attr.is_empty() {
        return None;
    }
    zcurses_attributes.iter().find(|p| p.name == attr)
}

// =====================================================================
// Port of `zcurses_color(const char *color)` from `Src/Modules/curses.c:318`.
// =====================================================================

/// Port of `zcurses_color(const char *color)` from `Src/Modules/curses.c:318`.
///
/// Resolve a color name to its ncurses constant. Returns `-2` on
/// miss (matching C's sentinel — `-1` is `default`, so the miss
/// value sits one step further down).
/// WARNING: param names don't match C — Rust=() vs C=(color)
pub(crate) fn zcurses_color(color: &str) -> i32 {
    for c in zcurses_colors {
        if c.name == color {
            return c.number;
        }
    }
    -2
}

/// Port of `zcurses_colorget(const char *nam, char *colorpair)` from `Src/Modules/curses.c:331`.
/// C body parses `"fg/bg"` (numeric or named on each side), resolves
/// both via `zcurses_color`, allocates a new color-pair slot via
/// `init_pair(next_cp, fg, bg)`, and caches the result keyed by the
/// `"fg/bg"` string in `zcurses_colorpairs`. Returns the pair index.
///
/// C signature: `static Colorpairnode zcurses_colorget(const char *nam,
/// char *colorpair)`. Rust port returns `Option<i16>` (the pair slot)
/// since the Colorpairnode struct is collapsed into the
/// `HashMap<String, i16>` colorpairs store.
pub fn zcurses_colorget(nam: &str, colorpair: &str) -> Option<i16> {
    // c:331
    // c:331-342 — cache hit?
    {
        let g = colorpairs_lock().lock().ok()?;
        if let Some(&cp) = g.get(colorpair) {
            // c:342 gethashnode2
            return Some(cp);
        }
    }
    // c:347 — parse "fg/bg".
    let (cp_str, bg_str) = match colorpair.split_once('/') {
        // c:351
        Some(t) => t,
        None => return None, // c:354
    };
    // c:359-369 — resolve foreground.
    let f: i16 = if !cp_str.is_empty() && cp_str.chars().next().unwrap_or('x').is_ascii_digit() {
        // c:360
        cp_str.parse::<i16>().unwrap_or(-2) // c:361 atoi
    } else {
        zcurses_color(cp_str) as i16 // c:363
    };
    // c:365-369 — resolve background.
    let b: i16 = if !bg_str.is_empty() && bg_str.chars().next().unwrap_or('x').is_ascii_digit() {
        // c:365
        bg_str.parse::<i16>().unwrap_or(-2) // c:366
    } else {
        zcurses_color(bg_str) as i16 // c:368
    };
    // c:370-378 — error on unknown names.
    if f == -2 || b == -2 {
        // c:370
        if f == -2 {
            zwarnnam(
                nam, // c:372
                &format!("foreground color `{}' not known", cp_str),
            );
        }
        if b == -2 {
            zwarnnam(
                nam, // c:374
                &format!("background color `{}' not known", bg_str),
            );
        }
        return None; // c:377
    }
    // c:381 — ++next_cp.
    let mut np = next_cp_lock().lock().ok()?;
    *np += 1; // c:381
    let cp_slot = *np;
    // c:382 — COLOR_PAIRS limit / init_pair check. Without a live
    // ncurses link we accept any slot up to a large bound and skip
    // the actual init_pair call; the colorpairs map is what callers
    // consult to know the slot exists.
    if cp_slot < 0 || cp_slot >= 1024 {
        // c:382 COLOR_PAIRS
        return None;
    }
    let _ = (f, b); // init_pair would consume
    drop(np);
    // c:387-394 — calloc cpn + addhashnode.
    let mut g = colorpairs_lock().lock().ok()?;
    g.insert(colorpair.to_string(), cp_slot); // c:393 addhashnode
    Some(cp_slot) // c:397
}

/// Direct port of `zcurses_colornode(HashNode hn, int cp)` from `Src/Modules/curses.c:402`.
/// C body (c:404-407): scanhashtable callback that compares each
/// Colorpairnode's `colorpair` short field against `cp` and stashes
/// the matching node in the global `cpn_match`. Static-link path:
/// the Rust port returns the matching name directly so callers
/// don't need a side-channel global.
/// WARNING: param names don't match C — Rust=(name, pair, cp) vs C=(hn, cp)
pub fn zcurses_colornode(name: &str, pair: i16, cp: i16) -> Option<String> {
    // c:402
    if pair == cp {
        Some(name.to_string())
    } else {
        None
    } // c:410
}

/// Direct port of `zcurses_colorget_reverse(cp)` from `Src/Modules/
/// curses.c:410`. C body (c:412-419): scanhashtable over
/// `zcurses_colorpairs`, calling zcurses_colornode per node; returns
/// `cpn_match`. Static-link path: walk the colorpairs table and
/// return the first name whose pair matches.
pub fn zcurses_colorget_reverse(cp: i16) -> Option<String> {
    // c:410
    let g = colorpairs_lock().lock().ok()?; // c:410
    if g.is_empty() {
        return None;
    } // c:413
    for (name, pair) in g.iter() {
        // c:417 scanhashtable
        if let Some(matched) = zcurses_colornode(name, *pair, cp) {
            // c:417
            return Some(matched); // c:418 cpn_match
        }
    }
    None
}

/// Direct port of `freecolorpairnode(HashNode hn)` from `Src/Modules/curses.c:422`.
/// C body (c:424-427): `zsfree(hn->nam); zfree(hn, sizeof(struct
/// colorpairnode));`. Rust drop handles both via Box ownership.
pub fn freecolorpairnode(hn: &str) { // c:422
                                     // c:422-426 — frees handled by Rust drop; nothing to do.
}

// =====================================================================
// Port of `zccmd_init(UNUSED(const char *nam), UNUSED(char **args))` from `Src/Modules/curses.c:434`.
// =====================================================================

/// Port of `zccmd_init(UNUSED(const char *nam), UNUSED(char **args))` from `Src/Modules/curses.c:434`.
/// WARNING: param names don't match C — Rust=(_args) vs C=(nam, args)
pub(crate) fn zccmd_init(_nam: &str, _args: &[String]) -> i32 {
    if zcurses_getwindowbyname("stdscr") {
        // c:495-496 — `} else { settyinfo(&curses_tty_state); }` —
        // re-entry restores the CURSES-mode termios captured at c:494
        // (post-cbreak/noecho), re-ENTERING curses mode. The prior
        // port restored the pre-init cooked state here — exactly
        // inverted: `zcurses init` after an `end` dropped the
        // terminal back to cooked mode instead of re-arming cbreak.
        if let Ok(saved) = curses_tty_state.lock() {
            if let Some(ti) = saved.as_ref() {
                unsafe {
                    libc::tcsetattr(0, libc::TCSANOW, ti as *const _);
                }
            }
        }
        return 0;
    }
    // c:443 — `gettyinfo(&saved_tty_state);` — snapshot the
    // PRE-curses termios; zccmd_endwin's c:830 settyinfo restores
    // this to hand the terminal back to the shell.
    {
        let mut saved = saved_tty_state.lock().unwrap();
        if saved.is_none() {
            let mut ti: libc::termios = unsafe { std::mem::zeroed() };
            if unsafe { libc::tcgetattr(0, &mut ti) } == 0 {
                *saved = Some(ti);
            }
        }
    }
    let mut stdout = io::stdout();
    let _ = write!(stdout, "\x1b[?1049h\x1b[2J\x1b[H");
    let _ = stdout.flush();
    let _ = cbreak(); // c:492-493 cbreak(); noecho();
                      // c:494 — `gettyinfo(&curses_tty_state);` — snapshot the termios
                      // AFTER cbreak/noecho; this is what re-entry restores.
    {
        let mut cur = curses_tty_state.lock().unwrap();
        let mut ti: libc::termios = unsafe { std::mem::zeroed() };
        if unsafe { libc::tcgetattr(0, &mut ti) } == 0 {
            *cur = Some(ti);
        }
    }
    let (rows, cols) = terminal_size().unwrap_or((24, 80));
    let mut stdscr = zc_win::new("stdscr", rows, cols, 0, 0);
    stdscr.flags = ZCWF_PERMANENT;
    windows_lock()
        .lock()
        .unwrap()
        .insert("stdscr".into(), stdscr);
    order_lock().lock().unwrap().push("stdscr".into());
    *next_cp_lock().lock().unwrap() = 0;
    // C: addhashnode(zcurses_colorpairs, ztrdup("default/default"), …)
    // for the default pair.
    colorpairs_lock()
        .lock()
        .unwrap()
        .insert("default/default".into(), 0);
    0
}

// =====================================================================
// Port of `zccmd_addwin(const char *nam, char **args)` from `Src/Modules/curses.c:503`.
// =====================================================================

/// Port of `zccmd_addwin(const char *nam, char **args)` from `Src/Modules/curses.c:503`.
///
/// `addwin NAME ROWS COLS Y X [PARENT]`. Validates that NAME is
/// not already in use via `zcurses_validate_window(_, ZCURSES_UNUSED)`,
/// and (when PARENT is given) that PARENT exists via
/// `zcurses_validate_window(_, ZCURSES_USED)`.
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_addwin(nam: &str, args: &[String]) -> i32 {
    if !zcurses_validate_window(args[0].as_str(), ZCURSES_UNUSED) && zc_errno_get() != 0 {
        zerrnam(
            nam,
            &format!("{}: {}", zcurses_strerror(zc_errno_get()), args[0]),
        );
        return 1;
    }
    // c:514-517 — `nlines = atoi(args[1]); ncols = atoi(args[2]);
    //              begin_y = atoi(args[3]); begin_x = atoi(args[4]);`
    // atoi keeps the sign; the geometry contract is then newwin(3)'s:
    //   - nlines/ncols == 0 → extend to the screen's bottom/right
    //     edge (NOT an empty window — prior port created a 0x0
    //     buffer that silently "worked")
    //   - negative dims / origin off-screen → newwin returns NULL →
    //     c:551-555 "failed to create window `%s'" + exit 1 (prior
    //     port clamped negatives to 0 via parse::<usize> and never
    //     failed)
    let (nlines_raw, _) = crate::ported::utils::zstrtol(&args[1], 10); // c:514
    let (ncols_raw, _) = crate::ported::utils::zstrtol(&args[2], 10); // c:515
    let (begin_y_raw, _) = crate::ported::utils::zstrtol(&args[3], 10); // c:516
    let (begin_x_raw, _) = crate::ported::utils::zstrtol(&args[4], 10); // c:517
    let (scr_rows, scr_cols) = {
        let wins = windows_lock().lock().unwrap();
        wins.get("stdscr")
            .map(|s| (s.rows as i64, s.cols as i64))
            .unwrap_or((24, 80))
    };
    let fail_create = |nam: &str| -> i32 {
        // c:551-555 — `zwarnnam(nam, "failed to create window `%s'", w->name);`
        zwarnnam(nam, &format!("failed to create window `{}'", args[0]));
        1
    };
    if nlines_raw < 0
        || ncols_raw < 0
        || begin_y_raw < 0
        || begin_x_raw < 0
        || begin_y_raw >= scr_rows
        || begin_x_raw >= scr_cols
    {
        return fail_create(nam); // c:551 newwin NULL
    }
    // newwin(3): zero dims default to the distance to the screen edge.
    let nlines = if nlines_raw == 0 {
        (scr_rows - begin_y_raw) as usize
    } else {
        nlines_raw as usize
    };
    let ncols = if ncols_raw == 0 {
        (scr_cols - begin_x_raw) as usize
    } else {
        ncols_raw as usize
    };
    let begin_y = begin_y_raw as usize;
    let begin_x = begin_x_raw as usize;
    let mut w = zc_win::new(args[0].as_str(), nlines, ncols, begin_y, begin_x);
    if let Some(parent_name) = args.get(5) {
        // C: node = zcurses_validate_window(args[5], ZCURSES_USED);
        if !zcurses_validate_window(parent_name.as_str(), ZCURSES_USED) {
            zwarnnam(
                nam,
                &format!("{}: {}", zcurses_strerror(zc_errno_get()), args[0]),
            );
            return 1;
        }
        w.parent = Some(parent_name.clone());
        // C: zinsertlinknode(worig->children, lastnode(worig->children),
        //                    (void *)w);
        let mut wins = windows_lock().lock().unwrap();
        if let Some(parent) = wins.get_mut(parent_name.as_str()) {
            parent.children.push(args[0].clone());
        }
    }
    windows_lock().lock().unwrap().insert(args[0].clone(), w);
    order_lock().lock().unwrap().push(args[0].clone());
    0
}

// =====================================================================
// Port of `zccmd_delwin(const char *nam, char **args)` from `Src/Modules/curses.c:564`.
// =====================================================================

/// Port of `zccmd_delwin(const char *nam, char **args)` from `Src/Modules/curses.c:564`.
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_delwin(nam: &str, args: &[String]) -> i32 {
    // C: node = zcurses_validate_window(args[0], ZCURSES_USED);
    if !zcurses_validate_window(args[0].as_str(), ZCURSES_USED) {
        zwarnnam(
            nam,
            &format!("{}: {}", zcurses_strerror(zc_errno_get()), args[0]),
        );
        return 1;
    }
    // c:582-591 — pre-delete guards:
    //
    //     if (w->flags & ZCWF_PERMANENT) {
    //         zwarnnam(nam, "window `%s' can't be deleted", args[0]);
    //         return 1;
    //     }
    //     if (w->children && firstnode(w->children)) {
    //         zwarnnam(nam, "window `%s' has subwindows, delete those first",
    //                  w->name);
    //         return 1;
    //     }
    //
    // Prior port had no subwindow guard at all (a parent could be
    // deleted out from under its children, orphaning their parent
    // back-references) and the PERMANENT diagnostic dropped the
    // window name.
    let parent_name: Option<String> = {
        let wins = windows_lock().lock().unwrap();
        let w = match wins.get(args[0].as_str()) {
            Some(w) => w,
            None => return 1,
        };
        if w.flags & ZCWF_PERMANENT != 0 {
            // c:582-584
            zwarnnam(nam, &format!("window `{}' can't be deleted", args[0]));
            return 1;
        }
        if !w.children.is_empty() {
            // c:587-590
            zwarnnam(
                nam,
                &format!("window `{}' has subwindows, delete those first", args[0]),
            );
            return 1;
        }
        w.parent.clone()
    };
    if zcurses_free_window(args[0].as_str()) != 0 {
        zwarnnam(nam, &format!("window `{}' can't be deleted", args[0])); // c:583
        return 1;
    }
    // c:601-611 — `if (w->parent) { ...remnode(wpc, pcnode)... }` —
    // unlink the deleted window from its parent's children list so
    // the parent's subwindow guard above doesn't permanently wedge
    // on a stale name.
    if let Some(pname) = parent_name {
        let mut wins = windows_lock().lock().unwrap();
        if let Some(parent) = wins.get_mut(pname.as_str()) {
            parent.children.retain(|c| c != &args[0]); // c:608 remnode
        }
    }
    0 // c:627
}

// =====================================================================
// Port of `zccmd_refresh(const char *nam, char **args)` from `Src/Modules/curses.c:632`.
// =====================================================================

/// Port of `zccmd_refresh(const char *nam, char **args)` from `Src/Modules/curses.c:632`.
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_refresh(nam: &str, args: &[String]) -> i32 {
    let wins = windows_lock().lock().unwrap();
    if args.is_empty() {
        // C: refresh stdscr if no args; but the table also walks
        // through every window. Rust port matches C's "no args =
        // refresh stdscr" path via wnoutrefresh+doupdate inside C.
        if let Some(stdscr) = wins.get("stdscr") {
            let _ = stdscr.refresh();
        }
        return 0;
    }
    drop(wins);
    for name in args {
        if !zcurses_validate_window(name.as_str(), ZCURSES_USED) {
            zwarnnam(
                nam,
                &format!("{}: {}", zcurses_strerror(zc_errno_get()), name),
            );
            return 1;
        }
        if let Some(w) = windows_lock().lock().unwrap().get(name.as_str()) {
            let _ = w.refresh();
        }
    }
    0
}

// =====================================================================
// Port of `zccmd_move(const char *nam, char **args)` from `Src/Modules/curses.c:669`.
// =====================================================================

/// Port of `zccmd_move(const char *nam, char **args)` from `Src/Modules/curses.c:669`.
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_move(nam: &str, args: &[String]) -> i32 {
    if !zcurses_validate_window(args[0].as_str(), ZCURSES_USED) {
        zwarnnam(
            nam,
            &format!("{}: {}", zcurses_strerror(zc_errno_get()), args[0]),
        );
        return 1;
    }
    // c:681-687 — `y = atoi(args[1]); x = atoi(args[2]);
    //              if (wmove(w->win, y, x) != OK) return 1;`
    // atoi: garbage/negative input parses to whatever leading int
    // exists (0 for pure garbage, negative for "-1"); wmove then
    // REJECTS any (y,x) outside the window with ERR → exit 1. Prior
    // port parsed as usize (negative → 0) and silently swallowed
    // out-of-bounds moves, returning 0 — `zcurses move w 999 0`
    // exited 0 without moving where zsh exits 1.
    let (new_y, _) = crate::ported::utils::zstrtol(&args[1], 10); // c:681 atoi
    let (new_x, _) = crate::ported::utils::zstrtol(&args[2], 10); // c:682 atoi
    let mut wins = windows_lock().lock().unwrap();
    if let Some(w) = wins.get_mut(args[0].as_str()) {
        if new_y < 0 || new_x < 0 || new_y as usize >= w.rows || new_x as usize >= w.cols {
            return 1; // c:686-687 wmove != OK
        }
        w.cursor_y = new_y as usize;
        w.cursor_x = new_x as usize;
    }
    0 // c:689
}

// =====================================================================
// Port of `zccmd_clear(const char *nam, char **args)` from `Src/Modules/curses.c:694`.
// =====================================================================

/// Port of `zccmd_clear(const char *nam, char **args)` from `Src/Modules/curses.c:694`.
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_clear(nam: &str, args: &[String]) -> i32 {
    if !zcurses_validate_window(args[0].as_str(), ZCURSES_USED) {
        zwarnnam(
            nam,
            &format!("{}: {}", zcurses_strerror(zc_errno_get()), args[0]),
        );
        return 1;
    }
    // c:707-718 — submode dispatch:
    //
    //     if (!args[1]) {
    //         return werase(w->win) != OK;
    //     } else if (!strcmp(args[1], "redraw")) {
    //         return wclear(w->win) != OK;
    //     } else if (!strcmp(args[1], "eol")) {
    //         return wclrtoeol(w->win) != OK;
    //     } else if (!strcmp(args[1], "bot")) {
    //         return wclrtobot(w->win) != OK;
    //     } else {
    //         zwarnnam(nam, "`clear' expects `redraw', `eol' or `bot'");
    //         return 1;
    //     }
    //
    // Prior port ignored args[1] entirely — every submode full-wiped
    // the buffer AND homed the cursor (ncurses werase/wclear leave
    // the cursor where it was; only the cell contents blank). `eol` /
    // `bot` partial clears and the unknown-submode diagnostic were
    // all missing.
    let mode = args.get(1).map(|s| s.as_str());
    match mode {
        None | Some("redraw") => {} // validated below
        Some("eol") | Some("bot") => {}
        Some(_) => {
            // c:716-717
            zwarnnam(nam, "`clear' expects `redraw', `eol' or `bot'");
            return 1;
        }
    }
    let mut wins = windows_lock().lock().unwrap();
    if let Some(w) = wins.get_mut(args[0].as_str()) {
        match mode {
            None | Some("redraw") => {
                // c:708 werase / c:710 wclear — blank every cell; the
                // emulation has no clearok bit so both collapse to a
                // full wipe. Cursor stays put per ncurses semantics.
                for row in &mut w.buffer {
                    for cell in row {
                        *cell = ' ';
                    }
                }
            }
            Some("eol") => {
                // c:712 wclrtoeol — blank from cursor to end of line.
                if w.cursor_y < w.rows {
                    for x in w.cursor_x..w.cols {
                        w.buffer[w.cursor_y][x] = ' ';
                    }
                }
            }
            Some("bot") => {
                // c:714 wclrtobot — blank from cursor to end of line,
                // then every row below.
                if w.cursor_y < w.rows {
                    for x in w.cursor_x..w.cols {
                        w.buffer[w.cursor_y][x] = ' ';
                    }
                    for y in (w.cursor_y + 1)..w.rows {
                        for x in 0..w.cols {
                            w.buffer[y][x] = ' ';
                        }
                    }
                }
            }
            Some(_) => unreachable!(),
        }
    }
    0
}

// =====================================================================
// Port of `zccmd_char(const char *nam, char **args)` from `Src/Modules/curses.c:723`.
// =====================================================================

/// Port of `zccmd_char(const char *nam, char **args)` from `Src/Modules/curses.c:723`. Writes
/// one character into the window buffer at the current cursor.
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_char(nam: &str, args: &[String]) -> i32 {
    if !zcurses_validate_window(args[0].as_str(), ZCURSES_USED) {
        zwarnnam(
            nam,
            &format!("{}: {}", zcurses_strerror(zc_errno_get()), args[0]),
        );
        return 1;
    }
    let ch = match args[1].chars().next() {
        Some(c) => c,
        None => return 1,
    };
    let mut wins = windows_lock().lock().unwrap();
    if let Some(w) = wins.get_mut(args[0].as_str()) {
        if w.cursor_y < w.rows && w.cursor_x < w.cols {
            w.buffer[w.cursor_y][w.cursor_x] = ch;
            // C: wadd_wch advances the cursor.
            w.cursor_x += 1;
            if w.cursor_x >= w.cols {
                w.cursor_x = 0;
                if w.cursor_y + 1 < w.rows {
                    w.cursor_y += 1;
                }
            }
        }
    }
    0
}

// =====================================================================
// Port of `zccmd_string(const char *nam, char **args)` from `Src/Modules/curses.c:759`.
// =====================================================================

/// Port of `zccmd_string(const char *nam, char **args)` from `Src/Modules/curses.c:759`.
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_string(nam: &str, args: &[String]) -> i32 {
    if !zcurses_validate_window(args[0].as_str(), ZCURSES_USED) {
        zwarnnam(
            nam,
            &format!("{}: {}", zcurses_strerror(zc_errno_get()), args[0]),
        );
        return 1;
    }
    // c:780-788 — `mb_charinit();
    //              while (*str && (clen = mb_metacharlenconv(str, &wc))) {
    //                  str += clen;
    //                  if (wc == WEOF) continue;
    //                  *wptr++ = wc;
    //              }`
    // mb_metacharlenconv is the META-AWARE wide decoder: it strips
    // zsh's Meta+(byte^32) encoding while assembling each wchar. The
    // shell-side arg arrives metafied; walking chars() on it directly
    // fed the raw Meta escape pairs into the window buffer for any
    // high-byte text. Decode first, then per-char walk.
    let raw = crate::ported::utils::unmeta(&args[1]); // c:783 Meta strip
    let mut wins = windows_lock().lock().unwrap();
    if let Some(w) = wins.get_mut(args[0].as_str()) {
        for ch in raw.chars() {
            // c:783 wide-char walk
            if w.cursor_y < w.rows && w.cursor_x < w.cols {
                w.buffer[w.cursor_y][w.cursor_x] = ch;
                w.cursor_x += 1;
                if w.cursor_x >= w.cols {
                    w.cursor_x = 0;
                    if w.cursor_y + 1 < w.rows {
                        w.cursor_y += 1;
                    }
                }
            }
        }
    }
    0
}

// =====================================================================
// Port of `zccmd_border(const char *nam, char **args)` from `Src/Modules/curses.c:802`.
// =====================================================================

/// Port of `zccmd_border(const char *nam, char **args)` from `Src/Modules/curses.c:802`.
///
/// C calls libncurses's `wborder(w, 0, 0, 0, 0, 0, 0, 0, 0)` which
/// draws default ACS line-drawing chars around the window. The
/// Rust port writes Unicode box-drawing equivalents to the buffer
/// perimeter — the closest faithful match without libncurses ACS
/// codepoint dispatch.
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_border(nam: &str, args: &[String]) -> i32 {
    if !zcurses_validate_window(args[0].as_str(), ZCURSES_USED) {
        zwarnnam(
            nam,
            &format!("{}: {}", zcurses_strerror(zc_errno_get()), args[0]),
        );
        return 1;
    }
    let mut wins = windows_lock().lock().unwrap();
    if let Some(w) = wins.get_mut(args[0].as_str()) {
        if w.rows < 2 || w.cols < 2 {
            return 0;
        }
        // Top + bottom horizontal runs.
        for x in 1..w.cols.saturating_sub(1) {
            w.buffer[0][x] = '─';
            w.buffer[w.rows - 1][x] = '─';
        }
        // Left + right vertical runs.
        for y in 1..w.rows.saturating_sub(1) {
            w.buffer[y][0] = '│';
            w.buffer[y][w.cols - 1] = '│';
        }
        // Corners.
        w.buffer[0][0] = '┌';
        w.buffer[0][w.cols - 1] = '┐';
        w.buffer[w.rows - 1][0] = '└';
        w.buffer[w.rows - 1][w.cols - 1] = '┘';
    }
    0
}

// =====================================================================
// Port of `zccmd_endwin(UNUSED(const char *nam), UNUSED(char **args))` from `Src/Modules/curses.c:823`.
// =====================================================================

/// Port of `zccmd_endwin(UNUSED(const char *nam), UNUSED(char **args))` from `Src/Modules/curses.c:823`.
/// WARNING: param names don't match C — Rust=(_args) vs C=(nam, args)
pub(crate) fn zccmd_endwin(_nam: &str, _args: &[String]) -> i32 {
    // c:825-838:
    //
    //     if (stdscr_win) {
    //         endwin();
    //         /* Restore TTY as it was before zcurses -i */
    //         settyinfo(&saved_tty_state);
    //         gettyinfo(&shttyinfo);
    //     }
    //     return 0;
    if !zcurses_getwindowbyname("stdscr") {
        return 0;
    }
    let mut stdout = io::stdout();
    let _ = write!(stdout, "\x1b[?1049l\x1b[0m"); // c:828 endwin()
    let _ = stdout.flush();
    // c:830 — `settyinfo(&saved_tty_state);` — hand the terminal back
    // to the shell in its pre-`zcurses init` mode. Prior port skipped
    // this entirely, leaving the tty in cbreak/noecho after
    // `zcurses end` — a cooked-mode shell with no echo and no canonical
    // line editing until the user blind-typed `stty sane`.
    if let Ok(saved) = saved_tty_state.lock() {
        if let Some(ti) = saved.as_ref() {
            unsafe {
                libc::tcsetattr(0, libc::TCSANOW, ti as *const _);
            }
        }
    }
    // C endwin does NOT free the window list — windows survive so a
    // later `zcurses init` re-enters curses mode with state intact
    // (c:495-496 settyinfo path); only module cleanup_ frees them.
    // Prior port cleared windows/order/colorpairs here, destroying
    // every window across an end/init bounce.
    0 // c:838
}

// =====================================================================
// Port of `zccmd_attr(const char *nam, char **args)` from `Src/Modules/curses.c:843`.
// =====================================================================

/// Port of `zccmd_attr(const char *nam, char **args)` from `Src/Modules/curses.c:843`.
///
/// `attr WINDOW [+ATTR|-ATTR]...`: turn each named attribute on
/// (`+`) or off (`-`). C handles ZCURSES_ATTRON / ZCURSES_ATTROFF
/// dispatch internally; Rust port mirrors via the `+`/`-` prefix.
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_attr(nam: &str, args: &[String]) -> i32 {
    if !zcurses_validate_window(args[0].as_str(), ZCURSES_USED) {
        zwarnnam(
            nam,
            &format!("{}: {}", zcurses_strerror(zc_errno_get()), args[0]),
        );
        return 1;
    }
    let mut ret = 0; // c:848
    let mut wins = windows_lock().lock().unwrap();
    let w = match wins.get_mut(args[0].as_str()) {
        Some(w) => w,
        None => return 1,
    };
    for spec in &args[1..] {
        // c:861
        if spec.contains('/') {
            // c:862-866 — `if (strchr(*attrs, '/')) {
            //                  if ((cpn = zcurses_colorget(nam, *attrs)) == NULL ||
            //                      wcolor_set(w->win, cpn->colorpair, NULL) == ERR)
            //                      ret = 1;
            //              }`
            // Color-pair spec "fg/bg". Prior port had NO `/` arm —
            // `zcurses attr win red/black` fell into the attribute
            // lookup and errored "attribute `red/black' not known".
            // The pair index lands in the chtype-convention high bits
            // of w.attrs (same COLOR_PAIR(n)<<16 encoding zccmd_bg
            // uses) for the refresh-time SGR emitter.
            let cp = colorpair_get_or_alloc(spec);
            if cp < 0 {
                ret = 1; // c:866
            } else {
                w.attrs = (w.attrs & 0xffff) | ((cp as u32) << 16); // c:865 wcolor_set
            }
            continue;
        }
        // c:872-885 — leading +/- selects ATTRON/ATTROFF; bare name
        // defaults to ATTRON.
        let (mode, attr_name) = match spec.as_bytes().first() {
            Some(b'+') => (ZCURSES_ATTRON, &spec[1..]),  // c:877-879
            Some(b'-') => (ZCURSES_ATTROFF, &spec[1..]), // c:873-875
            _ => (ZCURSES_ATTRON, spec.as_str()),        // c:881-883
        };
        match zcurses_attrget(w, attr_name) {
            Some(entry) => match mode {
                ZCURSES_ATTRON => w.attrs |= entry.number as u32, // c:892 wattron
                ZCURSES_ATTROFF => w.attrs &= !(entry.number as u32), // c:896 wattroff
                _ => {}
            },
            None => {
                // c:886-888 — `zwarnnam(nam, "attribute `%s' not
                // known", ptr); ret = 1;` — C CONTINUES the loop so
                // later specs still apply; prior port returned 1
                // immediately, dropping every spec after the bad one.
                zwarnnam(nam, &format!("attribute `{}' not known", attr_name));
                ret = 1; // c:888
            }
        }
    }
    ret // c:903
}

// =====================================================================
// Port of `zccmd_bg(const char *nam, char **args)` from `Src/Modules/curses.c:908`.
// =====================================================================

/// Port of `zccmd_bg(const char *nam, char **args)` from `Src/Modules/curses.c:908`.
///
/// `bg WINDOW [+ATTR|-ATTR|@CHAR|FG/BG]...`: build a `chtype` mask
/// of attributes / a fill character / a color-pair, then apply it
/// as the window's background via `wbkgd()`. The Rust port stores
/// the resolved mask on `w.bg_chtype` since the ANSI-escape pipeline
/// emits the equivalent SGR at refresh time.
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_bg(nam: &str, args: &[String]) -> i32 {
    if !zcurses_validate_window(args[0].as_str(), ZCURSES_USED) {
        zwarnnam(
            nam,
            &format!("{}: {}", zcurses_strerror(zc_errno_get()), args[0]),
        );
        return 1;
    }
    let mut ret = 0;
    let mut ch: u32 = 0;
    let mut wins = windows_lock().lock().unwrap();
    let w = match wins.get_mut(args[0].as_str()) {
        Some(w) => w,
        None => return 1,
    };
    for spec in &args[1..] {
        if spec.contains('/') {
            // Color pair "fg/bg" — resolve via colorpairs, OR pair
            // index into ch's high bits per `COLOR_PAIR(n)`. Since
            // libncurses isn't linked we just record the pair index
            // for later SGR emission.
            let cp = colorpair_get_or_alloc(spec);
            if cp < 0 {
                ret = 1;
            } else {
                // C: ch |= COLOR_PAIR(cp); — high bits encode pair.
                ch |= (cp as u32) << 16;
            }
        } else if let Some(rest) = spec.strip_prefix('@') {
            // C: ch |= the character itself. Use first char.
            if let Some(c) = rest.chars().next() {
                ch |= c as u32;
            }
        } else {
            let (mode, attr_name) = match spec.as_bytes().first() {
                Some(b'+') => (ZCURSES_ATTRON, &spec[1..]),
                Some(b'-') => (ZCURSES_ATTROFF, &spec[1..]),
                _ => (ZCURSES_ATTRON, spec.as_str()),
            };
            match zcurses_attrget(w, attr_name) {
                Some(p) => {
                    if mode == ZCURSES_ATTRON {
                        ch |= p.number as u32; // c:967 wattron
                    } else {
                        ch &= !(p.number as u32); // c:971 wattroff
                    }
                }
                None => {
                    // c:961-963 — `zwarnnam(...); ret = 1;` — C
                    // continues the spec loop; prior port returned 1
                    // immediately, dropping later specs AND skipping
                    // the c:979 wbkgd gate below.
                    zwarnnam(nam, &format!("attribute `{}' not known", attr_name));
                    ret = 1; // c:963
                }
            }
        }
    }
    if ret == 0 {
        // C: return wbkgd(w->win, ch) != OK;
        w.bg_chtype = ch;
    }
    ret
}

// =====================================================================
// Port of `zccmd_scroll(const char *nam, char **args)` from `Src/Modules/curses.c:986`.
// =====================================================================

/// Port of `zccmd_scroll(const char *nam, char **args)` from `Src/Modules/curses.c:986`.
///
/// `scroll WINDOW (on|off|N)`: enable/disable scroll for the
/// window, or scroll by N lines.
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_scroll(nam: &str, args: &[String]) -> i32 {
    if !zcurses_validate_window(args[0].as_str(), ZCURSES_USED) {
        zwarnnam(
            nam,
            &format!("{}: {}", zcurses_strerror(zc_errno_get()), args[0]),
        );
        return 1;
    }
    let mut wins = windows_lock().lock().unwrap();
    let w = match wins.get_mut(args[0].as_str()) {
        Some(w) => w,
        None => return 1,
    };
    match args[1].as_str() {
        "on" => {
            w.flags |= ZCWF_SCROLL;
        }
        "off" => {
            w.flags &= !ZCWF_SCROLL;
        }
        s => {
            let n: i32 = match s.parse() {
                Ok(n) => n,
                Err(_) => {
                    drop(wins);
                    zwarnnam(
                        nam,
                        &format!("scroll requires `on', `off' or integer: {}", s),
                    );
                    return 1;
                }
            };
            // C: wscrl(w->win, sl) — scroll buffer up by N lines
            // (negative = down).
            if n > 0 {
                for _ in 0..n {
                    if !w.buffer.is_empty() {
                        w.buffer.remove(0);
                        w.buffer.push(vec![' '; w.cols]);
                    }
                }
            } else {
                for _ in 0..(-n) {
                    if !w.buffer.is_empty() {
                        w.buffer.pop();
                        w.buffer.insert(0, vec![' '; w.cols]);
                    }
                }
            }
        }
    }
    0
}

// =====================================================================
// Port of `zccmd_input(const char *nam, char **args)` from `Src/Modules/curses.c:1029`.
// =====================================================================

/// Port of `zccmd_input(const char *nam, char **args)` from `Src/Modules/curses.c:1029`.
///
/// `input WINDOW [VAR [KEYVAR [MOUSEVAR]]]`: read one character
/// from stdin into VAR. With KEYVAR, also recognise keypad / arrow /
/// function keys — the Rust port parses the common CSI sequences
/// (`\e[A`/`\e[B`/`\e[C`/`\e[D` for arrows, `\e[1~`/`\e[2~`/etc.).
/// With a fourth MOUSEVAR arg, `read_key_sequence` decodes the xterm
/// SGR-1006 mouse report (`\e[<b;x;yM|m`) — and the legacy X10 form
/// (`\e[Mbxy`) — into a synthesized `KEY_MOUSE` code + a pending
/// `Mevent`, which this branch maps to the MOUSEVAR array exactly as
/// C does via `getmouse` / `zcurses_mouse_map` (c:1209-1263).
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_input(nam: &str, args: &[String]) -> i32 {
    if !zcurses_validate_window(args[0].as_str(), ZCURSES_USED) {
        zwarnnam(
            nam,
            &format!("{}: {}", zcurses_strerror(zc_errno_get()), args[0]),
        );
        return 1;
    }
    // C: keypad(w->win, args.len() >= 3 ? TRUE : FALSE);
    let want_keypad = args.len() >= 3;

    // c:1108-1131 — mousemask() setup. Pure-Rust curses has no
    // libncurses, so "enabling mouse mode" means (a) flipping the
    // ZCF_MOUSE_ACTIVE state read_key_sequence's decoder gates on and
    // (b) asking the terminal to emit xterm mouse reports via DECSET
    // 1000 (X10) + 1006 (SGR) — the native analog of what ncurses'
    // mousemask() drives through terminfo. `nargs >= 4` == a MOUSEVAR
    // was supplied.
    if args.len() >= 4 {
        let mut flags = flags_lock().lock().unwrap();
        // c:1110-1111 — (re)arm when inactive or the mask changed.
        if *flags & ZCF_MOUSE_ACTIVE == 0 || *flags & ZCF_MOUSE_MASK_CHANGED != 0 {
            *flags = (*flags & !ZCF_MOUSE_MASK_CHANGED) | ZCF_MOUSE_ACTIVE; // c:1116-1117
            drop(flags);
            let mut out = io::stdout();
            let _ = write!(out, "\x1b[?1000h\x1b[?1006h");
            let _ = out.flush();
        }
    } else {
        // c:1125-1130 — no MOUSEVAR: disable mouse mode if it was on.
        let mut flags = flags_lock().lock().unwrap();
        if *flags & ZCF_MOUSE_ACTIVE != 0 {
            *flags &= !ZCF_MOUSE_ACTIVE; // c:1128
            drop(flags);
            let mut out = io::stdout();
            let _ = write!(out, "\x1b[?1006l\x1b[?1000l");
            let _ = out.flush();
        }
    }

    let timeout = windows_lock()
        .lock()
        .unwrap()
        .get(args[0].as_str())
        .map(|w| w.timeout_ms)
        .unwrap_or(-1);
    let (key_str, key_code) = match read_key_sequence(want_keypad, timeout) {
        Some(pair) => pair,
        None => return 1,
    };
    // c:1200-1204 — store the character string into VAR (default REPLY).
    let var = args.get(1).map(|v| v.as_str()).unwrap_or("REPLY");
    setsparam(var, &key_str);

    if want_keypad {
        // c:1206 — nargs >= 3.
        if key_code > 0 {
            // c:1207 — a keypad / mouse code, not a plain character.
            if args.len() >= 4 && key_code == KEY_MOUSE {
                // c:1209-1263 — KEY_MOUSE branch.
                if let Some(kv) = args.get(2) {
                    setsparam(kv, "MOUSE"); // c:1215
                }
                let mvar = &args[3];
                // c:1217 — getmouse(): pull the pending decoded event.
                match PENDING_MOUSE.lock().unwrap().take() {
                    None => {
                        // c:1224 — nothing queued: empty array, success.
                        setaparam(mvar, Vec::<String>::new());
                    }
                    Some(m) => {
                        // c:1226-1234 — id, x, y, z leading fields.
                        let mut margs: Vec<String> = vec![
                            m.id.to_string(),
                            m.x.to_string(),
                            m.y.to_string(),
                            m.z.to_string(),
                        ];
                        // c:1240-1255 — one "<EVENT><button>" token per
                        // matching bstate bit.
                        for me in ZCURSES_MOUSE_MAP {
                            if m.bstate & me.event != 0 {
                                if let Some(&(name, _)) = ZCURSES_MOUSE_EVENT_LIST
                                    .iter()
                                    .find(|&&(_, num)| num == me.what)
                                {
                                    margs.push(format!("{}{}", name, me.button));
                                }
                            }
                        }
                        // c:1256-1261 — modifier tokens.
                        if m.bstate & BUTTON_SHIFT != 0 {
                            margs.push("SHIFT".to_string());
                        }
                        if m.bstate & BUTTON_CTRL != 0 {
                            margs.push("CTRL".to_string());
                        }
                        if m.bstate & BUTTON_ALT != 0 {
                            margs.push("ALT".to_string());
                        }
                        setaparam(mvar, margs); // c:1262
                    }
                }
            } else if let Some(kv) = args.get(2) {
                // c:1264-1284 — non-mouse keypad code.
                if key_code >= KEY_F0 && key_code < KEY_F0 + 64 {
                    // c:1276-1281 — function keys aren't in keypad_names;
                    // F1.. print "Fn", KEY_F0 itself prints its raw number.
                    let fbuf = if key_code > KEY_F0 {
                        format!("F{}", key_code - KEY_F0)
                    } else {
                        key_code.to_string()
                    };
                    setsparam(kv, &fbuf); // c:1283
                } else if let Some(name) = keypad_name(key_code) {
                    // c:1269-1274 — named key: set KEYVAR and return
                    // WITHOUT clearing MOUSEVAR (C's early `return 0`).
                    setsparam(kv, &name);
                    return 0;
                } else {
                    // c:1280 — unrecognized number: print it raw.
                    setsparam(kv, &key_code.to_string()); // c:1283
                }
            }
        } else if let Some(kv) = args.get(2) {
            // c:1288-1290 — plain character: KEYVAR := "".
            setsparam(kv, "");
        }
    }
    // c:1294-1295 — a non-mouse read with a MOUSEVAR clears it to an
    // EMPTY ARRAY (mkarray(NULL)). Named keys already returned above.
    if key_code != KEY_MOUSE && args.len() >= 4 {
        setaparam(&args[3], Vec::<String>::new());
    }
    0 // c:1297
}

// =====================================================================
// Port of `zccmd_timeout(const char *nam, char **args)` from `Src/Modules/curses.c:1255`.
// =====================================================================

/// Port of `zccmd_timeout(const char *nam, char **args)` from `Src/Modules/curses.c:1255`.
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_timeout(nam: &str, args: &[String]) -> i32 {
    if !zcurses_validate_window(args[0].as_str(), ZCURSES_USED) {
        zwarnnam(
            nam,
            &format!("{}: {}", zcurses_strerror(zc_errno_get()), args[0]),
        );
        return 1;
    }
    let to: i32 = match args[1].parse() {
        Ok(n) => n,
        Err(_) => {
            zwarnnam(nam, &format!("timeout requires an integer: {}", args[1]));
            return 1;
        }
    };
    let mut wins = windows_lock().lock().unwrap();
    if let Some(w) = wins.get_mut(args[0].as_str()) {
        w.timeout_ms = to;
    }
    0
}

/// Port of `zccmd_mouse(const char *nam, char **args)` from `Src/Modules/curses.c:1294`.
///
/// `mouse [+motion|-motion|delay N]...`: toggle the mouse mode.
/// Without libncurses calling `mouseinterval()` / `mousemask()`, the
/// Rust port records the mask + delay into module statics; the
/// ZCF_MOUSE_MASK_CHANGED flag it sets makes the next `zcurses input`
/// re-arm the terminal, and `read_key_sequence` consults the mask when
/// decoding xterm SGR / X10 mouse reports.
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_mouse(nam: &str, args: &[String]) -> i32 {
    let mut idx = 0usize;
    while idx < args.len() {
        let arg = args[idx].as_str();
        if arg == "delay" {
            idx += 1;
            let v: i32 = match args.get(idx).and_then(|a| a.parse().ok()) {
                Some(v) => v,
                None => {
                    zwarnnam(nam, "mouse delay requires an integer argument");
                    return 1;
                }
            };
            // C: mouseinterval(delay).
            // WARNING: NOT IN CURSES.C — stored locally; libncurses's
            // `mouseinterval()` would be called when ncurses is linked.
            let _ = v;
            idx += 1;
        } else {
            let (onoff, name) = match arg.as_bytes().first() {
                Some(b'+') => (true, &arg[1..]),
                Some(b'-') => (false, &arg[1..]),
                _ => (true, arg),
            };
            if name == "motion" {
                let mut mask = mouse_mask_lock().lock().unwrap();
                let old = *mask;
                if onoff {
                    *mask |= REPORT_MOUSE_POSITION;
                } else {
                    *mask &= !REPORT_MOUSE_POSITION;
                }
                if old != *mask {
                    *flags_lock().lock().unwrap() |= ZCF_MOUSE_MASK_CHANGED;
                }
            } else {
                zwarnnam(nam, &format!("unrecognised mouse command: {}", name));
                return 1;
            }
            idx += 1;
        }
    }
    0
}

// =====================================================================
// Port of `zccmd_position(const char *nam, char **args)` from `Src/Modules/curses.c:1343`.
// =====================================================================

/// Port of `zccmd_position(const char *nam, char **args)` from `Src/Modules/curses.c:1343`.
///
/// `position WINDOW VAR`: write `[cy, cx, y, x, rows, cols]` into
/// the named array param. C uses `getyx`/`getbegyx`/`getmaxyx`
/// macros; Rust port reads the cached fields on `zc_win`.
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_position(nam: &str, args: &[String]) -> i32 {
    if !zcurses_validate_window(args[0].as_str(), ZCURSES_USED) {
        zwarnnam(
            nam,
            &format!("{}: {}", zcurses_strerror(zc_errno_get()), args[0]),
        );
        return 1;
    }
    let wins = windows_lock().lock().unwrap();
    let w = match wins.get(args[0].as_str()) {
        Some(w) => w,
        None => return 1,
    };
    let arr = vec![
        w.cursor_y.to_string(),
        w.cursor_x.to_string(),
        w.y.to_string(),
        w.x.to_string(),
        w.rows.to_string(),
        w.cols.to_string(),
    ];
    drop(wins);
    // c:1376 — `setaparam(args[1], array);` — REAL array of six
    // numbers (cury curx begy begx maxy maxx). Prior port colon-
    // joined into a scalar, so `$pos[1]` indexed the first CHARACTER
    // of "3:5:0:0:24:80" instead of the cursor row.
    setaparam(&args[1], arr); // c:1376
    0 // c:1377
}

// =====================================================================
// Port of `zccmd_querychar(const char *nam, char **args)` from `Src/Modules/curses.c:1382`.
// =====================================================================

/// Port of `zccmd_querychar(const char *nam, char **args)` from `Src/Modules/curses.c:1382`.
///
/// `querychar WINDOW [VAR]`: write `[char, color, attr...]` into
/// the named array (or `reply`). C uses `winch` to read the
/// character + color + attrs at the cursor; Rust port reads from
/// the in-memory buffer.
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_querychar(nam: &str, args: &[String]) -> i32 {
    if !zcurses_validate_window(args[0].as_str(), ZCURSES_USED) {
        zwarnnam(
            nam,
            &format!("{}: {}", zcurses_strerror(zc_errno_get()), args[0]),
        );
        return 1;
    }
    let var = args.get(1).cloned().unwrap_or_else(|| "reply".to_string());
    let wins = windows_lock().lock().unwrap();
    let w = match wins.get(args[0].as_str()) {
        Some(w) => w,
        None => return 1,
    };
    let ch = if w.cursor_y < w.rows && w.cursor_x < w.cols {
        w.buffer[w.cursor_y][w.cursor_x]
    } else {
        ' '
    };
    let mut clist: Vec<String> = Vec::new();
    clist.push(ch.to_string());
    // C reads the color pair via `PAIR_NUMBER(winch(...))` and
    // resolves to the registered name via `zcurses_colorget_reverse`.
    // Without libncurses linked we always report "default".
    clist.push("default".into());
    for entry in zcurses_attributes {
        if w.attrs & entry.number as u32 != 0 {
            clist.push(entry.name.to_string());
        }
    }
    drop(wins);
    // c:1467 — `return !setaparam(args[1] ? args[1] : "reply",
    //                             zlinklist2array(clist, 1));`
    // REAL array: [char, color-name, attr...]. Prior port colon-
    // joined into a scalar — `$reply[1]` returned the first char of
    // the join instead of the queried character, and a literal `:`
    // at the cursor corrupted the field split entirely.
    setaparam(&var, clist); // c:1467
    0
}

// =====================================================================
// Port of `zccmd_touch(const char *nam, char **args)` from `Src/Modules/curses.c:1472`.
// =====================================================================

/// Port of `zccmd_touch(const char *nam, char **args)` from `Src/Modules/curses.c:1472`.
///
/// `touch WINDOW...`: mark each window for full redraw. The Rust
/// port's refresh always rewrites the whole buffer, so this just
/// validates each name and is otherwise a no-op.
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_touch(nam: &str, args: &[String]) -> i32 {
    for name in args {
        if !zcurses_validate_window(name.as_str(), ZCURSES_USED) {
            zwarnnam(
                nam,
                &format!("{}: {}", zcurses_strerror(zc_errno_get()), name),
            );
            return 1;
        }
    }
    0
}

// =====================================================================
// Port of `zccmd_resize(const char *nam, char **args)` from `Src/Modules/curses.c:1494`.
// =====================================================================

/// Port of `zccmd_resize(const char *nam, char **args)` from `Src/Modules/curses.c:1494`.
///
/// `resize ROWS COLS [endwin|nosave|endwin_nosave]`: resize stdscr
/// (and via parent-child chain, sub-windows) to the new geometry.
/// The third arg gates whether to call `endwin()` first / save tty
/// state — both are no-ops in the ANSI-escape backend.
/// WARNING: param names don't match C — Rust=(args) vs C=(nam, args)
pub(crate) fn zccmd_resize(nam: &str, args: &[String]) -> i32 {
    if !zcurses_getwindowbyname("stdscr") {
        return 1;
    }
    let y: usize = args[0].parse().unwrap_or(0);
    let x: usize = args[1].parse().unwrap_or(0);
    if let Some(third) = args.get(2) {
        match third.as_str() {
            "endwin" | "nosave" | "endwin_nosave" => {}
            other => {
                zwarnnam(
                    nam,
                    &format!(
                        "`resize' expects `endwin', `nosave' or `endwin_nosave' for third argument, if given: {}",
                        other
                    ),
                );
                return 1;
            }
        }
    }
    if y == 0 && x == 0 && args.get(2).is_none() {
        // C special-case: just probe whether resize_term is available.
        return 0;
    }
    let mut wins = windows_lock().lock().unwrap();
    if let Some(w) = wins.get_mut("stdscr") {
        w.rows = y;
        w.cols = x;
        w.buffer = vec![vec![' '; x]; y];
        w.cursor_y = w.cursor_y.min(y.saturating_sub(1));
        w.cursor_x = w.cursor_x.min(x.saturating_sub(1));
    }
    0
}

// =====================================================================
// Port of `bin_zcurses(char *nam, char **args, UNUSED(Options ops), UNUSED(int func))` from `Src/Modules/curses.c:1568`.
// =====================================================================

/// Port of `bin_zcurses(char *nam, char **args, UNUSED(Options ops), UNUSED(int func))` from `Src/Modules/curses.c:1568`.
///
/// Subcommand dispatcher. Walks `SCS[]` for a matching name,
/// validates arg-count against `minargs`/`maxargs`, then enforces
/// the C source's "command can't be used before `zcurses init`"
/// invariant before delegating to the matched `zccmd_*`.
/// WARNING: param names don't match C — Rust=(args, _ops, _func) vs C=(nam, args, ops, func)
pub(crate) fn bin_zcurses(nam: &str, args: &[String], _ops: &options, _func: i32) -> i32 {
    if args.is_empty() {
        zwarnnam(nam, "subcommand required");
        return 1;
    }
    // C: for(zcsc = scs; zcsc->name; zcsc++) {
    //         if(!strcmp(args[0], zcsc->name)) break;
    //     }
    let cmd_name = args[0].as_str();
    let entry = match SCS.iter().find(|sc| sc.name == cmd_name) {
        Some(e) => e,
        None => {
            zwarnnam(nam, &format!("unknown subcommand: {}", cmd_name));
            return 1;
        }
    };
    // C: num_args = saargs - (args + 2);  — args after subcommand.
    let sub_args = &args[1..];
    let num_args = sub_args.len() as i32;
    if num_args < entry.minargs {
        zwarnnam(
            nam,
            &format!("too few arguments for subcommand: {}", cmd_name),
        );
        return 1;
    }
    if entry.maxargs >= 0 && num_args > entry.maxargs {
        zwarnnam(
            nam,
            &format!("too many arguments for subcommand: {}", cmd_name),
        );
        return 1;
    }
    // C: if (zcsc->cmd != zccmd_init && zcsc->cmd != zccmd_endwin &&
    //         !zcurses_getwindowbyname("stdscr")) { … return 1; }
    let is_init = matches!(cmd_name, "init");
    let is_end = matches!(cmd_name, "end");
    if !is_init && !is_end && !zcurses_getwindowbyname("stdscr") {
        zwarnnam(
            nam,
            &format!("command `{}' can't be used before `zcurses init'", cmd_name),
        );
        return 1;
    }
    (entry.cmd)(nam, sub_args)
}

/// Direct port of `zcurses_colorsarrgetfn()` from `Src/Modules/
/// curses.c:1641`. C body: `return zcurses_pairs_to_array(zcurses_colors);`
pub fn zcurses_colorsarrgetfn() -> Vec<String> {
    // c:1641
    zcurses_pairs_to_array(zcurses_colors) // c:1651
}

/// Direct port of `zcurses_attrgetfn()` from `Src/Modules/
/// curses.c:1651`. C body: `return zcurses_pairs_to_array(zcurses_attributes);`
pub fn zcurses_attrgetfn() -> Vec<String> {
    // c:1651
    zcurses_pairs_to_array(zcurses_attributes) // c:1661
}

/// Direct port of `zcurses_keycodesgetfn()` from `Src/Modules/
/// curses.c:1661`. C body: `return zcurses_pairs_to_array(keypad_names);`
/// Static-link path: walk the canonical KEY_* set the Rust port
/// already enumerates via keypad_name.
pub fn zcurses_keycodesgetfn() -> Vec<String> {
    // c:1661
    // Walk the full canonical KEY_* range mirroring C's
    // `zcurses_pairs_to_array(keypad_names)` over the awk-generated
    // table. keypad_name returns None for unrecognized codes so the
    // filter_map prunes any gaps (KEY_F0+1..KEY_F0+63 are F-keys per
    // the inline range in keypad_name; codes outside the named
    // ranges are silently dropped).
    let base = (0o401..=0o407).chain(0o510..=0o633);
    let fkeys = (0..64).map(|n| KEY_F0 + n);
    base.chain(fkeys).filter_map(keypad_name).collect()
}

/// Direct port of `zcurses_windowsgetfn()` from `Src/Modules/
/// curses.c:1671`. C body (c:1675-1683): walk the `zcurses_windows`
/// LinkList collecting each ZCWin's `name`. Rust port reads from
/// the `order_lock` insertion-order tracker so the result preserves
/// creation order matching C's LinkList walk.
pub fn zcurses_windowsgetfn() -> Vec<String> {
    // c:1671
    order_lock().lock().map(|g| g.clone()).unwrap_or_default() // c:1691
}

/// Direct port of `zcurses_colorsintgetfn()` from `Src/Modules/
/// curses.c:1691`. C body: `return COLORS;` (the ncurses global).
/// Static-link path: probe the live ncurses COLORS via tigetnum.
pub fn zcurses_colorsintgetfn() -> i64 {
    // c:1691
    let cap = std::ffi::CString::new("colors").unwrap();
    let n = unsafe { libc_tigetnum(cap.as_ptr()) }; // c:1701 COLORS
    if n < 0 {
        0
    } else {
        n as i64
    }
}

/// Direct port of `zcurses_colorpairsintgetfn()` from `Src/Modules/
/// curses.c:1701`. C body: `return COLOR_PAIRS;`. Same probe as above
/// against the `pairs` capability.
pub fn zcurses_colorpairsintgetfn() -> i64 {
    // c:1701
    let cap = std::ffi::CString::new("pairs").unwrap();
    let n = unsafe { libc_tigetnum(cap.as_ptr()) }; // c:1703 COLOR_PAIRS
    if n < 0 {
        0
    } else {
        n as i64
    }
}

// =====================================================================
// Module entry points (curses.c:1744+).
// =====================================================================

/// Port of `setup_(UNUSED(Module m))` from `Src/Modules/curses.c:1744`. C body:
/// `return 0;`.
#[allow(unused_variables)]
pub fn setup_(m: *const module) -> i32 {
    // c:1744
    0
}

/// Port of `features_(UNUSED(Module m), UNUSED(char ***features))` from `Src/Modules/curses.c:1751`.
pub fn features_(m: *const module, features: &mut Vec<String>) -> i32 {
    // c:1751
    *features = featuresarray(m, module_features());
    0
}

/// Port of `enables_(UNUSED(Module m), UNUSED(int **enables))` from `Src/Modules/curses.c`.
pub fn enables_(m: *const module, enables: &mut Option<Vec<i32>>) -> i32 {
    // c:1759
    handlefeatures(m, module_features(), enables)
}

/// Port of `boot_(UNUSED(Module m))` from `Src/Modules/curses.c`. C body: `return 0;`.
/// WARNING: param names don't match C — Rust=(_m) vs C=(m)
pub fn boot_(_m: *const module) -> i32 {
    // c:1766
    0
}

/// Port of `cleanup_(UNUSED(Module m))` from `Src/Modules/curses.c`.
pub fn cleanup_(m: *const module) -> i32 {
    // c:1775
    setfeatureenables(m, module_features(), None)
}

/// Port of `finish_(UNUSED(Module m))` from `Src/Modules/curses.c`. C body: `return 0;`.
/// WARNING: param names don't match C — Rust=(_m) vs C=(m)
pub fn finish_(_m: *const module) -> i32 {
    // c:1785
    0
}

// =====================================================================
// Port of `enum zc_win_flags` from `Src/Modules/curses.c:54`.
// =====================================================================

// Window is permanent (probably "stdscr")                                  // c:55
/// Window is permanent (probably "stdscr"). C: `curses.c:56`.
pub const ZCWF_PERMANENT: u32 = 0x0001; // c:56
                                        // Scrolling enabled                                                        // c:57
/// Scrolling enabled. C: `curses.c:58`.
pub const ZCWF_SCROLL: u32 = 0x0002; // c:58

/// Port of `enum zcurses_mouse_event_types` from `Src/Modules/curses.c:146`.
/// Mouse-event discriminator bits returned by `zcurses input` mouse
/// reads.
pub const ZCME_PRESSED: i32 = 0; // c:147
/// `ZCME_RELEASED` constant.
pub const ZCME_RELEASED: i32 = 1; // c:148
/// `ZCME_CLICKED` constant.
pub const ZCME_CLICKED: i32 = 2; // c:149
/// `ZCME_DOUBLE_CLICKED` constant.
pub const ZCME_DOUBLE_CLICKED: i32 = 3; // c:150
/// `ZCME_TRIPLE_CLICKED` constant.
pub const ZCME_TRIPLE_CLICKED: i32 = 4; // c:151

/// `KEY_MOUSE` libncurses keycode (`curses.h`: `#define KEY_MOUSE 0631`).
/// Synthesized by `read_key_sequence` when it decodes an xterm mouse
/// report, then consumed by `zccmd_input`'s mouse branch (c:1209).
pub const KEY_MOUSE: i32 = 0o631;

// ncurses mouse-event bit masks (`curses.h` BUTTONn_* /
// BUTTON_SHIFT/CTRL/ALT). Layout follows NCURSES_MOUSE_VERSION 2:
//   NCURSES_MOUSE_MASK(b, m) = m << ((b - 1) * 5)
// with event bases NCURSES_BUTTON_RELEASED=001, _PRESSED=002,
// _CLICKED=004, _DOUBLE_CLICKED=010, _TRIPLE_CLICKED=020 and the
// SHIFT/CTRL/ALT/REPORT modifiers in the button-6 slot (shift 25).
// This is consistent with the already-defined
// `REPORT_MOUSE_POSITION = 010 << 25 = 1 << 28`. The names + bit
// positions match curses.h so the `ZCURSES_MOUSE_MAP` table below is
// reviewable side-by-side against `zcurses_mouse_map[]` (c:169).
/// `BUTTON1_RELEASED` (curses.h).
pub const BUTTON1_RELEASED: u64 = 0o1 << 0;
/// `BUTTON1_PRESSED` (curses.h).
pub const BUTTON1_PRESSED: u64 = 0o2 << 0;
/// `BUTTON1_CLICKED` (curses.h).
pub const BUTTON1_CLICKED: u64 = 0o4 << 0;
/// `BUTTON1_DOUBLE_CLICKED` (curses.h).
pub const BUTTON1_DOUBLE_CLICKED: u64 = 0o10 << 0;
/// `BUTTON1_TRIPLE_CLICKED` (curses.h).
pub const BUTTON1_TRIPLE_CLICKED: u64 = 0o20 << 0;
/// `BUTTON2_RELEASED` (curses.h).
pub const BUTTON2_RELEASED: u64 = 0o1 << 5;
/// `BUTTON2_PRESSED` (curses.h).
pub const BUTTON2_PRESSED: u64 = 0o2 << 5;
/// `BUTTON2_CLICKED` (curses.h).
pub const BUTTON2_CLICKED: u64 = 0o4 << 5;
/// `BUTTON2_DOUBLE_CLICKED` (curses.h).
pub const BUTTON2_DOUBLE_CLICKED: u64 = 0o10 << 5;
/// `BUTTON2_TRIPLE_CLICKED` (curses.h).
pub const BUTTON2_TRIPLE_CLICKED: u64 = 0o20 << 5;
/// `BUTTON3_RELEASED` (curses.h).
pub const BUTTON3_RELEASED: u64 = 0o1 << 10;
/// `BUTTON3_PRESSED` (curses.h).
pub const BUTTON3_PRESSED: u64 = 0o2 << 10;
/// `BUTTON3_CLICKED` (curses.h).
pub const BUTTON3_CLICKED: u64 = 0o4 << 10;
/// `BUTTON3_DOUBLE_CLICKED` (curses.h).
pub const BUTTON3_DOUBLE_CLICKED: u64 = 0o10 << 10;
/// `BUTTON3_TRIPLE_CLICKED` (curses.h).
pub const BUTTON3_TRIPLE_CLICKED: u64 = 0o20 << 10;
/// `BUTTON4_RELEASED` (curses.h).
pub const BUTTON4_RELEASED: u64 = 0o1 << 15;
/// `BUTTON4_PRESSED` (curses.h).
pub const BUTTON4_PRESSED: u64 = 0o2 << 15;
/// `BUTTON4_CLICKED` (curses.h).
pub const BUTTON4_CLICKED: u64 = 0o4 << 15;
/// `BUTTON4_DOUBLE_CLICKED` (curses.h).
pub const BUTTON4_DOUBLE_CLICKED: u64 = 0o10 << 15;
/// `BUTTON4_TRIPLE_CLICKED` (curses.h).
pub const BUTTON4_TRIPLE_CLICKED: u64 = 0o20 << 15;
/// `BUTTON5_RELEASED` (curses.h).
pub const BUTTON5_RELEASED: u64 = 0o1 << 20;
/// `BUTTON5_PRESSED` (curses.h).
pub const BUTTON5_PRESSED: u64 = 0o2 << 20;
/// `BUTTON5_CLICKED` (curses.h).
pub const BUTTON5_CLICKED: u64 = 0o4 << 20;
/// `BUTTON5_DOUBLE_CLICKED` (curses.h).
pub const BUTTON5_DOUBLE_CLICKED: u64 = 0o10 << 20;
/// `BUTTON5_TRIPLE_CLICKED` (curses.h).
pub const BUTTON5_TRIPLE_CLICKED: u64 = 0o20 << 20;
/// `BUTTON_CTRL` (curses.h) — control modifier bit.
pub const BUTTON_CTRL: u64 = 0o1 << 25;
/// `BUTTON_SHIFT` (curses.h) — shift modifier bit.
pub const BUTTON_SHIFT: u64 = 0o2 << 25;
/// `BUTTON_ALT` (curses.h) — alt/meta modifier bit.
pub const BUTTON_ALT: u64 = 0o4 << 25;

/// Port of `static const struct zcurses_mouse_event zcurses_mouse_map[]`
/// from `Src/Modules/curses.c:169`. Maps each ncurses button bit to a
/// `(button-number, event-kind)` pair for the decode loop at c:1240.
static ZCURSES_MOUSE_MAP: &[zcurses_mouse_event] = &[
    zcurses_mouse_event { button: 1, what: ZCME_PRESSED, event: BUTTON1_PRESSED }, // c:170
    zcurses_mouse_event { button: 1, what: ZCME_RELEASED, event: BUTTON1_RELEASED }, // c:171
    zcurses_mouse_event { button: 1, what: ZCME_CLICKED, event: BUTTON1_CLICKED }, // c:172
    zcurses_mouse_event { button: 1, what: ZCME_DOUBLE_CLICKED, event: BUTTON1_DOUBLE_CLICKED }, // c:173
    zcurses_mouse_event { button: 1, what: ZCME_TRIPLE_CLICKED, event: BUTTON1_TRIPLE_CLICKED }, // c:174
    zcurses_mouse_event { button: 2, what: ZCME_PRESSED, event: BUTTON2_PRESSED }, // c:176
    zcurses_mouse_event { button: 2, what: ZCME_RELEASED, event: BUTTON2_RELEASED }, // c:177
    zcurses_mouse_event { button: 2, what: ZCME_CLICKED, event: BUTTON2_CLICKED }, // c:178
    zcurses_mouse_event { button: 2, what: ZCME_DOUBLE_CLICKED, event: BUTTON2_DOUBLE_CLICKED }, // c:179
    zcurses_mouse_event { button: 2, what: ZCME_TRIPLE_CLICKED, event: BUTTON2_TRIPLE_CLICKED }, // c:180
    zcurses_mouse_event { button: 3, what: ZCME_PRESSED, event: BUTTON3_PRESSED }, // c:182
    zcurses_mouse_event { button: 3, what: ZCME_RELEASED, event: BUTTON3_RELEASED }, // c:183
    zcurses_mouse_event { button: 3, what: ZCME_CLICKED, event: BUTTON3_CLICKED }, // c:184
    zcurses_mouse_event { button: 3, what: ZCME_DOUBLE_CLICKED, event: BUTTON3_DOUBLE_CLICKED }, // c:185
    zcurses_mouse_event { button: 3, what: ZCME_TRIPLE_CLICKED, event: BUTTON3_TRIPLE_CLICKED }, // c:186
    zcurses_mouse_event { button: 4, what: ZCME_PRESSED, event: BUTTON4_PRESSED }, // c:188
    zcurses_mouse_event { button: 4, what: ZCME_RELEASED, event: BUTTON4_RELEASED }, // c:189
    zcurses_mouse_event { button: 4, what: ZCME_CLICKED, event: BUTTON4_CLICKED }, // c:190
    zcurses_mouse_event { button: 4, what: ZCME_DOUBLE_CLICKED, event: BUTTON4_DOUBLE_CLICKED }, // c:191
    zcurses_mouse_event { button: 4, what: ZCME_TRIPLE_CLICKED, event: BUTTON4_TRIPLE_CLICKED }, // c:192
    // c:194-201 — button 5 (guarded by `#ifdef BUTTON5_PRESSED` in C;
    // present here since the version-2 layout always defines it).
    zcurses_mouse_event { button: 5, what: ZCME_PRESSED, event: BUTTON5_PRESSED }, // c:196
    zcurses_mouse_event { button: 5, what: ZCME_RELEASED, event: BUTTON5_RELEASED }, // c:197
    zcurses_mouse_event { button: 5, what: ZCME_CLICKED, event: BUTTON5_CLICKED }, // c:198
    zcurses_mouse_event { button: 5, what: ZCME_DOUBLE_CLICKED, event: BUTTON5_DOUBLE_CLICKED }, // c:199
    zcurses_mouse_event { button: 5, what: ZCME_TRIPLE_CLICKED, event: BUTTON5_TRIPLE_CLICKED }, // c:200
];

/// Port of `static const struct zcurses_namenumberpair
/// zcurses_mouse_event_list[]` from `Src/Modules/curses.c:154`.
static ZCURSES_MOUSE_EVENT_LIST: &[(&str, i32)] = &[
    ("PRESSED", ZCME_PRESSED),               // c:155
    ("RELEASED", ZCME_RELEASED),             // c:156
    ("CLICKED", ZCME_CLICKED),               // c:157
    ("DOUBLE_CLICKED", ZCME_DOUBLE_CLICKED), // c:158
    ("TRIPLE_CLICKED", ZCME_TRIPLE_CLICKED), // c:159
];

/// ncurses `MEVENT` (`curses.h`) — one decoded mouse report, holding
/// the fields `zccmd_input` reads at c:1227-1234 and the `bstate` it
/// tests at c:1240-1261. `id`/`z` are unused by the terminal decoder
/// (kept for MEVENT parity); `x`/`y` are 0-based screen coordinates,
/// as ncurses' `getmouse()` returns them.
#[derive(Debug, Clone, Copy)]
pub struct Mevent {
    /// Device id (`MEVENT.id`); always 0 for the terminal decoder.
    pub id: i32,
    /// 0-based column (`MEVENT.x`).
    pub x: i32,
    /// 0-based row (`MEVENT.y`).
    pub y: i32,
    /// Unused scroll axis (`MEVENT.z`).
    pub z: i32,
    /// Button + modifier state bits (`MEVENT.bstate`).
    pub bstate: u64,
}

/// Pending decoded mouse event — the terminal-decoder analog of
/// ncurses' internal `getmouse()` FIFO. `read_key_sequence` stores an
/// event here when it synthesizes `KEY_MOUSE`; `zccmd_input`'s mouse
/// branch (c:1217 `getmouse`) takes it back out. Single slot: "we only
/// expect one event" (c:1236). Accessed inline (no accessor fn) to keep
/// the port a data extension, not a new function.
#[allow(non_upper_case_globals)]
static PENDING_MOUSE: Mutex<Option<Mevent>> = Mutex::new(None);

// =====================================================================
// Port of `static const struct zcurses_namenumberpair
// zcurses_attributes[]` from `curses.c:120`. ncurses constant
// values mirrored byte-for-byte (A_BOLD = 1<<8, etc.).
// =====================================================================

/// libncurses `A_BLINK` from `<curses.h>`.
pub const A_BLINK: i32 = 1 << 11;
/// libncurses `A_BOLD`.
pub const A_BOLD: i32 = 1 << 13;
/// libncurses `A_DIM`.
pub const A_DIM: i32 = 1 << 12;
/// libncurses `A_REVERSE`.
pub const A_REVERSE: i32 = 1 << 10;
/// libncurses `A_STANDOUT`.
pub const A_STANDOUT: i32 = 1 << 8;
/// libncurses `A_UNDERLINE`.
pub const A_UNDERLINE: i32 = 1 << 9;

/// Port of `zcurses_attributes[]` from `Src/Modules/curses.c:120`.
pub static zcurses_attributes: &[zcurses_namenumberpair] = &[
    zcurses_namenumberpair {
        name: "blink",
        number: A_BLINK,
    },
    zcurses_namenumberpair {
        name: "bold",
        number: A_BOLD,
    },
    zcurses_namenumberpair {
        name: "dim",
        number: A_DIM,
    },
    zcurses_namenumberpair {
        name: "reverse",
        number: A_REVERSE,
    },
    zcurses_namenumberpair {
        name: "standout",
        number: A_STANDOUT,
    },
    zcurses_namenumberpair {
        name: "underline",
        number: A_UNDERLINE,
    },
];

// =====================================================================
// Port of `zcurses_colors[]` from `Src/Modules/curses.c:130`.
// =====================================================================

/// libncurses `COLOR_BLACK` from `<curses.h>`.
pub const COLOR_BLACK: i32 = 0;
/// libncurses `COLOR_RED`.
pub const COLOR_RED: i32 = 1;
/// libncurses `COLOR_GREEN`.
pub const COLOR_GREEN: i32 = 2;
/// libncurses `COLOR_YELLOW`.
pub const COLOR_YELLOW: i32 = 3;
/// libncurses `COLOR_BLUE`.
pub const COLOR_BLUE: i32 = 4;
/// libncurses `COLOR_MAGENTA`.
pub const COLOR_MAGENTA: i32 = 5;
/// libncurses `COLOR_CYAN`.
pub const COLOR_CYAN: i32 = 6;
/// libncurses `COLOR_WHITE`.
pub const COLOR_WHITE: i32 = 7;

/// Port of `zcurses_colors[]` from `Src/Modules/curses.c:130`.
pub static zcurses_colors: &[zcurses_namenumberpair] = &[
    zcurses_namenumberpair {
        name: "black",
        number: COLOR_BLACK,
    },
    zcurses_namenumberpair {
        name: "red",
        number: COLOR_RED,
    },
    zcurses_namenumberpair {
        name: "green",
        number: COLOR_GREEN,
    },
    zcurses_namenumberpair {
        name: "yellow",
        number: COLOR_YELLOW,
    },
    zcurses_namenumberpair {
        name: "blue",
        number: COLOR_BLUE,
    },
    zcurses_namenumberpair {
        name: "magenta",
        number: COLOR_MAGENTA,
    },
    zcurses_namenumberpair {
        name: "cyan",
        number: COLOR_CYAN,
    },
    zcurses_namenumberpair {
        name: "white",
        number: COLOR_WHITE,
    },
    zcurses_namenumberpair {
        name: "default",
        number: -1,
    },
];

/// Insertion order tracker for `zcurses_windows`. C's LinkList
/// gives this for free; Rust port uses a parallel Vec.
static WINDOW_ORDER: OnceLock<Mutex<Vec<String>>> = OnceLock::new();

/// Port of `static int zc_errno` from `curses.c:112`. Last
/// validation error code set by `zcurses_validate_window`.
static zc_errno_cell: OnceLock<Mutex<i32>> = OnceLock::new();

/// `curses_tty_state` — file-static `struct ttyinfo curses_tty_state;`
/// from Src/Modules/curses.c:75. Snapshotted by gettyinfo at first
/// init (c:443), restored by settyinfo on re-entry (c:438).
#[allow(non_upper_case_globals)]
static curses_tty_state: Mutex<Option<libc::termios>> = Mutex::new(None); // c:75

/// `saved_tty_state` — file-static `struct ttyinfo saved_tty_state;`
/// from `Src/Modules/curses.c:74`. The PRE-`zcurses init` termios
/// snapshot (c:443 gettyinfo); zccmd_endwin's c:830 settyinfo
/// restores it to hand the terminal back to the shell.
#[allow(non_upper_case_globals)]
static saved_tty_state: Mutex<Option<libc::termios>> = Mutex::new(None); // c:74

/// `ZCF_MOUSE_ACTIVE` flag (curses.c:116).
pub const ZCF_MOUSE_ACTIVE: u32 = 1 << 0;
/// `ZCF_MOUSE_MASK_CHANGED` flag (curses.c:117).
pub const ZCF_MOUSE_MASK_CHANGED: u32 = 1 << 1;

/// `REPORT_MOUSE_POSITION` libncurses constant. Port of the bit
/// `zcurses_mouse_mask` toggles for `mouse motion`.
pub const REPORT_MOUSE_POSITION: u32 = 1 << 28;

/// Port of the `struct zcurses_subcommand scs[]` array inside
/// `bin_zcurses` (curses.c:1574). Order + min/max args match C.
static SCS: &[zcurses_subcommand] = &[
    zcurses_subcommand {
        name: "init",
        cmd: zccmd_init,
        minargs: 0,
        maxargs: 0,
    },
    zcurses_subcommand {
        name: "addwin",
        cmd: zccmd_addwin,
        minargs: 5,
        maxargs: 6,
    },
    zcurses_subcommand {
        name: "delwin",
        cmd: zccmd_delwin,
        minargs: 1,
        maxargs: 1,
    },
    zcurses_subcommand {
        name: "refresh",
        cmd: zccmd_refresh,
        minargs: 0,
        maxargs: -1,
    },
    zcurses_subcommand {
        name: "move",
        cmd: zccmd_move,
        minargs: 3,
        maxargs: 3,
    },
    zcurses_subcommand {
        name: "clear",
        cmd: zccmd_clear,
        minargs: 1,
        maxargs: 2,
    },
    zcurses_subcommand {
        name: "position",
        cmd: zccmd_position,
        minargs: 2,
        maxargs: 2,
    },
    zcurses_subcommand {
        name: "char",
        cmd: zccmd_char,
        minargs: 2,
        maxargs: 2,
    },
    zcurses_subcommand {
        name: "string",
        cmd: zccmd_string,
        minargs: 2,
        maxargs: 2,
    },
    zcurses_subcommand {
        name: "border",
        cmd: zccmd_border,
        minargs: 1,
        maxargs: 1,
    },
    zcurses_subcommand {
        name: "end",
        cmd: zccmd_endwin,
        minargs: 0,
        maxargs: 0,
    },
    zcurses_subcommand {
        name: "attr",
        cmd: zccmd_attr,
        minargs: 2,
        maxargs: -1,
    },
    zcurses_subcommand {
        name: "bg",
        cmd: zccmd_bg,
        minargs: 2,
        maxargs: -1,
    },
    zcurses_subcommand {
        name: "scroll",
        cmd: zccmd_scroll,
        minargs: 2,
        maxargs: 2,
    },
    zcurses_subcommand {
        name: "input",
        cmd: zccmd_input,
        minargs: 1,
        maxargs: 4,
    },
    zcurses_subcommand {
        name: "timeout",
        cmd: zccmd_timeout,
        minargs: 2,
        maxargs: 2,
    },
    zcurses_subcommand {
        name: "mouse",
        cmd: zccmd_mouse,
        minargs: 0,
        maxargs: -1,
    },
    zcurses_subcommand {
        name: "querychar",
        cmd: zccmd_querychar,
        minargs: 1,
        maxargs: 2,
    },
    zcurses_subcommand {
        name: "touch",
        cmd: zccmd_touch,
        minargs: 1,
        maxargs: -1,
    },
    zcurses_subcommand {
        name: "resize",
        cmd: zccmd_resize,
        minargs: 2,
        maxargs: 3,
    },
];

/// libncurses keypad code constants. Subset of the
/// autogenerated `curses_keys.h` table the C source includes.
pub const KEY_DOWN: i32 = 0o402;
/// `KEY_UP` constant.
pub const KEY_UP: i32 = 0o403;
/// `KEY_LEFT` constant.
pub const KEY_LEFT: i32 = 0o404;
/// `KEY_RIGHT` constant.
pub const KEY_RIGHT: i32 = 0o405;
/// `KEY_HOME` constant.
pub const KEY_HOME: i32 = 0o406;
/// `KEY_DC` constant.
pub const KEY_DC: i32 = 0o512;
/// `KEY_IC` constant.
pub const KEY_IC: i32 = 0o513;
/// `KEY_NPAGE` constant.
pub const KEY_NPAGE: i32 = 0o522;
/// `KEY_PPAGE` constant.
pub const KEY_PPAGE: i32 = 0o523;
/// `KEY_END` constant.
pub const KEY_END: i32 = 0o550;
/// `KEY_F0` constant.
pub const KEY_F0: i32 = 0o410;

// =====================================================================
// Module paraphernalia (curses.c:1631-).
// =====================================================================

// Port of `static struct builtin bintab[]` from `curses.c:1631`:
//   BUILTIN("zcurses", 0, bin_zcurses, 1, -1, 0, "", NULL)
// The Rust port keeps the descriptor inline in the local
// `featuresarray` stub below — the static-link path doesn't
// need a `static [builtin]` array since `bin_zcurses` is
// invoked through the canonical builtin dispatcher, not the
// per-module bintab pointer C uses for dlopen.

/// Port of `static struct features module_features` from
/// `Src/Modules/curses.c:1638`. C builds it as a stack literal;
/// Rust port keeps the OnceLock<Mutex> shape so callers consume
/// the same `*const module, &Mutex<crate::ported::zsh_h::features>` handle other
/// modules use.
static MODULE_FEATURES: OnceLock<Mutex<features>> = OnceLock::new();

// WARNING: NOT IN CURSES.C — Rust-only OnceLock get-or-init for
// each module static. C dereferences globals directly.
fn windows_lock() -> &'static Mutex<HashMap<String, zc_win>> {
    zcurses_windows.get_or_init(|| Mutex::new(HashMap::new()))
}

// WARNING: NOT IN CURSES.C — see windows_lock above.
fn errno_lock() -> &'static Mutex<i32> {
    zc_errno_cell.get_or_init(|| Mutex::new(0))
}

// WARNING: NOT IN CURSES.C — see windows_lock above.
fn colorpairs_lock() -> &'static Mutex<HashMap<String, i16>> {
    zcurses_colorpairs.get_or_init(|| Mutex::new(HashMap::new()))
}

// WARNING: NOT IN CURSES.C — see windows_lock above.
fn next_cp_lock() -> &'static Mutex<i16> {
    next_cp.get_or_init(|| Mutex::new(0))
}

/// WARNING: NOT IN CURSES.C — Mutex-based errno accessor; C reads `zc_errno` directly
/// (equivalent C logic at Src/Modules/curses.c:107).
/// Read the current `zc_errno` value. C dereferences the global
/// directly; Rust port wraps the lock acquire.
fn zc_errno_get() -> i32 {
    *errno_lock().lock().unwrap()
}

/// WARNING: NOT IN CURSES.C — Mutex-based errno setter; C writes `zc_errno` directly
/// (equivalent C logic at Src/Modules/curses.c:107).
/// Set `zc_errno`. Used by `zcurses_validate_window`.
fn zc_errno_set(v: i32) {
    *errno_lock().lock().unwrap() = v;
}

// WARNING: NOT IN CURSES.C — OnceLock get-or-init for `zcurses_flags`
// and `zcurses_mouse_mask` (C dereferences globals directly).
fn flags_lock() -> &'static Mutex<u32> {
    zcurses_flags.get_or_init(|| Mutex::new(0))
}

#[link(name = "ncurses")]
extern "C" {
    #[link_name = "tigetnum"]
    fn libc_tigetnum(name: *const libc::c_char) -> libc::c_int;
}
// WARNING: NOT IN CURSES.C — see flags_lock above.
/// Port of `zccmd_input(const char *nam, char **args)` from `Src/Modules/curses.c:1029`.
fn mouse_mask_lock() -> &'static Mutex<u32> {
    // ALL_MOUSE_EVENTS in ncurses ≈ 0x07ffffff for the standard
    // event set. Default to that until a `mouse delay`/`mouse motion`
    // command flips it.
    zcurses_mouse_mask.get_or_init(|| Mutex::new(0x07ffffff))
}

// =====================================================================
// Port of `zcurses_colorget(const char *nam, char *colorpair)` from `Src/Modules/curses.c:331`.
// =====================================================================

/// Port of `zcurses_colorget(const char *nam, char *colorpair)` from `Src/Modules/curses.c:331`.
///
/// Resolve `"fg/bg"` to a color-pair index, allocating a new pair
/// via `init_pair()` semantics (incrementing `next_cp`) on first
/// use. C uses libncurses's `init_pair`; Rust port stores the
/// mapping in the `zcurses_colorpairs` HashMap for later SGR.
pub(crate) fn colorpair_get_or_alloc(spec: &str) -> i32 {
    let mut pairs = colorpairs_lock().lock().unwrap();
    if let Some(&n) = pairs.get(spec) {
        return n as i32;
    }
    let slash = match spec.find('/') {
        Some(p) => p,
        None => return -1,
    };
    let fg = &spec[..slash];
    let bg = &spec[slash + 1..];
    let _fg_n = zcurses_color(fg);
    let _bg_n = zcurses_color(bg);
    if _fg_n == -2 || _bg_n == -2 {
        return -1;
    }
    let mut np = next_cp_lock().lock().unwrap();
    *np = np.saturating_add(1);
    let cp = *np;
    pairs.insert(spec.to_string(), cp);
    cp as i32
}

// =====================================================================
// Keypad / keyboard input helpers — substitutes for libncurses's
// `wgetch` / `wget_wch` + `keypad()` table from `curses_keys.h`.
// =====================================================================

// WARNING: NOT IN CURSES.C — Rust-only termios+read shim. C uses
// libncurses's `wget_wch(w->win, &wi)` / `wgetch(w->win, ...)`.
// Without libncurses linked, the Rust port reads raw bytes from
// stdin (cbreak set by `zccmd_init`) and parses CSI / SS3 sequences
// for arrow + function-key codes, plus xterm SGR-1006 / legacy X10
// mouse reports (decoded into a `KEY_MOUSE` code + pending `Mevent`
// when ZCF_MOUSE_ACTIVE is armed). Returns `(string, keycode)`.
// `keycode == 0` means a regular character; non-zero means a
// keypad code.
/// WARNING: NOT IN CURSES.C — Rust-side TTY key-sequence reader; C uses `wgetch()` from libncurses
/// (equivalent C logic at Src/Modules/curses.c:1473).
fn read_key_sequence(want_keypad: bool, _timeout_ms: i32) -> Option<(String, i32)> {
    #[cfg(unix)]
    {
        let mut buf = [0u8; 1];
        let n = io::stdin().read(&mut buf).ok()?;
        if n == 0 {
            return None;
        }
        let c = buf[0];
        if c == 0x1b && want_keypad {
            // ESC introduces a CSI / SS3 / mouse sequence. Read the
            // introducer byte, then dispatch.
            let mut seq = vec![c];
            let mut nb = [0u8; 1];
            if io::stdin().read(&mut nb).ok()? == 0 {
                return Some(((c as char).to_string(), 0));
            }
            seq.push(nb[0]);
            // c:1108-1131 mousemask gate: only decode mouse reports when
            // `zcurses input` armed mouse mode (ZCF_MOUSE_ACTIVE).
            let mouse_active = *flags_lock().lock().unwrap() & ZCF_MOUSE_ACTIVE != 0;
            if seq[1] == b'[' {
                if io::stdin().read(&mut nb).ok()? == 0 {
                    return Some(((c as char).to_string(), 0));
                }
                seq.push(nb[0]);
                if mouse_active && seq[2] == b'<' {
                    // xterm SGR-1006 mouse: ESC [ < b ; x ; y (M|m).
                    // The read_key_sequence half of the KEY_MOUSE decode
                    // (c:1162-1216): synthesize KEY_MOUSE + pending Mevent.
                    let mut params: Vec<u8> = Vec::new();
                    let mut final_ch = 0u8;
                    for _ in 0..32 {
                        if io::stdin().read(&mut nb).ok()? == 0 {
                            break;
                        }
                        if nb[0] == b'M' || nb[0] == b'm' {
                            final_ch = nb[0];
                            break;
                        }
                        params.push(nb[0]);
                    }
                    let text = String::from_utf8_lossy(&params);
                    let mut fields = text.split(';');
                    let b: i64 = fields.next().and_then(|v| v.parse().ok()).unwrap_or(-1);
                    let sx: i64 = fields.next().and_then(|v| v.parse().ok()).unwrap_or(0);
                    let sy: i64 = fields.next().and_then(|v| v.parse().ok()).unwrap_or(0);
                    if b >= 0 && (final_ch == b'M' || final_ch == b'm') {
                        // xterm button field: low 2 bits = button, +4 shift,
                        // +8 alt/meta, +16 ctrl, +32 motion, +64 wheel.
                        // Final 'M' = press, 'm' = release.
                        let released = final_ch == b'm';
                        let low = (b & 3) as i32;
                        let wheel = b & 64 != 0;
                        let motion = b & 32 != 0;
                        let button = if wheel {
                            4 + low
                        } else if low == 3 {
                            0 // motion with no button held
                        } else {
                            low + 1
                        };
                        let mut bstate: u64 = 0;
                        if button >= 1 && button <= 5 {
                            // NCURSES_MOUSE_MASK(button, base) = base << ((button-1)*5)
                            let base: u64 = if released { 0o1 } else { 0o2 };
                            bstate |= base << (((button - 1) * 5) as u64);
                        }
                        if motion {
                            bstate |= REPORT_MOUSE_POSITION as u64;
                        }
                        if b & 4 != 0 {
                            bstate |= BUTTON_SHIFT;
                        }
                        if b & 8 != 0 {
                            bstate |= BUTTON_ALT;
                        }
                        if b & 16 != 0 {
                            bstate |= BUTTON_CTRL;
                        }
                        // ncurses getmouse() reports 0-based coords.
                        *PENDING_MOUSE.lock().unwrap() = Some(Mevent {
                            id: 0,
                            x: (sx - 1) as i32,
                            y: (sy - 1) as i32,
                            z: 0,
                            bstate,
                        });
                        return Some((String::new(), KEY_MOUSE));
                    }
                    return Some(((c as char).to_string(), 0));
                } else if mouse_active && seq[2] == b'M' {
                    // Legacy X10 mouse: ESC [ M cb cx cy (three bytes,
                    // each offset by +32).
                    let mut raw = [0u8; 3];
                    let mut got = 0usize;
                    while got < 3 {
                        if io::stdin().read(&mut nb).ok()? == 0 {
                            break;
                        }
                        raw[got] = nb[0];
                        got += 1;
                    }
                    if got == 3 {
                        let b = raw[0] as i64 - 32;
                        let sx = raw[1] as i64 - 32;
                        let sy = raw[2] as i64 - 32;
                        let low = (b & 3) as i32;
                        let wheel = b & 64 != 0;
                        let (button, released) = if wheel {
                            (4 + low, false)
                        } else if low == 3 {
                            (1, true) // X10 release: button not reported
                        } else {
                            (low + 1, false)
                        };
                        let mut bstate: u64 = 0;
                        if button >= 1 && button <= 5 {
                            let base: u64 = if released { 0o1 } else { 0o2 };
                            bstate |= base << (((button - 1) * 5) as u64);
                        }
                        if b & 4 != 0 {
                            bstate |= BUTTON_SHIFT;
                        }
                        if b & 8 != 0 {
                            bstate |= BUTTON_ALT;
                        }
                        if b & 16 != 0 {
                            bstate |= BUTTON_CTRL;
                        }
                        *PENDING_MOUSE.lock().unwrap() = Some(Mevent {
                            id: 0,
                            x: (sx - 1) as i32,
                            y: (sy - 1) as i32,
                            z: 0,
                            bstate,
                        });
                        return Some((String::new(), KEY_MOUSE));
                    }
                    return Some(((c as char).to_string(), 0));
                } else {
                    // Ordinary CSI: read remaining bytes up to a final
                    // byte in 0x40..=0x7e, then map via csi_to_keypad.
                    if !(seq[2] >= 0x40 && seq[2] <= 0x7e) {
                        for _ in 0..6 {
                            if io::stdin().read(&mut nb).ok()? == 0 {
                                break;
                            }
                            seq.push(nb[0]);
                            if nb[0] >= 0x40 && nb[0] <= 0x7e {
                                break;
                            }
                        }
                    }
                    if let Some(code) = csi_to_keypad(&seq) {
                        return Some((String::new(), code));
                    }
                }
            } else if seq[1] == b'O' {
                // SS3: ESC O <final> (arrows / F1-F4).
                if io::stdin().read(&mut nb).ok()? == 0 {
                    return Some(((c as char).to_string(), 0));
                }
                seq.push(nb[0]);
                if let Some(code) = csi_to_keypad(&seq) {
                    return Some((String::new(), code));
                }
            }
            return Some(((c as char).to_string(), 0));
        }
        Some(((c as char).to_string(), 0))
    }
    #[cfg(not(unix))]
    {
        let _ = (want_keypad, _timeout_ms);
        None
    }
}

// WARNING: NOT IN CURSES.C — table-driven CSI/SS3 → libncurses
// keypad-code mapping. Substitutes for the `curses_keys.h`
// autogenerated table that ncurses' `keypad()` uses internally.
// Values match libncurses constants (KEY_UP = 0o403, etc.).
fn csi_to_keypad(seq: &[u8]) -> Option<i32> {
    if seq.len() < 3 || seq[0] != 0x1b {
        return None;
    }
    if seq[1] == b'[' {
        match seq[2] {
            b'A' => Some(KEY_UP),
            b'B' => Some(KEY_DOWN),
            b'C' => Some(KEY_RIGHT),
            b'D' => Some(KEY_LEFT),
            b'H' => Some(KEY_HOME),
            b'F' => Some(KEY_END),
            b'1' if seq.len() >= 4 && seq[3] == b'~' => Some(KEY_HOME),
            b'2' if seq.len() >= 4 && seq[3] == b'~' => Some(KEY_IC),
            b'3' if seq.len() >= 4 && seq[3] == b'~' => Some(KEY_DC),
            b'4' if seq.len() >= 4 && seq[3] == b'~' => Some(KEY_END),
            b'5' if seq.len() >= 4 && seq[3] == b'~' => Some(KEY_PPAGE),
            b'6' if seq.len() >= 4 && seq[3] == b'~' => Some(KEY_NPAGE),
            _ => None,
        }
    } else if seq[1] == b'O' {
        match seq[2] {
            b'A' => Some(KEY_UP),
            b'B' => Some(KEY_DOWN),
            b'C' => Some(KEY_RIGHT),
            b'D' => Some(KEY_LEFT),
            b'P' => Some(KEY_F0 + 1),
            b'Q' => Some(KEY_F0 + 2),
            b'R' => Some(KEY_F0 + 3),
            b'S' => Some(KEY_F0 + 4),
            _ => None,
        }
    } else {
        None
    }
}

// WARNING: NOT IN CURSES.C — Rust-only reverse lookup of the
// keypad-code → name table. C uses `keypad_names[]` from
// `curses_keys.h`; Rust port hardcodes the most common keys to
// keep the table compact.
fn keypad_name(code: i32) -> Option<String> {
    // Direct value-to-name table mirroring what C's awk-generated
    // keypad_names[] in curses_keys.h carries — every KEY_* define
    // from the system curses.h except MIN, MAX, CODE_YES (per the
    // awk filter at curses_keys.awk:8). Values match the canonical
    // ncurses octal-coded ranges:
    //   0o401-0o407: base set (BREAK..BACKSPACE)
    //   0o410-0o467: F-keys (F0..F63, handled inline below)
    //   0o510+:      extended set (DL..MOUSE)
    // Octal literals match the curses.h #defines exactly so a side-
    // by-side review against the original macros stays trivially
    // verifiable.
    let name = match code {
        // c:base set
        0o401 => "BREAK",
        KEY_DOWN => "DOWN",   // 0o402
        KEY_UP => "UP",       // 0o403
        KEY_LEFT => "LEFT",   // 0o404
        KEY_RIGHT => "RIGHT", // 0o405
        KEY_HOME => "HOME",   // 0o406
        0o407 => "BACKSPACE",
        // c:extended set
        0o510 => "DL",
        0o511 => "IL",
        KEY_DC => "DC", // 0o512
        KEY_IC => "IC", // 0o513
        0o514 => "EIC",
        0o515 => "CLEAR",
        0o516 => "EOS",
        0o517 => "EOL",
        0o520 => "SF",
        0o521 => "SR",
        KEY_NPAGE => "NPAGE", // 0o522
        KEY_PPAGE => "PPAGE", // 0o523
        0o524 => "STAB",
        0o525 => "CTAB",
        0o526 => "CATAB",
        0o527 => "ENTER",
        0o530 => "SRESET",
        0o531 => "RESET",
        0o532 => "PRINT",
        0o533 => "LL",
        0o534 => "A1",
        0o535 => "A3",
        0o536 => "B2",
        0o537 => "C1",
        0o540 => "C3",
        0o541 => "BTAB",
        0o542 => "BEG",
        0o543 => "CANCEL",
        0o544 => "CLOSE",
        0o545 => "COMMAND",
        0o546 => "COPY",
        0o547 => "CREATE",
        KEY_END => "END", // 0o550
        0o551 => "EXIT",
        0o552 => "FIND",
        0o553 => "HELP",
        0o554 => "MARK",
        0o555 => "MESSAGE",
        0o556 => "MOVE",
        0o557 => "NEXT",
        0o560 => "OPEN",
        0o561 => "OPTIONS",
        0o562 => "PREVIOUS",
        0o563 => "REDO",
        0o564 => "REFERENCE",
        0o565 => "REFRESH",
        0o566 => "REPLACE",
        0o567 => "RESTART",
        0o570 => "RESUME",
        0o571 => "SAVE",
        0o572 => "SBEG",
        0o573 => "SCANCEL",
        0o574 => "SCOMMAND",
        0o575 => "SCOPY",
        0o576 => "SCREATE",
        0o577 => "SDC",
        0o600 => "SDL",
        0o601 => "SELECT",
        0o602 => "SEND",
        0o603 => "SEOL",
        0o604 => "SEXIT",
        0o605 => "SFIND",
        0o606 => "SHELP",
        0o607 => "SHOME",
        0o610 => "SIC",
        0o611 => "SLEFT",
        0o612 => "SMESSAGE",
        0o613 => "SMOVE",
        0o614 => "SNEXT",
        0o615 => "SOPTIONS",
        0o616 => "SPREVIOUS",
        0o617 => "SPRINT",
        0o620 => "SREDO",
        0o621 => "SREPLACE",
        0o622 => "SRIGHT",
        0o623 => "SRSUME",
        0o624 => "SSAVE",
        0o625 => "SSUSPEND",
        0o626 => "SUNDO",
        0o627 => "SUSPEND",
        0o630 => "UNDO",
        0o631 => "MOUSE",
        0o632 => "RESIZE",
        0o633 => "EVENT", // KEY_EVENT — may not be defined on all platforms
        // F-keys: F0..F63 at KEY_F0 + n.
        c if c >= KEY_F0 && c < KEY_F0 + 64 => {
            return Some(format!("F{}", c - KEY_F0));
        }
        _ => return None,
    };
    Some(name.to_string())
}

// Local stubs mirroring the C `featuresarray` / `handlefeatures` /
// `setfeatureenables` signatures (Src/module.c:3388/3370/3445). The
// canonical free ported operate on `Module *` and `Features *`; the
// Rust port collapses the bintab into one constant since curses
// ships exactly one builtin (`zcurses`).
// WARNING: NOT IN CURSES.C — Rust-only module-framework shim.
// C uses generic featuresarray/handlefeatures/setfeatureenables from
// Src/module.c:3275/3370/3445 with C-side Builtin/Features pointers;
// Rust per-module shims hardcode the bintab/conddefs/mathfuncs/paramdefs.
fn featuresarray(_m: *const module, _f: &Mutex<features>) -> Vec<String> {
    vec!["b:zcurses".to_string()]
}

// WARNING: NOT IN CURSES.C — Rust-only module-framework shim.
// C uses generic featuresarray/handlefeatures/setfeatureenables from
// Src/module.c:3275/3370/3445 with C-side Builtin/Features pointers;
// Rust per-module shims hardcode the bintab/conddefs/mathfuncs/paramdefs.
fn handlefeatures(_m: *const module, _f: &Mutex<features>, enables: &mut Option<Vec<i32>>) -> i32 {
    if enables.is_none() {
        *enables = Some(vec![1]);
    }
    0
}

// WARNING: NOT IN CURSES.C — Rust-only module-framework shim.
// C uses generic featuresarray/handlefeatures/setfeatureenables from
// Src/module.c:3275/3370/3445 with C-side Builtin/Features pointers;
// Rust per-module shims hardcode the bintab/conddefs/mathfuncs/paramdefs.
fn setfeatureenables(_m: *const module, _f: &Mutex<features>, _e: Option<&[i32]>) -> i32 {
    0
}

// =====================================================================
// Rust-only helpers (libncurses substitutes).
// =====================================================================

// WARNING: NOT IN CURSES.C — Rust-only TIOCGWINSZ probe. C uses
// libncurses's `LINES` / `COLS` globals which `initscr()` populates
// from terminfo; Rust port queries the kernel directly because
// libncurses isn't linked.
fn terminal_size() -> Option<(usize, usize)> {
    #[cfg(unix)]
    {
        let mut ws: libc::winsize = unsafe { std::mem::zeroed() };
        let result = unsafe { libc::ioctl(libc::STDOUT_FILENO, libc::TIOCGWINSZ, &mut ws) };
        if result == 0 && ws.ws_row > 0 && ws.ws_col > 0 {
            return Some((ws.ws_row as usize, ws.ws_col as usize));
        }
    }
    // C falls back to `getiparam("LINES")` / `getiparam("COLUMNS")`
    // when TIOCGWINSZ fails. Read paramtab; convert i64→usize.
    let lines = getiparam("LINES");
    let cols = getiparam("COLUMNS");
    if lines > 0 && cols > 0 {
        Some((lines as usize, cols as usize))
    } else {
        None
    }
}

// WARNING: NOT IN CURSES.C — termios shim replacing libncurses's
// `cbreak()` call inside `zccmd_init` (curses.c:492).
#[cfg(unix)]
fn cbreak() -> io::Result<()> {
    let mut termios: libc::termios = unsafe { std::mem::zeroed() };
    unsafe {
        if libc::tcgetattr(libc::STDIN_FILENO, &mut termios) < 0 {
            return Err(io::Error::last_os_error());
        }
        termios.c_lflag &= !(libc::ICANON | libc::ECHO);
        termios.c_cc[libc::VMIN] = 1;
        termios.c_cc[libc::VTIME] = 0;
        if libc::tcsetattr(libc::STDIN_FILENO, libc::TCSANOW, &termios) < 0 {
            return Err(io::Error::last_os_error());
        }
    }
    Ok(())
}

/// WARNING: NOT IN CURSES.C — Rust-side terminal mode helper; C calls libncurses `cbreak()` directly
/// (equivalent C logic at Src/Modules/curses.c:1920).
#[cfg(not(unix))]
fn cbreak() -> io::Result<()> {
    Ok(())
}

// WARNING: NOT IN CURSES.C — Rust-only ANSI SGR encoder. C calls
// libncurses's `wattrset(win, attrs)` which the terminal handles;
// Rust port emits the matching SGR sequences since libncurses
// isn't linked.
fn sgr_for_attrs(attrs: u32) -> String {
    let mut s = "\x1b[0".to_string();
    if attrs & A_BOLD as u32 != 0 {
        s.push_str(";1");
    }
    if attrs & A_DIM as u32 != 0 {
        s.push_str(";2");
    }
    if attrs & A_UNDERLINE as u32 != 0 {
        s.push_str(";4");
    }
    if attrs & A_BLINK as u32 != 0 {
        s.push_str(";5");
    }
    if attrs & A_REVERSE as u32 != 0 || attrs & A_STANDOUT as u32 != 0 {
        s.push_str(";7");
    }
    s.push('m');
    s
}

// =====================================================================
// Tests
// =====================================================================

// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
// ─── 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.
// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

// WARNING: NOT IN CURSES.C — see windows_lock above.
fn order_lock() -> &'static Mutex<Vec<String>> {
    WINDOW_ORDER.get_or_init(|| Mutex::new(Vec::new()))
}

// WARNING: NOT IN CURSES.C — Rust-only module-framework shim.
// C uses generic featuresarray/handlefeatures/setfeatureenables from
// Src/module.c:3275/3370/3445 with C-side Builtin/Features pointers;
// Rust per-module shims hardcode the bintab/conddefs/mathfuncs/paramdefs.
fn module_features() -> &'static Mutex<features> {
    MODULE_FEATURES.get_or_init(|| {
        Mutex::new(features {
            bn_list: None, // c:1639 bintab
            bn_size: 1,    // c:1639 sizeof(bintab)/sizeof(*bintab)
            cd_list: None, // c:1640
            cd_size: 0,
            mf_list: None, // c:1641
            mf_size: 0,
            pd_list: None, // c:1642
            pd_size: 0,
            n_abstract: 0, // c:1643
        })
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::ported::zsh_h::MAX_OPS;

    static TEST_SERIAL: std::sync::Mutex<()> = std::sync::Mutex::new(());

    /// Empty Options struct for test invocations of bin_zcurses (whose
    /// canonical sig per Src/Modules/curses.c:1568 takes Options).
    /// All zccmd_* subcommands parse their own opts inline, so the
    /// dispatcher passes through a no-op ops bag.
    #[allow(non_upper_case_globals)]
    const _test_ops_: options = options {
        ind: [0u8; MAX_OPS],
        args: Vec::new(),
        argscount: 0,
        argsalloc: 0,
    };

    fn reset() -> std::sync::MutexGuard<'static, ()> {
        let guard = TEST_SERIAL.lock().unwrap_or_else(|e| {
            TEST_SERIAL.clear_poison();
            e.into_inner()
        });
        windows_lock()
            .lock()
            .unwrap_or_else(|e| {
                windows_lock().clear_poison();
                e.into_inner()
            })
            .clear();
        order_lock()
            .lock()
            .unwrap_or_else(|e| {
                order_lock().clear_poison();
                e.into_inner()
            })
            .clear();
        colorpairs_lock()
            .lock()
            .unwrap_or_else(|e| {
                colorpairs_lock().clear_poison();
                e.into_inner()
            })
            .clear();
        zc_errno_set(0);
        guard
    }

    /// Port of `zcurses_strerror(int err)` from `Src/Modules/curses.c:233`.
    #[test]
    fn test_zcurses_strerror_table() {
        let _g = crate::test_util::global_state_lock();
        assert_eq!(zcurses_strerror(0), "unknown error");
        assert_eq!(zcurses_strerror(1), "window name invalid");
        assert_eq!(zcurses_strerror(2), "window already defined");
        assert_eq!(zcurses_strerror(3), "window undefined");
        assert_eq!(zcurses_strerror(99), "unknown error");
    }

    #[test]
    fn test_zcurses_color_lookup() {
        let _g = crate::test_util::global_state_lock();
        assert_eq!(zcurses_color("red"), COLOR_RED);
        assert_eq!(zcurses_color("default"), -1);
        assert_eq!(zcurses_color("magenta"), COLOR_MAGENTA);
        assert_eq!(zcurses_color("unknown"), -2);
    }

    #[test]
    fn test_zcurses_validate_window_invalid_name() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        assert!(!zcurses_validate_window("", ZCURSES_UNUSED));
        assert_eq!(zc_errno_get(), ZCURSES_EINVALID);
    }

    #[test]
    fn test_zcurses_validate_window_unused_when_already_defined() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        windows_lock()
            .lock()
            .unwrap()
            .insert("win1".into(), zc_win::new("win1", 5, 10, 0, 0));
        assert!(!zcurses_validate_window("win1", ZCURSES_UNUSED));
        assert_eq!(zc_errno_get(), ZCURSES_EDEFINED);
    }

    #[test]
    fn test_zcurses_validate_window_used_when_undefined() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        assert!(!zcurses_validate_window("nope", ZCURSES_USED));
        assert_eq!(zc_errno_get(), ZCURSES_EUNDEFINED);
    }

    /// Port of `zccmd_delwin(const char *nam, char **args)` from `Src/Modules/curses.c:564`.
    #[test]
    fn test_zcurses_validate_window_success_used() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        windows_lock()
            .lock()
            .unwrap()
            .insert("stdscr".into(), zc_win::new("stdscr", 24, 80, 0, 0));
        assert!(zcurses_validate_window("stdscr", ZCURSES_USED));
        assert_eq!(zc_errno_get(), 0);
    }

    #[test]
    fn test_zcurses_attrget_lookup() {
        let _g = crate::test_util::global_state_lock();
        let w = zc_win::new("test", 5, 10, 0, 0);
        let bold = zcurses_attrget(&w, "bold").expect("bold should resolve");
        assert_eq!(bold.number, A_BOLD);
        assert!(zcurses_attrget(&w, "unknown_attr").is_none());
    }

    #[test]
    fn test_features_returns_bintab_names() {
        let _g = crate::test_util::global_state_lock();
        let mut features: Vec<String> = Vec::new();
        let rc = features_(std::ptr::null(), &mut features);
        assert_eq!(rc, 0);
        assert_eq!(features, vec!["b:zcurses"]);
    }

    #[test]
    fn test_cleanup_returns_zero() {
        let _g = crate::test_util::global_state_lock();
        assert_eq!(cleanup_(std::ptr::null()), 0);
    }

    /// Port of `bin_zcurses(char *nam, char **args, UNUSED(Options ops), UNUSED(int func))` from `Src/Modules/curses.c:1568`.
    #[test]
    fn test_bin_zcurses_init_then_addwin_then_delwin() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        let init_args: Vec<String> = vec!["init".into()];
        assert_eq!(bin_zcurses("zcurses", &init_args, &_test_ops_, 0), 0);
        assert!(zcurses_getwindowbyname("stdscr"));
        let add_args: Vec<String> = vec![
            "addwin".into(),
            "win1".into(),
            "5".into(),
            "10".into(),
            "0".into(),
            "0".into(),
        ];
        assert_eq!(bin_zcurses("zcurses", &add_args, &_test_ops_, 0), 0);
        assert!(zcurses_getwindowbyname("win1"));
        let del_args: Vec<String> = vec!["delwin".into(), "win1".into()];
        assert_eq!(bin_zcurses("zcurses", &del_args, &_test_ops_, 0), 0);
        assert!(!zcurses_getwindowbyname("win1"));
    }

    #[test]
    fn test_bin_zcurses_addwin_before_init_rejected() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        let add_args: Vec<String> = vec![
            "addwin".into(),
            "win1".into(),
            "5".into(),
            "10".into(),
            "0".into(),
            "0".into(),
        ];
        assert_eq!(bin_zcurses("zcurses", &add_args, &_test_ops_, 0), 1);
    }

    #[test]
    fn test_bin_zcurses_addwin_duplicate_rejected() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        bin_zcurses("zcurses", &["init".into()], &_test_ops_, 0);
        let add_args: Vec<String> = vec![
            "addwin".into(),
            "win1".into(),
            "5".into(),
            "10".into(),
            "0".into(),
            "0".into(),
        ];
        assert_eq!(bin_zcurses("zcurses", &add_args, &_test_ops_, 0), 0);
        // Second add of same name fails — zcurses_validate_window
        // sets ZCURSES_EDEFINED.
        assert_eq!(bin_zcurses("zcurses", &add_args, &_test_ops_, 0), 1);
        assert_eq!(zc_errno_get(), ZCURSES_EDEFINED);
    }

    #[test]
    fn test_bin_zcurses_delwin_undefined_rejected() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        bin_zcurses("zcurses", &["init".into()], &_test_ops_, 0);
        let del_args: Vec<String> = vec!["delwin".into(), "ghost".into()];
        assert_eq!(bin_zcurses("zcurses", &del_args, &_test_ops_, 0), 1);
        assert_eq!(zc_errno_get(), ZCURSES_EUNDEFINED);
    }

    /// Port of `bin_zcurses(char *nam, char **args, UNUSED(Options ops), UNUSED(int func))` from `Src/Modules/curses.c:1568`.
    #[test]
    fn test_bin_zcurses_delwin_stdscr_rejected() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        bin_zcurses("zcurses", &["init".into()], &_test_ops_, 0);
        let del_args: Vec<String> = vec!["delwin".into(), "stdscr".into()];
        assert_eq!(bin_zcurses("zcurses", &del_args, &_test_ops_, 0), 1);
    }

    #[test]
    fn test_bin_zcurses_too_few_args() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        bin_zcurses("zcurses", &["init".into()], &_test_ops_, 0);
        // addwin needs 5 args but we only give 2.
        let bad_args: Vec<String> = vec!["addwin".into(), "win1".into()];
        assert_eq!(bin_zcurses("zcurses", &bad_args, &_test_ops_, 0), 1);
    }

    #[test]
    fn test_bin_zcurses_unknown_subcommand() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        assert_eq!(bin_zcurses("zcurses", &["nope".into()], &_test_ops_, 0), 1);
    }

    #[test]
    fn test_bin_zcurses_no_args() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        assert_eq!(bin_zcurses("zcurses", &[], &_test_ops_, 0), 1);
    }

    #[test]
    fn test_zccmd_char_writes_into_buffer() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        bin_zcurses("zcurses", &["init".into()], &_test_ops_, 0);
        let add: Vec<String> = vec![
            "addwin".into(),
            "w".into(),
            "5".into(),
            "10".into(),
            "0".into(),
            "0".into(),
        ];
        bin_zcurses("zcurses", &add, &_test_ops_, 0);
        let ch: Vec<String> = vec!["char".into(), "w".into(), "X".into()];
        assert_eq!(bin_zcurses("zcurses", &ch, &_test_ops_, 0), 0);
        let wins = windows_lock().lock().unwrap();
        assert_eq!(wins.get("w").unwrap().buffer[0][0], 'X');
        assert_eq!(wins.get("w").unwrap().cursor_x, 1);
    }

    /// Port of `bin_zcurses(char *nam, char **args, UNUSED(Options ops), UNUSED(int func))` from `Src/Modules/curses.c:1568`.
    #[test]
    fn test_zccmd_border_draws_box() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        bin_zcurses("zcurses", &["init".into()], &_test_ops_, 0);
        let add: Vec<String> = vec![
            "addwin".into(),
            "box".into(),
            "3".into(),
            "5".into(),
            "0".into(),
            "0".into(),
        ];
        bin_zcurses("zcurses", &add, &_test_ops_, 0);
        assert_eq!(
            bin_zcurses("zcurses", &["border".into(), "box".into()], &_test_ops_, 0),
            0
        );
        let wins = windows_lock().lock().unwrap();
        let b = &wins.get("box").unwrap().buffer;
        assert_eq!(b[0][0], '┌');
        assert_eq!(b[0][4], '┐');
        assert_eq!(b[2][0], '└');
        assert_eq!(b[2][4], '┘');
        assert_eq!(b[1][0], '│');
        assert_eq!(b[0][2], '─');
    }

    /// Port of `zccmd_scroll(const char *nam, char **args)` from `Src/Modules/curses.c:986`.
    #[test]
    fn test_zccmd_scroll_on_off() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        bin_zcurses("zcurses", &["init".into()], &_test_ops_, 0);
        let add: Vec<String> = vec![
            "addwin".into(),
            "sw".into(),
            "5".into(),
            "10".into(),
            "0".into(),
            "0".into(),
        ];
        bin_zcurses("zcurses", &add, &_test_ops_, 0);
        let on: Vec<String> = vec!["scroll".into(), "sw".into(), "on".into()];
        assert_eq!(bin_zcurses("zcurses", &on, &_test_ops_, 0), 0);
        assert_eq!(
            windows_lock().lock().unwrap().get("sw").unwrap().flags & ZCWF_SCROLL,
            ZCWF_SCROLL
        );
        let off: Vec<String> = vec!["scroll".into(), "sw".into(), "off".into()];
        assert_eq!(bin_zcurses("zcurses", &off, &_test_ops_, 0), 0);
        assert_eq!(
            windows_lock().lock().unwrap().get("sw").unwrap().flags & ZCWF_SCROLL,
            0
        );
    }

    /// Port of `zccmd_resize(const char *nam, char **args)` from `Src/Modules/curses.c:1494`.
    #[test]
    fn test_zccmd_scroll_integer_advances_buffer() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        bin_zcurses("zcurses", &["init".into()], &_test_ops_, 0);
        let add: Vec<String> = vec![
            "addwin".into(),
            "sw".into(),
            "3".into(),
            "5".into(),
            "0".into(),
            "0".into(),
        ];
        bin_zcurses("zcurses", &add, &_test_ops_, 0);
        // Pre-fill row 0 with 'A' to detect the shift.
        windows_lock().lock().unwrap().get_mut("sw").unwrap().buffer[0][0] = 'A';
        let scr: Vec<String> = vec!["scroll".into(), "sw".into(), "1".into()];
        assert_eq!(bin_zcurses("zcurses", &scr, &_test_ops_, 0), 0);
        // Row 0 'A' shifted out — bottom row is fresh spaces.
        let wins = windows_lock().lock().unwrap();
        assert_eq!(wins.get("sw").unwrap().buffer[0][0], ' ');
    }

    /// Port of `bin_zcurses(char *nam, char **args, UNUSED(Options ops), UNUSED(int func))` from `Src/Modules/curses.c:1568`.
    #[test]
    fn test_zccmd_timeout_stores_value() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        bin_zcurses("zcurses", &["init".into()], &_test_ops_, 0);
        let add: Vec<String> = vec![
            "addwin".into(),
            "tw".into(),
            "5".into(),
            "10".into(),
            "0".into(),
            "0".into(),
        ];
        bin_zcurses("zcurses", &add, &_test_ops_, 0);
        let to: Vec<String> = vec!["timeout".into(), "tw".into(), "100".into()];
        assert_eq!(bin_zcurses("zcurses", &to, &_test_ops_, 0), 0);
        assert_eq!(
            windows_lock().lock().unwrap().get("tw").unwrap().timeout_ms,
            100
        );
    }

    /// Port of `bin_zcurses(char *nam, char **args, UNUSED(Options ops), UNUSED(int func))` from `Src/Modules/curses.c:1568`.
    #[test]
    fn test_zccmd_touch_validates_each() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        bin_zcurses("zcurses", &["init".into()], &_test_ops_, 0);
        let touch_ok: Vec<String> = vec!["touch".into(), "stdscr".into()];
        assert_eq!(bin_zcurses("zcurses", &touch_ok, &_test_ops_, 0), 0);
        let touch_bad: Vec<String> = vec!["touch".into(), "ghost".into()];
        assert_eq!(bin_zcurses("zcurses", &touch_bad, &_test_ops_, 0), 1);
        assert_eq!(zc_errno_get(), ZCURSES_EUNDEFINED);
    }

    /// Port of `bin_zcurses(char *nam, char **args, UNUSED(Options ops), UNUSED(int func))` from `Src/Modules/curses.c:1568`.
    #[test]
    fn test_zccmd_resize_changes_stdscr() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        bin_zcurses("zcurses", &["init".into()], &_test_ops_, 0);
        let rs: Vec<String> = vec!["resize".into(), "30".into(), "100".into()];
        assert_eq!(bin_zcurses("zcurses", &rs, &_test_ops_, 0), 0);
        let wins = windows_lock().lock().unwrap();
        let stdscr = wins.get("stdscr").unwrap();
        assert_eq!(stdscr.rows, 30);
        assert_eq!(stdscr.cols, 100);
        assert_eq!(stdscr.buffer.len(), 30);
        assert_eq!(stdscr.buffer[0].len(), 100);
    }

    #[test]
    fn test_zccmd_resize_bad_third_arg() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        bin_zcurses("zcurses", &["init".into()], &_test_ops_, 0);
        let rs: Vec<String> = vec!["resize".into(), "30".into(), "100".into(), "junk".into()];
        assert_eq!(bin_zcurses("zcurses", &rs, &_test_ops_, 0), 1);
    }

    /// Port of `zccmd_input(const char *nam, char **args)` from `Src/Modules/curses.c:1029`.
    #[test]
    fn test_zccmd_mouse_motion_toggle() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        bin_zcurses("zcurses", &["init".into()], &_test_ops_, 0);
        // Default mask should not have REPORT_MOUSE_POSITION.
        let mouse_on: Vec<String> = vec!["mouse".into(), "+motion".into()];
        assert_eq!(bin_zcurses("zcurses", &mouse_on, &_test_ops_, 0), 0);
        assert_ne!(
            *mouse_mask_lock().lock().unwrap() & REPORT_MOUSE_POSITION,
            0
        );
        let mouse_off: Vec<String> = vec!["mouse".into(), "-motion".into()];
        assert_eq!(bin_zcurses("zcurses", &mouse_off, &_test_ops_, 0), 0);
        assert_eq!(
            *mouse_mask_lock().lock().unwrap() & REPORT_MOUSE_POSITION,
            0
        );
    }

    #[test]
    fn test_zccmd_bg_with_color_pair() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        bin_zcurses("zcurses", &["init".into()], &_test_ops_, 0);
        let add: Vec<String> = vec![
            "addwin".into(),
            "bgw".into(),
            "5".into(),
            "10".into(),
            "0".into(),
            "0".into(),
        ];
        bin_zcurses("zcurses", &add, &_test_ops_, 0);
        let bg: Vec<String> = vec!["bg".into(), "bgw".into(), "red/black".into()];
        assert_eq!(bin_zcurses("zcurses", &bg, &_test_ops_, 0), 0);
        // Pair was allocated; bg_chtype encodes the pair in the high bits.
        assert_ne!(
            windows_lock().lock().unwrap().get("bgw").unwrap().bg_chtype,
            0
        );
    }

    /// Port of `zccmd_delwin(const char *nam, char **args)` from `Src/Modules/curses.c:564`.
    #[test]
    fn test_addwin_with_parent() {
        let _g = crate::test_util::global_state_lock();
        let _g = reset();
        bin_zcurses("zcurses", &["init".into()], &_test_ops_, 0);
        let parent_args: Vec<String> = vec![
            "addwin".into(),
            "parent".into(),
            "10".into(),
            "20".into(),
            "0".into(),
            "0".into(),
        ];
        assert_eq!(bin_zcurses("zcurses", &parent_args, &_test_ops_, 0), 0);
        let child_args: Vec<String> = vec![
            "addwin".into(),
            "child".into(),
            "5".into(),
            "10".into(),
            "1".into(),
            "1".into(),
            "parent".into(),
        ];
        assert_eq!(bin_zcurses("zcurses", &child_args, &_test_ops_, 0), 0);
        let wins = windows_lock().lock().unwrap();
        assert_eq!(wins.get("child").unwrap().parent.as_deref(), Some("parent"));
        assert_eq!(
            wins.get("parent").unwrap().children,
            vec!["child".to_string()]
        );
    }

    // ─── zsh-corpus pins for zcurses_strerror ──────────────────────

    /// `zcurses_strerror(0)` returns "unknown error" (out-of-range maps to idx 0).
    #[test]
    fn curses_corpus_strerror_zero_unknown() {
        let _g = crate::test_util::global_state_lock();
        assert_eq!(zcurses_strerror(0), "unknown error");
    }

    /// `zcurses_strerror(1)` returns "window name invalid".
    #[test]
    fn curses_corpus_strerror_one_invalid_name() {
        let _g = crate::test_util::global_state_lock();
        assert_eq!(zcurses_strerror(1), "window name invalid");
    }

    /// `zcurses_strerror(2)` returns "window already defined".
    #[test]
    fn curses_corpus_strerror_two_already_defined() {
        let _g = crate::test_util::global_state_lock();
        assert_eq!(zcurses_strerror(2), "window already defined");
    }

    /// `zcurses_strerror(3)` returns "window undefined".
    #[test]
    fn curses_corpus_strerror_three_undefined() {
        let _g = crate::test_util::global_state_lock();
        assert_eq!(zcurses_strerror(3), "window undefined");
    }

    /// `zcurses_strerror(99)` clamps to "unknown error" (out of range).
    #[test]
    fn curses_corpus_strerror_out_of_range_clamps_to_unknown() {
        let _g = crate::test_util::global_state_lock();
        assert_eq!(zcurses_strerror(99), "unknown error");
        assert_eq!(zcurses_strerror(-1), "unknown error");
        assert_eq!(zcurses_strerror(i32::MAX), "unknown error");
    }

    /// `zcurses_pairs_to_array` returns names from a zcurses_namenumberpair slice.
    #[test]
    fn curses_corpus_pairs_to_array_extracts_names() {
        let pairs = [
            zcurses_namenumberpair {
                name: "alpha",
                number: 1,
            },
            zcurses_namenumberpair {
                name: "beta",
                number: 2,
            },
            zcurses_namenumberpair {
                name: "gamma",
                number: 3,
            },
        ];
        let v = zcurses_pairs_to_array(&pairs);
        assert_eq!(v, vec!["alpha", "beta", "gamma"]);
    }

    /// `zcurses_pairs_to_array` on empty input returns empty Vec.
    #[test]
    fn curses_corpus_pairs_to_array_empty_input() {
        let v = zcurses_pairs_to_array(&[]);
        assert!(v.is_empty());
    }

    // ═══════════════════════════════════════════════════════════════════
    // Additional C-parity tests for Src/Modules/curses.c.
    // ═══════════════════════════════════════════════════════════════════

    /// c:233 — `zcurses_strerror(0)` returns 'unknown error'.
    #[test]
    fn zcurses_strerror_zero_returns_unknown() {
        assert_eq!(zcurses_strerror(0), "unknown error");
    }

    /// c:233 — `zcurses_strerror(1)` returns 'window name invalid'.
    #[test]
    fn zcurses_strerror_one_returns_name_invalid() {
        assert_eq!(zcurses_strerror(1), "window name invalid");
    }

    /// c:233 — `zcurses_strerror(2)` returns 'window already defined'.
    #[test]
    fn zcurses_strerror_two_returns_already_defined() {
        assert_eq!(zcurses_strerror(2), "window already defined");
    }

    /// c:233 — `zcurses_strerror(3)` returns 'window undefined'.
    #[test]
    fn zcurses_strerror_three_returns_undefined() {
        assert_eq!(zcurses_strerror(3), "window undefined");
    }

    /// c:233 — `zcurses_strerror` out-of-range returns 'unknown error'.
    #[test]
    fn zcurses_strerror_out_of_range_returns_unknown() {
        assert_eq!(zcurses_strerror(-1), "unknown error");
        assert_eq!(zcurses_strerror(4), "unknown error");
        assert_eq!(zcurses_strerror(999), "unknown error");
    }

    /// c:233 — `zcurses_strerror` is deterministic for known errnos.
    #[test]
    fn zcurses_strerror_is_deterministic() {
        for e in 0..=3 {
            let first = zcurses_strerror(e);
            for _ in 0..5 {
                assert_eq!(zcurses_strerror(e), first);
            }
        }
    }

    /// c:1420 — `zcurses_colorsarrgetfn` returns vec (color names).
    #[test]
    fn zcurses_colorsarrgetfn_returns_vec() {
        let _g = crate::test_util::global_state_lock();
        let v = zcurses_colorsarrgetfn();
        // Either empty (no curses init) or has color names — pin no panic.
        let _ = v;
    }

    /// c:1427 — `zcurses_attrgetfn` returns vec (attribute names).
    #[test]
    fn zcurses_attrgetfn_returns_vec() {
        let _g = crate::test_util::global_state_lock();
        let v = zcurses_attrgetfn();
        let _ = v;
    }

    /// c:1436 — `zcurses_keycodesgetfn` returns vec.
    #[test]
    fn zcurses_keycodesgetfn_returns_vec() {
        let _g = crate::test_util::global_state_lock();
        let v = zcurses_keycodesgetfn();
        let _ = v;
    }

    /// c:1453 — `zcurses_windowsgetfn` returns vec.
    #[test]
    fn zcurses_windowsgetfn_returns_vec() {
        let _g = crate::test_util::global_state_lock();
        let v = zcurses_windowsgetfn();
        let _ = v;
    }

    /// c:1461 — `zcurses_colorsintgetfn` returns non-negative.
    #[test]
    fn zcurses_colorsintgetfn_returns_non_negative() {
        let _g = crate::test_util::global_state_lock();
        let n = zcurses_colorsintgetfn();
        assert!(n >= 0, "color count must be ≥ 0, got {}", n);
    }

    /// c:1475 — `zcurses_colorpairsintgetfn` returns non-negative.
    #[test]
    fn zcurses_colorpairsintgetfn_returns_non_negative() {
        let _g = crate::test_util::global_state_lock();
        let n = zcurses_colorpairsintgetfn();
        assert!(n >= 0, "color pair count must be ≥ 0, got {}", n);
    }

    /// Lifecycle (c:1493/1513/1519/1526) split per-hook.
    #[test]
    fn curses_setup_returns_zero_pin() {
        let _g = crate::test_util::global_state_lock();
        assert_eq!(setup_(std::ptr::null()), 0);
    }

    /// c:1513 — boot_(NULL) = 0.
    #[test]
    fn curses_boot_returns_zero_pin() {
        let _g = crate::test_util::global_state_lock();
        assert_eq!(boot_(std::ptr::null()), 0);
    }

    // ═══════════════════════════════════════════════════════════════════
    // Additional C-parity tests for Src/Modules/curses.c
    // c:293 zcurses_pairs_to_array / c:437 zcurses_colorget /
    // c:525 zcurses_colorget_reverse / c:544 freecolorpairnode /
    // c:1420/1427/1436/1453 *getfn determinism + lifecycle types
    // ═══════════════════════════════════════════════════════════════════

    /// c:293 — `zcurses_pairs_to_array(empty)` returns empty Vec.
    #[test]
    fn zcurses_pairs_to_array_empty_returns_empty() {
        let r = zcurses_pairs_to_array(&[]);
        assert!(r.is_empty(), "empty input → empty Vec");
    }

    /// c:293 — `zcurses_pairs_to_array` returns Vec<String> (type pin).
    #[test]
    fn zcurses_pairs_to_array_returns_vec_string_type() {
        let _: Vec<String> = zcurses_pairs_to_array(&[]);
    }

    /// c:437 — `zcurses_colorget("", "")` returns Option<i16>.
    #[test]
    fn zcurses_colorget_returns_option_i16_type() {
        let _g = crate::test_util::global_state_lock();
        let _: Option<i16> = zcurses_colorget("", "");
    }

    /// c:525 — `zcurses_colorget_reverse(N)` returns Option<String>.
    #[test]
    fn zcurses_colorget_reverse_returns_option_string_type() {
        let _g = crate::test_util::global_state_lock();
        let _: Option<String> = zcurses_colorget_reverse(0);
    }

    /// c:525 — `zcurses_colorget_reverse(invalid)` returns None
    /// (i16::MAX is never a valid color pair index).
    #[test]
    fn zcurses_colorget_reverse_invalid_returns_none() {
        let _g = crate::test_util::global_state_lock();
        assert!(
            zcurses_colorget_reverse(i16::MAX).is_none(),
            "invalid color pair → None"
        );
    }

    /// c:544 — `freecolorpairnode("")` empty name is safe.
    #[test]
    fn freecolorpairnode_empty_name_safe() {
        let _g = crate::test_util::global_state_lock();
        freecolorpairnode("");
    }

    /// c:1420 — `zcurses_colorsarrgetfn` is deterministic.
    #[test]
    fn zcurses_colorsarrgetfn_is_deterministic() {
        let _g = crate::test_util::global_state_lock();
        let first = zcurses_colorsarrgetfn();
        for _ in 0..3 {
            assert_eq!(
                zcurses_colorsarrgetfn(),
                first,
                "zcurses_colorsarrgetfn must be deterministic"
            );
        }
    }

    /// c:1427 — `zcurses_attrgetfn` is deterministic.
    #[test]
    fn zcurses_attrgetfn_is_deterministic() {
        let _g = crate::test_util::global_state_lock();
        let first = zcurses_attrgetfn();
        for _ in 0..3 {
            assert_eq!(
                zcurses_attrgetfn(),
                first,
                "zcurses_attrgetfn must be deterministic"
            );
        }
    }

    /// c:1436 — `zcurses_keycodesgetfn` is deterministic.
    #[test]
    fn zcurses_keycodesgetfn_is_deterministic() {
        let _g = crate::test_util::global_state_lock();
        let first = zcurses_keycodesgetfn();
        for _ in 0..3 {
            assert_eq!(
                zcurses_keycodesgetfn(),
                first,
                "zcurses_keycodesgetfn must be deterministic"
            );
        }
    }

    /// c:1461 — `zcurses_colorsintgetfn` returns i64 (type pin).
    #[test]
    fn zcurses_colorsintgetfn_returns_i64_type() {
        let _g = crate::test_util::global_state_lock();
        let _: i64 = zcurses_colorsintgetfn();
    }

    /// c:1475 — `zcurses_colorpairsintgetfn` returns i64 (type pin).
    #[test]
    fn zcurses_colorpairsintgetfn_returns_i64_type() {
        let _g = crate::test_util::global_state_lock();
        let _: i64 = zcurses_colorpairsintgetfn();
    }

    /// c:1493 — `setup_` returns i32 (compile-time type pin).
    #[test]
    fn curses_setup_returns_i32_type() {
        let _g = crate::test_util::global_state_lock();
        let _: i32 = setup_(std::ptr::null());
    }

    /// c:1499 — features list non-empty.
    #[test]
    fn curses_features_nonempty() {
        let _g = crate::test_util::global_state_lock();
        let mut feats = Vec::new();
        features_(std::ptr::null(), &mut feats);
        assert!(!feats.is_empty(), "curses must advertise ≥1 feature");
    }

    /// c:1519 + c:1526 — cleanup/finish idempotent.
    #[test]
    fn curses_cleanup_finish_idempotent() {
        let _g = crate::test_util::global_state_lock();
        for _ in 0..5 {
            assert_eq!(cleanup_(std::ptr::null()), 0);
            assert_eq!(finish_(std::ptr::null()), 0);
        }
    }

    // ═══════════════════════════════════════════════════════════════════
    // Additional C-parity tests for Src/Modules/curses.c
    // c:293 zcurses_pairs_to_array / c:307 zcurses_strerror /
    // c:332 zcurses_getwindowbyname / c:379 zcurses_free_window /
    // c:418 zcurses_color / c:437 zcurses_colorget
    // ═══════════════════════════════════════════════════════════════════

    /// c:293 — `zcurses_pairs_to_array(&[])` returns empty Vec (alt).
    #[test]
    fn zcurses_pairs_to_array_empty_returns_empty_alt() {
        let v = zcurses_pairs_to_array(&[]);
        assert!(v.is_empty(), "empty input → empty Vec");
    }

    /// c:293 — `zcurses_pairs_to_array` returns Vec<String> (alt pin).
    #[test]
    fn zcurses_pairs_to_array_returns_vec_string_pin_alt() {
        let _: Vec<String> = zcurses_pairs_to_array(&[]);
    }

    /// c:307 — `zcurses_strerror(0)` returns non-empty static str.
    #[test]
    fn zcurses_strerror_zero_returns_non_empty() {
        let s = zcurses_strerror(0);
        assert!(!s.is_empty(), "zcurses_strerror(0) must be non-empty");
    }

    /// c:307 — `zcurses_strerror` returns `&'static str` (compile-time pin).
    #[test]
    fn zcurses_strerror_returns_static_str_type() {
        let _: &'static str = zcurses_strerror(-1);
    }

    /// c:307 — `zcurses_strerror` deterministic for any input.
    #[test]
    fn zcurses_strerror_deterministic() {
        for err in [0, -1, 1, 42, i32::MIN, i32::MAX] {
            let a = zcurses_strerror(err);
            let b = zcurses_strerror(err);
            assert_eq!(a, b, "zcurses_strerror({}) must be pure", err);
        }
    }

    /// c:332 — `zcurses_getwindowbyname("")` returns bool false (empty name).
    #[test]
    fn zcurses_getwindowbyname_empty_returns_false() {
        let _g = crate::test_util::global_state_lock();
        assert!(!zcurses_getwindowbyname(""), "empty name has no window");
    }

    /// c:332 — `zcurses_getwindowbyname` returns bool (compile-time pin).
    #[test]
    fn zcurses_getwindowbyname_returns_bool_type() {
        let _g = crate::test_util::global_state_lock();
        let _: bool = zcurses_getwindowbyname("__never_window__");
    }

    /// c:379 — `zcurses_free_window` returns i32 (compile-time pin).
    #[test]
    fn zcurses_free_window_returns_i32_type() {
        let _g = crate::test_util::global_state_lock();
        let _: i32 = zcurses_free_window("__never_window__");
    }

    /// c:418 — `zcurses_color("")` returns i32 sentinel for unknown.
    #[test]
    fn zcurses_color_empty_string_returns_sentinel() {
        let _g = crate::test_util::global_state_lock();
        let r = zcurses_color("");
        assert!(
            r < 0,
            "empty color name must return negative sentinel; got {}",
            r
        );
    }

    /// c:418 — `zcurses_color` is deterministic.
    #[test]
    fn zcurses_color_deterministic_for_unknown() {
        let _g = crate::test_util::global_state_lock();
        for name in ["__bogus_color__", "", "xyz"] {
            let first = zcurses_color(name);
            for _ in 0..3 {
                assert_eq!(
                    zcurses_color(name),
                    first,
                    "zcurses_color({:?}) must be pure",
                    name
                );
            }
        }
    }

    /// c:437 — `zcurses_colorget` returns Option<i16> (compile-time pin, alt).
    #[test]
    fn zcurses_colorget_returns_option_i16_pin_alt() {
        let _g = crate::test_util::global_state_lock();
        let _: Option<i16> = zcurses_colorget("__never__", "red/black");
    }
}