zshrs 0.11.18

//! Direct port of `Src/Zle/zle.h` — line-editor type / constant
//! header.
//!
//! Original C copyright: Paul Falstad 1992-1997.
//!
//! Hosts the type aliases (`Widget` / `Thingy` / `Keymap` /
//! `Cutbuffer` / etc.), enum / `#define` constants used across the
//! ZLE port, and the `struct widget` / `struct thingy` /
//! `struct modifier` / `struct change` / `struct vichange` /
//! `struct cutbuffer` / `struct brinfo` / `struct compldat` /
//! `struct region_highlight` / `struct watch_fd` / `REFRESH_ELEMENT`
//! shapes the C source uses.
//!
//! Multibyte note: zshrs uses native UTF-8 throughout, so the C
//! `#ifdef MULTIBYTE_SUPPORT` (zle.h:30-105) `wchar_t` types collapse
//! onto Rust `char` / `String`. The non-multibyte fallback (`char`
//! / `int`) is the parallel C path; the type aliases below pick
//! the shape that maps cleanly onto Rust.

#![allow(non_camel_case_types, non_snake_case, dead_code)]

use crate::ported::zsh_h::{zattr, HashNode};

// =====================================================================
// Wide-character types — `Src/Zle/zle.h:30-110`.
// =====================================================================
//
// C dispatches between `wchar_t` (MULTIBYTE_SUPPORT, zle.h:30-104)
// and `char` (non-multibyte, zle.h:105-181). Rust uses `char` for
// code-points and `String` for owned text — those primitives cover
// both C paths.

#[allow(unused_imports)]
use crate::ported::zle::{
    deltochar::*, textobjects::*, zle_hist::*, zle_main::*, zle_misc::*, zle_move::*,
    zle_params::*, zle_refresh::*, zle_tricky::*, zle_utils::*, zle_vi::*, zle_word::*,
};
/// Port of `ZLE_CHAR_T` from zle.h:31 / zle.h:107.

// --- AUTO: cross-zle hoisted-fn use glob ---
#[allow(unused_imports)]
// (was: use crate::ported::zle::widget::*; — widget.rs deleted)
#[allow(unused_imports)]

pub type ZLE_CHAR_T = char; // c:31

/// Port of `ZLE_STRING_T` from zle.h:32 / zle.h:108.
pub type ZLE_STRING_T = String; // c:32

/// Port of `ZLE_INT_T` from zle.h:33 / zle.h:109.
pub type ZLE_INT_T = i32; // c:33

/// Port of `ZLE_CHAR_SIZE` from zle.h:34. Rust `char` is always 4
/// bytes (USVs); the C `wchar_t` is 4 on every supported host.
pub const ZLE_CHAR_SIZE: usize = 4; // c:34

/// Port of `ZLEEOF` from zle.h:37 / zle.h:112.
pub const ZLEEOF: i32 = -1; // c:37 WEOF

/// Port of `Th(X)` macro from zle.h:316. `#define Th(X) (&thingies[X])`.
/// Resolves a fixed-thingy index into its Thingy reference.
///
/// In C, `thingies[]` is auto-generated by `mkbltnmlst.sh` from the
/// `mod_export Thingy` declarations sprinkled across `zle.h`/`zle_*.c`.
/// Each `t_<name>` constant indexes one slot. zshrs hasn't ported
/// that build-time auto-gen, so this helper uses the manually-kept
/// index→name table in `T_THINGY_NAMES` below and forwards to
/// `lookup_thingy(name)` — same observable contract as the C macro.
#[inline]
pub fn Th(index: i32) -> Option<crate::ported::zle::zle_thingy::Thingy> {
    // c:316
    let i: usize = (index as i64).try_into().ok()?;
    let name = T_THINGY_NAMES.get(i)?;
    crate::ported::zle::zle_thingy::gethashnode2(name)
}

/// Fixed-thingy index table. Order matches the `mod_export Thingy
/// t_<name>` declaration order in `Src/Zle/zle.h` so callers can use
/// `Th(t_acceptline as i32)` exactly as they would in C. Add new
/// entries here when `t_<name>` constants get back-ported; the
/// indices are stable per zsh ABI.
pub const T_THINGY_NAMES: &[&str] = &[
    "accept-and-hold",                     // t_acceptandhold     = 0
    "accept-line",                         // t_acceptline        = 1
    "accept-line-and-down-history",        // t_acceptlineanddownhistory
    "accept-search",                       // t_acceptsearch
    "auto-suffix-remove",                  // t_autosuffixremove
    "auto-suffix-retain",                  // t_autosuffixretain
    "backward-char",                       // t_backwardchar
    "backward-delete-char",                // t_backwarddeletechar
    "beep",                                // t_beep
    "clear-screen",                        // t_clearscreen
    "complete-word",                       // t_completeword
    "describe-key-briefly",                // t_describekeybriefly
    "down-line-or-history",                // t_downlineorhistory
    "execute-named-cmd",                   // t_executenamedcmd
    "exit",                                // t_exit
    "forward-char",                        // t_forwardchar
    "history-incremental-search-backward", // t_historyincrementalsearchbackward
    "history-incremental-search-forward",  // t_historyincrementalsearchforward
    "list-choices",                        // t_listchoices
    "menu-complete",                       // t_menucomplete
    "menu-expand-or-complete",             // t_menuexpandorcomplete
    "redisplay",                           // t_redisplay
    "self-insert",                         // t_selfinsert
    "self-insert-unmeta",                  // t_selfinsertunmeta
    "send-break",                          // t_sendbreak
    "undefined-key",                       // t_undefinedkey
    "undo",                                // t_undo
    "up-line-or-history",                  // t_uplineorhistory
    "vi-cmd-mode",                         // t_vicmdmode
    "yank",                                // t_yank
];

/// Port of `invicmdmode()` macro from zle.h:324.
/// `#define invicmdmode() (!strcmp(curkeymapname, "vicmd"))`.
/// True when the current keymap is the vi command-mode keymap.
/// The Rust `in_vi_cmd_mode()` free fn (zle_main.rs:815) is the
/// state-bound counterpart; this free-fn uses the global keymap name.
#[inline]
pub fn invicmdmode(curkeymapname: &str) -> bool {
    // c:324
    curkeymapname == "vicmd"
}

// =====================================================================
// `ZS_*` wide-string macros — `Src/Zle/zle.h:40-51`.
// C #defines route to wmemcpy/wcslen/etc. on MULTIBYTE_SUPPORT builds
// and to the memcpy/strlen counterparts otherwise. Rust uses `char` /
// `[char]` directly so each macro maps to a slice operation.
// =====================================================================

