@riddledc/riddle-proof 0.7.149 → 0.7.150

package/README.md

@@ -605,6 +605,26 @@ The check records visible text for the selector in each viewport and reports
 matched counts plus short samples, which makes generated-command and evidence
 card audits easier to diagnose than global `text_visible` checks.
 
+Use `observe_within` when the proof needs to catch a short-lived user-visible
+state after setup actions, such as a combo badge, damage flash, transient
+particle count, toast, or canvas-adjacent HUD update:
+
+```json
+{
+  "type": "observe_within",
+  "selector": ".result-state",
+  "pattern": "Photon.*active",
+  "timeout_ms": 1500
+}
+```
+
+With `selector` plus `text` or `pattern`, the runner polls visible selector
+text until it matches. With only `selector`, it polls for a visible matching
+element. With only `text` or `pattern`, it polls the rendered page body. The
+proof evidence records per-viewport match status, elapsed time, attempts,
+selector counts when applicable, and a compact sample. `within_ms` is accepted
+as an alias for `timeout_ms`; the default timeout is `2000`.
+
 Use `http_status` when the contract belongs to the fetched response itself:
 status code, content type, byte size, or raw body fragments from a markdown,
 JSON, YAML, robots, sitemap, or other machine-readable endpoint:

package/dist/{chunk-QXQCG3WB.js → chunk-QJJ3ISMK.js}

