@riddledc/riddle-proof 0.7.63 → 0.7.65

package/README.md

@@ -242,10 +242,10 @@ appears only after a picker, tab, login stub, storage seed, form fill,
 transport control, or other bounded interaction. Supported setup actions are
 `click`, `drag`, `press`, `fill`, `set_input_value`, `assert_text_visible`,
 `assert_text_absent`, `assert_selector_count`, `assert_window_value`,
-`assert_window_number`, `local_storage`, `session_storage`, `clear_storage`, `wait`,
-`wait_for_selector`, `wait_for_text`, and `window_call`; 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
+`assert_window_number`, `local_storage`, `session_storage`, `clear_storage`,
+`screenshot`, `wait`, `wait_for_selector`, `wait_for_text`, and `window_call`;
+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
 desktop or mobile-only links. Add `force: true` to a click action only when the
 matched visible element is intentionally animated or otherwise never becomes
@@ -276,6 +276,10 @@ can include `repeat` / `repeat_count` / `times` from 1 to 100; each repetition
 is recorded with `repeat_index` and `repeat_count`, and `after_ms` runs after
 each repetition. Use it for bounded game proof helpers, retry controls, or other
 workflows where one declarative action needs to advance the app several times.
+Use `screenshot` with an optional `label` to capture durable Riddle screenshots
+at important setup milestones, such as after a route switch, terminal state, or
+reset. These labels are recorded in setup evidence and included in profile
+artifact summaries alongside final viewport screenshots.
 Add `frame_selector` / `frameSelector` to a setup action when the interaction
 target lives inside an embedded iframe, such as a community game player or
 hosted preview surface. Selector-based actions, storage actions, window calls,
@@ -287,7 +291,7 @@ it defaults to the first frame.
 Profiles with setup actions also include a compact
 `setup_actions_succeeded.evidence.setup_summary`. The summary groups each
 viewport's final route, final URL, action counts, clicked targets, iframe URLs,
-compact text samples, and failures so setup-heavy clickthrough or iframe proofs
+setup screenshots, compact text samples, and failures so setup-heavy clickthrough or iframe proofs
 can be reviewed without reading every raw setup-action result. Long click
 sequences include `clicked_total` and `clicked_truncated`; the compact `clicked`
 list keeps the first and last clicked targets so later route switches and reset

package/dist/{chunk-MLJHMZLR.js → chunk-DQU65Z65.js}

@@ -46,6 +46,7 @@ var RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES = [
   "local_storage",
   "session_storage",
   "clear_storage",
+  "screenshot",
   "wait",
   "wait_for_selector",
   "wait_for_text",
@@ -206,12 +207,23 @@ function profileSetupActionCounts(results) {
   }
   return toJsonValue(counts);
 }
+function profileSetupScreenshotLabels(results) {
+  return results.filter((result) => profileSetupResultAction(result) === "screenshot" && result.ok !== false && typeof result.screenshot_label === "string").map((result) => result.screenshot_label).filter(Boolean);
+}
 function sampleProfileSetupSummaryItems(items, limit) {
   if (items.length <= limit) return items;
   const firstCount = Math.floor(limit / 2);
   const lastCount = limit - firstCount;
   return [...items.slice(0, firstCount), ...items.slice(-lastCount)];
 }
