@tishlang/tish-lsp 3.0.0 → 3.2.2

package/crates/tish_compile/src/codegen.rs

@@ -652,7 +652,7 @@ pub fn compile_project_full_emit(
     if let Some(cap) = feature_cap {
         all_features.retain(|f| cap.contains(f));
     }
-    let rust = compile_with_native_modules_emit(
+    let rust = compile_with_native_modules_emit_exports(
         &merged.program,
         project_root,
         &all_features,
@@ -660,6 +660,7 @@ pub fn compile_project_full_emit(
         &native_build.native_init,
         optimize,
         emit_mode,
+        &merged.entry_exports,
     )?;
     Ok((rust, native_modules, all_features, native_build))
 }
@@ -728,6 +729,16 @@ fn run_type_check(program: &Program) -> Result<(), CompileError> {
     Ok(())
 }
 
+/// One entry-module export, as the `RustLib` surface sees it.
+struct RustLibExport {
+    /// The Rust local `run()` binds — for a re-export, the dependency's binding.
+    local_name: String,
+    /// The name the crate exposes (and the key in the export table).
+    exported_name: String,
+    /// Parameter count when the export names a `fn`; `None` for a value export.
+    arity: Option<usize>,
+}
+
 pub fn compile_with_native_modules_emit(
     program: &Program,
     project_root: Option<&Path>,
@@ -736,6 +747,33 @@ pub fn compile_with_native_modules_emit(
     native_init: &std::collections::HashMap<String, crate::resolve::NativeModuleInit>,
     optimize: bool,
     emit_mode: crate::NativeEmitMode,
+) -> Result<String, CompileError> {
+    compile_with_native_modules_emit_exports(
+        program,
+        project_root,
+        features,
+        native_modules,
+        native_init,
+        optimize,
+        emit_mode,
+        &[],
+    )
+}
+
+/// Like [`compile_with_native_modules_emit`], plus the entry module's exported
+/// `(local_name, exported_name)` pairs. Only [`crate::NativeEmitMode::RustLib`] reads them — they
+/// become the emitted crate's `pub fn` surface. Every other mode ignores the argument, which is
+/// why the plain entry point above can pass `&[]`.
+#[allow(clippy::too_many_arguments)]
+pub fn compile_with_native_modules_emit_exports(
+    program: &Program,
+    project_root: Option<&Path>,
+    features: &[String],
+    native_modules: &[crate::resolve::ResolvedNativeModule],
+    native_init: &std::collections::HashMap<String, crate::resolve::NativeModuleInit>,
+    optimize: bool,
+    emit_mode: crate::NativeEmitMode,
+    entry_exports: &[(String, String)],
 ) -> Result<String, CompileError> {
     // Per-compile thread-local state — the narrow-int/`fixed`/`i32` numeric profile and the import-
     // scheme registry — must not outlive THIS compile. Both persist on the thread, so a later compile
@@ -786,6 +824,7 @@ pub fn compile_with_native_modules_emit(
         };
     let mut g = Codegen::new_with_native_modules(project_root, features, map);
     g.emit_mode = emit_mode;
+    g.entry_exports = entry_exports.to_vec();
     g.has_native_ui_host = native_modules.iter().any(|m| {
         m.package_name == "tish-macos"
             || m.package_name == "tish-ios"
@@ -1018,6 +1057,9 @@ pub(crate) struct Codegen {
     features: std::collections::HashSet<String>,
     /// spec -> native init strategy (legacy adapter object vs generated `generated_native` wrapper)
     native_module_init: std::collections::HashMap<String, crate::resolve::NativeModuleInit>,
+    /// spec -> the `run()`-local holding that module's namespace object, bound ONCE in the preamble.
+    /// Building it is O(exports) — see `emit_native_namespace_preamble`.
+    native_ns_locals: std::collections::HashMap<String, String>,
     /// Typed native imports (`declare fun` + a native import): tish name -> its typed signature.
     /// A matching call emits a DIRECT `<crate>::name_typed(..)` instead of a boxed `value_call`.
     extern_fns: std::collections::HashMap<String, ExternSig>,
@@ -1242,6 +1284,10 @@ pub(crate) struct Codegen {
     /// closures it must not return a `Result` from a `Value`-returning closure.
     value_fn_depth: u32,
     emit_mode: crate::NativeEmitMode,
+    /// `RustLib` only: the entry module's `(local_name, exported_name)` pairs, as computed by
+    /// `merge_modules` for the JS bundle's trailing `export { … }`. Drives the `pub fn` wrappers.
+    /// Empty for every other emit mode.
+    entry_exports: Vec<(String, String)>,
     /// Scheme imports as `(scheme_name, absolute_path)`, in first-seen order. Populated (Gba mode)
     /// before the entry is emitted from the active [`crate::schemes`] registry; drives the
     /// `mod __scheme_<name>_<j> { … }` blocks and their per-scheme registration. The handle a tish
@@ -1292,6 +1338,7 @@ impl Codegen {
             string_charset: String::new(),
             features,
             native_module_init,
+            native_ns_locals: std::collections::HashMap::new(),
             extern_fns: std::collections::HashMap::new(),
             user_fn_returns: std::collections::HashMap::new(),
             async_context_stack: Vec::new(),
@@ -1359,6 +1406,7 @@ impl Codegen {
             program_fun_decl_names: std::collections::HashSet::new(),
             value_fn_depth: 0,
             emit_mode: crate::NativeEmitMode::DesktopBin,
+            entry_exports: Vec::new(),
             scheme_files: Vec::new(),
             has_native_ui_host: false,
             program_uses_document: false,
@@ -2044,6 +2092,48 @@ impl Codegen {
         }
     }
 
+    /// The Rust expression that CONSTRUCTS a native module's namespace object. O(exports): it inserts
+    /// every function the crate exports into a fresh map. Call it once per module, not once per import.
+    fn native_module_ns_ctor(init: &crate::resolve::NativeModuleInit) -> String {
+        match init {
+            crate::resolve::NativeModuleInit::Legacy {
+                crate_name,
+                export_fn,
+            } => format!("{}::{}()", crate_name, export_fn),
+            crate::resolve::NativeModuleInit::Generated { export_fn, .. } => {
+                format!("crate::generated_native::{}()", export_fn)
+            }
+        }
+    }
+
+    /// Bind every native module's namespace object to a `run()`-local, ONCE, before any import reads
+    /// from one.
+    ///
+    /// Each named import lowers to "get this key out of the module's namespace". Building that
+    /// namespace is O(exports) — a fresh `ObjectMap` with an `Arc<str>` key and a native closure per
+    /// exported function — so doing it at every import site is O(imports x exports): importing 68
+    /// names from a crate that exports 68 cost 4,624 allocations to bind 68 functions. On a GBA that
+    /// was measured at 3 seconds of black screen (`tish-gba/examples/bench-boot`), paid before the
+    /// program's first statement; `packages/engine.tish` there imports 117 symbols across two crates
+    /// and cost 4.3s. Hoisting makes it O(imports + exports).
+    ///
+    /// Emitted in sorted order so the generated Rust is byte-identical across builds (the map is a
+    /// `HashMap`, whose iteration order is not).
+    fn emit_native_namespace_preamble(&mut self) {
+        let mut specs: Vec<String> = self.native_module_init.keys().cloned().collect();
+        specs.sort();
+        for (i, spec) in specs.iter().enumerate() {
+            // Index rather than a sanitized spec: `cargo:a-b` and `cargo:a_b` sanitize to the same
+            // identifier, and silently binding one module's namespace under another's name would be a
+            // very quiet bug.
+            let local = format!("__tish_native_ns_{}", i);
+            let ctor = Self::native_module_ns_ctor(&self.native_module_init[spec]);
+            // A module can be resolved but have every one of its imports shadowed or unused.
+            self.writeln(&format!("#[allow(unused_variables)] let {} = {};", local, ctor));
+            self.native_ns_locals.insert(spec.clone(), local);
+        }
+    }
+
     /// Map native module spec to Rust init expression using resolved package.json modules.
     /// For built-in modules (tish:fs, tish:http, tish:process), use builtin_native_module_rust_init.
     fn native_module_rust_init(&self, spec: &str, export_name: &str) -> Option<String> {
@@ -2053,19 +2143,18 @@ impl Codegen {
         self.native_module_init.get(spec).map(|init| {
             // Native modules return a namespace object (like an ES module).
             // Named imports extract the field from that namespace: `import { foo } from "pkg"` → `ns.foo`.
-            let init_expr = match init {
-                crate::resolve::NativeModuleInit::Legacy {
-                    crate_name,
-                    export_fn,
-                } => format!("{}::{}()", crate_name, export_fn),
-                crate::resolve::NativeModuleInit::Generated { export_fn, .. } => {
-                    format!("crate::generated_native::{}()", export_fn)
-                }
-            };
-            format!(
-                "{{ let _ns = {}; match _ns {{ Value::Object(ref _o) => _o.borrow().strings.get({:?}).cloned().unwrap_or(Value::Null), _ => Value::Null }} }}",
-                init_expr, export_name
-            )
+            // Read it from the hoisted local when there is one; the inline constructor is the fallback
+            // for anything emitted outside `run()`'s preamble.
+            match self.native_ns_locals.get(spec) {
+                Some(local) => format!(
+                    "{{ match &{} {{ Value::Object(ref _o) => _o.borrow().strings.get({:?}).cloned().unwrap_or(Value::Null), _ => Value::Null }} }}",
+                    local, export_name
+                ),
+                None => format!(
+                    "{{ let _ns = {}; match _ns {{ Value::Object(ref _o) => _o.borrow().strings.get({:?}).cloned().unwrap_or(Value::Null), _ => Value::Null }} }}",
+                    Self::native_module_ns_ctor(init), export_name
+                ),
+            }
         })
     }
 
@@ -2098,6 +2187,7 @@ impl Codegen {
                     "realpath" | "realpathSync" => Some("Value::native(|args: &[Value]| tishlang_runtime::fs_ext::realpath(args))"),
                     "readlink" | "readlinkSync" => Some("Value::native(|args: &[Value]| tishlang_runtime::fs_ext::readlink(args))"),
                     "truncate" | "truncateSync" => Some("Value::native(|args: &[Value]| tishlang_runtime::fs_ext::truncate(args))"),
+                    "chmod" | "chmodSync" => Some("Value::native(|args: &[Value]| tishlang_runtime::fs_ext::chmod(args))"),
                     "mkdtemp" | "mkdtempSync" => Some("Value::native(|args: &[Value]| tishlang_runtime::fs_ext::mkdtemp(args))"),
                     "cp" | "cpSync" => Some("Value::native(|args: &[Value]| tishlang_runtime::fs_ext::cp(args))"),
                     "access" | "accessSync" => Some("Value::native(|args: &[Value]| tishlang_runtime::fs_ext::access(args))"),
@@ -2121,6 +2211,7 @@ impl Codegen {
                     "realpath" => Some("Value::native(|args: &[Value]| tishlang_runtime::fs_ext::realpath_promise(args))"),
                     "readlink" => Some("Value::native(|args: &[Value]| tishlang_runtime::fs_ext::readlink_promise(args))"),
                     "truncate" => Some("Value::native(|args: &[Value]| tishlang_runtime::fs_ext::truncate_promise(args))"),
+                    "chmod" => Some("Value::native(|args: &[Value]| tishlang_runtime::fs_ext::chmod_promise(args))"),
                     "mkdtemp" => Some("Value::native(|args: &[Value]| tishlang_runtime::fs_ext::mkdtemp_promise(args))"),
                     "cp" => Some("Value::native(|args: &[Value]| tishlang_runtime::fs_ext::cp_promise(args))"),
                     "access" => Some("Value::native(|args: &[Value]| tishlang_runtime::fs_ext::access_promise(args))"),
@@ -2155,9 +2246,20 @@ impl Codegen {
                     "execFile" => Some("Value::native(|args: &[Value]| tish_process_exec_file(args))"),
                     "execCapture" => Some("Value::native(|args: &[Value]| tish_process_exec_capture(args))"),
                     "execFileCapture" => Some("Value::native(|args: &[Value]| tish_process_exec_file_capture(args))"),
+                    "spawn" => Some("Value::native(|args: &[Value]| tishlang_runtime::process_spawn(args))"),
+                    "readStdout" => Some("Value::native(|args: &[Value]| tishlang_runtime::process_read_stdout(args))"),
+                    "readStderr" => Some("Value::native(|args: &[Value]| tishlang_runtime::process_read_stderr(args))"),
+                    "writeStdin" => Some("Value::native(|args: &[Value]| tishlang_runtime::process_write_stdin(args))"),
+                    "closeStdin" => Some("Value::native(|args: &[Value]| tishlang_runtime::process_close_stdin(args))"),
+                    "wait" => Some("Value::native(|args: &[Value]| tishlang_runtime::process_wait(args))"),
+                    "kill" => Some("Value::native(|args: &[Value]| tishlang_runtime::process_kill(args))"),
+                    "pid" => Some("Value::native(|args: &[Value]| tishlang_runtime::process_pid(args))"),
                     "argv" => Some("Value::Array(VmRef::new(std::env::args().map(|s| Value::String(s.into())).collect()))"),
                     "env" => Some("Value::object(std::env::vars().map(|(k,v)| (Arc::from(k.as_str()), Value::String(v.into()))).collect())"),
-                    "process" => Some("{ let mut m = ObjectMap::default(); m.insert(Arc::from(\"exit\"), Value::native(|args: &[Value]| tish_process_exit(args))); m.insert(Arc::from(\"cwd\"), Value::native(|args: &[Value]| tish_process_cwd(args))); m.insert(Arc::from(\"exec\"), Value::native(|args: &[Value]| tish_process_exec(args))); m.insert(Arc::from(\"execFile\"), Value::native(|args: &[Value]| tish_process_exec_file(args))); m.insert(Arc::from(\"execCapture\"), Value::native(|args: &[Value]| tish_process_exec_capture(args))); m.insert(Arc::from(\"execFileCapture\"), Value::native(|args: &[Value]| tish_process_exec_file_capture(args))); m.insert(Arc::from(\"argv\"), Value::Array(VmRef::new(std::env::args().map(|s| Value::String(s.into())).collect()))); m.insert(Arc::from(\"env\"), Value::object(std::env::vars().map(|(k,v)| (Arc::from(k.as_str()), Value::String(v.into()))).collect::<ObjectMap>())); Value::object(m) }"),
+                    // Node-style platform string so `process.platform` reads identically on the JS
+                    // target (Node's real global) and native (this): macos->darwin, windows->win32.
+                    "platform" => Some("Value::String(match std::env::consts::OS { \"macos\" => \"darwin\", \"windows\" => \"win32\", o => o }.into())"),
+                    "process" => Some("{ let mut m = ObjectMap::default(); m.insert(Arc::from(\"exit\"), Value::native(|args: &[Value]| tish_process_exit(args))); m.insert(Arc::from(\"cwd\"), Value::native(|args: &[Value]| tish_process_cwd(args))); m.insert(Arc::from(\"exec\"), Value::native(|args: &[Value]| tish_process_exec(args))); m.insert(Arc::from(\"execFile\"), Value::native(|args: &[Value]| tish_process_exec_file(args))); m.insert(Arc::from(\"execCapture\"), Value::native(|args: &[Value]| tish_process_exec_capture(args))); m.insert(Arc::from(\"execFileCapture\"), Value::native(|args: &[Value]| tish_process_exec_file_capture(args))); m.insert(Arc::from(\"argv\"), Value::Array(VmRef::new(std::env::args().map(|s| Value::String(s.into())).collect()))); m.insert(Arc::from(\"env\"), Value::object(std::env::vars().map(|(k,v)| (Arc::from(k.as_str()), Value::String(v.into()))).collect::<ObjectMap>())); m.insert(Arc::from(\"platform\"), Value::String(match std::env::consts::OS { \"macos\" => \"darwin\", \"windows\" => \"win32\", o => o }.into())); Value::object(m) }"),
                     _ => None,
                 },
             "tish:ws" if self.has_feature("ws") => match export_name {
@@ -2187,6 +2289,37 @@ impl Codegen {
                     "pid" => Some("Value::native(|args: &[Value]| tishlang_runtime::pty_pid(args))"),
                     _ => None,
                 },
+            "tish:net" if self.has_feature("net") => match export_name {
+                    "connect" => Some("Value::native(|args: &[Value]| tishlang_runtime::net_connect(args))"),
+                    "read" => Some("Value::native(|args: &[Value]| tishlang_runtime::net_read(args))"),
+                    "write" => Some("Value::native(|args: &[Value]| tishlang_runtime::net_write(args))"),
+                    "close" => Some("Value::native(|args: &[Value]| tishlang_runtime::net_close(args))"),
+                    "listen" => Some("Value::native(|args: &[Value]| tishlang_runtime::net_listen(args))"),
+                    "accept" => Some("Value::native(|args: &[Value]| tishlang_runtime::net_accept(args))"),
+                    "probe" => Some("Value::native(|args: &[Value]| tishlang_runtime::net_probe(args))"),
+                    "sleep" => Some("Value::native(|args: &[Value]| tishlang_runtime::net_sleep(args))"),
+                    _ => None,
+                },
+            "tish:encoding" if self.has_feature("encoding") => match export_name {
+                    "base64Encode" => Some("Value::native(|args: &[Value]| tishlang_runtime::base64_encode(args))"),
+                    "base64Decode" => Some("Value::native(|args: &[Value]| tishlang_runtime::base64_decode(args))"),
+                    "base64UrlEncode" => Some("Value::native(|args: &[Value]| tishlang_runtime::base64_url_encode(args))"),
+                    "base64UrlDecode" => Some("Value::native(|args: &[Value]| tishlang_runtime::base64_url_decode(args))"),
+                    "utf8Decode" => Some("Value::native(|args: &[Value]| tishlang_runtime::utf8_decode(args))"),
+                    "utf8Encode" => Some("Value::native(|args: &[Value]| tishlang_runtime::utf8_encode(args))"),
+                    _ => None,
+                },
+            "tish:crypto" if self.has_feature("crypto") => match export_name {
+                    "sha256" => Some("Value::native(|args: &[Value]| tishlang_runtime::sha256(args))"),
+                    "sha256Hex" => Some("Value::native(|args: &[Value]| tishlang_runtime::sha256_hex(args))"),
+                    "randomBytes" => Some("Value::native(|args: &[Value]| tishlang_runtime::random_bytes(args))"),
+                    _ => None,
+                },
+            "tish:zip" if self.has_feature("zip") => match export_name {
+                    "extract" => Some("Value::native(|args: &[Value]| tishlang_runtime::zip_extract(args))"),
+                    "entries" => Some("Value::native(|args: &[Value]| tishlang_runtime::zip_entries(args))"),
+                    _ => None,
+                },
             _ => return None,
         };
         init.map(String::from)
@@ -2196,7 +2329,8 @@ impl Codegen {
         if self.features.contains("full") {
             matches!(
                 name,
-                "http" | "timers" | "fs" | "process" | "regex" | "ws" | "tty" | "pty"
+                "http" | "timers" | "fs" | "process" | "regex" | "ws" | "tty" | "pty" | "net"
+                    | "encoding" | "crypto" | "zip"
             )
         } else {
             self.features.contains(name)
@@ -2849,6 +2983,14 @@ impl Codegen {
             self.write("use std::rc::Rc;\n");
             self.write("use std::sync::Arc;\n");
         }
+        // RustLib: re-export the runtime prelude rather than importing it privately, so the crate's
+        // public API is self-contained — a consumer gets `Value` (and `ObjectMap` / `PropMap` /
+        // `VmRef`) from THIS crate and cannot version-skew them against a separate `tishlang_runtime`
+        // dependency of their own. Also avoids a duplicate-import error, since `Value` is already in
+        // this list and could not be re-exported a second time at the crate root.
+        if self.emit_mode == crate::NativeEmitMode::RustLib {
+            self.write("pub ");
+        }
         self.write("use tishlang_runtime::{console_debug as tish_console_debug, console_info as tish_console_info, console_log as tish_console_log, console_warn as tish_console_warn, console_error as tish_console_error, boolean as tish_boolean, decode_uri as tish_decode_uri, encode_uri as tish_encode_uri, encode_uri_component as tish_encode_uri_component, decode_uri_component as tish_decode_uri_component, string_escape_html_impl as tish_escape_html, in_operator as tish_in_operator, is_finite as tish_is_finite, is_nan as tish_is_nan, json_parse as tish_json_parse, json_stringify as tish_json_stringify, math_abs as tish_math_abs, math_ceil as tish_math_ceil, math_floor as tish_math_floor, math_max as tish_math_max, math_min as tish_math_min, math_round as tish_math_round, math_sqrt as tish_math_sqrt, parse_float as tish_parse_float, parse_int as tish_parse_int, math_random as tish_math_random, math_pow as tish_math_pow, math_sin as tish_math_sin, math_cos as tish_math_cos, math_tan as tish_math_tan, math_log as tish_math_log, math_exp as tish_math_exp, math_sign as tish_math_sign, math_trunc as tish_math_trunc, math_imul as tish_math_imul, math_sinh as tish_math_sinh, math_cosh as tish_math_cosh, math_tanh as tish_math_tanh, math_asinh as tish_math_asinh, math_acosh as tish_math_acosh, math_atanh as tish_math_atanh, math_cbrt as tish_math_cbrt, math_log2 as tish_math_log2, math_log10 as tish_math_log10, math_expm1 as tish_math_expm1, math_log1p as tish_math_log1p, math_clz32 as tish_math_clz32, math_fround as tish_math_fround, math_hypot as tish_math_hypot, math_atan2 as tish_math_atan2, math_asin as tish_math_asin, math_acos as tish_math_acos, math_atan as tish_math_atan, array_is_array as tish_array_is_array, array_of as tish_array_of, array_from as tish_array_from, object_is as tish_object_is, object_has_own as tish_object_has_own, structured_clone as tish_structured_clone, array_construct as tish_array_construct, string_from_char_code as tish_string_from_char_code, string_convert as tish_string_convert, number_convert as tish_number_convert, number_is_integer as tish_number_is_integer, number_is_safe_integer as tish_number_is_safe_integer, number_is_nan as tish_number_is_nan, number_is_finite as tish_number_is_finite, object_assign as tish_object_assign, object_freeze as tish_object_freeze, object_is_frozen as tish_object_is_frozen, object_keys as tish_object_keys, object_values as tish_object_values, object_entries as tish_object_entries, object_from_entries as tish_object_from_entries, symbol_object as tish_symbol_object, tish_construct, tish_error_constructor, tish_date_constructor, tish_set_constructor, tish_map_constructor, map_get as tish_map_get, map_has as tish_map_has, map_set as tish_map_set, map_values as tish_map_values, tish_float64_array_constructor, tish_float32_array_constructor, tish_int8_array_constructor, tish_uint8_array_constructor, tish_uint8_clamped_array_constructor, tish_int16_array_constructor, tish_uint16_array_constructor, tish_int32_array_constructor, tish_uint32_array_constructor, tish_audio_context_constructor, ObjectMap, ObjectData, PropMap, TishError, Value, VmRef};\n");
         if self.program_has_jsx {
             self.write("use tishlang_ui::{fragment_value, install_thread_local_host, native_create_root, native_use_state, ui_h, ui_text, HeadlessHost};\n");
@@ -2964,6 +3106,9 @@ impl Codegen {
             self.writeln("}");
             self.writeln("");
         }
+        if self.emit_mode == crate::NativeEmitMode::RustLib {
+            self.emit_rust_lib_surface(program)?;
+        }
         // M5 (default-on via native_opts_enabled; TISH_NATIVE_OPT=0 opts out): emit a parallel
         // native `fn f_native` for each eligible top-level numeric fn at top level; direct calls
         // route to it in emit_typed_expr.
@@ -3088,6 +3233,9 @@ impl Codegen {
         }
         self.indent += 1;
 
+        // Before anything else: one namespace object per native module, shared by all of its imports.
+        self.emit_native_namespace_preamble();
+
         // Initialize builtins
         self.writeln("let mut console = Value::object(ObjectMap::from([");
         self.indent += 1;
@@ -3331,6 +3479,9 @@ impl Codegen {
             self.indent -= 1;
             self.writeln("}");
             self.writeln("p.insert(Arc::from(\"env\"), Value::object(env_obj));");
+            // Node-style platform string (macos->darwin, windows->win32) so bare `process.platform`
+            // matches the JS target's Node global and the named `tish:process` export.
+            self.writeln("p.insert(Arc::from(\"platform\"), Value::String(match std::env::consts::OS { \"macos\" => \"darwin\", \"windows\" => \"win32\", o => o }.into()));");
             self.writeln("p");
             self.indent -= 1;
             self.writeln("});");
@@ -3456,6 +3607,29 @@ impl Codegen {
             self.writeln("tishlang_runtime::drain_timers();");
         }
 
+        // RustLib: hand the entry module's exported bindings to the thread-local table before
+        // `run()`'s frame drops. The bindings are ordinary `Value` locals; cloning one clones an
+        // `Rc`, so the closure — and every module-level cell it captured — stays alive and shared.
+        // That is what makes module state survive between `pub fn` calls (and stay mutable through
+        // `clear*`-style reassignment, since captures are `VmRef` cells, not copies).
+        if self.emit_mode == crate::NativeEmitMode::RustLib {
+            let pairs: Vec<String> = self
+                .rust_lib_exports(program)
+                .iter()
+                .map(|e| {
+                    format!(
+                        "({:?}, {}.clone())",
+                        e.exported_name,
+                        Self::escape_ident(&e.local_name)
+                    )
+                })
+                .collect();
+            self.writeln(&format!(
+                "__tish_publish_exports(::std::vec![{}]);",
+                pairs.join(", ")
+            ));
+        }
+
         self.writeln("Ok(())");
         self.indent -= 1;
         self.writeln("}");
@@ -3484,6 +3658,191 @@ impl Codegen {
         Ok(())
     }
 
+    /// The entry module's exports, paired with the arity of the `fn` each names (if it names one).
+    /// `merge_modules` unwraps `export` into plain top-level declarations and records the
+    /// `(local, exported)` pairs — including through `export { … } from './x.tish'` re-exports,
+    /// which resolve to the dependency's local binding — so a barrel module still yields the full
+    /// surface. Sorted for deterministic output.
+    fn rust_lib_exports(&self, program: &Program) -> Vec<RustLibExport> {
+        let mut arities: std::collections::HashMap<&str, usize> =
+            std::collections::HashMap::new();
+        for stmt in &program.statements {
+            if let Statement::FunDecl { name, params, .. } = stmt {
+                arities.insert(name.as_ref(), params.len());
+            }
+        }
+        let mut out: Vec<RustLibExport> = self
+            .entry_exports
+            .iter()
+            .map(|(local, exported)| RustLibExport {
+                local_name: local.clone(),
+                exported_name: exported.clone(),
+                arity: arities.get(local.as_str()).copied(),
+            })
+            .collect();
+        out.sort_by(|a, b| a.exported_name.cmp(&b.exported_name));
+        out
+    }
+
+    /// Emit the `RustLib` public surface: the thread-local module instance, the lazy `ensure_init`,
+    /// and one `pub fn` per entry export.
+    ///
+    /// The module body itself is the ordinary `run()` — this only changes *when* it runs and what
+    /// outlives it. Storage is `thread_local!` rather than a global because `Value` is `!Send`
+    /// unless the `send-values` feature is on (it follows `http`), so a `static` would not compile
+    /// for the common configuration. Per-thread instances also match how a consumer uses this:
+    /// register into the module's registries, then call it, on one thread.
+    fn emit_rust_lib_surface(&mut self, program: &Program) -> Result<(), CompileError> {
+        if self.is_async {
+            return Err(CompileError::new(
+                "--target rust --emit lib: the entry module has top-level `await`. A library has \
+                 no runtime to drive it — move the async work into an exported function."
+                    .to_string(),
+                None,
+            ));
+        }
+        let exports = self.rust_lib_exports(program);
+        if exports.is_empty() {
+            return Err(CompileError::new(
+                "--target rust --emit lib: the entry module exports nothing, so the crate would \
+                 have no public API. Add `export fn …` to the entry module."
+                    .to_string(),
+                None,
+            ));
+        }
+        // Only `export fn` is supported. A value export has no arity, and its Rust local is not
+        // necessarily a `Value` to publish (a `const` string lowers to `&str`), so it cannot be
+        // handed to the export table the way a closure can. Say so instead of emitting a getter
+        // that would always read back null.
+        let non_fn: Vec<&str> = exports
+            .iter()
+            .filter(|e| e.arity.is_none())
+            .map(|e| e.exported_name.as_str())
+            .collect();
+        if !non_fn.is_empty() {
+            return Err(CompileError::new(
+                format!(
+                    "--target rust --emit lib: only `export fn` can cross the crate boundary, but \
+                     the entry module also exports the value(s) `{}`. Wrap each in an exported \
+                     function (`export fn {}() {{ … }}`).",
+                    non_fn.join("`, `"),
+                    non_fn[0]
+                ),
+                None,
+            ));
+        }
+
+        self.writeln("// ── Tish library surface ──────────────────────────────────────────────");
+        // `Value` and friends are already re-exported by the (pub) runtime prelude above; this adds
+        // the whole runtime for consumers that need more than the prelude carries.
+        self.writeln("pub use tishlang_runtime as runtime;");
+        self.writeln("");
+        self.writeln("thread_local! {");
+        self.indent += 1;
+        self.writeln(
+            "static __TISH_MODULE: ::std::cell::RefCell<::std::option::Option<::std::collections::HashMap<&'static str, Value>>> =",
+        );
+        self.writeln("    ::std::cell::RefCell::new(::std::option::Option::None);");
+        self.indent -= 1;
+        self.writeln("}");
+        self.writeln("");
+        self.writeln("/// Called once from the tail of `run()` with the entry module's exports.");
+        self.writeln("fn __tish_publish_exports(pairs: ::std::vec::Vec<(&'static str, Value)>) {");
+        self.indent += 1;
+        self.writeln("__TISH_MODULE.with(|m| {");
+        self.writeln("    *m.borrow_mut() = ::std::option::Option::Some(pairs.into_iter().collect());");
+        self.writeln("});");
+        self.indent -= 1;
+        self.writeln("}");
+        self.writeln("");
+        self.writeln("/// Run the module body exactly once per thread, before the first export call.");
+        self.writeln("fn __tish_ensure_init() {");
+        self.indent += 1;
+        self.writeln("// Park an empty table BEFORE running the body: that makes init non-reentrant");
+        self.writeln("// (an export reached while the module is still initialising sees an empty");
+        self.writeln("// table and returns null, rather than recursing forever).");
+        self.writeln("let fresh = __TISH_MODULE.with(|m| {");
+        self.writeln("    let mut b = m.borrow_mut();");
+        self.writeln("    if b.is_some() { return false; }");
+        self.writeln("    *b = ::std::option::Option::Some(::std::collections::HashMap::new());");
+        self.writeln("    true");
+        self.writeln("});");
+        self.writeln("if fresh {");
+        self.writeln("    // A module whose top level fails cannot be recovered from here: every");
+        self.writeln("    // export would observe half-initialised state.");
+        self.writeln("    run().unwrap_or_else(|e| panic!(\"tish module initialisation failed: {}\", e));");
+        self.writeln("}");
+        self.indent -= 1;
+        self.writeln("}");
+        self.writeln("");
+        self.writeln("/// Clone an export out of the table. The borrow is released before the value is");
+        self.writeln("/// used, because an export is free to call back into another export.");
+        self.writeln("fn __tish_export(name: &str) -> Value {");
+        self.indent += 1;
+        self.writeln("__tish_ensure_init();");
+        self.writeln("__TISH_MODULE.with(|m| {");
+        self.writeln("    m.borrow().as_ref().and_then(|t| t.get(name).cloned()).unwrap_or(Value::Null)");
+        self.writeln("})");
+        self.indent -= 1;
+        self.writeln("}");
+        self.writeln("");
+        self.writeln("thread_local! {");
+        self.writeln("    static __TISH_LAST_THROW: ::std::cell::RefCell<Value> = ::std::cell::RefCell::new(Value::Null);");
+        self.writeln("}");
+        self.writeln("");
+        self.writeln("/// The value thrown by the most recent export call, or null if it completed normally.");
+        self.writeln("///");
+        self.writeln("/// A `pub fn … -> Value` has no error channel, so a throw that escapes an export is drained");
+        self.writeln("/// and recorded here rather than left parked. Reading it is the way to tell \"returned null\"");
+        self.writeln("/// from \"threw\".");
+        self.writeln("pub fn tish_last_throw() -> Value {");
+        self.indent += 1;
+        self.writeln("__TISH_LAST_THROW.with(|t| t.borrow().clone())");
+        self.indent -= 1;
+        self.writeln("}");
+        self.writeln("");
+        self.writeln("fn __tish_call_export(name: &str, args: &[Value]) -> Value {");
+        self.indent += 1;
+        self.writeln("// A throw is PARKED for the next checkpoint rather than unwound (#303). Across a `pub fn`");
+        self.writeln("// boundary there is no Tish frame to surface it in, so a parked throw would sit latched and");
+        self.writeln("// every LATER call would bail at its own checkpoint and silently return null — one bad call");
+        self.writeln("// bricking the module for the rest of the process. A host hits this simply by reading a");
+        self.writeln("// property off a null the runtime handed it. So: enter clean, leave clean.");
+        self.writeln("let _ = tishlang_runtime::take_pending_throw();");
+        self.writeln("let out = match __tish_export(name) {");
+        self.writeln("    Value::Function(f) => f.call(args),");
+        self.writeln("    other => other,");
+        self.writeln("};");
+        self.writeln("let thrown = tishlang_runtime::take_pending_throw().unwrap_or(Value::Null);");
+        self.writeln("__TISH_LAST_THROW.with(|t| *t.borrow_mut() = thrown);");
+        self.writeln("out");
+        self.indent -= 1;
+        self.writeln("}");
+        self.writeln("");
+
+        for e in &exports {
+            // Checked above: every remaining export is a `fn`, so the arity is present.
+            let n = e.arity.unwrap_or(0);
+            let params: Vec<String> = (0..n).map(|i| format!("a{}: Value", i)).collect();
+            let args: Vec<String> = (0..n).map(|i| format!("a{}", i)).collect();
+            self.writeln(&format!(
+                "pub fn {}({}) -> Value {{",
+                Self::escape_ident(&e.exported_name),
+                params.join(", ")
+            ));
+            self.indent += 1;
+            self.writeln(&format!(
+                "__tish_call_export({:?}, &[{}])",
+                e.exported_name,
+                args.join(", ")
+            ));
+            self.indent -= 1;
+            self.writeln("}");
+        }
+        self.writeln("");
+        Ok(())
+    }
+
     /// Emit an expression in **statement position** (its value is discarded). For a native
     /// assignment this emits only the side-effect — NOT the boxed `Value::Number(..)` that the
     /// expression form returns (JS "assignment yields its value"). In a hot loop that boxed
@@ -3612,9 +3971,17 @@ impl Codegen {
                         let escaped = Self::escape_ident(name.as_ref());
                         return Ok(format!("{} = ({}) as i32", escaped, int_code));
                     }
+                    let (val_code, val_ty) = self.emit_typed_expr(value)?;
+                    // An RHS that is ALREADY an integer stores straight into the register. `d = d + 1`
+                    // reaches here — it is arithmetic, not a bitwise chain, so `emit_int32_operand`
+                    // declines it — and boxing that i32 into a `Value::Number` only to run ToInt32 back
+                    // out of it was the whole cost of incrementing an annotated counter.
+                    let escaped_int = Self::escape_ident(name.as_ref());
+                    if val_ty.is_integer_scalar() {
+                        return Ok(format!("{} = ({}) as i32", escaped_int, val_code));
+                    }
                     // Defensive: gate guarantees `Some`, but if a future RHS shape slips through,
                     // fall back to a sound f64-narrowed store rather than miscompiling.
-                    let (val_code, val_ty) = self.emit_typed_expr(value)?;
                     let v = if val_ty.is_native() {
                         val_ty.to_value_expr(&val_code)
                     } else {
@@ -6859,6 +7226,23 @@ impl Codegen {
         Ok(())
     }
 
+    /// `.clone()` an emitted operand that is a bare Rust identifier, leave anything else alone.
+    ///
+    /// Used where an operand is yielded as the value of an expression that does not consume it
+    /// exclusively (`&&` / `||`): moving a non-`Copy` `Value` local out of such a position makes
+    /// every later read a use-after-move. A parenthesised expression, call, field access, or an
+    /// already-`.clone()`d ident is a temporary, so it needs nothing.
+    fn clone_if_bare_ident(s: &str) -> String {
+        let bare = !s.is_empty()
+            && !s.starts_with(|c: char| c.is_ascii_digit())
+            && s.chars().all(|c| c.is_ascii_alphanumeric() || c == '_');
+        if bare {
+            format!("{}.clone()", s)
+        } else {
+            s.to_string()
+        }
+    }
+
     fn emit_call_arg(&mut self, arg: &CallArg) -> Result<String, CompileError> {
         let e = match arg {
             CallArg::Expr(e) | CallArg::Spread(e) => e,
@@ -14083,6 +14467,22 @@ impl Codegen {
     /// native `Num<i32,8>` arithmetic instead of boxing the literal side through `f64`. Uses the
     /// same truncating `(n * 256) as i32` conversion as the dynamic `fixed`↔`Value` boundary, so
     /// the constant is bit-identical to the boxed path.
+    /// A numeric literal that is EXACTLY a whole number inside `i32`'s range, as an `i32`. Used to keep
+    /// `x > 0` / `i < 100` in integer registers when the other side is already an integer — a fraction
+    /// or an out-of-range magnitude returns `None` and stays on the `f64` path, where it is correct.
+    fn int_literal_of(e: &Expr) -> Option<i32> {
+        if let Expr::Literal {
+            value: Literal::Number(n),
+            ..
+        } = e
+        {
+            if n.fract() == 0.0 && *n >= i32::MIN as f64 && *n <= i32::MAX as f64 {
+                return Some(*n as i32);
+            }
+        }
+        None
+    }
+
     fn fixed_literal_of(e: &Expr) -> Option<String> {
         if let Expr::Literal {
             value: Literal::Number(n),
@@ -21824,6 +22224,14 @@ impl Codegen {
     /// the routing state so call sites de-virtualize. On any failure the state is left empty (path
     /// disabled) and nothing is appended to the output.
     fn setup_aggregate_fns(&mut self, program: &Program) {
+        // #177 de-virtualization deletes the boxed `let <name> = Value::native(..)` local for every
+        // routed fn. `RustLib` publishes exactly those locals as the crate's public API, so an
+        // exported fn that got de-virtualized would leave the emitted `__tish_publish_exports` call
+        // referencing a binding that no longer exists. The unboxed path is a numeric fast path;
+        // a correct public surface outranks it.
+        if self.emit_mode == crate::NativeEmitMode::RustLib {
+            return;
+        }
         let dbg = std::env::var("TISH_AGG_DEBUG").is_ok();
         // The unboxed struct alias: the (unique) name `A` used as an `A[]` array param of some fn,
         // and registered as an all-`Copy`-field struct alias.
@@ -23161,6 +23569,83 @@ impl Codegen {
                 // A narrow int storage read (`u8` HP, `i16` tile x) promotes the same way — read
                 // as its exact `f64` value so arithmetic keeps JS Number semantics; the truncating
                 // store back to the field happens at the assignment site.
+                // …but when BOTH sides are already integers, that detour is pure loss on a CPU with no
+                // FPU. On ARM7TDMI every f64 op is a soft-float library CALL, so `i + 1` on a `: i32`
+                // counter costs two int→float conversions, a call, and a float→int store. It is why
+                // annotating a loop counter `: i32` measured SLOWER than leaving it a plain number
+                // (examples/bench-ai) — the opposite of what an annotation is for.
+                //
+                // Keeping the pair in integer registers is not an approximation: every i32 is exact in
+                // f64, so `+`, `-` and the relational operators give bit-identical answers in either
+                // domain. Only the operators where the two domains genuinely DISAGREE stay on floats:
+                //   `/`  JS division is real division — `5 / 2` is 2.5, not 2
+                //   `%`  integer `%` panics on a zero divisor where JS yields NaN
+                //   `*`  a product can leave i32's range while staying exact in f64, and the bitwise
+                //        lowering below deliberately relies on that headroom (`h * 16777619`)
+                // Operands widen to `i32` first so mixed widths (a `u8` HP against an `i16` tile
+                // coordinate) still agree with JS Number semantics. `u32` is excluded because it is the
+                // one width that does not fit — reading 3 billion `as i32` would flip its sign.
+                // The adds wrap rather than panic, which matches both JS (`to_int32` is modulo 2³²) and
+                // the truncating `as` store every integer target already performs.
+                let fits_i32 = |t: &RustType| {
+                    matches!(
+                        t,
+                        RustType::I32
+                            | RustType::I8
+                            | RustType::U8
+                            | RustType::I16
+                            | RustType::U16
+                    )
+                };
+                // An integer against a whole-number LITERAL is the shape most of this actually is —
+                // `x > 0`, `i < 100`, `0 - dir`. The literal types as `f64`, which would drag the
+                // integer side out of its register for a soft-float compare over two values that are
+                // both plainly integers. Fold it into the integer domain instead. Only exact whole
+                // numbers inside i32's range qualify, so `x < 2.5` and `x < 3e9` still go to floats,
+                // where they belong.
+                let (l, lt, r, rt) = if fits_i32(&lt) && rt == RustType::F64 {
+                    match Self::int_literal_of(right) {
+                        Some(v) => (l, lt, format!("{}i32", v), RustType::I32),
+                        None => (l, lt, r, rt),
+                    }
+                } else if fits_i32(&rt) && lt == RustType::F64 {
+                    match Self::int_literal_of(left) {
+                        Some(v) => (format!("{}i32", v), RustType::I32, r, rt),
+                        None => (l, lt, r, rt),
+                    }
+                } else {
+                    (l, lt, r, rt)
+                };
+                if fits_i32(&lt) && fits_i32(&rt) {
+                    let li = format!("(({}) as i32)", l);
+                    let ri = format!("(({}) as i32)", r);
+                    match op {
+                        BinOp::Add => {
+                            return Ok((
+                                format!("({}).wrapping_add({})", li, ri),
+                                RustType::I32,
+                            ))
+                        }
+                        BinOp::Sub => {
+                            return Ok((
+                                format!("({}).wrapping_sub({})", li, ri),
+                                RustType::I32,
+                            ))
+                        }
+                        BinOp::Lt => return Ok((format!("({} < {})", li, ri), RustType::Bool)),
+                        BinOp::Le => return Ok((format!("({} <= {})", li, ri), RustType::Bool)),
+                        BinOp::Gt => return Ok((format!("({} > {})", li, ri), RustType::Bool)),
+                        BinOp::Ge => return Ok((format!("({} >= {})", li, ri), RustType::Bool)),
+                        BinOp::StrictEq => {
+                            return Ok((format!("({} == {})", li, ri), RustType::Bool))
+                        }
+                        BinOp::StrictNe => {
+                            return Ok((format!("({} != {})", li, ri), RustType::Bool))
+                        }
+                        _ => {}
+                    }
+                }
+
                 let (l, lt) = if lt.is_integer_scalar() {
                     (format!("(({}) as f64)", l), RustType::F64)
                 } else {
@@ -24817,8 +25302,21 @@ impl Codegen {
             // the same local (`aid && out.indexOf(aid)`), and a bare `let __l = aid;` moves the non-`Copy`
             // `Value` so the reuse is a borrow-after-move (E0382). The left operand is still evaluated
             // exactly once (its side effects don't double-run); only its value is cloned for the test.
-            BinOp::And => format!("{{ let __l = ({}).clone(); if __l.is_truthy() {{ {} }} else {{ __l }} }}", l, r),
-            BinOp::Or => format!("{{ let __l = ({}).clone(); if __l.is_truthy() {{ __l }} else {{ {} }} }}", l, r),
+            //
+            // The RESULT operand has the same hazard: when it lowers to a bare local (`inGenBlock &&
+            // currentTrack`), yielding it moves that local out, so a later read — the next iteration
+            // of the enclosing loop, or any subsequent use — is E0382. Clone it in that case only;
+            // anything else is already a temporary (or already cloned), so the fast path is unchanged.
+            BinOp::And => format!(
+                "{{ let __l = ({}).clone(); if __l.is_truthy() {{ {} }} else {{ __l }} }}",
+                l,
+                Self::clone_if_bare_ident(r)
+            ),
+            BinOp::Or => format!(
+                "{{ let __l = ({}).clone(); if __l.is_truthy() {{ __l }} else {{ {} }} }}",
+                l,
+                Self::clone_if_bare_ident(r)
+            ),
             BinOp::BitAnd => Self::emit_bitwise_binop(l, r, "&"),
             BinOp::BitOr => Self::emit_bitwise_binop(l, r, "|"),
             BinOp::BitXor => Self::emit_bitwise_binop(l, r, "^"),