@tishlang/tish 1.13.2 → 2.0.1

package/crates/tish_runtime/src/promise.rs

@@ -2,7 +2,28 @@
 //!
 //! The global `Promise` value is an **object** with a `__call` entry so the VM can
 //! invoke `Promise(executor)` like `new Promise(executor)` in JS. Static methods live
-//! on the same object (`resolve`, `reject`, `all`, `race`).
+//! on the same object (`resolve`, `reject`, `all`, `race`, `any`, `allSettled`, `spawn`).
+//!
+//! ## Concurrency model for race / any / allSettled / spawn
+//!
+//! `TishPromise::block_until_settled` is a *blocking* call. To wait on "whichever of N
+//! settles first" without serializing them, we spawn one OS thread per promise — each
+//! calls `block_until_settled` and forwards the result (with its index) to a shared
+//! `mpsc::channel`. The main thread reads from that channel:
+//!   - `race`  → first message wins (fulfilled or rejected).
+//!   - `any`   → first *fulfilled* message wins; collect rejections; if all reject →
+//!     `AggregateError` (array of reasons).
+//!   - `allSettled` → drain all N messages, sort by index, build `{status,value|reason}`.
+//!
+//! This requires `Value: Send`, which holds under the `send-values` feature (all handles
+//! become `Arc<Mutex<…>>`). The `send-values` feature is enabled in every build that has
+//! `http` (i.e. the shipped `full` binary). Without it (wasm / wasi) we fall back to a
+//! sequential path — correct but not concurrent.
+//!
+//! `Promise.spawn(fn)` runs `fn()` on a fresh OS thread and returns a Promise. This is
+//! the primitive for CPU-bound and GPU-bound work (e.g. `Promise.spawn(() => matmul(…))`
+//! from `tish:mlx` or `tish:metal`). The thread is an ordinary OS thread, not a tokio
+//! task, so it does not contend with the I/O runtime.
 
 use std::sync::mpsc;
 use std::sync::{Arc, Mutex};
@@ -32,6 +53,12 @@ impl TishPromise for ImmediateSettledPromise {
                 "Promise already settled or consumed".into(),
             )))
     }
+    /// Always already settled — return the result immediately without blocking.
+    fn try_settle(&self) -> Option<std::result::Result<Value, Value>> {
+        Some(self.slot.lock().unwrap().take().unwrap_or(
+            Err(Value::String("Promise already consumed".into())),
+        ))
+    }
 }
 
 fn fulfilled(v: Value) -> Value {
@@ -66,6 +93,30 @@ impl TishPromise for DeferredChannelPromise {
             )),
         }
     }
+
+    /// Non-blocking settle: if the executor has already called resolve/reject (the channel
+    /// has a message waiting), return it immediately. Returns `None` if the work is still
+    /// pending (channel empty). This lets `race`/`any`/`allSettled` handle already-settled
+    /// `new Promise(executor)` promises in input-order without spawning threads.
+    fn try_settle(&self) -> Option<std::result::Result<Value, Value>> {
+        let mut lock = self.rx.lock().unwrap();
+        match lock.as_ref() {
+            None => Some(Err(Value::String("Promise already consumed".into()))),
+            Some(rx) => match rx.try_recv() {
+                Ok(r) => {
+                    *lock = None; // consumed — block_until_settled would error now (correct)
+                    Some(r)
+                }
+                Err(mpsc::TryRecvError::Disconnected) => {
+                    *lock = None;
+                    Some(Err(Value::String(
+                        "Promise executor did not call resolve or reject".into(),
+                    )))
+                }
+                Err(mpsc::TryRecvError::Empty) => None, // still pending
+            },
+        }
+    }
 }
 
 /// `.then` / `.catch` chain: when awaited, settle the predecessor then optionally invoke a handler.