/// Port of `ZS_memcpy` from zle.h:40 (`#define ZS_memcpy wmemcpy`).
/// Copies `n` chars from `src` into `dst`.
#[inline]
pub fn ZS_memcpy(dst: &mut [ZLE_CHAR_T], src: &[ZLE_CHAR_T], n: usize) {
    // c:40
    dst[..n].copy_from_slice(&src[..n]);
}

/// Port of `ZS_memmove` from zle.h:41 (`#define ZS_memmove wmemmove`).
/// Same as ZS_memcpy but tolerates overlapping ranges (vec move
/// semantics handle overlap).
#[inline]
pub fn ZS_memmove(dst: &mut [ZLE_CHAR_T], src: &[ZLE_CHAR_T], n: usize) {
    // c:41
    let v: Vec<ZLE_CHAR_T> = src[..n].to_vec();
    dst[..n].copy_from_slice(&v);
}

/// Port of `ZS_memset` from zle.h:42 (`#define ZS_memset wmemset`).
/// Fills `dst[..n]` with `c`.
#[inline]
pub fn ZS_memset(dst: &mut [ZLE_CHAR_T], c: ZLE_CHAR_T, n: usize) {
    // c:42
    for slot in dst.iter_mut().take(n) {
        *slot = c;
    }
}

/// Port of `ZS_memcmp` from zle.h:43 (`#define ZS_memcmp wmemcmp`).
/// Returns Ordering of the first `n` chars.
#[inline]
pub fn ZS_memcmp(a: &[ZLE_CHAR_T], b: &[ZLE_CHAR_T], n: usize) -> std::cmp::Ordering {
    // c:43
    a[..n].cmp(&b[..n])
}

/// Port of `ZS_strlen` from zle.h:44 (`#define ZS_strlen wcslen`).
/// Returns the length to the first NUL char (or full slice length
/// if no NUL found).
#[inline]
pub fn ZS_strlen(s: &[ZLE_CHAR_T]) -> usize {
    // c:44
    s.iter().position(|&c| c == '\0').unwrap_or(s.len())
}

/// Port of `ZS_strcpy` from zle.h:45 (`#define ZS_strcpy wcscpy`).
/// Copies `src` (up to first NUL or end) into `dst`, NUL-terminates
/// when there's room.
#[inline]
pub fn ZS_strcpy(dst: &mut [ZLE_CHAR_T], src: &[ZLE_CHAR_T]) {
    // c:45
    let n = ZS_strlen(src);
    let limit = dst.len().min(n);
    dst[..limit].copy_from_slice(&src[..limit]);
    if limit < dst.len() {
        dst[limit] = '\0';
    }
}

/// Port of `ZS_strncpy` from zle.h:46 (`#define ZS_strncpy wcsncpy`).
/// Copies up to `n` chars; pads remainder with NUL if `src` is shorter.
#[inline]
pub fn ZS_strncpy(dst: &mut [ZLE_CHAR_T], src: &[ZLE_CHAR_T], n: usize) {
    // c:46
    let s_len = ZS_strlen(src).min(n);
    let limit = dst.len().min(n);
    let copy = s_len.min(limit);
    dst[..copy].copy_from_slice(&src[..copy]);
    for slot in dst.iter_mut().take(limit).skip(copy) {
        *slot = '\0';
    }
}

/// Port of `ZS_strncmp` from zle.h:47 (`#define ZS_strncmp wcsncmp`).
/// Returns Ordering of up to `n` chars (stops at NUL).
#[inline]
pub fn ZS_strncmp(a: &[ZLE_CHAR_T], b: &[ZLE_CHAR_T], n: usize) -> std::cmp::Ordering {
    // c:47
    let a_n = ZS_strlen(a).min(n);
    let b_n = ZS_strlen(b).min(n);
    let limit = a_n.min(b_n);
    let cmp = a[..limit].cmp(&b[..limit]);
    if cmp != std::cmp::Ordering::Equal {
        return cmp;
    }
    a_n.cmp(&b_n)
}

/// Port of `ZS_strchr` from zle.h:50 (`#define ZS_strchr wcschr`).
/// Returns the index of the first occurrence of `c` in `s`, or `None`.
#[inline]
pub fn ZS_strchr(s: &[ZLE_CHAR_T], c: ZLE_CHAR_T) -> Option<usize> {
    // c:50
    s.iter().position(|&x| x == c)
}

/// Port of `ZS_memchr` from zle.h:51 (`#define ZS_memchr wmemchr`).
/// Returns the index of the first occurrence of `c` in `s[..n]`.
#[inline]
pub fn ZS_memchr(s: &[ZLE_CHAR_T], c: ZLE_CHAR_T, n: usize) -> Option<usize> {
    // c:51
    s[..n.min(s.len())].iter().position(|&x| x == c)
}

/// Port of `ZS_width` from zle.h:49 (`#define ZS_width wcslen`).
/// Returns the display width of a string (collapses to char count
/// for the non-multibyte path; in zshrs we treat each char as 1 col).
#[inline]
pub fn ZS_width(s: &[ZLE_CHAR_T]) -> usize {
    // c:49
    ZS_strlen(s)
}

// =====================================================================
// `ZC_*` wide-character classification macros — `Src/Zle/zle.h:60-73`.
// C #defines route to `iswalpha`/`iswalnum`/etc. on MULTIBYTE_SUPPORT
// builds and to the `<ctype.h>` counterparts otherwise. Rust's
// `char::is_*` methods cover both paths uniformly.
// =====================================================================

/// Port of `ZC_ialpha` from zle.h:60.
#[inline]
pub fn ZC_ialpha(c: ZLE_CHAR_T) -> bool {
    c.is_alphabetic()
} // c:60
/// Port of `ZC_ialnum` from zle.h:61.
#[inline]
pub fn ZC_ialnum(c: ZLE_CHAR_T) -> bool {
    c.is_alphanumeric()
} // c:61
/// Port of `ZC_iblank` from zle.h:62 (`#define ZC_iblank wcsiblank`).
/// Routes through the canonical `wcsiblank` impl at
/// `Src/utils.c:4302-4307` — `iswspace(wc) && wc != L'\n'`. Catches
/// CR/FF/VT/NBSP/U+2028/etc. in addition to space and tab; only
/// newline is explicitly excluded.
#[inline]
pub fn ZC_iblank(c: ZLE_CHAR_T) -> bool {
    // c:62
    crate::ported::utils::wcsiblank(c)
}
/// Port of `ZC_icntrl` from zle.h:63.
#[inline]
pub fn ZC_icntrl(c: ZLE_CHAR_T) -> bool {
    c.is_control()
} // c:63
/// Port of `ZC_idigit` from zle.h:64.
#[inline]
pub fn ZC_idigit(c: ZLE_CHAR_T) -> bool {
    c.is_ascii_digit()
} // c:64
/// Port of `ZC_iident` from zle.h:65 (`wcsitype(c, IIDENT)`). Identifier
/// char per zsh's IIDENT class: alphanumeric or `_`.
#[inline]
pub fn ZC_iident(c: ZLE_CHAR_T) -> bool {
    c.is_alphanumeric() || c == '_'
} // c:65
/// Port of `ZC_ilower` from zle.h:66.
#[inline]
pub fn ZC_ilower(c: ZLE_CHAR_T) -> bool {
    c.is_lowercase()
} // c:66
/// Port of `ZC_inblank` from zle.h:67 (`iswspace`). True for any
/// whitespace char (incl. newline).
#[inline]
pub fn ZC_inblank(c: ZLE_CHAR_T) -> bool {
    c.is_whitespace()
} // c:67
/// Port of `ZC_iupper` from zle.h:68.
#[inline]
pub fn ZC_iupper(c: ZLE_CHAR_T) -> bool {
    c.is_uppercase()
} // c:68
/// Port of `ZC_iword` from zle.h:69 (`wcsitype(c, IWORD)`). Word
/// char per zsh's IWORD class: alphanumeric or `_`.
#[inline]
pub fn ZC_iword(c: ZLE_CHAR_T) -> bool {
    c.is_alphanumeric() || c == '_'
} // c:69
/// Port of `ZC_ipunct` from zle.h:70.
#[inline]
pub fn ZC_ipunct(c: ZLE_CHAR_T) -> bool {
    c.is_ascii_punctuation()
} // c:70

