@riddledc/riddle-proof 0.5.41 → 0.5.43

package/dist/{chunk-4YCWZVBN.js → chunk-U4VNN2CT.js}

@@ -371,7 +371,8 @@ function visualDeltaShipGateReason(state = {}) {
   if (visualDelta.status === "measured" && visualDelta.passed === true) return null;
   const status = String(visualDelta.status || "missing");
   if (status === "unmeasured") {
-    return "visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof";
+    const reason2 = String(visualDelta.reason || "").trim();
+    return reason2 ? `visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof: ${reason2}` : "visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof";
   }
   if (status === "measured" && visualDelta.passed === false) {
     return "visual_delta.status=measured but visual_delta.passed=false blocks ready_to_ship for visual/UI proof";

package/dist/{chunk-ZBM67XGB.js → chunk-VSLU6XNI.js}

@@ -26,7 +26,7 @@ import {
 } from "./chunk-W7VTDN4T.js";
 import {
   visualDeltaShipGateReason
-} from "./chunk-4YCWZVBN.js";
+} from "./chunk-U4VNN2CT.js";
 
 // src/engine-harness.ts
 import { execFileSync } from "child_process";

package/dist/{chunk-DWQK7J4U.js → chunk-XNRMMQAY.js}

@@ -96,14 +96,16 @@ function summarizeCaptureArtifacts(payload) {
   const record = isRecord(payload) ? payload : {};
   const artifactJson = isRecord(record._artifact_json) ? record._artifact_json : {};
   const proofJson = isRecord(record._proof_json) ? record._proof_json : isRecord(artifactJson["proof.json"]) ? artifactJson["proof.json"] : {};
+  const visualDiffJson = isRecord(record.visual_diff) ? record.visual_diff : isRecord(record.visualDiff) ? record.visualDiff : isRecord(artifactJson["visual-diff.json"]) ? artifactJson["visual-diff.json"] : {};
   const consoleJson = isRecord(record.console) ? record.console : isRecord(artifactJson["console.json"]) ? artifactJson["console.json"] : {};
   const result = isRecord(record.result) ? record.result : isRecord(proofJson.result) ? proofJson.result : isRecord(proofJson.script_result) ? proofJson.script_result : isRecord(proofJson.return_value) ? proofJson.return_value : isRecord(proofJson.value) ? proofJson.value : {};
   const consoleSummary = isRecord(consoleJson.summary) ? redactForProofDiagnostics(consoleJson.summary, { string_limit: 500 }) : void 0;
+  const resultKeys = /* @__PURE__ */ new Set([...sortedKeys(result), ...sortedKeys(visualDiffJson)]);
   return {
     outputs: artifactItems(record.outputs).slice(0, 20).map((item) => artifactSummary(item, "outputs")),
     screenshots: artifactItems(record.screenshots).slice(0, 10).map((item) => artifactSummary(item, "screenshots")),
     artifacts: artifactItems(record.artifacts).slice(0, 20).map((item) => artifactSummary(item, "artifacts")),
-    result_keys: sortedKeys(result),
+    result_keys: Array.from(resultKeys).sort(),
     artifact_json: sortedKeys(artifactJson),
     artifact_errors: artifactErrorMap(record._artifact_errors),
     proof_script_error: Boolean(proofJson.script_error),

package/dist/diagnostics.cjs

@@ -127,14 +127,16 @@ function summarizeCaptureArtifacts(payload) {
   const record = isRecord(payload) ? payload : {};
   const artifactJson = isRecord(record._artifact_json) ? record._artifact_json : {};
   const proofJson = isRecord(record._proof_json) ? record._proof_json : isRecord(artifactJson["proof.json"]) ? artifactJson["proof.json"] : {};
+  const visualDiffJson = isRecord(record.visual_diff) ? record.visual_diff : isRecord(record.visualDiff) ? record.visualDiff : isRecord(artifactJson["visual-diff.json"]) ? artifactJson["visual-diff.json"] : {};
   const consoleJson = isRecord(record.console) ? record.console : isRecord(artifactJson["console.json"]) ? artifactJson["console.json"] : {};
   const result = isRecord(record.result) ? record.result : isRecord(proofJson.result) ? proofJson.result : isRecord(proofJson.script_result) ? proofJson.script_result : isRecord(proofJson.return_value) ? proofJson.return_value : isRecord(proofJson.value) ? proofJson.value : {};
   const consoleSummary = isRecord(consoleJson.summary) ? redactForProofDiagnostics(consoleJson.summary, { string_limit: 500 }) : void 0;
+  const resultKeys = /* @__PURE__ */ new Set([...sortedKeys(result), ...sortedKeys(visualDiffJson)]);
   return {
     outputs: artifactItems(record.outputs).slice(0, 20).map((item) => artifactSummary(item, "outputs")),
     screenshots: artifactItems(record.screenshots).slice(0, 10).map((item) => artifactSummary(item, "screenshots")),
     artifacts: artifactItems(record.artifacts).slice(0, 20).map((item) => artifactSummary(item, "artifacts")),
-    result_keys: sortedKeys(result),
+    result_keys: Array.from(resultKeys).sort(),
     artifact_json: sortedKeys(artifactJson),
     artifact_errors: artifactErrorMap(record._artifact_errors),
     proof_script_error: Boolean(proofJson.script_error),

package/dist/diagnostics.js

@@ -7,7 +7,7 @@ import {
   createCaptureDiagnostic,
   redactForProofDiagnostics,
   summarizeCaptureArtifacts
-} from "./chunk-DWQK7J4U.js";
+} from "./chunk-XNRMMQAY.js";
 export {
   DEFAULT_DIAGNOSTIC_ARRAY_LIMIT,
   DEFAULT_DIAGNOSTIC_HISTORY_LIMIT,

package/dist/engine-harness.cjs

@@ -379,7 +379,8 @@ function visualDeltaShipGateReason(state = {}) {
   if (visualDelta.status === "measured" && visualDelta.passed === true) return null;
   const status = String(visualDelta.status || "missing");
   if (status === "unmeasured") {
-    return "visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof";
+    const reason2 = String(visualDelta.reason || "").trim();
+    return reason2 ? `visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof: ${reason2}` : "visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof";
   }
   if (status === "measured" && visualDelta.passed === false) {
     return "visual_delta.status=measured but visual_delta.passed=false blocks ready_to_ship for visual/UI proof";

package/dist/engine-harness.js

@@ -2,11 +2,11 @@ import {
   createDisabledRiddleProofAgentAdapter,
   readRiddleProofRunStatus,
   runRiddleProofEngineHarness
-} from "./chunk-ZBM67XGB.js";
+} from "./chunk-VSLU6XNI.js";
 import "./chunk-RI25RGQP.js";
 import "./chunk-7S7O3NKF.js";
 import "./chunk-W7VTDN4T.js";
-import "./chunk-4YCWZVBN.js";
+import "./chunk-U4VNN2CT.js";
 export {
   createDisabledRiddleProofAgentAdapter,
   readRiddleProofRunStatus,

package/dist/index.cjs

@@ -379,7 +379,8 @@ function visualDeltaShipGateReason(state = {}) {
   if (visualDelta.status === "measured" && visualDelta.passed === true) return null;
   const status = String(visualDelta.status || "missing");
   if (status === "unmeasured") {
-    return "visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof";
+    const reason2 = String(visualDelta.reason || "").trim();
+    return reason2 ? `visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof: ${reason2}` : "visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof";
   }
   if (status === "measured" && visualDelta.passed === false) {
     return "visual_delta.status=measured but visual_delta.passed=false blocks ready_to_ship for visual/UI proof";
@@ -5171,14 +5172,16 @@ function summarizeCaptureArtifacts(payload) {
   const record = isRecord(payload) ? payload : {};
   const artifactJson = isRecord(record._artifact_json) ? record._artifact_json : {};
   const proofJson = isRecord(record._proof_json) ? record._proof_json : isRecord(artifactJson["proof.json"]) ? artifactJson["proof.json"] : {};
+  const visualDiffJson = isRecord(record.visual_diff) ? record.visual_diff : isRecord(record.visualDiff) ? record.visualDiff : isRecord(artifactJson["visual-diff.json"]) ? artifactJson["visual-diff.json"] : {};
   const consoleJson = isRecord(record.console) ? record.console : isRecord(artifactJson["console.json"]) ? artifactJson["console.json"] : {};
   const result = isRecord(record.result) ? record.result : isRecord(proofJson.result) ? proofJson.result : isRecord(proofJson.script_result) ? proofJson.script_result : isRecord(proofJson.return_value) ? proofJson.return_value : isRecord(proofJson.value) ? proofJson.value : {};
   const consoleSummary = isRecord(consoleJson.summary) ? redactForProofDiagnostics(consoleJson.summary, { string_limit: 500 }) : void 0;
+  const resultKeys = /* @__PURE__ */ new Set([...sortedKeys(result), ...sortedKeys(visualDiffJson)]);
   return {
     outputs: artifactItems(record.outputs).slice(0, 20).map((item) => artifactSummary(item, "outputs")),
     screenshots: artifactItems(record.screenshots).slice(0, 10).map((item) => artifactSummary(item, "screenshots")),
     artifacts: artifactItems(record.artifacts).slice(0, 20).map((item) => artifactSummary(item, "artifacts")),
-    result_keys: sortedKeys(result),
+    result_keys: Array.from(resultKeys).sort(),
     artifact_json: sortedKeys(artifactJson),
     artifact_errors: artifactErrorMap(record._artifact_errors),
     proof_script_error: Boolean(proofJson.script_error),

package/dist/index.js

@@ -20,12 +20,12 @@ import {
   createCaptureDiagnostic,
   redactForProofDiagnostics,
   summarizeCaptureArtifacts
-} from "./chunk-DWQK7J4U.js";
+} from "./chunk-XNRMMQAY.js";
 import {
   createDisabledRiddleProofAgentAdapter,
   readRiddleProofRunStatus,
   runRiddleProofEngineHarness
-} from "./chunk-ZBM67XGB.js";
+} from "./chunk-VSLU6XNI.js";
 import {
   RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
   RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
@@ -67,7 +67,7 @@ import {
   extractPlayabilityEvidence,
   isRiddleProofPlayabilityMode
 } from "./chunk-NSWT3VSV.js";
-import "./chunk-4YCWZVBN.js";
+import "./chunk-U4VNN2CT.js";
 export {
   DEFAULT_DIAGNOSTIC_ARRAY_LIMIT,
   DEFAULT_DIAGNOSTIC_HISTORY_LIMIT,

package/dist/proof-run-core.cjs

@@ -430,7 +430,8 @@ function visualDeltaShipGateReason(state = {}) {
   if (visualDelta.status === "measured" && visualDelta.passed === true) return null;
   const status = String(visualDelta.status || "missing");
   if (status === "unmeasured") {
-    return "visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof";
+    const reason2 = String(visualDelta.reason || "").trim();
+    return reason2 ? `visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof: ${reason2}` : "visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof";
   }
   if (status === "measured" && visualDelta.passed === false) {
     return "visual_delta.status=measured but visual_delta.passed=false blocks ready_to_ship for visual/UI proof";

package/dist/proof-run-core.js

@@ -24,7 +24,7 @@ import {
   visualDeltaShipGateReason,
   workflowFile,
   writeState
-} from "./chunk-4YCWZVBN.js";
+} from "./chunk-U4VNN2CT.js";
 export {
   BUNDLED_RIDDLE_PROOF_DIR,
   CHECKPOINT_CONTRACT_VERSION,

package/dist/proof-run-engine.cjs

@@ -412,7 +412,8 @@ function visualDeltaShipGateReason(state = {}) {
   if (visualDelta.status === "measured" && visualDelta.passed === true) return null;
   const status = String(visualDelta.status || "missing");
   if (status === "unmeasured") {
-    return "visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof";
+    const reason2 = String(visualDelta.reason || "").trim();
+    return reason2 ? `visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof: ${reason2}` : "visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof";
   }
   if (status === "measured" && visualDelta.passed === false) {
     return "visual_delta.status=measured but visual_delta.passed=false blocks ready_to_ship for visual/UI proof";

package/dist/proof-run-engine.js

@@ -14,7 +14,7 @@ import {
   validateShipGate,
   workflowFile,
   writeState
-} from "./chunk-4YCWZVBN.js";
+} from "./chunk-U4VNN2CT.js";
 
 // src/proof-run-engine.ts
 import { execFileSync } from "child_process";

package/package.json

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

package/runtime/lib/author.py

@@ -154,6 +154,7 @@ def author_request_payload(state, reference, baselines, current_plan, hypothesis
             'For playable/gameplay proof, start the experience, send keyboard or pointer input, sample state before/after, measure non-HUD playfield/canvas pixel deltas across time, and set window.__riddleProofEvidence.playability or playability_evidence with version riddle-proof.playability.v1.',
             'For data/audio/log/metric/custom proof, screenshots are optional; set window.__riddleProofEvidence inside page.evaluate to a JSON-serializable object with the measured observations the verifier should judge.',
             'Do not assign globalThis.__riddleProofEvidence, window.__riddleProofEvidence, or self.__riddleProofEvidence outside page.evaluate; the Riddle worker context may not expose those globals safely.',
+            'When page.evaluate needs data from the outer Playwright script, pass exactly one serializable argument object; do not pass multiple positional arguments.',
             'Do not begin capture_script with page.goto unless an in-app navigation is genuinely required after the preview opens the target route.',
             'Only escalate to the human after the supervising agent concludes the workflow is genuinely stuck or not converging.',
         ],

package/runtime/lib/recon.py

@@ -33,6 +33,7 @@ import subprocess as sp
 MAX_RECON_ATTEMPTS = 4
 MIN_BODY_TEXT_LENGTH = 50
 MIN_INTERACTIVE_ELEMENTS = 1
+MIN_CANVAS_AREA = 50000
 HYDRATION_WAIT_MS = 1500
 PAGE_STATE_PREFIX = 'RIDDLE_PROOF_STATE:'
 PROOF_EVIDENCE_PREFIX = 'RIDDLE_PROOF_EVIDENCE:'
@@ -423,6 +424,45 @@ def has_enriched_page_state(page_state):
     )
 
 
+def numeric_value(value):
+    if isinstance(value, bool) or value is None:
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        text = value.strip().rstrip('%').replace(',', '')
+        if not text:
+            return None
+        try:
+            return float(text)
+        except Exception:
+            return None
+    return None
+
+
+def canvas_capture_signal(page_state):
+    if not isinstance(page_state, dict):
+        return {
+            'canvas_ready': False,
+            'canvas_count': 0,
+            'large_canvas_area': 0,
+        }
+    large_canvas_area = 0
+    for item in list_value(page_state.get('largeVisibleElements')):
+        if not isinstance(item, dict) or item.get('tag') != 'canvas':
+            continue
+        area = numeric_value(item.get('area')) or 0
+        if area > large_canvas_area:
+            large_canvas_area = area
+    canvas_count = int(numeric_value(page_state.get('canvasCount')) or 0)
+    return {
+        'canvas_ready': bool(canvas_count > 0 and large_canvas_area >= MIN_CANVAS_AREA),
+        'canvas_count': canvas_count,
+        'large_canvas_area': int(large_canvas_area),
+        'min_canvas_area': MIN_CANVAS_AREA,
+    }
+
+
 def normalize_observed_path(value):
     raw = str(value or '').strip()
     if not raw:
@@ -538,6 +578,9 @@ def evaluate_capture_quality(payload, expected_path):
         'buttons': [],
         'links': [],
         'canvas_count': 0,
+        'canvas_capture_ready': False,
+        'large_canvas_area': 0,
+        'min_canvas_area': MIN_CANVAS_AREA,
         'large_visible_elements': [],
         'semantic_anchor_count': 0,
         'capture_error_messages': [],
@@ -572,6 +615,12 @@ def evaluate_capture_quality(payload, expected_path):
             'large_visible_elements': list_value(page_state.get('largeVisibleElements'))[:10],
             'semantic_anchor_count': semantic_anchor_count(page_state),
         })
+        canvas_signal = canvas_capture_signal(page_state)
+        details.update({
+            'canvas_capture_ready': canvas_signal['canvas_ready'],
+            'large_canvas_area': canvas_signal['large_canvas_area'],
+            'min_canvas_area': canvas_signal['min_canvas_area'],
+        })
     else:
         details.update({
             'body_text_length': MIN_BODY_TEXT_LENGTH + 100,
@@ -596,11 +645,20 @@ def evaluate_capture_quality(payload, expected_path):
         details['capture_error_messages'].append(str(proof_json.get('script_error'))[:500])
 
     reasons = []
-    if details['body_text_length'] < MIN_BODY_TEXT_LENGTH:
+    canvas_ready = bool(details.get('canvas_capture_ready'))
+    body_text_ready = details['body_text_length'] >= MIN_BODY_TEXT_LENGTH or canvas_ready
+    interactive_ready = details['interactive_elements'] >= MIN_INTERACTIVE_ELEMENTS or canvas_ready
+    semantic_ready = (not has_enriched_page_state(page_state)) or details['semantic_anchor_count'] >= 1 or canvas_ready
+    details['body_text_ready'] = body_text_ready
+    details['interactive_ready'] = interactive_ready
+    details['semantic_ready'] = semantic_ready
+    details['canvas_capture_override'] = canvas_ready
+
+    if not body_text_ready:
         reasons.append(f'blank/near-blank page (text length: {details["body_text_length"]})')
-    if details['interactive_elements'] < MIN_INTERACTIVE_ELEMENTS:
+    if not interactive_ready:
         reasons.append(f'not interactive enough ({details["interactive_elements"]} interactive elements)')
-    if has_enriched_page_state(page_state) and details['semantic_anchor_count'] < 1:
+    if has_enriched_page_state(page_state) and not semantic_ready:
         reasons.append('no visible semantic UI anchors in page capture')
     if details['has_errors']:
         reasons.append('page has console/runtime errors')
@@ -610,11 +668,10 @@ def evaluate_capture_quality(payload, expected_path):
         raw_observed = details.get('observed_path_raw') or details.get('observed_path') or observed_path
         reasons.append(f'wrong route: expected {expected_path}, got {raw_observed}')
 
-    semantic_ready = (not has_enriched_page_state(page_state)) or details['semantic_anchor_count'] >= 1
     telemetry_ready = (
         details['has_screenshot']
-        and details['body_text_length'] >= MIN_BODY_TEXT_LENGTH
-        and details['interactive_elements'] >= MIN_INTERACTIVE_ELEMENTS
+        and body_text_ready
+        and interactive_ready
         and semantic_ready
         and not details['has_errors']
     )

package/runtime/lib/riddle_core_call.mjs

@@ -136,6 +136,28 @@ async function run(tool, args) {
     });
   }
 
+  if (tool === "riddle_visual_diff") {
+    const {
+      async,
+      options,
+      stealth,
+      timeout_sec,
+      ...visualDiffOptions
+    } = args;
+    const script = `return await visualDiff(${JSON.stringify(visualDiffOptions)});`;
+    return core.runWithDefaults(config, {
+      url: args.url_before,
+      script,
+      options: { ...(options ?? {}), returnResult: true },
+      stealth,
+      timeout_sec: timeout_sec ?? 60,
+      async,
+    }, {
+      include: ["result", "console", "visual_diff"],
+      returnAsync: !!async,
+    });
+  }
+
   if (tool === "riddle_run") {
     return core.runWithDefaults(config, args.payload ?? args, {
       include: ["screenshot", "console", "result"],

package/runtime/lib/ship.py

@@ -352,7 +352,9 @@ def visual_delta_ship_blocker(state):
         return ''
     status = str(visual_delta.get('status') or 'missing')
     if status == 'unmeasured':
-        return 'visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof'
+        reason = str(visual_delta.get('reason') or '').strip()
+        detail = f': {reason}' if reason else ''
+        return 'visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof' + detail
     if status == 'measured' and visual_delta.get('passed') is False:
         return 'visual_delta.status=measured but visual_delta.passed=false blocks ready_to_ship for visual/UI proof'
     reason = str(visual_delta.get('reason') or '').strip()

package/runtime/lib/util.py

@@ -14,6 +14,7 @@ RIDDLE_DIRECT_TOOLS = {
     'riddle_build_preview',
     'riddle_build_preview_status',
     'riddle_script',
+    'riddle_visual_diff',
     'riddle_run',
 }
 CAPTURE_ARTIFACT_JSON_LIMIT = 256 * 1024
@@ -767,7 +768,7 @@ def enrich_capture_payload(payload):
     artifact_json = dict(enriched.get('_artifact_json') or {})
     artifact_errors = dict(enriched.get('_artifact_errors') or {})
 
-    for name in ('console.json', 'proof.json'):
+    for name in ('console.json', 'proof.json', 'visual-diff.json'):
         if name in artifact_json or name in artifact_errors:
             continue
         item = capture_output_item(enriched, name)
@@ -798,6 +799,10 @@ def enrich_capture_payload(payload):
                     enriched['result'] = result
                     break
 
+    visual_diff_json = artifact_json.get('visual-diff.json')
+    if isinstance(visual_diff_json, dict) and not enriched.get('visual_diff'):
+        enriched['visual_diff'] = visual_diff_json
+
     return enriched
 
 

package/runtime/lib/verify.py

@@ -33,6 +33,7 @@ import subprocess as sp
 
 MIN_BODY_TEXT_LENGTH = 50
 MIN_INTERACTIVE_ELEMENTS = 1
+MIN_CANVAS_AREA = 50000
 HYDRATION_WAIT_MS = 1500
 PAGE_STATE_PREFIX = 'RIDDLE_PROOF_STATE:'
 PROOF_EVIDENCE_PREFIX = 'RIDDLE_PROOF_EVIDENCE:'
@@ -54,13 +55,24 @@ MIN_VISUAL_CHANGED_PIXELS = 5000
 VISUAL_DELTA_PERCENT_KEYS = {
     'change_pct', 'change_percent', 'changed_percent', 'percent_changed',
     'diff_percent', 'visual_delta_percent', 'pixel_change_percent',
+    'changepercent', 'changedpercent', 'percentchanged', 'diffpercent',
+    'visualdeltapercent', 'pixelchangepercent', 'difference_percent',
+    'differencepercent', 'diff_percentage', 'diffpercentage',
+    'mismatch_percent', 'mismatchpercent', 'percentage', 'percent',
 }
 VISUAL_DELTA_RATIO_KEYS = {
     'change_ratio', 'changed_ratio', 'diff_ratio', 'visual_delta_ratio',
+    'changeratio', 'changedratio', 'diffratio', 'visualdeltaratio',
+    'difference_ratio', 'differenceratio', 'mismatch_ratio', 'mismatchratio',
 }
 VISUAL_CHANGED_PIXEL_KEYS = {
     'changed_pixels', 'changed_pixel_count', 'changedpixels',
     'diff_pixels', 'pixel_delta', 'visual_delta_pixels',
+    'diffpixels', 'pixeldelta', 'visualdeltapixels', 'different_pixels',
+    'differentpixels', 'mismatch_pixels', 'mismatchpixels', 'pixels_changed',
+    'pixelschanged', 'diff_pixel_count', 'diffpixelcount',
+    'pixel_diff_count', 'pixeldiffcount', 'different_pixel_count',
+    'differentpixelcount', 'num_different_pixels', 'numdifferentpixels',
 }
 VISUAL_TOTAL_PIXEL_KEYS = {
     'total_pixels', 'total_pixel_count', 'pixel_count', 'totalpixels',
@@ -799,11 +811,19 @@ def extract_visual_delta(payload):
     payload = enrich_capture_payload(payload)
     result = payload.get('result') if isinstance(payload, dict) else {}
     proof_json = payload.get('_proof_json') if isinstance(payload, dict) else {}
+    artifact_json = payload.get('_artifact_json') if isinstance(payload, dict) else {}
     proof_evidence = extract_proof_evidence(payload)
+    screenshot_url = extract_screenshot_url(payload)
+    artifact_summary = summarize_capture_artifacts(payload)
     candidates = [
         payload if isinstance(payload, dict) else {},
         result if isinstance(result, dict) else {},
         proof_json if isinstance(proof_json, dict) else {},
+        payload.get('visual_diff') if isinstance(payload, dict) and isinstance(payload.get('visual_diff'), dict) else {},
+        payload.get('visualDiff') if isinstance(payload, dict) and isinstance(payload.get('visualDiff'), dict) else {},
+        result.get('visual_diff') if isinstance(result, dict) and isinstance(result.get('visual_diff'), dict) else {},
+        result.get('visualDiff') if isinstance(result, dict) and isinstance(result.get('visualDiff'), dict) else {},
+        artifact_json.get('visual-diff.json') if isinstance(artifact_json, dict) and isinstance(artifact_json.get('visual-diff.json'), dict) else {},
         proof_evidence,
     ]
 
@@ -837,6 +857,23 @@ def extract_visual_delta(payload):
         percent = (changed_pixels / total_pixels) * 100
 
     if percent is None and changed_pixels is None:
+        has_artifacts = bool(
+            screenshot_url
+            or artifact_summary.get('outputs')
+            or artifact_summary.get('screenshots')
+            or artifact_summary.get('artifact_json')
+        )
+        reason = 'No measured before/after visual delta was found in proof evidence.'
+        if screenshot_url:
+            reason = (
+                'After screenshot artifact is present, but no measured before/after visual delta metrics were emitted; '
+                'the comparator did not run or did not publish change_percent/changed_pixels.'
+            )
+        elif has_artifacts:
+            reason = (
+                'Capture artifacts are present, but no measured before/after visual delta metrics were emitted; '
+                'the comparator did not run or did not publish change_percent/changed_pixels.'
+            )
         return {
             'status': 'unmeasured',
             'passed': None,
@@ -845,7 +882,19 @@ def extract_visual_delta(payload):
             'total_pixels': int(total_pixels) if total_pixels else None,
             'min_change_percent': MIN_VISUAL_DELTA_PERCENT,
             'min_changed_pixels': MIN_VISUAL_CHANGED_PIXELS,
-            'reason': 'No measured before/after visual delta was found in proof evidence.',
+            'reason': reason,
+            'diagnostic': {
+                'after_screenshot_present': bool(screenshot_url),
+                'proof_evidence_present': proof_evidence is not None,
+                'artifact_output_count': len(artifact_summary.get('outputs') or []),
+                'artifact_screenshot_count': len(artifact_summary.get('screenshots') or []),
+                'artifact_json': list(artifact_summary.get('artifact_json') or []),
+                'expected_metric_keys': {
+                    'percent': sorted(VISUAL_DELTA_PERCENT_KEYS),
+                    'changed_pixels': sorted(VISUAL_CHANGED_PIXEL_KEYS),
+                    'total_pixels': sorted(VISUAL_TOTAL_PIXEL_KEYS),
+                },
+            },
         }
 
     percent_pass = percent is not None and percent >= MIN_VISUAL_DELTA_PERCENT
@@ -867,6 +916,114 @@ def extract_visual_delta(payload):
     }
 
 
+def visual_delta_baseline_candidate(state, results):
+    reference = str(state.get('requested_reference') or state.get('reference') or 'both').strip().lower()
+    baseline = (results.get('baseline') or {}) if isinstance(results, dict) else {}
+    candidates = []
+    if reference in ('before', 'both', ''):
+        candidates.append(('before', (baseline.get('before') or {}).get('url') if isinstance(baseline.get('before'), dict) else ''))
+    if reference in ('prod', 'production', 'both'):
+        candidates.append(('prod', (baseline.get('prod') or {}).get('url') if isinstance(baseline.get('prod'), dict) else ''))
+    candidates.extend([
+        ('before', state.get('before_cdn') or ''),
+        ('prod', state.get('prod_cdn') or ''),
+    ])
+    for label, url in candidates:
+        text = str(url or '').strip()
+        if text:
+            return {'label': label, 'url': text}
+    return {'label': '', 'url': ''}
+
+
+def add_visual_delta_diagnostic(visual_delta, key, value):
+    updated = dict(visual_delta or {})
+    diagnostic = dict(updated.get('diagnostic') or {})
+    diagnostic[key] = value
+    updated['diagnostic'] = diagnostic
+    return updated
+
+
+def measure_visual_delta_against_baseline(state, results, after_payload, current_visual_delta):
+    if not visual_delta_applies(state.get('verification_mode')):
+        return current_visual_delta
+    if isinstance(current_visual_delta, dict) and current_visual_delta.get('status') == 'measured':
+        return current_visual_delta
+
+    baseline = visual_delta_baseline_candidate(state, results)
+    before_url = baseline.get('url') or ''
+    after_url = extract_screenshot_url(after_payload, 'after-proof') or str(state.get('after_cdn') or '').strip()
+    if not before_url or not after_url:
+        missing = []
+        if not before_url:
+            missing.append('baseline screenshot')
+        if not after_url:
+            missing.append('after screenshot')
+        return add_visual_delta_diagnostic(
+            current_visual_delta,
+            'visual_diff_fallback',
+            {
+                'status': 'skipped',
+                'reason': 'missing ' + ' and '.join(missing),
+                'baseline_label': baseline.get('label') or '',
+                'before_url_present': bool(before_url),
+                'after_url_present': bool(after_url),
+            },
+        )
+
+    args = {
+        'url_before': before_url,
+        'url_after': after_url,
+        'delay_ms': 250,
+        'timeout_sec': 60,
+    }
+    try:
+        payload = invoke_retry('riddle_visual_diff', args, retries=2, timeout=180)
+        append_capture_diagnostic(state, 'visual_delta', 'riddle_visual_diff', args, payload)
+    except Exception as exc:
+        return add_visual_delta_diagnostic(
+            current_visual_delta,
+            'visual_diff_fallback',
+            {
+                'status': 'error',
+                'error': type(exc).__name__ + ': ' + str(exc)[:300],
+                'baseline_label': baseline.get('label') or '',
+            },
+        )
+
+    measured = extract_visual_delta(payload)
+    if isinstance(measured, dict) and measured.get('status') == 'measured':
+        measured['source'] = 'riddle_visual_diff'
+        measured['comparison'] = {
+            'baseline_label': baseline.get('label') or '',
+            'before_url': before_url,
+            'after_url': after_url,
+        }
+        if isinstance(payload, dict):
+            diff_url = extract_screenshot_url(payload, 'visual-diff') or extract_screenshot_url(payload, 'diff')
+            if diff_url:
+                measured['comparison']['diff_url'] = diff_url
+            measured['artifact_summary'] = summarize_capture_artifacts(payload)
+        return measured
+
+    updated = add_visual_delta_diagnostic(
+        current_visual_delta,
+        'visual_diff_fallback',
+        {
+            'status': 'unmeasured',
+            'baseline_label': baseline.get('label') or '',
+            'before_url': before_url,
+            'after_url': after_url,
+            'payload_ok': payload.get('ok') if isinstance(payload, dict) else None,
+            'payload_error': str(payload.get('error') or payload.get('stderr') or '')[:500] if isinstance(payload, dict) else '',
+            'artifact_summary': summarize_capture_artifacts(payload) if isinstance(payload, dict) else {},
+        },
+    )
+    reason = str(updated.get('reason') or '').strip()
+    suffix = ' Riddle visual_diff fallback ran but did not publish a recognizable numeric delta.'
+    updated['reason'] = (reason + suffix).strip() if reason else suffix.strip()
+    return updated
+
+
 def visual_delta_applies(verification_mode):
     return screenshot_required_for_mode(verification_mode)
 
@@ -891,7 +1048,8 @@ def visual_delta_blocker_for_mode(verification_mode, visual_delta):
         status = str(visual_delta.get('status') or 'missing')
         reason = str(visual_delta.get('reason') or '').strip()
     if status == 'unmeasured':
-        return 'visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof; capture a measured before/after visual delta or choose needs_richer_proof.'
+        detail = f' Reason: {reason}' if reason else ''
+        return 'visual_delta.status=unmeasured blocks ready_to_ship for visual/UI proof; capture a measured before/after visual delta or choose needs_richer_proof.' + detail
     if status == 'measured' and isinstance(visual_delta, dict) and visual_delta.get('passed') is False:
         return 'visual_delta.status=measured but visual_delta.passed=false blocks ready_to_ship for visual/UI proof; the measured change did not clear the threshold.'
     if reason:
@@ -926,6 +1084,29 @@ def has_enriched_page_state(page_state):
     )
 
 
+def canvas_capture_signal(page_state):
+    if not isinstance(page_state, dict):
+        return {
+            'canvas_ready': False,
+            'canvas_count': 0,
+            'large_canvas_area': 0,
+        }
+    large_canvas_area = 0
+    for item in list_value(page_state.get('largeVisibleElements')):
+        if not isinstance(item, dict) or item.get('tag') != 'canvas':
+            continue
+        area = metric_number(item.get('area')) or 0
+        if area > large_canvas_area:
+            large_canvas_area = area
+    canvas_count = int(metric_number(page_state.get('canvasCount')) or 0)
+    return {
+        'canvas_ready': bool(canvas_count > 0 and large_canvas_area >= MIN_CANVAS_AREA),
+        'canvas_count': canvas_count,
+        'large_canvas_area': int(large_canvas_area),
+        'min_canvas_area': MIN_CANVAS_AREA,
+    }
+
+
 def normalize_observed_path(value):
     raw = str(value or '').strip()
     if not raw:
@@ -1135,6 +1316,7 @@ def evaluate_capture_quality(payload, expected_path, verification_mode='proof'):
     mode = normalized_verification_mode(verification_mode)
     supporting = collect_supporting_artifacts(payload)
     structured_ready = bool(supporting.get('has_structured_payload'))
+    playability_ready = mode in PLAYABILITY_MODES and bool(supporting.get('playability_ready'))
     screenshot_required = screenshot_required_for_mode(mode)
     details = {
         'verification_mode': mode,
@@ -1143,6 +1325,10 @@ def evaluate_capture_quality(payload, expected_path, verification_mode='proof'):
         'screenshot_required': screenshot_required,
         'structured_evidence_present': structured_ready,
         'proof_evidence_present': bool(supporting.get('proof_evidence_present')),
+        'playability_ready': playability_ready,
+        'canvas_capture_ready': False,
+        'large_canvas_area': 0,
+        'min_canvas_area': MIN_CANVAS_AREA,
         'proof_evidence_sample': supporting.get('proof_evidence_sample', ''),
         'body_text_length': 0,
         'interactive_elements': 0,
@@ -1183,6 +1369,12 @@ def evaluate_capture_quality(payload, expected_path, verification_mode='proof'):
             'large_visible_elements': list_value(page_state.get('largeVisibleElements'))[:10],
             'semantic_anchor_count': semantic_anchor_count(page_state),
         })
+        canvas_signal = canvas_capture_signal(page_state)
+        details.update({
+            'canvas_capture_ready': canvas_signal['canvas_ready'],
+            'large_canvas_area': canvas_signal['large_canvas_area'],
+            'min_canvas_area': canvas_signal['min_canvas_area'],
+        })
     elif screenshot_url:
         details.update({
             'body_text_length': MIN_BODY_TEXT_LENGTH + 100,
@@ -1220,11 +1412,20 @@ def evaluate_capture_quality(payload, expected_path, verification_mode='proof'):
         reasons.append('no screenshot or structured proof evidence in capture')
 
     should_enforce_visual_readiness = screenshot_required or (details['has_screenshot'] and not structured_ready)
-    if should_enforce_visual_readiness and details['body_text_length'] < MIN_BODY_TEXT_LENGTH:
+    canvas_ready = bool(details.get('canvas_capture_ready'))
+    body_text_ready = details['body_text_length'] >= MIN_BODY_TEXT_LENGTH or canvas_ready or playability_ready
+    interactive_ready = details['interactive_elements'] >= MIN_INTERACTIVE_ELEMENTS or canvas_ready or playability_ready
+    semantic_ready = (not has_enriched_page_state(page_state)) or details['semantic_anchor_count'] >= 1 or canvas_ready or playability_ready
+    details['body_text_ready'] = body_text_ready
+    details['interactive_ready'] = interactive_ready
+    details['semantic_ready'] = semantic_ready
+    details['canvas_or_playability_override'] = bool(should_enforce_visual_readiness and (canvas_ready or playability_ready))
+
+    if should_enforce_visual_readiness and not body_text_ready:
         reasons.append(f'blank/near-blank page (text length: {details["body_text_length"]})')
-    if should_enforce_visual_readiness and details['interactive_elements'] < MIN_INTERACTIVE_ELEMENTS:
+    if should_enforce_visual_readiness and not interactive_ready:
         reasons.append(f'not interactive enough ({details["interactive_elements"]} interactive elements)')
-    if should_enforce_visual_readiness and has_enriched_page_state(page_state) and details['semantic_anchor_count'] < 1:
+    if should_enforce_visual_readiness and has_enriched_page_state(page_state) and not semantic_ready:
         reasons.append('no visible semantic UI anchors in page capture')
     if details['has_errors']:
         reasons.append('page has console/runtime errors')
@@ -1234,15 +1435,14 @@ def evaluate_capture_quality(payload, expected_path, verification_mode='proof'):
         raw_observed = details.get('observed_path_raw') or details.get('observed_path') or observed_path
         reasons.append(f'wrong route: expected {expected_path}, got {raw_observed}')
 
-    semantic_ready = (not has_enriched_page_state(page_state)) or details['semantic_anchor_count'] >= 1
     visual_ready = (
         details['has_screenshot']
-        and details['body_text_length'] >= MIN_BODY_TEXT_LENGTH
-        and details['interactive_elements'] >= MIN_INTERACTIVE_ELEMENTS
+        and body_text_ready
+        and interactive_ready
         and semantic_ready
         and not details['has_errors']
     )
-    telemetry_ready = (visual_ready or structured_ready) and not details['has_errors']
+    telemetry_ready = (visual_ready or structured_ready or playability_ready) and not details['has_errors']
 
     return {
         'valid': len(reasons) == 0 and telemetry_ready,
@@ -1368,6 +1568,7 @@ def build_evidence_bundle(state, results, after_payload, after_observation, requ
         if visual_delta_applies(state.get('verification_mode'))
         else {'status': 'not_applicable', 'passed': None, 'reason': 'Verification mode does not require visual delta gating.'}
     )
+    visual_delta = measure_visual_delta_against_baseline(state, results, after_payload, visual_delta)
     semantic_context = build_semantic_context(state, results, after_observation, expected_path)
     artifact_contract = artifact_contract_for_mode(state.get('verification_mode'))
     artifact_production = artifact_production_summary(after_payload, supporting)

package/runtime/tests/recon_verify_smoke.py

@@ -566,8 +566,150 @@ def run_verify_quality_ignores_proof_telemetry_console_text():
     })
     assert unmeasured_delta['status'] == 'unmeasured'
     assert unmeasured_delta['passed'] is None
+    assert unmeasured_delta['diagnostic']['after_screenshot_present'] is True
+    assert 'After screenshot artifact is present' in unmeasured_delta['reason']
 
-    return {'ok': True, 'telemetry_valid': quality['valid'], 'weak_delta_passed': weak_delta['passed']}
+    visual_diff_delta = namespace['extract_visual_delta']({
+        'ok': True,
+        'outputs': [{'name': 'visual-diff.json', 'url': 'https://cdn.example.com/visual-diff.json'}],
+        '_artifact_json': {
+            'visual-diff.json': {
+                'changePercent': '1.45',
+                'diffPixelCount': 14094,
+                'totalPixels': 972000,
+            },
+        },
+    })
+    assert visual_diff_delta['status'] == 'measured'
+    assert visual_diff_delta['passed'] is True
+    assert visual_diff_delta['change_percent'] == 1.45
+    assert visual_diff_delta['changed_pixels'] == 14094
+
+    fallback_calls = []
+
+    def fake_invoke_retry(tool, args, retries=3, timeout=180):
+        fallback_calls.append({'tool': tool, 'args': args, 'retries': retries, 'timeout': timeout})
+        return {
+            'ok': True,
+            'visual_diff': {
+                'diffPercentage': 0.82,
+                'differentPixels': 7970,
+                'totalPixels': 972000,
+            },
+            'outputs': [{'name': 'visual-diff.png', 'url': 'https://cdn.example.com/visual-diff.png'}],
+        }
+
+    namespace['invoke_retry'] = fake_invoke_retry
+    namespace['append_capture_diagnostic'] = lambda *args, **kwargs: None
+    fallback_delta = namespace['measure_visual_delta_against_baseline'](
+        {'verification_mode': 'visual', 'requested_reference': 'before', 'before_cdn': 'https://cdn.example.com/before.png'},
+        {'baseline': {'before': {'url': 'https://cdn.example.com/before.png'}}},
+        {'ok': True, 'screenshots': [{'name': 'after-proof.png', 'url': 'https://cdn.example.com/after.png'}]},
+        unmeasured_delta,
+    )
+    assert fallback_delta['status'] == 'measured'
+    assert fallback_delta['source'] == 'riddle_visual_diff'
+    assert fallback_delta['comparison']['before_url'] == 'https://cdn.example.com/before.png'
+    assert fallback_delta['comparison']['after_url'] == 'https://cdn.example.com/after.png'
+    assert fallback_calls[0]['tool'] == 'riddle_visual_diff'
+
+    canvas_payload = {
+        'bodyTextLength': 7,
+        'visibleTextSample': 'Luge',
+        'interactiveElements': 1,
+        'visibleInteractiveElements': 1,
+        'pathname': '/games/luge-run',
+        'title': 'Luge Run',
+        'headings': [],
+        'buttons': [],
+        'links': [],
+        'canvasCount': 1,
+        'largeVisibleElements': [{'tag': 'canvas', 'text': '', 'area': 420000}],
+    }
+    canvas_quality = namespace['evaluate_capture_quality']({
+        'ok': True,
+        'screenshots': [{'name': 'after-proof.png', 'url': 'https://cdn.example.com/after-proof.png'}],
+        'outputs': [{'name': 'after-proof.png', 'url': 'https://cdn.example.com/after-proof.png'}],
+        'console': ['RIDDLE_PROOF_STATE:' + json.dumps(canvas_payload)],
+    }, '/games/luge-run', 'visual')
+    assert canvas_quality['valid'] is True, canvas_quality
+    assert canvas_quality['details']['canvas_capture_ready'] is True
+    assert canvas_quality['details']['body_text_ready'] is True
+    assert 'blank/near-blank' not in canvas_quality['reason']
+
+    playability_payload = {
+        **canvas_payload,
+        'interactiveElements': 0,
+        'visibleInteractiveElements': 0,
+        'largeVisibleElements': [],
+    }
+    playability_evidence = {
+        'input_events': [{'type': 'pointerdown'}],
+        'state_delta': {'changed': True, 'changed_keys': ['distance']},
+        'canvas_delta': {'changed_pixels': 18000},
+        'time_delta_ms': 1300,
+    }
+    playable_quality = namespace['evaluate_capture_quality']({
+        'ok': True,
+        'screenshots': [{'name': 'after-proof.png', 'url': 'https://cdn.example.com/after-proof.png'}],
+        'outputs': [{'name': 'after-proof.png', 'url': 'https://cdn.example.com/after-proof.png'}],
+        'console': [
+            'RIDDLE_PROOF_STATE:' + json.dumps(playability_payload),
+            'RIDDLE_PROOF_EVIDENCE:' + json.dumps({'playability': playability_evidence}),
+        ],
+    }, '/games/luge-run', 'playable')
+    assert playable_quality['valid'] is True, playable_quality
+    assert playable_quality['details']['playability_ready'] is True
+    assert playable_quality['details']['interactive_ready'] is True
+
+    return {
+        'ok': True,
+        'telemetry_valid': quality['valid'],
+        'weak_delta_passed': weak_delta['passed'],
+        'canvas_valid': canvas_quality['valid'],
+        'playable_valid': playable_quality['valid'],
+    }
+
+
+def run_recon_quality_accepts_canvas_first_routes():
+    tempdir = Path(tempfile.mkdtemp(prefix='riddle-proof-recon-canvas-quality-'))
+    state_path = tempdir / 'state.json'
+    try:
+        write_state(state_path, {
+            'after_worktree': str(tempdir),
+            'before_worktree': str(tempdir),
+        })
+        with temporary_env(RIDDLE_PROOF_STATE_FILE=str(state_path)):
+            sys.modules.pop('util', None)
+            source = RECON_PATH.read_text()
+            helpers_source = source.split('\ndef clean_next_cache', 1)[0]
+            namespace = {'__file__': str(RECON_PATH)}
+            exec(compile(helpers_source, str(RECON_PATH), 'exec'), namespace)
+        canvas_payload = {
+            'bodyTextLength': 4,
+            'visibleTextSample': 'Game',
+            'interactiveElements': 1,
+            'visibleInteractiveElements': 1,
+            'pathname': '/games/luge-run',
+            'title': 'Luge Run',
+            'headings': [],
+            'buttons': [],
+            'links': [],
+            'canvasCount': 1,
+            'largeVisibleElements': [{'tag': 'canvas', 'text': '', 'area': 420000}],
+        }
+        quality = namespace['evaluate_capture_quality']({
+            'ok': True,
+            'screenshots': [{'name': 'before.png', 'url': 'https://cdn.example.com/before.png'}],
+            'outputs': [{'name': 'before.png', 'url': 'https://cdn.example.com/before.png'}],
+            'console': ['RIDDLE_PROOF_STATE:' + json.dumps(canvas_payload)],
+        }, '/games/luge-run')
+        assert quality['valid'] is True, quality
+        assert quality['details']['canvas_capture_ready'] is True
+        assert 'blank/near-blank' not in quality['reason']
+        return {'ok': True, 'valid': quality['valid']}
+    finally:
+        shutil.rmtree(tempdir, ignore_errors=True)
 
 
 def load_util_with_fake(fake: FakeRiddle):
@@ -1992,6 +2134,7 @@ if __name__ == '__main__':
         'implement_records_detection_when_changes_missing': run_implement_records_detection_when_changes_missing(),
         'implement_ignores_tool_noise_when_detecting_changes': run_implement_ignores_tool_noise_when_detecting_changes(),
         'verify_quality_ignores_proof_telemetry_console_text': run_verify_quality_ignores_proof_telemetry_console_text(),
+        'recon_quality_accepts_canvas_first_routes': run_recon_quality_accepts_canvas_first_routes(),
         'recon_then_author_request': run_recon_then_author_request(),
         'recon_preserves_query_route': run_recon_preserves_query_route(),
         'recon_route_literal_preference': run_recon_prefers_route_literals_over_import_paths(),