@@ -80,14 +131,14 @@ impl TishPromise for ThenPromise {
         match self.pred.block_until_settled() {
             Ok(v) => {
                 if let Some(Value::Function(f)) = &self.on_fulfilled {
-                    flatten_chain_out(f(&[v]))
+                    flatten_chain_out(f.call(&[v]))
                 } else {
                     Ok(v)
                 }
             }
             Err(e) => {
                 if let Some(Value::Function(f)) = &self.on_rejected {
-                    flatten_chain_out(f(&[e]))
+                    flatten_chain_out(f.call(&[e]))
                 } else {
                     Err(e)
                 }
@@ -137,24 +188,252 @@ pub fn promise_all(args: &[Value]) -> Value {
     }
 }
 
-/// `Promise.race(iterable)` — first element wins (blocking first promise if it is one).
-pub fn promise_race(args: &[Value]) -> Value {
+// ---------------------------------------------------------------------------
+// Concurrent combinators (race / any / allSettled) + Promise.spawn
+//
+// All three combinators need to wait on multiple promises concurrently. We
+// spawn one OS thread per promise; each thread calls block_until_settled and
+// sends (index, Result) to a shared mpsc channel on the calling thread.
+// ---------------------------------------------------------------------------
+
+/// Extract the array of items from `Promise.all/race/any/allSettled(array)`.
+fn combinator_items(args: &[Value]) -> Option<Vec<Value>> {
     match args.first() {
-        Some(Value::Array(arr)) => {
-            let borrowed = arr.borrow();
-            for v in borrowed.iter() {
-                if let Value::Promise(p) = v {
-                    return match p.block_until_settled() {
-                        Ok(x) => fulfilled(x),
-                        Err(e) => rejected(e),
-                    };
+        Some(Value::Array(arr)) => Some(arr.borrow().clone()),
+        _ => None,
+    }
+}
+
+/// Concurrent settlement channel for `race`/`any`/`allSettled`.
+///
+/// **Two-phase:** already-settled promises (`try_settle` returns `Some`) are handled
+/// inline in input-order before any threads are spawned. This gives deterministic
+/// JS-compatible ordering for already-settled inputs (e.g. `Promise.any([rej, ok, ok])`
+/// reliably returns the first fulfilled, not a random thread-schedule winner). Only
+/// genuinely-pending promises (e.g. from `Promise.spawn`) go to background threads,
+/// which is where concurrency matters.
+///
+/// Returns the receiving end of the channel plus the count of items it will send.
+#[cfg(feature = "send-values")]
+#[allow(clippy::type_complexity)]
+fn race_channel(
+    items: Vec<Value>,
+) -> (mpsc::Receiver<(usize, std::result::Result<Value, Value>)>, usize) {
+    let (tx, rx) = mpsc::channel::<(usize, std::result::Result<Value, Value>)>();
+    let mut count = 0usize;
+    for (i, v) in items.into_iter().enumerate() {
+        count += 1;
+        match v {
+            Value::Promise(ref p) => {
+                // Phase 1: try non-blocking settle (ImmediateSettledPromise, ThenPromise
+                // over immediate, etc.). These never need a thread; handle in order.
+                if let Some(r) = p.try_settle() {
+                    let _ = tx.send((i, r));
+                } else {
+                    // Phase 2: genuinely pending — spawn a thread.
+                    let p = Arc::clone(p);
+                    let tx = tx.clone();
+                    std::thread::spawn(move || {
+                        let r = p.block_until_settled();
+                        let _ = tx.send((i, r));
+                    });
+                }
+            }
+            other => {
+                let _ = tx.send((i, Ok(other)));
+            }
+        }
+    }
+    drop(tx); // closes the channel when all senders finish
+    (rx, count)
+}
+
+/// `Promise.race(iterable)` — first to settle (fulfilled or rejected) wins.
+/// Fixed: genuinely concurrent — the old impl only ever blocked on element 0.
+pub fn promise_race(args: &[Value]) -> Value {
+    let items = match combinator_items(args) {
+        Some(v) => v,
+        None => return fulfilled(args.first().cloned().unwrap_or(Value::Null)),
+    };
+    if items.is_empty() {
+        return rejected(Value::String("Promise.race: empty iterable".into()));
+    }
+    #[cfg(feature = "send-values")]
+    {
+        let (rx, _) = race_channel(items);
+        match rx.recv() {
+            Ok((_, Ok(v)))  => fulfilled(v),
+            Ok((_, Err(e))) => rejected(e),
+            Err(_)          => rejected(Value::String("Promise.race: all promises dropped".into())),
+        }
+    }
+    #[cfg(not(feature = "send-values"))]
+    {
+        // Sequential fallback (no threads): first item wins, whether promise or value.
+        for item in items {
+            return match item {
+                Value::Promise(p) => match p.block_until_settled() {
+                    Ok(v)  => fulfilled(v),
+                    Err(e) => rejected(e),
+                },
+                other => fulfilled(other),
+            };
+        }
+        rejected(Value::String("Promise.race: empty iterable".into()))
+    }
+}
+
+/// `Promise.any(iterable)` — resolves with the **first fulfilled** value.
+/// Rejects with an array of all rejection reasons only if every promise rejects
+/// (matching the JS `AggregateError.errors` convention — we return the array
+/// directly, not wrapped, to keep things simple without a full AggregateError class).
+pub fn promise_any(args: &[Value]) -> Value {
+    let items = match combinator_items(args) {
+        Some(v) => v,
+        None => return fulfilled(args.first().cloned().unwrap_or(Value::Null)),
+    };
+    if items.is_empty() {
+        return rejected(Value::Array(VmRef::new(vec![])));
+    }
+    let n = items.len();
+    #[cfg(feature = "send-values")]
+    {
+        let (rx, sent) = race_channel(items);
+        let mut errors = vec![Value::Null; n];
+        let mut reject_count = 0usize;
+        // Drain the channel: the first fulfilled result wins immediately; collect
+        // all rejections in case every promise rejects.
+        let mut received = 0usize;
+        while received < sent {
+            match rx.recv() {
+                Ok((_, Ok(v))) => return fulfilled(v), // first fulfillment wins
+                Ok((i, Err(e))) => {
+                    errors[i] = e;
+                    reject_count += 1;
+                    received += 1;
+                    if reject_count == sent {
+                        return rejected(Value::Array(VmRef::new(errors)));
+                    }
                 }
-                return fulfilled(v.clone());
+                Err(_) => break,
             }
-            Value::Null
         }
-        Some(v) => fulfilled(v.clone()),
-        None => Value::Null,
+        rejected(Value::Array(VmRef::new(errors)))
+    }
+    #[cfg(not(feature = "send-values"))]
+    {
+        // Sequential: return first fulfilled, or array of all rejections.
+        let mut errors = Vec::with_capacity(n);
+        for item in items {
+            match item {
+                Value::Promise(p) => match p.block_until_settled() {
+                    Ok(v)  => return fulfilled(v),
+                    Err(e) => errors.push(e),
+                },
+                other => return fulfilled(other),
+            }
+        }
+        rejected(Value::Array(VmRef::new(errors)))
+    }
+}
+
+/// `Promise.allSettled(iterable)` — always fulfills with an array of outcome objects.
+/// Each entry is `{status:"fulfilled",value:v}` or `{status:"rejected",reason:e}`.
+pub fn promise_all_settled(args: &[Value]) -> Value {
+    let items = match combinator_items(args) {
+        Some(v) => v,
+        None => return fulfilled(Value::Array(VmRef::new(vec![]))),
+    };
+    let n = items.len();
+    if n == 0 {
+        return fulfilled(Value::Array(VmRef::new(vec![])));
+    }
+
+    fn make_settled(r: std::result::Result<Value, Value>) -> Value {
+        let mut obj = ObjectMap::default();
+        match r {
+            Ok(v) => {
+                obj.insert(Arc::from("status"), Value::String("fulfilled".into()));
+                obj.insert(Arc::from("value"), v);
+            }
+            Err(e) => {
+                obj.insert(Arc::from("status"), Value::String("rejected".into()));
+                obj.insert(Arc::from("reason"), e);
+            }
+        }
+        Value::object(obj)
+    }
+
+    #[cfg(feature = "send-values")]
+    {
+        let (rx, _) = race_channel(items);
+        let mut results = vec![None::<std::result::Result<Value, Value>>; n];
+        while let Ok((i, r)) = rx.recv() {
+            results[i] = Some(r);
+        }
+        let out: Vec<Value> = results
+            .into_iter()
+            .map(|r| make_settled(r.unwrap_or(Err(Value::String("Promise dropped".into())))))
+            .collect();
+        fulfilled(Value::Array(VmRef::new(out)))
+    }
+    #[cfg(not(feature = "send-values"))]
+    {
+        let out: Vec<Value> = items.into_iter().map(|item| {
+            let r = match item {
+                Value::Promise(p) => p.block_until_settled(),
+                other => Ok(other),
+            };
+            make_settled(r)
+        }).collect();
+        fulfilled(Value::Array(VmRef::new(out)))
+    }
+}
+
+/// `Promise.spawn(fn)` — run `fn()` on a background OS thread and return a Promise
+/// that resolves with the function's return value. This is the key primitive for
+/// CPU-bound and GPU-bound work:
+///
+/// ```tish
+/// import { matmul } from 'tish:mlx'
+/// let result = await Promise.any([
+///     Promise.spawn(() => matmul(a, b, N)),   // MLX GPU path
+///     Promise.spawn(() => fallback(a, b, N)), // CPU fallback
+/// ])
+/// ```
+///
+/// Under `send-values` (the shipped `full` build), the function runs on a real OS
+/// thread; other threads can proceed concurrently. Without `send-values` (wasm/wasi),
+/// the function runs synchronously and the result is wrapped in an immediate promise.
+pub fn promise_spawn(args: &[Value]) -> Value {
+    let f = match args.first() {
+        Some(Value::Function(f)) => Arc::clone(f),
+        _ => return rejected(Value::String("Promise.spawn: expected a function argument".into())),
+    };
+    #[cfg(feature = "send-values")]
+    {
+        let (tx, rx) = mpsc::channel::<std::result::Result<Value, Value>>();
+        std::thread::spawn(move || {
+            // Wrap in catch_unwind so a panicking GPU/CPU kernel rejects the promise
+            // rather than aborting the whole process.
+            let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| f.call(&[])));
+            let _ = tx.send(match result {
+                Ok(v)  => Ok(v),
+                Err(_) => Err(Value::String("Promise.spawn: task panicked".into())),
+            });
+        });
+        Value::Promise(Arc::new(DeferredChannelPromise {
+            rx: Mutex::new(Some(rx)),
+        }))
+    }
+    #[cfg(not(feature = "send-values"))]
+    {
+        // No threads available (wasm/wasi): run synchronously, wrap result.
+        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| f.call(&[])));
+        match result {
+            Ok(v)  => fulfilled(v),
+            Err(_) => rejected(Value::String("Promise.spawn: task panicked".into())),
+        }
     }
 }
 
@@ -188,7 +467,7 @@ pub fn promise_object() -> Value {
                     Value::Null
                 }
             });
