diff --git a/CLAUDE.md b/CLAUDE.md
index ff8c85e..1e823f4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -211,6 +211,7 @@ Line-based, one command per line. `#` starts a comment.
 | `click <css-selector>` | Dispatch a synthetic `mousedown`/`mouseup`/`click` event sequence (bubbling) at the first element matching the selector, then re-style/re-layout/re-paint. Because `#` is the scenario comment delimiter, an ID match must be written as `[id=foo]` rather than `#foo`. |
 | `type <css-selector> <text>` | Focus the element and dispatch `keydown`/`beforeinput`/`input`/`keyup` for each character; for `<input>` / `<textarea>` the element's `value` is extended per character. Re-paints after the sequence. |
 | `wait_for_console <substring> [--timeout-ms N]` | Pump the JS event loop until the captured console contains `<substring>`, or the timeout (default 1000ms) expires. Useful for asserting async work kicked off by a click/type. |
+| `wait_for_dom_contains <substring> [--timeout-ms N]` | Pump the JS event loop until the DOM dump contains `<substring>`, or the timeout (default 1000ms) expires. Useful for settling delayed async DOM mutations before screenshots. |
 | `screenshot <out.png>` | Write PNG of current viewport. |
 | `dump_dom <out.txt>` | Write indented text dump of the DOM. |
 | `dump_console <out.txt>` | Write captured console.log/warn/error output. |
@@ -222,7 +223,8 @@ Line-based, one command per line. `#` starts a comment.
 
 The JS VM stays alive across commands within a single page session, so
 `click`/`type` mutate the live DOM through the same bridge a real page would
-use; subsequent `screenshot` / `dump_dom` / `assert_dom_contains` commands
+use, and `wait_for_console` / `wait_for_dom_contains` can settle asynchronous
+work; subsequent `screenshot` / `dump_dom` / `assert_dom_contains` commands
 observe the post-event state. A `goto` (or `goto_as`) tears the prior session
 down and starts a fresh one.
 
diff --git a/crates/e2e/scenarios/real-web/opera.com.we b/crates/e2e/scenarios/real-web/opera.com.we
index 9c83156..e5fafb4 100644
--- a/crates/e2e/scenarios/real-web/opera.com.we
+++ b/crates/e2e/scenarios/real-web/opera.com.we
@@ -88,6 +88,7 @@ cache_put opera https://cdn-production-opera-website.operacdn.com/staticfiles/as
 cache_put opera https://cdn-production-opera-website.operacdn.com/staticfiles/assets/images/main/home/opera__home--hero__mobile-android.0ce2e2d9de27.png ../../real-web/snapshots/opera.com/cdn-production-opera-website.operacdn.com/staticfiles/assets/images/main/home/opera__home--hero__mobile-android.0ce2e2d9de27.png image/png
 cache_put opera https://cdn-production-opera-website.operacdn.com/staticfiles/assets/images/main/home/opera__home--hero__mobile-android%402x.239d7c979096.png ../../real-web/snapshots/opera.com/cdn-production-opera-website.operacdn.com/staticfiles/assets/images/main/home/opera__home--hero__mobile-android%402x.239d7c979096.png image/png
 goto_as https://www.opera.com/ crates/e2e/real-web/snapshots/opera.com/index.html
+wait_for_dom_contains survey_container --timeout-ms 6000
 dump_dom real-web/opera.com/desktop_dom.txt
 dump_console real-web/opera.com/desktop_console.txt
 assert_dom_contains "Opera"
@@ -102,6 +103,7 @@ assert_dom_contains survey_container
 
 viewport 390 844
 goto_as https://www.opera.com/ crates/e2e/real-web/snapshots/opera.com/index.html
+wait_for_dom_contains survey_container --timeout-ms 6000
 dump_dom real-web/opera.com/mobile_dom.txt
 dump_console real-web/opera.com/mobile_console.txt
 assert_dom_contains "Opera"
diff --git a/crates/e2e/src/scenario.rs b/crates/e2e/src/scenario.rs
index 2477a19..62b80b8 100644
--- a/crates/e2e/src/scenario.rs
+++ b/crates/e2e/src/scenario.rs
@@ -19,6 +19,10 @@
 //!                              # pump the JS event loop until the console
 //!                              # capture contains <substring>, or the
 //!                              # timeout (default 1000ms) expires.
+//! wait_for_dom_contains <substring> [--timeout-ms N]
+//!                              # pump the JS event loop until the DOM dump
+//!                              # contains <substring>, or the timeout
+//!                              # (default 1000ms) expires.
 //! screenshot <out.png>         # write current screenshot
 //! dump_dom <out.txt>           # write DOM tree dump
 //! dump_console <out.txt>       # write captured console
@@ -47,11 +51,11 @@
 //! panic_now [msg]              # debug-only: deliberately panic to exercise the catcher.
 //! ```
 //!
