@tishlang/tish-format 2.39.0 → 3.0.0

package/crates/tish_core/src/value.rs

@@ -1,12 +1,20 @@
 //! Unified Value type for Tish runtime values.
 
-use std::sync::atomic::{AtomicU64, Ordering};
-use std::sync::Arc;
-
-use ahash::AHashMap;
+use crate::compat::{AHashMap, ArcStr, AtomicU64, Arc, Ordering, RandomState};
 use indexmap::IndexMap;
 use smallvec::SmallVec;
 
+#[cfg(feature = "portable")]
+use alloc::{
+    boxed::Box,
+    format,
+    string::{String, ToString},
+    vec,
+    vec::Vec,
+};
+#[cfg(feature = "portable")]
+use crate::compat::FloatExt;
+
 use crate::vmref::VmRef;
 
 /// Property map for objects and other `Arc<str>` → `Value` tables (VM globals, scopes).
@@ -75,12 +83,12 @@ use fancy_regex::Regex;
 pub trait Callable: Send + Sync {
     fn call(&self, args: &[Value]) -> Value;
     /// Downcast hook for the VM frame path; native adapters return themselves (downcast fails).
-    fn as_any(&self) -> &dyn std::any::Any;
+    fn as_any(&self) -> &dyn core::any::Any;
 }
 #[cfg(not(feature = "send-values"))]
 pub trait Callable {
     fn call(&self, args: &[Value]) -> Value;
-    fn as_any(&self) -> &dyn std::any::Any;
+    fn as_any(&self) -> &dyn core::any::Any;
 }
 
 /// Adapter wrapping a plain `Fn` closure (every native builtin) as a [`Callable`].
@@ -91,7 +99,7 @@ impl<F: Fn(&[Value]) -> Value + Send + Sync + 'static> Callable for FnCallable<F
     fn call(&self, args: &[Value]) -> Value {
         (self.0)(args)
     }
-    fn as_any(&self) -> &dyn std::any::Any {
+    fn as_any(&self) -> &dyn core::any::Any {
         self
     }
 }
@@ -101,7 +109,7 @@ impl<F: Fn(&[Value]) -> Value + 'static> Callable for FnCallable<F> {
     fn call(&self, args: &[Value]) -> Value {
         (self.0)(args)
     }
-    fn as_any(&self) -> &dyn std::any::Any {
+    fn as_any(&self) -> &dyn core::any::Any {
         self
     }
 }
@@ -109,7 +117,7 @@ impl<F: Fn(&[Value]) -> Value + 'static> Callable for FnCallable<F> {
 #[cfg(feature = "send-values")]
 pub type NativeFn = Arc<dyn Callable>;
 #[cfg(not(feature = "send-values"))]
-pub type NativeFn = std::rc::Rc<dyn Callable>;
+pub type NativeFn = alloc::rc::Rc<dyn Callable>;
 
 /// Build a raw [`NativeFn`] from a plain closure (wraps it in [`FnCallable`]). For sites that
 /// need a `NativeFn` handle directly rather than a `Value::Function` (e.g. HTTP/promise/timer
@@ -120,7 +128,7 @@ pub fn native_fn<F: Fn(&[Value]) -> Value + Send + Sync + 'static>(f: F) -> Nati
 }
 #[cfg(not(feature = "send-values"))]
 pub fn native_fn<F: Fn(&[Value]) -> Value + 'static>(f: F) -> NativeFn {
-    std::rc::Rc::new(FnCallable(f))
+    alloc::rc::Rc::new(FnCallable(f))
 }
 
 /// Trait for opaque Rust types exposed to Tish (e.g. Polars DataFrame).
@@ -141,7 +149,7 @@ pub trait TishOpaque: Send + Sync {
     fn get_method(&self, name: &str) -> Option<NativeFn>;
 
     /// For downcasting `Arc<dyn TishOpaque>` in native crates (e.g. Polars → `DataFrame`).
-    fn as_any(&self) -> &dyn std::any::Any;
+    fn as_any(&self) -> &dyn core::any::Any;
 }
 
 /// Single-threaded variant (no `Send + Sync` bound); see the `send-values` doc above.
