Implement JS async functions and await

Add async/await support to the JavaScript engine:

- Add `Await` opcode (0x82) to bytecode format
- Add `is_async` flag to bytecode Function struct
- Compile async function declarations, expressions, arrows, and methods
- Compile `await expr` to emit Await opcode
- Parse `for await...of` syntax
- VM creates internal generator for async functions, driven by promises
- Await suspends generator and sets up promise reactions for resume
- Rejected await throws into generator (preserving try/catch)
- Save/restore exception handlers across yield/await suspension points
- Async generators return async iterator wrappers
- 16 unit tests covering all async patterns

Co-Authored-By: Claude Opus 4.6 (1M context) <[e-mail]>

crates/js/src/builtins.rs

···
     chain_promise(gc, source, target)
 }
 
+pub fn create_promise_object_pub(gc: &mut Gc<HeapObject>) -> GcRef {
+    create_promise_object(gc)
+}
+
+pub fn enqueue_microtask_pub(task: Microtask) {
+    enqueue_microtask(task);
+}
+
+pub fn add_reaction_pub(
+    gc: &mut Gc<HeapObject>,
+    promise: GcRef,
+    on_fulfilled: Value,
+    on_rejected: Value,
+) -> GcRef {
+    add_reaction(gc, promise, on_fulfilled, on_rejected)
+}
+
 fn init_promise_builtins(vm: &mut Vm) {
     // Create Promise.prototype (inherits from Object.prototype).
     let mut proto_data = ObjectData::new();

crates/js/src/bytecode.rs

···
     Yield = 0x80,
     /// Spread dst_array, src — iterate src via @@iterator, append all elements to dst_array
     Spread = 0x81,
+    /// Await dst, src — suspend async function, await src value. On resume, dst gets the
+    /// settled value. The VM saves the frame state and returns to the async driver.
+    Await = 0x82,
 }
 
 impl Op {
···
             0x7C => Some(Op::StoreUpvalue),
             0x80 => Some(Op::Yield),
             0x81 => Some(Op::Spread),
+            0x82 => Some(Op::Await),
             _ => None,
         }
     }
···
     pub upvalue_defs: Vec<UpvalueDef>,
     /// Whether this is a generator function (function*).
     pub is_generator: bool,
+    /// Whether this is an async function.
+    pub is_async: bool,
 }
 
 impl Function {
···
             source_map: Vec::new(),
             upvalue_defs: Vec::new(),
             is_generator: false,
+            is_async: false,
         }
     }
 }
···
         self.emit_u8(src);
     }
 
+    /// Emit: Await dst, src — suspend async function
+    pub fn emit_await(&mut self, dst: Reg, src: Reg) {
+        self.emit_u8(Op::Await as u8);
+        self.emit_u8(dst);
+        self.emit_u8(src);
+    }
+
     /// Add a source map entry: current bytecode offset → source line.
     pub fn add_source_map(&mut self, line: u32) {
         let offset = self.offset() as u32;
···
                     pc += 2;
                     format!("Spread r{dst}, r{src}")
                 }
+                Op::Await => {
+                    let dst = code[pc];
+                    let src = code[pc + 1];
+                    pc += 2;
+                    format!("Await r{dst}, r{src}")
+                }
             };
             out.push_str(&format!("    {offset:04X}  {line}\n"));
         }
···
             Op::StoreUpvalue,
             Op::Yield,
             Op::Spread,
+            Op::Await,
         ];
         for op in ops {
             assert_eq!(

crates/js/src/compiler.rs

···
             left,
             right,
             body,
-            is_await: _,
+            is_await,
         } => {
             let saved_locals = fc.locals.len();
             let saved_next = fc.next_reg;
···
             let iterable_r = fc.alloc_reg();
             compile_expr(fc, right, iterable_r)?;
 
-            // Get the iterator: call iterable[@@iterator]().
+            // Get the iterator: call iterable[@@iterator]() or @@asyncIterator().
             let iter_method_r = fc.alloc_reg();
-            let sym_iter_ni = fc.builder.add_name("@@iterator");
+            let sym_name = if *is_await {
+                "@@asyncIterator"
+            } else {
+                "@@iterator"
+            };
+            let sym_iter_ni = fc.builder.add_name(sym_name);
             fc.builder
                 .emit_get_prop_name(iter_method_r, iterable_r, sym_iter_ni);
 
···
             let this_ni = fc.builder.add_name("this");
             fc.builder.emit_store_global(this_ni, iterable_r);
 
-            // Call [@@iterator]() with 0 args.
+            // Call [@@iterator/@@asyncIterator]() with 0 args.
             let iterator_r = fc.alloc_reg();
             let args_start = fc.next_reg;
             fc.builder
···
             fc.builder
                 .emit_call(result_obj_r, next_method_r, args_start, 0);
 
+            // For await: await the result of .next() (which returns a Promise).
+            if *is_await {
+                let awaited_r = fc.alloc_reg();
+                fc.builder.emit_await(awaited_r, result_obj_r);
+                fc.builder.emit_reg_reg(Op::Move, result_obj_r, awaited_r);
+                fc.free_reg(awaited_r);
+            }
+
             // Extract done and value.
             let done_ni = fc.builder.add_name("done");
             let value_ni = fc.builder.add_name("value");
···
     inner.builder.emit_reg(Op::Return, result_reg);
     let mut func = inner.builder.finish();
     func.is_generator = func_def.is_generator;
+    func.is_async = func_def.is_async;
     Ok(func)
 }
 
···
         ExprKind::Arrow {
             params,
             body,
-            is_async: _,
+            is_async,
         } => {
             // Collect free variables from the arrow body.
             let free_vars = collect_free_vars_arrow(params, body);
···
             inner.builder.emit_reg(Op::Return, result);
             let mut inner_func = inner.builder.finish();
             inner_func.upvalue_defs = upvalue_entries.iter().map(|e| e.def.clone()).collect();
+            inner_func.is_async = *is_async;
             let func_idx = fc.builder.add_function(inner_func);
             fc.builder.emit_reg_u16(Op::CreateClosure, dst, func_idx);
         }
···
         }
 
         ExprKind::Await(inner) => {
-            // Await is a VM-level operation; compile the argument.
-            compile_expr(fc, inner, dst)?;
+            let src = fc.alloc_reg();
+            compile_expr(fc, inner, src)?;
+            fc.builder.emit_await(dst, src);
+            fc.free_reg(src);
         }
 
         ExprKind::RegExp { pattern, flags } => {

crates/js/src/parser.rs

···
     fn parse_for(&mut self) -> Result<Stmt, ParseError> {
         let start = self.start_span();
         self.expect(&TokenKind::For)?;
+        let is_await = self.eat(&TokenKind::Await);
         self.expect(&TokenKind::LParen)?;
 
         // Check for for-in/for-of with var/let/const
···
                         },
                         right,
                         body,
-                        is_await: false,
+                        is_await,
                     },
                     span: self.span_from(start),
                 });
