@riddledc/riddle-proof 0.7.58 → 0.7.60

package/README.md

@@ -270,6 +270,13 @@ can include `repeat` / `repeat_count` / `times` from 1 to 100; each repetition
 is recorded with `repeat_index` and `repeat_count`, and `after_ms` runs after
 each repetition. Use it for bounded game proof helpers, retry controls, or other
 workflows where one declarative action needs to advance the app several times.
+Add `frame_selector` / `frameSelector` to a setup action when the interaction
+target lives inside an embedded iframe, such as a community game player or
+hosted preview surface. Selector-based actions, storage actions, window calls,
+and setup assertions then execute in that frame context and record
+`frame_selector`, `frame_index`, and `frame_count` in setup-action evidence.
+Use `frame_index` / `frameIndex` when more than one matching iframe is present;
+it defaults to the first frame.
 
 `target.timeout_sec` is optional. Use it for known-heavy profile targets so the
 profile carries its own hosted Riddle worker budget; an explicit CLI `--timeout`
@@ -348,6 +355,11 @@ game, or preview surfaces that render inside iframes:
 
 ```json
 [
+  {
+    "type": "frame_url_matches",
+    "selector": ".game-player-root iframe",
+    "pattern": "/saved/hot-path-.+/index\\.html$"
+  },
   {
     "type": "frame_text_visible",
     "selector": ".game-player-root iframe",
@@ -361,6 +373,11 @@ game, or preview surfaces that render inside iframes:
 ]
 ```
 
+Use `frame_url_equals` when the iframe must resolve to one exact embedded
+resource, or `frame_url_matches` when a preview/job/saved-game URL has a stable
+shape but a generated ID. URL checks fail when the frame is missing, just like
+frame text and overflow checks.
+
 Frame checks capture each matching iframe's URL, title, compact text sample,
 scroll width, client width, measured horizontal overflow, and top visible
 overflow offenders. This keeps embedded-player audits in profile mode instead

package/dist/{chunk-7ZBK2GQX.js → chunk-FLQ4HHTT.js}

