@riddledc/riddle-proof 0.7.63 → 0.7.64

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-ZVKKBM2J.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;
@@ -2709,6 +2738,18 @@ 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 label = profileSlug + "-" + viewport.name + "-" + 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);

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;
@@ -9566,6 +9595,18 @@ 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 label = profileSlug + "-" + viewport.name + "-" + 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);

package/dist/cli.js

@@ -10,7 +10,7 @@ import {
   profileStatusExitCode,
   resolveRiddleProofProfileTargetUrl,
   resolveRiddleProofProfileTimeoutSec
-} from "./chunk-MLJHMZLR.js";
+} from "./chunk-ZVKKBM2J.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;
@@ -11423,6 +11452,18 @@ 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 label = profileSlug + "-" + viewport.name + "-" + 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);

package/dist/index.js

@@ -58,7 +58,7 @@ import {
   resolveRiddleProofProfileTimeoutSec,
   slugifyRiddleProofProfileName,
   summarizeRiddleProofProfileResult
-} from "./chunk-MLJHMZLR.js";
+} from "./chunk-ZVKKBM2J.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;
@@ -2752,6 +2781,18 @@ 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 label = profileSlug + "-" + viewport.name + "-" + 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);

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-ZVKKBM2J.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.64",
   "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
   "license": "MIT",
   "author": "RiddleDC",