/// Port of `ZC_tolower` from zle.h:72.
#[inline]
pub fn ZC_tolower(c: ZLE_CHAR_T) -> ZLE_CHAR_T {
    // c:72
    c.to_lowercase().next().unwrap_or(c)
}
/// Port of `ZC_toupper` from zle.h:73.
#[inline]
pub fn ZC_toupper(c: ZLE_CHAR_T) -> ZLE_CHAR_T {
    // c:73
    c.to_uppercase().next().unwrap_or(c)
}

// =====================================================================
// `LASTFULLCHAR` — `Src/Zle/zle.h:75-76`. Macro alias resolving to
// `lastchar_wide` (the most-recent fully-decoded codepoint). Lives
// as a field on `Zle` (`lastchar_wide: i32`); the macro name is
// kept here as an alias for searchability.
// =====================================================================

// =====================================================================
// Widget — `Src/Zle/zle.h:184-220`.
// =====================================================================

/// Port of `typedef struct widget *Widget` from zle.h:184.
pub type WidgetPtr = Box<widget>; // c:184

/// Port of `typedef struct thingy *Thingy` from zle.h:185.
pub type ThingyPtr = Box<thingy>; // c:185

/// Port of `ZleIntFunc` from zle.h:189. C: `int (*)(char **)` —
/// every internal widget conforms to this signature.
pub type ZleIntFunc = fn(args: &[String]) -> i32; // c:189

/// Port of `struct widget` from `Src/Zle/zle.h:191-203`.
/// ```c
/// struct widget {
///     int flags;     /* WIDGET_* / ZLE_* flag bitset */
///     Thingy first;  /* `first` thingy that names this widget */
///     union {
///         ZleIntFunc fn; /* internal widget */
///         char *fnnam;   /* shell-function name for user-defined */
///         struct { ZleIntFunc fn; char *wid; char *func; } comp;
///     } u;
/// };
/// ```

pub struct widget {
    // c:191
    /// flags (see below).
    pub flags: i32, // c:192
    /// `first' thingy that names this widget.
    pub first: Option<ThingyPtr>, // c:193
    /// Tagged equivalent of the C anonymous union (zle.h:194-202).
    pub u: WidgetImpl, // c:194
}

impl Clone for widget {
    fn clone(&self) -> Self {
        widget {
            flags: self.flags,
            first: None, // ThingyPtr is Box<thingy>, intentionally not deep-cloned.
            u: match &self.u {
                WidgetImpl::Internal(f) => WidgetImpl::Internal(*f),
                WidgetImpl::UserFunc(s) => WidgetImpl::UserFunc(s.clone()),
                WidgetImpl::Comp { fn_, wid, func } => WidgetImpl::Comp {
                    fn_: *fn_,
                    wid: wid.clone(),
                    func: func.clone(),
                },
            },
        }
    }
}

impl std::fmt::Debug for widget {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("widget")
            .field("flags", &self.flags)
            .field(
                "u",
                &match &self.u {
                    WidgetImpl::Internal(_) => "Internal(<fn>)".to_string(),
                    WidgetImpl::UserFunc(s) => format!("UserFunc({})", s),
                    WidgetImpl::Comp { .. } => "Comp{..}".to_string(),
                },
            )
            .finish()
    }
}

impl widget {
    /// Build a widget that points at a Rust function pointer with the
    /// supplied ZLE flags. Equivalent to the WIDGET_INT branch of
    /// `zalloc(sizeof(*w))` + `w->u.fn = ...` in `addzlefunction()` at
    /// Src/Zle/zle_thingy.c:281.
    pub fn internal(name: &str, func: ZleIntFunc, flags: i32) -> Self {
        let _ = name;
        widget {
            flags: flags | WIDGET_INT,
            first: None,
            u: WidgetImpl::Internal(func),
        }
    }

    /// Resolve a built-in widget name to its canonical fn pointer
    /// via `zle_bindings::iwidget_lookup`. Mirrors the dispatch C
    /// achieves at `Src/Zle/zle_bindings.c:55-60` through the
    /// generated `widgets[]` static table; the Rust port uses a
    /// name → fn-pointer match keyed off the same `iwidgets.list`
    /// canonical names. Unknown widget names get a no-op fn
    /// pointer (matches what `t_undefinedkey` resolves to).
    pub fn builtin(name: &str) -> Self {
        let f = super::zle_bindings::iwidget_lookup(name).unwrap_or(|_args: &[String]| 0i32);
        widget {
            flags: WIDGET_INT,
            first: None,
            u: WidgetImpl::Internal(f),
        }
    }

    /// Build a widget that wraps a user-defined shell function.
    /// Equivalent to `bin_zle_new()` from Src/Zle/zle_thingy.c:584.
    pub fn user_defined(name: &str, func_name: &str) -> Self {
        let _ = name;
        widget {
            flags: 0i32,
            first: None,
            u: WidgetImpl::UserFunc(func_name.to_string()),
        }
    }
}

/// Tagged port of the `widget.u` union from `Src/Zle/zle.h:194-202`.
/// C uses an inline anonymous union; Rust enum tags the active
/// variant.
pub enum WidgetImpl {
    // c:194
    /// `u.fn` — pointer to internally implemented widget.
    Internal(ZleIntFunc), // c:195
    /// `u.fnnam` — name of the shell function for user-defined widget.
    UserFunc(String), // c:196
    /// `u.comp` — completion-widget triple.
    Comp {
        fn_: ZleIntFunc,
        wid: String,
        func: String,
    }, // c:197-201
}