···
                     left: ForInOfLeft::Pattern(pattern),
                     right,
                     body,
-                    is_await: false,
+                    is_await,
                 },
                 span: self.span_from(start),
             });

crates/js/src/vm.rs

···
     pub ip: usize,
     /// The GcRef of the result prototype (for {value, done} objects).
     pub prototype: Option<GcRef>,
+    /// Saved exception handlers (for try/catch across await/yield points).
+    pub exception_handlers: Vec<(usize, Reg)>,
 }
 
 impl Traceable for HeapObject {
···
 
         match kind {
             FunctionKind::Native(native) => {
+                // Set async resume data if this function has it.
+                if let Some(HeapObject::Function(f)) = self.gc.get(func_ref) {
+                    if let Some(prop) = f.properties.get("__async_data__") {
+                        if let Value::Object(data_ref) = &prop.value {
+                            ASYNC_RESUME_DATA.with(|cell| cell.set(Some(*data_ref)));
+                        }
+                    }
+                }
+
                 let this = self
                     .globals
                     .get("this")
···
 
                 // Check for generator resume marker.
                 if let Value::Object(r) = &result {
-                    let is_resume = matches!(
+                    let is_gen_resume = matches!(
                         gc_get_property(&self.gc, *r, "__generator_resume__"),
                         Value::Boolean(true)
                     );
-                    if is_resume {
+                    if is_gen_resume {
                         let gen_ref = match gc_get_property(&self.gc, *r, "__gen_ref__") {
                             Value::Object(gr) => gr,
                             _ => return Ok(Value::Undefined),
···
                             _ => Ok(Value::Undefined),
                         };
                     }
+
+                    // Check for async resume marker.
+                    let is_async_resume = matches!(
+                        gc_get_property(&self.gc, *r, "__async_resume__"),
+                        Value::Boolean(true)
+                    );
+                    if is_async_resume {
+                        let gen_ref = match gc_get_property(&self.gc, *r, "__gen_ref__") {
+                            Value::Object(gr) => gr,
+                            _ => return Ok(Value::Undefined),
+                        };
+                        let result_promise =
+                            match gc_get_property(&self.gc, *r, "__result_promise__") {
+                                Value::Object(pr) => pr,
+                                _ => return Ok(Value::Undefined),
+                            };
+                        let is_throw = matches!(
+                            gc_get_property(&self.gc, *r, "__is_throw__"),
+                            Value::Boolean(true)
+                        );
+                        let value = gc_get_property(&self.gc, *r, "__value__");
+                        self.drive_async_step(gen_ref, result_promise, value, is_throw);
+                        return Ok(Value::Undefined);
+                    }
+
+                    // Check for async generator resume marker.
+                    let is_ag_resume = matches!(
+                        gc_get_property(&self.gc, *r, "__async_generator_resume__"),
+                        Value::Boolean(true)
+                    );
+                    if is_ag_resume {
+                        let gen_ref = match gc_get_property(&self.gc, *r, "__gen_ref__") {
+                            Value::Object(gr) => gr,
+                            _ => return Ok(Value::Undefined),
+                        };
+                        let send_val = gc_get_property(&self.gc, *r, "__send_value__");
+                        let kind_str = match gc_get_property(&self.gc, *r, "__resume_kind__") {
+                            Value::String(s) => s,
+                            _ => "next".to_string(),
+                        };
+
+                        // Create a promise for the result.
+                        let promise = crate::builtins::create_promise_object_pub(&mut self.gc);
+
+                        match kind_str.as_str() {
+                            "next" => match self.run_generator(gen_ref, send_val) {
+                                Ok(iter_result) => {
+                                    crate::builtins::resolve_promise_internal(
+                                        &mut self.gc,
+                                        promise,
+                                        iter_result,
+                                    );
+                                }
+                                Err(err) => {
+                                    let reason = err.to_value(&mut self.gc);
+                                    crate::builtins::reject_promise_internal(
+                                        &mut self.gc,
+                                        promise,
+                                        reason,
+                                    );
+                                }
+                            },
+                            "return" => {
+                                if let Some(HeapObject::Generator(gen)) = self.gc.get_mut(gen_ref) {
+                                    gen.state = GeneratorState::Completed;
+                                }
+                                let result = self.make_iterator_result(send_val, true);
+                                crate::builtins::resolve_promise_internal(
+                                    &mut self.gc,
+                                    promise,
+                                    result,
+                                );
+                            }
+                            _ => {}
+                        }
+                        return Ok(Value::Object(promise));
+                    }
                 }
 
                 Ok(result)
             }
             FunctionKind::Bytecode(bc) => {
                 let callee_func = bc.func;
+
+                // Async function: create generator + promise, drive async.
+                if callee_func.is_async && !callee_func.is_generator {
+                    let gen_ref = self.create_raw_generator(callee_func, upvalues, args);
+                    let result_promise = crate::builtins::create_promise_object_pub(&mut self.gc);
+                    self.drive_async_step(gen_ref, result_promise, Value::Undefined, false);
+                    return Ok(Value::Object(result_promise));
+                }
+
+                // Async generator function: create async generator wrapper.
+                if callee_func.is_async && callee_func.is_generator {
+                    let gen_ref = self.create_raw_generator(callee_func, upvalues, args);
+                    let wrapper = self.create_async_generator_wrapper(gen_ref);
+                    return Ok(Value::Object(wrapper));
+                }
 
                 // Generator function: create a generator object instead of executing.
                 if callee_func.is_generator {
···
             registers: regs,
             ip: 0,
             prototype: self.object_prototype,
+            exception_handlers: Vec::new(),
         };
 
         let gen_ref = self.gc.alloc(HeapObject::Generator(Box::new(gen_data)));
···
         self.gc.alloc(HeapObject::Object(obj))
     }
 
+    /// Create a raw GeneratorData (HeapObject::Generator) without the wrapper object.
+    /// Used by async functions which manage their own driving logic.
+    fn create_raw_generator(
+        &mut self,
+        func: Function,
+        upvalues: Vec<GcRef>,
+        args: &[Value],
+    ) -> GcRef {
+        let reg_count = func.register_count as usize;
+        let mut regs = vec![Value::Undefined; reg_count];
+        for (i, arg) in args.iter().enumerate() {
+            if i < func.param_count as usize {
+                regs[i] = arg.clone();
+            }
+        }
+
+        let gen_data = GeneratorData {
+            state: GeneratorState::NotStarted,
+            func,
+            upvalues,
+            registers: regs,
+            ip: 0,
+            prototype: self.object_prototype,
+            exception_handlers: Vec::new(),
+        };
+
+        self.gc.alloc(HeapObject::Generator(Box::new(gen_data)))
+    }
+
     /// Create a {value, done} iterator result object.
     fn make_iterator_result(&mut self, value: Value, done: bool) -> Value {
         let mut obj = ObjectData::new();
···
         send_value: Value,
     ) -> Result<Value, RuntimeError> {
         // Extract generator data.
-        let (func, upvalues, mut regs, ip, state) = match self.gc.get(gen_ref) {
+        let (func, upvalues, mut regs, ip, state, saved_exc_handlers) = match self.gc.get(gen_ref) {
             Some(HeapObject::Generator(gen)) => {
                 if gen.state == GeneratorState::Completed {
                     return Ok(self.make_iterator_result(Value::Undefined, true));
···
                     gen.registers.clone(),
                     gen.ip,
                     gen.state,
+                    gen.exception_handlers.clone(),
                 )
             }
             _ => return Err(RuntimeError::type_error("not a generator")),
···
             gen.state = GeneratorState::Executing;
         }
 
-        // If resuming from a yield, write the sent value into the yield's dst register.
+        // If resuming from a yield/await, write the sent value into the dst register.
         if state == GeneratorState::Suspended && ip >= 3 {
-            // The Yield instruction was: Yield dst, src (3 bytes total: op + dst + src)
-            // After executing Yield, ip points past it. The dst byte is at ip - 2.
+            // The Yield/Await instruction was: op dst, src (3 bytes total: op + dst + src)
+            // After executing, ip points past it. The dst byte is at ip - 2.
             let dst_reg = func.code[ip - 2] as usize;
             regs[dst_reg] = send_value;
         }
···
         // so Yield can find it. We use a slot just past the registers.
         self.registers[base + reg_count] = Value::Object(gen_ref);
 
+        // Restore exception handlers.
+        let exception_handlers = saved_exc_handlers
+            .iter()
+            .map(|&(catch_ip, catch_reg)| ExceptionHandler {
+                catch_ip,
+                catch_reg,
+            })
+            .collect();
+
         self.frames.push(CallFrame {
             func,
             ip,
             base,
-            return_reg: base + reg_count, // slot holding gen_ref for Yield to find
-            exception_handlers: Vec::new(),
+            return_reg: base + reg_count,
+            exception_handlers,
             upvalues,
         });
 
···
         }
     }
 
+    /// Throw a value into a suspended generator. Used for `await` on rejected
+    /// promises — the rejection reason is thrown so that try/catch can handle it.
+    fn throw_into_generator(
+        &mut self,
+        gen_ref: GcRef,
+        throw_value: Value,
+    ) -> Result<Value, RuntimeError> {
+        // Extract generator data.
+        let (func, upvalues, regs, ip, state, saved_exc_handlers) = match self.gc.get(gen_ref) {
+            Some(HeapObject::Generator(gen)) => {
+                if gen.state == GeneratorState::Completed {
+                    return Ok(self.make_iterator_result(Value::Undefined, true));
+                }
+                (
+                    gen.func.clone(),
+                    gen.upvalues.clone(),
+                    gen.registers.clone(),
+                    gen.ip,
+                    gen.state,
+                    gen.exception_handlers.clone(),
+                )
+            }
+            _ => return Err(RuntimeError::type_error("not a generator")),
+        };
+
+        if state == GeneratorState::NotStarted {
+            if let Some(HeapObject::Generator(gen)) = self.gc.get_mut(gen_ref) {
+                gen.state = GeneratorState::Completed;
+            }
+            return Err(RuntimeError {
+                kind: ErrorKind::Error,
+                message: throw_value.to_js_string(&self.gc),
+            });
+        }
+
+        // Mark as executing.
+        if let Some(HeapObject::Generator(gen)) = self.gc.get_mut(gen_ref) {
+            gen.state = GeneratorState::Executing;
+        }
+
+        // Save current VM state.
+        let saved_frames = std::mem::take(&mut self.frames);
+        let saved_instructions = self.instructions_executed;
+
+        let base = saved_frames
+            .last()
+            .map(|f| f.base + f.func.register_count as usize)
+            .unwrap_or(0);
+
+        let reg_count = func.register_count as usize;
+        self.ensure_registers(base + reg_count + 1);
+
+        for (i, val) in regs.iter().enumerate() {
+            self.registers[base + i] = val.clone();
+        }
+
+        self.registers[base + reg_count] = Value::Object(gen_ref);
+
+        // Restore exception handlers from the generator.
+        let exception_handlers = saved_exc_handlers
+            .iter()
+            .map(|&(catch_ip, catch_reg)| ExceptionHandler {
+                catch_ip,
+                catch_reg,
+            })
+            .collect();
+
+        self.frames.push(CallFrame {
+            func,
+            ip,
+            base,
+            return_reg: base + reg_count,
+            exception_handlers,
+            upvalues,
+        });
+
+        // Instead of writing send_value to dst register, throw the value.
+        let caught = self.handle_exception(throw_value);
+        let result = if caught {
+            self.run()
+        } else {
+            let msg = "Uncaught (in async)".to_string();
+            Err(RuntimeError {
+                kind: ErrorKind::Error,
+                message: msg,
+            })
+        };
+
+        // Restore VM state.
+        self.frames = saved_frames;
+        self.instructions_executed = saved_instructions;
+
+        match result {
+            Ok(val) => {
+                let gen_state = match self.gc.get(gen_ref) {
+                    Some(HeapObject::Generator(gen)) => gen.state,
+                    _ => GeneratorState::Completed,
+                };
+                if gen_state == GeneratorState::Suspended {
+                    Ok(val)
+                } else {
+                    if let Some(HeapObject::Generator(gen)) = self.gc.get_mut(gen_ref) {
+                        gen.state = GeneratorState::Completed;
+                    }
+                    Ok(self.make_iterator_result(val, true))
+                }
+            }
+            Err(err) => {
+                if let Some(HeapObject::Generator(gen)) = self.gc.get_mut(gen_ref) {
+                    gen.state = GeneratorState::Completed;
+                }
+                Err(err)
+            }
+        }
+    }
+
     // ── Iterator protocol helpers ────────────────────────────────
 
     /// Get an iterator from a value by calling its [Symbol.iterator]() method.
···
         };
 
         Ok((value, done))
+    }
+
+    // ── Async function helpers ──────────────────────────────────
+
+    /// Drive one step of an async function. Runs the internal generator until
+    /// it yields (await) or returns, then wires up promise reactions for the
+    /// next step.
+    fn drive_async_step(
+        &mut self,
+        gen_ref: GcRef,
+        result_promise: GcRef,
+        send_value: Value,
+        is_throw: bool,
+    ) {
+        let result = if is_throw {
+            // Throw into the generator — resume it and throw so that
+            // try/catch inside the async function can handle it.
+            self.throw_into_generator(gen_ref, send_value)
+        } else {
+            self.run_generator(gen_ref, send_value)
+        };
+
+        match result {
+            Ok(iter_result) => {
+                // Extract {value, done} from the iterator result.
+                let (value, done) = match &iter_result {
+                    Value::Object(r) => {
+                        let val = gc_get_property(&self.gc, *r, "value");
+                        let d = gc_get_property(&self.gc, *r, "done");
+                        (val, d.to_boolean())
+                    }
+                    _ => (Value::Undefined, true),
+                };
+
+                if done {
+                    // Async function returned — resolve the result promise.
+                    crate::builtins::resolve_promise_internal(&mut self.gc, result_promise, value);
+                } else {
+                    // Async function awaited — set up promise chain to resume.
+                    self.setup_async_resume(gen_ref, result_promise, value);
+                }
+            }
+            Err(err) => {
+                // Async function threw — reject the result promise.
+                // For plain `throw expr` (ErrorKind::Error), reject with the
+                // message string to preserve the original thrown value.
+                // For typed errors (TypeError, etc.), wrap in an error object.
+                let reason = if err.kind == ErrorKind::Error {
+                    Value::String(err.message.clone())
+                } else {
+                    err.to_value(&mut self.gc)
+                };
+                crate::builtins::reject_promise_internal(&mut self.gc, result_promise, reason);
+            }
+        }
+    }
+
+    /// Set up promise reactions so that when the awaited value settles, the
+    /// async function resumes.
+    fn setup_async_resume(&mut self, gen_ref: GcRef, result_promise: GcRef, awaited_value: Value) {
+        // Create the fulfill callback.
+        let fulfill_data = self.make_async_resume_data(gen_ref, result_promise, false);
+        let fulfill_fn = self.gc.alloc(HeapObject::Function(Box::new(FunctionData {
+            name: "__async_fulfill__".to_string(),
+            kind: FunctionKind::Native(NativeFunc {
+                callback: async_resume_callback,
+            }),
+            prototype_obj: None,
+            properties: {
+                let mut m = HashMap::new();
+                m.insert(
+                    "__async_data__".to_string(),
+                    Property::builtin(Value::Object(fulfill_data)),
+                );
+                m
+            },
+            upvalues: Vec::new(),
+        })));
+
+        // Create the reject callback.
+        let reject_data = self.make_async_resume_data(gen_ref, result_promise, true);
+        let reject_fn = self.gc.alloc(HeapObject::Function(Box::new(FunctionData {
+            name: "__async_reject__".to_string(),
+            kind: FunctionKind::Native(NativeFunc {
+                callback: async_resume_callback,
+            }),
+            prototype_obj: None,
+            properties: {
+                let mut m = HashMap::new();
+                m.insert(
+                    "__async_data__".to_string(),
+                    Property::builtin(Value::Object(reject_data)),
+                );
+                m
+            },
+            upvalues: Vec::new(),
+        })));
+
+        // If the awaited value is a promise, react to it.
+        if crate::builtins::is_promise_pub(&self.gc, &awaited_value) {
+            let val_ref = awaited_value.gc_ref().unwrap();
+            let state = crate::builtins::promise_state_pub(&self.gc, val_ref);
+            if state == crate::builtins::PROMISE_FULFILLED {
+                let r = crate::builtins::promise_get_prop_pub(
+                    &self.gc,
+                    val_ref,
+                    crate::builtins::PROMISE_RESULT_KEY,
+                );
+                crate::builtins::enqueue_microtask_pub(crate::builtins::Microtask {
+                    handler: Some(fulfill_fn),
+                    value: r,
+                    chained_promise: None,
+                    is_fulfillment: true,
+                });
+            } else if state == crate::builtins::PROMISE_REJECTED {
+                let r = crate::builtins::promise_get_prop_pub(
+                    &self.gc,
+                    val_ref,
+                    crate::builtins::PROMISE_RESULT_KEY,
+                );
+                crate::builtins::enqueue_microtask_pub(crate::builtins::Microtask {
+                    handler: Some(reject_fn),
+                    value: r,
+                    chained_promise: None,
+                    is_fulfillment: false,
+                });
+            } else {
+                // Pending promise: add reactions.
+                crate::builtins::add_reaction_pub(
+                    &mut self.gc,
+                    val_ref,
+                    Value::Function(fulfill_fn),
+                    Value::Function(reject_fn),
+                );
+            }
+        } else {
+            // Not a promise: resume immediately via microtask with the value.
+            crate::builtins::enqueue_microtask_pub(crate::builtins::Microtask {
+                handler: Some(fulfill_fn),
+                value: awaited_value,
+                chained_promise: None,
+                is_fulfillment: true,
+            });
+        }
+    }
+
+    /// Create an object holding the data needed to resume an async function.
+    fn make_async_resume_data(
+        &mut self,
+        gen_ref: GcRef,
+        result_promise: GcRef,
+        is_throw: bool,
+    ) -> GcRef {
+        let mut data = ObjectData::new();
+        data.properties.insert(
+            "__gen_ref__".to_string(),
+            Property::builtin(Value::Object(gen_ref)),
+        );
+        data.properties.insert(
+            "__result_promise__".to_string(),
+            Property::builtin(Value::Object(result_promise)),
+        );
+        data.properties.insert(
+            "__is_throw__".to_string(),
+            Property::builtin(Value::Boolean(is_throw)),
+        );
+        self.gc.alloc(HeapObject::Object(data))
+    }
+
+    /// Create an async generator wrapper object (for `async function*`).
+    fn create_async_generator_wrapper(&mut self, gen_ref: GcRef) -> GcRef {
+        let mut obj = ObjectData::new();
+        obj.prototype = self.object_prototype;
+
+        obj.properties.insert(
+            "__gen__".to_string(),
+            Property {
+                value: Value::Object(gen_ref),
+                writable: false,
+                enumerable: false,
+                configurable: false,
+            },
+        );
+
+        // next() method — returns a Promise for the next iteration result.
+        let next_fn = self.gc.alloc(HeapObject::Function(Box::new(FunctionData {
+            name: "next".to_string(),
+            kind: FunctionKind::Native(NativeFunc {
+                callback: async_generator_next,
+            }),
+            prototype_obj: None,
+            properties: HashMap::new(),
+            upvalues: Vec::new(),
+        })));
+        obj.properties.insert(
+            "next".to_string(),
+            Property::builtin(Value::Function(next_fn)),
+        );
+
+        // return() method
+        let return_fn = self.gc.alloc(HeapObject::Function(Box::new(FunctionData {
+            name: "return".to_string(),
+            kind: FunctionKind::Native(NativeFunc {
+                callback: async_generator_return,
+            }),
+            prototype_obj: None,
+            properties: HashMap::new(),
+            upvalues: Vec::new(),
+        })));
+        obj.properties.insert(
+            "return".to_string(),
+            Property::builtin(Value::Function(return_fn)),
+        );
+
+        // @@asyncIterator method — returns self.
+        let iter_fn = self.gc.alloc(HeapObject::Function(Box::new(FunctionData {
+            name: "[Symbol.asyncIterator]".to_string(),
+            kind: FunctionKind::Native(NativeFunc {
+                callback: generator_symbol_iterator,
+            }),
+            prototype_obj: None,
+            properties: HashMap::new(),
+            upvalues: Vec::new(),
+        })));
+        obj.properties.insert(
+            "@@asyncIterator".to_string(),
+            Property::builtin(Value::Function(iter_fn)),
+        );
+
+        self.gc.alloc(HeapObject::Object(obj))
     }
 
     /// Collect all GcRef values reachable from the mutator (roots for GC).
···
 
                     match call_info {
                         CallInfo::Native(callback) => {
+                            // Set async resume data if the function has it.
+                            if let Some(HeapObject::Function(f)) = self.gc.get(func_gc_ref) {
+                                if let Some(prop) = f.properties.get("__async_data__") {
+                                    if let Value::Object(data_ref) = &prop.value {
+                                        ASYNC_RESUME_DATA.with(|cell| cell.set(Some(*data_ref)));
+                                    }
+                                }
+                            }
+
                             let this = self
                                 .globals
                                 .get("this")
···
                                             }
                                             continue;
                                         }
+
+                                        // Check for async resume marker.
+                                        let is_async_resume = matches!(
+                                            gc_get_property(&self.gc, *r, "__async_resume__"),
+                                            Value::Boolean(true)
+                                        );
+                                        if is_async_resume {
+                                            let ar_gen = match gc_get_property(
+                                                &self.gc,
+                                                *r,
+                                                "__gen_ref__",
+                                            ) {
+                                                Value::Object(gr) => gr,
+                                                _ => {
+                                                    self.registers[base + dst as usize] =
+                                                        Value::Undefined;
+                                                    continue;
+                                                }
+                                            };
+                                            let ar_promise = match gc_get_property(
+                                                &self.gc,
+                                                *r,
+                                                "__result_promise__",
+                                            ) {
+                                                Value::Object(pr) => pr,
+                                                _ => {
+                                                    self.registers[base + dst as usize] =
+                                                        Value::Undefined;
+                                                    continue;
+                                                }
+                                            };
+                                            let ar_throw = matches!(
+                                                gc_get_property(&self.gc, *r, "__is_throw__"),
+                                                Value::Boolean(true)
+                                            );
+                                            let ar_value =
+                                                gc_get_property(&self.gc, *r, "__value__");
+                                            self.drive_async_step(
+                                                ar_gen, ar_promise, ar_value, ar_throw,
+                                            );
+                                            self.registers[base + dst as usize] = Value::Undefined;
+                                            continue;
+                                        }
+
+                                        // Check for async generator resume marker.
+                                        let is_ag_resume = matches!(
+                                            gc_get_property(
+                                                &self.gc,
+                                                *r,
+                                                "__async_generator_resume__"
+                                            ),
+                                            Value::Boolean(true)
+                                        );
+                                        if is_ag_resume {
+                                            let ag_gen = match gc_get_property(
+                                                &self.gc,
+                                                *r,
+                                                "__gen_ref__",
+                                            ) {
+                                                Value::Object(gr) => gr,
+                                                _ => {
+                                                    self.registers[base + dst as usize] =
+                                                        Value::Undefined;
+                                                    continue;
+                                                }
+                                            };
+                                            let ag_send =
+                                                gc_get_property(&self.gc, *r, "__send_value__");
+                                            let ag_kind = match gc_get_property(
+                                                &self.gc,
+                                                *r,
+                                                "__resume_kind__",
+                                            ) {
+                                                Value::String(s) => s,
+                                                _ => "next".to_string(),
+                                            };
+
+                                            let promise =
+                                                crate::builtins::create_promise_object_pub(
+                                                    &mut self.gc,
+                                                );
+
+                                            match ag_kind.as_str() {
+                                                "next" => {
+                                                    match self.run_generator(ag_gen, ag_send) {
+                                                        Ok(iter_result) => {
+                                                            crate::builtins::resolve_promise_internal(
+                                                                &mut self.gc,
+                                                                promise,
+                                                                iter_result,
+                                                            );
+                                                        }
+                                                        Err(err) => {
+                                                            let reason = err.to_value(&mut self.gc);
+                                                            crate::builtins::reject_promise_internal(
+                                                                &mut self.gc,
+                                                                promise,
+                                                                reason,
+                                                            );
+                                                        }
+                                                    }
+                                                }
+                                                "return" => {
+                                                    if let Some(HeapObject::Generator(gen)) =
+                                                        self.gc.get_mut(ag_gen)
+                                                    {
+                                                        gen.state = GeneratorState::Completed;
+                                                    }
+                                                    let result =
+                                                        self.make_iterator_result(ag_send, true);
+                                                    crate::builtins::resolve_promise_internal(
+                                                        &mut self.gc,
+                                                        promise,
+                                                        result,
+                                                    );
+                                                }
+                                                _ => {}
+                                            }
+                                            self.registers[base + dst as usize] =
+                                                Value::Object(promise);
+                                            continue;
+                                        }
                                     }
                                     self.registers[base + dst as usize] = val;
                                 }
