@riddledc/riddle-proof 0.7.8 → 0.7.10

package/dist/profile.cjs

@@ -23,6 +23,7 @@ __export(profile_exports, {
   RIDDLE_PROOF_PROFILE_CHECK_TYPES: () => RIDDLE_PROOF_PROFILE_CHECK_TYPES,
   RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION: () => RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION,
   RIDDLE_PROOF_PROFILE_RESULT_VERSION: () => RIDDLE_PROOF_PROFILE_RESULT_VERSION,
+  RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES: () => RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES,
   RIDDLE_PROOF_PROFILE_STATUSES: () => RIDDLE_PROOF_PROFILE_STATUSES,
   RIDDLE_PROOF_PROFILE_VERSION: () => RIDDLE_PROOF_PROFILE_VERSION,
   assessRiddleProofProfileEvidence: () => assessRiddleProofProfileEvidence,
@@ -60,6 +61,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 }
 ];
@@ -112,6 +119,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);
@@ -179,7 +221,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"],
@@ -197,7 +240,13 @@ function resolveRiddleProofProfileTargetUrl(profile) {
   throw new Error("profile target URL could not be resolved.");
 }
 function routeForViewport(viewport) {
-  return viewport?.route || {
+  if (viewport?.route) {
+    return {
+      ...viewport.route,
+      matched: viewport.route.matched || routePathMatches(viewport.route.observed, viewport.route.expected_path)
+    };
+  }
+  return {
     requested: "",
     observed: "",
     matched: false,
@@ -223,8 +272,17 @@ function matchText(sample, check) {
   }
   return sample.includes(check.text || "");
 }
+function normalizeRoutePath(path) {
+  const value = path || "/";
+  if (value === "/") return "/";
+  return value.replace(/\/+$/, "") || "/";
+}
+function routePathMatches(observed, expected) {
+  return normalizeRoutePath(observed) === normalizeRoutePath(expected);
+}
 function successfulRoute(route) {
-  return route.matched && !route.error && (route.http_status === null || route.http_status === void 0 || route.http_status < 400);
+  const matched = route.matched || routePathMatches(route.observed, route.expected_path);
+  return matched && !route.error && (route.http_status === null || route.http_status === void 0 || route.http_status < 400);
 }
 function assessCheckFromEvidence(check, evidence) {
   const viewports = evidence.viewports || [];
@@ -242,7 +300,7 @@ function assessCheckFromEvidence(check, evidence) {
     const failed = viewports.filter((viewport) => !successfulRoute({
       ...viewport.route,
       expected_path: expectedPath,
-      matched: viewport.route.observed === expectedPath || viewport.route.matched
+      matched: routePathMatches(viewport.route.observed, expectedPath) || viewport.route.matched
     }));
     return {
       type: check.type,
@@ -352,6 +410,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 || [];
@@ -363,7 +463,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));
@@ -465,8 +568,16 @@ function createRiddleProofProfileInsufficientResult(input) {
 }
 function runtimeScriptAssessmentSource() {
   return String.raw`
+function normalizeRoutePath(path) {
+  const value = path || "/";
+  if (value === "/") return "/";
+  return value.replace(/\/+$/, "") || "/";
+}
+function routePathMatches(observed, expected) {
+  return normalizeRoutePath(observed) === normalizeRoutePath(expected);
+}
 function routeOk(route) {
-  return Boolean(route && route.matched && !route.error && (route.http_status == null || route.http_status < 400));
+  return Boolean(route && (route.matched || routePathMatches(route.observed, route.expected_path)) && !route.error && (route.http_status == null || route.http_status < 400));
 }
 function textMatches(sample, check) {
   if (check.pattern) {
@@ -477,12 +588,53 @@ 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 || "/";
       const failed = viewports.filter((viewport) => {
         const route = { ...(viewport.route || {}), expected_path: expectedPath };
-        route.matched = route.observed === expectedPath || route.matched;
+        route.matched = routePathMatches(route.observed, expectedPath) || route.matched;
         return !routeOk(route);
       });
       checks.push({
@@ -639,6 +791,105 @@ 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 setupLocatorVisible(locator, index) {
+  return await locator.nth(index).isVisible({ timeout: 1000 }).catch(() => false);
+}
+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;
+      let hiddenMatchIndex = -1;
+      let hiddenMatchedText = 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)) {
+            const visible = await setupLocatorVisible(locator, index);
+            if (visible) {
+              targetIndex = index;
+              matchedText = text;
+              break;
+            }
+            if (hiddenMatchIndex < 0) {
+              hiddenMatchIndex = index;
+              hiddenMatchedText = text;
+            }
+          }
+        }
+        if (targetIndex < 0 && hiddenMatchIndex >= 0) return { ...base, reason: "matching_element_not_visible", count, target_index: hiddenMatchIndex, text: hiddenMatchedText };
+        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 || "/";
 }
@@ -673,6 +924,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;
@@ -722,7 +976,7 @@ async function captureViewport(viewport) {
       requested: targetUrl,
       observed: dom.pathname,
       expected_path: expectedPath,
-      matched: dom.pathname === expectedPath,
+      matched: routePathMatches(dom.pathname, expectedPath),
       http_status: httpStatus,
       error: navigationError || waitError || undefined,
     },
@@ -734,6 +988,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,
@@ -831,6 +1086,7 @@ function extractRiddleProofProfileResult(input) {
   RIDDLE_PROOF_PROFILE_CHECK_TYPES,
   RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION,
   RIDDLE_PROOF_PROFILE_RESULT_VERSION,
+  RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES,
   RIDDLE_PROOF_PROFILE_STATUSES,
   RIDDLE_PROOF_PROFILE_VERSION,
   assessRiddleProofProfileEvidence,

package/dist/profile.d.cts

@@ -5,8 +5,10 @@ declare const RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION: "riddle-proof.profile-evide
 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", "selector_visible", "selector_count_at_least", "text_visible", "text_absent", "no_horizontal_overflow", "no_mobile_horizontal_overflow", "no_fatal_console_errors"];
+declare const RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES: readonly ["click", "wait", "wait_for_selector", "wait_for_text"];
 type RiddleProofProfileStatus = typeof RIDDLE_PROOF_PROFILE_STATUSES[number];
 type RiddleProofProfileCheckType = typeof RIDDLE_PROOF_PROFILE_CHECK_TYPES[number];
+type RiddleProofProfileSetupActionType = typeof RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES[number];
 type RiddleProofProfileRunner = "riddle" | "local-playwright" | "browserless" | "github-actions" | (string & {});
 type RiddleProofProfileFailureAction = "fail" | "neutral" | "review";
 type RiddleProofProfileBaselinePolicy = "invariant_only" | "production_comparison" | "last_accepted_artifact" | "golden_reference_artifact" | (string & {});
@@ -15,6 +17,18 @@ interface RiddleProofProfileViewport {
     width: number;
     height: number;
 }
+interface RiddleProofProfileSetupAction {
+    type: RiddleProofProfileSetupActionType;
+    selector?: string;
+    text?: string;
+    pattern?: string;
+    flags?: string;
+    index?: number;
+    ms?: number;
+    timeout_ms?: number;
+    after_ms?: number;
+    continue_on_failure?: boolean;
+}
 interface RiddleProofProfileTarget {
     url?: string;
     route?: string;
@@ -22,6 +36,7 @@ interface RiddleProofProfileTarget {
     auth?: "none" | (string & {});
     wait_for_selector?: string;
     wait_ms?: number;
+    setup_actions?: RiddleProofProfileSetupAction[];
 }
 interface RiddleProofProfileCheck {
     type: RiddleProofProfileCheckType;
@@ -69,6 +84,7 @@ interface RiddleProofProfileViewportEvidence {
         visible_count: number;
     }>;
     text_matches?: Record<string, boolean>;
+    setup_action_results?: Array<Record<string, JsonValue>>;
     screenshot_label?: string;
     navigation_error?: string;
     wait_error?: string;
@@ -172,4 +188,4 @@ declare function buildRiddleProofProfileScript(profile: RiddleProofProfile): str
 declare function collectRiddleProfileArtifactRefs(input: unknown): RiddleProofProfileArtifactRef[];
 declare function extractRiddleProofProfileResult(input: unknown): RiddleProofProfileResult | undefined;
 
-export { type NormalizeRiddleProofProfileOptions, RIDDLE_PROOF_PROFILE_CHECK_TYPES, RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION, RIDDLE_PROOF_PROFILE_RESULT_VERSION, RIDDLE_PROOF_PROFILE_STATUSES, RIDDLE_PROOF_PROFILE_VERSION, type RiddleProofProfile, type RiddleProofProfileArtifactRef, type RiddleProofProfileBaselinePolicy, type RiddleProofProfileCheck, type RiddleProofProfileCheckResult, type RiddleProofProfileCheckType, type RiddleProofProfileEvidence, type RiddleProofProfileFailureAction, type RiddleProofProfileResult, type RiddleProofProfileRouteEvidence, type RiddleProofProfileRunner, type RiddleProofProfileStatus, type RiddleProofProfileTarget, type RiddleProofProfileViewport, type RiddleProofProfileViewportEvidence, assessRiddleProofProfileEvidence, buildRiddleProofProfileScript, collectRiddleProfileArtifactRefs, createRiddleProofProfileConfigurationError, createRiddleProofProfileEnvironmentBlockedResult, createRiddleProofProfileInsufficientResult, extractRiddleProofProfileResult, normalizeRiddleProofProfile, profileStatusExitCode, resolveRiddleProofProfileTargetUrl, slugifyRiddleProofProfileName, summarizeRiddleProofProfileResult };
+export { type NormalizeRiddleProofProfileOptions, RIDDLE_PROOF_PROFILE_CHECK_TYPES, RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION, RIDDLE_PROOF_PROFILE_RESULT_VERSION, RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES, RIDDLE_PROOF_PROFILE_STATUSES, RIDDLE_PROOF_PROFILE_VERSION, type RiddleProofProfile, type RiddleProofProfileArtifactRef, type RiddleProofProfileBaselinePolicy, type RiddleProofProfileCheck, type RiddleProofProfileCheckResult, type RiddleProofProfileCheckType, type RiddleProofProfileEvidence, type RiddleProofProfileFailureAction, type RiddleProofProfileResult, type RiddleProofProfileRouteEvidence, type RiddleProofProfileRunner, type RiddleProofProfileSetupAction, type RiddleProofProfileSetupActionType, type RiddleProofProfileStatus, type RiddleProofProfileTarget, type RiddleProofProfileViewport, type RiddleProofProfileViewportEvidence, assessRiddleProofProfileEvidence, buildRiddleProofProfileScript, collectRiddleProfileArtifactRefs, createRiddleProofProfileConfigurationError, createRiddleProofProfileEnvironmentBlockedResult, createRiddleProofProfileInsufficientResult, extractRiddleProofProfileResult, normalizeRiddleProofProfile, profileStatusExitCode, resolveRiddleProofProfileTargetUrl, slugifyRiddleProofProfileName, summarizeRiddleProofProfileResult };

package/dist/profile.d.ts

@@ -5,8 +5,10 @@ declare const RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION: "riddle-proof.profile-evide
 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", "selector_visible", "selector_count_at_least", "text_visible", "text_absent", "no_horizontal_overflow", "no_mobile_horizontal_overflow", "no_fatal_console_errors"];
+declare const RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES: readonly ["click", "wait", "wait_for_selector", "wait_for_text"];
 type RiddleProofProfileStatus = typeof RIDDLE_PROOF_PROFILE_STATUSES[number];
 type RiddleProofProfileCheckType = typeof RIDDLE_PROOF_PROFILE_CHECK_TYPES[number];
+type RiddleProofProfileSetupActionType = typeof RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES[number];
 type RiddleProofProfileRunner = "riddle" | "local-playwright" | "browserless" | "github-actions" | (string & {});
 type RiddleProofProfileFailureAction = "fail" | "neutral" | "review";
 type RiddleProofProfileBaselinePolicy = "invariant_only" | "production_comparison" | "last_accepted_artifact" | "golden_reference_artifact" | (string & {});
@@ -15,6 +17,18 @@ interface RiddleProofProfileViewport {
     width: number;
     height: number;
 }
+interface RiddleProofProfileSetupAction {
+    type: RiddleProofProfileSetupActionType;
+    selector?: string;
+    text?: string;
+    pattern?: string;
+    flags?: string;
+    index?: number;
+    ms?: number;
+    timeout_ms?: number;
+    after_ms?: number;
+    continue_on_failure?: boolean;
+}
 interface RiddleProofProfileTarget {
     url?: string;
     route?: string;
@@ -22,6 +36,7 @@ interface RiddleProofProfileTarget {
     auth?: "none" | (string & {});
     wait_for_selector?: string;
     wait_ms?: number;
+    setup_actions?: RiddleProofProfileSetupAction[];
 }
 interface RiddleProofProfileCheck {
     type: RiddleProofProfileCheckType;
@@ -69,6 +84,7 @@ interface RiddleProofProfileViewportEvidence {
         visible_count: number;
     }>;
     text_matches?: Record<string, boolean>;
+    setup_action_results?: Array<Record<string, JsonValue>>;
     screenshot_label?: string;
     navigation_error?: string;
     wait_error?: string;
@@ -172,4 +188,4 @@ declare function buildRiddleProofProfileScript(profile: RiddleProofProfile): str
 declare function collectRiddleProfileArtifactRefs(input: unknown): RiddleProofProfileArtifactRef[];
 declare function extractRiddleProofProfileResult(input: unknown): RiddleProofProfileResult | undefined;
 
-export { type NormalizeRiddleProofProfileOptions, RIDDLE_PROOF_PROFILE_CHECK_TYPES, RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION, RIDDLE_PROOF_PROFILE_RESULT_VERSION, RIDDLE_PROOF_PROFILE_STATUSES, RIDDLE_PROOF_PROFILE_VERSION, type RiddleProofProfile, type RiddleProofProfileArtifactRef, type RiddleProofProfileBaselinePolicy, type RiddleProofProfileCheck, type RiddleProofProfileCheckResult, type RiddleProofProfileCheckType, type RiddleProofProfileEvidence, type RiddleProofProfileFailureAction, type RiddleProofProfileResult, type RiddleProofProfileRouteEvidence, type RiddleProofProfileRunner, type RiddleProofProfileStatus, type RiddleProofProfileTarget, type RiddleProofProfileViewport, type RiddleProofProfileViewportEvidence, assessRiddleProofProfileEvidence, buildRiddleProofProfileScript, collectRiddleProfileArtifactRefs, createRiddleProofProfileConfigurationError, createRiddleProofProfileEnvironmentBlockedResult, createRiddleProofProfileInsufficientResult, extractRiddleProofProfileResult, normalizeRiddleProofProfile, profileStatusExitCode, resolveRiddleProofProfileTargetUrl, slugifyRiddleProofProfileName, summarizeRiddleProofProfileResult };
+export { type NormalizeRiddleProofProfileOptions, RIDDLE_PROOF_PROFILE_CHECK_TYPES, RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION, RIDDLE_PROOF_PROFILE_RESULT_VERSION, RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES, RIDDLE_PROOF_PROFILE_STATUSES, RIDDLE_PROOF_PROFILE_VERSION, type RiddleProofProfile, type RiddleProofProfileArtifactRef, type RiddleProofProfileBaselinePolicy, type RiddleProofProfileCheck, type RiddleProofProfileCheckResult, type RiddleProofProfileCheckType, type RiddleProofProfileEvidence, type RiddleProofProfileFailureAction, type RiddleProofProfileResult, type RiddleProofProfileRouteEvidence, type RiddleProofProfileRunner, type RiddleProofProfileSetupAction, type RiddleProofProfileSetupActionType, type RiddleProofProfileStatus, type RiddleProofProfileTarget, type RiddleProofProfileViewport, type RiddleProofProfileViewportEvidence, assessRiddleProofProfileEvidence, buildRiddleProofProfileScript, collectRiddleProfileArtifactRefs, createRiddleProofProfileConfigurationError, createRiddleProofProfileEnvironmentBlockedResult, createRiddleProofProfileInsufficientResult, extractRiddleProofProfileResult, normalizeRiddleProofProfile, profileStatusExitCode, resolveRiddleProofProfileTargetUrl, slugifyRiddleProofProfileName, summarizeRiddleProofProfileResult };

package/dist/profile.js

@@ -2,6 +2,7 @@ import {
   RIDDLE_PROOF_PROFILE_CHECK_TYPES,
   RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION,
   RIDDLE_PROOF_PROFILE_RESULT_VERSION,
+  RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES,
   RIDDLE_PROOF_PROFILE_STATUSES,
   RIDDLE_PROOF_PROFILE_VERSION,
   assessRiddleProofProfileEvidence,
@@ -16,11 +17,12 @@ import {
   resolveRiddleProofProfileTargetUrl,
   slugifyRiddleProofProfileName,
   summarizeRiddleProofProfileResult
-} from "./chunk-7NMAU4DP.js";
+} from "./chunk-A7RJZD4I.js";
 export {
   RIDDLE_PROOF_PROFILE_CHECK_TYPES,
   RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION,
   RIDDLE_PROOF_PROFILE_RESULT_VERSION,
+  RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES,
   RIDDLE_PROOF_PROFILE_STATUSES,
   RIDDLE_PROOF_PROFILE_VERSION,
   assessRiddleProofProfileEvidence,

package/dist/proof-run-engine.d.cts

@@ -292,7 +292,7 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
     blocking?: boolean;
     details?: Record<string, unknown>;
     ok: boolean;
-    action: "author" | "recon" | "ship" | "implement" | "verify" | "setup" | "run";
+    action: "recon" | "author" | "ship" | "implement" | "verify" | "setup" | "run";
     state_path: string;
     stage: any;
     summary: string;
@@ -382,7 +382,7 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
     continueWithStage?: WorkflowStage | null;
     blocking?: boolean;
     details?: Record<string, unknown>;
-    action: "author" | "recon" | "ship" | "implement" | "verify" | "setup" | "run";
+    action: "recon" | "author" | "ship" | "implement" | "verify" | "setup" | "run";
     state_path: string;
     stage: any;
     checkpoint: string;
@@ -659,7 +659,7 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
     error?: undefined;
 } | {
     ok: boolean;
-    action: "author" | "recon" | "ship" | "implement" | "verify" | "setup" | "run";
+    action: "recon" | "author" | "ship" | "implement" | "verify" | "setup" | "run";
     state_path: string;
     stage: any;
     summary: string;

package/dist/proof-run-engine.d.ts

@@ -292,7 +292,7 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
     blocking?: boolean;
     details?: Record<string, unknown>;
     ok: boolean;
-    action: "author" | "recon" | "ship" | "implement" | "verify" | "setup" | "run";
+    action: "recon" | "author" | "ship" | "implement" | "verify" | "setup" | "run";
     state_path: string;
     stage: any;
     summary: string;
@@ -382,7 +382,7 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
     continueWithStage?: WorkflowStage | null;
     blocking?: boolean;
     details?: Record<string, unknown>;
-    action: "author" | "recon" | "ship" | "implement" | "verify" | "setup" | "run";
+    action: "recon" | "author" | "ship" | "implement" | "verify" | "setup" | "run";
     state_path: string;
     stage: any;
     checkpoint: string;
@@ -659,7 +659,7 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
     error?: undefined;
 } | {
     ok: boolean;
-    action: "author" | "recon" | "ship" | "implement" | "verify" | "setup" | "run";
+    action: "recon" | "author" | "ship" | "implement" | "verify" | "setup" | "run";
     state_path: string;
     stage: any;
     summary: string;

package/examples/profiles/page-content-basic.json

@@ -8,7 +8,10 @@
       { "name": "desktop", "width": 1440, "height": 1000 }
     ],
     "auth": "none",
-    "wait_for_selector": "body"
+    "wait_for_selector": "body",
+    "setup_actions": [
+      { "type": "wait", "ms": 250 }
+    ]
   },
   "checks": [
     { "type": "route_loaded", "expected_path": "/" },

package/package.json

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