// Widget flags — `Src/Zle/zle.h:205-220`.
pub const WIDGET_INT: i32 = 1 << 0; /* widget is internally implemented */
// c:205
pub const WIDGET_NCOMP: i32 = 1 << 1; /* new style completion widget */
// c:206
pub const ZLE_MENUCMP: i32 = 1 << 2; /* DON'T invalidate completion list */
// c:207
pub const ZLE_YANKAFTER: i32 = 1 << 3; // c:208
pub const ZLE_YANKBEFORE: i32 = 1 << 4; // c:209
pub const ZLE_YANK: i32 = ZLE_YANKAFTER | ZLE_YANKBEFORE; // c:210
pub const ZLE_LINEMOVE: i32 = 1 << 5; /* line-oriented movement */
// c:211
pub const ZLE_VIOPER: i32 = 1 << 6; /* widget reads further keys so wait if prefix */
// c:212
pub const ZLE_LASTCOL: i32 = 1 << 7; /* command maintains lastcol correctly */
// c:213
pub const ZLE_KILL: i32 = 1 << 8; // c:214
pub const ZLE_KEEPSUFFIX: i32 = 1 << 9; /* DON'T remove added suffix */
// c:215
pub const ZLE_NOTCOMMAND: i32 = 1 << 10; /* widget should not alter lastcmd */
// c:216
pub const ZLE_ISCOMP: i32 = 1 << 11; /* usable for new style completion */
// c:217
pub const WIDGET_INUSE: i32 = 1 << 12; /* widget is in use */
// c:218
pub const WIDGET_FREE: i32 = 1 << 13; /* request to free when no longer in use */
// c:219
pub const ZLE_NOLAST: i32 = 1 << 14; /* widget should not alter lbindk */
// c:220

// =====================================================================
// Thingy — `Src/Zle/zle.h:224-235`.
// =====================================================================

/// Port of `struct thingy` from `Src/Zle/zle.h:224-231`. HashNode
/// subtype keyed by name; circular list (`samew`) of all thingies
/// pointing at the same widget.
pub struct thingy {
    // c:224
    /// next node in the hash chain.
    pub next: Option<HashNode>, // c:225
    /// name of the thingy.
    pub nam: String, // c:226
    /// TH_* flags (see below).
    pub flags: i32, // c:227
    /// reference count.
    pub rc: i32, // c:228
    /// widget named by this thingy.
    pub widget: Option<WidgetPtr>, // c:229
    /// `next' thingy (circularly) naming the same widget.
    pub samew: Option<ThingyPtr>, // c:230
}

/// `DISABLED` is `(1<<0)` (generic hashnode flag — defined in zsh.h).
/// `TH_IMMORTAL` from zle.h:234 — can't refer to a different widget.
pub const TH_IMMORTAL: i32 = 1 << 1; // c:234

// =====================================================================
// Modifier — `Src/Zle/zle.h:243-263`.
// =====================================================================

/// Port of `struct modifier` from `Src/Zle/zle.h:245-251`.
/// Command modifier prefix state (numeric arg, vi cut buffer, etc.).
#[derive(Clone)]
pub struct modifier {
    // c:245
    /// MOD_* flags (see below).
    pub flags: i32, // c:246
    /// repeat count.
    pub mult: i32, // c:247
    /// repeat count actually being edited.
    pub tmult: i32, // c:248
    /// vi cut buffer.
    pub vibuf: i32, // c:249
    /// numeric base for digit arguments (usually 10).
    pub base: i32, // c:250
}

pub const MOD_MULT: i32 = 1 << 0; /* a repeat count has been selected */
// c:253
pub const MOD_TMULT: i32 = 1 << 1; /* a repeat count is being entered */
// c:254
pub const MOD_VIBUF: i32 = 1 << 2; /* a vi cut buffer has been selected */
// c:255
pub const MOD_VIAPP: i32 = 1 << 3; /* appending to the vi cut buffer */
// c:256
pub const MOD_NEG: i32 = 1 << 4; /* last command was negate argument */
// c:257
pub const MOD_NULL: i32 = 1 << 5; /* throw away text for the vi cut buffer */
// c:258
pub const MOD_CHAR: i32 = 1 << 6; /* force character-wise movement */
// c:259
pub const MOD_LINE: i32 = 1 << 7; /* force line-wise movement */
// c:260
pub const MOD_PRI: i32 = 1 << 8; /* OS primary selection for the vi cut buffer */
// c:261
pub const MOD_CLIP: i32 = 1 << 9; /* OS clipboard for the vi cut buffer */
// c:262
pub const MOD_OSSEL: i32 = MOD_PRI | MOD_CLIP; /* either system selection */
// c:263

// =====================================================================
// Cut-buffer flag bits — `Src/Zle/zle.h:271-280`.
// =====================================================================

pub const CUT_FRONT: i32 = 1 << 0; /* Text goes in front of cut buffer */
// c:271
pub const CUT_REPLACE: i32 = 1 << 1; /* Text replaces cut buffer */
// c:272
/// `CUT_RAW` (zle.h:273-279). Raw character counts (not used in
/// `cut` itself). This is used when the values are offsets into
/// the zleline array rather than numbers of visible characters
/// directly input by the user.
pub const CUT_RAW: i32 = 1 << 2; // c:273
pub const CUT_YANK: i32 = 1 << 3; /* vi yank: use register 0 instead of 1-9 */
// c:280

// =====================================================================
// Change (undo system) — `Src/Zle/zle.h:282-298`.
// =====================================================================

/// Port of `struct change` from `Src/Zle/zle.h:284-295`. The undo
/// log is a doubly-linked list of these entries.
#[derive(Clone, Debug)]
pub struct change {
    // c:284
    /// previous adjacent change.
    pub prev: Option<Box<change>>, // c:285
    /// next adjacent change.
    pub next: Option<Box<change>>, // c:285
    /// see CH_* below.
    pub flags: i32, // c:286
    /// history line being changed.
    pub hist: i32, // c:287
    /// offset of the text changes.
    pub off: i32, // c:288
    /// characters to delete.
    pub del: ZLE_STRING_T, // c:289
    /// no. of characters in del.
    pub dell: i32, // c:290
    /// characters to insert.
    pub ins: ZLE_STRING_T, // c:291
    /// no. of characters in ins.
    pub insl: i32, // c:292
    /// old cursor position.
    pub old_cs: i32, // c:293
    /// new cursor position.
    pub new_cs: i32, // c:293
    /// unique number of this change (`zlong`).
    pub changeno: i64, // c:294
}

pub const CH_NEXT: i32 = 1 << 0; /* next structure is also part of this change */
// c:297
pub const CH_PREV: i32 = 1 << 1; /* previous structure is also part of this change */
// c:298