@@ -154,13 +162,42 @@ pub trait TishOpaque {
     fn get_method(&self, name: &str) -> Option<NativeFn>;
 
     /// For downcasting `Arc<dyn TishOpaque>` in native crates (e.g. Polars → `DataFrame`).
-    fn as_any(&self) -> &dyn std::any::Any;
+    fn as_any(&self) -> &dyn core::any::Any;
+}
+
+/// A typed native struct (from an `interface` / typed object literal in native codegen) carried inside
+/// a [`Value::Struct`] WITHOUT serialising to a hashmap object. Each generated `TishStruct_*` implements
+/// it: a boxed function that returns/passes a typed struct keeps it by reference, property access
+/// dispatches here (a small `match` on the field name — no string hash, no allocation), and it
+/// materialises to a real `Value::Object` only when a boxed `Value::Struct` (a struct whose static
+/// type was erased) crosses into genuinely dynamic territory (`JSON.stringify`, display,
+/// `Object.keys`/`values`/`entries`, `for..in`, `in`, `Object.assign`, object-literal spread `{...s}`).
+/// This is the RUNTIME fallback: when the struct's static type IS known at a reflection site, GBA
+/// codegen lowers `Object.keys`/`values`/`entries`/`in`/`{...s}` to native field reads instead — the
+/// struct is never boxed and this materialisation never runs. No `Send + Sync` bound: the `Value::Struct` variant is
+/// `cfg(portable)` and `portable` excludes `send-values` (they are mutually exclusive), so the ref is
+/// single-threaded `Rc` — mirroring the single-threaded [`TishOpaque`].
+pub trait TishStruct {
+    /// Read a field as a boxed `Value` (`Null` if `key` is not a field). Backs `get_prop`.
+    fn tish_get(&self, key: &str) -> Value;
+    /// Write a field from a boxed `Value` (no-op if `key` is not a field). Backs `set_prop`.
+    fn tish_set(&mut self, key: &str, value: Value);
+    /// Materialise an ordered `Value::Object` copy (field-declaration order, JS insertion order). Used
+    /// for JSON / display / `Object`-interop, and as the non-portable `Value::from_struct` fallback so
+    /// off-GBA backends behave EXACTLY as the historical `object_from_pairs` boundary did.
+    fn tish_to_object(&self) -> Value;
+    /// `typeof` result — always "object".
+    fn tish_type_name(&self) -> &'static str {
+        "object"
+    }
+    /// Downcast hook — recover the concrete `TishStruct_*` (e.g. for a future typed fast path).
+    fn as_any(&self) -> &dyn core::any::Any;
 }
 
 /// Trait for Promise-like values that can be awaited (block until settled).
 /// Implemented by the runtime for native compile; interpreter uses its own Promise.
 pub trait TishPromise: Send + Sync {
-    fn block_until_settled(&self) -> std::result::Result<Value, Value>;
+    fn block_until_settled(&self) -> core::result::Result<Value, Value>;
     /// Try to settle WITHOUT blocking. Returns `Some(result)` if the promise was already
     /// settled before this call; returns `None` if it is still pending (a background thread
     /// / I/O task has not completed yet). Default: always pending — implementors of async
@@ -169,7 +206,7 @@ pub trait TishPromise: Send + Sync {
     /// Used by `race`/`any`/`allSettled` to handle already-settled promises in input-order
     /// (deterministic, JS-compatible) before falling back to concurrent thread waiting for
     /// genuinely-pending ones.
-    fn try_settle(&self) -> Option<std::result::Result<Value, Value>> {
+    fn try_settle(&self) -> Option<core::result::Result<Value, Value>> {
         None
     }
 }
@@ -236,8 +273,8 @@ impl RegExpFlags {
 }
 
 #[cfg(feature = "regex")]
-impl std::fmt::Display for RegExpFlags {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+impl core::fmt::Display for RegExpFlags {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         if self.global {
             f.write_str("g")?;
         }
@@ -344,20 +381,111 @@ impl TishRegExp {
 /// **Thread safety**: `Value: Send + Sync`. Mutable payloads live inside
 /// [`VmRef`], a `Send + Sync` `Arc<Mutex<T>>` wrapper that preserves the
 /// `RefCell`-style borrow API. Functions are `Arc<dyn Fn + Send + Sync>`.
+/// Backing store for a [`Value::NumberArray`] (#199 packed arrays). Starts `Packed`; a mutation
+/// that would introduce a non-numeric element upgrades it to `Boxed` **in place** via
+/// [`NumArrayBacking::deopt`], so all aliases sharing the `VmRef` observe the change (#506).
+///
+/// Access rules that keep the two arms sound at every call site:
+/// - single-element read → [`get`](Self::get) (O(1), no alloc);
+/// - iterate/snapshot as `Value`s → [`to_values`](Self::to_values) (Packed boxes each f64, same
+///   cost the old `materialize` path paid);
+/// - hot packed-only fast path (sort/fold/`sum`) → [`as_packed`](Self::as_packed) /
+///   [`as_packed_mut`](Self::as_packed_mut), which return `None` after a deopt so the caller falls
+///   back to the boxed path instead of assuming `Vec<f64>`.
+#[derive(Clone, Debug)]
+pub enum NumArrayBacking {
+    Packed(Vec<f64>),
+    Boxed(Vec<Value>),
+}
+
+impl NumArrayBacking {
+    #[inline]
+    pub fn len(&self) -> usize {
+        match self {
+            NumArrayBacking::Packed(v) => v.len(),
+            NumArrayBacking::Boxed(v) => v.len(),
+        }
+    }
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+    /// Element `i` as a `Value` (Packed: `Number(n)`, NaN kept as `Number(NaN)` — the hole-as-null
+    /// rule is applied by the specific read sites that want it, preserving current per-site
+    /// behavior). `None` if out of bounds.
+    #[inline]
+    pub fn get(&self, i: usize) -> Option<Value> {
+        match self {
+            NumArrayBacking::Packed(v) => v.get(i).map(|n| Value::Number(*n)),
+            NumArrayBacking::Boxed(v) => v.get(i).cloned(),
+        }
+    }
+    /// Snapshot the whole array as boxed `Value`s (Packed boxes each `f64`).
+    #[inline]
+    pub fn to_values(&self) -> Vec<Value> {
+        match self {
+            NumArrayBacking::Packed(v) => v.iter().map(|n| Value::Number(*n)).collect(),
+            NumArrayBacking::Boxed(v) => v.clone(),
+        }
+    }
+    /// The packed `f64` slice, iff still packed (hot fast paths); `None` once deopted.
+    #[inline]
+    pub fn as_packed(&self) -> Option<&Vec<f64>> {
+        match self {
+            NumArrayBacking::Packed(v) => Some(v),
+            NumArrayBacking::Boxed(_) => None,
+        }
+    }
+    #[inline]
+    pub fn as_packed_mut(&mut self) -> Option<&mut Vec<f64>> {
+        match self {
+            NumArrayBacking::Packed(v) => Some(v),
+            NumArrayBacking::Boxed(_) => None,
+        }
+    }
+    /// The boxed slice, iff already deopted.
+    #[inline]
+    pub fn as_boxed(&self) -> Option<&Vec<Value>> {
+        match self {
+            NumArrayBacking::Boxed(v) => Some(v),
+            NumArrayBacking::Packed(_) => None,
+        }
+    }
+    /// Upgrade to a boxed backing **in place** (idempotent) and return `&mut` to the boxed `Vec`.
+    /// Every alias sharing this cell now sees a boxed array (#506). Packed `f64`s become
+    /// `Number(n)` (NaN preserved), so a read after deopt matches what the packed form returned.
+    #[inline]
+    pub fn deopt(&mut self) -> &mut Vec<Value> {
+        if let NumArrayBacking::Packed(v) = self {
+            let boxed = v.iter().map(|n| Value::Number(*n)).collect();
+            *self = NumArrayBacking::Boxed(boxed);
+        }
+        match self {
+            NumArrayBacking::Boxed(v) => v,
+            NumArrayBacking::Packed(_) => unreachable!("just deopted"),
+        }
+    }
+}
+
 #[derive(Clone, Default)]
 pub enum Value {
     Number(f64),
-    String(arcstr::ArcStr),
+    String(ArcStr),
     Bool(bool),
     #[default]
     Null,
     Array(VmRef<Vec<Value>>),
-    /// Packed f64 array — `TISH_PACKED_ARRAYS` mode only. All elements are f64; a non-numeric
-    /// push/set/op materializes to `Value::Array` first. Eliminates per-element boxing and
-    /// enables direct `sort_unstable_by` without an unbox pass. Created by all-numeric array
-    /// literals, `new Array(n)` (zero-filled), and from numeric HOF results. Never created
-    /// when `packed_arrays_enabled()` is false — callers check before constructing.
-    NumberArray(VmRef<Vec<f64>>),
+    /// Numeric-origin array — `TISH_PACKED_ARRAYS` mode only. Starts `Packed` (a `Vec<f64>`, no
+    /// per-element boxing; enables direct `sort_unstable_by` and unboxed folds). A mutation that
+    /// introduces a **non-numeric** value ([`NumArrayBacking::deopt`]) upgrades the backing to
+    /// `Boxed` IN PLACE, so every alias sharing this `VmRef` observes the transition (#506) — the
+    /// value stays a `NumberArray` (aliases can't be rewritten to `Array`), but its backing is now
+    /// a `Vec<Value>` and it behaves exactly like a boxed array. So the tag means "numeric-origin,
+    /// possibly deopted"; access goes through the [`NumArrayBacking`] accessors, never a raw
+    /// `Vec<f64>` assumption. Created by all-numeric array literals, `new Array(n)` (zero-filled),
+    /// numeric HOF results, and typed arrays. Never created when `packed_arrays_enabled()` is
+    /// false — callers check before constructing.
+    NumberArray(VmRef<NumArrayBacking>),
     Object(VmRef<ObjectData>),
     /// ECMAScript-style primitive symbol (identity by `Arc`).
     Symbol(Arc<TishSymbol>),
@@ -368,8 +496,24 @@ pub enum Value {
     Promise(Arc<dyn TishPromise>),
     /// Opaque handle to a native Rust type (e.g. Polars DataFrame).
     Opaque(Arc<dyn TishOpaque>),
+    /// A typed native struct carried BY REFERENCE (portable / GBA native codegen). Lets a boxed
+    /// function return or pass a typed struct without serialising it to a hashmap `Object` —
+    /// property access dispatches through [`TishStruct`] (a small match, no hash lookup / alloc), and
+    /// it materialises to an `Object` only on JSON / display / `Object.keys`-family / `for..in` /
+    /// `in` / `Object.assign` / `{...s}` spread. Built via
+    /// [`Value::from_struct`]. Portable-only: the ref is a single-threaded `Rc<RefCell<dyn …>>` and
+    /// `portable` excludes `send-values`, so this never violates `Send` (which off-portable `Value`
+    /// may need). A fat pointer is 16 B, so the 24 B `Value` size guard still holds.
+    #[cfg(feature = "portable")]
+    Struct(StructRef),
 }
 
+/// Reference to a boxed typed struct: `Rc<RefCell<dyn TishStruct>>`. Portable-only (see [`TishStruct`]
+/// / [`Value::Struct`]). `RefCell` is OUTSIDE the trait object so `set_prop` can borrow it mutably; the
+/// `Rc<RefCell<Concrete>> → Rc<RefCell<dyn TishStruct>>` unsizing is a stable coercion (no nightly).
+#[cfg(feature = "portable")]
+pub type StructRef = alloc::rc::Rc<core::cell::RefCell<dyn TishStruct>>;
+
 // Size guard. `Value` is 24 bytes: `String` is thin (`ArcStr`, 8B), but `Function`/`Promise`/`Opaque`
 // are fat `Arc<dyn …>` (data+vtable, 16B) ⇒ 16B payload + discriminant = 24.
 //
@@ -381,7 +525,7 @@ pub enum Value {
 // re-attempt the box trick; only a dispatch-level change (e.g. NaN-box's branch-free tag test, not
 // its size) could pay off. Gated to 64-bit: wasm32 (wasi) has 32-bit pointers, so size differs there.
 #[cfg(target_pointer_width = "64")]
-const _: () = assert!(std::mem::size_of::<Value>() == 24);
+const _: () = assert!(core::mem::size_of::<Value>() == 24);
 
 // ─────────────────────────────────────────────────────────────────────────────
 // #201 Stage A — representation abstraction (behavior-preserving, zero perf effect).
@@ -414,6 +558,8 @@ pub enum ValueTag {
     RegExp,
     Promise,
     Opaque,
+    #[cfg(feature = "portable")]
+    Struct,
 }
 
 /// Borrowed view of a [`Value`]'s payload, mirroring the enum variants. Lets call sites
@@ -422,11 +568,11 @@ pub enum ValueTag {
 /// sites. Zero-cost — each arm borrows the existing payload in place.
 pub enum ValueRef<'a> {
     Number(f64),
-    String(&'a arcstr::ArcStr),
+    String(&'a ArcStr),
     Bool(bool),
     Null,
     Array(&'a VmRef<Vec<Value>>),
-    NumberArray(&'a VmRef<Vec<f64>>),
+    NumberArray(&'a VmRef<NumArrayBacking>),
     Object(&'a VmRef<ObjectData>),
     Symbol(&'a Arc<TishSymbol>),
     Function(&'a NativeFn),
@@ -434,6 +580,8 @@ pub enum ValueRef<'a> {
     RegExp(&'a VmRef<TishRegExp>),
     Promise(&'a Arc<dyn TishPromise>),
     Opaque(&'a Arc<dyn TishOpaque>),
+    #[cfg(feature = "portable")]
+    Struct(&'a StructRef),
 }
 
 impl Value {
@@ -452,7 +600,7 @@ impl Value {
     /// Named constructor for a string (#201 abstraction). Accepts anything that converts
     /// into the interned `ArcStr` (`&str`, `String`, `ArcStr`).
     #[inline]
-    pub fn string(s: impl Into<arcstr::ArcStr>) -> Self {
+    pub fn string(s: impl Into<ArcStr>) -> Self {
         Value::String(s.into())
     }
 
@@ -479,6 +627,8 @@ impl Value {
             Value::RegExp(r) => ValueRef::RegExp(r),
             Value::Promise(p) => ValueRef::Promise(p),
             Value::Opaque(o) => ValueRef::Opaque(o),
+            #[cfg(feature = "portable")]
+            Value::Struct(s) => ValueRef::Struct(s),
         }
     }
 
@@ -499,6 +649,8 @@ impl Value {
             Value::RegExp(_) => ValueTag::RegExp,
             Value::Promise(_) => ValueTag::Promise,
             Value::Opaque(_) => ValueTag::Opaque,
+            #[cfg(feature = "portable")]
+            Value::Struct(_) => ValueTag::Struct,
         }
     }
 
@@ -540,7 +692,7 @@ impl Value {
 
     /// Borrow the packed-number-array payload, if this is a `NumberArray`.
     #[inline]
-    pub fn as_number_array(&self) -> Option<&VmRef<Vec<f64>>> {
+    pub fn as_number_array(&self) -> Option<&VmRef<NumArrayBacking>> {
         match self {
             Value::NumberArray(a) => Some(a),
             _ => None,
@@ -571,7 +723,7 @@ const PROPMAP_INLINE: usize = 8;
 #[derive(Clone, Debug, Default)]
 pub struct PropMap {
     inline: SmallVec<[(Arc<str>, Value); PROPMAP_INLINE]>,
-    map: Option<Box<IndexMap<Arc<str>, Value, ahash::RandomState>>>,
+    map: Option<Box<IndexMap<Arc<str>, Value, RandomState>>>,
     /// Hidden-class identity for this object's ordered key-set (JSC Structure). `EMPTY_SHAPE` (0)
     /// for `{}`. Maintained by `insert` (new key → `shape::transition`) and reset to `DICT_SHAPE` by
     /// `remove`. Lets the VM's inline caches compare a `u32` instead of hashing a key. INVARIANT: a
@@ -592,7 +744,7 @@ impl PropMap {
                 inline: SmallVec::new(),
                 map: Some(Box::new(IndexMap::with_capacity_and_hasher(
                     n,
-                    ahash::RandomState::default(),
+                    RandomState::default(),
                 ))),
                 shape: crate::shape::EMPTY_SHAPE,
             }
@@ -693,15 +845,15 @@ impl PropMap {
         }
         if let Some(slot) = self.inline.iter_mut().find(|(k, _)| k.as_ref() == key.as_ref()) {
             // Update existing key → value changes, layout (shape) does not.
-            return Some(std::mem::replace(&mut slot.1, val));
+            return Some(core::mem::replace(&mut slot.1, val));
         }
         // New key (inline storage) → transition the shape away from the current one.
         self.shape = crate::shape::transition(self.shape, &key);
         if self.inline.len() >= PROPMAP_INLINE {
             // Promote inline storage to an insertion-ordered map (keys + their order are preserved,
             // so the shape stays valid).
-            let mut m: IndexMap<Arc<str>, Value, ahash::RandomState> =
-                IndexMap::with_capacity_and_hasher(self.inline.len() + 1, ahash::RandomState::default());
+            let mut m: IndexMap<Arc<str>, Value, RandomState> =
+                IndexMap::with_capacity_and_hasher(self.inline.len() + 1, RandomState::default());
             for (k, v) in self.inline.drain(..) {
                 m.insert(k, v);
             }
@@ -778,9 +930,9 @@ impl PropMap {
         // If the combined worst-case size escapes inline storage, promote once up front so the
         // per-key inserts below never reallocate or re-promote.
         if self.map.is_none() && self.inline.len() + incoming > PROPMAP_INLINE {
-            let mut m: IndexMap<Arc<str>, Value, ahash::RandomState> = IndexMap::with_capacity_and_hasher(
+            let mut m: IndexMap<Arc<str>, Value, RandomState> = IndexMap::with_capacity_and_hasher(
                 self.inline.len() + incoming,
-                ahash::RandomState::default(),
+                RandomState::default(),
             );
             for (k, v) in self.inline.drain(..) {
                 m.insert(k, v);
@@ -826,7 +978,7 @@ impl IntoIterator for PropMap {
 
 /// Zero-allocation borrowing iterator over [`PropMap`] entries (insertion order).
 pub enum PropMapIter<'a> {
-    Inline(std::slice::Iter<'a, (Arc<str>, Value)>),
+    Inline(core::slice::Iter<'a, (Arc<str>, Value)>),
     Map(indexmap::map::Iter<'a, Arc<str>, Value>),
 }
 impl<'a> Iterator for PropMapIter<'a> {
@@ -842,7 +994,7 @@ impl<'a> Iterator for PropMapIter<'a> {
 
 /// Zero-allocation key iterator over [`PropMap`] (insertion order).
 pub enum PropMapKeys<'a> {
-    Inline(std::slice::Iter<'a, (Arc<str>, Value)>),
+    Inline(core::slice::Iter<'a, (Arc<str>, Value)>),
     Map(indexmap::map::Keys<'a, Arc<str>, Value>),
 }
 impl<'a> Iterator for PropMapKeys<'a> {
@@ -858,7 +1010,7 @@ impl<'a> Iterator for PropMapKeys<'a> {
 
 /// Zero-allocation value iterator over [`PropMap`] (insertion order).
 pub enum PropMapValues<'a> {
-    Inline(std::slice::Iter<'a, (Arc<str>, Value)>),
+    Inline(core::slice::Iter<'a, (Arc<str>, Value)>),
     Map(indexmap::map::Values<'a, Arc<str>, Value>),
 }
 impl<'a> Iterator for PropMapValues<'a> {
@@ -894,6 +1046,10 @@ impl Iterator for PropMapIntoIter {
 pub struct ObjectData {
     pub strings: PropMap,
     pub symbols: Option<AHashMap<u64, Value>>,
+    /// `Object.freeze` marker (#437). When true, property writes must throw a catchable TypeError
+    /// instead of mutating — enforced at every write chokepoint (interp assign, vm `set_member`,
+    /// native `set_prop`). Reference-shared like the rest of the object; a fresh object is not frozen.
+    pub frozen: bool,
 }
 
 impl ObjectData {
@@ -902,9 +1058,16 @@ impl ObjectData {
         Self {
             strings: strings.into_iter().collect(),
             symbols: None,
+            frozen: false,
         }
     }
 
+    /// True if `Object.freeze` has been applied to this object.
+    #[inline]
+    pub fn is_frozen(&self) -> bool {
+        self.frozen
+    }
+
     #[inline]
     pub fn len_entries(&self) -> usize {
         self.strings.len() + self.symbols.as_ref().map(|s| s.len()).unwrap_or(0)
@@ -1084,15 +1247,15 @@ pub fn value_call(callee: &Value, args: &[Value]) -> Value {
                 return value_call(&inner, args);
             }
             crate::set_pending_throw(crate::not_a_function_error(format!(
-                "{} is not a function",
-                callee.to_display_string()
+                "Call of non-function: {}",
+                callee.type_name()
             )));
             Value::Null
         }
         _ => {
             crate::set_pending_throw(crate::not_a_function_error(format!(
-                "{} is not a function",
-                callee.to_display_string()
+                "Call of non-function: {}",
+                callee.type_name()
             )));
             Value::Null
         }
@@ -1118,11 +1281,15 @@ pub fn merge_object_data(left: &VmRef<ObjectData>, right: &VmRef<ObjectData>) ->
             None => symbols = Some(rs.clone()),
         }
     }
-    ObjectData { strings, symbols }
+    ObjectData {
+        strings,
+        symbols,
+        frozen: false,
+    }
 }
 
-impl std::fmt::Debug for Value {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+impl core::fmt::Debug for Value {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         match self {
             Value::Number(n) => write!(f, "Number({})", n),
             Value::String(s) => write!(f, "String({:?})", s.as_str()),
@@ -1142,6 +1309,8 @@ impl std::fmt::Debug for Value {
             ),
             Value::Promise(_) => write!(f, "Promise"),
             Value::Opaque(o) => write!(f, "{}(opaque)", o.type_name()),
+            #[cfg(feature = "portable")]
+            Value::Struct(s) => write!(f, "Struct({})", s.borrow().tish_type_name()),
         }
     }
 }
@@ -1242,7 +1411,7 @@ pub fn js_number_to_string_into(out: &mut String, value: f64) {
         end -= 1;
     }
     let trail = (n - end) as i32;
-    let digits = std::str::from_utf8(&digits_buf[lead..end]).expect("ascii digits");
+    let digits = core::str::from_utf8(&digits_buf[lead..end]).expect("ascii digits");
     let k = digits.len() as i32; // significant digit count (≤ 17 for an f64)
     let point = k + exp - frac_len + trail;
 
@@ -1318,8 +1487,12 @@ impl Value {
             Value::NumberArray(arr) => {
                 let inner: Vec<String> = arr
                     .borrow()
+                    .to_values()
                     .iter()
-                    .map(|&n| if n.is_nan() { "null".to_string() } else { Value::Number(n).to_display_string() })
+                    .map(|v| match v {
+                        Value::Number(n) if n.is_nan() => "null".to_string(),
+                        other => other.to_display_string(),
+                    })
                     .collect();
                 format!("[{}]", inner.join(", "))
             }
@@ -1348,6 +1521,9 @@ impl Value {
             Value::Function(_) => "[Function]".to_string(),
             Value::Promise(_) => "[object Promise]".to_string(),
             Value::Opaque(o) => format!("[object {}]", o.type_name()),
+            // Display a boxed struct like the object it is (materialise once, then reuse the Object path).
+            #[cfg(feature = "portable")]
+            Value::Struct(s) => s.borrow().tish_to_object().to_display_string_guarded(ancestors),
             #[cfg(feature = "regex")]
             Value::RegExp(re) => {
                 let re = re.borrow();
@@ -1393,11 +1569,14 @@ impl Value {
             }
             Value::NumberArray(arr) => arr
                 .borrow()
+                .to_values()
                 .iter()
-                .map(|n| Value::Number(*n).to_js_string())
+                .map(|v| v.to_js_string())
                 .collect::<Vec<_>>()
                 .join(","),
             Value::Object(_) => "[object Object]".to_string(),
+            #[cfg(feature = "portable")]
+            Value::Struct(_) => "[object Object]".to_string(),
             // ECMAScript ToString of a number (drops `-0`'s sign), distinct from the inspect form
             // that `to_display_string` would give for `-0`. (#247)
             Value::Number(n) => js_number_to_string(*n),
@@ -1436,12 +1615,16 @@ impl Value {
             #[cfg(feature = "send-values")]
             (Value::Function(a), Value::Function(b)) => Arc::ptr_eq(a, b),
             #[cfg(not(feature = "send-values"))]
-            (Value::Function(a), Value::Function(b)) => std::rc::Rc::ptr_eq(a, b),
+            (Value::Function(a), Value::Function(b)) => alloc::rc::Rc::ptr_eq(a, b),
             #[cfg(feature = "regex")]
             (Value::RegExp(a), Value::RegExp(b)) => VmRef::ptr_eq(a, b),
             (Value::Promise(a), Value::Promise(b)) => Arc::ptr_eq(a, b),
             (Value::Opaque(a), Value::Opaque(b)) => Arc::ptr_eq(a, b),
             (Value::Symbol(a), Value::Symbol(b)) => Arc::ptr_eq(a, b),
+            // Struct-Value identity is `Rc` pointer equality, exactly like `Object` — two distinct
+            // boxings compare unequal, but a struct aliased through one `Value` is `=== ` itself.
+            #[cfg(feature = "portable")]
+            (Value::Struct(a), Value::Struct(b)) => alloc::rc::Rc::ptr_eq(a, b),
             _ => false,
         }
     }
@@ -1465,7 +1648,7 @@ impl Value {
     where
         F: Fn(&[Value]) -> Value + 'static,
     {
-        Value::Function(std::rc::Rc::new(FnCallable(f)))
+        Value::Function(alloc::rc::Rc::new(FnCallable(f)))
     }
 
     /// Create a new array Value from a Vec.
@@ -1490,9 +1673,67 @@ impl Value {
         Value::Object(VmRef::new(ObjectData {
             strings,
             symbols: None,
+            frozen: false,
         }))
     }
 
+    /// Box a typed native struct (a generated `TishStruct_*`). On portable (GBA) it is kept BY
+    /// REFERENCE as a cheap [`Value::Struct`] — one `Rc` allocation, no per-field string keys / hashmap;
+    /// property access later dispatches through [`TishStruct`]. On every other backend it serialises to
+    /// an ordered `Value::Object` (via [`TishStruct::tish_to_object`]) — byte-identical to the historical
+    /// `object_from_pairs` boundary, so off-GBA behaviour is unchanged. Codegen's struct-to-`Value`
+    /// boxing emits a single `Value::from_struct(..)` call for all native targets.
+    #[cfg(feature = "portable")]
+    #[inline]
+    pub fn from_struct<T: TishStruct + 'static>(v: T) -> Value {
+        Value::Struct(alloc::rc::Rc::new(core::cell::RefCell::new(v)))
+    }
+    /// See the portable variant above — off-GBA this is exactly the old `object_from_pairs` boundary.
+    #[cfg(not(feature = "portable"))]
+    #[inline]
+    pub fn from_struct<T: TishStruct>(v: T) -> Value {
+        v.tish_to_object()
+    }
+
+    /// Box a typed native struct BY SHARED REFERENCE — the boxing path codegen actually emits, so the
+    /// whole-struct clone is paid ONLY where it's genuinely needed. On portable (GBA) the struct must
+    /// be OWNED by the `Rc`, so it clones (identical to `from_struct((v).clone())`). Off-GBA it
+    /// serialises the borrow directly via [`TishStruct::tish_to_object`] with NO whole-struct clone —
+    /// byte-identical to the historical `object_from_pairs` boundary that read fields straight off the
+    /// place (#565: the old `from_struct((v).clone())` cloned the entire struct just to serialise it).
+    #[cfg(feature = "portable")]
+    #[inline]
+    pub fn from_struct_ref<T: TishStruct + Clone + 'static>(v: &T) -> Value {
+        Value::Struct(alloc::rc::Rc::new(core::cell::RefCell::new(v.clone())))
+    }
+    /// See the portable variant — off-GBA this serialises the borrow with no whole-struct clone.
+    #[cfg(not(feature = "portable"))]
+    #[inline]
+    pub fn from_struct_ref<T: TishStruct>(v: &T) -> Value {
+        v.tish_to_object()
+    }
+
+    /// If this value is a by-reference boxed struct of concrete type `T` (a `Value::Struct`), return a
+    /// CLONE of it — the native fast path for `let x: T = <boxed struct return>`, so subsequent field
+    /// reads are plain Rust loads instead of `get_prop`. Portable only: off-GBA there is no `Value::Struct`
+    /// variant, so this is always `None` and codegen's `from_value_expr` falls back to the field-by-field
+    /// `get_prop` rebuild (which also handles a genuine `Value::Object`). Returns `None` for any non-struct
+    /// value or a struct of a different concrete type.
+    #[cfg(feature = "portable")]
+    #[inline]
+    pub fn downcast_struct<T: TishStruct + Clone + 'static>(&self) -> Option<T> {
+        match self {
+            Value::Struct(s) => s.borrow().as_any().downcast_ref::<T>().cloned(),
+            _ => None,
+        }
+    }
+    /// See the portable variant — off-GBA there is no struct variant, so always `None`.
+    #[cfg(not(feature = "portable"))]
+    #[inline]
+    pub fn downcast_struct<T: TishStruct + Clone + 'static>(&self) -> Option<T> {
+        None
+    }
+
     /// Create an empty array Value.
     pub fn empty_array() -> Self {
         Value::Array(VmRef::new(Vec::new()))
@@ -1509,6 +1750,7 @@ impl Value {
     /// process starts (as the CI sweep does); mid-process toggling is not observed by design.
     /// The flag is intentionally backwards from the slot/JIT flags (those were default-on) to
     /// keep the default binary behaviour byte-identical while we validate coverage.
+    #[cfg(not(feature = "portable"))]
     #[inline]
     pub fn packed_arrays_enabled() -> bool {
         static PACKED_ARRAYS: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
@@ -1517,10 +1759,18 @@ impl Value {
         })
     }
 
+    /// Packed f64 arrays are off under `portable` (no env to opt in; keeps the
+    /// generic array path, which the GBA runtime already exercises).
+    #[cfg(feature = "portable")]
+    #[inline]
+    pub fn packed_arrays_enabled() -> bool {
+        false
+    }
+
     /// Wrap a `Vec<f64>` as a `Value::NumberArray`. Only call when `packed_arrays_enabled()`.
     #[inline]
     pub fn number_array(items: Vec<f64>) -> Self {
-        Value::NumberArray(VmRef::new(items))
+        Value::NumberArray(VmRef::new(NumArrayBacking::Packed(items)))
     }
 
     /// Materialize a `Value::NumberArray` into a boxed `Value::Array`.
@@ -1529,9 +1779,8 @@ impl Value {
     /// converts once and continues on the generic path. The original `NumberArray` VmRef
     /// is consumed; callers replace the `Value` in whatever container held it.
     #[inline]
-    pub fn materialize_number_array(arr: &VmRef<Vec<f64>>) -> Value {
-        let nums = arr.borrow();
-        Value::Array(VmRef::new(nums.iter().map(|&n| Value::Number(n)).collect()))
+    pub fn materialize_number_array(arr: &VmRef<NumArrayBacking>) -> Value {
+        Value::Array(VmRef::new(arr.borrow().to_values()))
     }
 
     /// If `self` is a `NumberArray`, materialise and return `Value::Array`; otherwise
@@ -1572,6 +1821,8 @@ impl Value {
             Value::Promise(_) => "object",
             Value::Opaque(o) => o.type_name(),
             Value::Symbol(_) => "symbol",
+            #[cfg(feature = "portable")]
+            Value::Struct(_) => "object",
         }
     }