+function profileScreenshotLabels(viewports) {
+  const labels = [];
+  for (const viewport of viewports || []) {
+    if (viewport.screenshot_label) labels.push(viewport.screenshot_label);
+    labels.push(...profileSetupScreenshotLabels(viewport.setup_action_results || []));
+  }
+  return labels;
+}
 function profileSetupSummary(viewports, actionCount) {
   return toJsonValue({
     viewport_count: viewports.length,
@@ -241,6 +253,7 @@ function profileSetupSummary(viewports, actionCount) {
         action_counts: profileSetupActionCounts(results),
         frame_action_count: results.filter((result) => result.frame_selector).length,
         frame_urls: profileSetupFrameUrls(viewport),
+        setup_screenshots: profileSetupScreenshotLabels(results),
         clicked_total: clickedItems.length,
         clicked_truncated: clickedItems.length > clicked.length,
         clicked,
@@ -286,7 +299,7 @@ function isSupportedCheckType(value) {
 }
 function normalizeSetupActionType(value, index) {
   const normalizedInput = String(value || "").trim().replace(/-/g, "_");
-  const normalized = normalizedInput === "clear_browser_storage" ? "clear_storage" : normalizedInput === "pointer_drag" || normalizedInput === "mouse_drag" || normalizedInput === "drag_to" ? "drag" : normalizedInput === "keyboard_press" || normalizedInput === "key_press" ? "press" : normalizedInput;
+  const normalized = normalizedInput === "clear_browser_storage" ? "clear_storage" : 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;
   if (RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES.includes(normalized)) {
     return normalized;
   }
@@ -417,6 +430,7 @@ function normalizeSetupAction(input, index) {
     key,
     value,
     value_json: hasJsonValue ? toJsonValue(input.value_json ?? input.valueJson ?? input.json) : void 0,
+    label: stringFromOwn(input, "label", "name", "screenshot_label", "screenshotLabel"),
     path,
     args,
     expect_return: hasExpectedReturn ? toJsonValue(valueFromOwn(input, "expect_return", "expectReturn", "expected_return", "expectedReturn")) : void 0,
@@ -1459,7 +1473,7 @@ function assessRiddleProofProfileEvidence(profile, evidence, options = {}) {
   ].filter((check) => Boolean(check)) : [];
   const status = profileStatusFromEvidence(profile, evidence, checks);
   const firstViewport = evidence?.viewports?.[0];
-  const screenshots = (evidence?.viewports || []).map((viewport) => viewport.screenshot_label).filter((label) => Boolean(label));
+  const screenshots = profileScreenshotLabels(evidence?.viewports);
   return {
     version: RIDDLE_PROOF_PROFILE_RESULT_VERSION,
     profile_name: profile.name,
@@ -1808,12 +1822,26 @@ function profileSetupActionCounts(results) {
   }
   return counts;
 }
+function profileSetupScreenshotLabels(results) {
+  return (results || [])
+    .filter((result) => result && profileSetupResultAction(result) === "screenshot" && result.ok !== false && typeof result.screenshot_label === "string")
+    .map((result) => result.screenshot_label)
+    .filter(Boolean);
+}
 function sampleProfileSetupSummaryItems(items, limit) {
   if ((items || []).length <= limit) return items || [];
   const firstCount = Math.floor(limit / 2);
   const lastCount = limit - firstCount;
   return [...items.slice(0, firstCount), ...items.slice(-lastCount)];
 }
+function profileScreenshotLabels(viewports) {
+  const labels = [];
+  for (const viewport of viewports || []) {
+    if (viewport && viewport.screenshot_label) labels.push(viewport.screenshot_label);
+    labels.push(...profileSetupScreenshotLabels(viewport && viewport.setup_action_results || []));
+  }
+  return labels;
+}
 function profileSetupSummary(viewports, actionCount) {
   return {
     viewport_count: (viewports || []).length,
@@ -1853,6 +1881,7 @@ function profileSetupSummary(viewports, actionCount) {
         action_counts: profileSetupActionCounts(results),
         frame_action_count: results.filter((result) => result && result.frame_selector).length,
         frame_urls: profileSetupFrameUrls(viewport),
+        setup_screenshots: profileSetupScreenshotLabels(results),
         clicked_total: clickedItems.length,
         clicked_truncated: clickedItems.length > clicked.length,
         clicked,
@@ -2342,7 +2371,7 @@ function assessProfile(profile, evidence) {
   else if (expectedViewportCount && viewports.length < expectedViewportCount) status = "proof_insufficient";
   else if (checks.some((check) => check.status === "needs_human_review")) status = "needs_human_review";
   else if (checks.some((check) => check.status === "failed")) status = "product_regression";
-  const screenshotLabels = viewports.map((viewport) => viewport.screenshot_label).filter(Boolean);
+  const screenshotLabels = profileScreenshotLabels(viewports);
   const route = viewports[0] && viewports[0].route ? viewports[0].route : { requested: evidence.target_url, observed: "", matched: false, error: "missing viewport evidence" };
   const passedChecks = checks.filter((check) => check.status === "passed").length;
   const failedChecks = checks.filter((check) => check.status === "failed").length;
@@ -2698,7 +2727,7 @@ async function registerNetworkMocks(mocks) {
     });
   }
 }
-async function executeSetupAction(action, ordinal) {
+async function executeSetupAction(action, ordinal, viewport) {
   const type = setupActionType(action);
   const frameSelector = setupFrameSelector(action);
   const base = { ok: false, action: type || "unknown", ordinal, selector: action.selector || null, frame_selector: frameSelector || null };
@@ -2709,6 +2738,19 @@ async function executeSetupAction(action, ordinal) {
       await page.waitForTimeout(ms);
       return { ...base, ok: true, ms };
     }
+    if (type === "screenshot") {
+      const rawLabel = String(action.label || action.name || action.screenshot_label || action.screenshotLabel || ("setup-" + ordinal));
+      const labelPart = rawLabel
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80) || ("setup-" + ordinal);
+      const viewportName = viewport && viewport.name ? viewport.name : "viewport";
+      const label = profileSlug + "-" + viewportName + "-" + labelPart;
+      if (typeof saveScreenshot !== "function") return { ...base, reason: "save_screenshot_unavailable", label: rawLabel };
+      await saveScreenshot(label);
+      return { ...base, ok: true, label: rawLabel, screenshot_label: label };
+    }
     if (type === "wait_for_selector") {
       const scope = await setupActionScope(action, timeout);
       if (!scope.ok) return setupScopeFailure(base, scope);
@@ -3121,7 +3163,7 @@ async function executeSetupAction(action, ordinal) {
     return { ...base, error: String(error && error.message ? error.message : error).slice(0, 1000) };
   }
 }
-async function executeSetupActions(actions) {
+async function executeSetupActions(actions, viewport) {
   const results = [];
   for (let index = 0; index < (actions || []).length; index += 1) {
     const action = actions[index] || {};
@@ -3129,7 +3171,7 @@ async function executeSetupActions(actions) {
     const repeatCount = Math.min(100, Math.max(1, Math.floor(requestedRepeat || 1)));
     let shouldStop = false;
     for (let repeatIndex = 0; repeatIndex < repeatCount; repeatIndex += 1) {
-      const result = await executeSetupAction(action, index);
+      const result = await executeSetupAction(action, index, viewport);
       results.push(repeatCount > 1
         ? { ...result, repeat_index: repeatIndex, repeat_count: repeatCount }
         : result);
@@ -3604,7 +3646,7 @@ async function captureViewport(viewport) {
     await page.waitForTimeout(profile.target.wait_ms);
   }
   const setupActionResults = (!navigationError && !waitError)
-    ? await executeSetupActions(profile.target.setup_actions || [])
+    ? await executeSetupActions(profile.target.setup_actions || [], viewport)
     : [];
   const dom = await page.evaluate(() => {
     const body = document.body;

package/dist/cli.cjs

@@ -6919,6 +6919,7 @@ var RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES = [
   "local_storage",
   "session_storage",
   "clear_storage",
+  "screenshot",
   "wait",
   "wait_for_selector",
   "wait_for_text",
@@ -7079,12 +7080,23 @@ function profileSetupActionCounts(results) {
   }
   return toJsonValue(counts);
 }
+function profileSetupScreenshotLabels(results) {
+  return results.filter((result) => profileSetupResultAction(result) === "screenshot" && result.ok !== false && typeof result.screenshot_label === "string").map((result) => result.screenshot_label).filter(Boolean);
+}
 function sampleProfileSetupSummaryItems(items, limit) {
   if (items.length <= limit) return items;
   const firstCount = Math.floor(limit / 2);
   const lastCount = limit - firstCount;
   return [...items.slice(0, firstCount), ...items.slice(-lastCount)];
 }
+function profileScreenshotLabels(viewports) {
+  const labels = [];
+  for (const viewport of viewports || []) {
+    if (viewport.screenshot_label) labels.push(viewport.screenshot_label);
+    labels.push(...profileSetupScreenshotLabels(viewport.setup_action_results || []));
+  }
+  return labels;
+}
 function profileSetupSummary(viewports, actionCount) {
   return toJsonValue({
     viewport_count: viewports.length,
@@ -7114,6 +7126,7 @@ function profileSetupSummary(viewports, actionCount) {
         action_counts: profileSetupActionCounts(results),
         frame_action_count: results.filter((result) => result.frame_selector).length,
         frame_urls: profileSetupFrameUrls(viewport),
+        setup_screenshots: profileSetupScreenshotLabels(results),
         clicked_total: clickedItems.length,
         clicked_truncated: clickedItems.length > clicked.length,
         clicked,
@@ -7159,7 +7172,7 @@ function isSupportedCheckType(value) {
 }
 function normalizeSetupActionType(value, index) {
   const normalizedInput = String(value || "").trim().replace(/-/g, "_");
-  const normalized = normalizedInput === "clear_browser_storage" ? "clear_storage" : normalizedInput === "pointer_drag" || normalizedInput === "mouse_drag" || normalizedInput === "drag_to" ? "drag" : normalizedInput === "keyboard_press" || normalizedInput === "key_press" ? "press" : normalizedInput;
+  const normalized = normalizedInput === "clear_browser_storage" ? "clear_storage" : 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;
   if (RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES.includes(normalized)) {
     return normalized;
   }
@@ -7290,6 +7303,7 @@ function normalizeSetupAction(input, index) {
     key,
     value,
     value_json: hasJsonValue ? toJsonValue(input.value_json ?? input.valueJson ?? input.json) : void 0,
+    label: stringFromOwn(input, "label", "name", "screenshot_label", "screenshotLabel"),
     path: path7,
     args,
     expect_return: hasExpectedReturn ? toJsonValue(valueFromOwn(input, "expect_return", "expectReturn", "expected_return", "expectedReturn")) : void 0,
@@ -8332,7 +8346,7 @@ function assessRiddleProofProfileEvidence(profile, evidence, options = {}) {
   ].filter((check) => Boolean(check)) : [];
   const status = profileStatusFromEvidence(profile, evidence, checks);
   const firstViewport = evidence?.viewports?.[0];
-  const screenshots = (evidence?.viewports || []).map((viewport) => viewport.screenshot_label).filter((label) => Boolean(label));
+  const screenshots = profileScreenshotLabels(evidence?.viewports);
   return {
     version: RIDDLE_PROOF_PROFILE_RESULT_VERSION,
     profile_name: profile.name,
@@ -8665,12 +8679,26 @@ function profileSetupActionCounts(results) {
   }
   return counts;
 }
+function profileSetupScreenshotLabels(results) {
+  return (results || [])
+    .filter((result) => result && profileSetupResultAction(result) === "screenshot" && result.ok !== false && typeof result.screenshot_label === "string")
+    .map((result) => result.screenshot_label)
+    .filter(Boolean);
+}
 function sampleProfileSetupSummaryItems(items, limit) {
   if ((items || []).length <= limit) return items || [];
   const firstCount = Math.floor(limit / 2);
   const lastCount = limit - firstCount;
   return [...items.slice(0, firstCount), ...items.slice(-lastCount)];
 }
+function profileScreenshotLabels(viewports) {
+  const labels = [];
+  for (const viewport of viewports || []) {
+    if (viewport && viewport.screenshot_label) labels.push(viewport.screenshot_label);
+    labels.push(...profileSetupScreenshotLabels(viewport && viewport.setup_action_results || []));
+  }
+  return labels;
+}
 function profileSetupSummary(viewports, actionCount) {
   return {
     viewport_count: (viewports || []).length,
@@ -8710,6 +8738,7 @@ function profileSetupSummary(viewports, actionCount) {
         action_counts: profileSetupActionCounts(results),
         frame_action_count: results.filter((result) => result && result.frame_selector).length,
         frame_urls: profileSetupFrameUrls(viewport),
+        setup_screenshots: profileSetupScreenshotLabels(results),
         clicked_total: clickedItems.length,
         clicked_truncated: clickedItems.length > clicked.length,
         clicked,
@@ -9199,7 +9228,7 @@ function assessProfile(profile, evidence) {
   else if (expectedViewportCount && viewports.length < expectedViewportCount) status = "proof_insufficient";
   else if (checks.some((check) => check.status === "needs_human_review")) status = "needs_human_review";
   else if (checks.some((check) => check.status === "failed")) status = "product_regression";
-  const screenshotLabels = viewports.map((viewport) => viewport.screenshot_label).filter(Boolean);
+  const screenshotLabels = profileScreenshotLabels(viewports);
   const route = viewports[0] && viewports[0].route ? viewports[0].route : { requested: evidence.target_url, observed: "", matched: false, error: "missing viewport evidence" };
   const passedChecks = checks.filter((check) => check.status === "passed").length;
   const failedChecks = checks.filter((check) => check.status === "failed").length;
@@ -9555,7 +9584,7 @@ async function registerNetworkMocks(mocks) {
     });
   }
 }
-async function executeSetupAction(action, ordinal) {
+async function executeSetupAction(action, ordinal, viewport) {
   const type = setupActionType(action);
   const frameSelector = setupFrameSelector(action);
   const base = { ok: false, action: type || "unknown", ordinal, selector: action.selector || null, frame_selector: frameSelector || null };
@@ -9566,6 +9595,19 @@ async function executeSetupAction(action, ordinal) {
       await page.waitForTimeout(ms);
       return { ...base, ok: true, ms };
     }
+    if (type === "screenshot") {
+      const rawLabel = String(action.label || action.name || action.screenshot_label || action.screenshotLabel || ("setup-" + ordinal));
+      const labelPart = rawLabel
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80) || ("setup-" + ordinal);
+      const viewportName = viewport && viewport.name ? viewport.name : "viewport";
+      const label = profileSlug + "-" + viewportName + "-" + labelPart;
+      if (typeof saveScreenshot !== "function") return { ...base, reason: "save_screenshot_unavailable", label: rawLabel };
+      await saveScreenshot(label);
+      return { ...base, ok: true, label: rawLabel, screenshot_label: label };
+    }
     if (type === "wait_for_selector") {
       const scope = await setupActionScope(action, timeout);
       if (!scope.ok) return setupScopeFailure(base, scope);
@@ -9978,7 +10020,7 @@ async function executeSetupAction(action, ordinal) {
     return { ...base, error: String(error && error.message ? error.message : error).slice(0, 1000) };
   }
 }
-async function executeSetupActions(actions) {
+async function executeSetupActions(actions, viewport) {
   const results = [];
   for (let index = 0; index < (actions || []).length; index += 1) {
     const action = actions[index] || {};
@@ -9986,7 +10028,7 @@ async function executeSetupActions(actions) {
     const repeatCount = Math.min(100, Math.max(1, Math.floor(requestedRepeat || 1)));
     let shouldStop = false;
     for (let repeatIndex = 0; repeatIndex < repeatCount; repeatIndex += 1) {
-      const result = await executeSetupAction(action, index);
+      const result = await executeSetupAction(action, index, viewport);
       results.push(repeatCount > 1
         ? { ...result, repeat_index: repeatIndex, repeat_count: repeatCount }
         : result);
@@ -10461,7 +10503,7 @@ async function captureViewport(viewport) {
     await page.waitForTimeout(profile.target.wait_ms);
   }
   const setupActionResults = (!navigationError && !waitError)
-    ? await executeSetupActions(profile.target.setup_actions || [])
+    ? await executeSetupActions(profile.target.setup_actions || [], viewport)
     : [];
   const dom = await page.evaluate(() => {
     const body = document.body;

package/dist/cli.js

@@ -10,7 +10,7 @@ import {
   profileStatusExitCode,
   resolveRiddleProofProfileTargetUrl,
   resolveRiddleProofProfileTimeoutSec
-} from "./chunk-MLJHMZLR.js";
+} from "./chunk-DQU65Z65.js";
 import {
   createRiddleApiClient,
   parseRiddleViewport

package/dist/index.cjs

@@ -8760,6 +8760,7 @@ var RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES = [
   "local_storage",
   "session_storage",
   "clear_storage",
+  "screenshot",
   "wait",
   "wait_for_selector",
   "wait_for_text",
@@ -8920,12 +8921,23 @@ function profileSetupActionCounts(results) {
   }
   return toJsonValue(counts);
 }
+function profileSetupScreenshotLabels(results) {
+  return results.filter((result) => profileSetupResultAction(result) === "screenshot" && result.ok !== false && typeof result.screenshot_label === "string").map((result) => result.screenshot_label).filter(Boolean);
+}
 function sampleProfileSetupSummaryItems(items, limit) {
   if (items.length <= limit) return items;
   const firstCount = Math.floor(limit / 2);
   const lastCount = limit - firstCount;
   return [...items.slice(0, firstCount), ...items.slice(-lastCount)];
 }
+function profileScreenshotLabels(viewports) {
+  const labels = [];
+  for (const viewport of viewports || []) {
+    if (viewport.screenshot_label) labels.push(viewport.screenshot_label);
+    labels.push(...profileSetupScreenshotLabels(viewport.setup_action_results || []));
+  }
+  return labels;
+}
 function profileSetupSummary(viewports, actionCount) {
   return toJsonValue({
     viewport_count: viewports.length,
@@ -8955,6 +8967,7 @@ function profileSetupSummary(viewports, actionCount) {
         action_counts: profileSetupActionCounts(results),
         frame_action_count: results.filter((result) => result.frame_selector).length,
         frame_urls: profileSetupFrameUrls(viewport),
+        setup_screenshots: profileSetupScreenshotLabels(results),
         clicked_total: clickedItems.length,
         clicked_truncated: clickedItems.length > clicked.length,
         clicked,
@@ -9000,7 +9013,7 @@ function isSupportedCheckType(value) {
 }
 function normalizeSetupActionType(value, index) {
   const normalizedInput = String(value || "").trim().replace(/-/g, "_");
-  const normalized = normalizedInput === "clear_browser_storage" ? "clear_storage" : normalizedInput === "pointer_drag" || normalizedInput === "mouse_drag" || normalizedInput === "drag_to" ? "drag" : normalizedInput === "keyboard_press" || normalizedInput === "key_press" ? "press" : normalizedInput;
+  const normalized = normalizedInput === "clear_browser_storage" ? "clear_storage" : 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;
   if (RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES.includes(normalized)) {
     return normalized;
   }
@@ -9131,6 +9144,7 @@ function normalizeSetupAction(input, index) {
     key,
     value,
     value_json: hasJsonValue ? toJsonValue(input.value_json ?? input.valueJson ?? input.json) : void 0,
+    label: stringFromOwn(input, "label", "name", "screenshot_label", "screenshotLabel"),
     path: path6,
     args,
     expect_return: hasExpectedReturn ? toJsonValue(valueFromOwn(input, "expect_return", "expectReturn", "expected_return", "expectedReturn")) : void 0,
@@ -10173,7 +10187,7 @@ function assessRiddleProofProfileEvidence(profile, evidence, options = {}) {
   ].filter((check) => Boolean(check)) : [];
   const status = profileStatusFromEvidence(profile, evidence, checks);
   const firstViewport = evidence?.viewports?.[0];
-  const screenshots = (evidence?.viewports || []).map((viewport) => viewport.screenshot_label).filter((label) => Boolean(label));
+  const screenshots = profileScreenshotLabels(evidence?.viewports);
   return {
     version: RIDDLE_PROOF_PROFILE_RESULT_VERSION,
     profile_name: profile.name,
@@ -10522,12 +10536,26 @@ function profileSetupActionCounts(results) {
   }
   return counts;
 }
+function profileSetupScreenshotLabels(results) {
+  return (results || [])
+    .filter((result) => result && profileSetupResultAction(result) === "screenshot" && result.ok !== false && typeof result.screenshot_label === "string")
+    .map((result) => result.screenshot_label)
+    .filter(Boolean);
+}
 function sampleProfileSetupSummaryItems(items, limit) {
   if ((items || []).length <= limit) return items || [];
   const firstCount = Math.floor(limit / 2);
   const lastCount = limit - firstCount;
   return [...items.slice(0, firstCount), ...items.slice(-lastCount)];
 }
+function profileScreenshotLabels(viewports) {
+  const labels = [];
+  for (const viewport of viewports || []) {
+    if (viewport && viewport.screenshot_label) labels.push(viewport.screenshot_label);
+    labels.push(...profileSetupScreenshotLabels(viewport && viewport.setup_action_results || []));
+  }
+  return labels;
+}
 function profileSetupSummary(viewports, actionCount) {
   return {
     viewport_count: (viewports || []).length,
@@ -10567,6 +10595,7 @@ function profileSetupSummary(viewports, actionCount) {
         action_counts: profileSetupActionCounts(results),
         frame_action_count: results.filter((result) => result && result.frame_selector).length,
         frame_urls: profileSetupFrameUrls(viewport),
+        setup_screenshots: profileSetupScreenshotLabels(results),
         clicked_total: clickedItems.length,
         clicked_truncated: clickedItems.length > clicked.length,
         clicked,
@@ -11056,7 +11085,7 @@ function assessProfile(profile, evidence) {
   else if (expectedViewportCount && viewports.length < expectedViewportCount) status = "proof_insufficient";
   else if (checks.some((check) => check.status === "needs_human_review")) status = "needs_human_review";
   else if (checks.some((check) => check.status === "failed")) status = "product_regression";
-  const screenshotLabels = viewports.map((viewport) => viewport.screenshot_label).filter(Boolean);
+  const screenshotLabels = profileScreenshotLabels(viewports);
   const route = viewports[0] && viewports[0].route ? viewports[0].route : { requested: evidence.target_url, observed: "", matched: false, error: "missing viewport evidence" };
   const passedChecks = checks.filter((check) => check.status === "passed").length;
   const failedChecks = checks.filter((check) => check.status === "failed").length;
@@ -11412,7 +11441,7 @@ async function registerNetworkMocks(mocks) {
     });
   }
 }
-async function executeSetupAction(action, ordinal) {
+async function executeSetupAction(action, ordinal, viewport) {
   const type = setupActionType(action);
   const frameSelector = setupFrameSelector(action);
   const base = { ok: false, action: type || "unknown", ordinal, selector: action.selector || null, frame_selector: frameSelector || null };
@@ -11423,6 +11452,19 @@ async function executeSetupAction(action, ordinal) {
       await page.waitForTimeout(ms);
       return { ...base, ok: true, ms };
     }
+    if (type === "screenshot") {
+      const rawLabel = String(action.label || action.name || action.screenshot_label || action.screenshotLabel || ("setup-" + ordinal));
+      const labelPart = rawLabel
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80) || ("setup-" + ordinal);
+      const viewportName = viewport && viewport.name ? viewport.name : "viewport";
+      const label = profileSlug + "-" + viewportName + "-" + labelPart;
+      if (typeof saveScreenshot !== "function") return { ...base, reason: "save_screenshot_unavailable", label: rawLabel };
+      await saveScreenshot(label);
+      return { ...base, ok: true, label: rawLabel, screenshot_label: label };
+    }
     if (type === "wait_for_selector") {
       const scope = await setupActionScope(action, timeout);
       if (!scope.ok) return setupScopeFailure(base, scope);
@@ -11835,7 +11877,7 @@ async function executeSetupAction(action, ordinal) {
     return { ...base, error: String(error && error.message ? error.message : error).slice(0, 1000) };
   }
 }
-async function executeSetupActions(actions) {
+async function executeSetupActions(actions, viewport) {
   const results = [];
   for (let index = 0; index < (actions || []).length; index += 1) {
     const action = actions[index] || {};
@@ -11843,7 +11885,7 @@ async function executeSetupActions(actions) {
     const repeatCount = Math.min(100, Math.max(1, Math.floor(requestedRepeat || 1)));
     let shouldStop = false;
     for (let repeatIndex = 0; repeatIndex < repeatCount; repeatIndex += 1) {
-      const result = await executeSetupAction(action, index);
+      const result = await executeSetupAction(action, index, viewport);
       results.push(repeatCount > 1
         ? { ...result, repeat_index: repeatIndex, repeat_count: repeatCount }
         : result);
@@ -12318,7 +12360,7 @@ async function captureViewport(viewport) {
     await page.waitForTimeout(profile.target.wait_ms);
   }
   const setupActionResults = (!navigationError && !waitError)
-    ? await executeSetupActions(profile.target.setup_actions || [])
+    ? await executeSetupActions(profile.target.setup_actions || [], viewport)
     : [];
   const dom = await page.evaluate(() => {
     const body = document.body;

package/dist/index.js

@@ -58,7 +58,7 @@ import {
   resolveRiddleProofProfileTimeoutSec,
   slugifyRiddleProofProfileName,
   summarizeRiddleProofProfileResult
-} from "./chunk-MLJHMZLR.js";
+} from "./chunk-DQU65Z65.js";
 import {
   DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE,

package/dist/profile.cjs

@@ -89,6 +89,7 @@ var RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES = [
   "local_storage",
   "session_storage",
   "clear_storage",
+  "screenshot",
   "wait",
   "wait_for_selector",
   "wait_for_text",
@@ -249,12 +250,23 @@ function profileSetupActionCounts(results) {
   }
   return toJsonValue(counts);
 }
+function profileSetupScreenshotLabels(results) {
+  return results.filter((result) => profileSetupResultAction(result) === "screenshot" && result.ok !== false && typeof result.screenshot_label === "string").map((result) => result.screenshot_label).filter(Boolean);
+}
 function sampleProfileSetupSummaryItems(items, limit) {
   if (items.length <= limit) return items;
   const firstCount = Math.floor(limit / 2);
   const lastCount = limit - firstCount;
   return [...items.slice(0, firstCount), ...items.slice(-lastCount)];
 }
+function profileScreenshotLabels(viewports) {
+  const labels = [];
+  for (const viewport of viewports || []) {
+    if (viewport.screenshot_label) labels.push(viewport.screenshot_label);
+    labels.push(...profileSetupScreenshotLabels(viewport.setup_action_results || []));
+  }
+  return labels;
+}
 function profileSetupSummary(viewports, actionCount) {
   return toJsonValue({
     viewport_count: viewports.length,
@@ -284,6 +296,7 @@ function profileSetupSummary(viewports, actionCount) {
         action_counts: profileSetupActionCounts(results),
         frame_action_count: results.filter((result) => result.frame_selector).length,
         frame_urls: profileSetupFrameUrls(viewport),
+        setup_screenshots: profileSetupScreenshotLabels(results),
         clicked_total: clickedItems.length,
         clicked_truncated: clickedItems.length > clicked.length,
         clicked,
@@ -329,7 +342,7 @@ function isSupportedCheckType(value) {
 }
 function normalizeSetupActionType(value, index) {
   const normalizedInput = String(value || "").trim().replace(/-/g, "_");
-  const normalized = normalizedInput === "clear_browser_storage" ? "clear_storage" : normalizedInput === "pointer_drag" || normalizedInput === "mouse_drag" || normalizedInput === "drag_to" ? "drag" : normalizedInput === "keyboard_press" || normalizedInput === "key_press" ? "press" : normalizedInput;
+  const normalized = normalizedInput === "clear_browser_storage" ? "clear_storage" : 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;
   if (RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES.includes(normalized)) {
     return normalized;
   }
@@ -460,6 +473,7 @@ function normalizeSetupAction(input, index) {
     key,
     value,
     value_json: hasJsonValue ? toJsonValue(input.value_json ?? input.valueJson ?? input.json) : void 0,
+    label: stringFromOwn(input, "label", "name", "screenshot_label", "screenshotLabel"),
     path,
     args,
     expect_return: hasExpectedReturn ? toJsonValue(valueFromOwn(input, "expect_return", "expectReturn", "expected_return", "expectedReturn")) : void 0,
@@ -1502,7 +1516,7 @@ function assessRiddleProofProfileEvidence(profile, evidence, options = {}) {
   ].filter((check) => Boolean(check)) : [];
   const status = profileStatusFromEvidence(profile, evidence, checks);
   const firstViewport = evidence?.viewports?.[0];
-  const screenshots = (evidence?.viewports || []).map((viewport) => viewport.screenshot_label).filter((label) => Boolean(label));
+  const screenshots = profileScreenshotLabels(evidence?.viewports);
   return {
     version: RIDDLE_PROOF_PROFILE_RESULT_VERSION,
     profile_name: profile.name,
@@ -1851,12 +1865,26 @@ function profileSetupActionCounts(results) {
   }
   return counts;
 }
+function profileSetupScreenshotLabels(results) {
+  return (results || [])
+    .filter((result) => result && profileSetupResultAction(result) === "screenshot" && result.ok !== false && typeof result.screenshot_label === "string")
+    .map((result) => result.screenshot_label)
+    .filter(Boolean);
+}
 function sampleProfileSetupSummaryItems(items, limit) {
   if ((items || []).length <= limit) return items || [];
   const firstCount = Math.floor(limit / 2);
   const lastCount = limit - firstCount;
   return [...items.slice(0, firstCount), ...items.slice(-lastCount)];
 }
+function profileScreenshotLabels(viewports) {
+  const labels = [];
+  for (const viewport of viewports || []) {
+    if (viewport && viewport.screenshot_label) labels.push(viewport.screenshot_label);
+    labels.push(...profileSetupScreenshotLabels(viewport && viewport.setup_action_results || []));
+  }
+  return labels;
+}
 function profileSetupSummary(viewports, actionCount) {
   return {
     viewport_count: (viewports || []).length,
@@ -1896,6 +1924,7 @@ function profileSetupSummary(viewports, actionCount) {
         action_counts: profileSetupActionCounts(results),
         frame_action_count: results.filter((result) => result && result.frame_selector).length,
         frame_urls: profileSetupFrameUrls(viewport),
+        setup_screenshots: profileSetupScreenshotLabels(results),
         clicked_total: clickedItems.length,
         clicked_truncated: clickedItems.length > clicked.length,
         clicked,
@@ -2385,7 +2414,7 @@ function assessProfile(profile, evidence) {
   else if (expectedViewportCount && viewports.length < expectedViewportCount) status = "proof_insufficient";
   else if (checks.some((check) => check.status === "needs_human_review")) status = "needs_human_review";
   else if (checks.some((check) => check.status === "failed")) status = "product_regression";
-  const screenshotLabels = viewports.map((viewport) => viewport.screenshot_label).filter(Boolean);
+  const screenshotLabels = profileScreenshotLabels(viewports);
   const route = viewports[0] && viewports[0].route ? viewports[0].route : { requested: evidence.target_url, observed: "", matched: false, error: "missing viewport evidence" };
   const passedChecks = checks.filter((check) => check.status === "passed").length;
   const failedChecks = checks.filter((check) => check.status === "failed").length;
@@ -2741,7 +2770,7 @@ async function registerNetworkMocks(mocks) {
     });
   }
 }
-async function executeSetupAction(action, ordinal) {
+async function executeSetupAction(action, ordinal, viewport) {
   const type = setupActionType(action);
   const frameSelector = setupFrameSelector(action);
   const base = { ok: false, action: type || "unknown", ordinal, selector: action.selector || null, frame_selector: frameSelector || null };
@@ -2752,6 +2781,19 @@ async function executeSetupAction(action, ordinal) {
       await page.waitForTimeout(ms);
       return { ...base, ok: true, ms };
     }
+    if (type === "screenshot") {
+      const rawLabel = String(action.label || action.name || action.screenshot_label || action.screenshotLabel || ("setup-" + ordinal));
+      const labelPart = rawLabel
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80) || ("setup-" + ordinal);
+      const viewportName = viewport && viewport.name ? viewport.name : "viewport";
+      const label = profileSlug + "-" + viewportName + "-" + labelPart;
+      if (typeof saveScreenshot !== "function") return { ...base, reason: "save_screenshot_unavailable", label: rawLabel };
+      await saveScreenshot(label);
+      return { ...base, ok: true, label: rawLabel, screenshot_label: label };
+    }
     if (type === "wait_for_selector") {
       const scope = await setupActionScope(action, timeout);
       if (!scope.ok) return setupScopeFailure(base, scope);
@@ -3164,7 +3206,7 @@ async function executeSetupAction(action, ordinal) {
     return { ...base, error: String(error && error.message ? error.message : error).slice(0, 1000) };
   }
 }
-async function executeSetupActions(actions) {
+async function executeSetupActions(actions, viewport) {
   const results = [];
   for (let index = 0; index < (actions || []).length; index += 1) {
     const action = actions[index] || {};
@@ -3172,7 +3214,7 @@ async function executeSetupActions(actions) {
     const repeatCount = Math.min(100, Math.max(1, Math.floor(requestedRepeat || 1)));
     let shouldStop = false;
     for (let repeatIndex = 0; repeatIndex < repeatCount; repeatIndex += 1) {
-      const result = await executeSetupAction(action, index);
+      const result = await executeSetupAction(action, index, viewport);
       results.push(repeatCount > 1
         ? { ...result, repeat_index: repeatIndex, repeat_count: repeatCount }
         : result);
@@ -3647,7 +3689,7 @@ async function captureViewport(viewport) {
     await page.waitForTimeout(profile.target.wait_ms);
   }
   const setupActionResults = (!navigationError && !waitError)
-    ? await executeSetupActions(profile.target.setup_actions || [])
+    ? await executeSetupActions(profile.target.setup_actions || [], viewport)
     : [];
   const dom = await page.evaluate(() => {
     const body = document.body;

package/dist/profile.d.cts

@@ -5,7 +5,7 @@ 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", "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", "selector_text_order", "frame_text_visible", "frame_url_equals", "frame_url_matches", "frame_no_horizontal_overflow", "text_visible", "text_absent", "route_inventory", "no_horizontal_overflow", "no_mobile_horizontal_overflow", "no_fatal_console_errors"];
-declare const RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES: readonly ["click", "drag", "press", "fill", "set_input_value", "assert_text_visible", "assert_text_absent", "assert_selector_count", "assert_window_value", "assert_window_number", "local_storage", "session_storage", "clear_storage", "wait", "wait_for_selector", "wait_for_text", "window_call"];
+declare const RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES: readonly ["click", "drag", "press", "fill", "set_input_value", "assert_text_visible", "assert_text_absent", "assert_selector_count", "assert_window_value", "assert_window_number", "local_storage", "session_storage", "clear_storage", "screenshot", "wait", "wait_for_selector", "wait_for_text", "window_call"];
 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];
@@ -33,6 +33,7 @@ interface RiddleProofProfileSetupAction {
     key?: string;
     value?: string;
     value_json?: JsonValue;
+    label?: string;
     path?: string;
     args?: JsonValue[];
     expect_return?: JsonValue;

package/dist/profile.d.ts

@@ -5,7 +5,7 @@ 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", "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", "selector_text_order", "frame_text_visible", "frame_url_equals", "frame_url_matches", "frame_no_horizontal_overflow", "text_visible", "text_absent", "route_inventory", "no_horizontal_overflow", "no_mobile_horizontal_overflow", "no_fatal_console_errors"];
-declare const RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES: readonly ["click", "drag", "press", "fill", "set_input_value", "assert_text_visible", "assert_text_absent", "assert_selector_count", "assert_window_value", "assert_window_number", "local_storage", "session_storage", "clear_storage", "wait", "wait_for_selector", "wait_for_text", "window_call"];
+declare const RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES: readonly ["click", "drag", "press", "fill", "set_input_value", "assert_text_visible", "assert_text_absent", "assert_selector_count", "assert_window_value", "assert_window_number", "local_storage", "session_storage", "clear_storage", "screenshot", "wait", "wait_for_selector", "wait_for_text", "window_call"];
 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];
@@ -33,6 +33,7 @@ interface RiddleProofProfileSetupAction {
     key?: string;
     value?: string;
     value_json?: JsonValue;
+    label?: string;
     path?: string;
     args?: JsonValue[];
     expect_return?: JsonValue;

package/dist/profile.js

@@ -19,7 +19,7 @@ import {
   resolveRiddleProofProfileTimeoutSec,
   slugifyRiddleProofProfileName,
   summarizeRiddleProofProfileResult
-} from "./chunk-MLJHMZLR.js";
+} from "./chunk-DQU65Z65.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.63",
+  "version": "0.7.65",
   "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
   "license": "MIT",
   "author": "RiddleDC",