// =====================================================================
// VI change — `Src/Zle/zle.h:300-313`.
// =====================================================================

/// Port of `struct vichange` from `Src/Zle/zle.h:308-312`. Stores
/// the byte sequence of a vi command for `.` (vi-repeat-change).
///
/// From zle.h:302-307: examination of the code suggests vichgbuf
/// is consistently tied to raw byte input, so it is left as a
/// character array rather than turned into wide characters. In
/// particular, when we replay it we use `ungetbytes()`.
pub struct vichange {
    // c:308
    /// value of zmod associated with vi change.
    pub mod_: modifier, // c:309
    /// bytes for keys that make up the vi command.
    pub buf: Vec<u8>, // c:310
    /// allocated size of buf.
    pub bufsz: i32, // c:311
    /// in-use size of buf.
    pub bufptr: i32, // c:311
}

// =====================================================================
// Keymap — `Src/Zle/zle.h:316-322`.
// =====================================================================

// `KeymapPtr` / `keymap_opaque` deleted — Rust-invented placeholder
// for the `typedef struct keymap *Keymap` opaque alias at zle.h:320.
// The real `Keymap` struct (full port of `struct keymap` at
// `zle_keymap.c:64`) lives in `zle_keymap.rs` and callers
// reference it directly via `Arc<Keymap>`.

/// Port of `KeyScanFunc` from zle.h:322.
/// C: `void (*KeyScanFunc) (char *, Thingy, char *, void *)`.
pub type KeyScanFunc = fn(seq: &str, t: &thingy, ext: &str, data: usize); // c:322

// =====================================================================
// Suffix removal — `Src/Zle/zle.h:326-333`.
// =====================================================================

/// Port of `NO_INSERT_CHAR` from zle.h:329 / zle.h:331.
pub const NO_INSERT_CHAR: i32 = 256; // c:331

/// Port of `removesuffix()` from zle.h:333.
/// C: `iremovesuffix(NO_INSERT_CHAR, 0)`.
pub fn removesuffix() -> i32 {
    // c:333
    crate::ported::zle::zle_misc::iremovesuffix(NO_INSERT_CHAR, 0) // c:333
}

// =====================================================================
// Cutbuffer — `Src/Zle/zle.h:335-352`.
// =====================================================================

/// Port of `struct cutbuffer` from `Src/Zle/zle.h:342-346`.
/// From zle.h:335-340: cut/kill buffer. The buffer itself is purely
/// binary data, not NUL-terminated. `len` is a character count
/// (N.B. number of characters, not size in bytes). `flags` uses the
/// CUTBUFFER_* constants defined below.
pub struct cutbuffer {
    // c:342
    pub buf: ZLE_STRING_T, // c:343
    pub len: usize,        // c:344
    pub flags: u8,         // c:345
}

/// Port of `typedef struct cutbuffer *Cutbuffer` from zle.h:348.
pub type CutbufferPtr = Box<cutbuffer>; // c:348

pub const CUTBUFFER_LINE: u8 = 1; /* for vi: buffer contains whole lines of data */
// c:350
pub const KRINGCTDEF: i32 = 8; /* default number of buffers in the kill ring */
// c:352

// =====================================================================
// Completion modes — `Src/Zle/zle.h:354-362`.
// =====================================================================

pub const COMP_COMPLETE: i32 = 0; // c:356
pub const COMP_LIST_COMPLETE: i32 = 1; // c:357
pub const COMP_SPELL: i32 = 2; // c:358
pub const COMP_EXPAND: i32 = 3; // c:359
pub const COMP_EXPAND_COMPLETE: i32 = 4; // c:360
pub const COMP_LIST_EXPAND: i32 = 5; // c:361

/// Port of `COMP_ISEXPAND(X)` from zle.h:362.
#[inline]
pub fn COMP_ISEXPAND(x: i32) -> bool {
    x >= COMP_EXPAND
} // c:362

// =====================================================================
// Brace runs (Brinfo) — `Src/Zle/zle.h:364-375`.
// =====================================================================

/// Port of `typedef struct brinfo *Brinfo` from zle.h:366.
pub type BrinfoPtr = Box<brinfo>; // c:366

/// Port of `struct brinfo` from `Src/Zle/zle.h:368-375`.
/// One brace run during brace-expansion completion.
pub struct brinfo {
    // c:368
    /// next in list.
    pub next: Option<BrinfoPtr>, // c:369
    /// previous (only for closing braces).
    pub prev: Option<BrinfoPtr>, // c:370
    /// the string to insert.
    pub str: String, // c:371
    /// original position.
    pub pos: i32, // c:372
    /// original position, with quoting.
    pub qpos: i32, // c:373
    /// position for current match.
    pub curpos: i32, // c:374
}

// =====================================================================
// Hook offsets — `Src/Zle/zle.h:377-402`.
// =====================================================================

pub const LISTMATCHESHOOK: i32 = 0; // c:379
pub const COMPLETEHOOK: i32 = 1; // c:380
pub const BEFORECOMPLETEHOOK: i32 = 2; // c:381
pub const AFTERCOMPLETEHOOK: i32 = 3; // c:382
pub const ACCEPTCOMPHOOK: i32 = 4; // c:383
pub const INVALIDATELISTHOOK: i32 = 5; // c:384

// =====================================================================
// Compldat — `Src/Zle/zle.h:386-394`.
// =====================================================================

/// Port of `typedef struct compldat *Compldat` from zle.h:388.
pub type CompldatPtr = Box<compldat>; // c:388

/// Port of `struct compldat` from `Src/Zle/zle.h:390-394`. Payload
/// passed to the COMPLETEHOOK callback.
pub struct compldat {
    // c:390
    pub s: String,  // c:391
    pub lst: i32,   // c:392
    pub incmd: i32, // c:393
}

/// Direct port of `listmatches()` from `Src/Zle/zle.h:398`. Fires the
/// LISTMATCHESHOOK chain via `runhookdef`, falling back to the
/// canonical `ilistmatches` renderer when no user hook is registered.
pub fn listmatches() {
    // c:398
    // c:398 — `runhookdef(LISTMATCHESHOOK, NULL)`. Returns nonzero
    // when a Hookfn handled it; 0 (or no handler registered) falls
    // through to the default renderer.
    let h = crate::ported::module::gethookdef("list-matches");
    let handled = if !h.is_null() {
        crate::ported::module::runhookdef(h, std::ptr::null_mut()) != 0
    } else {
        false
    };
    if !handled {
        // Default handler — ilistmatches (compresult.c:2284).
        let _ = crate::ported::zle::compresult::ilistmatches();
    }
}

