@riddledc/riddle-proof 0.7.8 → 0.7.10

package/README.md

@@ -108,7 +108,11 @@ or as a stronger proof base before a change loop.
       { "name": "mobile", "width": 390, "height": 844 },
       { "name": "desktop", "width": 1440, "height": 1000 }
     ],
-    "auth": "none"
+    "auth": "none",
+    "setup_actions": [
+      { "type": "click", "selector": "[data-testid='show-plans']" },
+      { "type": "wait_for_text", "selector": "body", "text": "Start building" }
+    ]
   },
   "checks": [
     { "type": "route_loaded", "expected_path": "/pricing" },
@@ -141,6 +145,15 @@ The package includes a generic starter profile at
 profile directory and replace the selector/text checks with app-specific
 invariants.
 
+`target.setup_actions` is optional. Use it when the meaningful proof surface
+appears only after a picker, tab, login stub, transport control, or other
+bounded interaction. Supported setup actions are `click`, `wait`,
+`wait_for_selector`, and `wait_for_text`; a failed setup action is recorded as
+a failed `setup_actions_succeeded` check so the profile cannot pass without
+reaching the intended state. Text-matched `click` actions prefer visible
+matching elements, which keeps responsive layouts from selecting hidden desktop
+or mobile-only links.
+
 The result uses `riddle-proof.profile-result.v1` and separates product failures
 from weak proof and environment blockers:
 

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

@@ -20,6 +20,12 @@ var RIDDLE_PROOF_PROFILE_CHECK_TYPES = [
   "no_mobile_horizontal_overflow",
   "no_fatal_console_errors"
 ];
+var RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES = [
+  "click",
+  "wait",
+  "wait_for_selector",
+  "wait_for_text"
+];
 var DEFAULT_VIEWPORTS = [
   { name: "desktop", width: 1280, height: 800 }
 ];
@@ -72,6 +78,41 @@ function normalizeViewports(value) {
 function isSupportedCheckType(value) {
   return RIDDLE_PROOF_PROFILE_CHECK_TYPES.includes(value);
 }
+function normalizeSetupActionType(value, index) {
+  const normalized = String(value || "").trim().replace(/-/g, "_");
+  if (RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES.includes(normalized)) {
+    return normalized;
+  }
+  throw new Error(`target.setup_actions[${index}].type ${value || "(missing)"} is not supported. Supported actions: ${RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES.join(", ")}`);
+}
+function normalizeSetupAction(input, index) {
+  if (!isRecord(input)) throw new Error(`target.setup_actions[${index}] must be an object.`);
+  const type = normalizeSetupActionType(stringValue(input.type), index);
+  const selector = stringValue(input.selector);
+  if ((type === "click" || type === "wait_for_selector" || type === "wait_for_text") && !selector) {
+    throw new Error(`target.setup_actions[${index}] ${type} requires selector.`);
+  }
+  if (type === "wait_for_text" && !stringValue(input.text) && !stringValue(input.pattern)) {
+    throw new Error(`target.setup_actions[${index}] wait_for_text requires text or pattern.`);
+  }
+  return {
+    type,
+    selector,
+    text: stringValue(input.text),
+    pattern: stringValue(input.pattern),
+    flags: stringValue(input.flags),
+    index: numberValue(input.index),
+    ms: numberValue(input.ms) ?? numberValue(input.wait_ms) ?? numberValue(input.waitMs),
+    timeout_ms: numberValue(input.timeout_ms) ?? numberValue(input.timeoutMs),
+    after_ms: numberValue(input.after_ms) ?? numberValue(input.afterMs),
+    continue_on_failure: input.continue_on_failure === true || input.continueOnFailure === true
+  };
+}
+function normalizeSetupActions(value) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value)) throw new Error("target.setup_actions must be an array.");
+  return value.map(normalizeSetupAction);
+}
 function normalizeCheck(input, index) {
   if (!isRecord(input)) throw new Error(`checks[${index}] must be an object.`);
   const type = stringValue(input.type);
@@ -139,7 +180,8 @@ function normalizeRiddleProofProfile(input, options = {}) {
       viewports: options.viewports?.length ? options.viewports : normalizeViewports(targetInput.viewports),
       auth: stringValue(targetInput.auth) || "none",
       wait_for_selector: stringValue(targetInput.wait_for_selector) || stringValue(targetInput.waitForSelector),
-      wait_ms: numberValue(targetInput.wait_ms) ?? numberValue(targetInput.waitMs)
+      wait_ms: numberValue(targetInput.wait_ms) ?? numberValue(targetInput.waitMs),
+      setup_actions: normalizeSetupActions(targetInput.setup_actions ?? targetInput.setupActions)
     },
     checks,
     artifacts: Array.isArray(input.artifacts) ? input.artifacts.map((item) => String(item)).filter(Boolean) : ["screenshot", "console", "dom_summary", "proof_json"],
@@ -157,7 +199,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,
@@ -183,8 +231,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 || [];
@@ -202,7 +259,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,
@@ -312,6 +369,48 @@ function assessCheckFromEvidence(check, evidence) {
     message: "Unsupported check type."
   };
 }
