@riddledc/riddle-proof 0.7.7 → 0.7.9

package/README.md

@@ -108,7 +108,11 @@ or as a stronger proof base before a change loop.
       { "name": "mobile", "width": 390, "height": 844 },
       { "name": "desktop", "width": 1440, "height": 1000 }
     ],
-    "auth": "none"
+    "auth": "none",
+    "setup_actions": [
+      { "type": "click", "selector": "[data-testid='show-plans']" },
+      { "type": "wait_for_text", "selector": "body", "text": "Start building" }
+    ]
   },
   "checks": [
     { "type": "route_loaded", "expected_path": "/pricing" },
@@ -141,6 +145,13 @@ The package includes a generic starter profile at
 profile directory and replace the selector/text checks with app-specific
 invariants.
 
+`target.setup_actions` is optional. Use it when the meaningful proof surface
+appears only after a picker, tab, login stub, transport control, or other
+bounded interaction. Supported setup actions are `click`, `wait`,
+`wait_for_selector`, and `wait_for_text`; a failed setup action is recorded as
+a failed `setup_actions_succeeded` check so the profile cannot pass without
+reaching the intended state.
+
 The result uses `riddle-proof.profile-result.v1` and separates product failures
 from weak proof and environment blockers:
 
@@ -301,9 +312,10 @@ const catches = createBasicGameplayCatchRecords(assessment, evidence);
 ```
 
 The package owns generic contracts such as `state_path`, `state_call`,
-`property_path`, `number_unchanged`, held-key/window-call/evaluate action type
-constants, and JSON-safe text compaction. Site-specific manifests, selectors,
-and deterministic game scripts should stay in the caller.
+`property_path`, `number_unchanged`, held-key, canvas-click,
+canvas-pointer-down/move/up, window-call/evaluate action type constants, and
+JSON-safe text compaction. Site-specific manifests, selectors, and
+deterministic game scripts should stay in the caller.
 
 ### Server Preview Usage
 

package/dist/basic-gameplay.cjs

@@ -51,6 +51,10 @@ var BASIC_GAMEPLAY_ACTION_TYPES = [
   "repeat",
   "click",
   "click-by-text",
+  "canvas-click",
+  "canvas-pointer-down",
+  "canvas-pointer-move",
+  "canvas-pointer-up",
   "wait-for-text",
   "window-call",
   "evaluate"

package/dist/basic-gameplay.d.cts

@@ -36,7 +36,7 @@ interface BasicGameplayActionResult {
     action?: string;
     [key: string]: unknown;
 }
-declare const BASIC_GAMEPLAY_ACTION_TYPES: readonly ["wait", "key", "key-down", "key-up", "hold-key", "repeat", "click", "click-by-text", "wait-for-text", "window-call", "evaluate"];
+declare const BASIC_GAMEPLAY_ACTION_TYPES: readonly ["wait", "key", "key-down", "key-up", "hold-key", "repeat", "click", "click-by-text", "canvas-click", "canvas-pointer-down", "canvas-pointer-move", "canvas-pointer-up", "wait-for-text", "window-call", "evaluate"];
 declare const BASIC_GAMEPLAY_PROGRESS_CHECK_TYPES: readonly ["selector_count_increases", "selector_count_at_least", "selector_absent", "selector_text_matches", "number_increases", "number_decreases", "number_at_least", "number_gte", "number_unchanged", "number_stays_equal", "number_equals", "canvas_hash_changes", "screenshot_hash_changes", "visual_hash_changes", "state_changes"];
 type BasicGameplayActionType = typeof BASIC_GAMEPLAY_ACTION_TYPES[number] | (string & {});
 type BasicGameplayProgressCheckType = typeof BASIC_GAMEPLAY_PROGRESS_CHECK_TYPES[number] | (string & {});

package/dist/basic-gameplay.d.ts

@@ -36,7 +36,7 @@ interface BasicGameplayActionResult {
     action?: string;
     [key: string]: unknown;
 }
-declare const BASIC_GAMEPLAY_ACTION_TYPES: readonly ["wait", "key", "key-down", "key-up", "hold-key", "repeat", "click", "click-by-text", "wait-for-text", "window-call", "evaluate"];
+declare const BASIC_GAMEPLAY_ACTION_TYPES: readonly ["wait", "key", "key-down", "key-up", "hold-key", "repeat", "click", "click-by-text", "canvas-click", "canvas-pointer-down", "canvas-pointer-move", "canvas-pointer-up", "wait-for-text", "window-call", "evaluate"];
 declare const BASIC_GAMEPLAY_PROGRESS_CHECK_TYPES: readonly ["selector_count_increases", "selector_count_at_least", "selector_absent", "selector_text_matches", "number_increases", "number_decreases", "number_at_least", "number_gte", "number_unchanged", "number_stays_equal", "number_equals", "canvas_hash_changes", "screenshot_hash_changes", "visual_hash_changes", "state_changes"];
 type BasicGameplayActionType = typeof BASIC_GAMEPLAY_ACTION_TYPES[number] | (string & {});
 type BasicGameplayProgressCheckType = typeof BASIC_GAMEPLAY_PROGRESS_CHECK_TYPES[number] | (string & {});

package/dist/basic-gameplay.js

@@ -16,7 +16,7 @@ import {
   extractBasicGameplayEvidence,
   resolveBasicGameplayProgressionCheckWithArtifactScreenshots,
   sanitizeBasicGameplayJsonString
-} from "./chunk-AHW7SL3W.js";
+} from "./chunk-5A4SL6CX.js";
 export {
   BASIC_GAMEPLAY_ACTION_TYPES,
   BASIC_GAMEPLAY_PROGRESS_CHECK_TYPES,

package/dist/{chunk-AHW7SL3W.js → chunk-5A4SL6CX.js}

@@ -11,6 +11,10 @@ var BASIC_GAMEPLAY_ACTION_TYPES = [
   "repeat",
   "click",
   "click-by-text",
+  "canvas-click",
+  "canvas-pointer-down",
+  "canvas-pointer-move",
+  "canvas-pointer-up",
   "wait-for-text",
   "window-call",
   "evaluate"

package/dist/{chunk-7NMAU4DP.js → chunk-NUSUGO2P.js}

@@ -20,6 +20,12 @@ var RIDDLE_PROOF_PROFILE_CHECK_TYPES = [
   "no_mobile_horizontal_overflow",
   "no_fatal_console_errors"
 ];
+var RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES = [
+  "click",
+  "wait",
+  "wait_for_selector",
+  "wait_for_text"
+];
 var DEFAULT_VIEWPORTS = [
   { name: "desktop", width: 1280, height: 800 }
 ];
@@ -72,6 +78,41 @@ function normalizeViewports(value) {
 function isSupportedCheckType(value) {
   return RIDDLE_PROOF_PROFILE_CHECK_TYPES.includes(value);
 }
+function normalizeSetupActionType(value, index) {
+  const normalized = String(value || "").trim().replace(/-/g, "_");
+  if (RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES.includes(normalized)) {
+    return normalized;
+  }
+  throw new Error(`target.setup_actions[${index}].type ${value || "(missing)"} is not supported. Supported actions: ${RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES.join(", ")}`);
+}
+function normalizeSetupAction(input, index) {
+  if (!isRecord(input)) throw new Error(`target.setup_actions[${index}] must be an object.`);
+  const type = normalizeSetupActionType(stringValue(input.type), index);
+  const selector = stringValue(input.selector);
+  if ((type === "click" || type === "wait_for_selector" || type === "wait_for_text") && !selector) {
+    throw new Error(`target.setup_actions[${index}] ${type} requires selector.`);
+  }
+  if (type === "wait_for_text" && !stringValue(input.text) && !stringValue(input.pattern)) {
+    throw new Error(`target.setup_actions[${index}] wait_for_text requires text or pattern.`);
+  }
+  return {
+    type,
+    selector,
+    text: stringValue(input.text),
+    pattern: stringValue(input.pattern),
+    flags: stringValue(input.flags),
+    index: numberValue(input.index),
+    ms: numberValue(input.ms) ?? numberValue(input.wait_ms) ?? numberValue(input.waitMs),
+    timeout_ms: numberValue(input.timeout_ms) ?? numberValue(input.timeoutMs),
+    after_ms: numberValue(input.after_ms) ?? numberValue(input.afterMs),
+    continue_on_failure: input.continue_on_failure === true || input.continueOnFailure === true
+  };
+}
+function normalizeSetupActions(value) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value)) throw new Error("target.setup_actions must be an array.");
+  return value.map(normalizeSetupAction);
+}
 function normalizeCheck(input, index) {
   if (!isRecord(input)) throw new Error(`checks[${index}] must be an object.`);
   const type = stringValue(input.type);
@@ -139,7 +180,8 @@ function normalizeRiddleProofProfile(input, options = {}) {
       viewports: options.viewports?.length ? options.viewports : normalizeViewports(targetInput.viewports),
       auth: stringValue(targetInput.auth) || "none",
       wait_for_selector: stringValue(targetInput.wait_for_selector) || stringValue(targetInput.waitForSelector),
-      wait_ms: numberValue(targetInput.wait_ms) ?? numberValue(targetInput.waitMs)
+      wait_ms: numberValue(targetInput.wait_ms) ?? numberValue(targetInput.waitMs),
+      setup_actions: normalizeSetupActions(targetInput.setup_actions ?? targetInput.setupActions)
     },
     checks,
     artifacts: Array.isArray(input.artifacts) ? input.artifacts.map((item) => String(item)).filter(Boolean) : ["screenshot", "console", "dom_summary", "proof_json"],
@@ -312,6 +354,48 @@ function assessCheckFromEvidence(check, evidence) {
     message: "Unsupported check type."
   };
 }
+function assessSetupActionsFromEvidence(profile, evidence) {
+  if (!profile.target.setup_actions?.length) return void 0;
+  const actionCount = profile.target.setup_actions.length;
+  const failed = [];
+  const viewports = evidence.viewports || [];
+  for (const viewport of viewports) {
+    const results = viewport.setup_action_results || [];
+    for (const result of results) {
+      if (result.ok === false) {
+        failed.push({
+          viewport: viewport.name,
+          action: result.action ?? result.type ?? null,
+          selector: result.selector ?? null,
+          reason: result.reason ?? result.error ?? null
+        });
+      }
+    }
+    if (results.length < actionCount && results.every((result) => result.ok !== false)) {
+      failed.push({
+        viewport: viewport.name,
+        action: "setup_actions",
+        selector: null,
+        reason: `missing setup action results: ${results.length}/${actionCount}`
+      });
+    }
+  }
+  return {
+    type: "setup_actions_succeeded",
+    label: "setup actions succeeded",
+    status: failed.length ? "failed" : "passed",
+    evidence: {
+      action_count: actionCount,
+      viewports: viewports.map((viewport) => ({
+        name: viewport.name,
+        ok: (viewport.setup_action_results || []).length >= actionCount && (viewport.setup_action_results || []).every((result) => result.ok !== false),
+        result_count: (viewport.setup_action_results || []).length
+      })),
+      failed
+    },
+    message: failed.length ? `Setup actions failed in ${failed.length} viewport action(s).` : void 0
+  };
+}
 function profileStatusFromEvidence(evidence, checks) {
   if (!evidence) return "proof_insufficient";
   const viewports = evidence.viewports || [];
@@ -323,7 +407,10 @@ function profileStatusFromEvidence(evidence, checks) {
 }
 function assessRiddleProofProfileEvidence(profile, evidence, options = {}) {
   const capturedAt = evidence?.captured_at || (/* @__PURE__ */ new Date()).toISOString();
-  const checks = evidence ? profile.checks.map((check) => assessCheckFromEvidence(check, evidence)) : [];
+  const checks = evidence ? [
+    assessSetupActionsFromEvidence(profile, evidence),
+    ...profile.checks.map((check) => assessCheckFromEvidence(check, evidence))
+  ].filter((check) => Boolean(check)) : [];
   const status = profileStatusFromEvidence(evidence, checks);
   const firstViewport = evidence?.viewports?.[0];
   const screenshots = (evidence?.viewports || []).map((viewport) => viewport.screenshot_label).filter((label) => Boolean(label));
@@ -437,6 +524,47 @@ function textMatches(sample, check) {
 function assessProfile(profile, evidence) {
   const checks = [];
   const viewports = evidence.viewports || [];
+  if (profile.target && Array.isArray(profile.target.setup_actions) && profile.target.setup_actions.length) {
+    const actionCount = profile.target.setup_actions.length;
+    const failed = [];
+    for (const viewport of viewports) {
+      const results = viewport.setup_action_results || [];
+      for (const result of results) {
+        if (result && result.ok === false) {
+          failed.push({
+            viewport: viewport.name,
+            action: result.action || result.type || null,
+            selector: result.selector || null,
+            reason: result.reason || result.error || null,
+          });
+        }
+      }
+      if (results.length < actionCount && results.every((result) => !result || result.ok !== false)) {
+        failed.push({
+          viewport: viewport.name,
+          action: "setup_actions",
+          selector: null,
+          reason: "missing setup action results: " + results.length + "/" + actionCount,
+        });
+      }
+    }
+    checks.push({
+      type: "setup_actions_succeeded",
+      label: "setup actions succeeded",
+      status: failed.length ? "failed" : "passed",
+      evidence: {
+        action_count: actionCount,
+        viewports: viewports.map((viewport) => ({
+          name: viewport.name,
+          ok: (viewport.setup_action_results || []).length >= actionCount
+            && (viewport.setup_action_results || []).every((result) => !result || result.ok !== false),
+          result_count: (viewport.setup_action_results || []).length,
+        })),
+        failed,
+      },
+      message: failed.length ? "Setup actions failed in " + failed.length + " viewport action(s)." : undefined,
+    });
+  }
   for (const check of profile.checks || []) {
     if (check.type === "route_loaded") {
       const expectedPath = check.expected_path || new URL(evidence.target_url).pathname || "/";
@@ -599,6 +727,92 @@ function textMatches(sample, check) {
   }
   return String(sample || "").includes(check.text || "");
 }
+function setupActionType(action) {
+  return String(action && action.type ? action.type : "").replace(/-/g, "_");
+}
+function setupNumber(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : fallback;
+}
+function setupTextMatches(sample, action) {
+  if (action.pattern) {
+    try { return new RegExp(action.pattern, action.flags || "").test(sample || ""); } catch { return false; }
+  }
+  return String(sample || "").includes(action.text || "");
+}
+async function setupLocatorText(locator, index) {
+  return await locator.nth(index).textContent({ timeout: 1000 }).catch(() => "");
+}
+async function executeSetupAction(action, ordinal) {
+  const type = setupActionType(action);
+  const base = { ok: false, action: type || "unknown", ordinal, selector: action.selector || null };
+  const timeout = setupNumber(action.timeout_ms, 5000);
+  try {
+    if (type === "wait") {
+      const ms = setupNumber(action.ms, 500);
+      await page.waitForTimeout(ms);
+      return { ...base, ok: true, ms };
+    }
+    if (type === "wait_for_selector") {
+      await page.waitForSelector(action.selector, { state: "visible", timeout });
+      return { ...base, ok: true, timeout_ms: timeout };
+    }
+    if (type === "click") {
+      const locator = page.locator(action.selector);
+      const count = await locator.count();
+      if (!count) return { ...base, reason: "selector_not_found", count };
+      let targetIndex = Number.isInteger(action.index) ? action.index : 0;
+      let matchedText = null;
+      if (action.text || action.pattern) {
+        targetIndex = -1;
+        for (let index = 0; index < count; index += 1) {
+          const text = await setupLocatorText(locator, index);
+          if (setupTextMatches(text, action)) {
+            targetIndex = index;
+            matchedText = text;
+            break;
+          }
+        }
+        if (targetIndex < 0) return { ...base, reason: "text_not_found", count };
+      }
+      if (targetIndex < 0 || targetIndex >= count) return { ...base, reason: "index_out_of_range", count, target_index: targetIndex };
+      await locator.nth(targetIndex).click({ timeout });
+      return { ...base, ok: true, count, target_index: targetIndex, text: matchedText };
+    }
+    if (type === "wait_for_text") {
+      const locator = page.locator(action.selector);
+      const startedAt = Date.now();
+      let lastText = "";
+      while (Date.now() - startedAt <= timeout) {
+        const count = await locator.count().catch(() => 0);
+        for (let index = 0; index < count; index += 1) {
+          const text = await setupLocatorText(locator, index);
+          lastText = text || lastText;
+          if (setupTextMatches(text, action)) {
+            return { ...base, ok: true, text, target_index: index, timeout_ms: timeout };
+          }
+        }
+        await page.waitForTimeout(100);
+      }
+      return { ...base, reason: "text_not_found", text: lastText, timeout_ms: timeout };
+    }
+    return { ...base, reason: "unsupported_action" };
+  } catch (error) {
+    return { ...base, error: String(error && error.message ? error.message : error).slice(0, 1000) };
+  }
+}
+async function executeSetupActions(actions) {
+  const results = [];
+  for (let index = 0; index < (actions || []).length; index += 1) {
+    const action = actions[index] || {};
+    const result = await executeSetupAction(action, index);
+    results.push(result);
+    const afterMs = setupNumber(action.after_ms, 0);
+    if (afterMs) await page.waitForTimeout(afterMs);
+    if (result.ok === false && action.continue_on_failure !== true) break;
+  }
+  return results;
+}
 function expectedPathFor(check) {
   return check.expected_path || new URL(targetUrl).pathname || "/";
 }
@@ -633,6 +847,9 @@ async function captureViewport(viewport) {
   if (!navigationError && profile.target.wait_ms) {
     await page.waitForTimeout(profile.target.wait_ms);
   }
+  const setupActionResults = (!navigationError && !waitError)
+    ? await executeSetupActions(profile.target.setup_actions || [])
+    : [];
   const dom = await page.evaluate(() => {
     const body = document.body;
     const documentElement = document.documentElement;
@@ -694,6 +911,7 @@ async function captureViewport(viewport) {
     overflow_px: Math.max(0, (dom.scroll_width || 0) - (dom.client_width || viewport.width)),
     selectors,
     text_matches,
+    setup_action_results: setupActionResults,
     screenshot_label: screenshotLabel,
     navigation_error: navigationError,
     wait_error: waitError,
@@ -793,6 +1011,7 @@ export {
   RIDDLE_PROOF_PROFILE_RESULT_VERSION,
   RIDDLE_PROOF_PROFILE_STATUSES,
   RIDDLE_PROOF_PROFILE_CHECK_TYPES,
+  RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES,
   slugifyRiddleProofProfileName,
   normalizeRiddleProofProfile,
   resolveRiddleProofProfileTargetUrl,

package/dist/cli.cjs

@@ -6799,6 +6799,12 @@ var RIDDLE_PROOF_PROFILE_CHECK_TYPES = [
   "no_mobile_horizontal_overflow",
   "no_fatal_console_errors"
 ];
+var RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES = [
+  "click",
+  "wait",
+  "wait_for_selector",
+  "wait_for_text"
+];
 var DEFAULT_VIEWPORTS = [
   { name: "desktop", width: 1280, height: 800 }
 ];
@@ -6851,6 +6857,41 @@ function normalizeViewports(value) {
 function isSupportedCheckType(value) {
   return RIDDLE_PROOF_PROFILE_CHECK_TYPES.includes(value);
 }
+function normalizeSetupActionType(value, index) {
+  const normalized = String(value || "").trim().replace(/-/g, "_");
+  if (RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES.includes(normalized)) {
+    return normalized;
+  }
+  throw new Error(`target.setup_actions[${index}].type ${value || "(missing)"} is not supported. Supported actions: ${RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES.join(", ")}`);
+}
+function normalizeSetupAction(input, index) {
+  if (!isRecord(input)) throw new Error(`target.setup_actions[${index}] must be an object.`);
+  const type = normalizeSetupActionType(stringValue2(input.type), index);
+  const selector = stringValue2(input.selector);
+  if ((type === "click" || type === "wait_for_selector" || type === "wait_for_text") && !selector) {
+    throw new Error(`target.setup_actions[${index}] ${type} requires selector.`);
+  }
+  if (type === "wait_for_text" && !stringValue2(input.text) && !stringValue2(input.pattern)) {
+    throw new Error(`target.setup_actions[${index}] wait_for_text requires text or pattern.`);
+  }
+  return {
+    type,
+    selector,
+    text: stringValue2(input.text),
+    pattern: stringValue2(input.pattern),
+    flags: stringValue2(input.flags),
+    index: numberValue(input.index),
+    ms: numberValue(input.ms) ?? numberValue(input.wait_ms) ?? numberValue(input.waitMs),
+    timeout_ms: numberValue(input.timeout_ms) ?? numberValue(input.timeoutMs),
+    after_ms: numberValue(input.after_ms) ?? numberValue(input.afterMs),
+    continue_on_failure: input.continue_on_failure === true || input.continueOnFailure === true
+  };
+}
+function normalizeSetupActions(value) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value)) throw new Error("target.setup_actions must be an array.");
+  return value.map(normalizeSetupAction);
+}
 function normalizeCheck(input, index) {
   if (!isRecord(input)) throw new Error(`checks[${index}] must be an object.`);
   const type = stringValue2(input.type);
@@ -6918,7 +6959,8 @@ function normalizeRiddleProofProfile(input, options = {}) {
       viewports: options.viewports?.length ? options.viewports : normalizeViewports(targetInput.viewports),
       auth: stringValue2(targetInput.auth) || "none",
       wait_for_selector: stringValue2(targetInput.wait_for_selector) || stringValue2(targetInput.waitForSelector),
-      wait_ms: numberValue(targetInput.wait_ms) ?? numberValue(targetInput.waitMs)
+      wait_ms: numberValue(targetInput.wait_ms) ?? numberValue(targetInput.waitMs),
+      setup_actions: normalizeSetupActions(targetInput.setup_actions ?? targetInput.setupActions)
     },
     checks,
     artifacts: Array.isArray(input.artifacts) ? input.artifacts.map((item) => String(item)).filter(Boolean) : ["screenshot", "console", "dom_summary", "proof_json"],
@@ -7091,6 +7133,48 @@ function assessCheckFromEvidence(check, evidence) {
     message: "Unsupported check type."
   };
 }
+function assessSetupActionsFromEvidence(profile, evidence) {
+  if (!profile.target.setup_actions?.length) return void 0;
+  const actionCount = profile.target.setup_actions.length;
+  const failed = [];
+  const viewports = evidence.viewports || [];
+  for (const viewport of viewports) {
+    const results = viewport.setup_action_results || [];
+    for (const result of results) {
+      if (result.ok === false) {
+        failed.push({
+          viewport: viewport.name,
+          action: result.action ?? result.type ?? null,
+          selector: result.selector ?? null,
+          reason: result.reason ?? result.error ?? null
+        });
+      }
+    }
+    if (results.length < actionCount && results.every((result) => result.ok !== false)) {
+      failed.push({
+        viewport: viewport.name,
+        action: "setup_actions",
+        selector: null,
+        reason: `missing setup action results: ${results.length}/${actionCount}`
+      });
+    }
+  }
+  return {
+    type: "setup_actions_succeeded",
+    label: "setup actions succeeded",
+    status: failed.length ? "failed" : "passed",
+    evidence: {
+      action_count: actionCount,
+      viewports: viewports.map((viewport) => ({
+        name: viewport.name,
+        ok: (viewport.setup_action_results || []).length >= actionCount && (viewport.setup_action_results || []).every((result) => result.ok !== false),
+        result_count: (viewport.setup_action_results || []).length
+      })),
+      failed
+    },
+    message: failed.length ? `Setup actions failed in ${failed.length} viewport action(s).` : void 0
+  };
+}
 function profileStatusFromEvidence(evidence, checks) {
   if (!evidence) return "proof_insufficient";
   const viewports = evidence.viewports || [];
@@ -7102,7 +7186,10 @@ function profileStatusFromEvidence(evidence, checks) {
 }
 function assessRiddleProofProfileEvidence(profile, evidence, options = {}) {
   const capturedAt = evidence?.captured_at || (/* @__PURE__ */ new Date()).toISOString();
-  const checks = evidence ? profile.checks.map((check) => assessCheckFromEvidence(check, evidence)) : [];
+  const checks = evidence ? [
+    assessSetupActionsFromEvidence(profile, evidence),
+    ...profile.checks.map((check) => assessCheckFromEvidence(check, evidence))
+  ].filter((check) => Boolean(check)) : [];
   const status = profileStatusFromEvidence(evidence, checks);
   const firstViewport = evidence?.viewports?.[0];
   const screenshots = (evidence?.viewports || []).map((viewport) => viewport.screenshot_label).filter((label) => Boolean(label));
@@ -7200,6 +7287,47 @@ function textMatches(sample, check) {
 function assessProfile(profile, evidence) {
   const checks = [];
   const viewports = evidence.viewports || [];
+  if (profile.target && Array.isArray(profile.target.setup_actions) && profile.target.setup_actions.length) {
+    const actionCount = profile.target.setup_actions.length;
+    const failed = [];
+    for (const viewport of viewports) {
+      const results = viewport.setup_action_results || [];
+      for (const result of results) {
+        if (result && result.ok === false) {
+          failed.push({
+            viewport: viewport.name,
+            action: result.action || result.type || null,
+            selector: result.selector || null,
+            reason: result.reason || result.error || null,
+          });
+        }
+      }
+      if (results.length < actionCount && results.every((result) => !result || result.ok !== false)) {
+        failed.push({
+          viewport: viewport.name,
+          action: "setup_actions",
+          selector: null,
+          reason: "missing setup action results: " + results.length + "/" + actionCount,
+        });
+      }
+    }
+    checks.push({
+      type: "setup_actions_succeeded",
+      label: "setup actions succeeded",
+      status: failed.length ? "failed" : "passed",
+      evidence: {
+        action_count: actionCount,
+        viewports: viewports.map((viewport) => ({
+          name: viewport.name,
+          ok: (viewport.setup_action_results || []).length >= actionCount
+            && (viewport.setup_action_results || []).every((result) => !result || result.ok !== false),
+          result_count: (viewport.setup_action_results || []).length,
+        })),
+        failed,
+      },
+      message: failed.length ? "Setup actions failed in " + failed.length + " viewport action(s)." : undefined,
+    });
+  }
   for (const check of profile.checks || []) {
     if (check.type === "route_loaded") {
       const expectedPath = check.expected_path || new URL(evidence.target_url).pathname || "/";
@@ -7362,6 +7490,92 @@ function textMatches(sample, check) {
   }
   return String(sample || "").includes(check.text || "");
 }
+function setupActionType(action) {
+  return String(action && action.type ? action.type : "").replace(/-/g, "_");
+}
+function setupNumber(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : fallback;
+}
+function setupTextMatches(sample, action) {
+  if (action.pattern) {
+    try { return new RegExp(action.pattern, action.flags || "").test(sample || ""); } catch { return false; }
+  }
+  return String(sample || "").includes(action.text || "");
+}
+async function setupLocatorText(locator, index) {
+  return await locator.nth(index).textContent({ timeout: 1000 }).catch(() => "");
+}
+async function executeSetupAction(action, ordinal) {
+  const type = setupActionType(action);
+  const base = { ok: false, action: type || "unknown", ordinal, selector: action.selector || null };
+  const timeout = setupNumber(action.timeout_ms, 5000);
+  try {
+    if (type === "wait") {
+      const ms = setupNumber(action.ms, 500);
+      await page.waitForTimeout(ms);
+      return { ...base, ok: true, ms };
+    }
+    if (type === "wait_for_selector") {
+      await page.waitForSelector(action.selector, { state: "visible", timeout });
+      return { ...base, ok: true, timeout_ms: timeout };
+    }
+    if (type === "click") {
+      const locator = page.locator(action.selector);
+      const count = await locator.count();
+      if (!count) return { ...base, reason: "selector_not_found", count };
+      let targetIndex = Number.isInteger(action.index) ? action.index : 0;
+      let matchedText = null;
+      if (action.text || action.pattern) {
+        targetIndex = -1;
+        for (let index = 0; index < count; index += 1) {
+          const text = await setupLocatorText(locator, index);
+          if (setupTextMatches(text, action)) {
+            targetIndex = index;
+            matchedText = text;
+            break;
+          }
+        }
+        if (targetIndex < 0) return { ...base, reason: "text_not_found", count };
+      }
+      if (targetIndex < 0 || targetIndex >= count) return { ...base, reason: "index_out_of_range", count, target_index: targetIndex };
+      await locator.nth(targetIndex).click({ timeout });
+      return { ...base, ok: true, count, target_index: targetIndex, text: matchedText };
+    }
+    if (type === "wait_for_text") {
+      const locator = page.locator(action.selector);
+      const startedAt = Date.now();
+      let lastText = "";
+      while (Date.now() - startedAt <= timeout) {
+        const count = await locator.count().catch(() => 0);
+        for (let index = 0; index < count; index += 1) {
+          const text = await setupLocatorText(locator, index);
+          lastText = text || lastText;
+          if (setupTextMatches(text, action)) {
+            return { ...base, ok: true, text, target_index: index, timeout_ms: timeout };
+          }
+        }
+        await page.waitForTimeout(100);
+      }
+      return { ...base, reason: "text_not_found", text: lastText, timeout_ms: timeout };
+    }
+    return { ...base, reason: "unsupported_action" };
+  } catch (error) {
+    return { ...base, error: String(error && error.message ? error.message : error).slice(0, 1000) };
+  }
+}
+async function executeSetupActions(actions) {
+  const results = [];
+  for (let index = 0; index < (actions || []).length; index += 1) {
+    const action = actions[index] || {};
+    const result = await executeSetupAction(action, index);
+    results.push(result);
+    const afterMs = setupNumber(action.after_ms, 0);
+    if (afterMs) await page.waitForTimeout(afterMs);
+    if (result.ok === false && action.continue_on_failure !== true) break;
+  }
+  return results;
+}
 function expectedPathFor(check) {
   return check.expected_path || new URL(targetUrl).pathname || "/";
 }
@@ -7396,6 +7610,9 @@ async function captureViewport(viewport) {
   if (!navigationError && profile.target.wait_ms) {
     await page.waitForTimeout(profile.target.wait_ms);
   }
+  const setupActionResults = (!navigationError && !waitError)
+    ? await executeSetupActions(profile.target.setup_actions || [])
+    : [];
   const dom = await page.evaluate(() => {
     const body = document.body;
     const documentElement = document.documentElement;
@@ -7457,6 +7674,7 @@ async function captureViewport(viewport) {
     overflow_px: Math.max(0, (dom.scroll_width || 0) - (dom.client_width || viewport.width)),
     selectors,
     text_matches,
+    setup_action_results: setupActionResults,
     screenshot_label: screenshotLabel,
     navigation_error: navigationError,
     wait_error: waitError,

package/dist/cli.js

@@ -9,7 +9,7 @@ import {
   normalizeRiddleProofProfile,
   profileStatusExitCode,
   resolveRiddleProofProfileTargetUrl
-} from "./chunk-7NMAU4DP.js";
+} from "./chunk-NUSUGO2P.js";
 import {
   createRiddleApiClient,
   parseRiddleViewport