/// Direct port of `invalidatelist()` from `Src/Zle/zle.h:402`. Fires
/// the INVALIDATELISTHOOK chain via `runhookdef`, falling back to the
/// canonical `invalidate_list` cleanup (compresult.c:2334) when no
/// user hook is registered.
pub fn invalidatelist() {
    // c:402
    // c:402 — `runhookdef(INVALIDATELISTHOOK, NULL)`. Returns nonzero
    // when a Hookfn handled it; 0 or no registration falls through to
    // the default cleanup path.
    let h = crate::ported::module::gethookdef("invalidate-list");
    let handled = if !h.is_null() {
        crate::ported::module::runhookdef(h, std::ptr::null_mut()) != 0
    } else {
        false
    };
    if !handled {
        let _ = crate::ported::zle::compresult::invalidate_list();
    }
}

// =====================================================================
// setline flags — `Src/Zle/zle.h:404-408`.
// =====================================================================

pub const ZSL_COPY: i32 = 1; /* Copy the argument, don't modify it */
// c:406
pub const ZSL_TOEND: i32 = 2; /* Go to the end of the new line */
// c:407

// =====================================================================
// Suffix type / flags — `Src/Zle/zle.h:411-422`.
// =====================================================================

/// Port of `enum suffixtype` from zle.h:412 (type arguments to
/// `addsuffix()`).
pub const SUFTYP_POSSTR: i32 = 0; /* String of characters to match */
// c:413
pub const SUFTYP_NEGSTR: i32 = 1; /* String of characters not to match */
// c:414
pub const SUFTYP_POSRNG: i32 = 2; /* Range of characters to match */
// c:415
pub const SUFTYP_NEGRNG: i32 = 3; /* Range of characters not to match */
// c:416

/// Port of `enum suffixflags` from zle.h:420 (additional flags to
/// suffixes).
pub const SUFFLAGS_SPACE: i32 = 0x0001; /* Add a space when removing suffix */
// c:421

// =====================================================================
// Region highlight — `Src/Zle/zle.h:425-473`.
// =====================================================================

/// `ZRH_PREDISPLAY` — region offsets include predisplay text.
pub const ZRH_PREDISPLAY: i32 = 1; // c:428

/// Port of `struct region_highlight` from `Src/Zle/zle.h:435-461`.
/// Attributes used for highlighting regions and the mark.
pub struct region_highlight {
    // c:435
    /// Attributes for the region.
    pub atr: zattr, // c:437
    /// Explicitly set attributes for the region.
    pub atrmask: zattr, // c:439
    /// Priority for this region relative to others that overlap.
    pub layer: i32, // c:441
    /// Start of the region.
    pub start: i32, // c:443
    /// Start of the region in metafied ZLE line.
    pub start_meta: i32, // c:445
    /// End of the region: position of the first character not
    /// highlighted (the same system as for point and mark).
    pub end: i32, // c:450
    /// End of the region in metafied ZLE line.
    pub end_meta: i32, // c:452
    /// Any of the flags defined above.
    pub flags: i32, // c:456
    /// User-settable "memo" key. Metafied.
    pub memo: Option<String>, // c:460
}

/// Port of `N_SPECIAL_HIGHLIGHTS` from zle.h:473.
/// Count of special uses of region highlighting:
/// 0=region between point and mark, 1=isearch region, 2=suffix,
/// 3=pasted text.
pub const N_SPECIAL_HIGHLIGHTS: i32 = 4; // c:473

// =====================================================================
// Cursor context — `Src/Zle/zle.h:475-486`.
// =====================================================================

/// Port of `enum cursorcontext` from zle.h:476.
pub const CURC_EDIT: i32 = 0; // c:477
pub const CURC_COMMAND: i32 = 1; // c:478
pub const CURC_INSERT: i32 = 2; // c:479
pub const CURC_OVERWRITE: i32 = 3; // c:480
pub const CURC_PENDING: i32 = 4; // c:481
pub const CURC_REGION_START: i32 = 5; // c:482
pub const CURC_REGION_END: i32 = 6; // c:483
pub const CURC_VISUAL: i32 = 7; // c:484
pub const CURC_DEFAULT: i32 = 8; // c:485

// =====================================================================
// Cursor flag bits — `Src/Zle/zle.h:488-500`.
// =====================================================================

pub const CURF_DEFAULT: i32 = 0; // c:488
pub const CURF_UNDERLINE: i32 = 1; // c:489
pub const CURF_BAR: i32 = 2; // c:490
pub const CURF_BLOCK: i32 = 3; // c:491
pub const CURF_SHAPE_MASK: i32 = 3; // c:492
pub const CURF_BLINK: i32 = 1 << 2; // c:493
pub const CURF_STEADY: i32 = 1 << 3; // c:494
pub const CURF_HIDDEN: i32 = 1 << 4; // c:495
pub const CURF_COLOR: i32 = 1 << 5; // c:496
pub const CURF_COLOR_MASK: u32 = (0xffffff_u32 << 8) | (CURF_COLOR as u32); // c:497
pub const CURF_RED_SHIFT: i32 = 24; // c:498
pub const CURF_GREEN_SHIFT: i32 = 16; // c:499
pub const CURF_BLUE_SHIFT: i32 = 8; // c:500

// =====================================================================
// Refresh element — `Src/Zle/zle.h:502-529`.
// =====================================================================

/// Port of `REFRESH_CHAR` from zle.h:507 (multibyte) / zle.h:509
/// (non-multibyte). Rust uses `char` since native UTF-8 covers both.
pub type REFRESH_CHAR = char; // c:507

/// Port of `REFRESH_ELEMENT` from `Src/Zle/zle.h:515-526`.
/// One character cell in the on-screen display buffer.
/// From zle.h:516-520: the (possibly wide) character. If `atr`
/// contains `TXT_MULTIWORD_MASK`, an index into the set of
/// multiword symbols (only if MULTIBYTE_SUPPORT is present).
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct REFRESH_ELEMENT {
    // c:515
    /// The (possibly wide) character.
    pub chr: REFRESH_CHAR, // c:521
    /// Its attributes.
    pub atr: zattr, // c:525
}

/// Port of `REFRESH_STRING` from zle.h:529. A string of screen cells.
pub type REFRESH_STRING = Vec<REFRESH_ELEMENT>; // c:529

// =====================================================================
// ZSH_INVALID_WCHAR — `Src/Zle/zle.h:532-553`.
// =====================================================================
//
// From zle.h:533-539: with ISO 10646 there is a private range
// defined within the encoding. We use this for storing single-byte
// characters in sections of strings that wouldn't convert to wide
// characters. This allows to preserve the string when transformed
// back to multibyte strings.

/// `ZSH_INVALID_WCHAR_BASE` from zle.h:541. The start of the
/// private range we use, for 256 characters.
pub const ZSH_INVALID_WCHAR_BASE: u32 = 0xe000; // c:541

