zexus 1.6.8 → 1.7.2

package/src/zexus/evaluator/statements.py

@@ -8,7 +8,8 @@ from ..zexus_ast import (
     TryCatchStatement, UseStatement, FromStatement, ExportStatement,
     ContractStatement, EntityStatement, VerifyStatement, ProtectStatement,
     SealStatement, MiddlewareStatement, AuthStatement, ThrottleStatement, CacheStatement,
-    ComponentStatement, ThemeStatement, DebugStatement, ExternalDeclaration, AssignmentExpression,
+    ComponentStatement, ThemeStatement, ColorStatement, CanvasStatement, GraphicsStatement,
+    AnimationStatement, ClockStatement, DebugStatement, ExternalDeclaration, AssignmentExpression,
     PrintStatement, ScreenStatement, EmbeddedCodeStatement, ExactlyStatement,
     Identifier, PropertyAccessExpression, RestrictStatement, SandboxStatement, TrailStatement,
     NativeStatement, GCStatement, InlineStatement, BufferStatement, SIMDStatement,
@@ -30,6 +31,24 @@ from ..security import (
     ProtectionPolicy, Middleware, AuthConfig, RateLimiter, CachePolicy
 )
 from .utils import is_error, debug_log, EVAL_SUMMARY, NULL, TRUE, FALSE, _resolve_awaitable, _zexus_to_python, _python_to_zexus, is_truthy
+from ..config import config as zexus_config
+
+try:
+    from ..renderer import (
+        create_named_canvas as renderer_create_named_canvas,
+        define_color as renderer_define_color,
+        register_animation as renderer_register_animation,
+        register_clock as renderer_register_clock,
+        register_graphics as renderer_register_graphics,
+    )
+    _RENDERER_AVAILABLE = True
+except Exception:  # pragma: no cover - renderer optional during bootstrap
+    renderer_create_named_canvas = None
+    renderer_define_color = None
+    renderer_register_animation = None
+    renderer_register_clock = None
+    renderer_register_graphics = None
+    _RENDERER_AVAILABLE = False
 
 # Break exception for loop control flow
 class BreakException:
@@ -37,9 +56,77 @@ class BreakException:
     def __repr__(self):
         return "BreakException()"
 
+class ContinueException:
+    """Exception raised when continue statement is encountered in a loop."""
+    def __repr__(self):
+        return "ContinueException()"
+
+
 class StatementEvaluatorMixin:
     """Handles evaluation of statements, flow control, module loading, and security features."""
     
+    def _statement_signature(self, stmt):
+        """Create a stable, cheap signature for tolerant duplicate-skipping.
+
+        The tolerant parser/recovery can sometimes enqueue duplicate statements.
+        For long files, calling ``str(stmt)`` for every statement can become
+        expensive because AST __repr__ often includes nested expressions.
+        Prefer source location (line/column) when available.
+        """
+        stmt_type = type(stmt).__name__
+        line = int(getattr(stmt, 'line', 0) or 0)
+        column = int(getattr(stmt, 'column', 0) or 0)
+
+        if line or column:
+            extra = ""
+            try:
+                if isinstance(stmt, ExpressionStatement):
+                    expr = getattr(stmt, "expression", None)
+                    func = getattr(expr, "function", None)
+                    if isinstance(func, Identifier) and getattr(func, "value", None):
+                        extra = f":{func.value}"
+            except Exception:
+                extra = ""
+            return f"{stmt_type}@{line}:{column}{extra}"
+
+        # Fallback: retain old behavior for nodes without location metadata.
+        try:
+            return str(stmt)
+        except Exception:
+            return f"{stmt_type}@{id(stmt)}"
+
+    def _enqueue_tolerant_duplicates(self, statements):
+        if not statements:
+            return
+
+        counts = getattr(self, "_tolerant_skip_counts", None)
+        if counts is None:
+            counts = {}
+            self._tolerant_skip_counts = counts
+
+        local_counts = {}
+        for stmt in statements:
+            if isinstance(stmt, ExpressionStatement):
+                expr = getattr(stmt, "expression", None)
+                func = getattr(expr, "function", None)
+                if (
+                    isinstance(func, Identifier)
+                    and getattr(func, "value", None) == "revert"
+                ):
+                    continue
+            sig = self._statement_signature(stmt)
+            local_counts[sig] = local_counts.get(sig, 0) + 1
+
+        duplicates_added = 0
+        for sig, occurrence in local_counts.items():
+            if occurrence > 1:
+                counts[sig] = counts.get(sig, 0) + (occurrence - 1)
+                duplicates_added += occurrence - 1
+
+        if duplicates_added:
+            if zexus_config.should_log('debug'):
+                print(f"[TOLERANT] enqueue {duplicates_added} duplicate statements")
+
     def ceval_program(self, statements, env):
         debug_log("eval_program", f"Processing {len(statements)} statements")
         
@@ -55,6 +142,23 @@ class StatementEvaluatorMixin:
         try:
             for i, stmt in enumerate(statements):
                 debug_log(f"  Statement {i+1}", type(stmt).__name__)
+                counts = getattr(self, "_tolerant_skip_counts", None)
+                if counts:
+                    signature = self._statement_signature(stmt)
+                    remaining = counts.get(signature, 0)
+                    if remaining > 0:
+                        if zexus_config.should_log('debug'):
+                            print(f"[TOLERANT] skipping program stmt {type(stmt).__name__} sig={signature} remaining={remaining}")
+                        if remaining == 1:
+                            counts.pop(signature, None)
+                        else:
+                            counts[signature] = remaining - 1
+                        continue
+                if (
+                    getattr(self, "_pending_revert_signature", None) is not None
+                    and not isinstance(stmt, RevertStatement)
+                ):
+                    self._pending_revert_signature = None
                 res = self.eval_node(stmt, env)
                 res = _resolve_awaitable(res)
                 EVAL_SUMMARY['evaluated_statements'] += 1
@@ -64,6 +168,14 @@ class StatementEvaluatorMixin:
                     # Execute deferred cleanup before returning
                     self._execute_deferred_cleanup(env, [])
                     return res.value
+                
+                # Check for ContinueException (Top-Level = Enable Error Recovery)
+                if isinstance(res, ContinueException):
+                    self.continue_on_error = True
+                    debug_log("ceval_program", "Enabling error recovery mode via continue")
+                    result = NULL
+                    continue
+
                 if is_error(res):
                     debug_log("  Error encountered", res)
                     try:
@@ -76,7 +188,8 @@ class StatementEvaluatorMixin:
                         # Log the error and continue execution
                         error_msg = str(res)
                         self.error_log.append(error_msg)
-                        print(f"[ERROR] {error_msg}")
+                        if zexus_config.should_log('error'):
+                            print(f"[ERROR] {error_msg}")
                         debug_log("  Continuing after error", "continue_on_error=True")
                         result = NULL  # Continue with null result
                         continue
@@ -106,11 +219,23 @@ class StatementEvaluatorMixin:
         result = NULL
         try:
             for stmt in block.statements:
+                counts = getattr(self, "_tolerant_skip_counts", None)
+                if counts:
+                    signature = self._statement_signature(stmt)
+                    remaining = counts.get(signature, 0)
+                    if remaining > 0:
+                        if zexus_config.should_log('debug'):
+                            print(f"[TOLERANT] skipping block stmt {type(stmt).__name__} sig={signature} remaining={remaining}")
+                        if remaining == 1:
+                            counts.pop(signature, None)
+                        else:
+                            counts[signature] = remaining - 1
+                        continue
                 res = self.eval_node(stmt, env, stack_trace)
                 res = _resolve_awaitable(res)
                 EVAL_SUMMARY['evaluated_statements'] += 1
                 
-                if isinstance(res, (ReturnValue, BreakException, EvaluationError)):
+                if isinstance(res, (ReturnValue, BreakException, ContinueException, EvaluationError)):
                     debug_log("  Block interrupted", res)
                     if is_error(res):
                         try:
@@ -123,7 +248,8 @@ class StatementEvaluatorMixin:
                             # Log the error and continue execution
                             error_msg = str(res)
                             self.error_log.append(error_msg)
-                            print(f"[ERROR] {error_msg}")
+                            if zexus_config.should_log('error'):
+                                print(f"[ERROR] {error_msg}")
                             debug_log("  Continuing after error in block", "continue_on_error=True")
                             result = NULL  # Continue with null result
                             continue
@@ -142,23 +268,124 @@ class StatementEvaluatorMixin:
             self._execute_deferred_cleanup(env, stack_trace)
             # Restore stdout to previous state (scope-aware)
             self._restore_stdout(env)
-    
+
+    # ------------------------------------------------------------------
+    # Renderer helpers
+    # ------------------------------------------------------------------
+    def _evaluate_renderer_block(self, block, env, stack_trace):
+        local_env = Environment(outer=env)
+        result = self.eval_block_statement(block, local_env, list(stack_trace) if stack_trace else [])
+
+        if isinstance(result, ReturnValue):
+            result = result.value
+        if is_error(result):
+            return result
+
+        collected = {}
+        for key, value in local_env.store.items():
+            if key.startswith("__"):
+                continue
+            collected[key] = value
+        return collected
+
+    def _evaluate_renderer_properties(self, prop_node, env, stack_trace):
+        if prop_node is None:
+            return None
+
+        if isinstance(prop_node, list):
+            values = []
+            for expr in prop_node:
+                val = self.eval_node(expr, env, stack_trace)
+                val = _resolve_awaitable(val)
+                if isinstance(val, ReturnValue):
+                    val = val.value
+                if is_error(val):
+                    return val
+                values.append(_zexus_to_python(val))
+            return values
+
+        if isinstance(prop_node, BlockStatement):
+            bindings = self._evaluate_renderer_block(prop_node, env, stack_trace)
+            if is_error(bindings):
+                return bindings
+            return {key: _zexus_to_python(val) for key, val in bindings.items()}
+
+        val = self.eval_node(prop_node, env, stack_trace)
+        val = _resolve_awaitable(val)
+        if isinstance(val, ReturnValue):
+            val = val.value
+        if is_error(val):
+            return val
+        return _zexus_to_python(val)
+
     def eval_expression_statement(self, node, env, stack_trace):
         # Debug: Check if expression is being evaluated
         if hasattr(node.expression, 'function') and hasattr(node.expression.function, 'value'):
             func_name = node.expression.function.value
             if func_name in ['persist_set', 'persist_get']:
-                print(f"[EVAL_EXPR_STMT] Evaluating {func_name} call", flush=True)
+                debug_log("eval_expression_statement", f"Evaluating {func_name} call", level='info')
         result = self.eval_node(node.expression, env, stack_trace)
         if hasattr(node.expression, 'function') and hasattr(node.expression.function, 'value'):
             func_name = node.expression.function.value
             if func_name in ['persist_set', 'persist_get']:
-                print(f"[EVAL_EXPR_STMT] Result from {func_name}: {result}", flush=True)
+                debug_log("eval_expression_statement", f"Result from {func_name}: {result}", level='info')
         return result
     
     # === VARIABLE & CONTROL FLOW ===
     
+    def _eval_destructure(self, pattern, value, env, stack_trace):
+        """Bind variables from a DestructurePattern against a runtime value.
+        
+        let {a, b} = {"a": 1, "b": 2}   -> env.a=1, env.b=2
+        let [x, y] = [10, 20]             -> env.x=10, env.y=20
+        """
+        from ..zexus_ast import DestructurePattern
+        if pattern.kind == 'map':
+            # Value must be a Map or dict-like
+            if not hasattr(value, 'pairs'):
+                return EvaluationError(
+                    f"Cannot destructure {type(value).__name__} as map — expected a Map"
+                )
+            pairs = value.pairs
+            for source_key, target_name in pattern.bindings:
+                # Map keys are stored as strings
+                val = pairs.get(source_key)
+                if val is None:
+                    # Try with String wrapper
+                    val = pairs.get(f'"{source_key}"')
+                if val is None:
+                    val = NULL
+                env.set(target_name, val)
+        elif pattern.kind == 'list':
+            # Value must be a List with .elements
+            if not hasattr(value, 'elements'):
+                return EvaluationError(
+                    f"Cannot destructure {type(value).__name__} as list — expected a List"
+                )
+            elements = value.elements
+            for idx, target_name in pattern.bindings:
+                if idx < len(elements):
+                    env.set(target_name, elements[idx])
+                else:
+                    env.set(target_name, NULL)
+            # Handle rest element
+            if pattern.rest:
+                rest_start = len(pattern.bindings)
+                from ..object import List as ListObj
+                env.set(pattern.rest, ListObj(elements[rest_start:]))
+        return NULL
+
     def eval_let_statement(self, node, env, stack_trace):
+        from ..zexus_ast import DestructurePattern
+        
+        # Handle destructuring: let {a, b} = expr  or  let [x, y] = expr
+        if isinstance(node.name, DestructurePattern):
+            debug_log("eval_let_statement", f"let destructure ({node.name.kind})")
+            value = self.eval_node(node.value, env, stack_trace)
+            if is_error(value):
+                return value
+            return self._eval_destructure(node.name, value, env, stack_trace)
+        
         debug_log("eval_let_statement", f"let {node.name.value}")
         
         # FIXED: Evaluate value FIRST to prevent recursion issues
@@ -213,6 +440,16 @@ class StatementEvaluatorMixin:
         return value_type in expected_types
     
     def eval_const_statement(self, node, env, stack_trace):
+        from ..zexus_ast import DestructurePattern
+        
+        # Handle destructuring: const {a, b} = expr  or  const [x, y] = expr
+        if isinstance(node.name, DestructurePattern):
+            debug_log("eval_const_statement", f"const destructure ({node.name.kind})")
+            value = self.eval_node(node.value, env, stack_trace)
+            if is_error(value):
+                return value
+            return self._eval_destructure(node.name, value, env, stack_trace)
+        
         debug_log("eval_const_statement", f"const {node.name.value}")
         
         # Evaluate value FIRST
@@ -745,10 +982,9 @@ class StatementEvaluatorMixin:
         return ReturnValue(val)
     
     def eval_continue_statement(self, node, env, stack_trace):
-        """Enable continue-on-error mode for the evaluator."""
-        debug_log("eval_continue_statement", "Enabling error recovery mode")
-        self.continue_on_error = True
-        return NULL
+        """Return ContinueException to signal loop continuation or error recovery."""
+        debug_log("eval_continue_statement", "Signaling continue")
+        return ContinueException()
     
     def eval_break_statement(self, node, env, stack_trace):
         """Return BreakException to signal loop exit."""
@@ -842,9 +1078,11 @@ class StatementEvaluatorMixin:
                     obj.set(prop_key, value)
                     return value
             except Exception as e:
-                return EvaluationError(str(e))
+                obj_type = type(obj).__name__
+                return EvaluationError(f"Assignment to property failed for {prop_key} on {obj_type}: {e}")
 
-            return EvaluationError('Assignment to property failed')
+            obj_type = type(obj).__name__
+            return EvaluationError(f"Assignment to property failed for {prop_key} on {obj_type}")
 
         # Otherwise it's an identifier assignment
         if isinstance(node.name, Identifier):
@@ -865,25 +1103,50 @@ class StatementEvaluatorMixin:
             return value
 
         debug_log("eval_assignment", f"Invalid assignment target - node.name: {node.name}, type: {type(node.name).__name__}")
-        print(f"[ASSIGN ERROR] node.name: {node.name}, type: {type(node.name).__name__}, value: {getattr(node.name, 'value', 'N/A')}")
+        if zexus_config.should_log('debug'):
+            print(f"[ASSIGN ERROR] node.name: {node.name}, type: {type(node.name).__name__}, value: {getattr(node.name, 'value', 'N/A')}")
         return EvaluationError('Invalid assignment target')
     
     def eval_try_catch_statement(self, node, env, stack_trace):
         debug_log("eval_try_catch", f"error_var: {node.error_variable.value if node.error_variable else 'error'}")
         
+        # Clear any pending tolerant skips when entering a try/catch, 
+        # as the protected block defines a new execution context
+        self._tolerant_skip_counts = {}
+
+        finally_block = getattr(node, 'finally_block', None)
+        result = None
+
         try:
             result = self.eval_node(node.try_block, env, stack_trace)
             if is_error(result):
                 catch_env = Environment(outer=env)
                 var_name = node.error_variable.value if node.error_variable else "error"
                 catch_env.set(var_name, String(str(result)))
-                return self.eval_node(node.catch_block, catch_env, stack_trace)
+                if zexus_config.should_log('debug'):
+                    print(f"[TRY_CATCH] caught error: {result}")
+                result = self.eval_node(node.catch_block, catch_env, stack_trace)
+                self._tolerant_skip_counts = {}
+                self._enqueue_tolerant_duplicates(getattr(node.try_block, "statements", []))
+                self._enqueue_tolerant_duplicates(getattr(node.catch_block, "statements", []))
+                return result
+            self._tolerant_skip_counts = {}
+            self._enqueue_tolerant_duplicates(getattr(node.try_block, "statements", []))
+            self._enqueue_tolerant_duplicates(getattr(node.catch_block, "statements", []))
             return result
         except Exception as e:
             catch_env = Environment(outer=env)
             var_name = node.error_variable.value if node.error_variable else "error"
             catch_env.set(var_name, String(str(e)))
-            return self.eval_node(node.catch_block, catch_env, stack_trace)
+            result = self.eval_node(node.catch_block, catch_env, stack_trace)
+            self._tolerant_skip_counts = {}
+            self._enqueue_tolerant_duplicates(getattr(node.try_block, "statements", []))
+            self._enqueue_tolerant_duplicates(getattr(node.catch_block, "statements", []))
+            return result
+        finally:
+            # Always execute the finally block if present
+            if finally_block is not None:
+                self.eval_node(finally_block, env, stack_trace)
     
     def eval_if_statement(self, node, env, stack_trace):
         cond = self.eval_node(node.condition, env, stack_trace)
@@ -913,7 +1176,11 @@ class StatementEvaluatorMixin:
         loop_id = id(node)  # Unique identifier for this loop
         
         # Use unified executor if available
-        if hasattr(self, 'unified_executor') and self.unified_executor:
+        if (
+            hasattr(self, 'unified_executor')
+            and self.unified_executor
+            and not getattr(env, 'disable_vm', False)
+        ):
             # Unified execution system handles everything automatically
             try:
                 return self.unified_executor.execute_loop(
@@ -950,6 +1217,10 @@ class StatementEvaluatorMixin:
             if isinstance(result, BreakException):
                 # Break out of loop, return NULL to continue execution in block
                 return NULL
+            if isinstance(result, ContinueException):
+                # Continue loop iteration
+                result = NULL
+                continue
             if isinstance(result, EvaluationError):
                 return result
     def eval_foreach_statement(self, node, env, stack_trace):
@@ -979,6 +1250,10 @@ class StatementEvaluatorMixin:
             if isinstance(result, BreakException):
                 # Break out of loop, return NULL to continue execution in block
                 return NULL
+            if isinstance(result, ContinueException):
+                # Continue loop iteration
+                result = NULL
+                continue
             if isinstance(result, EvaluationError):
                 return result
         
@@ -1119,9 +1394,38 @@ class StatementEvaluatorMixin:
             return False
         
         return False
+
+    def _try_vm_module_exec(self, program, module_env, candidate_path: str):
+        """Attempt to execute a module via VM bytecode for faster imports.
+
+        Returns compiled bytecodes if VM execution succeeds, else None.
+        """
+        if not getattr(self, "use_vm", False):
+            return None
+        bytecode_compiler = getattr(self, "bytecode_compiler", None)
+        if bytecode_compiler is None:
+            return None
+        try:
+            if getattr(self, "vm_instance", None) is None and hasattr(self, "_initialize_vm"):
+                self._initialize_vm()
+        except Exception:
+            return None
+        try:
+            compiled = bytecode_compiler.compile_file(candidate_path, program, optimize=True)
+            if not compiled:
+                return None
+            result = self._execute_bytecode_sequence(compiled, module_env, debug_mode=False)
+            if result is None:
+                return None
+            return compiled
+        except Exception:
+            return None
     
     def eval_use_statement(self, node, env, stack_trace):
-        from ..module_cache import get_cached_module, cache_module, get_module_candidates, normalize_path, invalidate_module
+        from ..module_cache import (get_cached_module, cache_module, get_module_candidates,
+                                     normalize_path, invalidate_module,
+                                     begin_loading, end_loading, CircularImportError,
+                                     is_loading)
         from ..builtin_modules import is_builtin_module, get_builtin_module
         from ..stdlib_integration import is_stdlib_module, get_stdlib_module
         
@@ -1131,6 +1435,7 @@ class StatementEvaluatorMixin:
         if not file_path: 
             return EvaluationError("use: missing file path")
         
+        debug_enabled = zexus_config.enable_debug_logs
         debug_log("  UseStatement loading", file_path)
         
         # 1a. Check if this is a stdlib module (fs, http, json, datetime, crypto, blockchain)
@@ -1155,7 +1460,8 @@ class StatementEvaluatorMixin:
                             debug_log(f"  Imported '{name}' from {file_path}", value)
                     elif alias:
                         # Import as alias: use "stdlib/fs" as fs
-                        env.set(alias, module_env)
+                        alias_name = alias.value if hasattr(alias, 'value') else str(alias)
+                        env.set(alias_name, module_env)
                     else:
                         # Import all functions into current scope
                         for key in module_env.store.keys():
@@ -1183,10 +1489,47 @@ class StatementEvaluatorMixin:
                 return EvaluationError(f"Builtin module '{file_path}' not available")
         
         normalized_path = normalize_path(file_path)
-        
+
+        # 1c. Circular import detection — check before cache lookup
+        # because the cache may contain a partially-loaded placeholder env
+        if is_loading(normalized_path):
+            return EvaluationError(
+                f"Circular import detected: {file_path} is already being loaded"
+            )
+
         # 2. Check Cache
-        module_env = get_cached_module(normalized_path)
-        
+        module_env = None
+        cached_bytecode = None
+        cached_ast = None
+        _cache_entry = get_cached_module(normalized_path)
+        if isinstance(_cache_entry, tuple) and _cache_entry:
+            module_env, cached_bytecode, cached_ast = _cache_entry
+
+        # 2a. Handle pre-compiled but not-yet-evaluated modules
+        if module_env and getattr(module_env, '_precompiled', False):
+            module_env._precompiled = False  # Clear flag to prevent re-entrant eval
+            if cached_bytecode is not None:
+                # Execute pre-compiled bytecode into module env (fastest)
+                try:
+                    self._execute_bytecode_sequence(
+                        cached_bytecode if isinstance(cached_bytecode, (list, tuple)) else [cached_bytecode],
+                        module_env, debug_mode=False)
+                    cache_module(normalized_path, module_env, cached_bytecode, cached_ast)
+                    debug_log("  Pre-compiled module bytecode executed:", file_path)
+                except Exception:
+                    # Bytecode execution failed — fall through to AST eval
+                    module_env._precompiled = True
+                    module_env = None
+            elif cached_ast is not None:
+                # Fall back to evaluating pre-parsed AST
+                try:
+                    self.eval_node(cached_ast, module_env)
+                    cache_module(normalized_path, module_env, None, cached_ast)
+                    debug_log("  Pre-compiled module AST evaluated:", file_path)
+                except Exception:
+                    module_env._precompiled = True
+                    module_env = None
+
         # 3. Load if not cached
         if not module_env:
             # Get the importing file's path for relative resolution
@@ -1197,52 +1540,109 @@ class StatementEvaluatorMixin:
                     importer_file = __file_obj.value
                 elif isinstance(__file_obj, str):
                     importer_file = __file_obj
-            
+
             candidates = get_module_candidates(file_path, importer_file)
-            module_env = Environment()
-            loaded = False
+            for candidate in candidates:
+                try:
+                    cached = get_cached_module(normalize_path(candidate))
+                    if cached:
+                        _env, _bc, _ast = cached
+                        if getattr(_env, '_precompiled', False):
+                            # Pre-compiled but not evaluated — try executing
+                            _env._precompiled = False
+                            if _bc is not None:
+                                try:
+                                    self._execute_bytecode_sequence(
+                                        _bc if isinstance(_bc, (list, tuple)) else [_bc],
+                                        _env, debug_mode=False)
+                                    cache_module(normalize_path(candidate), _env, _bc, _ast)
+                                    module_env = _env
+                                    break
+                                except Exception:
+                                    _env._precompiled = True
+                            elif _ast is not None:
+                                try:
+                                    self.eval_node(_ast, _env)
+                                    cache_module(normalize_path(candidate), _env, None, _ast)
+                                    module_env = _env
+                                    break
+                                except Exception:
+                                    _env._precompiled = True
+                        else:
+                            module_env = _env
+                            break
+                except Exception:
+                    continue
+
+            loaded = module_env is not None
+            if not module_env:
+                module_env = Environment()
             parse_errors = []
-            
+
+            # Circular import detection — register this path as in-progress
+            try:
+                begin_loading(normalized_path)
+            except CircularImportError as e:
+                return EvaluationError(str(e))
+
             # Circular dependency placeholder
             try: 
                 cache_module(normalized_path, module_env)
             except Exception: 
                 pass
-            
-            for candidate in candidates:
-                try:
-                    if not os.path.exists(candidate): 
-                        continue
-                    
-                    debug_log("  Found module file", candidate)
-                    with open(candidate, 'r', encoding='utf-8') as f: 
-                        code = f.read()
-                    
-                    from ..lexer import Lexer
-                    from ..parser import Parser
-                    
-                    lexer = Lexer(code)
-                    parser = Parser(lexer)
-                    program = parser.parse_program()
-                    
-                    if getattr(parser, 'errors', None):
-                        parse_errors.append((candidate, parser.errors))
-                        continue
-                    
-                    # Set __file__ in module environment so it can do relative imports
-                    module_env.set("__file__", String(os.path.abspath(candidate)))
-                    # Set __MODULE__ to the module path (not "__main__" since it's imported)
-                    module_env.set("__MODULE__", String(file_path))
-                    
-                    # Recursive evaluation
-                    self.eval_node(program, module_env)
-                    
-                    # Update cache with fully loaded env
-                    cache_module(normalized_path, module_env)
-                    loaded = True
-                    break
-                except Exception as e:
-                    parse_errors.append((candidate, str(e)))
+
+            try:
+                if not loaded:
+                    for candidate in candidates:
+                        try:
+                            if not os.path.exists(candidate): 
+                                continue
+                            
+                            debug_log("  Found module file", candidate)
+                            # Use VFS cache for module reads (hot path)
+                            try:
+                                from .integration import get_integration
+                                code = get_integration().vfs_manager.cached_read(candidate)
+                            except Exception:
+                                with open(candidate, 'r', encoding='utf-8') as f: 
+                                    code = f.read()
+                            
+                            from ..lexer import Lexer
+                            from ..parser import Parser
+                            
+                            lexer = Lexer(code)
+                            parser = Parser(lexer)
+                            program = parser.parse_program()
+                            
+                            if getattr(parser, 'errors', None):
+                                parse_errors.append((candidate, parser.errors))
+                                continue
+                            
+                            # Set __file__ in module environment so it can do relative imports
+                            module_env.set("__file__", String(os.path.abspath(candidate)))
+                            # Set __MODULE__ to the module path (not "__main__" since it's imported)
+                            module_env.set("__MODULE__", String(file_path))
+
+                            compiled = self._try_vm_module_exec(program, module_env, os.path.abspath(candidate))
+                            if compiled:
+                                cache_module(normalized_path, module_env, compiled, program)
+                                cache_module(normalize_path(candidate), module_env, compiled, program)
+                                loaded = True
+                                break
+
+                            # Recursive evaluation (interpreter fallback)
+                            self.eval_node(program, module_env)
+
+                            # Update cache with fully loaded env
+                            cache_module(normalized_path, module_env, None, program)
+                            cache_module(normalize_path(candidate), module_env, None, program)
+                            loaded = True
+                            break
+                        except Exception as e:
+                            parse_errors.append((candidate, str(e)))
+            finally:
+                # Always unmark, even if loading threw
+                end_loading(normalized_path)
             
             if not loaded:
                 try: 
@@ -1298,12 +1698,14 @@ class StatementEvaluatorMixin:
                 
         elif alias:
             # Handle: use "./file.zx" as alias
-            env.set(alias, module_env)
+            alias_name = alias.value if hasattr(alias, 'value') else str(alias)
+            env.set(alias_name, module_env)
         else:
             # Handle: use "./file.zx" (import all exports)
             try:
                 exports = module_env.get_exports()
-                print(f"[DEBUG USE] Importing from module, exports: {list(exports.keys())}")
+                if debug_enabled:
+                    print(f"[DEBUG USE] Importing from module, exports: {list(exports.keys())}")
                 __file_obj = env.get("__file__")
                 importer_file = None
                 if __file_obj:
@@ -1313,10 +1715,12 @@ class StatementEvaluatorMixin:
                     if importer_file:
                         if not self._check_import_permission(value, importer_file):
                             return EvaluationError(f"Permission denied for export {name}")
-                    print(f"[DEBUG USE] Setting {name} = {value}")
+                    if debug_enabled:
+                        print(f"[DEBUG USE] Setting {name} = {value}")
                     env.set(name, value)
             except Exception as e:
-                print(f"[DEBUG USE] Exception during export import: {e}")
+                if debug_enabled:
+                    print(f"[DEBUG USE] Exception during export import: {e}")
                 # Fallback: expose module as filename object
                 module_name = os.path.basename(file_path)
                 env.set(module_name, module_env)
@@ -1325,7 +1729,9 @@ class StatementEvaluatorMixin:
     
     def eval_from_statement(self, node, env, stack_trace):
         """Full implementation of FromStatement."""
-        from ..module_cache import get_cached_module, cache_module, get_module_candidates, normalize_path, invalidate_module
+        from ..module_cache import (get_cached_module, cache_module, get_module_candidates,
+                                     normalize_path, invalidate_module,
+                                     begin_loading, end_loading, is_loading)
         
         # 1. Resolve Path
         file_path = node.file_path
@@ -1333,7 +1739,16 @@ class StatementEvaluatorMixin:
             return EvaluationError("from: missing file path")
         
         normalized_path = normalize_path(file_path)
+
+        # Circular import detection
+        if is_loading(normalized_path):
+            return EvaluationError(
+                f"Circular import detected: {file_path} is already being loaded"
+            )
+
         module_env = get_cached_module(normalized_path)
+        if isinstance(module_env, tuple):
+            module_env = module_env[0] if module_env else None
         
         # 2. Load Logic (Explicitly repeated to ensure isolation)
         if not module_env:
@@ -1349,41 +1764,55 @@ class StatementEvaluatorMixin:
             candidates = get_module_candidates(file_path, importer_file)
             module_env = Environment()
             loaded = False
+
+            try:
+                begin_loading(normalized_path)
+            except Exception:
+                return EvaluationError(f"Circular import detected while loading {file_path}")
             
             try: 
                 cache_module(normalized_path, module_env)
             except Exception: 
                 pass
             
-            for candidate in candidates:
-                try:
-                    if not os.path.exists(candidate): 
-                        continue
-                    
-                    with open(candidate, 'r', encoding='utf-8') as f: 
-                        code = f.read()
-                    
-                    from ..lexer import Lexer
-                    from ..parser import Parser
-                    
-                    lexer = Lexer(code)
-                    parser = Parser(lexer)
-                    program = parser.parse_program()
-                    
-                    if getattr(parser, 'errors', None): 
+            try:
+                for candidate in candidates:
+                    try:
+                        if not os.path.exists(candidate): 
+                            continue
+                        
+                        with open(candidate, 'r', encoding='utf-8') as f: 
+                            code = f.read()
+                        
+                        from ..lexer import Lexer
+                        from ..parser import Parser
+                        
+                        lexer = Lexer(code)
+                        parser = Parser(lexer)
+                        program = parser.parse_program()
+                        
+                        if getattr(parser, 'errors', None): 
+                            continue
+                        
+                        # Set __file__ in module environment so it can do relative imports
+                        module_env.set("__file__", String(os.path.abspath(candidate)))
+                        # Set __MODULE__ to the module path (not "__main__" since it's imported)
+                        module_env.set("__MODULE__", String(file_path))
+
+                        compiled = self._try_vm_module_exec(program, module_env, os.path.abspath(candidate))
+                        if compiled:
+                            cache_module(normalized_path, module_env, compiled, program)
+                            loaded = True
+                            break
+
+                        self.eval_node(program, module_env)
+                        cache_module(normalized_path, module_env, None, program)
+                        loaded = True
+                        break
+                    except Exception:
                         continue
-                    
-                    # Set __file__ in module environment so it can do relative imports
-                    module_env.set("__file__", String(os.path.abspath(candidate)))
-                    # Set __MODULE__ to the module path (not "__main__" since it's imported)
-                    module_env.set("__MODULE__", String(file_path))
-                    
-                    self.eval_node(program, module_env)
-                    cache_module(normalized_path, module_env)
-                    loaded = True
-                    break
-                except Exception:
-                    continue
+            finally:
+                end_loading(normalized_path)
             
             if not loaded:
                 try: 
@@ -1635,7 +2064,8 @@ class StatementEvaluatorMixin:
         
         Syntax: sandbox { code }
         
-        Creates a new isolated environment and executes code within it.
+        Creates a new isolated environment with VFS-backed file access
+        and restricted capability policy, then executes code within it.
         """
 
         # Create isolated environment (child of current)
@@ -1645,6 +2075,26 @@ class StatementEvaluatorMixin:
         # Allow caller to specify a policy on the node (future enhancement)
         sandbox_policy = getattr(node, 'policy', None) or 'default'
         sandbox_env.set('__sandbox_policy__', sandbox_policy)
+
+        # --- VFS integration: create a per-sandbox VFS with temp-only write ---
+        sandbox_id = f"sandbox_{id(node)}_{id(env)}"
+        try:
+            from .integration import get_integration
+            integration = get_integration()
+            from ..virtual_filesystem import SandboxBuilder, FileAccessMode
+            builder = SandboxBuilder(integration.vfs_manager, sandbox_id)
+            builder.with_temp_access()  # /tmp read-write
+            # Mount CWD as read-only so sandbox can read source files
+            import os
+            cwd = os.getcwd()
+            if os.path.isdir(cwd):
+                builder.add_mount("/workspace", cwd, FileAccessMode.READ)
+            sandbox_fs = builder.build()
+            sandbox_env.set('__sandbox_vfs__', sandbox_fs)
+            sandbox_env.set('__sandbox_id__', sandbox_id)
+        except Exception:
+            pass
+
         # Ensure default sandbox policy exists
         try:
             sec = get_security_context()
@@ -1664,10 +2114,16 @@ class StatementEvaluatorMixin:
 
         result = self.eval_node(node.body, sandbox_env, stack_trace)
 
+        # --- Cleanup VFS sandbox ---
+        try:
+            integration = get_integration()
+            integration.vfs_manager.delete_sandbox(sandbox_id)
+        except Exception:
+            pass
+
         # Register sandbox run for observability
         try:
             ctx = get_security_context()
-            # store a minimal summary (stringified result) for now
             result_summary = None
             try:
                 result_summary = str(result)
@@ -2525,6 +2981,174 @@ class StatementEvaluatorMixin:
         obj = EmbeddedCode(node.name.value, node.language, node.code)
         env.set(node.name.value, obj)
         return NULL
+
+    def eval_color_statement(self, node, env, stack_trace):
+        if node.value is None:
+            return EvaluationError(f"color {node.name.value}: missing definition")
+
+        if isinstance(node.value, BlockStatement):
+            bindings = self._evaluate_renderer_block(node.value, env, stack_trace)
+            if is_error(bindings):
+                return bindings
+            python_spec = {key: _zexus_to_python(val) for key, val in bindings.items()}
+        else:
+            spec_val = self.eval_node(node.value, env, stack_trace)
+            spec_val = _resolve_awaitable(spec_val)
+            if isinstance(spec_val, ReturnValue):
+                spec_val = spec_val.value
+            if is_error(spec_val):
+                return spec_val
+            python_spec = _zexus_to_python(spec_val)
+
+        colour_repr = python_spec
+        if _RENDERER_AVAILABLE and renderer_define_color:
+            try:
+                colour_obj = renderer_define_color(node.name.value, python_spec)
+                colour_repr = str(colour_obj)
+            except Exception as exc:
+                return EvaluationError(f"color {node.name.value}: {exc}")
+        else:
+            registry = getattr(self, 'render_registry', None)
+            if isinstance(registry, dict):
+                registry.setdefault('colours', {})[node.name.value] = python_spec
+
+        env.set(node.name.value, _python_to_zexus(colour_repr))
+        return NULL
+
+    def eval_canvas_statement(self, node, env, stack_trace):
+        prop_data = self._evaluate_renderer_properties(node.properties, env, stack_trace)
+        if is_error(prop_data):
+            return prop_data
+
+        width = 80
+        height = 24
+
+        if isinstance(prop_data, list):
+            if len(prop_data) > 0:
+                width = prop_data[0]
+            if len(prop_data) > 1:
+                height = prop_data[1]
+        elif isinstance(prop_data, dict):
+            width = prop_data.get('width', prop_data.get('w', width))
+            height = prop_data.get('height', prop_data.get('h', height))
+        elif prop_data is not None:
+            width = prop_data
+
+        try:
+            width = int(width)
+            height = int(height)
+        except (ValueError, TypeError):
+            return EvaluationError(f"canvas {node.name.value}: width/height must be numeric")
+
+        canvas_id = None
+        if _RENDERER_AVAILABLE and renderer_create_named_canvas:
+            try:
+                canvas_id = renderer_create_named_canvas(node.name.value, width, height)
+            except Exception as exc:
+                return EvaluationError(f"canvas {node.name.value}: {exc}")
+        else:
+            registry = getattr(self, 'render_registry', None)
+            if isinstance(registry, dict):
+                canvases = registry.setdefault('canvases', {})
+                alias_map = registry.setdefault('canvas_aliases', {})
+                canvas_id = f"canvas_{len(canvases) + 1}"
+                canvases[canvas_id] = {
+                    'width': width,
+                    'height': height,
+                    'draw_ops': [],
+                }
+                alias_map[node.name.value] = canvas_id
+            else:
+                canvas_id = f"{node.name.value}_canvas"
+
+        canvas_obj = _python_to_zexus(canvas_id)
+        env.set(node.name.value, canvas_obj)
+
+        if node.body:
+            local_env = Environment(outer=env)
+            local_env.set(node.name.value, canvas_obj)
+            local_env.set('canvas', canvas_obj)
+            result = self.eval_block_statement(node.body, local_env, stack_trace)
+            if isinstance(result, ReturnValue):
+                return result
+            if is_error(result):
+                return result
+
+        return NULL
+
+    def eval_graphics_statement(self, node, env, stack_trace):
+        payload = {}
+        if node.body:
+            bindings = self._evaluate_renderer_block(node.body, env, stack_trace)
+            if is_error(bindings):
+                return bindings
+            payload = {key: _zexus_to_python(val) for key, val in bindings.items()}
+
+        if _RENDERER_AVAILABLE and renderer_register_graphics:
+            try:
+                renderer_register_graphics(node.name.value, payload)
+            except Exception as exc:
+                return EvaluationError(f"graphics {node.name.value}: {exc}")
+        else:
+            registry = getattr(self, 'render_registry', None)
+            if isinstance(registry, dict):
+                registry.setdefault('graphics', {})[node.name.value] = payload
+
+        env.set(node.name.value, _python_to_zexus(payload))
+        return NULL
+
+    def eval_animation_statement(self, node, env, stack_trace):
+        animation_data = {}
+
+        props = self._evaluate_renderer_properties(node.properties, env, stack_trace)
+        if is_error(props):
+            return props
+        if props is not None:
+            animation_data['properties'] = props
+
+        if node.body:
+            bindings = self._evaluate_renderer_block(node.body, env, stack_trace)
+            if is_error(bindings):
+                return bindings
+            animation_data.update({key: _zexus_to_python(val) for key, val in bindings.items()})
+
+        if _RENDERER_AVAILABLE and renderer_register_animation:
+            try:
+                renderer_register_animation(node.name.value, animation_data)
+            except Exception as exc:
+                return EvaluationError(f"animation {node.name.value}: {exc}")
+        else:
+            registry = getattr(self, 'render_registry', None)
+            if isinstance(registry, dict):
+                registry.setdefault('animations', {})[node.name.value] = animation_data
+
+        env.set(node.name.value, _python_to_zexus(animation_data))
+        return NULL
+
+    def eval_clock_statement(self, node, env, stack_trace):
+        config = self._evaluate_renderer_properties(node.properties, env, stack_trace)
+        if is_error(config):
+            return config
+
+        if isinstance(config, dict):
+            clock_data = dict(config)
+        elif config is None:
+            clock_data = {}
+        else:
+            clock_data = {'value': config}
+
+        if _RENDERER_AVAILABLE and renderer_register_clock:
+            try:
+                renderer_register_clock(node.name.value, clock_data)
+            except Exception as exc:
+                return EvaluationError(f"clock {node.name.value}: {exc}")
+        else:
+            registry = getattr(self, 'render_registry', None)
+            if isinstance(registry, dict):
+                registry.setdefault('clocks', {})[node.name.value] = clock_data
+
+        env.set(node.name.value, _python_to_zexus(clock_data))
+        return NULL
     
     def eval_component_statement(self, node, env, stack_trace):
         props = None
@@ -2611,7 +3235,15 @@ class StatementEvaluatorMixin:
         return self.eval_node(node.body, env, stack_trace)
     
     def eval_action_statement(self, node, env, stack_trace):
-        action = Action(node.parameters, node.body, env)
+        capture_env = env.clone_for_closure() if hasattr(env, "clone_for_closure") else env
+        action = Action(node.parameters, node.body, capture_env)
+
+        # Ensure recursive references resolve within closures
+        try:
+            if capture_env is not env and hasattr(capture_env, "set"):
+                capture_env.set(node.name.value, action)
+        except Exception:
+            pass
         
         # Check for direct is_async attribute (from UltimateParser)
         if hasattr(node, 'is_async') and node.is_async:
@@ -2644,20 +3276,26 @@ class StatementEvaluatorMixin:
     
     def eval_function_statement(self, node, env, stack_trace):
         """Evaluate function statement - identical to action statement in Zexus"""
-        print(f"[EVAL_FUNC] Starting eval_function_statement for: {node.name.value}", flush=True)
-        action = Action(node.parameters, node.body, env)
-        print(f"[EVAL_FUNC] Created Action object", flush=True)
+        debug_log("eval_function_statement", f"Start {node.name.value}")
+        capture_env = env.clone_for_closure() if hasattr(env, "clone_for_closure") else env
+        action = Action(node.parameters, node.body, capture_env)
+        try:
+            if capture_env is not env and hasattr(capture_env, "set"):
+                capture_env.set(node.name.value, action)
+        except Exception:
+            pass
+        debug_log("eval_function_statement", "Created Action object")
         
         # Apply modifiers if present
         modifiers = getattr(node, 'modifiers', [])
-        print(f"[EVAL_FUNC] Modifiers: {modifiers}", flush=True)
+        debug_log("eval_function_statement", f"Modifiers: {modifiers}")
         if modifiers:
             # Set modifier flags on the action object
             if 'inline' in modifiers:
                 action.is_inlined = True
             if 'async' in modifiers:
                 action.is_async = True
-                print(f"[EVAL_FUNC] Set is_async=True", flush=True)
+                debug_log("eval_function_statement", "Set is_async=True")
             if 'secure' in modifiers:
                 action.is_secure = True
             if 'pure' in modifiers:
@@ -2672,9 +3310,9 @@ class StatementEvaluatorMixin:
                 except Exception:
                     pass
         
-        print(f"[EVAL_FUNC] About to set in environment: {node.name.value}", flush=True)
+        debug_log("eval_function_statement", f"Binding {node.name.value}")
         env.set(node.name.value, action)
-        print(f"[EVAL_FUNC] Successfully set in environment", flush=True)
+        debug_log("eval_function_statement", "Binding complete")
         return NULL
     
     # === PERFORMANCE OPTIMIZATION STATEMENTS ===
@@ -3758,10 +4396,12 @@ class StatementEvaluatorMixin:
             if not is_truthy(condition):
                 # Execute tolerance block if provided (for conditional allowances)
                 if node.tolerance_block:
-                    print(f"⚡ TOLERANCE BLOCK: type={type(node.tolerance_block).__name__}")
+                    if zexus_config.should_log('debug'):
+                        print(f"⚡ TOLERANCE BLOCK: type={type(node.tolerance_block).__name__}")
                     debug_log("eval_require_statement", "Condition failed - executing tolerance logic")
                     tolerance_result = self.eval_node(node.tolerance_block, env, stack_trace)
-                    print(f"⚡ TOLERANCE RESULT: type={type(tolerance_result).__name__}")
+                    if zexus_config.should_log('debug'):
+                        print(f"⚡ TOLERANCE RESULT: type={type(tolerance_result).__name__}")
                     
                     # Check if tolerance logic allows proceeding
                     if is_error(tolerance_result):
@@ -3770,18 +4410,22 @@ class StatementEvaluatorMixin:
                     # Unwrap ReturnValue if present
                     from ..object import ReturnValue
                     if isinstance(tolerance_result, ReturnValue):
-                        print(f"⚡ UNWRAPPING ReturnValue")
+                        if zexus_config.should_log('debug'):
+                            print(f"⚡ UNWRAPPING ReturnValue")
                         tolerance_result = tolerance_result.value
-                        print(f"⚡ UNWRAPPED VALUE: {tolerance_result}")
+                        if zexus_config.should_log('debug'):
+                            print(f"⚡ UNWRAPPED VALUE: {tolerance_result}")
                     
                     # If tolerance block returns true/truthy, allow it
                     if is_truthy(tolerance_result):
-                        print(f"⚡ TOLERANCE APPROVED")
+                        if zexus_config.should_log('debug'):
+                            print(f"⚡ TOLERANCE APPROVED")
                         debug_log("eval_require_statement", "Tolerance logic approved - allowing requirement")
                         return NULL
                     
                     # If tolerance block returns false, requirement still fails
-                    print(f"⚡ TOLERANCE REJECTED")
+                    if zexus_config.should_log('debug'):
+                        print(f"⚡ TOLERANCE REJECTED")
                     debug_log("eval_require_statement", "Tolerance logic rejected - requirement fails")
                     # Fall through to error below
                 
@@ -3902,25 +4546,32 @@ class StatementEvaluatorMixin:
         debug_log("_eval_require_resource", f"{req_type} requirement satisfied")
         return NULL
     
-    def eval_revert_statement(self, node, env, stack_trace):
-        """Evaluate revert statement - rollback transaction.
-        
-        revert();
-        revert("Unauthorized");
-        """
+    def _perform_revert(self, reason_expr, env, stack_trace):
         debug_log("eval_revert_statement", "Reverting transaction")
-        
-        # Evaluate revert reason if provided
+
         reason = "Transaction reverted"
-        if node.reason:
-            reason_val = self.eval_node(node.reason, env, stack_trace)
+        if reason_expr:
+            reason_val = self.eval_node(reason_expr, env, stack_trace)
             if isinstance(reason_val, String):
                 reason = reason_val.value
             elif not is_error(reason_val):
                 reason = str(reason_val.inspect() if hasattr(reason_val, 'inspect') else reason_val)
-        
+
         debug_log("eval_revert_statement", f"REVERT: {reason}")
         return EvaluationError(f"Transaction reverted: {reason}", stack_trace=stack_trace)
+
+    def eval_revert_statement(self, node, env, stack_trace):
+        """Evaluate revert statement - rollback transaction."""
+
+        signature = self._compute_revert_signature(getattr(node, "reason", None))
+        pending = getattr(self, "_pending_revert_signature", None)
+        if pending is not None and pending == signature:
+            debug_log("eval_revert_statement", "Skipping duplicate revert statement")
+            self._pending_revert_signature = None
+            return NULL
+
+        self._pending_revert_signature = None
+        return self._perform_revert(getattr(node, "reason", None), env, stack_trace)
     
     def eval_limit_statement(self, node, env, stack_trace):
         """Evaluate limit statement - set gas limit.
@@ -4247,7 +4898,8 @@ class StatementEvaluatorMixin:
         
         # Print event for debugging (optional)
         args_str = ", ".join(str(arg.inspect() if hasattr(arg, 'inspect') else arg) for arg in args)
-        print(f"📢 Event: {event_name}({args_str})")
+        if zexus_config.should_log('info'):
+            print(f"📢 Event: {event_name}({args_str})")
         
         return NULL