-            let _ = f(&[resolve, reject]);
+            let _ = f.call(&[resolve, reject]);
             Value::Promise(Arc::new(DeferredChannelPromise {
                 rx: Mutex::new(Some(rx)),
             }))
@@ -213,6 +492,18 @@ pub fn promise_object() -> Value {
         Arc::from("race"),
         Value::native(|args: &[Value]| promise_race(args)),
     );
+    map.insert(
+        Arc::from("any"),
+        Value::native(|args: &[Value]| promise_any(args)),
+    );
+    map.insert(
+        Arc::from("allSettled"),
+        Value::native(|args: &[Value]| promise_all_settled(args)),
+    );
+    map.insert(
+        Arc::from("spawn"),
+        Value::native(|args: &[Value]| promise_spawn(args)),
+    );
     Value::object(map)
 }
 
@@ -246,3 +537,22 @@ pub fn await_promise(v: Value) -> Value {
         v
     }
 }
+
+/// Like [`await_promise`], but a REJECTED promise surfaces as a catchable throw rather than
+/// silently yielding the rejection value. `await Promise.reject(x)` must throw `x` (so a
+/// surrounding `try/catch` fires) — matching interp/vm/cranelift/wasi. The codegen emits this
+/// variant (with `?`) wherever an error channel exists (inside a `try` body, or top-level `run()`),
+/// and falls back to [`await_promise`] only where there is no channel (a nested value-fn with no
+/// enclosing try), mirroring how `throw` is lowered.
+pub fn await_promise_throw(v: Value) -> Result<Value, Box<dyn std::error::Error>> {
+    if let Value::Promise(p) = v {
+        match p.block_until_settled() {
+            Ok(val) => Ok(val),
+            Err(rejection) => {
+                Err(Box::new(crate::TishError::Throw(rejection)) as Box<dyn std::error::Error>)
+            }
+        }
+    } else {
+        Ok(v)
+    }
+}