-//! Interactivity commands (`click`, `type`, `wait_for_console`) keep the JS
-//! VM alive across commands via [`crate::render::Session`]: the synthetic
-//! event is dispatched through a small JS snippet, the event loop is pumped,
-//! and the page is re-painted so the next `screenshot` reflects post-event
-//! state.
+//! Interactivity commands (`click`, `type`, `wait_for_console`,
+//! `wait_for_dom_contains`) keep the JS VM alive across commands via
+//! [`crate::render::Session`]: the synthetic event is dispatched through a
+//! small JS snippet, the event loop is pumped, and the page is re-painted so
+//! the next `screenshot` reflects post-event state.
 
 use std::path::{Path, PathBuf};
 use std::time::Instant;
@@ -61,6 +65,8 @@ use crate::render::Session;
 
 /// Default `wait_for_console` timeout when the scenario omits `--timeout-ms`.
 pub const DEFAULT_WAIT_FOR_CONSOLE_MS: u64 = 1000;
+/// Default `wait_for_dom_contains` timeout when the scenario omits `--timeout-ms`.
+pub const DEFAULT_WAIT_FOR_DOM_CONTAINS_MS: u64 = 1000;
 
 #[derive(Debug, Clone)]
 pub enum Cmd {
@@ -94,6 +100,10 @@ pub enum Cmd {
         needle: String,
         timeout_ms: u64,
     },
+    WaitForDomContains {
+        needle: String,
+        timeout_ms: u64,
+    },
     Screenshot(PathBuf),
     DumpDom(PathBuf),
     DumpConsole(PathBuf),
@@ -257,6 +267,7 @@ fn parse_line(line: &str) -> Result<Cmd, String> {
             })
         }
         "wait_for_console" => parse_wait_for_console(rest),
