yggdrasil/
xterm_bridge.rs

1//! xterm.js 终端桥接：输出专用（无 stdin），配合 SSE 流式渲染容器 stdout/stderr。
2//!
3//! 镜像 `codemirror_bridge.rs` 范式：
4//! - `window.XtermTerminal` 是 IIFE 产物挂在 window 上的对象字面量（含 create 方法），
5//!   不是函数。用 `js_sys::Reflect::get` 做属性访问拿到模块对象，再 `unchecked_into`。
6//! - `XtermOptions` 是 class（非 interface），TS 擦除后存活，wasm 侧能 `new`。
7//! - `TerminalHandle` 持有实例 + onReady 闭包，Drop → destroy()。
8//!
9//! WASM-only：所有 extern 与 handle 都在 `#[cfg(target_arch = "wasm32")] mod wasm` 内，
10//! server 构建整体剥离。无跨目标共享数据（纯渲染层）。
11
12#[cfg(target_arch = "wasm32")]
13pub mod wasm {
14    use wasm_bindgen::prelude::*;
15    use wasm_bindgen::JsCast;
16
17    // —— window.XtermTerminal 模块对象 ——
18    //
19    // XtermTerminal 是 IIFE 产物挂在 window 上的对象字面量（含 create 方法），
20    // 不是函数。wasm-bindgen 对 `fn get_module() -> T` 形式的 extern 会生成
21    // `window.XtermTerminal()`（函数调用），会因 "not a function" 失败。
22    // 因此用 js_sys::Reflect::get 做属性访问拿到模块对象，再 unchecked_into。
23    #[wasm_bindgen]
24    extern "C" {
25        /// `window.XtermTerminal` 模块对象的 Rust 映射（IIFE 产物挂在 window 上的对象字面量）。
26        /// 不是函数——通过 [`get_module`] 用 Reflect::get 取属性而非 extern fn 调用拿到。
27        pub type XtermTerminalModule;
28
29        /// 调用 `XtermTerminal.create(containerId, opts)`。
30        /// 找不到容器返回 null（被 Option 捕获）；构造失败抛异常（被 catch 捕获）。
31        #[wasm_bindgen(method, catch)]
32        pub fn create(
33            this: &XtermTerminalModule,
34            container_id: &str,
35            opts: &XtermOptions,
36        ) -> Result<Option<TerminalInstance>, JsValue>;
37    }
38
39    /// 读取 `window.XtermTerminal`（IIFE 默认导出，顶层 var 即 window 属性）。
40    /// 用 Reflect::get 做属性访问——extern fn 形式会被 wasm-bindgen 编成函数调用。
41    ///
42    /// 用 unchecked_into 而非 dyn_into：XtermTerminal 是 JS 对象字面量，
43    /// 不是 wasm-bindgen 注册的构造函数实例，dyn_into 的 instanceof 检查必然失败。
44    /// unchecked_into 只做编译期类型标注，不做运行时校验
45    /// （Reflect.get 已保证拿到的是目标对象）。
46    pub fn get_module() -> XtermTerminalModule {
47        let window = web_sys::window().expect("no window");
48        let val = js_sys::Reflect::get(&window, &"XtermTerminal".into())
49            .expect("window.XtermTerminal missing");
50        val.unchecked_into::<XtermTerminalModule>()
51    }
52
53    // —— 终端实例（TerminalInstance）——
54    #[wasm_bindgen]
55    extern "C" {
56        /// `XtermTerminal.create` 返回的终端实例对象，承载 xterm.js Terminal。
57        pub type TerminalInstance;
58
59        /// 流式写入 stdout 块（SSE stdout 事件）。
60        #[wasm_bindgen(method, js_name = writeStdout)]
61        pub fn write_stdout(this: &TerminalInstance, data: &str);
62
63        /// 流式写入 stderr 块（SSE stderr 事件），红色显示。
64        #[wasm_bindgen(method, js_name = writeStderr)]
65        pub fn write_stderr(this: &TerminalInstance, data: &str);
66
67        /// 整段写入（轮询兜底路径）：清屏后重写 stdout + stderr。
68        #[wasm_bindgen(method, js_name = writeAll)]
69        pub fn write_all(this: &TerminalInstance, stdout: &str, stderr: &str);
70
71        /// 热切换主题（Catppuccin Latte/Mocha）。
72        #[wasm_bindgen(method, js_name = setTheme)]
73        pub fn set_theme(this: &TerminalInstance, theme: &str);
74
75        /// 重新计算列宽以适配容器（如父容器尺寸变化时调用）。
76        #[wasm_bindgen(method)]
77        pub fn fit(this: &TerminalInstance);
78
79        /// 清屏（新一轮运行前调用）。
80        #[wasm_bindgen(method)]
81        pub fn clear(this: &TerminalInstance);
82
83        /// 销毁终端，释放 JS 侧资源。
84        #[wasm_bindgen(method)]
85        pub fn destroy(this: &TerminalInstance);
86    }
87
88    // —— XtermOptions：用 builder 模式（setter）构造 JS 对象 ——
89    #[wasm_bindgen]
90    extern "C" {
91        /// 传给 `XtermTerminal.create` 的配置对象，对应 JS 侧的 XtermOptions。
92        /// 用 `new()` 创建空对象后通过 setter 链式设置字段。
93        pub type XtermOptions;
94
95        /// 构造一个空的 XtermOptions，随后用各 setter 填充。
96        #[wasm_bindgen(constructor)]
97        pub fn new() -> XtermOptions;
98
99        /// 主题：'light'（Catppuccin Latte）或 'dark'（Catppuccin Mocha）。
100        #[wasm_bindgen(method, setter, js_name = theme)]
101        pub fn set_theme(this: &XtermOptions, v: &str);
102
103        /// 字号（默认 13）。
104        #[wasm_bindgen(method, setter, js_name = fontSize)]
105        pub fn set_font_size(this: &XtermOptions, v: u32);
106
107        /// 终端就绪回调（构造末尾同步触发一次）。
108        #[wasm_bindgen(method, setter, js_name = onReady)]
109        pub fn set_on_ready(this: &XtermOptions, cb: &Closure<dyn FnMut()>);
110    }
111
112    /// 终端实例句柄：持有 instance + onReady 闭包，Drop 时销毁实例并释放闭包。
113    ///
114    /// 闭包字段 `_` 前缀表示仅用于保持生命周期——它被注入 JS 后，JS 侧持有
115    /// 函数引用；只要 [`TerminalHandle`] 存活，闭包就不会被回收。Drop 时随结构释放。
116    pub struct TerminalHandle {
117        instance: TerminalInstance,
118        _on_ready: Closure<dyn FnMut()>,
119    }
120
121    impl TerminalHandle {
122        /// 调用方须先把 on_ready set 进 XtermOptions，再 create，
123        /// 然后把返回的 instance + 同一 closure 一起传入 new。
124        pub fn new(instance: TerminalInstance, on_ready: Closure<dyn FnMut()>) -> Self {
125            Self {
126                instance,
127                _on_ready: on_ready,
128            }
129        }
130
131        /// 借用底层实例，供宿主调 writeStdout/writeStderr/setTheme 等。
132        pub fn instance(&self) -> &TerminalInstance {
133            &self.instance
134        }
135    }
136
137    impl Drop for TerminalHandle {
138        fn drop(&mut self) {
139            // 销毁 JS 侧终端；随后 _on_ready 字段释放，释放 wasm-bindgen 函数表槽位。
140            self.instance.destroy();
141        }
142    }
143}
144
145#[cfg(target_arch = "wasm32")]
146pub use wasm::*;
yggdrasil/xterm_bridge.rs

yggdrasil/
xterm_bridge.rs