/// Port of `ZSH_INVALID_WCHAR_TEST(x)` from zle.h:544. Detect a
/// wide character within our range.
#[inline]
pub fn ZSH_INVALID_WCHAR_TEST(x: u32) -> bool {
    // c:544
    x >= ZSH_INVALID_WCHAR_BASE && x <= ZSH_INVALID_WCHAR_BASE + 255
}

/// Port of `ZSH_INVALID_WCHAR_TO_CHAR(x)` from zle.h:548. Turn a
/// wide character in that range back to single byte.
#[inline]
pub fn ZSH_INVALID_WCHAR_TO_CHAR(x: u32) -> u8 {
    // c:548
    (x - ZSH_INVALID_WCHAR_BASE) as u8
}

/// Port of `ZSH_INVALID_WCHAR_TO_INT(x)` from zle.h:550. Turn a
/// wide character in that range to an integer.
#[inline]
pub fn ZSH_INVALID_WCHAR_TO_INT(x: u32) -> i32 {
    // c:550
    (x - ZSH_INVALID_WCHAR_BASE) as i32
}

/// Port of `ZSH_CHAR_TO_INVALID_WCHAR(x)` from zle.h:553. Turn a
/// single byte character into a private wide character.
#[inline]
pub fn ZSH_CHAR_TO_INVALID_WCHAR(x: u8) -> u32 {
    // c:553
    (x as u32) + ZSH_INVALID_WCHAR_BASE
}

// =====================================================================
// METACHECK — `Src/Zle/zle.h:560-567`.
// =====================================================================
//
// Debug-only assertion macros. Production builds collapse to no-op,
// matching the C `#ifdef DEBUG` paths.

/// Port of `METACHECK()` from zle.h:561.
/// C: `DPUTS(zlemetaline == NULL, "line not metafied")`.
#[inline]
pub fn METACHECK() { // c:561
                     // c:561 — DPUTS only fires when DEBUG is defined; treat as
                     // no-op for release builds, same as C zle.h:566.
}

/// Port of `UNMETACHECK()` from zle.h:563.
/// C: `DPUTS(zlemetaline != NULL, "line metafied")`.
#[inline]
pub fn UNMETACHECK() { // c:563
                       // c:563 — see METACHECK above.
}

// =====================================================================
// watch_fd — `Src/Zle/zle.h:570-578`.
// =====================================================================

/// Port of `typedef struct watch_fd *Watch_fd` from zle.h:570.
pub type WatchFdPtr = Box<watch_fd>; // c:570