@@ -22,6 +22,8 @@ var RIDDLE_PROOF_PROFILE_CHECK_TYPES = [
   "selector_count_eq",
   "selector_text_order",
   "frame_text_visible",
+  "frame_url_equals",
+  "frame_url_matches",
   "frame_no_horizontal_overflow",
   "text_visible",
   "text_absent",
@@ -236,6 +238,11 @@ function normalizeSetupAction(input, index) {
   if (!isRecord(input)) throw new Error(`target.setup_actions[${index}] must be an object.`);
   const type = normalizeSetupActionType(stringValue(input.type), index);
   const selector = stringValue(input.selector);
+  const frameSelector = stringFromOwn(input, "frame_selector", "frameSelector", "iframe_selector", "iframeSelector");
+  const frameIndex = numberValue(valueFromOwn(input, "frame_index", "frameIndex", "iframe_index", "iframeIndex"));
+  if (frameIndex !== void 0 && (!Number.isInteger(frameIndex) || frameIndex < 0)) {
+    throw new Error(`target.setup_actions[${index}].frame_index must be a non-negative integer.`);
+  }
   if ((type === "click" || type === "fill" || type === "set_input_value" || type === "wait_for_selector" || type === "wait_for_text" || type === "assert_text_visible" || type === "assert_text_absent" || type === "assert_selector_count") && !selector) {
     throw new Error(`target.setup_actions[${index}] ${type} requires selector.`);
   }
@@ -288,6 +295,8 @@ function normalizeSetupAction(input, index) {
   return {
     type,
     selector,
+    frame_selector: frameSelector,
+    frame_index: frameIndex,
     force: type === "click" && (input.force === true || input.force_click === true || input.forceClick === true),
     key,
     value,
@@ -499,12 +508,19 @@ function normalizeCheck(input, index) {
   if ((type === "selector_visible" || type === "selector_absent" || type === "selector_count_at_least" || type === "selector_count_equals" || type === "selector_count_equal" || type === "selector_count_eq") && !stringValue(input.selector)) {
     throw new Error(`checks[${index}] ${type} requires selector.`);
   }
-  if ((type === "frame_text_visible" || type === "frame_no_horizontal_overflow") && !stringValue(input.selector)) {
+  if ((type === "frame_text_visible" || type === "frame_url_equals" || type === "frame_url_matches" || type === "frame_no_horizontal_overflow") && !stringValue(input.selector)) {
     throw new Error(`checks[${index}] ${type} requires selector.`);
   }
   if (type === "frame_text_visible" && !stringValue(input.text) && !stringValue(input.pattern)) {
     throw new Error(`checks[${index}] frame_text_visible requires text or pattern.`);
   }
+  const expectedUrl = stringFromOwn(input, "expected_url", "expectedUrl", "url", "expected_value", "expectedValue", "value");
+  if (type === "frame_url_equals" && expectedUrl === void 0) {
+    throw new Error(`checks[${index}] frame_url_equals requires expected_url.`);
+  }
+  if (type === "frame_url_matches" && !stringValue(input.pattern)) {
+    throw new Error(`checks[${index}] frame_url_matches requires pattern.`);
+  }
   if ((type === "text_visible" || type === "text_absent") && !stringValue(input.text) && !stringValue(input.pattern)) {
     throw new Error(`checks[${index}] ${type} requires text or pattern.`);
   }
@@ -537,6 +553,7 @@ function normalizeCheck(input, index) {
     expected_path: stringValue(input.expected_path),
     param: stringValue(input.param) || stringValue(input.search_param) || stringValue(input.searchParam) || stringValue(input.key),
     expected_value: expectedValue,
+    expected_url: expectedUrl,
     expected_routes: expectedRoutes,
     selector: stringValue(input.selector),
     expected_texts: expectedTexts,
@@ -1004,6 +1021,35 @@ function assessCheckFromEvidence(check, evidence) {
       message: failed ? `Frame selector ${key} did not contain expected text in ${failed} viewport(s).` : void 0
     };
   }
+  if (check.type === "frame_url_equals" || check.type === "frame_url_matches") {
+    const key = selectorKey(check);
+    const expectedUrl = check.expected_url || check.expected_value || "";
+    const results = viewports.map((viewport) => {
+      const frames = frameEvidenceForSelector(viewport, key);
+      const urls = frames.map((frame) => String(frame.url || "")).filter(Boolean);
+      const matches = urls.filter((url) => check.type === "frame_url_equals" ? url === expectedUrl : matchText(url, check));
+      return {
+        viewport: viewport.name,
+        frame_count: frames.length,
+        matched_count: matches.length,
+        matched: matches.length > 0,
+        urls: urls.slice(0, 10)
+      };
+    });
+    const failed = results.filter((result) => !result.matched).length;
+    return {
+      type: check.type,
+      label: checkLabel(check),
+      status: failed ? "failed" : "passed",
+      evidence: {
+        selector: key,
+        expected_url: check.type === "frame_url_equals" ? expectedUrl : null,
+        pattern: check.type === "frame_url_matches" ? check.pattern || null : null,
+        viewports: results.map((result) => toJsonValue(result))
+      },
+      message: failed ? `Frame selector ${key} URL assertion failed in ${failed} viewport(s).` : void 0
+    };
+  }
   if (check.type === "frame_no_horizontal_overflow") {
     const key = selectorKey(check);
     const maxOverflow = check.max_overflow_px ?? 4;
@@ -1174,6 +1220,8 @@ function assessSetupActionsFromEvidence(profile, evidence) {
           viewport: viewport.name,
           action: result.action ?? result.type ?? null,
           selector: result.selector ?? null,
+          frame_selector: result.frame_selector ?? null,
+          frame_index: result.frame_index ?? null,
           reason: result.reason ?? result.error ?? null
         });
       }
@@ -1686,10 +1734,12 @@ function assessProfile(profile, evidence) {
         if (result && result.ok === false) {
           failed.push({
             viewport: viewport.name,
-            action: result.action || result.type || null,
-            selector: result.selector || null,
-            reason: result.reason || result.error || null,
-          });
+          action: result.action || result.type || null,
+          selector: result.selector || null,
+          frame_selector: result.frame_selector || null,
+          frame_index: result.frame_index ?? null,
+          reason: result.reason || result.error || null,
+        });
         }
       }
       if (results.length < actionCount && results.every((result) => !result || result.ok !== false)) {
@@ -1891,6 +1941,36 @@ function assessProfile(profile, evidence) {
       });
       continue;
     }
+    if (check.type === "frame_url_equals" || check.type === "frame_url_matches") {
+      const selector = check.selector || "";
+      const expectedUrl = check.expected_url || check.expected_value || "";
+      const results = checkViewports.map((viewport) => {
+        const frames = frameEvidenceForSelector(viewport, selector);
+        const urls = frames.map((frame) => String(frame.url || "")).filter(Boolean);
+        const matches = urls.filter((url) => check.type === "frame_url_equals" ? url === expectedUrl : textMatches(url, check));
+        return {
+          viewport: viewport.name,
+          frame_count: frames.length,
+          matched_count: matches.length,
+          matched: matches.length > 0,
+          urls: urls.slice(0, 10),
+        };
+      });
+      const failed = results.filter((result) => !result.matched).length;
+      checks.push({
+        type: check.type,
+        label: check.label || check.type,
+        status: failed ? "failed" : "passed",
+        evidence: {
+          selector,
+          expected_url: check.type === "frame_url_equals" ? expectedUrl : null,
+          pattern: check.type === "frame_url_matches" ? check.pattern || null : null,
+          viewports: results,
+        },
+        message: failed ? "Frame selector " + selector + " URL assertion failed in " + failed + " viewport(s)." : undefined,
+      });
+      continue;
+    }
     if (check.type === "frame_no_horizontal_overflow") {
       const selector = check.selector || "";
       const maxOverflow = check.max_overflow_px == null ? 4 : check.max_overflow_px;
@@ -2152,8 +2232,8 @@ function setupJsonValue(value) {
 function setupValuesEqual(left, right) {
   return JSON.stringify(setupJsonValue(left)) === JSON.stringify(setupJsonValue(right));
 }
-async function setupReadWindowValue(path) {
-  return await page.evaluate(({ path }) => {
+async function setupReadWindowValue(context, path) {
+  return await context.evaluate(({ path }) => {
     const toJsonValue = (value) => {
       if (value === null || value === undefined) return null;
       if (typeof value === "string" || typeof value === "boolean") return value;
@@ -2175,6 +2255,80 @@ async function setupReadWindowValue(path) {
     return { ok: true, value: toJsonValue(current) };
   }, { path });
 }
+function setupFrameSelector(action) {
+  return String(action?.frame_selector || action?.frameSelector || action?.iframe_selector || action?.iframeSelector || "").trim();
+}
+function setupFrameIndex(action) {
+  const raw = action?.frame_index ?? action?.frameIndex ?? action?.iframe_index ?? action?.iframeIndex ?? 0;
+  const number = Number(raw);
+  return Number.isInteger(number) && number >= 0 ? number : 0;
+}
+function setupScopeEvidence(scope) {
+  if (!scope || !scope.frame_selector) return {};
+  return {
+    frame_selector: scope.frame_selector,
+    frame_index: scope.frame_index,
+    frame_count: scope.frame_count,
+  };
+}
+function setupScopeFailure(base, scope) {
+  return {
+    ...base,
+    ...setupScopeEvidence(scope),
+    reason: scope?.reason || "frame_scope_unavailable",
+    error: scope?.error || undefined,
+  };
+}
+async function setupActionScope(action, timeout) {
+  const frameSelector = setupFrameSelector(action);
+  if (!frameSelector) return { ok: true, context: page };
+  const frameIndex = setupFrameIndex(action);
+  let frameCount = 0;
+  let locator = null;
+  try {
+    await page.waitForSelector(frameSelector, { state: "attached", timeout });
+    locator = page.locator(frameSelector);
+    frameCount = await locator.count();
+  } catch (error) {
+    return {
+      ok: false,
+      reason: "frame_selector_not_found",
+      frame_selector: frameSelector,
+      frame_index: frameIndex,
+      frame_count: frameCount,
+      error: String(error && error.message ? error.message : error).slice(0, 1000),
+    };
+  }
+  if (!frameCount) {
+    return { ok: false, reason: "frame_selector_not_found", frame_selector: frameSelector, frame_index: frameIndex, frame_count: frameCount };
+  }
+  if (frameIndex >= frameCount) {
+    return { ok: false, reason: "frame_index_out_of_range", frame_selector: frameSelector, frame_index: frameIndex, frame_count: frameCount };
+  }
+  const handle = await locator.nth(frameIndex).elementHandle({ timeout }).catch((error) => ({ __riddle_error: error }));
+  if (!handle || handle.__riddle_error) {
+    return {
+      ok: false,
+      reason: "frame_element_unavailable",
+      frame_selector: frameSelector,
+      frame_index: frameIndex,
+      frame_count: frameCount,
+      error: handle?.__riddle_error ? String(handle.__riddle_error && handle.__riddle_error.message ? handle.__riddle_error.message : handle.__riddle_error).slice(0, 1000) : undefined,
+    };
+  }
+  const frame = typeof handle.contentFrame === "function" ? await handle.contentFrame().catch((error) => ({ __riddle_error: error })) : null;
+  if (!frame || frame.__riddle_error) {
+    return {
+      ok: false,
+      reason: "content_frame_unavailable",
+      frame_selector: frameSelector,
+      frame_index: frameIndex,
+      frame_count: frameCount,
+      error: frame?.__riddle_error ? String(frame.__riddle_error && frame.__riddle_error.message ? frame.__riddle_error.message : frame.__riddle_error).slice(0, 1000) : undefined,
+    };
+  }
+  return { ok: true, context: frame, frame_selector: frameSelector, frame_index: frameIndex, frame_count: frameCount };
+}
 async function setupLocatorText(locator, index) {
   return await locator.nth(index).textContent({ timeout: 1000 }).catch(() => "");
 }
@@ -2336,7 +2490,8 @@ async function registerNetworkMocks(mocks) {
 }
 async function executeSetupAction(action, ordinal) {
   const type = setupActionType(action);
-  const base = { ok: false, action: type || "unknown", ordinal, selector: action.selector || null };
+  const frameSelector = setupFrameSelector(action);
+  const base = { ok: false, action: type || "unknown", ordinal, selector: action.selector || null, frame_selector: frameSelector || null };
   const timeout = setupNumber(action.timeout_ms, 5000);
   try {
     if (type === "wait") {
@@ -2345,51 +2500,65 @@ async function executeSetupAction(action, ordinal) {
       return { ...base, ok: true, ms };
     }
     if (type === "wait_for_selector") {
-      await page.waitForSelector(action.selector, { state: "visible", timeout });
-      return { ...base, ok: true, timeout_ms: timeout };
+      const scope = await setupActionScope(action, timeout);
+      if (!scope.ok) return setupScopeFailure(base, scope);
+      await scope.context.waitForSelector(action.selector, { state: "visible", timeout });
+      return { ...base, ...setupScopeEvidence(scope), ok: true, timeout_ms: timeout };
     }
     if (type === "press") {
       const key = String(action.key || "").trim();
       if (!key) return { ...base, reason: "missing_key" };
+      const scope = await setupActionScope(action, timeout);
+      if (!scope.ok) return setupScopeFailure(base, scope);
       if (!action.selector) {
-        await page.keyboard.press(key);
-        return { ...base, ok: true, key };
+        if (scope.frame_selector) {
+          await scope.context.locator("body").press(key, { timeout });
+        } else {
+          await page.keyboard.press(key);
+        }
+        return { ...base, ...setupScopeEvidence(scope), ok: true, key };
       }
-      const locator = page.locator(action.selector);
+      const locator = scope.context.locator(action.selector);
       const count = await locator.count();
       if (!count) return { ...base, reason: "selector_not_found", count, key };
       const targetIndex = Number.isInteger(action.index) ? action.index : 0;
       if (targetIndex < 0 || targetIndex >= count) return { ...base, reason: "index_out_of_range", count, target_index: targetIndex, key };
       await locator.nth(targetIndex).press(key, { timeout });
-      return { ...base, ok: true, count, target_index: targetIndex, key };
+      return { ...base, ...setupScopeEvidence(scope), ok: true, count, target_index: targetIndex, key };
     }
     if (type === "local_storage" || type === "session_storage") {
       const value = setupActionValue(action);
-      await page.evaluate(({ type, key, value }) => {
+      const scope = await setupActionScope(action, timeout);
+      if (!scope.ok) return setupScopeFailure(base, scope);
+      await scope.context.evaluate(({ type, key, value }) => {
         const storage = type === "session_storage" ? window.sessionStorage : window.localStorage;
         storage.setItem(key, value);
       }, { type, key: action.key, value });
       if (action.reload === true) {
         await page.reload({ waitUntil: "domcontentloaded", timeout: 45000 });
       }
-      return { ...base, ok: true, key: action.key, value_length: value.length, reload: action.reload === true };
+      return { ...base, ...setupScopeEvidence(scope), ok: true, key: action.key, value_length: value.length, reload: action.reload === true };
     }
     if (type === "clear_storage") {
       const storage = action.storage || "both";
-      await page.evaluate(({ storage }) => {
+      const scope = await setupActionScope(action, timeout);
+      if (!scope.ok) return setupScopeFailure(base, scope);
+      await scope.context.evaluate(({ storage }) => {
         if (storage === "local" || storage === "both") window.localStorage.clear();
         if (storage === "session" || storage === "both") window.sessionStorage.clear();
       }, { storage });
       if (action.reload === true) {
         await page.reload({ waitUntil: "domcontentloaded", timeout: 45000 });
       }
-      return { ...base, ok: true, storage, reload: action.reload === true };
+      return { ...base, ...setupScopeEvidence(scope), ok: true, storage, reload: action.reload === true };
     }
     if (type === "window_call") {
       const path = String(action.path || action.function_path || action.functionPath || "");
       const args = Array.isArray(action.args) ? action.args : [];
       if (!path) return { ...base, path, reason: "missing_path" };
-      const result = await page.evaluate(async ({ path, args }) => {
+      const scope = await setupActionScope(action, timeout);
+      if (!scope.ok) return setupScopeFailure(base, scope);
+      const result = await scope.context.evaluate(async ({ path, args }) => {
         const toJsonValue = (value) => {
           if (value === null || value === undefined) return null;
           if (typeof value === "string" || typeof value === "boolean") return value;
@@ -2429,6 +2598,7 @@ async function executeSetupAction(action, ordinal) {
       const expectationMet = !hasExpectation || setupValuesEqual(result.returned, expected);
       return {
         ...base,
+        ...setupScopeEvidence(scope),
         ok: Boolean(result.ok && expectationMet),
         path,
         arg_count: args.length,
@@ -2459,13 +2629,16 @@ async function executeSetupAction(action, ordinal) {
                 : action.expect;
       if (!path) return { ...base, path, reason: "missing_path" };
       if (!hasExpected) return { ...base, path, reason: "missing_expected_value" };
+      const scope = await setupActionScope(action, timeout);
+      if (!scope.ok) return setupScopeFailure(base, scope);
       const startedAt = Date.now();
       let result = null;
       while (Date.now() - startedAt <= timeout) {
-        result = await setupReadWindowValue(path);
+        result = await setupReadWindowValue(scope.context, path);
         if (result.ok && setupValuesEqual(result.value, expected)) {
           return {
             ...base,
+            ...setupScopeEvidence(scope),
             ok: true,
             path,
             value: setupJsonValue(result.value),
@@ -2477,6 +2650,7 @@ async function executeSetupAction(action, ordinal) {
       }
       return {
         ...base,
+        ...setupScopeEvidence(scope),
         path,
         reason: result?.ok ? "unexpected_value" : result?.reason || "path_not_found",
         missing_part: result?.missing_part || undefined,
@@ -2493,11 +2667,13 @@ async function executeSetupAction(action, ordinal) {
       const hasExpected = expected !== undefined;
       if (!path) return { ...base, path, reason: "missing_path" };
       if (!hasExpected && minValue === undefined && maxValue === undefined) return { ...base, path, reason: "missing_number_expectation" };
+      const scope = await setupActionScope(action, timeout);
+      if (!scope.ok) return setupScopeFailure(base, scope);
       const startedAt = Date.now();
       let result = null;
       let lastReason = "path_not_found";
       while (Date.now() - startedAt <= timeout) {
-        result = await setupReadWindowValue(path);
+        result = await setupReadWindowValue(scope.context, path);
         if (result.ok) {
           const actual = setupFiniteNumber(result.value);
           if (actual === undefined) {
@@ -2511,6 +2687,7 @@ async function executeSetupAction(action, ordinal) {
           } else {
             return {
               ...base,
+              ...setupScopeEvidence(scope),
               ok: true,
               path,
               value: actual,
@@ -2527,6 +2704,7 @@ async function executeSetupAction(action, ordinal) {
       }
       return {
         ...base,
+        ...setupScopeEvidence(scope),
         path,
         reason: lastReason,
         missing_part: result?.missing_part || undefined,
@@ -2538,7 +2716,9 @@ async function executeSetupAction(action, ordinal) {
       };
     }
     if (type === "click") {
-      const locator = page.locator(action.selector);
+      const scope = await setupActionScope(action, timeout);
+      if (!scope.ok) return setupScopeFailure(base, scope);
+      const locator = scope.context.locator(action.selector);
       const count = await locator.count();
       if (!count) return { ...base, reason: "selector_not_found", count };
       let targetIndex = Number.isInteger(action.index) ? action.index : 0;
@@ -2570,33 +2750,39 @@ async function executeSetupAction(action, ordinal) {
         ? { timeout, noWaitAfter: true, force: true }
         : { timeout, noWaitAfter: true };
       await locator.nth(targetIndex).click(clickOptions);
-      return { ...base, ok: true, count, target_index: targetIndex, text: matchedText, force: action.force === true || undefined };
+      return { ...base, ...setupScopeEvidence(scope), ok: true, count, target_index: targetIndex, text: matchedText, force: action.force === true || undefined };
     }
     if (type === "fill" || type === "set_input_value") {
-      const locator = page.locator(action.selector);
+      const scope = await setupActionScope(action, timeout);
+      if (!scope.ok) return setupScopeFailure(base, scope);
+      const locator = scope.context.locator(action.selector);
       const count = await locator.count();
       if (!count) return { ...base, reason: "selector_not_found", count };
       const targetIndex = Number.isInteger(action.index) ? action.index : 0;
       if (targetIndex < 0 || targetIndex >= count) return { ...base, reason: "index_out_of_range", count, target_index: targetIndex };
       const value = setupActionValue(action);
       await locator.nth(targetIndex).fill(value, { timeout });
-      return { ...base, ok: true, count, target_index: targetIndex, value_length: value.length };
+      return { ...base, ...setupScopeEvidence(scope), ok: true, count, target_index: targetIndex, value_length: value.length };
     }
     if (type === "assert_selector_count") {
-      const locator = page.locator(action.selector);
+      const scope = await setupActionScope(action, timeout);
+      if (!scope.ok) return setupScopeFailure(base, scope);
+      const locator = scope.context.locator(action.selector);
       const expectedCount = setupNumber(action.expected_count, -1);
       if (!Number.isInteger(expectedCount) || expectedCount < 0) return { ...base, reason: "invalid_expected_count", expected_count: action.expected_count };
       const startedAt = Date.now();
       let count = 0;
       while (Date.now() - startedAt <= timeout) {
         count = await locator.count().catch(() => 0);
-        if (count === expectedCount) return { ...base, ok: true, count, expected_count: expectedCount, timeout_ms: timeout };
+        if (count === expectedCount) return { ...base, ...setupScopeEvidence(scope), ok: true, count, expected_count: expectedCount, timeout_ms: timeout };
         await page.waitForTimeout(100);
       }
-      return { ...base, reason: "selector_count_mismatch", count, expected_count: expectedCount, timeout_ms: timeout };
+      return { ...base, ...setupScopeEvidence(scope), reason: "selector_count_mismatch", count, expected_count: expectedCount, timeout_ms: timeout };
     }
     if (type === "wait_for_text") {
-      const locator = page.locator(action.selector);
+      const scope = await setupActionScope(action, timeout);
+      if (!scope.ok) return setupScopeFailure(base, scope);
+      const locator = scope.context.locator(action.selector);
       const startedAt = Date.now();
       let lastText = "";
       while (Date.now() - startedAt <= timeout) {
@@ -2605,15 +2791,17 @@ async function executeSetupAction(action, ordinal) {
           const text = await setupLocatorText(locator, index);
           lastText = text || lastText;
           if (setupTextMatches(text, action)) {
-            return { ...base, ok: true, text: compactSetupResultText(text), target_index: index, timeout_ms: timeout };
+            return { ...base, ...setupScopeEvidence(scope), ok: true, text: compactSetupResultText(text), target_index: index, timeout_ms: timeout };
           }
         }
         await page.waitForTimeout(100);
       }
-      return { ...base, reason: "text_not_found", text: compactSetupResultText(lastText), timeout_ms: timeout };
+      return { ...base, ...setupScopeEvidence(scope), reason: "text_not_found", text: compactSetupResultText(lastText), timeout_ms: timeout };
     }
     if (type === "assert_text_visible" || type === "assert_text_absent") {
-      const locator = page.locator(action.selector);
+      const scope = await setupActionScope(action, timeout);
+      if (!scope.ok) return setupScopeFailure(base, scope);
+      const locator = scope.context.locator(action.selector);
       const startedAt = Date.now();
       let lastText = "";
       let matchedText = "";
@@ -2632,7 +2820,7 @@ async function executeSetupAction(action, ordinal) {
             if (type === "assert_text_visible") {
               const visible = await setupLocatorVisible(locator, index);
               if (visible) {
-                return { ...base, ok: true, count, text: compactSetupResultText(text), target_index: index, timeout_ms: timeout };
+                return { ...base, ...setupScopeEvidence(scope), ok: true, count, text: compactSetupResultText(text), target_index: index, timeout_ms: timeout };
               }
               hiddenMatch = true;
               break;
@@ -2641,17 +2829,17 @@ async function executeSetupAction(action, ordinal) {
           }
         }
         if (type === "assert_text_absent" && !matched) {
-          return { ...base, ok: true, count, timeout_ms: timeout };
+          return { ...base, ...setupScopeEvidence(scope), ok: true, count, timeout_ms: timeout };
         }
         await page.waitForTimeout(100);
       }
       if (type === "assert_text_visible") {
         if (hiddenMatch) {
-          return { ...base, reason: "matching_element_not_visible", text: compactSetupResultText(matchedText), timeout_ms: timeout };
+          return { ...base, ...setupScopeEvidence(scope), reason: "matching_element_not_visible", text: compactSetupResultText(matchedText), timeout_ms: timeout };
         }
-        return { ...base, reason: "text_not_found", text: compactSetupResultText(lastText), timeout_ms: timeout };
+        return { ...base, ...setupScopeEvidence(scope), reason: "text_not_found", text: compactSetupResultText(lastText), timeout_ms: timeout };
       }
-      return { ...base, reason: "text_still_present", text: compactSetupResultText(matchedText || lastText), timeout_ms: timeout };
+      return { ...base, ...setupScopeEvidence(scope), reason: "text_still_present", text: compactSetupResultText(matchedText || lastText), timeout_ms: timeout };
     }
     return { ...base, reason: "unsupported_action" };
   } catch (error) {
@@ -3254,7 +3442,7 @@ async function captureViewport(viewport) {
     if ((check.type === "text_visible" || check.type === "text_absent") && (check.text || check.pattern)) {
       text_matches[textKey(check)] = textMatches(dom.body_text || dom.body_text_sample || "", check);
     }
-    if ((check.type === "frame_text_visible" || check.type === "frame_no_horizontal_overflow") && check.selector) {
+    if ((check.type === "frame_text_visible" || check.type === "frame_url_equals" || check.type === "frame_url_matches" || check.type === "frame_no_horizontal_overflow") && check.selector) {
       selectors[check.selector] = selectors[check.selector] || await selectorStats(check.selector);
       frames[check.selector] = frames[check.selector] || await frameEvidence(check.selector);
     }