@tishlang/tish-format 2.39.0 → 3.0.0

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,
@@ -191,11 +255,47 @@ impl RustType {
         !matches!(self, RustType::Value)
     }
 
+    /// Whether the generated Rust type is `Copy` — the native numeric scalars, `Fixed`, and `Unit`.
+    /// A `Copy` field can be read out of a borrowed place (`arr[i].field`, `(*cell.borrow()).field`)
+    /// by value; a non-`Copy` one (`Value`/`String`/an aggregate) must be `.clone()`d there or it
+    /// moves out of the borrow — a use-after-move / cannot-move-out-of-index error (E0382 / E0507).
+    pub fn is_copy(&self) -> bool {
+        matches!(
+            self,
+            RustType::F64 | RustType::I32 | RustType::Bool | RustType::Fixed | RustType::Unit
+        ) || self.is_narrow_int()
+    }
+
     /// Check if this type is numeric (f64).
     pub fn is_numeric(&self) -> bool {
         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 +321,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 +363,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 +400,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 +485,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
@@ -400,11 +544,19 @@ impl RustType {
                 // e.g. an assignment-as-expression `{ let _v = obj; lhs = <coerce _v>; _v }` reuses
                 // `_v` for its value (tishlang/tish#486). `&(expr)` evaluates the source once and
                 // (for a temporary) lifetime-extends it to this block, so it's still single-eval.
+                //
+                // FAST PATH (GBA/portable): if the source is a BY-REFERENCE boxed struct of exactly this
+                // type (`Value::Struct`, e.g. from a `Value::from_struct` return), `downcast_struct`
+                // clones it out directly — no per-field `get_prop`. Off-portable there is no struct
+                // variant, so `downcast_struct` is a `None` constant the optimiser removes, leaving the
+                // rebuild path byte-identical to before.
+                let struct_ident = named_struct_ident(name);
                 format!(
-                    "{{ let _src = &({}); {} {{ {} }} }}",
-                    value_expr,
-                    named_struct_ident(name),
-                    field_assigns
+                    "{{ let _src = &({}); match _src.downcast_struct::<{}>() {{ \
+                        Some(_s) => _s, \
+                        None => {} {{ {} }} \
+                    }} }}",
+                    value_expr, struct_ident, struct_ident, field_assigns
                 )
             }
             RustType::ShapeUnion { .. } => {
@@ -437,6 +589,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(),
@@ -463,34 +621,22 @@ impl RustType {
                     native_expr, inner_to_value
                 )
             }
-            RustType::Named { fields, .. } => {
-                // Build the boxed Value with an ORDERED PropMap via `object_from_pairs` (no
-                // intermediate `AHashMap`), so key order == field-declaration order == JS
-                // insertion order. The old `ObjectMap::default()` (`AHashMap`) + insert path
-                // scrambled key order NON-DETERMINISTICALLY per run (ahash seed) — a shipped
-                // `JSON.stringify` / `Object.keys` / `for..in` divergence from node whenever a
-                // native struct crosses back into untyped Tish. This boundary is paid only on
-                // that crossing (JSON.stringify, calling a Value::Function, etc.); direct
-                // Rust-to-Rust paths between two Named values stay as plain struct moves.
-                let pairs = fields
-                    .iter()
-                    .map(|(k, ty)| {
-                        let access = format!("{}.{}", native_expr, field_ident(k));
-                        // A `Value`-typed field (e.g. from a generic struct `Box<T>`) accessed
-                        // behind `&self` must be cloned — it isn't `Copy` and `to_value_expr(Value)`
-                        // is identity. Native field types clone/copy inside their own `to_value_expr`.
-                        let v_expr = if matches!(ty, RustType::Value) {
-                            format!("{}.clone()", access)
-                        } else {
-                            ty.to_value_expr(&access)
-                        };
-                        format!("(::std::sync::Arc::from({:?}), {})", k.as_ref(), v_expr)
-                    })
-                    .collect::<Vec<_>>()
-                    .join(", ");
-                // `object_from_pairs::<N>` builds the `PropMap` in one ordered pass (N = field
-                // count, a codegen-time constant) — no AHashMap, so key order is preserved.
-                format!("Value::object_from_pairs([{}])", pairs)
+            RustType::Named { .. } => {
+                // Box the struct BY SHARED REFERENCE via `Value::from_struct_ref(&(..))`. Portable/GBA
+                // keeps it as a cheap `Value::Struct` (one `Rc` — the struct must be OWNED there, so it
+                // clones internally). Every other native backend serialises the borrow directly through
+                // `TishStruct::tish_to_object` (the ordered `object_from_pairs` boundary — see
+                // [`named_struct_to_object_expr`]) with NO whole-struct clone, byte-identical to the
+                // historical behaviour that read fields straight off the place (#565: the previous
+                // `from_struct((..).clone())` cloned the entire struct just to serialise it off-GBA).
+                // Property access on a boxed struct dispatches through the generated `impl TishStruct`
+                // (small match, no hash); materialisation is reached only on JSON.stringify / display /
+                // `Object.keys`-family / `for..in` / `in` / `Object.assign` / `{...s}` spread. `&(..)`
+                // borrows the place codegen already emits here (a value or a deref like `(*gs.borrow())`).
+                format!(
+                    "tishlang_runtime::Value::from_struct_ref(&({}))",
+                    native_expr
+                )
             }
             RustType::ShapeUnion { name, variants } => {
                 // union → boxed Value::Object: one match arm per variant, delegating to that
@@ -534,6 +680,31 @@ pub fn named_struct_ident(tish_name: &str) -> String {
     format!("TishStruct_{}", tish_name)
 }
 
+/// Build the `Value::object_from_pairs([...])` that materialises a Named struct at `native_expr` into
+/// an ORDERED boxed object (field-declaration = JS insertion order — deterministic, unlike an AHashMap
+/// insert). This was the body of `to_value_expr`'s `Named` arm; it now backs the generated
+/// `TishStruct::tish_to_object` (the JSON / display / `Object.keys`-family / `for..in` / `in` /
+/// `Object.assign` / `{...s}` spread materialisation, and the non-portable
+/// `Value::from_struct` fallback), while the live boxing path emits the cheap by-ref `Value::from_struct`.
+pub fn named_struct_to_object_expr(fields: &[(Arc<str>, RustType)], native_expr: &str) -> String {
+    let pairs = fields
+        .iter()
+        .map(|(k, ty)| {
+            let access = format!("{}.{}", native_expr, field_ident(k));
+            // A `Value`-typed field must be cloned (not `Copy`, and `to_value_expr(Value)` is identity);
+            // native field types clone/copy inside their own `to_value_expr`.
+            let v_expr = if matches!(ty, RustType::Value) {
+                format!("{}.clone()", access)
+            } else {
+                ty.to_value_expr(&access)
+            };
+            format!("(::std::sync::Arc::from({:?}), {})", k.as_ref(), v_expr)
+        })
+        .collect::<Vec<_>>()
+        .join(", ");
+    format!("Value::object_from_pairs([{}])", pairs)
+}
+
 /// #179 Stage B: map a shape-union alias to the generated Rust enum identifier.
 pub fn shape_union_enum_ident(tish_name: &str) -> String {
     format!("TishUnion_{}", tish_name)

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_556_param_name_collision.rs

@@ -0,0 +1,40 @@
+//! tishlang/tish#556 — a top-level MUTABLE var captured by a closure becomes a `VmRef` cell; if its
+//! name matches an imported/other function's PARAMETER, a reference to the parameter inside that
+//! function must resolve to the parameter, NOT a `vm_read` of the outer cell (which emits
+//! `vm_read(&param)` — a `&Value` where a `&VmRef` is wanted, so the generated Rust won't compile).
+//! The bug bit the GBA backend; guard both emit modes.
+use std::collections::HashSet;
+use std::path::PathBuf;
+use tishlang_compile::{compile_project_full_emit, NativeEmitMode};
+
+fn compile(rel: &str, mode: NativeEmitMode) -> String {
+    let manifest = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    let path = manifest.join("../..").join(rel).canonicalize().unwrap();
+    let caps: HashSet<String> = HashSet::new();
+    compile_project_full_emit(&path, path.parent(), &[], true, mode, Some(&caps))
+        .unwrap()
+        .0
+}
+
+#[test]
+fn param_shadows_outer_cell_not_read_via_vm_read() {
+    let rel = "crates/tish_compile/tests/regression/name_collision_main.tish";
+    for mode in [NativeEmitMode::DesktopBin, NativeEmitMode::Gba] {
+        let rust = compile(rel, mode);
+        // The bug: inside `loadScene`, calling the `scene` PARAMETER (`scene(1)`) compiled the callee
+        // as `vm_read(&scene)` — a read of the outer `VmRef` cell, i.e. `&Value` where a `&VmRef` is
+        // wanted (won't compile). The param must be used directly instead. (A plain `vm_read(&scene)`
+        // still legitimately appears where `bump` mutates the real outer cell, so we target this
+        // exact param-as-callee shape.)
+        assert!(
+            !rust.contains("_callee = (tishlang_runtime::vm_read(&scene))"),
+            "#556 ({mode:?}): `loadScene`'s `scene` parameter must shadow the outer cell — a call to \
+             it must not read `vm_read(&scene)`\n{rust}"
+        );
+        // The outer cell itself is still legitimately a real `VmRef` where `bump` mutates it.
+        assert!(
+            rust.contains("scene.borrow_mut()"),
+            "#556 ({mode:?}): expected the outer captured `scene` to remain a real `VmRef` cell\n{rust}"
+        );
+    }
+}

package/crates/tish_compile/tests/regr_558_struct_array_write.rs

@@ -0,0 +1,65 @@
+//! tishlang/tish#558 — a typed `Vec<struct>` element field write (`arr[i].field = v`) must lower to
+//! a NATIVE store into the Vec element, not a `set_prop` on a throwaway `Value::object_from_pairs`
+//! copy of the element (which silently discards the write). Regressed the module-level array and the
+//! local array; both are covered here.
+use std::collections::HashSet;
+use std::path::PathBuf;
+use tishlang_compile::{compile_project_full, compile_project_full_emit, NativeEmitMode};
+
+fn compile(rel: &str) -> String {
+    let manifest = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    let path = manifest.join("../..").join(rel).canonicalize().unwrap();
+    compile_project_full(&path, path.parent(), &[], true).unwrap().0
+}
+
+fn compile_gba(rel: &str) -> String {
+    let manifest = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    let path = manifest.join("../..").join(rel).canonicalize().unwrap();
+    let caps: HashSet<String> = HashSet::new();
+    compile_project_full_emit(&path, path.parent(), &[], true, NativeEmitMode::Gba, Some(&caps))
+        .unwrap()
+        .0
+}
+
+#[test]
+fn gba_struct_write_is_a_fully_native_i32_store() {
+    // On the GBA target a `: i32` struct field is a native `i32`, so the write is a single-word store
+    // into the Vec element — the whole point of typed struct arrays for hot AI loops. Guard that the
+    // perf win is maximal there: no `Value`, no `set_prop`, no per-write allocation.
+    let rust = compile_gba("crates/tish_compile/tests/regression/struct_array_write.tish");
+    assert!(
+        rust.contains("pub x: i32"),
+        "expected the `: i32` field to be a native i32 on the GBA target\n{rust}"
+    );
+    assert!(
+        rust.contains("arr[(0_f64) as usize].x = (200_f64) as i32"),
+        "#558: expected a fully-native i32 element store on GBA\n{rust}"
+    );
+    assert!(
+        !rust.contains("set_prop(&(Value::object_from_pairs"),
+        "#558: the GBA struct write must not box + set_prop on a throwaway copy\n{rust}"
+    );
+}
+
+#[test]
+fn struct_array_write_is_a_native_store_not_a_discarded_copy() {
+    let rust = compile("crates/tish_compile/tests/regression/struct_array_write.tish");
+
+    // The write must NOT build a throwaway object and set_prop on it — that mutates a copy and
+    // discards the store. This exact shape is what the bug emitted.
+    assert!(
+        !rust.contains("set_prop(&(Value::object_from_pairs"),
+        "#558: `arr[i].field = v` must not set_prop on a throwaway object_from_pairs copy\n{rust}"
+    );
+
+    // It must instead be a direct field store into the Vec element (module-level `arr` here).
+    assert!(
+        rust.contains("arr[(0_f64) as usize].x ="),
+        "#558: expected a native `arr[(0_f64) as usize].x = …` store into the Vec element\n{rust}"
+    );
+    // …and the local array `es` inside the function.
+    assert!(
+        rust.contains("es[(0_f64) as usize].x ="),
+        "#558: expected a native `es[(0_f64) as usize].x = …` store into the local Vec element\n{rust}"
+    );
+}

package/crates/tish_compile/tests/regr_558b_struct_field_read.rs

@@ -0,0 +1,21 @@
+//! tishlang/tish#558 residual — a struct-field read from a Vec element in a value/return position must
+//! clone a non-Copy field instead of moving it out of the borrowed element (E0507).
+use std::path::PathBuf;
+use tishlang_compile::compile_project_full;
+
+fn compile(rel: &str) -> String {
+    let manifest = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    let path = manifest.join("../..").join(rel).canonicalize().unwrap();
+    compile_project_full(&path, path.parent(), &[], true).unwrap().0
+}
+
+#[test]
+fn struct_field_read_from_vec_element_clones_non_copy() {
+    let rust = compile("crates/tish_compile/tests/regression/struct_field_return_read.tish");
+    // Off-GBA the `: i32` field is a boxed `Value` (non-Copy); the read must clone it out of the
+    // borrowed `es[0]`, not move it.
+    assert!(
+        rust.contains("es[(0_f64) as usize]).x.clone()"),
+        "#558 residual: `es[0].x` read must clone the non-Copy field out of the borrowed element\n{rust}"
+    );
+}