@@ -26,6 +26,7 @@ var RIDDLE_PROOF_PROFILE_CHECK_TYPES = [
   "selector_text_visible",
   "selector_text_absent",
   "selector_text_order",
+  "observe_within",
   "frame_text_visible",
   "frame_url_equals",
   "frame_url_matches",
@@ -1348,7 +1349,7 @@ function normalizeCheck(input, index) {
     throw new Error(`checks[${index}].type ${type} is not supported. Supported checks: ${RIDDLE_PROOF_PROFILE_CHECK_TYPES.join(", ")}`);
   }
   const isDialogCountCheck = isDialogCountCheckType(type);
-  if ((type === "selector_visible" || type === "selector_absent" || type === "selector_count_at_least" || type === "selector_count_equals" || type === "selector_count_equal" || type === "selector_count_eq" || type === "selector_text_visible" || type === "selector_text_absent") && !stringValue(input.selector)) {
+  if ((type === "selector_visible" || type === "selector_absent" || type === "selector_count_at_least" || type === "selector_count_equals" || type === "selector_count_equal" || type === "selector_count_eq" || type === "selector_text_visible" || type === "selector_text_absent" || type === "observe_within" && !stringValue(input.text) && !stringValue(input.pattern)) && !stringValue(input.selector)) {
     throw new Error(`checks[${index}] ${type} requires selector.`);
   }
   if ((type === "frame_text_visible" || type === "frame_url_equals" || type === "frame_url_matches" || type === "frame_no_horizontal_overflow") && !stringValue(input.selector)) {
@@ -1489,7 +1490,7 @@ function normalizeCheck(input, index) {
     allowed_content_types: allowedContentTypes,
     allow_get_fallback: isLinkStatusCheck ? input.allow_get_fallback === false || input.allowGetFallback === false ? false : true : void 0,
     max_overflow_px: numberValue(input.max_overflow_px),
-    timeout_ms: numberValue(input.timeout_ms) ?? numberValue(input.timeoutMs),
+    timeout_ms: numberValue(input.timeout_ms) ?? numberValue(input.timeoutMs) ?? numberValue(input.within_ms) ?? numberValue(input.withinMs),
     run_direct_routes: input.run_direct_routes === false || input.runDirectRoutes === false ? false : true,
     run_clickthroughs: input.run_clickthroughs === false || input.runClickthroughs === false ? false : true,
     run_all_viewports: input.run_all_viewports === true || input.runAllViewports === true,
@@ -2007,6 +2008,16 @@ function summarizeLinkStatusEvidence(viewport, check) {
 function textKey(check) {
   return check.pattern ? `pattern:${check.pattern}/${check.flags || ""}` : `text:${check.text || ""}`;
 }
+function observeWithinTimeoutMs(check) {
+  const raw = check.timeout_ms;
+  if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) return Math.min(Math.round(raw), 6e4);
+  return 2e3;
+}
+function observeWithinKey(check) {
+  const target = check.selector ? `selector:${check.selector}` : "page";
+  const expectation = check.pattern ? `pattern:${check.pattern}/${check.flags || ""}` : check.text ? `text:${check.text}` : "visible";
+  return `${target}|${expectation}|within:${observeWithinTimeoutMs(check)}`;
+}
 function textSequenceForCheck(viewport, check) {
   const key = selectorKey(check);
   const sequence = viewport.text_sequences?.[key];
@@ -2513,6 +2524,40 @@ function assessCheckFromEvidence(check, evidence) {
       message: failed ? `Selector ${key} text order failed in ${failed} viewport(s).` : void 0
     };
   }
+  if (check.type === "observe_within") {
+    const key = observeWithinKey(check);
+    const timeoutMs = observeWithinTimeoutMs(check);
+    const results = viewports.map((viewport) => {
+      const observation = viewport.observations?.[key];
+      const matched = observation?.matched === true;
+      return {
+        viewport: viewport.name,
+        matched,
+        elapsed_ms: numberValue(observation?.elapsed_ms) ?? null,
+        timeout_ms: numberValue(observation?.timeout_ms) ?? timeoutMs,
+        attempts: numberValue(observation?.attempts) ?? null,
+        selector_count: numberValue(observation?.selector_count) ?? null,
+        visible_count: numberValue(observation?.visible_count) ?? null,
+        matched_count: numberValue(observation?.matched_count) ?? null,
+        sample: stringValue(observation?.sample) ?? null,
+        error: stringValue(observation?.error) ?? null
+      };
+    });
+    const failed = results.filter((result) => !result.matched).length;
+    return {
+      type: check.type,
+      label: checkLabel(check),
+      status: failed ? "failed" : "passed",
+      evidence: {
+        selector: check.selector || null,
+        text: check.text || null,
+        pattern: check.pattern || null,
+        timeout_ms: timeoutMs,
+        viewports: results.map((result) => toJsonValue(result))
+      },
+      message: failed ? `Observation did not match within ${timeoutMs}ms in ${failed} viewport(s).` : void 0
+    };
+  }
   if (check.type === "frame_text_visible") {
     const key = selectorKey(check);
     const results = viewports.map((viewport) => {
@@ -4422,6 +4467,36 @@ function assessProfile(profile, evidence) {
       });
       continue;
     }
+    if (check.type === "observe_within") {
+      const key = observeWithinKey(check);
+      const timeoutMs = observeWithinTimeoutMs(check);
+      const results = checkViewports.map((viewport) => {
+        const observation = viewport.observations && viewport.observations[key] && typeof viewport.observations[key] === "object"
+          ? viewport.observations[key]
+          : {};
+        return {
+          viewport: viewport.name,
+          matched: observation.matched === true,
+          elapsed_ms: typeof observation.elapsed_ms === "number" && Number.isFinite(observation.elapsed_ms) ? observation.elapsed_ms : null,
+          timeout_ms: typeof observation.timeout_ms === "number" && Number.isFinite(observation.timeout_ms) ? observation.timeout_ms : timeoutMs,
+          attempts: typeof observation.attempts === "number" && Number.isFinite(observation.attempts) ? observation.attempts : null,
+          selector_count: typeof observation.selector_count === "number" && Number.isFinite(observation.selector_count) ? observation.selector_count : null,
+          visible_count: typeof observation.visible_count === "number" && Number.isFinite(observation.visible_count) ? observation.visible_count : null,
+          matched_count: typeof observation.matched_count === "number" && Number.isFinite(observation.matched_count) ? observation.matched_count : null,
+          sample: typeof observation.sample === "string" && observation.sample.trim() ? observation.sample.trim() : null,
+          error: typeof observation.error === "string" && observation.error.trim() ? observation.error.trim() : null,
+        };
+      });
+      const failed = results.filter((result) => !result.matched).length;
+      checks.push({
+        type: check.type,
+        label: check.label || check.type,
+        status: failed ? "failed" : "passed",
+        evidence: { selector: check.selector || null, text: check.text || null, pattern: check.pattern || null, timeout_ms: timeoutMs, viewports: results },
+        message: failed ? "Observation did not match within " + timeoutMs + "ms in " + failed + " viewport(s)." : undefined,
+      });
+      continue;
+    }
     if (check.type === "frame_text_visible") {
       const selector = check.selector || "";
       const results = checkViewports.map((viewport) => {
@@ -4854,6 +4929,19 @@ function ensureDialogHandler() {
 function textKey(check) {
   return check.pattern ? "pattern:" + check.pattern + "/" + (check.flags || "") : "text:" + (check.text || "");
 }
+function observeWithinTimeoutMs(check) {
+  const raw = Number(check && check.timeout_ms);
+  return Number.isFinite(raw) && raw > 0 ? Math.min(Math.round(raw), 60000) : 2000;
+}
+function observeWithinKey(check) {
+  const target = check && check.selector ? "selector:" + check.selector : "page";
+  const expectation = check && check.pattern
+    ? "pattern:" + check.pattern + "/" + (check.flags || "")
+    : check && check.text
+      ? "text:" + check.text
+      : "visible";
+  return target + "|" + expectation + "|within:" + observeWithinTimeoutMs(check);
+}
 function textMatches(sample, check) {
   if (check.pattern) {
     try { return new RegExp(check.pattern, check.flags || "").test(sample || ""); } catch { return false; }
@@ -6169,6 +6257,104 @@ async function selectorTextSequence(selector) {
     };
   }).catch((error) => ({ count: 0, visible_count: 0, texts: [], visible_texts: [], match_texts: [], visible_match_texts: [], error: String(error && error.message ? error.message : error).slice(0, 500) }));
 }
+async function observeWithinSnapshot(check) {
+  const payload = {
+    selector: check.selector || "",
+    text: check.text || "",
+    pattern: check.pattern || "",
+    flags: check.flags || "",
+    wants_text: Boolean(check.text || check.pattern),
+  };
+  if (payload.selector) {
+    return page.locator(payload.selector).evaluateAll((elements, input) => {
+      const compact = (value) => String(value || "").replace(/\s+/g, " ").trim();
+      const matchText = (value) => {
+        const source = compact(value);
+        if (input.pattern) {
+          try { return new RegExp(input.pattern, input.flags || "").test(source); } catch { return false; }
+        }
+        return source.includes(input.text || "");
+      };
+      const isVisible = (element) => {
+        const style = window.getComputedStyle(element);
+        const rect = element.getBoundingClientRect();
+        return style && style.visibility !== "hidden" && style.display !== "none" && rect.width > 0 && rect.height > 0;
+      };
+      const rows = elements.map((element, index) => {
+        const text = compact(element.innerText || element.textContent || "");
+        const visible = isVisible(element);
+        return { index, text, visible, matched: input.wants_text ? matchText(text) : visible };
+      });
+      const visibleRows = rows.filter((row) => row.visible);
+      const matches = input.wants_text ? visibleRows.filter((row) => row.matched) : visibleRows;
+      const sampleRow = matches[0] || visibleRows[0] || rows[0] || null;
+      return {
+        selector: input.selector,
+        text: input.text || null,
+        pattern: input.pattern || null,
+        selector_count: rows.length,
+        visible_count: visibleRows.length,
+        matched_count: matches.length,
+        matched: matches.length > 0,
+        sample: sampleRow && sampleRow.text ? sampleRow.text.slice(0, 240) : null,
+      };
+    }, payload).catch((error) => ({
+      selector: payload.selector,
+      text: payload.text || null,
+      pattern: payload.pattern || null,
+      selector_count: 0,
+      visible_count: 0,
+      matched_count: 0,
+      matched: false,
+      sample: null,
+      error: String(error && error.message ? error.message : error).slice(0, 500),
+    }));
+  }
+  return page.evaluate((input) => {
+    const compact = (value) => String(value || "").replace(/\s+/g, " ").trim();
+    const sample = compact(document.body ? document.body.innerText || document.body.textContent || "" : "");
+    let matched = false;
+    if (input.pattern) {
+      try { matched = new RegExp(input.pattern, input.flags || "").test(sample); } catch { matched = false; }
+    } else {
+      matched = sample.includes(input.text || "");
+    }
+    return {
+      selector: null,
+      text: input.text || null,
+      pattern: input.pattern || null,
+      matched,
+      matched_count: matched ? 1 : 0,
+      sample: sample.slice(0, 240),
+    };
+  }, payload).catch((error) => ({
+    selector: null,
+    text: payload.text || null,
+    pattern: payload.pattern || null,
+    matched: false,
+    matched_count: 0,
+    sample: null,
+    error: String(error && error.message ? error.message : error).slice(0, 500),
+  }));
+}
+async function observeWithin(check) {
+  const timeoutMs = observeWithinTimeoutMs(check);
+  const startedAt = Date.now();
+  let attempts = 0;
+  let last = null;
+  while (true) {
+    attempts += 1;
+    last = await observeWithinSnapshot(check);
+    const elapsedMs = Date.now() - startedAt;
+    if (last && last.matched === true) {
+      return { ...last, timeout_ms: timeoutMs, elapsed_ms: elapsedMs, attempts };
+    }
+    if (elapsedMs >= timeoutMs) {
+      return { ...(last || {}), matched: false, timeout_ms: timeoutMs, elapsed_ms: elapsedMs, attempts };
+    }
+    await page.waitForTimeout(Math.min(100, Math.max(25, timeoutMs - elapsedMs)));
+  }
+}
 function linkProbeMaxLinks(check) {
   const value = Number(check.max_links || check.maxLinks || check.limit || 100);
   return Number.isInteger(value) && value > 0 ? Math.min(value, 500) : 100;
@@ -7221,6 +7407,7 @@ async function captureViewport(viewport) {
   const text_matches = {};
   const text_match_samples = {};
   const text_case_insensitive_samples = {};
+  const observations = {};
   const http_statuses = {};
   const link_statuses = {};
   for (const check of profile.checks || []) {
@@ -7241,6 +7428,10 @@ async function captureViewport(viewport) {
       selectors[check.selector] = selectors[check.selector] || await selectorStats(check.selector);
       text_sequences[check.selector] = await selectorTextSequence(check.selector);
     }
+    if (check.type === "observe_within") {
+      const key = observeWithinKey(check);
+      observations[key] = observations[key] || await observeWithin(check);
+    }
     if ((check.type === "text_visible" || check.type === "text_absent") && (check.text || check.pattern)) {
       const key = textKey(check);
       const sample = dom.body_text || dom.body_text_sample || "";
@@ -7334,6 +7525,7 @@ async function captureViewport(viewport) {
     text_matches,
     text_match_samples,
     text_case_insensitive_samples,
+    observations,
     http_statuses,
     link_statuses,
     route_inventory: routeInventory,

package/dist/cli.cjs

@@ -6975,6 +6975,7 @@ var RIDDLE_PROOF_PROFILE_CHECK_TYPES = [
   "selector_text_visible",
   "selector_text_absent",
   "selector_text_order",
+  "observe_within",
   "frame_text_visible",
   "frame_url_equals",
   "frame_url_matches",
@@ -8297,7 +8298,7 @@ function normalizeCheck(input, index) {
     throw new Error(`checks[${index}].type ${type} is not supported. Supported checks: ${RIDDLE_PROOF_PROFILE_CHECK_TYPES.join(", ")}`);
   }
   const isDialogCountCheck = isDialogCountCheckType(type);
-  if ((type === "selector_visible" || type === "selector_absent" || type === "selector_count_at_least" || type === "selector_count_equals" || type === "selector_count_equal" || type === "selector_count_eq" || type === "selector_text_visible" || type === "selector_text_absent") && !stringValue2(input.selector)) {
+  if ((type === "selector_visible" || type === "selector_absent" || type === "selector_count_at_least" || type === "selector_count_equals" || type === "selector_count_equal" || type === "selector_count_eq" || type === "selector_text_visible" || type === "selector_text_absent" || type === "observe_within" && !stringValue2(input.text) && !stringValue2(input.pattern)) && !stringValue2(input.selector)) {
     throw new Error(`checks[${index}] ${type} requires selector.`);
   }
   if ((type === "frame_text_visible" || type === "frame_url_equals" || type === "frame_url_matches" || type === "frame_no_horizontal_overflow") && !stringValue2(input.selector)) {
@@ -8438,7 +8439,7 @@ function normalizeCheck(input, index) {
     allowed_content_types: allowedContentTypes,
     allow_get_fallback: isLinkStatusCheck ? input.allow_get_fallback === false || input.allowGetFallback === false ? false : true : void 0,
     max_overflow_px: numberValue(input.max_overflow_px),
-    timeout_ms: numberValue(input.timeout_ms) ?? numberValue(input.timeoutMs),
+    timeout_ms: numberValue(input.timeout_ms) ?? numberValue(input.timeoutMs) ?? numberValue(input.within_ms) ?? numberValue(input.withinMs),
     run_direct_routes: input.run_direct_routes === false || input.runDirectRoutes === false ? false : true,
     run_clickthroughs: input.run_clickthroughs === false || input.runClickthroughs === false ? false : true,
     run_all_viewports: input.run_all_viewports === true || input.runAllViewports === true,
@@ -8956,6 +8957,16 @@ function summarizeLinkStatusEvidence(viewport, check) {
 function textKey(check) {
   return check.pattern ? `pattern:${check.pattern}/${check.flags || ""}` : `text:${check.text || ""}`;
 }
+function observeWithinTimeoutMs(check) {
+  const raw = check.timeout_ms;
+  if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) return Math.min(Math.round(raw), 6e4);
+  return 2e3;
+}
+function observeWithinKey(check) {
+  const target = check.selector ? `selector:${check.selector}` : "page";
+  const expectation = check.pattern ? `pattern:${check.pattern}/${check.flags || ""}` : check.text ? `text:${check.text}` : "visible";
+  return `${target}|${expectation}|within:${observeWithinTimeoutMs(check)}`;
+}
 function textSequenceForCheck(viewport, check) {
   const key = selectorKey(check);
   const sequence = viewport.text_sequences?.[key];
@@ -9462,6 +9473,40 @@ function assessCheckFromEvidence(check, evidence) {
       message: failed ? `Selector ${key} text order failed in ${failed} viewport(s).` : void 0
     };
   }
+  if (check.type === "observe_within") {
+    const key = observeWithinKey(check);
+    const timeoutMs = observeWithinTimeoutMs(check);
+    const results = viewports.map((viewport) => {
+      const observation = viewport.observations?.[key];
+      const matched = observation?.matched === true;
+      return {
+        viewport: viewport.name,
+        matched,
+        elapsed_ms: numberValue(observation?.elapsed_ms) ?? null,
+        timeout_ms: numberValue(observation?.timeout_ms) ?? timeoutMs,
+        attempts: numberValue(observation?.attempts) ?? null,
+        selector_count: numberValue(observation?.selector_count) ?? null,
+        visible_count: numberValue(observation?.visible_count) ?? null,
+        matched_count: numberValue(observation?.matched_count) ?? null,
+        sample: stringValue2(observation?.sample) ?? null,
+        error: stringValue2(observation?.error) ?? null
+      };
+    });
+    const failed = results.filter((result) => !result.matched).length;
+    return {
+      type: check.type,
+      label: checkLabel(check),
+      status: failed ? "failed" : "passed",
+      evidence: {
+        selector: check.selector || null,
+        text: check.text || null,
+        pattern: check.pattern || null,
+        timeout_ms: timeoutMs,
+        viewports: results.map((result) => toJsonValue(result))
+      },
+      message: failed ? `Observation did not match within ${timeoutMs}ms in ${failed} viewport(s).` : void 0
+    };
+  }
   if (check.type === "frame_text_visible") {
     const key = selectorKey(check);
     const results = viewports.map((viewport) => {
@@ -11355,6 +11400,36 @@ function assessProfile(profile, evidence) {
       });
       continue;
     }
+    if (check.type === "observe_within") {
+      const key = observeWithinKey(check);
+      const timeoutMs = observeWithinTimeoutMs(check);
+      const results = checkViewports.map((viewport) => {
+        const observation = viewport.observations && viewport.observations[key] && typeof viewport.observations[key] === "object"
+          ? viewport.observations[key]
+          : {};
+        return {
+          viewport: viewport.name,
+          matched: observation.matched === true,
+          elapsed_ms: typeof observation.elapsed_ms === "number" && Number.isFinite(observation.elapsed_ms) ? observation.elapsed_ms : null,
+          timeout_ms: typeof observation.timeout_ms === "number" && Number.isFinite(observation.timeout_ms) ? observation.timeout_ms : timeoutMs,
+          attempts: typeof observation.attempts === "number" && Number.isFinite(observation.attempts) ? observation.attempts : null,
+          selector_count: typeof observation.selector_count === "number" && Number.isFinite(observation.selector_count) ? observation.selector_count : null,
+          visible_count: typeof observation.visible_count === "number" && Number.isFinite(observation.visible_count) ? observation.visible_count : null,
+          matched_count: typeof observation.matched_count === "number" && Number.isFinite(observation.matched_count) ? observation.matched_count : null,
+          sample: typeof observation.sample === "string" && observation.sample.trim() ? observation.sample.trim() : null,
+          error: typeof observation.error === "string" && observation.error.trim() ? observation.error.trim() : null,
+        };
+      });
+      const failed = results.filter((result) => !result.matched).length;
+      checks.push({
+        type: check.type,
+        label: check.label || check.type,
+        status: failed ? "failed" : "passed",
+        evidence: { selector: check.selector || null, text: check.text || null, pattern: check.pattern || null, timeout_ms: timeoutMs, viewports: results },
+        message: failed ? "Observation did not match within " + timeoutMs + "ms in " + failed + " viewport(s)." : undefined,
+      });
+      continue;
+    }
     if (check.type === "frame_text_visible") {
       const selector = check.selector || "";
       const results = checkViewports.map((viewport) => {
@@ -11787,6 +11862,19 @@ function ensureDialogHandler() {
 function textKey(check) {
   return check.pattern ? "pattern:" + check.pattern + "/" + (check.flags || "") : "text:" + (check.text || "");
 }
+function observeWithinTimeoutMs(check) {
+  const raw = Number(check && check.timeout_ms);
+  return Number.isFinite(raw) && raw > 0 ? Math.min(Math.round(raw), 60000) : 2000;
+}
+function observeWithinKey(check) {
+  const target = check && check.selector ? "selector:" + check.selector : "page";
+  const expectation = check && check.pattern
+    ? "pattern:" + check.pattern + "/" + (check.flags || "")
+    : check && check.text
+      ? "text:" + check.text
+      : "visible";
+  return target + "|" + expectation + "|within:" + observeWithinTimeoutMs(check);
+}
 function textMatches(sample, check) {
   if (check.pattern) {
     try { return new RegExp(check.pattern, check.flags || "").test(sample || ""); } catch { return false; }
@@ -13102,6 +13190,104 @@ async function selectorTextSequence(selector) {
     };
   }).catch((error) => ({ count: 0, visible_count: 0, texts: [], visible_texts: [], match_texts: [], visible_match_texts: [], error: String(error && error.message ? error.message : error).slice(0, 500) }));
 }
+async function observeWithinSnapshot(check) {
+  const payload = {
+    selector: check.selector || "",
+    text: check.text || "",
+    pattern: check.pattern || "",
+    flags: check.flags || "",
+    wants_text: Boolean(check.text || check.pattern),
+  };
+  if (payload.selector) {
+    return page.locator(payload.selector).evaluateAll((elements, input) => {
+      const compact = (value) => String(value || "").replace(/\s+/g, " ").trim();
+      const matchText = (value) => {
+        const source = compact(value);
+        if (input.pattern) {
+          try { return new RegExp(input.pattern, input.flags || "").test(source); } catch { return false; }
+        }
+        return source.includes(input.text || "");
+      };
+      const isVisible = (element) => {
+        const style = window.getComputedStyle(element);
+        const rect = element.getBoundingClientRect();
+        return style && style.visibility !== "hidden" && style.display !== "none" && rect.width > 0 && rect.height > 0;
+      };
+      const rows = elements.map((element, index) => {
+        const text = compact(element.innerText || element.textContent || "");
+        const visible = isVisible(element);
+        return { index, text, visible, matched: input.wants_text ? matchText(text) : visible };
+      });
+      const visibleRows = rows.filter((row) => row.visible);
+      const matches = input.wants_text ? visibleRows.filter((row) => row.matched) : visibleRows;
+      const sampleRow = matches[0] || visibleRows[0] || rows[0] || null;
+      return {
+        selector: input.selector,
+        text: input.text || null,
+        pattern: input.pattern || null,
+        selector_count: rows.length,
+        visible_count: visibleRows.length,
+        matched_count: matches.length,
+        matched: matches.length > 0,
+        sample: sampleRow && sampleRow.text ? sampleRow.text.slice(0, 240) : null,
+      };
+    }, payload).catch((error) => ({
+      selector: payload.selector,
+      text: payload.text || null,
+      pattern: payload.pattern || null,
+      selector_count: 0,
+      visible_count: 0,
+      matched_count: 0,
+      matched: false,
+      sample: null,
+      error: String(error && error.message ? error.message : error).slice(0, 500),
+    }));
+  }
+  return page.evaluate((input) => {
+    const compact = (value) => String(value || "").replace(/\s+/g, " ").trim();
+    const sample = compact(document.body ? document.body.innerText || document.body.textContent || "" : "");
+    let matched = false;
+    if (input.pattern) {
+      try { matched = new RegExp(input.pattern, input.flags || "").test(sample); } catch { matched = false; }
+    } else {
+      matched = sample.includes(input.text || "");
+    }
+    return {
+      selector: null,
+      text: input.text || null,
+      pattern: input.pattern || null,
+      matched,
+      matched_count: matched ? 1 : 0,
+      sample: sample.slice(0, 240),
+    };
+  }, payload).catch((error) => ({
+    selector: null,
+    text: payload.text || null,
+    pattern: payload.pattern || null,
+    matched: false,
+    matched_count: 0,
+    sample: null,
+    error: String(error && error.message ? error.message : error).slice(0, 500),
+  }));
+}
+async function observeWithin(check) {
+  const timeoutMs = observeWithinTimeoutMs(check);
+  const startedAt = Date.now();
+  let attempts = 0;
+  let last = null;
+  while (true) {
+    attempts += 1;
+    last = await observeWithinSnapshot(check);
+    const elapsedMs = Date.now() - startedAt;
+    if (last && last.matched === true) {
+      return { ...last, timeout_ms: timeoutMs, elapsed_ms: elapsedMs, attempts };
+    }
+    if (elapsedMs >= timeoutMs) {
+      return { ...(last || {}), matched: false, timeout_ms: timeoutMs, elapsed_ms: elapsedMs, attempts };
+    }
+    await page.waitForTimeout(Math.min(100, Math.max(25, timeoutMs - elapsedMs)));
+  }
+}
 function linkProbeMaxLinks(check) {
   const value = Number(check.max_links || check.maxLinks || check.limit || 100);
   return Number.isInteger(value) && value > 0 ? Math.min(value, 500) : 100;
@@ -14154,6 +14340,7 @@ async function captureViewport(viewport) {
   const text_matches = {};
   const text_match_samples = {};
   const text_case_insensitive_samples = {};
+  const observations = {};
   const http_statuses = {};
   const link_statuses = {};
   for (const check of profile.checks || []) {
@@ -14174,6 +14361,10 @@ async function captureViewport(viewport) {
       selectors[check.selector] = selectors[check.selector] || await selectorStats(check.selector);
       text_sequences[check.selector] = await selectorTextSequence(check.selector);
     }
+    if (check.type === "observe_within") {
+      const key = observeWithinKey(check);
+      observations[key] = observations[key] || await observeWithin(check);
+    }
     if ((check.type === "text_visible" || check.type === "text_absent") && (check.text || check.pattern)) {
       const key = textKey(check);
       const sample = dom.body_text || dom.body_text_sample || "";
@@ -14267,6 +14458,7 @@ async function captureViewport(viewport) {
     text_matches,
     text_match_samples,
     text_case_insensitive_samples,
+    observations,
     http_statuses,
     link_statuses,
     route_inventory: routeInventory,
@@ -14949,6 +15141,14 @@ function profileCheckMarkdownTarget(check) {
   if (check.type === "selector_text_order") {
     return selector ? `${markdownInlineCode(selector)} text order` : void 0;
   }
+  if (check.type === "observe_within") {
+    const textTarget = profileCheckTextTarget(evidence);
+    const timeoutMs = cliFiniteNumber(evidence.timeout_ms);
+    const withinLabel = timeoutMs === void 0 ? "within timeout" : `within ${timeoutMs}ms`;
+    if (selector && textTarget) return `${markdownInlineCode(selector)} observes ${textTarget} ${withinLabel}`;
+    if (selector) return `${markdownInlineCode(selector)} visible ${withinLabel}`;
+    return textTarget ? `${textTarget} ${withinLabel}` : withinLabel;
+  }
   if (check.type === "text_visible" || check.type === "text_absent") {
     return profileCheckTextTarget(evidence);
   }

package/dist/cli.js

@@ -13,7 +13,7 @@ import {
   profileStatusExitCode,
   resolveRiddleProofProfileTargetUrl,
   resolveRiddleProofProfileTimeoutSec
-} from "./chunk-QXQCG3WB.js";
+} from "./chunk-QJJ3ISMK.js";
 import {
   createRiddleApiClient,
   parseRiddleViewport
@@ -507,6 +507,14 @@ function profileCheckMarkdownTarget(check) {
   if (check.type === "selector_text_order") {
     return selector ? `${markdownInlineCode(selector)} text order` : void 0;
   }
+  if (check.type === "observe_within") {
+    const textTarget = profileCheckTextTarget(evidence);
+    const timeoutMs = cliFiniteNumber(evidence.timeout_ms);
+    const withinLabel = timeoutMs === void 0 ? "within timeout" : `within ${timeoutMs}ms`;
+    if (selector && textTarget) return `${markdownInlineCode(selector)} observes ${textTarget} ${withinLabel}`;
+    if (selector) return `${markdownInlineCode(selector)} visible ${withinLabel}`;
+    return textTarget ? `${textTarget} ${withinLabel}` : withinLabel;
+  }
   if (check.type === "text_visible" || check.type === "text_absent") {
     return profileCheckTextTarget(evidence);
   }

package/dist/index.cjs

@@ -8759,6 +8759,7 @@ var RIDDLE_PROOF_PROFILE_CHECK_TYPES = [
   "selector_text_visible",
   "selector_text_absent",
   "selector_text_order",
+  "observe_within",
   "frame_text_visible",
   "frame_url_equals",
   "frame_url_matches",
@@ -10081,7 +10082,7 @@ function normalizeCheck(input, index) {
     throw new Error(`checks[${index}].type ${type} is not supported. Supported checks: ${RIDDLE_PROOF_PROFILE_CHECK_TYPES.join(", ")}`);
   }
   const isDialogCountCheck = isDialogCountCheckType(type);
-  if ((type === "selector_visible" || type === "selector_absent" || type === "selector_count_at_least" || type === "selector_count_equals" || type === "selector_count_equal" || type === "selector_count_eq" || type === "selector_text_visible" || type === "selector_text_absent") && !stringValue5(input.selector)) {
+  if ((type === "selector_visible" || type === "selector_absent" || type === "selector_count_at_least" || type === "selector_count_equals" || type === "selector_count_equal" || type === "selector_count_eq" || type === "selector_text_visible" || type === "selector_text_absent" || type === "observe_within" && !stringValue5(input.text) && !stringValue5(input.pattern)) && !stringValue5(input.selector)) {
     throw new Error(`checks[${index}] ${type} requires selector.`);
   }
   if ((type === "frame_text_visible" || type === "frame_url_equals" || type === "frame_url_matches" || type === "frame_no_horizontal_overflow") && !stringValue5(input.selector)) {
@@ -10222,7 +10223,7 @@ function normalizeCheck(input, index) {
     allowed_content_types: allowedContentTypes,
     allow_get_fallback: isLinkStatusCheck ? input.allow_get_fallback === false || input.allowGetFallback === false ? false : true : void 0,
     max_overflow_px: numberValue3(input.max_overflow_px),
-    timeout_ms: numberValue3(input.timeout_ms) ?? numberValue3(input.timeoutMs),
+    timeout_ms: numberValue3(input.timeout_ms) ?? numberValue3(input.timeoutMs) ?? numberValue3(input.within_ms) ?? numberValue3(input.withinMs),
     run_direct_routes: input.run_direct_routes === false || input.runDirectRoutes === false ? false : true,
     run_clickthroughs: input.run_clickthroughs === false || input.runClickthroughs === false ? false : true,
     run_all_viewports: input.run_all_viewports === true || input.runAllViewports === true,
@@ -10740,6 +10741,16 @@ function summarizeLinkStatusEvidence(viewport, check) {
 function textKey(check) {
   return check.pattern ? `pattern:${check.pattern}/${check.flags || ""}` : `text:${check.text || ""}`;
 }
+function observeWithinTimeoutMs(check) {
+  const raw = check.timeout_ms;
+  if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) return Math.min(Math.round(raw), 6e4);
+  return 2e3;
+}
+function observeWithinKey(check) {
+  const target = check.selector ? `selector:${check.selector}` : "page";
+  const expectation = check.pattern ? `pattern:${check.pattern}/${check.flags || ""}` : check.text ? `text:${check.text}` : "visible";
+  return `${target}|${expectation}|within:${observeWithinTimeoutMs(check)}`;
+}
 function textSequenceForCheck(viewport, check) {
   const key = selectorKey(check);
   const sequence = viewport.text_sequences?.[key];
@@ -11246,6 +11257,40 @@ function assessCheckFromEvidence(check, evidence) {
       message: failed ? `Selector ${key} text order failed in ${failed} viewport(s).` : void 0
     };
   }
+  if (check.type === "observe_within") {
+    const key = observeWithinKey(check);
+    const timeoutMs = observeWithinTimeoutMs(check);
+    const results = viewports.map((viewport) => {
+      const observation = viewport.observations?.[key];
+      const matched = observation?.matched === true;
+      return {
+        viewport: viewport.name,
+        matched,
+        elapsed_ms: numberValue3(observation?.elapsed_ms) ?? null,
+        timeout_ms: numberValue3(observation?.timeout_ms) ?? timeoutMs,
+        attempts: numberValue3(observation?.attempts) ?? null,
+        selector_count: numberValue3(observation?.selector_count) ?? null,
+        visible_count: numberValue3(observation?.visible_count) ?? null,
+        matched_count: numberValue3(observation?.matched_count) ?? null,
+        sample: stringValue5(observation?.sample) ?? null,
+        error: stringValue5(observation?.error) ?? null
+      };
+    });
+    const failed = results.filter((result) => !result.matched).length;
+    return {
+      type: check.type,
+      label: checkLabel(check),
+      status: failed ? "failed" : "passed",
+      evidence: {
+        selector: check.selector || null,
+        text: check.text || null,
+        pattern: check.pattern || null,
+        timeout_ms: timeoutMs,
+        viewports: results.map((result) => toJsonValue(result))
+      },
+      message: failed ? `Observation did not match within ${timeoutMs}ms in ${failed} viewport(s).` : void 0
+    };
+  }
   if (check.type === "frame_text_visible") {
     const key = selectorKey(check);
     const results = viewports.map((viewport) => {
@@ -13155,6 +13200,36 @@ function assessProfile(profile, evidence) {
       });
       continue;
     }
+    if (check.type === "observe_within") {
+      const key = observeWithinKey(check);
+      const timeoutMs = observeWithinTimeoutMs(check);
+      const results = checkViewports.map((viewport) => {
+        const observation = viewport.observations && viewport.observations[key] && typeof viewport.observations[key] === "object"
+          ? viewport.observations[key]
+          : {};
+        return {
+          viewport: viewport.name,
+          matched: observation.matched === true,
+          elapsed_ms: typeof observation.elapsed_ms === "number" && Number.isFinite(observation.elapsed_ms) ? observation.elapsed_ms : null,
+          timeout_ms: typeof observation.timeout_ms === "number" && Number.isFinite(observation.timeout_ms) ? observation.timeout_ms : timeoutMs,
+          attempts: typeof observation.attempts === "number" && Number.isFinite(observation.attempts) ? observation.attempts : null,
+          selector_count: typeof observation.selector_count === "number" && Number.isFinite(observation.selector_count) ? observation.selector_count : null,
+          visible_count: typeof observation.visible_count === "number" && Number.isFinite(observation.visible_count) ? observation.visible_count : null,
+          matched_count: typeof observation.matched_count === "number" && Number.isFinite(observation.matched_count) ? observation.matched_count : null,
+          sample: typeof observation.sample === "string" && observation.sample.trim() ? observation.sample.trim() : null,
+          error: typeof observation.error === "string" && observation.error.trim() ? observation.error.trim() : null,
+        };
+      });
+      const failed = results.filter((result) => !result.matched).length;
+      checks.push({
+        type: check.type,
+        label: check.label || check.type,
+        status: failed ? "failed" : "passed",
+        evidence: { selector: check.selector || null, text: check.text || null, pattern: check.pattern || null, timeout_ms: timeoutMs, viewports: results },
+        message: failed ? "Observation did not match within " + timeoutMs + "ms in " + failed + " viewport(s)." : undefined,
+      });
+      continue;
+    }
     if (check.type === "frame_text_visible") {
       const selector = check.selector || "";
       const results = checkViewports.map((viewport) => {
@@ -13587,6 +13662,19 @@ function ensureDialogHandler() {
 function textKey(check) {
   return check.pattern ? "pattern:" + check.pattern + "/" + (check.flags || "") : "text:" + (check.text || "");
 }
+function observeWithinTimeoutMs(check) {
+  const raw = Number(check && check.timeout_ms);
+  return Number.isFinite(raw) && raw > 0 ? Math.min(Math.round(raw), 60000) : 2000;
+}
+function observeWithinKey(check) {
+  const target = check && check.selector ? "selector:" + check.selector : "page";
+  const expectation = check && check.pattern
+    ? "pattern:" + check.pattern + "/" + (check.flags || "")
+    : check && check.text
+      ? "text:" + check.text
+      : "visible";
+  return target + "|" + expectation + "|within:" + observeWithinTimeoutMs(check);
+}
 function textMatches(sample, check) {
   if (check.pattern) {
     try { return new RegExp(check.pattern, check.flags || "").test(sample || ""); } catch { return false; }
@@ -14902,6 +14990,104 @@ async function selectorTextSequence(selector) {
     };
   }).catch((error) => ({ count: 0, visible_count: 0, texts: [], visible_texts: [], match_texts: [], visible_match_texts: [], error: String(error && error.message ? error.message : error).slice(0, 500) }));
 }
+async function observeWithinSnapshot(check) {
+  const payload = {
+    selector: check.selector || "",
+    text: check.text || "",
+    pattern: check.pattern || "",
+    flags: check.flags || "",
+    wants_text: Boolean(check.text || check.pattern),
+  };
+  if (payload.selector) {
+    return page.locator(payload.selector).evaluateAll((elements, input) => {
+      const compact = (value) => String(value || "").replace(/\s+/g, " ").trim();
+      const matchText = (value) => {
+        const source = compact(value);
+        if (input.pattern) {
+          try { return new RegExp(input.pattern, input.flags || "").test(source); } catch { return false; }
+        }
+        return source.includes(input.text || "");
+      };
+      const isVisible = (element) => {
+        const style = window.getComputedStyle(element);
+        const rect = element.getBoundingClientRect();
+        return style && style.visibility !== "hidden" && style.display !== "none" && rect.width > 0 && rect.height > 0;
+      };
+      const rows = elements.map((element, index) => {
+        const text = compact(element.innerText || element.textContent || "");
+        const visible = isVisible(element);
+        return { index, text, visible, matched: input.wants_text ? matchText(text) : visible };
+      });
+      const visibleRows = rows.filter((row) => row.visible);
+      const matches = input.wants_text ? visibleRows.filter((row) => row.matched) : visibleRows;
+      const sampleRow = matches[0] || visibleRows[0] || rows[0] || null;
+      return {
+        selector: input.selector,
+        text: input.text || null,
+        pattern: input.pattern || null,
+        selector_count: rows.length,
+        visible_count: visibleRows.length,
+        matched_count: matches.length,
+        matched: matches.length > 0,
+        sample: sampleRow && sampleRow.text ? sampleRow.text.slice(0, 240) : null,
+      };
+    }, payload).catch((error) => ({
+      selector: payload.selector,
+      text: payload.text || null,
+      pattern: payload.pattern || null,
+      selector_count: 0,
+      visible_count: 0,
+      matched_count: 0,
+      matched: false,
+      sample: null,
+      error: String(error && error.message ? error.message : error).slice(0, 500),
+    }));
+  }
+  return page.evaluate((input) => {
+    const compact = (value) => String(value || "").replace(/\s+/g, " ").trim();
+    const sample = compact(document.body ? document.body.innerText || document.body.textContent || "" : "");
+    let matched = false;
+    if (input.pattern) {
+      try { matched = new RegExp(input.pattern, input.flags || "").test(sample); } catch { matched = false; }
+    } else {
+      matched = sample.includes(input.text || "");
+    }
+    return {
+      selector: null,
+      text: input.text || null,
+      pattern: input.pattern || null,
+      matched,
+      matched_count: matched ? 1 : 0,
+      sample: sample.slice(0, 240),
+    };
+  }, payload).catch((error) => ({
+    selector: null,
+    text: payload.text || null,
+    pattern: payload.pattern || null,
+    matched: false,
+    matched_count: 0,
+    sample: null,
+    error: String(error && error.message ? error.message : error).slice(0, 500),
+  }));
+}
+async function observeWithin(check) {
+  const timeoutMs = observeWithinTimeoutMs(check);
+  const startedAt = Date.now();
+  let attempts = 0;
+  let last = null;
+  while (true) {
+    attempts += 1;
+    last = await observeWithinSnapshot(check);
+    const elapsedMs = Date.now() - startedAt;
+    if (last && last.matched === true) {
+      return { ...last, timeout_ms: timeoutMs, elapsed_ms: elapsedMs, attempts };
+    }
+    if (elapsedMs >= timeoutMs) {
+      return { ...(last || {}), matched: false, timeout_ms: timeoutMs, elapsed_ms: elapsedMs, attempts };
+    }
+    await page.waitForTimeout(Math.min(100, Math.max(25, timeoutMs - elapsedMs)));
+  }
+}
 function linkProbeMaxLinks(check) {
   const value = Number(check.max_links || check.maxLinks || check.limit || 100);
   return Number.isInteger(value) && value > 0 ? Math.min(value, 500) : 100;
@@ -15954,6 +16140,7 @@ async function captureViewport(viewport) {
   const text_matches = {};
   const text_match_samples = {};
   const text_case_insensitive_samples = {};
+  const observations = {};
   const http_statuses = {};
   const link_statuses = {};
   for (const check of profile.checks || []) {
@@ -15974,6 +16161,10 @@ async function captureViewport(viewport) {
       selectors[check.selector] = selectors[check.selector] || await selectorStats(check.selector);
       text_sequences[check.selector] = await selectorTextSequence(check.selector);
     }
+    if (check.type === "observe_within") {
+      const key = observeWithinKey(check);
+      observations[key] = observations[key] || await observeWithin(check);
+    }
     if ((check.type === "text_visible" || check.type === "text_absent") && (check.text || check.pattern)) {
       const key = textKey(check);
       const sample = dom.body_text || dom.body_text_sample || "";
@@ -16067,6 +16258,7 @@ async function captureViewport(viewport) {
     text_matches,
     text_match_samples,
     text_case_insensitive_samples,
+    observations,
     http_statuses,
     link_statuses,
     route_inventory: routeInventory,

package/dist/index.js

@@ -62,7 +62,7 @@ import {
   resolveRiddleProofProfileTimeoutSec,
   slugifyRiddleProofProfileName,
   summarizeRiddleProofProfileResult
-} from "./chunk-QXQCG3WB.js";
+} from "./chunk-QJJ3ISMK.js";
 import {
   DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE,

package/dist/profile.cjs

@@ -73,6 +73,7 @@ var RIDDLE_PROOF_PROFILE_CHECK_TYPES = [
   "selector_text_visible",
   "selector_text_absent",
   "selector_text_order",
+  "observe_within",
   "frame_text_visible",
   "frame_url_equals",
   "frame_url_matches",
@@ -1395,7 +1396,7 @@ function normalizeCheck(input, index) {
     throw new Error(`checks[${index}].type ${type} is not supported. Supported checks: ${RIDDLE_PROOF_PROFILE_CHECK_TYPES.join(", ")}`);
   }
   const isDialogCountCheck = isDialogCountCheckType(type);
-  if ((type === "selector_visible" || type === "selector_absent" || type === "selector_count_at_least" || type === "selector_count_equals" || type === "selector_count_equal" || type === "selector_count_eq" || type === "selector_text_visible" || type === "selector_text_absent") && !stringValue(input.selector)) {
+  if ((type === "selector_visible" || type === "selector_absent" || type === "selector_count_at_least" || type === "selector_count_equals" || type === "selector_count_equal" || type === "selector_count_eq" || type === "selector_text_visible" || type === "selector_text_absent" || type === "observe_within" && !stringValue(input.text) && !stringValue(input.pattern)) && !stringValue(input.selector)) {
     throw new Error(`checks[${index}] ${type} requires selector.`);
   }
   if ((type === "frame_text_visible" || type === "frame_url_equals" || type === "frame_url_matches" || type === "frame_no_horizontal_overflow") && !stringValue(input.selector)) {
@@ -1536,7 +1537,7 @@ function normalizeCheck(input, index) {
     allowed_content_types: allowedContentTypes,
     allow_get_fallback: isLinkStatusCheck ? input.allow_get_fallback === false || input.allowGetFallback === false ? false : true : void 0,
     max_overflow_px: numberValue(input.max_overflow_px),
-    timeout_ms: numberValue(input.timeout_ms) ?? numberValue(input.timeoutMs),
+    timeout_ms: numberValue(input.timeout_ms) ?? numberValue(input.timeoutMs) ?? numberValue(input.within_ms) ?? numberValue(input.withinMs),
     run_direct_routes: input.run_direct_routes === false || input.runDirectRoutes === false ? false : true,
     run_clickthroughs: input.run_clickthroughs === false || input.runClickthroughs === false ? false : true,
     run_all_viewports: input.run_all_viewports === true || input.runAllViewports === true,
@@ -2054,6 +2055,16 @@ function summarizeLinkStatusEvidence(viewport, check) {
 function textKey(check) {
   return check.pattern ? `pattern:${check.pattern}/${check.flags || ""}` : `text:${check.text || ""}`;
 }
+function observeWithinTimeoutMs(check) {
+  const raw = check.timeout_ms;
+  if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) return Math.min(Math.round(raw), 6e4);
+  return 2e3;
+}
+function observeWithinKey(check) {
+  const target = check.selector ? `selector:${check.selector}` : "page";
+  const expectation = check.pattern ? `pattern:${check.pattern}/${check.flags || ""}` : check.text ? `text:${check.text}` : "visible";
+  return `${target}|${expectation}|within:${observeWithinTimeoutMs(check)}`;
+}
 function textSequenceForCheck(viewport, check) {
   const key = selectorKey(check);
   const sequence = viewport.text_sequences?.[key];
@@ -2560,6 +2571,40 @@ function assessCheckFromEvidence(check, evidence) {
       message: failed ? `Selector ${key} text order failed in ${failed} viewport(s).` : void 0
     };
   }
+  if (check.type === "observe_within") {
+    const key = observeWithinKey(check);
+    const timeoutMs = observeWithinTimeoutMs(check);
+    const results = viewports.map((viewport) => {
+      const observation = viewport.observations?.[key];
+      const matched = observation?.matched === true;
+      return {
+        viewport: viewport.name,
+        matched,
+        elapsed_ms: numberValue(observation?.elapsed_ms) ?? null,
+        timeout_ms: numberValue(observation?.timeout_ms) ?? timeoutMs,
+        attempts: numberValue(observation?.attempts) ?? null,
+        selector_count: numberValue(observation?.selector_count) ?? null,
+        visible_count: numberValue(observation?.visible_count) ?? null,
+        matched_count: numberValue(observation?.matched_count) ?? null,
+        sample: stringValue(observation?.sample) ?? null,
+        error: stringValue(observation?.error) ?? null
+      };
+    });
+    const failed = results.filter((result) => !result.matched).length;
+    return {
+      type: check.type,
+      label: checkLabel(check),
+      status: failed ? "failed" : "passed",
+      evidence: {
+        selector: check.selector || null,
+        text: check.text || null,
+        pattern: check.pattern || null,
+        timeout_ms: timeoutMs,
+        viewports: results.map((result) => toJsonValue(result))
+      },
+      message: failed ? `Observation did not match within ${timeoutMs}ms in ${failed} viewport(s).` : void 0
+    };
+  }
   if (check.type === "frame_text_visible") {
     const key = selectorKey(check);
     const results = viewports.map((viewport) => {
@@ -4469,6 +4514,36 @@ function assessProfile(profile, evidence) {
       });
       continue;
     }
+    if (check.type === "observe_within") {
+      const key = observeWithinKey(check);
+      const timeoutMs = observeWithinTimeoutMs(check);
+      const results = checkViewports.map((viewport) => {
+        const observation = viewport.observations && viewport.observations[key] && typeof viewport.observations[key] === "object"
+          ? viewport.observations[key]
+          : {};
+        return {
+          viewport: viewport.name,
+          matched: observation.matched === true,
+          elapsed_ms: typeof observation.elapsed_ms === "number" && Number.isFinite(observation.elapsed_ms) ? observation.elapsed_ms : null,
+          timeout_ms: typeof observation.timeout_ms === "number" && Number.isFinite(observation.timeout_ms) ? observation.timeout_ms : timeoutMs,
+          attempts: typeof observation.attempts === "number" && Number.isFinite(observation.attempts) ? observation.attempts : null,
+          selector_count: typeof observation.selector_count === "number" && Number.isFinite(observation.selector_count) ? observation.selector_count : null,
+          visible_count: typeof observation.visible_count === "number" && Number.isFinite(observation.visible_count) ? observation.visible_count : null,
+          matched_count: typeof observation.matched_count === "number" && Number.isFinite(observation.matched_count) ? observation.matched_count : null,
+          sample: typeof observation.sample === "string" && observation.sample.trim() ? observation.sample.trim() : null,
+          error: typeof observation.error === "string" && observation.error.trim() ? observation.error.trim() : null,
+        };
+      });
+      const failed = results.filter((result) => !result.matched).length;
+      checks.push({
+        type: check.type,
+        label: check.label || check.type,
+        status: failed ? "failed" : "passed",
+        evidence: { selector: check.selector || null, text: check.text || null, pattern: check.pattern || null, timeout_ms: timeoutMs, viewports: results },
+        message: failed ? "Observation did not match within " + timeoutMs + "ms in " + failed + " viewport(s)." : undefined,
+      });
+      continue;
+    }
     if (check.type === "frame_text_visible") {
       const selector = check.selector || "";
       const results = checkViewports.map((viewport) => {
@@ -4901,6 +4976,19 @@ function ensureDialogHandler() {
 function textKey(check) {
   return check.pattern ? "pattern:" + check.pattern + "/" + (check.flags || "") : "text:" + (check.text || "");
 }
+function observeWithinTimeoutMs(check) {
+  const raw = Number(check && check.timeout_ms);
+  return Number.isFinite(raw) && raw > 0 ? Math.min(Math.round(raw), 60000) : 2000;
+}
+function observeWithinKey(check) {
+  const target = check && check.selector ? "selector:" + check.selector : "page";
+  const expectation = check && check.pattern
+    ? "pattern:" + check.pattern + "/" + (check.flags || "")
+    : check && check.text
+      ? "text:" + check.text
+      : "visible";
+  return target + "|" + expectation + "|within:" + observeWithinTimeoutMs(check);
+}
 function textMatches(sample, check) {
   if (check.pattern) {
     try { return new RegExp(check.pattern, check.flags || "").test(sample || ""); } catch { return false; }
@@ -6216,6 +6304,104 @@ async function selectorTextSequence(selector) {
     };
   }).catch((error) => ({ count: 0, visible_count: 0, texts: [], visible_texts: [], match_texts: [], visible_match_texts: [], error: String(error && error.message ? error.message : error).slice(0, 500) }));
 }
+async function observeWithinSnapshot(check) {
+  const payload = {
+    selector: check.selector || "",
+    text: check.text || "",
+    pattern: check.pattern || "",
+    flags: check.flags || "",
+    wants_text: Boolean(check.text || check.pattern),
+  };
+  if (payload.selector) {
+    return page.locator(payload.selector).evaluateAll((elements, input) => {
+      const compact = (value) => String(value || "").replace(/\s+/g, " ").trim();
+      const matchText = (value) => {
+        const source = compact(value);
+        if (input.pattern) {
+          try { return new RegExp(input.pattern, input.flags || "").test(source); } catch { return false; }
+        }
+        return source.includes(input.text || "");
+      };
+      const isVisible = (element) => {
+        const style = window.getComputedStyle(element);
+        const rect = element.getBoundingClientRect();
+        return style && style.visibility !== "hidden" && style.display !== "none" && rect.width > 0 && rect.height > 0;
+      };
+      const rows = elements.map((element, index) => {
+        const text = compact(element.innerText || element.textContent || "");
+        const visible = isVisible(element);
+        return { index, text, visible, matched: input.wants_text ? matchText(text) : visible };
+      });
+      const visibleRows = rows.filter((row) => row.visible);
+      const matches = input.wants_text ? visibleRows.filter((row) => row.matched) : visibleRows;
+      const sampleRow = matches[0] || visibleRows[0] || rows[0] || null;
+      return {
+        selector: input.selector,
+        text: input.text || null,
+        pattern: input.pattern || null,
+        selector_count: rows.length,
+        visible_count: visibleRows.length,
+        matched_count: matches.length,
+        matched: matches.length > 0,
+        sample: sampleRow && sampleRow.text ? sampleRow.text.slice(0, 240) : null,
+      };
+    }, payload).catch((error) => ({
+      selector: payload.selector,
+      text: payload.text || null,
+      pattern: payload.pattern || null,
+      selector_count: 0,
+      visible_count: 0,
+      matched_count: 0,
+      matched: false,
+      sample: null,
+      error: String(error && error.message ? error.message : error).slice(0, 500),
+    }));
+  }
+  return page.evaluate((input) => {
+    const compact = (value) => String(value || "").replace(/\s+/g, " ").trim();
+    const sample = compact(document.body ? document.body.innerText || document.body.textContent || "" : "");
+    let matched = false;
+    if (input.pattern) {
+      try { matched = new RegExp(input.pattern, input.flags || "").test(sample); } catch { matched = false; }
+    } else {
+      matched = sample.includes(input.text || "");
+    }
+    return {
+      selector: null,
+      text: input.text || null,
+      pattern: input.pattern || null,
+      matched,
+      matched_count: matched ? 1 : 0,
+      sample: sample.slice(0, 240),
+    };
+  }, payload).catch((error) => ({
+    selector: null,
+    text: payload.text || null,
+    pattern: payload.pattern || null,
+    matched: false,
+    matched_count: 0,
+    sample: null,
+    error: String(error && error.message ? error.message : error).slice(0, 500),
+  }));
+}
+async function observeWithin(check) {
+  const timeoutMs = observeWithinTimeoutMs(check);
+  const startedAt = Date.now();
+  let attempts = 0;
+  let last = null;
+  while (true) {
+    attempts += 1;
+    last = await observeWithinSnapshot(check);
+    const elapsedMs = Date.now() - startedAt;
+    if (last && last.matched === true) {
+      return { ...last, timeout_ms: timeoutMs, elapsed_ms: elapsedMs, attempts };
+    }
+    if (elapsedMs >= timeoutMs) {
+      return { ...(last || {}), matched: false, timeout_ms: timeoutMs, elapsed_ms: elapsedMs, attempts };
+    }
+    await page.waitForTimeout(Math.min(100, Math.max(25, timeoutMs - elapsedMs)));
+  }
+}
 function linkProbeMaxLinks(check) {
   const value = Number(check.max_links || check.maxLinks || check.limit || 100);
   return Number.isInteger(value) && value > 0 ? Math.min(value, 500) : 100;
@@ -7268,6 +7454,7 @@ async function captureViewport(viewport) {
   const text_matches = {};
   const text_match_samples = {};
   const text_case_insensitive_samples = {};
+  const observations = {};
   const http_statuses = {};
   const link_statuses = {};
   for (const check of profile.checks || []) {
@@ -7288,6 +7475,10 @@ async function captureViewport(viewport) {
       selectors[check.selector] = selectors[check.selector] || await selectorStats(check.selector);
       text_sequences[check.selector] = await selectorTextSequence(check.selector);
     }
+    if (check.type === "observe_within") {
+      const key = observeWithinKey(check);
+      observations[key] = observations[key] || await observeWithin(check);
+    }
     if ((check.type === "text_visible" || check.type === "text_absent") && (check.text || check.pattern)) {
       const key = textKey(check);
       const sample = dom.body_text || dom.body_text_sample || "";
@@ -7381,6 +7572,7 @@ async function captureViewport(viewport) {
     text_matches,
     text_match_samples,
     text_case_insensitive_samples,
+    observations,
     http_statuses,
     link_statuses,
     route_inventory: routeInventory,

package/dist/profile.d.cts

@@ -4,7 +4,7 @@ declare const RIDDLE_PROOF_PROFILE_VERSION: "riddle-proof.profile.v1";
 declare const RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION: "riddle-proof.profile-evidence.v1";
 declare const RIDDLE_PROOF_PROFILE_RESULT_VERSION: "riddle-proof.profile-result.v1";
 declare const RIDDLE_PROOF_PROFILE_STATUSES: readonly ["passed", "product_regression", "proof_insufficient", "environment_blocked", "configuration_error", "needs_human_review"];
-declare const RIDDLE_PROOF_PROFILE_CHECK_TYPES: readonly ["route_loaded", "url_search_param_equals", "url_search_param_absent", "selector_visible", "selector_absent", "selector_count_at_least", "selector_count_equals", "selector_count_equal", "selector_count_eq", "dialog_count_equals", "dialog_accept_count_equals", "dialog_dismiss_count_equals", "selector_text_visible", "selector_text_absent", "selector_text_order", "frame_text_visible", "frame_url_equals", "frame_url_matches", "frame_no_horizontal_overflow", "text_visible", "text_absent", "http_status", "link_status", "artifact_link_status", "route_inventory", "no_horizontal_overflow", "no_mobile_horizontal_overflow", "no_fatal_console_errors", "no_console_warnings"];
+declare const RIDDLE_PROOF_PROFILE_CHECK_TYPES: readonly ["route_loaded", "url_search_param_equals", "url_search_param_absent", "selector_visible", "selector_absent", "selector_count_at_least", "selector_count_equals", "selector_count_equal", "selector_count_eq", "dialog_count_equals", "dialog_accept_count_equals", "dialog_dismiss_count_equals", "selector_text_visible", "selector_text_absent", "selector_text_order", "observe_within", "frame_text_visible", "frame_url_equals", "frame_url_matches", "frame_no_horizontal_overflow", "text_visible", "text_absent", "http_status", "link_status", "artifact_link_status", "route_inventory", "no_horizontal_overflow", "no_mobile_horizontal_overflow", "no_fatal_console_errors", "no_console_warnings"];
 declare const RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES: readonly ["click", "drag", "press", "fill", "set_input_value", "set_range_value", "assert_text_visible", "assert_text_absent", "assert_selector_count", "assert_window_value", "assert_window_number", "local_storage", "session_storage", "clear_storage", "clear_console", "dialog_response", "screenshot", "wait", "wait_for_selector", "wait_for_text", "window_eval", "window_call", "window_call_until"];
 type RiddleProofProfileStatus = typeof RIDDLE_PROOF_PROFILE_STATUSES[number];
 type RiddleProofProfileCheckType = typeof RIDDLE_PROOF_PROFILE_CHECK_TYPES[number];
@@ -319,6 +319,7 @@ interface RiddleProofProfileViewportEvidence {
     text_matches?: Record<string, boolean>;
     text_match_samples?: Record<string, string[]>;
     text_case_insensitive_samples?: Record<string, string[]>;
+    observations?: Record<string, Record<string, JsonValue>>;
     http_statuses?: Record<string, Record<string, JsonValue>>;
     link_statuses?: Record<string, Record<string, JsonValue>>;
     route_inventory?: Record<string, JsonValue>;

package/dist/profile.d.ts

@@ -4,7 +4,7 @@ declare const RIDDLE_PROOF_PROFILE_VERSION: "riddle-proof.profile.v1";
 declare const RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION: "riddle-proof.profile-evidence.v1";
 declare const RIDDLE_PROOF_PROFILE_RESULT_VERSION: "riddle-proof.profile-result.v1";
 declare const RIDDLE_PROOF_PROFILE_STATUSES: readonly ["passed", "product_regression", "proof_insufficient", "environment_blocked", "configuration_error", "needs_human_review"];
-declare const RIDDLE_PROOF_PROFILE_CHECK_TYPES: readonly ["route_loaded", "url_search_param_equals", "url_search_param_absent", "selector_visible", "selector_absent", "selector_count_at_least", "selector_count_equals", "selector_count_equal", "selector_count_eq", "dialog_count_equals", "dialog_accept_count_equals", "dialog_dismiss_count_equals", "selector_text_visible", "selector_text_absent", "selector_text_order", "frame_text_visible", "frame_url_equals", "frame_url_matches", "frame_no_horizontal_overflow", "text_visible", "text_absent", "http_status", "link_status", "artifact_link_status", "route_inventory", "no_horizontal_overflow", "no_mobile_horizontal_overflow", "no_fatal_console_errors", "no_console_warnings"];
+declare const RIDDLE_PROOF_PROFILE_CHECK_TYPES: readonly ["route_loaded", "url_search_param_equals", "url_search_param_absent", "selector_visible", "selector_absent", "selector_count_at_least", "selector_count_equals", "selector_count_equal", "selector_count_eq", "dialog_count_equals", "dialog_accept_count_equals", "dialog_dismiss_count_equals", "selector_text_visible", "selector_text_absent", "selector_text_order", "observe_within", "frame_text_visible", "frame_url_equals", "frame_url_matches", "frame_no_horizontal_overflow", "text_visible", "text_absent", "http_status", "link_status", "artifact_link_status", "route_inventory", "no_horizontal_overflow", "no_mobile_horizontal_overflow", "no_fatal_console_errors", "no_console_warnings"];
 declare const RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES: readonly ["click", "drag", "press", "fill", "set_input_value", "set_range_value", "assert_text_visible", "assert_text_absent", "assert_selector_count", "assert_window_value", "assert_window_number", "local_storage", "session_storage", "clear_storage", "clear_console", "dialog_response", "screenshot", "wait", "wait_for_selector", "wait_for_text", "window_eval", "window_call", "window_call_until"];
 type RiddleProofProfileStatus = typeof RIDDLE_PROOF_PROFILE_STATUSES[number];
 type RiddleProofProfileCheckType = typeof RIDDLE_PROOF_PROFILE_CHECK_TYPES[number];
@@ -319,6 +319,7 @@ interface RiddleProofProfileViewportEvidence {
     text_matches?: Record<string, boolean>;
     text_match_samples?: Record<string, string[]>;
     text_case_insensitive_samples?: Record<string, string[]>;
+    observations?: Record<string, Record<string, JsonValue>>;
     http_statuses?: Record<string, Record<string, JsonValue>>;
     link_statuses?: Record<string, Record<string, JsonValue>>;
     route_inventory?: Record<string, JsonValue>;

package/dist/profile.js

@@ -23,7 +23,7 @@ import {
   resolveRiddleProofProfileTimeoutSec,
   slugifyRiddleProofProfileName,
   summarizeRiddleProofProfileResult
-} from "./chunk-QXQCG3WB.js";
+} from "./chunk-QJJ3ISMK.js";
 export {
   RIDDLE_PROOF_PROFILE_CHECK_TYPES,
   RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof",
-  "version": "0.7.149",
+  "version": "0.7.150",
   "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
   "license": "MIT",
   "author": "RiddleDC",