+function assessSetupActionsFromEvidence(profile, evidence) {
+  if (!profile.target.setup_actions?.length) return void 0;
+  const actionCount = profile.target.setup_actions.length;
+  const failed = [];
+  const viewports = evidence.viewports || [];
+  for (const viewport of viewports) {
+    const results = viewport.setup_action_results || [];
+    for (const result of results) {
+      if (result.ok === false) {
+        failed.push({
+          viewport: viewport.name,
+          action: result.action ?? result.type ?? null,
+          selector: result.selector ?? null,
+          reason: result.reason ?? result.error ?? null
+        });
+      }
+    }
+    if (results.length < actionCount && results.every((result) => result.ok !== false)) {
+      failed.push({
+        viewport: viewport.name,
+        action: "setup_actions",
+        selector: null,
+        reason: `missing setup action results: ${results.length}/${actionCount}`
+      });
+    }
+  }
+  return {
+    type: "setup_actions_succeeded",
+    label: "setup actions succeeded",
+    status: failed.length ? "failed" : "passed",
+    evidence: {
+      action_count: actionCount,
+      viewports: viewports.map((viewport) => ({
+        name: viewport.name,
+        ok: (viewport.setup_action_results || []).length >= actionCount && (viewport.setup_action_results || []).every((result) => result.ok !== false),
+        result_count: (viewport.setup_action_results || []).length
+      })),
+      failed
+    },
+    message: failed.length ? `Setup actions failed in ${failed.length} viewport action(s).` : void 0
+  };
+}
 function profileStatusFromEvidence(evidence, checks) {
   if (!evidence) return "proof_insufficient";
   const viewports = evidence.viewports || [];
@@ -323,7 +422,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));
@@ -425,8 +527,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) {
@@ -437,12 +547,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({
@@ -599,6 +750,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 || "/";
 }
@@ -633,6 +883,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;
@@ -682,7 +935,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,
     },
@@ -694,6 +947,7 @@ async function captureViewport(viewport) {
     overflow_px: Math.max(0, (dom.scroll_width || 0) - (dom.client_width || viewport.width)),
     selectors,
     text_matches,
+    setup_action_results: setupActionResults,
     screenshot_label: screenshotLabel,
     navigation_error: navigationError,
     wait_error: waitError,
@@ -793,6 +1047,7 @@ export {
   RIDDLE_PROOF_PROFILE_RESULT_VERSION,
   RIDDLE_PROOF_PROFILE_STATUSES,
   RIDDLE_PROOF_PROFILE_CHECK_TYPES,
+  RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES,
   slugifyRiddleProofProfileName,
   normalizeRiddleProofProfile,
   resolveRiddleProofProfileTargetUrl,