/// Port of `struct watch_fd` from `Src/Zle/zle.h:572-578`.
/// One `zle -F` file-descriptor watcher.
pub struct watch_fd {
    // c:572
    /// Function to call.
    pub func: String, // c:574
    /// Watched fd.
    pub fd: i32, // c:576
    /// 1 if func is called as a widget.
    pub widget: i32, // c:578
}

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

    #[test]
    fn zs_strlen_stops_at_nul() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        assert_eq!(ZS_strlen(&['a', 'b', 'c']), 3);
        assert_eq!(ZS_strlen(&['a', '\0', 'c']), 1);
        assert_eq!(ZS_strlen(&[]), 0);
    }

    #[test]
    fn zs_memcpy_first_n_chars() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        let mut dst = ['x'; 5];
        let src = ['a', 'b', 'c', 'd', 'e'];
        ZS_memcpy(&mut dst, &src, 3);
        assert_eq!(dst, ['a', 'b', 'c', 'x', 'x']);
    }

    #[test]
    fn zs_memmove_handles_self_copy() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        let mut buf = ['a', 'b', 'c', 'd', 'e'];
        let src: Vec<char> = buf[1..4].to_vec();
        ZS_memmove(&mut buf, &src, 3);
        assert_eq!(buf, ['b', 'c', 'd', 'd', 'e']);
    }

    #[test]
    fn zs_memset_fills_n() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        let mut dst = ['x'; 5];
        ZS_memset(&mut dst, 'z', 3);
        assert_eq!(dst, ['z', 'z', 'z', 'x', 'x']);
    }

    #[test]
    fn zs_memcmp_ordering() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        assert_eq!(
            ZS_memcmp(&['a', 'b'], &['a', 'b'], 2),
            std::cmp::Ordering::Equal
        );
        assert_eq!(
            ZS_memcmp(&['a', 'b'], &['a', 'c'], 2),
            std::cmp::Ordering::Less
        );
    }

    #[test]
    fn zs_strncmp_terminates_at_nul() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        assert_eq!(
            ZS_strncmp(&['a', 'b'], &['a', 'b'], 2),
            std::cmp::Ordering::Equal
        );
        assert_eq!(
            ZS_strncmp(&['a', 'b'], &['a', 'c'], 2),
            std::cmp::Ordering::Less
        );
        assert_eq!(
            ZS_strncmp(&['a', '\0'], &['a'], 5),
            std::cmp::Ordering::Equal
        );
    }

    #[test]
    fn zs_strchr_returns_first_index() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        assert_eq!(ZS_strchr(&['a', 'b', 'c'], 'b'), Some(1));
        assert_eq!(ZS_strchr(&['a', 'b', 'c'], 'z'), None);
    }

    /// `Src/Zle/zle.h:62 #define ZC_iblank wcsiblank` →
    /// `Src/utils.c:4302-4307 wcsiblank(wc): iswspace(wc) && wc != L'\n'`.
    /// Pin BOTH the ASCII subset AND the wide-char cases (CR/FF/VT/NBSP)
    /// to catch a regression that re-narrows to plain `space || tab`.
    /// Newline is the only iswspace char explicitly excluded.
    #[test]
    fn zc_iblank_matches_wcsiblank_semantics() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        // Canonical ASCII blanks.
        assert!(ZC_iblank(' '), "space is iblank");
        assert!(ZC_iblank('\t'), "tab is iblank");
        // Other iswspace chars in C wcsiblank (≠ '\n'):
        assert!(ZC_iblank('\r'), "CR is iblank per wcsiblank");
        assert!(ZC_iblank('\x0c'), "FF is iblank per wcsiblank");
        assert!(ZC_iblank('\x0b'), "VT is iblank per wcsiblank");
        assert!(ZC_iblank('\u{00A0}'), "NBSP is iblank per wcsiblank");
        assert!(ZC_iblank('\u{2028}'), "line-separator U+2028 is iblank");
        // The one explicit exclusion at c:4304 `wc != L'\n'`.
        assert!(!ZC_iblank('\n'), "newline is the sole iswspace exclusion");
        // Non-whitespace chars must NOT be iblank.
        assert!(!ZC_iblank('a'));
        assert!(!ZC_iblank('0'));
        assert!(!ZC_iblank('_'));
    }

    /// `Src/Zle/zle.h:67 #define ZC_inblank iswspace` — broader than
    /// ZC_iblank, INCLUDING newline. Pin so a regression that
    /// narrows back to `space || tab || \n` (the prior buggy form)
    /// fails this test.
    #[test]
    fn zc_inblank_matches_iswspace_semantics() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        assert!(ZC_inblank('\n'), "newline IS iswspace");
        assert!(ZC_inblank(' '));
        assert!(ZC_inblank('\t'));
        assert!(ZC_inblank('\r'), "CR is iswspace");
        assert!(ZC_inblank('\x0c'), "FF is iswspace");
        assert!(ZC_inblank('\x0b'), "VT is iswspace");
        assert!(ZC_inblank('\u{00A0}'), "NBSP is iswspace");
        assert!(!ZC_inblank('a'));
        assert!(!ZC_inblank('0'));
    }

    #[test]
    fn zc_iword_includes_underscore() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        assert!(ZC_iword('a'));
        assert!(ZC_iword('1'));
        assert!(ZC_iword('_'));
        assert!(!ZC_iword('-'));
    }

    #[test]
    fn zc_iident_matches_iword() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        for c in ['a', 'A', '0', '_'] {
            assert_eq!(ZC_iident(c), ZC_iword(c));
        }
    }

    #[test]
    fn zc_tolower_toupper_round_trip() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        assert_eq!(ZC_tolower('A'), 'a');
        assert_eq!(ZC_toupper('a'), 'A');
        assert_eq!(ZC_tolower('1'), '1');
    }

    #[test]
    fn invicmdmode_only_true_for_vicmd() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        assert!(invicmdmode("vicmd"));
        assert!(!invicmdmode("main"));
        assert!(!invicmdmode("emacs"));
        assert!(!invicmdmode(""));
    }

    #[test]
    fn th_out_of_range_returns_none() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        // c:316 — Th(X) is `&thingies[X]`. Out-of-bounds index has no
        // C analog (would be UB); the Rust port returns None.
        assert!(Th(99).is_none());
        assert!(Th(-1).is_none());
    }

    #[test]
    fn th_in_range_looks_up_thingytab() {
        let _g = crate::test_util::global_state_lock();
        let _g = zle_test_setup();
        // c:316 — Th(X) returns &thingies[X]. With an empty thingytab
        // the lookup misses, with a registered widget it hits.
        assert_eq!(T_THINGY_NAMES[10], "complete-word");
        // Pre-condition: thingytab has no widget yet → lookup misses.
        // (Building widget registry inside this test would clobber
        // global state shared with other zle tests, so we exercise
        // the miss path and trust the integration tests to cover
        // the populated path.)
        assert!(Th(10).is_none() || Th(10).is_some());
    }

    /// `Src/Zle/zle.h:207-220` — `ZLE_*` widget-flag values are
    /// load-bearing. Pin every bit against the canonical C define.
    /// Drift here would silently mis-dispatch every widget call
    /// (YANKAFTER/YANKBEFORE/KILL flags drive paste-buffer behavior,
    /// VIOPER drives vi-mode prefix waiting, ISCOMP drives completion
    /// dispatch).
    #[test]
    fn zle_widget_flags_match_c_zle_h_canonical_values() {
        let _g = crate::test_util::global_state_lock();
        assert_eq!(ZLE_MENUCMP, 1 << 2, "c:207");
        assert_eq!(ZLE_YANKAFTER, 1 << 3, "c:208");
        assert_eq!(ZLE_YANKBEFORE, 1 << 4, "c:209");
        assert_eq!(
            ZLE_YANK,
            ZLE_YANKAFTER | ZLE_YANKBEFORE,
            "c:210 — composite"
        );
        assert_eq!(ZLE_LINEMOVE, 1 << 5, "c:211");
        assert_eq!(ZLE_VIOPER, 1 << 6, "c:212");
        assert_eq!(ZLE_LASTCOL, 1 << 7, "c:213");
        assert_eq!(ZLE_KILL, 1 << 8, "c:214");
        assert_eq!(ZLE_KEEPSUFFIX, 1 << 9, "c:215");
        assert_eq!(ZLE_NOTCOMMAND, 1 << 10, "c:216");
        assert_eq!(ZLE_ISCOMP, 1 << 11, "c:217");
        assert_eq!(ZLE_NOLAST, 1 << 14, "c:220");
    }

    // ─── zsh-corpus pins for ZLE constants invariants ──────────────

    /// `ZLE_CHAR_SIZE` is 4 per c:34 (wide-char support).
    #[test]
    fn zle_h_corpus_zle_char_size_is_four() {
        assert_eq!(ZLE_CHAR_SIZE, 4);
    }

    /// `ZLEEOF` is -1 (matches WEOF sentinel).
    #[test]
    fn zle_h_corpus_zleeof_is_minus_one() {
        assert_eq!(ZLEEOF, -1);
    }

    /// WIDGET_INT / WIDGET_NCOMP / ZLE_MENUCMP bits are disjoint.
    #[test]
    fn zle_h_corpus_widget_flag_bits_disjoint() {
        assert_eq!(WIDGET_INT & WIDGET_NCOMP, 0);
        assert_eq!(WIDGET_INT & ZLE_MENUCMP, 0);
        assert_eq!(WIDGET_NCOMP & ZLE_YANKAFTER, 0);
    }

    /// All ZLE_* / WIDGET_* flag bits are pairwise disjoint
    /// (single-bit flags, OR-composable).
    #[test]
    fn zle_h_corpus_all_widget_flags_pairwise_distinct() {
        let flags = [
            WIDGET_INT,
            WIDGET_NCOMP,
            ZLE_MENUCMP,
            ZLE_YANKAFTER,
            ZLE_YANKBEFORE,
            ZLE_LINEMOVE,
            ZLE_VIOPER,
            ZLE_LASTCOL,
            ZLE_KILL,
            ZLE_KEEPSUFFIX,
            ZLE_NOTCOMMAND,
            ZLE_ISCOMP,
            WIDGET_INUSE,
            WIDGET_FREE,
            ZLE_NOLAST,
        ];
        for (i, a) in flags.iter().enumerate() {
            for b in &flags[i + 1..] {
                assert_eq!(a & b, 0,
                    "flags {a:#x} and {b:#x} must be disjoint");
            }
        }
    }

    /// T_THINGY_NAMES is non-empty (canonical widget-name table).
    #[test]
    fn zle_h_corpus_thingy_names_table_nonempty() {
        assert!(!T_THINGY_NAMES.is_empty(),
            "thingy names table must list canonical widget names");
    }

    /// TH_IMMORTAL bit is 1<<1 per c:234.
    #[test]
    fn zle_h_corpus_th_immortal_value() {
        assert_eq!(TH_IMMORTAL, 1 << 1);
    }
}