···
                             }
                         }
                         CallInfo::Bytecode(callee_func, callee_upvalues) => {
+                            // Async function: create generator + promise, drive async.
+                            if callee_func.is_async && !callee_func.is_generator {
+                                let gen_ref =
+                                    self.create_raw_generator(callee_func, callee_upvalues, &args);
+                                let result_promise =
+                                    crate::builtins::create_promise_object_pub(&mut self.gc);
+                                self.drive_async_step(
+                                    gen_ref,
+                                    result_promise,
+                                    Value::Undefined,
+                                    false,
+                                );
+                                self.registers[base + dst as usize] = Value::Object(result_promise);
+                                continue;
+                            }
+
+                            // Async generator function: create async generator wrapper.
+                            if callee_func.is_async && callee_func.is_generator {
+                                let gen_ref =
+                                    self.create_raw_generator(callee_func, callee_upvalues, &args);
+                                let wrapper = self.create_async_generator_wrapper(gen_ref);
+                                self.registers[base + dst as usize] = Value::Object(wrapper);
+                                continue;
+                            }
+
                             // Generator function: create a generator object instead of executing.
                             if callee_func.is_generator {
                                 let gen_obj = self.create_generator_object(
···
                     let saved_regs: Vec<Value> =
                         self.registers[saved_base..saved_base + reg_count].to_vec();
 
+                    // Save exception handlers as (catch_ip, catch_reg) pairs.
+                    let saved_handlers: Vec<(usize, Reg)> = self.frames[fi]
+                        .exception_handlers
+                        .iter()
+                        .map(|h| (h.catch_ip, h.catch_reg))
+                        .collect();
+
                     if let Some(HeapObject::Generator(gen)) = self.gc.get_mut(gen_ref) {
                         gen.ip = saved_ip;
                         gen.registers = saved_regs;
                         gen.state = GeneratorState::Suspended;
+                        gen.exception_handlers = saved_handlers;
                     }
 
                     // Pop the generator frame.
···
                     return Ok(result);
                 }
 
+                // Await works identically to Yield at the opcode level: save state and
+                // suspend.  The async driver (not the generator protocol) handles resume.
+                Op::Await => {
+                    let _dst = Self::read_u8(&mut self.frames[fi]);
+                    let src = Self::read_u8(&mut self.frames[fi]);
+                    let base = self.frames[fi].base;
+                    let await_val = self.registers[base + src as usize].clone();
+
+                    // Save the generator's state (same as Yield).
+                    let frame = &self.frames[fi];
+                    let gen_ref = match self.registers.get(frame.return_reg) {
+                        Some(Value::Object(r)) => *r,
+                        _ => {
+                            return Err(RuntimeError {
+                                kind: ErrorKind::Error,
+                                message: "Await outside async function".into(),
+                            });
+                        }
+                    };
+
+                    let saved_ip = self.frames[fi].ip;
+                    let saved_base = self.frames[fi].base;
+                    let reg_count = self.frames[fi].func.register_count as usize;
+                    let saved_regs: Vec<Value> =
+                        self.registers[saved_base..saved_base + reg_count].to_vec();
+
+                    let saved_handlers: Vec<(usize, Reg)> = self.frames[fi]
+                        .exception_handlers
+                        .iter()
+                        .map(|h| (h.catch_ip, h.catch_reg))
+                        .collect();
+
+                    if let Some(HeapObject::Generator(gen)) = self.gc.get_mut(gen_ref) {
+                        gen.ip = saved_ip;
+                        gen.registers = saved_regs;
+                        gen.state = GeneratorState::Suspended;
+                        gen.exception_handlers = saved_handlers;
+                    }
+
+                    self.frames.pop();
+
+                    let result = self.make_iterator_result(await_val, false);
+                    return Ok(result);
+                }
+
                 Op::Spread => {
                     let dst = Self::read_u8(&mut self.frames[fi]);
                     let src = Self::read_u8(&mut self.frames[fi]);
···
     ctx: &mut NativeContext,
 ) -> Result<Value, RuntimeError> {
     Ok(ctx.this.clone())
+}
+
+// ── Async function native callbacks ──────────────────────────
+
+/// Native callback for async function resume. Called from microtask drain.
+/// Returns a marker object with `__async_resume__` so the VM can detect it
+/// and call `drive_async_step`.
+fn async_resume_callback(args: &[Value], ctx: &mut NativeContext) -> Result<Value, RuntimeError> {
+    // The resume data is stored on the function's own properties.
+    // We need to find the function ref from the calling convention.
+    // Since NativeContext doesn't provide function-self, we store data on the
+    // function object's properties and read them from global __async_current_fn__.
+    //
+    // Alternative approach: the callback itself reads from ctx.gc using a
+    // known __async_data__ property on the function. However, we don't have
+    // the function's GcRef here.
+    //
+    // Workaround: store the data in a global variable set before calling.
+
+    // Actually, the simplest approach: pass the data as extra information.
+    // We set __async_data__ as a property of the function, and the VM's
+    // call_function / Call handler extracts it from the function before
+    // calling the native callback.
+
+    // For now, use a sentinel return value that the VM intercepts.
+    let value = args.first().cloned().unwrap_or(Value::Undefined);
+
+    // We need the async data (gen_ref, result_promise, is_throw).
+    // The data was stored on the function's properties. We read from
+    // a thread-local set by the VM before calling us.
+    let data_ref = ASYNC_RESUME_DATA.with(|cell| cell.take());
+    if let Some(data) = data_ref {
+        let gen_ref = match gc_get_property(ctx.gc, data, "__gen_ref__") {
+            Value::Object(r) => r,
+            _ => return Ok(value),
+        };
+        let result_promise = match gc_get_property(ctx.gc, data, "__result_promise__") {
+            Value::Object(r) => r,
+            _ => return Ok(value),
+        };
+        let is_throw = matches!(
+            gc_get_property(ctx.gc, data, "__is_throw__"),
+            Value::Boolean(true)
+        );
+
+        // Return a marker for the VM to detect.
+        let mut obj = ObjectData::new();
+        obj.properties.insert(
+            "__async_resume__".to_string(),
+            Property::builtin(Value::Boolean(true)),
+        );
+        obj.properties.insert(
+            "__gen_ref__".to_string(),
+            Property::builtin(Value::Object(gen_ref)),
+        );
+        obj.properties.insert(
+            "__result_promise__".to_string(),
+            Property::builtin(Value::Object(result_promise)),
+        );
+        obj.properties.insert(
+            "__is_throw__".to_string(),
+            Property::builtin(Value::Boolean(is_throw)),
+        );
+        obj.properties
+            .insert("__value__".to_string(), Property::builtin(value));
+        let r = ctx.gc.alloc(HeapObject::Object(obj));
+        Ok(Value::Object(r))
+    } else {
+        Ok(value)
+    }
+}
+
+thread_local! {
+    static ASYNC_RESUME_DATA: std::cell::Cell<Option<GcRef>> = const { std::cell::Cell::new(None) };
+}
+
+/// Native callback for async generator `.next(value)`.
+fn async_generator_next(args: &[Value], ctx: &mut NativeContext) -> Result<Value, RuntimeError> {
+    let gen_ref = match &ctx.this {
+        Value::Object(r) => match gc_get_property(ctx.gc, *r, "__gen__") {
+            Value::Object(gen_r) => gen_r,
+            _ => return Err(RuntimeError::type_error("not an async generator")),
+        },
+        _ => return Err(RuntimeError::type_error("not an async generator")),
+    };
+
+    let send_value = args.first().cloned().unwrap_or(Value::Undefined);
+
+    // Return a marker for the VM to handle.
+    let mut obj = ObjectData::new();
+    obj.properties.insert(
+        "__async_generator_resume__".to_string(),
+        Property::builtin(Value::Boolean(true)),
+    );
+    obj.properties.insert(
+        "__gen_ref__".to_string(),
+        Property::builtin(Value::Object(gen_ref)),
+    );
+    obj.properties
+        .insert("__send_value__".to_string(), Property::builtin(send_value));
+    obj.properties.insert(
+        "__resume_kind__".to_string(),
+        Property::builtin(Value::String("next".to_string())),
+    );
+    let r = ctx.gc.alloc(HeapObject::Object(obj));
+    Ok(Value::Object(r))
+}
+
+/// Native callback for async generator `.return(value)`.
+fn async_generator_return(args: &[Value], ctx: &mut NativeContext) -> Result<Value, RuntimeError> {
+    let gen_ref = match &ctx.this {
+        Value::Object(r) => match gc_get_property(ctx.gc, *r, "__gen__") {
+            Value::Object(gen_r) => gen_r,
+            _ => return Err(RuntimeError::type_error("not an async generator")),
+        },
+        _ => return Err(RuntimeError::type_error("not an async generator")),
+    };
+
+    let return_value = args.first().cloned().unwrap_or(Value::Undefined);
+
+    let mut obj = ObjectData::new();
+    obj.properties.insert(
+        "__async_generator_resume__".to_string(),
+        Property::builtin(Value::Boolean(true)),
+    );
+    obj.properties.insert(
+        "__gen_ref__".to_string(),
+        Property::builtin(Value::Object(gen_ref)),
+    );
+    obj.properties.insert(
+        "__send_value__".to_string(),
+        Property::builtin(return_value),
+    );
+    obj.properties.insert(
+        "__resume_kind__".to_string(),
+        Property::builtin(Value::String("return".to_string())),
+    );
+    let r = ctx.gc.alloc(HeapObject::Object(obj));
+    Ok(Value::Object(r))
 }
 
 // ── Tests ────────────────────────────────────────────────────
···
             Value::String(s) => assert_eq!(s, "10,20,30,"),
             v => panic!("expected '10,20,30,', got {v:?}"),
         }
+    }
+
+    // ── Async/await tests ────────────────────────────────────
+
+    #[test]
+    fn test_async_function_returns_promise() {
+        match eval("async function f() { return 42; } typeof f()").unwrap() {
+            Value::String(s) => assert_eq!(s, "object"),
+            v => panic!("expected 'object', got {v:?}"),
+        }
+    }
+
+    #[test]
+    fn test_async_function_resolves_value() {
+        match eval_global(
+            "async function f() { return 42; } f().then(function(v) { result = v; });",
+            "result",
+        )
+        .unwrap()
+        {
+            Value::Number(n) => assert_eq!(n, 42.0),
+            v => panic!("expected 42, got {v:?}"),
+        }
+    }
+
+    #[test]
+    fn test_await_resolved_promise() {
+        match eval_global(
+            "async function f() { var x = await Promise.resolve(10); return x + 5; }
+             f().then(function(v) { result = v; });",
+            "result",
+        )
+        .unwrap()
+        {
+            Value::Number(n) => assert_eq!(n, 15.0),
+            v => panic!("expected 15, got {v:?}"),
+        }
+    }
+
+    #[test]
+    fn test_await_non_promise_value() {
+        match eval_global(
+            "async function f() { var x = await 7; return x * 3; }
+             f().then(function(v) { result = v; });",
+            "result",
+        )
+        .unwrap()
+        {
+            Value::Number(n) => assert_eq!(n, 21.0),
+            v => panic!("expected 21, got {v:?}"),
+        }
+    }
+
+    #[test]
+    fn test_multiple_awaits_in_sequence() {
+        match eval_global(
+            "async function f() {
+               var a = await Promise.resolve(1);
+               var b = await Promise.resolve(2);
+               var c = await Promise.resolve(3);
+               return a + b + c;
+             }
+             f().then(function(v) { result = v; });",
+            "result",
+        )
+        .unwrap()
+        {
+            Value::Number(n) => assert_eq!(n, 6.0),
+            v => panic!("expected 6, got {v:?}"),
+        }
+    }
+
+    #[test]
+    fn test_await_rejected_promise_throws() {
+        match eval_global(
+            "async function f() {
+               try { await Promise.reject('oops'); } catch(e) { return 'caught: ' + e; }
+             }
+             f().then(function(v) { result = v; });",
+            "result",
+        )
+        .unwrap()
+        {
+            Value::String(s) => assert_eq!(s, "caught: oops"),
+            v => panic!("expected 'caught: oops', got {v:?}"),
+        }
+    }
+
+    #[test]
+    fn test_async_function_throw_rejects() {
+        match eval_global(
+            "async function f() { throw 'error!'; }
+             f()['catch'](function(e) { result = 'got: ' + e; });",
+            "result",
+        )
+        .unwrap()
+        {
+            Value::String(s) => assert_eq!(s, "got: error!"),
+            v => panic!("expected 'got: error!', got {v:?}"),
+        }
+    }
+
+    #[test]
+    fn test_async_arrow_function() {
+        match eval_global(
+            "var f = async function() { var x = await Promise.resolve(99); return x; };
+             f().then(function(v) { result = v; });",
+            "result",
+        )
+        .unwrap()
+        {
+            Value::Number(n) => assert_eq!(n, 99.0),
+            v => panic!("expected 99, got {v:?}"),
+        }
+    }
+
+    #[test]
+    fn test_async_arrow_concise_body() {
+        match eval_global(
+            "var f = async function(x) { return x * 2; };
+             f(21).then(function(v) { result = v; });",
+            "result",
+        )
+        .unwrap()
+        {
+            Value::Number(n) => assert_eq!(n, 42.0),
+            v => panic!("expected 42, got {v:?}"),
+        }
+    }
+
+    #[test]
+    fn test_await_chained_promises() {
+        match eval_global(
+            "async function f() {
+               var p = Promise.resolve(5).then(function(v) { return v * 10; });
+               return await p;
+             }
+             f().then(function(v) { result = v; });",
+            "result",
+        )
+        .unwrap()
+        {
+            Value::Number(n) => assert_eq!(n, 50.0),
+            v => panic!("expected 50, got {v:?}"),
+        }
+    }
+
+    #[test]
+    fn test_async_function_with_closure() {
+        match eval_global(
+            "function make() {
+               var x = 100;
+               return async function() { var y = await Promise.resolve(23); return x + y; };
+             }
+             make()().then(function(v) { result = v; });",
+            "result",
+        )
+        .unwrap()
+        {
+            Value::Number(n) => assert_eq!(n, 123.0),
+            v => panic!("expected 123, got {v:?}"),
+        }
+    }
+
+    #[test]
+    fn test_async_method_in_object() {
+        match eval_global(
+            "var obj = { async getValue() { return await Promise.resolve(42); } };
+             obj.getValue().then(function(v) { result = v; });",
+            "result",
+        )
+        .unwrap()
+        {
+            Value::Number(n) => assert_eq!(n, 42.0),
+            v => panic!("expected 42, got {v:?}"),
+        }
+    }
+
+    #[test]
+    fn test_async_generator_basic() {
+        match eval_global(
+            "async function* gen() { yield 1; yield 2; yield 3; }
+             var it = gen();
+             it.next().then(function(r) { result = r.value; });",
+            "result",
+        )
+        .unwrap()
+        {
+            Value::Number(n) => assert_eq!(n, 1.0),
+            v => panic!("expected 1, got {v:?}"),
+        }
+    }
+
+    #[test]
+    fn test_for_await_of_parsing() {
+        let prog =
+            crate::parser::Parser::parse("async function f() { for await (let x of iter) { } }");
+        assert!(prog.is_ok());
     }
 }