@tishlang/tish-format 2.39.0 → 2.43.8

package/crates/tish_compile/src/types.rs

@@ -2,10 +2,34 @@
 //!
 //! Maps TypeAnnotation from the AST to concrete Rust types for code generation.
 
+use std::cell::Cell;
 use std::collections::HashMap;
 use std::sync::Arc;
 use tishlang_ast::{BinOp, FunParam, TypeAnnotation, TypedParam};
 
+thread_local! {
+    /// Whether the extended GBA numeric vocabulary — the narrow integer widths (`i8/u8/i16/u16/u32`)
+    /// and `fixed` — lowers to native scalar types. **Off by default** (standard targets): those
+    /// annotations must fall back to the boxed `Value` path off-GBA, because `fixed` has no host
+    /// runtime type (a hard compile error) and the narrow widths truncate on store (`u8 = 300` → 255),
+    /// diverging from the interpreter and breaking the typed == boxed == interpreter guarantee that
+    /// non-GBA targets rely on. A GBA build turns this on (see `set_gba_numerics`), where those
+    /// types ARE the point. `i32`/`f64` are NOT gated — `f64` is just `number`, and `i32` is the
+    /// pre-existing JS-ToInt32 register lowering.
+    static GBA_NUMERICS: Cell<bool> = const { Cell::new(false) };
+}
+
+/// Enable (GBA) or disable (every other target) the extended narrow-int/`fixed` numeric vocabulary
+/// for the current compile. Set once at compile start from the emit mode; see [`GBA_NUMERICS`].
+pub fn set_gba_numerics(on: bool) {
+    GBA_NUMERICS.with(|c| c.set(on));
+}
+
+/// Whether `from_annotation` should lower `i8/u8/i16/u16/u32/fixed` to native scalars.
+fn gba_numerics() -> bool {
+    GBA_NUMERICS.with(|c| c.get())
+}
+
 /// Concrete Rust type representation for code generation.
 #[derive(Debug, Clone, PartialEq)]
 pub enum RustType {
@@ -16,9 +40,27 @@ pub enum RustType {
     /// i32 — a `number` local PROVEN to always hold an integer reinterpretable as a JS ToInt32
     /// bit-pattern, kept in an integer register across a bitwise/hash hot loop (bun/JSC-style)
     /// instead of round-tripping `f64`↔`i32` on every op. The value is the signed int32
-    /// (= JS `ToInt32`) view; `>>> 0` results are uint32 reinterpreted into this i32. Only the
-    /// codegen's i32-loop-var lowering produces this type — never `from_annotation`.
+    /// (= JS `ToInt32`) view; `>>> 0` results are uint32 reinterpreted into this i32. Off-GBA only
+    /// the codegen's i32-loop-var lowering produces this type (a proven-in-range value) — never
+    /// `from_annotation`; a `--target gba` build additionally lowers a `: i32` annotation to it
+    /// (part of the GBA typed-scalar vocabulary, gated by `GBA_NUMERICS`).
     I32,
+    /// Fixed-point `tishlang_runtime::Fixed` (= agb `Num<i32, 8>`), for the `fixed`
+    /// annotation — fast, FPU-free math for positions/velocities on the GBA. Only
+    /// `from_annotation` (and fixed-typed inference) produces this. Boxes to/from
+    /// `Value::Number` losslessly at boundaries.
+    Fixed,
+    /// Narrow integer STORAGE types (`i8`/`u8`/`i16`/`u16`/`u32` annotations). Their whole
+    /// point is compact struct fields — a `u8` HP or an `i16` tile coordinate costs 1–2
+    /// bytes in scarce EWRAM instead of 8. Arithmetic PROMOTES to `f64` (JS Number
+    /// semantics, exactly like `I32` at [`Self::result_type_of_binop`]); a store back into
+    /// the narrow field truncates with a saturating `as` cast. Only `from_annotation`
+    /// produces these. Box to/from `Value::Number` (every value in-range is exact in f64).
+    I8,
+    U8,
+    I16,
+    U16,
+    U32,
     /// String (for string)
     String,
     /// bool (for boolean)
@@ -83,6 +125,28 @@ impl RustType {
         match ann {
             TypeAnnotation::Simple(name, _) => match name.as_ref() {
                 "number" => RustType::F64,
+                // Concrete Rust scalar names in typed tish (user requirement): they
+                // lower to the corresponding native Rust type instead of a boxed
+                // `Value`. `f64` is an alias for `number`; `i32` reuses the existing
+                // integer-register lowering (its value is the JS ToInt32 view, which
+                // is exactly an annotated `i32`). The narrow widths are compact struct
+                // storage; `fixed` is agb `Num<i32,8>`.
+                // GBA-only numeric vocabulary (see `GBA_NUMERICS`): off-GBA these fall through to
+                // the `other` arm → boxed `Value` (matching main, where these annotations were
+                // unrecognized), so `fixed` compiles (no host `Fixed` type), narrow widths keep
+                // interpreter number semantics instead of truncating, and a `: i32` annotation
+                // doesn't saturate/ToInt32 an out-of-range value — restoring the invariant that
+                // `I32` comes ONLY from the proven-in-range i32-loop-var lowering, never a raw
+                // annotation. `f64` is the redundant Rust spelling of `number`; gated alongside the
+                // rest so it too is inert off-GBA (`number` itself stays `F64`, always).
+                "f64" if gba_numerics() => RustType::F64,
+                "i32" if gba_numerics() => RustType::I32,
+                "i8" if gba_numerics() => RustType::I8,
+                "u8" if gba_numerics() => RustType::U8,
+                "i16" if gba_numerics() => RustType::I16,
+                "u16" if gba_numerics() => RustType::U16,
+                "u32" if gba_numerics() => RustType::U32,
+                "fixed" if gba_numerics() => RustType::Fixed,
                 "string" => RustType::String,
                 "boolean" | "bool" => RustType::Bool,
                 "void" | "undefined" => RustType::Unit,
@@ -196,6 +260,31 @@ impl RustType {
         matches!(self, RustType::F64)
     }
 
+    /// A native integer scalar (`i32` or one of the narrow storage widths). These share one
+    /// arithmetic model: read as `f64` (JS Number semantics), store with a truncating `as`
+    /// cast. `Fixed` is deliberately excluded — it is fixed-point, not an integer.
+    pub fn is_integer_scalar(&self) -> bool {
+        matches!(
+            self,
+            RustType::I32
+                | RustType::I8
+                | RustType::U8
+                | RustType::I16
+                | RustType::U16
+                | RustType::U32
+        )
+    }
+
+    /// A NARROW integer storage width (`i8`/`u8`/`i16`/`u16`/`u32`) — an integer scalar other
+    /// than the `I32` register type, which has its own JS-ToInt32 lowering. These promote to
+    /// `f64` for arithmetic and truncate-cast on store.
+    pub fn is_narrow_int(&self) -> bool {
+        matches!(
+            self,
+            RustType::I8 | RustType::U8 | RustType::I16 | RustType::U16 | RustType::U32
+        )
+    }
+
     /// Infer the result type of a binary operation given the operand types.
     /// Returns `None` if native code cannot be emitted (fall back to Value path).
     pub fn result_type_of_binop(op: BinOp, lhs: &RustType, rhs: &RustType) -> Option<RustType> {
@@ -221,6 +310,21 @@ impl RustType {
                 | BinOp::StrictNe => Some(RustType::Bool),
                 _ => None,
             }
+        } else if lhs == &RustType::Fixed && rhs == &RustType::Fixed {
+            // agb `Num<i32,8>` overloads `+ - * /` (Mul/Div apply the Q24.8 shift
+            // correction) and `PartialOrd`/`PartialEq`, so these lower to native
+            // fixed-point ops — no f64 round-trip, no FPU. `%`/`**`/bitwise fall to
+            // the boxed path (rare on positions/velocities).
+            match op {
+                BinOp::Add | BinOp::Sub | BinOp::Mul | BinOp::Div => Some(RustType::Fixed),
+                BinOp::Lt
+                | BinOp::Le
+                | BinOp::Gt
+                | BinOp::Ge
+                | BinOp::StrictEq
+                | BinOp::StrictNe => Some(RustType::Bool),
+                _ => None,
+            }
         } else if lhs == &RustType::Bool && rhs == &RustType::Bool {
             match op {
                 BinOp::And | BinOp::Or => Some(RustType::Bool),
@@ -248,6 +352,12 @@ impl RustType {
             RustType::Value => "Value".to_string(),
             RustType::F64 => "f64".to_string(),
             RustType::I32 => "i32".to_string(),
+            RustType::I8 => "i8".to_string(),
+            RustType::U8 => "u8".to_string(),
+            RustType::I16 => "i16".to_string(),
+            RustType::U16 => "u16".to_string(),
+            RustType::U32 => "u32".to_string(),
+            RustType::Fixed => "tishlang_runtime::Fixed".to_string(),
             RustType::String => "String".to_string(),
             RustType::Bool => "bool".to_string(),
             RustType::Unit => "()".to_string(),
@@ -279,6 +389,12 @@ impl RustType {
             RustType::Value => "Value::Null".to_string(),
             RustType::F64 => "0.0".to_string(),
             RustType::I32 => "0i32".to_string(),
+            RustType::I8 => "0i8".to_string(),
+            RustType::U8 => "0u8".to_string(),
+            RustType::I16 => "0i16".to_string(),
+            RustType::U16 => "0u16".to_string(),
+            RustType::U32 => "0u32".to_string(),
+            RustType::Fixed => "tishlang_runtime::Fixed::from_raw(0)".to_string(),
             RustType::String => "String::new()".to_string(),
             RustType::Bool => "false".to_string(),
             RustType::Unit => "()".to_string(),
@@ -358,6 +474,23 @@ impl RustType {
                 "match &{} {{ Value::Number(n) => tishlang_runtime::to_int32(*n), _ => panic!(\"expected number\") }}",
                 value_expr
             ),
+            // Narrow int storage: extract the JS Number and truncate-cast to the field width
+            // (Rust `f64 as iN` saturates out-of-range and maps NaN→0 — safe for a storage slot).
+            RustType::I8 | RustType::U8 | RustType::I16 | RustType::U16 | RustType::U32 => {
+                format!(
+                    "match &{} {{ Value::Number(n) => (*n as {}), _ => panic!(\"expected number\") }}",
+                    value_expr,
+                    self.to_rust_type_str()
+                )
+            }
+            // f64 → Q24.8: scale by 256 and TRUNCATE toward zero (`as i32`), keeping only 8
+            // fractional bits (`0.1` → raw 25 ≈ 0.0977, not exact). Must stay bit-identical with
+            // the compile-time literal fold in codegen (`fixed_literal_of`) so a `fixed` value is
+            // the same whether it came from a folded literal or this runtime conversion.
+            RustType::Fixed => format!(
+                "match &{} {{ Value::Number(n) => tishlang_runtime::Fixed::from_raw((*n * 256.0) as i32), _ => panic!(\"expected number\") }}",
+                value_expr
+            ),
             RustType::String => format!(
                 "match &{} {{ Value::String(s) => s.to_string(), _ => panic!(\"expected string\") }}",
                 value_expr
@@ -437,6 +570,12 @@ impl RustType {
             // The signed int32 view boxes as a JS Number (every i32 is exactly representable in
             // f64). The uint32 `>>> 0` reinterpretation is applied at the boxing site, not here.
             RustType::I32 => format!("Value::Number(({}) as f64)", native_expr),
+            // Narrow int → JS Number: every in-range narrow int is exact in f64.
+            RustType::I8 | RustType::U8 | RustType::I16 | RustType::U16 | RustType::U32 => {
+                format!("Value::Number(({}) as f64)", native_expr)
+            }
+            // Q24.8 → f64 is exact (32 significant bits into a 52-bit mantissa).
+            RustType::Fixed => format!("Value::Number(({}).to_raw() as f64 / 256.0)", native_expr),
             RustType::String => format!("Value::String({}.clone().into())", native_expr),
             RustType::Bool => format!("Value::Bool({})", native_expr),
             RustType::Unit => "Value::Null".to_string(),

package/crates/tish_compile/tests/perf_codegen_320.rs

@@ -134,8 +134,8 @@ fn readonly_arr_param_unboxed_to_native_vec() {
     // NumberArray clones its backing; a boxed Array is mapped element-wise).
     assert!(
         rust.contains("let mut seq: Vec<f64> = match args.get(")
-            && rust.contains("Some(Value::NumberArray(a)) => a.borrow().clone()"),
-        "read-only number[] param should be unboxed to a native Vec<f64>"
+            && rust.contains("NumArrayBacking::Packed(p) => p.clone()"),
+        "read-only number[] param should be unboxed to a native Vec<f64> (packed backing cloned directly)"
     );
     // And the hot inner loop indexes it natively (f64 mul + native vec read), no boxed get_index.
     assert!(

package/crates/tish_compile/tests/perf_codegen_module_const_forof.rs

@@ -33,7 +33,9 @@ fn template_literals_hoisted_nums_compiles() {
     let (rust, _, _, _) = compile_project_full(&path, path.parent(), &[], true).unwrap();
     assert!(rust.contains("const G_NUMS:"));
     assert!(
-        rust.contains("array_join(&Value::NumberArray(VmRef::new(G_NUMS"),
+        rust.contains(
+            "array_join(&Value::NumberArray(VmRef::new(tishlang_runtime::NumArrayBacking::Packed(G_NUMS"
+        ),
         "nums.join should box hoisted G_NUMS, not reference missing local nums"
     );
     assert!(!rust.contains("&nums,"));

package/crates/tish_compile/tests/platform_resolve_cli.rs

@@ -0,0 +1,164 @@
+//! Golden: `resolve_with_platform` cascade matches the documented order.
+//! Vite consumes the same rules via `tish resolve-id`.
+//!
+//! The CLI parity test **fails** (does not skip) when no usable `tish` binary is found,
+//! so CI cannot silently ship without `resolve-id`.
+
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use tempfile::tempdir;
+use tishlang_compile::{resolve_with_platform, Platform, ResolveContext, Surface};
+
+#[test]
+fn cascade_orders_match_language_md() {
+    let dir = tempdir().unwrap();
+    let root = dir.path();
+    fs::write(root.join("Button.tish"), "export fn Button() {}").unwrap();
+    fs::write(root.join("Button.web.tish"), "export fn Button() {}").unwrap();
+    fs::write(root.join("Button.webview.tish"), "export fn Button() {}").unwrap();
+    fs::write(root.join("Button.macos.tish"), "export fn Button() {}").unwrap();
+    fs::write(root.join("Button.desktop.tish"), "export fn Button() {}").unwrap();
+
+    let macos_native = resolve_with_platform(
+        "./Button",
+        root,
+        ResolveContext {
+            platform: Platform::Macos,
+            surface: Surface::Native,
+        },
+    )
+    .unwrap();
+    assert!(macos_native.ends_with("Button.macos.tish"));
+
+    let webview = resolve_with_platform(
+        "./Button",
+        root,
+        ResolveContext {
+            platform: Platform::Macos,
+            surface: Surface::Webview,
+        },
+    )
+    .unwrap();
+    assert!(webview.ends_with("Button.webview.tish"));
+
+    let web = resolve_with_platform(
+        "./Button",
+        root,
+        ResolveContext {
+            platform: Platform::Web,
+            surface: Surface::Web,
+        },
+    )
+    .unwrap();
+    assert!(web.ends_with("Button.web.tish"));
+
+    // Remap explicit .tish to platform file when present
+    let remapped = resolve_with_platform(
+        "./Button.tish",
+        root,
+        ResolveContext {
+            platform: Platform::Macos,
+            surface: Surface::Native,
+        },
+    )
+    .unwrap();
+    assert!(remapped.ends_with("Button.macos.tish"));
+}
+
+/// Locate a `tish` binary that supports `resolve-id`.
+///
+/// Does **not** shell out to `cargo build --bin tish` (under `cargo llvm-cov` that can shadow the
+/// instrumented CLI). Searches the same places as `integration_test::tish_bin()`, including
+/// `llvm-cov-target`. Callers must fail hard if this returns `None` — CI must not soft-skip.
+fn find_tish_binary() -> Option<PathBuf> {
+    if let Ok(p) = std::env::var("TISH_PATH") {
+        let pb = PathBuf::from(&p);
+        if pb.is_file() {
+            return Some(pb);
+        }
+    }
+    let bin = if cfg!(windows) { "tish.exe" } else { "tish" };
+    let manifest = Path::new(env!("CARGO_MANIFEST_DIR"));
+    let mut roots: Vec<PathBuf> = Vec::new();
+    if let Ok(td) = std::env::var("CARGO_TARGET_DIR") {
+        roots.push(PathBuf::from(td));
+    }
+    // crates/tish_compile → workspace `target/` (and the coverage-instrumented `llvm-cov-target`).
+    for rel in ["../../target", "../../../target"] {
+        roots.push(manifest.join(rel));
+        roots.push(manifest.join(rel).join("llvm-cov-target"));
+    }
+    for root in roots {
+        for profile in ["debug", "release"] {
+            let cand = root.join(profile).join(bin);
+            if cand.is_file() {
+                return Some(cand);
+            }
+        }
+    }
+    if let Ok(out) = Command::new("which").arg("tish").output() {
+        if out.status.success() {
+            let p = String::from_utf8_lossy(&out.stdout).trim().to_string();
+            if !p.is_empty() && Path::new(&p).is_file() {
+                return Some(PathBuf::from(p));
+            }
+        }
+    }
+    None
+}
+
+#[test]
+fn resolve_id_cli_matches_library() {
+    let dir = tempdir().unwrap();
+    let root = dir.path();
+    fs::write(root.join("X.web.tish"), "").unwrap();
+    fs::write(root.join("X.tish"), "").unwrap();
+    let importer = root.join("App.tish");
+    fs::write(&importer, "").unwrap();
+
+    let lib = resolve_with_platform(
+        "./X",
+        root,
+        ResolveContext {
+            platform: Platform::Web,
+            surface: Surface::Web,
+        },
+    )
+    .unwrap();
+
+    let tish = find_tish_binary().unwrap_or_else(|| {
+        panic!(
+            "tish binary with resolve-id required (set TISH_PATH or cargo build -p tishlang --bin tish). \
+             Soft-skip is forbidden — Vite and tish build must share resolve rules."
+        )
+    });
+    let out = Command::new(&tish)
+        .args([
+            "resolve-id",
+            "./X",
+            "--importer",
+            importer.to_str().unwrap(),
+            "--platform",
+            "web",
+            "--surface",
+            "web",
+        ])
+        .output()
+        .unwrap_or_else(|e| panic!("failed to run {}: {e}", tish.display()));
+
+    assert!(
+        out.status.success(),
+        "tish resolve-id failed ({}):\nstdout: {}\nstderr: {}",
+        tish.display(),
+        String::from_utf8_lossy(&out.stdout),
+        String::from_utf8_lossy(&out.stderr)
+    );
+    let cli_path = String::from_utf8_lossy(&out.stdout).trim().to_string();
+    assert_eq!(
+        std::fs::canonicalize(&cli_path).unwrap(),
+        lib,
+        "Vite/CLI resolve-id must match library cascade"
+    );
+}

package/crates/tish_compile/tests/regr_gba_numerics_gated.rs

@@ -0,0 +1,58 @@
+//! Regression: `fixed` and the narrow integer widths (`i8/u8/i16/u16/u32`) are the GBA typed-scalar
+//! vocabulary and must lower to native scalars ONLY for `--target gba`. On the default native build
+//! they must fall back to boxed `Value` — otherwise `fixed` references `tishlang_runtime::Fixed`,
+//! which does not exist off-GBA (a hard compile error), and narrow widths truncate on store,
+//! diverging from the interpreter and breaking the typed == boxed == interpreter guarantee.
+use std::path::PathBuf;
+use tishlang_compile::{compile_project_full, compile_project_full_emit, NativeEmitMode};
+
+fn fixture(rel: &str) -> PathBuf {
+    let manifest = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    manifest.join("../..").join(rel).canonicalize().unwrap()
+}
+
+fn compile(rel: &str) -> String {
+    let path = fixture(rel);
+    // compile_project_full uses the default DesktopBin emit mode (i.e. NOT --target gba).
+    compile_project_full(&path, path.parent(), &[], true).unwrap().0
+}
+
+#[test]
+fn narrow_int_and_fixed_do_not_lower_to_native_off_gba() {
+    let rust = compile("tests/regression/gba_numerics_gated.tish");
+    // `fixed` must not emit the GBA-only native type (absent off-GBA → would not compile).
+    assert!(
+        !rust.contains("tishlang_runtime::Fixed"),
+        "`: fixed` must fall back to boxed Value on a non-GBA build (found the native Fixed type):\n{}",
+        rust
+    );
+    // The narrow-width fields must not become native storage types (which would truncate).
+    assert!(
+        !rust.contains(": u8") && !rust.contains(": i16") && !rust.contains("as u8"),
+        "narrow-int annotations must stay boxed Value off-GBA (found native narrow storage):\n{}",
+        rust
+    );
+}
+
+#[test]
+fn gba_numeric_profile_does_not_leak_to_a_later_desktop_compile() {
+    // The numeric profile is a thread-local. A GBA compile turns it on; a subsequent non-GBA
+    // compile on the SAME thread (as happens in an LSP / a `cargo test` worker) must NOT inherit it
+    // — otherwise `: fixed`/narrow/`i32` would lower natively off-GBA and diverge. This orders both
+    // compiles on one thread and checks the desktop one is clean.
+    let path = fixture("tests/regression/gba_numerics_gated.tish");
+    let gba = compile_project_full_emit(&path, path.parent(), &[], true, NativeEmitMode::Gba, None)
+        .unwrap()
+        .0;
+    assert!(
+        gba.contains("tishlang_runtime::Fixed"),
+        "sanity: GBA mode DOES lower `: fixed` to the native Fixed type"
+    );
+    // Same thread, right after the GBA compile: a default (DesktopBin) compile must reset the profile.
+    let desktop = compile_project_full(&path, path.parent(), &[], true).unwrap().0;
+    assert!(
+        !desktop.contains("tishlang_runtime::Fixed"),
+        "a desktop compile after a GBA compile leaked the GBA numeric profile (found native Fixed):\n{}",
+        desktop
+    );
+}

package/crates/tish_compiler_wasm/Cargo.toml

@@ -16,6 +16,7 @@ wasm-bindgen = "0.2"
 
 tishlang_ast = { path = "../tish_ast", version = ">=0.1" }
 tishlang_bytecode = { path = "../tish_bytecode", version = ">=0.1" }
+tishlang_compile = { path = "../tish_compile", version = ">=0.1" }
 tishlang_compile_js = { path = "../tish_compile_js", version = ">=0.1" }
 tishlang_opt = { path = "../tish_opt", version = ">=0.1" }
 tishlang_parser = { path = "../tish_parser", version = ">=0.1" }

package/crates/tish_compiler_wasm/src/resolve_virtual.rs

@@ -76,7 +76,8 @@ fn parent_dir(path: &str) -> &str {
     }
 }
 
-/// Resolve import spec to a key for the files map. Tries .tish extension if missing.
+/// Resolve import spec to a key for the files map.
+/// Uses the same platform/surface cascade as `tish resolve-id` / disk resolve (`TISH_PLATFORM` / `TISH_SURFACE`).
 fn resolve_import_to_key(
     spec: &str,
     from_dir: &str,
@@ -86,14 +87,29 @@ fn resolve_import_to_key(
     if files.contains_key(&normalized) {
         return Ok(normalized);
     }
-    if !normalized.ends_with(".tish") && !normalized.contains('.') {
-        let with_ext = format!("{}.tish", normalized);
-        if files.contains_key(&with_ext) {
-            return Ok(with_ext);
+
+    let stem = if normalized.ends_with(".tish") {
+        &normalized[..normalized.len() - 5]
+    } else if !normalized.contains('.') {
+        normalized.as_str()
+    } else {
+        return Err(format!(
+            "Cannot resolve import '{}' from {}: file not in virtual file map",
+            spec, from_dir
+        ));
+    };
+
+    // Match CLI: honor env when set (playground can set TISH_PLATFORM / TISH_SURFACE).
+    let _ = tishlang_compile::apply_resolve_env(None, None);
+    let ctx = tishlang_compile::resolve_context();
+    for key in tishlang_compile::platform_virtual_keys(stem, ctx) {
+        if files.contains_key(&key) {
+            return Ok(key);
         }
     }
+
     Err(format!(
-        "Cannot resolve import '{}' from {}: file not in virtual file map",
+        "Cannot resolve import '{}' from {}: file not in virtual file map (platform cascade)",
         spec, from_dir
     ))
 }
@@ -584,4 +600,38 @@ mod tests {
             "import of re-exported `plus` should bind to dep's `add`"
         );
     }
+
+    #[test]
+    fn resolve_virtual_honors_platform_cascade() {
+        use tishlang_compile::{set_resolve_context, Platform, ResolveContext, Surface};
+        set_resolve_context(ResolveContext {
+            platform: Platform::Macos,
+            surface: Surface::Native,
+        });
+        let mut files = HashMap::new();
+        files.insert(
+            "Button.tish".to_string(),
+            "export fn Button() {}".to_string(),
+        );
+        files.insert(
+            "Button.macos.tish".to_string(),
+            "export fn Button() {}".to_string(),
+        );
+        files.insert(
+            "main.tish".to_string(),
+            "import { Button } from \"./Button\"\nButton()".to_string(),
+        );
+        let modules = resolve_virtual("main.tish", &files).unwrap();
+        // macos/native → the .macos variant wins; the base is never loaded.
+        assert!(
+            modules.iter().any(|m| m.path == "Button.macos.tish"),
+            "platform cascade should resolve Button.macos.tish"
+        );
+        assert!(
+            !modules.iter().any(|m| m.path == "Button.tish"),
+            "base Button.tish must not resolve when the macos variant exists"
+        );
+        // Reset the process-wide context so it doesn't leak into sibling tests.
+        set_resolve_context(ResolveContext::default());
+    }
 }

package/crates/tish_core/Cargo.toml

@@ -7,8 +7,25 @@ description = "Shared Value type and utilities for Tish (used by interpreter and
 license-file = { workspace = true }
 repository = { workspace = true }
 [features]
-default = []
+# `std` is on by default, so every existing consumer builds exactly as before
+# (ahash + arcstr + indexmap/std). No workspace crate disables default-features on
+# tishlang_core, so gating the std-only deps here is safe.
+default = ["std"]
+std = ["dep:ahash", "dep:arcstr", "indexmap/std"]
 regex = ["dep:fancy-regex"]
+# no_std + alloc build for embedded targets (Game Boy Advance, thumbv4t-none-eabi).
+# Depend on it as `default-features = false, features = ["portable"]`. It swaps the
+# std-only deps (ahash, arcstr) and primitives (std::sync::Arc/atomic, thread_local!)
+# for atomics-free, alloc-based equivalents via the `compat` module. Default (std)
+# builds are unaffected — `compat` is a transparent re-export when this is off.
+# Mutually exclusive with `send-values` (single-threaded target; no Arc/Mutex).
+# See crates/tish_core/src/compat.rs.
+portable = [
+    "dep:hashbrown",
+    "dep:rustc-hash",
+    "dep:portable-atomic",
+    "dep:libm",
+]
 # Make `Value` (and its array / object / regex payloads) `Send + Sync` by
 # switching the interior `Rc<RefCell<T>>` to `Arc<Mutex<T>>` and the native
 # function type from `Rc<dyn Fn>` to `Arc<dyn Fn + Send + Sync>`. Enabled
@@ -19,10 +36,13 @@ regex = ["dep:fancy-regex"]
 send-values = ["dep:parking_lot"]
 
 [dependencies]
-ahash = "0.8.11"
-arcstr = "1"
+# std-only (need atomics); optional so the `portable` build can drop them.
+ahash = { version = "0.8.11", optional = true }
+arcstr = { version = "1", optional = true }
 smallvec = "1"
-indexmap = "2"
+# default-features=false keeps indexmap no_std-capable; the `std` feature re-adds
+# its std integration for hosted builds (indexmap always works on alloc alone).
+indexmap = { version = "2", default-features = false }
 # Fast integer→decimal for the JSON.stringify number fast-path (already in the workspace lock).
 itoa = "1"
 # Fast shortest-float→decimal for the number→string general path (JSON/template/log). ryu writes the
@@ -34,5 +54,20 @@ fancy-regex = { version = "0.17.0", optional = true }
 # single atomic with no pthread syscall — profiled as a top cost on object/array access.
 parking_lot = { version = "0.12", optional = true }
 
+# --- `portable` (no_std) deps. All optional; only pulled in for embedded builds. ---
+# Atomics-free hash map (ahash needs std/atomics). FxHasher is what agb_hashmap uses on GBA.
+hashbrown = { version = "0.15", default-features = false, optional = true }
+rustc-hash = { version = "2", default-features = false, optional = true }
+# AtomicU64 for the single symbol-id counter — portable-atomic provides it on no-atomics
+# targets via critical-section (impl supplied at final link by agb).
+# Default features include `fallback`, which provides AtomicU64 on targets lacking
+# native 64-bit atomics. The single-core backend is selected by the
+# `portable_atomic_unsafe_assume_single_core` cfg — supplied by agb in the real GBA
+# build (do NOT also enable the `critical-section` feature; agb forbids both). The
+# standalone core/builtins CI build passes that cfg via RUSTFLAGS.
+portable-atomic = { version = "1", optional = true }
+# f64 transcendentals in no_std (std's f64 methods are unavailable without libm).
+libm = { version = "0.2", optional = true }
+
 [target.wasm32-unknown-unknown.dependencies]
 getrandom = { version = "0.3", features = ["wasm_js"] }