+        "wait_for_dom_contains" => parse_wait_for_dom_contains(rest),
         "screenshot" => {
             if rest.is_empty() {
                 return Err("screenshot: missing path".into());
@@ -356,7 +367,26 @@ fn split_first_token(rest: &str) -> Option<(&str, &str)> {
 }
 
 fn parse_wait_for_console(rest: &str) -> Result<Cmd, String> {
-    let mut timeout_ms = DEFAULT_WAIT_FOR_CONSOLE_MS;
+    let (needle, timeout_ms) =
+        parse_wait_command(rest, "wait_for_console", DEFAULT_WAIT_FOR_CONSOLE_MS)?;
+    Ok(Cmd::WaitForConsole { needle, timeout_ms })
+}
+
+fn parse_wait_for_dom_contains(rest: &str) -> Result<Cmd, String> {
+    let (needle, timeout_ms) = parse_wait_command(
+        rest,
+        "wait_for_dom_contains",
+        DEFAULT_WAIT_FOR_DOM_CONTAINS_MS,
+    )?;
+    Ok(Cmd::WaitForDomContains { needle, timeout_ms })
+}
+
+fn parse_wait_command(
+    rest: &str,
+    command_name: &str,
+    default_timeout_ms: u64,
+) -> Result<(String, u64), String> {
+    let mut timeout_ms = default_timeout_ms;
     let mut needle_parts: Vec<String> = Vec::new();
     let mut it = rest.split_whitespace();
     while let Some(tok) = it.next() {
@@ -364,22 +394,22 @@ fn parse_wait_for_console(rest: &str) -> Result<Cmd, String> {
             "--timeout-ms" => {
                 let v = it
                     .next()
-                    .ok_or("wait_for_console: --timeout-ms: missing value")?;
+                    .ok_or_else(|| format!("{command_name}: --timeout-ms: missing value"))?;
                 timeout_ms = v
                     .parse()
-                    .map_err(|_| "wait_for_console: --timeout-ms: not an integer".to_string())?;
+                    .map_err(|_| format!("{command_name}: --timeout-ms: not an integer"))?;
             }
             other if other.starts_with("--") => {
-                return Err(format!("wait_for_console: unknown flag {other:?}"));
+                return Err(format!("{command_name}: unknown flag {other:?}"));
             }
             other => needle_parts.push(other.to_string()),
         }
     }
     if needle_parts.is_empty() {
-        return Err("wait_for_console: missing substring".into());
+        return Err(format!("{command_name}: missing substring"));
     }
     let needle = unquote(needle_parts.join(" ").as_str());
-    Ok(Cmd::WaitForConsole { needle, timeout_ms })
+    Ok((needle, timeout_ms))
 }
 
 fn parse_assert_screenshot_matches(rest: &str) -> Result<Cmd, String> {
@@ -585,6 +615,9 @@ fn cmd_label(cmd: &Cmd) -> String {
         Cmd::WaitForConsole { needle, timeout_ms } => {
             format!("wait_for_console {needle:?} (timeout {timeout_ms}ms)")
         }
+        Cmd::WaitForDomContains { needle, timeout_ms } => {
+            format!("wait_for_dom_contains {needle:?} (timeout {timeout_ms}ms)")
+        }
         Cmd::Screenshot(p) => format!("screenshot {}", p.display()),
         Cmd::DumpDom(p) => format!("dump_dom {}", p.display()),
         Cmd::DumpConsole(p) => format!("dump_console {}", p.display()),
@@ -836,6 +869,36 @@ fn execute_cmd(
                 steps.push((lineno, false, "wait_for_console: no page loaded".into()));
             }
         },
+        Cmd::WaitForDomContains { needle, timeout_ms } => match current {
+            Some(session) => {
+                let deadline = Instant::now() + std::time::Duration::from_millis(*timeout_ms);
+                let mut found = session.dom_dump().contains(needle.as_str());
+                while !found && Instant::now() < deadline {
+                    session.pump_event_loop();
+                    found = session.dom_dump().contains(needle.as_str());
+                    if !found {
+                        std::thread::sleep(std::time::Duration::from_millis(1));
+                    }
+                }
+                if found {
+                    session.repaint();
+                    steps.push((lineno, true, format!("wait_for_dom_contains {needle:?} ok")));
+                } else {
+                    steps.push((
+                        lineno,
+                        false,
+                        format!("wait_for_dom_contains {needle:?}: not seen within {timeout_ms}ms"),
+                    ));
+                }
+            }
+            None => {
+                steps.push((
+                    lineno,
+                    false,
+                    "wait_for_dom_contains: no page loaded".into(),
+                ));
+            }
+        },
         Cmd::Screenshot(path) => match current {
             Some(session) => {
                 let png = crate::png_out::bgra_to_png(&session.bgra, session.width, session.height);
@@ -1201,6 +1264,36 @@ mod tests {
         assert!(err.contains("not an integer"), "got: {err}");
     }
 
+    #[test]
+    fn wait_for_dom_contains_default_timeout() {
+        let cmd = parse_one("wait_for_dom_contains \"survey_container\"").unwrap();
+        match cmd {
+            Cmd::WaitForDomContains { needle, timeout_ms } => {
+                assert_eq!(needle, "survey_container");
+                assert_eq!(timeout_ms, DEFAULT_WAIT_FOR_DOM_CONTAINS_MS);
+            }
+            other => panic!("unexpected: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn wait_for_dom_contains_custom_timeout() {
+        let cmd = parse_one("wait_for_dom_contains async content --timeout-ms 2500").unwrap();
+        match cmd {
+            Cmd::WaitForDomContains { needle, timeout_ms } => {
+                assert_eq!(needle, "async content");
+                assert_eq!(timeout_ms, 2500);
+            }
+            other => panic!("unexpected: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn wait_for_dom_contains_rejects_missing_needle() {
+        let err = parse_one("wait_for_dom_contains --timeout-ms 100").unwrap_err();
+        assert!(err.contains("missing substring"), "got: {err}");
+    }
+
     #[test]
     fn js_string_literal_escapes() {
         assert_eq!(js_string_literal("a\"b\\c"), "\"a\\\"b\\\\c\"");
diff --git a/crates/e2e/tests/scenario_wait.rs b/crates/e2e/tests/scenario_wait.rs
new file mode 100644
index 0000000..6208e3a
--- /dev/null
+++ b/crates/e2e/tests/scenario_wait.rs
@@ -0,0 +1,61 @@
+//! Integration tests for scenario wait commands.
+
+use std::path::PathBuf;
+
+use we_e2e::scenario;
+
+fn tmp_dir(name: &str) -> PathBuf {
+    let mut p = std::env::temp_dir();
+    p.push(format!(
+        "we-e2e-scenario-wait-{name}-{}-{}",
+        std::process::id(),
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_nanos())
+            .unwrap_or(0)
+    ));
+    let _ = std::fs::remove_dir_all(&p);
+    std::fs::create_dir_all(&p).expect("create tmp dir");
+    p
+}
+
+#[test]
+fn wait_for_dom_contains_observes_delayed_mutation() {
+    let dir = tmp_dir("dom");
+    let page_path = dir.join("page.html");
+    std::fs::write(
+        &page_path,
+        r#"<!doctype html>
+<main>initial</main>
+<script>
+setTimeout(function() {
+  var node = document.createElement("p");
+  node.textContent = "async ready marker";
+  document.body.appendChild(node);
+}, 20);
+</script>
+"#,
+    )
+    .expect("write page");
+
+    let scenario_path = dir.join("wait.we");
+    std::fs::write(
+        &scenario_path,
+        format!(
+            "goto_as https://example.test/ {}\n\
+             wait_for_dom_contains \"async ready marker\" --timeout-ms 1000\n\
+             assert_dom_contains \"async ready marker\"\n",
+            page_path.display()
+        ),
+    )
+    .expect("write scenario");
+
+    let parsed = scenario::parse(&scenario_path).expect("parse scenario");
+    let report = scenario::run(&parsed, &dir);
+
+    assert!(report.passed, "steps: {:?}", report.steps);
+    assert!(report
+        .steps
+        .iter()
+        .any(|(_, ok, msg)| *ok && msg.contains("wait_for_dom_contains")));
+}