@riddledc/riddle-proof 0.7.139 → 0.7.141

package/README.md

@@ -401,7 +401,7 @@ transport control, or other bounded interaction. Supported setup actions are
 `assert_text_absent`, `assert_selector_count`, `assert_window_value`,
 `assert_window_number`, `local_storage`, `session_storage`, `clear_storage`,
 `clear_console`, `screenshot`, `wait`, `wait_for_selector`, `wait_for_text`,
-`window_call`, and `window_call_until`;
+`window_eval`, `window_call`, and `window_call_until`;
 a failed setup action is recorded as a failed `setup_actions_succeeded` check so
 the profile cannot pass without reaching the intended state. Text-matched `click` actions prefer
 visible matching elements, which keeps responsive layouts from selecting hidden
@@ -447,6 +447,12 @@ errors, but keeps network mock hit evidence intact. Any setup action can include
 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.
+Use `window_eval` for async browser-side helper code that is easier to express
+as a short script body than as a preexisting `window` function. It accepts
+`script` plus optional JSON `args`, can compare `expect_return`, can store the
+JSON-safe return value with `store_return_to`, and honors `capture_return:
+false` for compact receipts. The script runs as an async function body with
+`args` available in scope, so `return { ok: true }` records a structured return.
 Use `window_call_until` when a proof helper needs to advance randomized or
 progressive state until a window-state receipt is true. It accepts `path` plus
 optional `args`, `until_path`, `until_expected_value`, `max_calls` from 1 to
@@ -486,7 +492,9 @@ Profile final viewport screenshots are full-page by default. Set
 `target.screenshot_full_page: false`, `target.screenshotFullPage: false`, or
 `target.screenshot_mode: "viewport"` when the automatic final screenshots
 should capture only the current viewport, for example when fixed or sticky
-headers make full-page captures misleading.
+headers make full-page captures misleading. Compact profile summaries include
+the final screenshot count and mode when a profile sets an explicit target
+screenshot mode.
 
 Use `allowed_console_patterns` / `allowed_console_texts` on
 `no_fatal_console_errors` when a negative-path profile intentionally triggers a

package/dist/{chunk-DB6J53V5.js → chunk-F46O7DP2.js}

@@ -61,6 +61,7 @@ var RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES = [
   "wait",
   "wait_for_selector",
   "wait_for_text",
+  "window_eval",
   "window_call",
   "window_call_until"
 ];
@@ -480,6 +481,21 @@ function profileSetupWindowCallReceipts(results) {
     return receipt;
   });
 }
+function profileSetupWindowEvalReceipts(results) {
+  return results.filter((result) => profileSetupResultAction(result) === "window_eval").map((result) => {
+    const receipt = {
+      ordinal: result.ordinal ?? null,
+      ok: result.ok !== false,
+      script_length: result.script_length ?? null,
+      return_captured: result.return_captured ?? null,
+      return_stored_to: result.return_stored_to ?? null,
+      reason: result.reason ?? result.error ?? result.store_reason ?? null
+    };
+    if (result.returned !== void 0) receipt.returned = result.returned;
+    if (result.expected_return !== void 0) receipt.expected_return = result.expected_return;
+    return receipt;
+  });
+}
 function sampleProfileSetupSummaryItems(items, limit) {
   if (items.length <= limit) return items;
   const firstCount = Math.floor(limit / 2);
@@ -494,12 +510,18 @@ function profileScreenshotLabels(viewports) {
   }
   return labels;
 }