package/crates/tish_runtime/src/timers.rs

@@ -56,7 +56,7 @@ fn run_due_timers() {
         }
         for (id, callback, args, interval_ms) in due {
             if let Value::Function(f) = &callback {
-                let _ = f(&args);
+                let _ = f.call(&args);
             }
             if interval_ms > 0 {
                 re_register_interval(id, callback, args, interval_ms);
@@ -69,15 +69,21 @@ fn take_due_timers() -> Vec<(u64, Value, Vec<Value>, u64)> {
     let now = Instant::now();
     REGISTRY.with(|r| {
         let mut reg = r.borrow_mut();
-        let due: Vec<_> = reg
+        let mut due: Vec<_> = reg
             .iter()
             .filter(|(_, e)| e.due <= now)
-            .map(|(id, e)| (*id, e.callback.clone(), e.args.clone(), e.interval_ms))
+            .map(|(id, e)| (e.due, *id, e.callback.clone(), e.args.clone(), e.interval_ms))
             .collect();
-        for (id, _, _, _) in &due {
+        // Deterministic JS timer order: earliest `due` first, ties broken by registration order
+        // (the monotonic id). REGISTRY is a HashMap whose iteration order is otherwise arbitrary,
+        // which scrambled same-delay timers (e.g. three `setTimeout(_, 0)` firing out of order).
+        due.sort_by(|a, b| a.0.cmp(&b.0).then(a.1.cmp(&b.1)));
+        for (_, id, _, _, _) in &due {
             reg.remove(id);
         }
-        due
+        due.into_iter()
+            .map(|(_, id, cb, args, iv)| (id, cb, args, iv))
+            .collect()
     })
 }
 
@@ -100,7 +106,7 @@ fn re_register_interval(id: u64, callback: Value, args: Vec<Value>, interval_ms:
 /// Callbacks run when run_due_timers() is invoked (e.g. from ws.receiveTimeout poll loop).
 pub fn set_timeout(args: &[Value]) -> Value {
     let callback = args.first().cloned().unwrap_or(Value::Null);
-    let delay_ms = extract_num(args.get(1)).min(3600_000);
+    let delay_ms = extract_num(args.get(1)).min(3_600_000);
     let extra_args: Vec<Value> = args.iter().skip(2).cloned().collect();
     if matches!(callback, Value::Null) {
         return Value::Number(next_id() as f64);
@@ -124,7 +130,7 @@ pub fn set_timeout(args: &[Value]) -> Value {
 /// setInterval(callback, intervalMs, ...args) — first run after `intervalMs`, then repeats.
 pub fn set_interval(args: &[Value]) -> Value {
     let callback = args.first().cloned().unwrap_or(Value::Null);
-    let interval_ms = extract_num(args.get(1)).min(3600_000);
+    let interval_ms = extract_num(args.get(1)).min(3_600_000);
     let extra_args: Vec<Value> = args.iter().skip(2).cloned().collect();
     if matches!(callback, Value::Null) {
         return Value::Number(next_id() as f64);

package/crates/tish_runtime/src/tty.rs

@@ -0,0 +1,226 @@
+//! Interactive terminal I/O for Tish (issue #101), behind the `tty` feature.
+//!
+//! Exposes raw mode, the alternate screen, terminal size, and key/resize **events** via
+//! `crossterm`, so Tish programs can build interactive TUIs (menus, forms, live keyboard
+//! navigation). Imported as `import { … } from 'tish:tty'`.
+//!
+//! The Value-agnostic core (`size`, `is_tty`, `set_raw_mode`, `read_event`, …) returns plain
+//! Rust data so every backend — the bytecode VM (via the `tty_*` wrappers here) and the
+//! tree-walk interpreter (whose `Value` is a distinct type) — can build its own `Value` from
+//! the same logic. Errors surface as `null`/`false` rather than panicking.
+
+use std::io::{IsTerminal, Write};
+use std::sync::Arc;
+use std::time::Duration;
+
+use tishlang_core::{ObjectMap, Value};
+
+use crossterm::event::{self, Event, KeyCode, KeyEventKind, KeyModifiers};
+use crossterm::terminal;
+
+/// A terminal event delivered by [`read_event`]. Plain data so each backend maps it to its
+/// own `Value` object.
+pub enum TtyEvent {
+    Key {
+        key: String,
+        ctrl: bool,
+        alt: bool,
+        shift: bool,
+    },
+    Resize {
+        cols: u16,
+        rows: u16,
+    },
+    /// Mouse / focus / paste — reported generically so an input loop can ignore it.
+    Other,
+}
+
+// ── Value-agnostic core (shared by every backend) ───────────────────────────────────────
+
+/// Terminal `(cols, rows)`, or `None` if stdout is not connected to a terminal.
+///
+/// Gated on `stdout().is_terminal()` to match Node (`process.stdout.columns` is
+/// `undefined` when stdout is not a TTY). Without the gate, `crossterm::terminal::size()`
+/// can still succeed via the controlling terminal even when stdout is redirected — so a
+/// piped run (e.g. CI, `tish run x.tish | cat`) would report a bogus size instead of null.
+pub fn size() -> Option<(u16, u16)> {
+    if std::io::stdout().is_terminal() {
+        terminal::size().ok()
+    } else {
+        None
+    }
+}
+
+/// Whether stdin **and** stdout are connected to a terminal.
+pub fn is_tty() -> bool {
+    std::io::stdin().is_terminal() && std::io::stdout().is_terminal()
+}
+
+/// Enter (cbreak) or leave raw mode. Returns `true` on success.
+pub fn set_raw_mode(enabled: bool) -> bool {
+    if enabled {
+        terminal::enable_raw_mode().is_ok()
+    } else {
+        terminal::disable_raw_mode().is_ok()
+    }
+}
+
+/// Switch to / from the alternate screen buffer (full-screen apps).
+pub fn enter_alt_screen() -> bool {
+    let mut out = std::io::stdout();
+    let ok = crossterm::execute!(out, terminal::EnterAlternateScreen).is_ok();
+    let _ = out.flush();
+    ok
+}
+pub fn leave_alt_screen() -> bool {
+    let mut out = std::io::stdout();
+    let ok = crossterm::execute!(out, terminal::LeaveAlternateScreen).is_ok();
+    let _ = out.flush();
+    ok
+}
+
+/// Read the next terminal event. `timeout_ms = None` blocks; `Some(ms)` polls for `ms`
+/// milliseconds (0 = non-blocking) and returns `None` on timeout. Key-release events
+/// (Windows) are skipped, yielding `None`.
+pub fn read_event(timeout_ms: Option<u64>) -> Option<TtyEvent> {
+    if let Some(ms) = timeout_ms {
+        match event::poll(Duration::from_millis(ms)) {
+            Ok(true) => {}
+            _ => return None,
+        }
+    }
+    match event::read().ok()? {
+        Event::Key(k) => {
+            if k.kind == KeyEventKind::Release {
+                return None;
+            }
+            Some(TtyEvent::Key {
+                key: key_code_name(k.code),
+                ctrl: k.modifiers.contains(KeyModifiers::CONTROL),
+                alt: k.modifiers.contains(KeyModifiers::ALT),
+                shift: k.modifiers.contains(KeyModifiers::SHIFT),
+            })
+        }
+        Event::Resize(cols, rows) => Some(TtyEvent::Resize { cols, rows }),
+        _ => Some(TtyEvent::Other),
+    }
+}
+
+/// Read one line of **cooked** input from stdin (line mode), with the trailing newline
+/// stripped. Returns `None` at EOF. For raw key-by-key input use [`read_event`].
+pub fn read_line() -> Option<String> {
+    use std::io::BufRead;
+    let mut s = String::new();
+    match std::io::stdin().lock().read_line(&mut s) {
+        Ok(0) => None,
+        Ok(_) => {
+            while s.ends_with('\n') || s.ends_with('\r') {
+                s.pop();
+            }
+            Some(s)
+        }
+        Err(_) => None,
+    }
+}
+
+/// Normalize a crossterm key code to a stable JS-friendly name (`"a"`, `"Enter"`, `"Up"`,
+/// `"Esc"`, `"F1"`, …).
+fn key_code_name(code: KeyCode) -> String {
+    match code {
+        KeyCode::Char(c) => c.to_string(),
+        KeyCode::Enter => "Enter".into(),
+        KeyCode::Esc => "Esc".into(),
+        KeyCode::Backspace => "Backspace".into(),
+        KeyCode::Tab => "Tab".into(),
+        KeyCode::BackTab => "BackTab".into(),
+        KeyCode::Delete => "Delete".into(),
+        KeyCode::Insert => "Insert".into(),
+        KeyCode::Home => "Home".into(),
+        KeyCode::End => "End".into(),
+        KeyCode::PageUp => "PageUp".into(),
+        KeyCode::PageDown => "PageDown".into(),
+        KeyCode::Up => "Up".into(),
+        KeyCode::Down => "Down".into(),
+        KeyCode::Left => "Left".into(),
+        KeyCode::Right => "Right".into(),
+        KeyCode::F(n) => format!("F{n}"),
+        KeyCode::Null => "Null".into(),
+        other => format!("{other:?}"),
+    }
+}
+
+// ── core::Value wrappers for the bytecode VM / native runtime ────────────────────────────
+
+fn obj(pairs: Vec<(&str, Value)>) -> Value {
+    let mut m = ObjectMap::default();
+    for (k, v) in pairs {
+        m.insert(Arc::from(k), v);
+    }
+    Value::object(m)
+}
+
+/// `size()` → `{ cols, rows }` or `null`.
+pub fn tty_size(_args: &[Value]) -> Value {
+    match size() {
+        Some((cols, rows)) => obj(vec![
+            ("cols", Value::Number(cols as f64)),
+            ("rows", Value::Number(rows as f64)),
+        ]),
+        None => Value::Null,
+    }
+}
+
+/// `isTTY()` → bool.
+pub fn tty_is_tty(_args: &[Value]) -> Value {
+    Value::Bool(is_tty())
+}
+
+/// `setRawMode(enabled)` → bool (success).
+pub fn tty_set_raw_mode(args: &[Value]) -> Value {
+    Value::Bool(set_raw_mode(args.first().map(|v| v.is_truthy()).unwrap_or(false)))
+}
+
+/// `enterAltScreen()` / `leaveAltScreen()` → bool.
+pub fn tty_enter_alt_screen(_args: &[Value]) -> Value {
+    Value::Bool(enter_alt_screen())
+}
+pub fn tty_leave_alt_screen(_args: &[Value]) -> Value {
+    Value::Bool(leave_alt_screen())
+}
+
+/// `readLine()` → one line of cooked stdin (no trailing newline), or `null` at EOF.
+pub fn tty_read_line(_args: &[Value]) -> Value {
+    match read_line() {
+        Some(s) => Value::String(s.into()),
+        None => Value::Null,
+    }
+}
+
+/// `read(timeoutMs?)` → an event object (`{ type, … }`) or `null`.
+pub fn tty_read(args: &[Value]) -> Value {
+    let timeout = match args.first() {
+        Some(Value::Number(ms)) => Some(ms.max(0.0) as u64),
+        _ => None,
+    };
+    match read_event(timeout) {
+        Some(TtyEvent::Key {
+            key,
+            ctrl,
+            alt,
+            shift,
+        }) => obj(vec![
+            ("type", Value::String("key".into())),
+            ("key", Value::String(key.into())),
+            ("ctrl", Value::Bool(ctrl)),
+            ("alt", Value::Bool(alt)),
+            ("shift", Value::Bool(shift)),
+        ]),
+        Some(TtyEvent::Resize { cols, rows }) => obj(vec![
+            ("type", Value::String("resize".into())),
+            ("cols", Value::Number(cols as f64)),
+            ("rows", Value::Number(rows as f64)),
+        ]),
+        Some(TtyEvent::Other) => obj(vec![("type", Value::String("other".into()))]),
+        None => Value::Null,
+    }
+}