From e50b9121e1d287416eee59392a5ead11175c880c Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Tue, 2 Dec 2025 14:13:56 +0000
Subject: [PATCH] Document top-level await support for JavaScript execution

Add documentation for new top-level await capability in JavaScript/TypeScript
code execution. Variables declared with const, let, or var now persist across
executions within a context, enabling multi-step workflows.

Related PR: cloudflare/sandbox-sdk#261
---
 src/content/docs/sandbox/api/interpreter.mdx | 34 ++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/src/content/docs/sandbox/api/interpreter.mdx b/src/content/docs/sandbox/api/interpreter.mdx
index 562effd32142ed2..ee33bb4d065f2da 100644
--- a/src/content/docs/sandbox/api/interpreter.mdx
+++ b/src/content/docs/sandbox/api/interpreter.mdx
@@ -104,6 +104,40 @@ if (result.error) {
 ```
 </TypeScriptExample>
 
+**JavaScript and TypeScript features**:
+
+JavaScript and TypeScript code execution supports top-level `await` and persistent variables across executions within the same context.
+
+<TypeScriptExample>
+```
+const ctx = await sandbox.createCodeContext({ language: 'javascript' });
+
+// Execution 1: Fetch data with top-level await
+await sandbox.runCode(`
+const response = await fetch('https://api.example.com/data');
+const data = await response.json();
+`, { context: ctx });
+
+// Execution 2: Use the data from previous execution
+const result = await sandbox.runCode('console.log(data)', { context: ctx });
+console.log(result.logs.stdout); // Data persists across executions
+```
+</TypeScriptExample>
+
+Variables declared with `const`, `let`, or `var` persist across executions, enabling multi-step workflows:
+
+<TypeScriptExample>
+```
+const ctx = await sandbox.createCodeContext({ language: 'javascript' });
+
+await sandbox.runCode('const x = 10', { context: ctx });
+await sandbox.runCode('let y = 20', { context: ctx });
+const result = await sandbox.runCode('x + y', { context: ctx });
+
+console.log(result.results[0].text); // "30"
+```
+</TypeScriptExample>
+
 ### `listCodeContexts()`
 
 List all active code execution contexts.