-function profileSetupSummary(viewports, actionCount, expectedActionCountByViewport) {
+function profileSetupSummary(viewports, actionCount, expectedActionCountByViewport, finalScreenshotFullPage) {
+  const normalizedFinalScreenshotFullPage = finalScreenshotFullPage === void 0 ? void 0 : finalScreenshotFullPage !== false;
+  const finalScreenshotCount = viewports.filter((viewport) => typeof viewport.screenshot_label === "string" && viewport.screenshot_label.trim()).length;
   return toJsonValue({
     viewport_count: viewports.length,
     action_count: actionCount ?? null,
+    final_screenshot_count: finalScreenshotCount,
+    final_screenshot_full_page: normalizedFinalScreenshotFullPage ?? null,
+    final_screenshot_mode: normalizedFinalScreenshotFullPage === void 0 ? null : normalizedFinalScreenshotFullPage ? "full_page" : "viewport",
     viewports: viewports.map((viewport) => {
       const expectedActionCount = expectedActionCountByViewport?.get(viewport.name) ?? actionCount;
+      const viewportFinalScreenshotFullPage = typeof viewport.screenshot_full_page === "boolean" ? viewport.screenshot_full_page : normalizedFinalScreenshotFullPage;
       const results = viewport.setup_action_results || [];
       const failed = results.filter((result) => result.ok === false && result.optional !== true);
       const optionalFailed = results.filter((result) => result.ok === false && result.optional === true);
@@ -512,6 +534,10 @@ function profileSetupSummary(viewports, actionCount, expectedActionCountByViewpo
       const windowCallStoredTotal = windowCallReceipts.filter((result) => typeof result.return_stored_to === "string" && result.return_stored_to.trim()).length;
       const windowCallCapturedTotal = windowCallReceipts.filter((result) => result.return_captured === true).length;
       const sampledWindowCallReceipts = sampleProfileSetupSummaryItems(windowCallReceipts, 8);
+      const windowEvalReceipts = profileSetupWindowEvalReceipts(results);
+      const windowEvalStoredTotal = windowEvalReceipts.filter((result) => typeof result.return_stored_to === "string" && result.return_stored_to.trim()).length;
+      const windowEvalCapturedTotal = windowEvalReceipts.filter((result) => result.return_captured === true).length;
+      const sampledWindowEvalReceipts = sampleProfileSetupSummaryItems(windowEvalReceipts, 8);
       const clickedItems = results.filter((result) => profileSetupResultAction(result) === "click" && result.ok !== false).map((result) => {
         const clickCount = typeof result.click_count === "number" && Number.isFinite(result.click_count) && result.click_count > 1 ? result.click_count : void 0;
         return {
@@ -539,6 +565,8 @@ function profileSetupSummary(viewports, actionCount, expectedActionCountByViewpo
         action_counts: profileSetupActionCounts(results),
         frame_action_count: results.filter((result) => result.frame_selector).length,
         frame_urls: profileSetupFrameUrls(viewport),
+        final_screenshot: viewport.screenshot_label ?? null,
+        final_screenshot_full_page: viewportFinalScreenshotFullPage ?? null,
         setup_screenshots: profileSetupScreenshotLabels(results),
         clicked_total: clickedItems.length,
         clicked_truncated: clickedItems.length > clicked.length,
@@ -553,6 +581,11 @@ function profileSetupSummary(viewports, actionCount, expectedActionCountByViewpo
         window_call_captured_total: windowCallCapturedTotal,
         window_call_truncated: windowCallReceipts.length > sampledWindowCallReceipts.length,
         window_call: sampledWindowCallReceipts,
+        window_eval_total: windowEvalReceipts.length,
+        window_eval_stored_total: windowEvalStoredTotal,
+        window_eval_captured_total: windowEvalCapturedTotal,
+        window_eval_truncated: windowEvalReceipts.length > sampledWindowEvalReceipts.length,
+        window_eval: sampledWindowEvalReceipts,
         clicked,
         text_samples,
         failed: failed.map((result) => ({
@@ -605,7 +638,7 @@ function isSupportedCheckType(value) {
 }
 function normalizeSetupActionType(value, index) {
   const normalizedInput = String(value || "").trim().replace(/-/g, "_");
-  const normalized = normalizedInput === "clear_browser_storage" ? "clear_storage" : normalizedInput === "reset_console" || normalizedInput === "clear_browser_console" || normalizedInput === "reset_browser_console" ? "clear_console" : normalizedInput === "pointer_drag" || normalizedInput === "mouse_drag" || normalizedInput === "drag_to" ? "drag" : normalizedInput === "keyboard_press" || normalizedInput === "key_press" ? "press" : normalizedInput === "capture_screenshot" || normalizedInput === "save_screenshot" || normalizedInput === "setup_screenshot" ? "screenshot" : normalizedInput === "accept_dialog" || normalizedInput === "accept_dialogs" || normalizedInput === "confirm_dialog" || normalizedInput === "set_dialog_response" ? "dialog_response" : normalizedInput === "dismiss_dialog" || normalizedInput === "dismiss_dialogs" || normalizedInput === "cancel_dialog" ? "dialog_response" : normalizedInput === "window_call_until" || normalizedInput === "call_until" || normalizedInput === "window_call_repeat_until" || normalizedInput === "repeat_window_call_until" ? "window_call_until" : normalizedInput;
+  const normalized = normalizedInput === "clear_browser_storage" ? "clear_storage" : normalizedInput === "reset_console" || normalizedInput === "clear_browser_console" || normalizedInput === "reset_browser_console" ? "clear_console" : normalizedInput === "pointer_drag" || normalizedInput === "mouse_drag" || normalizedInput === "drag_to" ? "drag" : normalizedInput === "keyboard_press" || normalizedInput === "key_press" ? "press" : normalizedInput === "capture_screenshot" || normalizedInput === "save_screenshot" || normalizedInput === "setup_screenshot" ? "screenshot" : normalizedInput === "accept_dialog" || normalizedInput === "accept_dialogs" || normalizedInput === "confirm_dialog" || normalizedInput === "set_dialog_response" ? "dialog_response" : normalizedInput === "dismiss_dialog" || normalizedInput === "dismiss_dialogs" || normalizedInput === "cancel_dialog" ? "dialog_response" : normalizedInput === "window_call_until" || normalizedInput === "call_until" || normalizedInput === "window_call_repeat_until" || normalizedInput === "repeat_window_call_until" ? "window_call_until" : normalizedInput === "window_evaluate" || normalizedInput === "browser_eval" || normalizedInput === "browser_evaluate" || normalizedInput === "evaluate_script" || normalizedInput === "profile_script" ? "window_eval" : normalizedInput;
   if (RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES.includes(normalized)) {
     return normalized;
   }
@@ -623,7 +656,7 @@ function normalizeSetupActionArgs(input, index) {
   const argsInput = valueFromOwn(input, "args", "arguments", "args_json", "argsJson");
   if (argsInput === void 0) return void 0;
   if (!Array.isArray(argsInput)) {
-    throw new Error(`target.setup_actions[${index}] window_call args must be an array.`);
+    throw new Error(`target.setup_actions[${index}] window_call/window_eval args must be an array.`);
   }
   return argsInput.map(toJsonValue);
 }
@@ -767,7 +800,11 @@ function normalizeSetupAction(input, index) {
   if ((type === "window_call" || type === "window_call_until" || type === "assert_window_value" || type === "assert_window_number") && !path) {
     throw new Error(`target.setup_actions[${index}] ${type} requires path.`);
   }
-  const args = type === "window_call" || type === "window_call_until" ? normalizeSetupActionArgs(input, index) : void 0;
+  const script = stringFromOwn(input, "script", "code", "source", "body");
+  if (type === "window_eval" && !script) {
+    throw new Error(`target.setup_actions[${index}] window_eval requires script.`);
+  }
+  const args = type === "window_call" || type === "window_call_until" || type === "window_eval" ? normalizeSetupActionArgs(input, index) : void 0;
   const hasExpectedValue = hasOwn(input, "expected_value") || hasOwn(input, "expectedValue") || hasOwn(input, "expected") || hasOwn(input, "expect_value") || hasOwn(input, "expectValue") || hasOwn(input, "expect");
   if (type === "assert_window_value" && !hasExpectedValue) {
     throw new Error(`target.setup_actions[${index}] ${type} requires expected_value.`);
@@ -838,6 +875,7 @@ function normalizeSetupAction(input, index) {
     value,
     value_json: hasJsonValue ? toJsonValue(input.value_json ?? input.valueJson ?? input.json) : void 0,
     label: stringFromOwn(input, "label", "name", "screenshot_label", "screenshotLabel"),
+    script,
     path,
     args,
     expect_return: hasExpectedReturn ? toJsonValue(valueFromOwn(input, "expect_return", "expectReturn", "expected_return", "expectedReturn")) : void 0,
@@ -2783,7 +2821,7 @@ function assessSetupActionsFromEvidence(profile, evidence) {
         ok: (viewport.setup_action_results || []).length >= (expectedActionCountByViewport.get(viewport.name) ?? actionCount) && (viewport.setup_action_results || []).every((result) => result.ok !== false || result.optional === true),
         result_count: (viewport.setup_action_results || []).length
       })),
-      setup_summary: profileSetupSummary(viewports, actionCount, expectedActionCountByViewport),
+      setup_summary: profileSetupSummary(viewports, actionCount, expectedActionCountByViewport, profile.target.screenshot_full_page),
       failed
     },
     message: failed.length ? `Setup actions failed in ${failed.length} viewport action(s).` : void 0
@@ -3789,6 +3827,23 @@ function profileSetupWindowCallReceipts(results) {
       return receipt;
     });
 }
+function profileSetupWindowEvalReceipts(results) {
+  return (results || [])
+    .filter((result) => result && profileSetupResultAction(result) === "window_eval")
+    .map((result) => {
+      const receipt = {
+        ordinal: result.ordinal ?? null,
+        ok: result.ok !== false,
+        script_length: result.script_length ?? null,
+        return_captured: result.return_captured ?? null,
+        return_stored_to: result.return_stored_to ?? null,
+        reason: result.reason || result.error || result.store_reason || null,
+      };
+      if (result.returned !== undefined) receipt.returned = result.returned;
+      if (result.expected_return !== undefined) receipt.expected_return = result.expected_return;
+      return receipt;
+    });
+}
 function sampleProfileSetupSummaryItems(items, limit) {
   if ((items || []).length <= limit) return items || [];
   const firstCount = Math.floor(limit / 2);
@@ -3803,14 +3858,28 @@ function profileScreenshotLabels(viewports) {
   }
   return labels;
 }
-function profileSetupSummary(viewports, actionCount, expectedActionCountsByViewport) {
+function profileSetupSummary(viewports, actionCount, expectedActionCountsByViewport, finalScreenshotFullPage) {
+  const normalizedFinalScreenshotFullPage = finalScreenshotFullPage === undefined
+    ? undefined
+    : finalScreenshotFullPage !== false;
+  const finalScreenshotCount = (viewports || []).filter((viewport) => viewport && typeof viewport.screenshot_label === "string" && viewport.screenshot_label.trim()).length;
   return {
     viewport_count: (viewports || []).length,
     action_count: actionCount ?? null,
+    final_screenshot_count: finalScreenshotCount,
+    final_screenshot_full_page: normalizedFinalScreenshotFullPage ?? null,
+    final_screenshot_mode: normalizedFinalScreenshotFullPage === undefined
+      ? null
+      : normalizedFinalScreenshotFullPage
+        ? "full_page"
+        : "viewport",
     viewports: (viewports || []).map((viewport) => {
       const expectedActionCount = expectedActionCountsByViewport && expectedActionCountsByViewport[viewport.name] !== undefined
         ? expectedActionCountsByViewport[viewport.name]
         : actionCount;
+      const viewportFinalScreenshotFullPage = typeof viewport.screenshot_full_page === "boolean"
+        ? viewport.screenshot_full_page
+        : normalizedFinalScreenshotFullPage;
       const results = viewport.setup_action_results || [];
       const failed = results.filter((result) => result && result.ok === false && result.optional !== true);
       const optionalFailed = results.filter((result) => result && result.ok === false && result.optional === true);
@@ -3827,6 +3896,10 @@ function profileSetupSummary(viewports, actionCount, expectedActionCountsByViewp
       const windowCallStoredTotal = windowCallReceipts.filter((result) => typeof result.return_stored_to === "string" && result.return_stored_to.trim()).length;
       const windowCallCapturedTotal = windowCallReceipts.filter((result) => result.return_captured === true).length;
       const sampledWindowCallReceipts = sampleProfileSetupSummaryItems(windowCallReceipts, 8);
+      const windowEvalReceipts = profileSetupWindowEvalReceipts(results);
+      const windowEvalStoredTotal = windowEvalReceipts.filter((result) => typeof result.return_stored_to === "string" && result.return_stored_to.trim()).length;
+      const windowEvalCapturedTotal = windowEvalReceipts.filter((result) => result.return_captured === true).length;
+      const sampledWindowEvalReceipts = sampleProfileSetupSummaryItems(windowEvalReceipts, 8);
       const clickedItems = results
         .filter((result) => result && profileSetupResultAction(result) === "click" && result.ok !== false)
         .map((result) => {
@@ -3864,6 +3937,8 @@ function profileSetupSummary(viewports, actionCount, expectedActionCountsByViewp
         action_counts: profileSetupActionCounts(results),
         frame_action_count: results.filter((result) => result && result.frame_selector).length,
         frame_urls: profileSetupFrameUrls(viewport),
+        final_screenshot: viewport.screenshot_label || null,
+        final_screenshot_full_page: viewportFinalScreenshotFullPage ?? null,
         setup_screenshots: profileSetupScreenshotLabels(results),
         clicked_total: clickedItems.length,
         clicked_truncated: clickedItems.length > clicked.length,
@@ -3878,6 +3953,11 @@ function profileSetupSummary(viewports, actionCount, expectedActionCountsByViewp
         window_call_captured_total: windowCallCapturedTotal,
         window_call_truncated: windowCallReceipts.length > sampledWindowCallReceipts.length,
         window_call: sampledWindowCallReceipts,
+        window_eval_total: windowEvalReceipts.length,
+        window_eval_stored_total: windowEvalStoredTotal,
+        window_eval_captured_total: windowEvalCapturedTotal,
+        window_eval_truncated: windowEvalReceipts.length > sampledWindowEvalReceipts.length,
+        window_eval: sampledWindowEvalReceipts,
         clicked,
         text_samples: textSamples,
         failed: failed.map((result) => ({
@@ -4048,7 +4128,7 @@ function assessProfile(profile, evidence) {
             && (viewport.setup_action_results || []).every((result) => !result || result.ok !== false || result.optional === true),
           result_count: (viewport.setup_action_results || []).length,
         })),
-        setup_summary: profileSetupSummary(viewports, actionCount, expectedActionCountsByViewport),
+        setup_summary: profileSetupSummary(viewports, actionCount, expectedActionCountsByViewport, profile.target && profile.target.screenshot_full_page),
         failed,
       },
       message: failed.length ? "Setup actions failed in " + failed.length + " viewport action(s)." : undefined,
@@ -4858,6 +4938,49 @@ async function setupCallWindowFunction(context, path, args, storeReturnTo, captu
     }
   }, { path, args, storeReturnTo, captureReturn });
 }
+async function setupEvaluateWindowScript(context, script, args, storeReturnTo, captureReturn) {
+  return await context.evaluate(async ({ script, args, storeReturnTo, captureReturn }) => {
+    const toJsonValue = (value) => {
+      if (value === null || value === undefined) return null;
+      if (typeof value === "string" || typeof value === "boolean") return value;
+      if (typeof value === "number") return Number.isFinite(value) ? value : null;
+      if (Array.isArray(value)) return value.map(toJsonValue);
+      if (typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, toJsonValue(child)]));
+      }
+      return String(value);
+    };
+    const storeWindowReturn = (storePath, value) => {
+      const pathParts = String(storePath || "").split(".").map((part) => part.trim()).filter(Boolean);
+      if (pathParts[0] === "window") pathParts.shift();
+      if (!pathParts.length) return { ok: false, reason: "missing_store_path" };
+      let target = window;
+      for (let index = 0; index < pathParts.length - 1; index += 1) {
+        const part = pathParts[index];
+        if (target[part] === null || typeof target[part] !== "object") target[part] = {};
+        target = target[part];
+      }
+      target[pathParts[pathParts.length - 1]] = value;
+      return { ok: true, path: pathParts.join(".") };
+    };
+    const body = String(script || "");
+    if (!body.trim()) return { ok: false, reason: "missing_script" };
+    try {
+      const run = new Function("args", "\"use strict\"; return (async () => {\\n" + body + "\\n})();");
+      const returned = await run(Array.isArray(args) ? args : []);
+      const jsonReturned = toJsonValue(returned);
+      const returnedForResult = captureReturn === false ? undefined : jsonReturned;
+      if (storeReturnTo) {
+        const stored = storeWindowReturn(storeReturnTo, jsonReturned);
+        if (!stored.ok) return { ok: false, reason: "return_store_failed", store_reason: stored.reason, returned: returnedForResult };
+        return { ok: true, returned: returnedForResult, return_stored_to: stored.path };
+      }
+      return { ok: true, returned: returnedForResult };
+    } catch (error) {
+      return { ok: false, reason: "script_threw", error: String(error && error.message ? error.message : error).slice(0, 1000) };
+    }
+  }, { script, args, storeReturnTo, captureReturn });
+}
 function setupFrameSelector(action) {
   return String(action?.frame_selector || action?.frameSelector || action?.iframe_selector || action?.iframeSelector || "").trim();
 }
@@ -5371,6 +5494,44 @@ async function executeSetupAction(action, ordinal, viewport) {
       }
       return { ...base, ...setupScopeEvidence(scope), ok: true, storage, reload: action.reload === true };
     }
+    if (type === "window_eval") {
+      const script = String(action.script || action.code || action.source || action.body || "");
+      const args = Array.isArray(action.args) ? action.args : [];
+      const storeReturnTo = String(action.store_return_to || action.storeReturnTo || action.save_return_to || action.saveReturnTo || action.assign_return_to || action.assignReturnTo || action.return_state_path || action.returnStatePath || "").trim();
+      if (!script.trim()) return { ...base, reason: "missing_script" };
+      const scope = await setupActionScope(action, timeout);
+      if (!scope.ok) return setupScopeFailure(base, scope);
+      const hasExpectation = setupHasOwn(action, "expect_return")
+        || setupHasOwn(action, "expectReturn")
+        || setupHasOwn(action, "expected_return")
+        || setupHasOwn(action, "expectedReturn");
+      const expected = setupHasOwn(action, "expect_return")
+        ? action.expect_return
+        : setupHasOwn(action, "expectReturn")
+          ? action.expectReturn
+        : setupHasOwn(action, "expected_return")
+          ? action.expected_return
+          : action.expectedReturn;
+      const captureReturn = action.capture_return === false || action.captureReturn === false || action.include_return === false || action.includeReturn === false || action.omit_return === true || action.omitReturn === true
+        ? hasExpectation
+        : true;
+      const result = await setupEvaluateWindowScript(scope.context, script, args, storeReturnTo, captureReturn);
+      const expectationMet = !hasExpectation || setupValuesEqual(result.returned, expected);
+      return {
+        ...base,
+        ...setupScopeEvidence(scope),
+        ok: Boolean(result.ok && expectationMet),
+        script_length: script.length,
+        arg_count: args.length,
+        returned: captureReturn ? setupJsonValue(result.returned) : undefined,
+        return_captured: captureReturn,
+        expected_return: hasExpectation ? setupJsonValue(expected) : undefined,
+        return_stored_to: result.return_stored_to || storeReturnTo || undefined,
+        reason: result.ok ? (expectationMet ? undefined : "unexpected_return_value") : result.reason,
+        store_reason: result.store_reason || undefined,
+        error: result.error || undefined,
+      };
+    }
     if (type === "window_call") {
       const path = String(action.path || action.function_path || action.functionPath || "");
       const args = Array.isArray(action.args) ? action.args : [];
@@ -6926,9 +7087,13 @@ async function captureViewport(viewport) {
     }
   }
   const screenshotLabel = profileSlug + "-" + viewport.name;
+  let screenshotFullPage = null;
   try {
     const screenshotOptions = {};
-    if (profile.target && profile.target.screenshot_full_page !== undefined) screenshotOptions.fullPage = profile.target.screenshot_full_page !== false;
+    if (profile.target && profile.target.screenshot_full_page !== undefined) {
+      screenshotFullPage = profile.target.screenshot_full_page !== false;
+      screenshotOptions.fullPage = screenshotFullPage;
+    }
     if (typeof saveScreenshot === "function") await saveScreenshot(screenshotLabel, screenshotOptions);
   } catch (error) {
     pageErrors.push({ message: "saveScreenshot failed: " + String(error && error.message ? error.message : error).slice(0, 500) });
@@ -6996,6 +7161,7 @@ async function captureViewport(viewport) {
     route_inventory: routeInventory,
     setup_action_results: setupActionResults,
     screenshot_label: screenshotLabel,
+    screenshot_full_page: screenshotFullPage,
     navigation_error: navigationError,
     wait_error: waitError,
   };