@riddledc/riddle-proof 0.7.80 → 0.7.82

package/runtime/lib/verify.py

@@ -7,7 +7,7 @@ while good captures produce a structured evidence packet that the supervising ag
 must assess before the wrapper routes back into author/implement/recon work or ship.
 """
 
-import json, os, struct, sys, time, zlib
+import json, os, re, struct, sys, time, zlib
 from urllib.parse import parse_qsl, urlparse
 from urllib.request import Request, urlopen
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
@@ -18,6 +18,7 @@ from util import (
     build_visual_proof_session,
     capture_proof_session_seed,
     capture_static_preview,
+    capture_viewport_matrix_status,
     enrich_capture_payload,
     has_auth_context,
     invoke,
@@ -31,6 +32,9 @@ from util import (
     should_use_static_preview,
     proof_session_output_url,
     summarize_capture_artifacts,
+    viewport_matrix_return_js,
+    viewport_matrix_screenshot_js,
+    viewport_matrix_setup_js,
 )
 import subprocess as sp
 
@@ -55,6 +59,16 @@ PLAYABILITY_MODES = {'playable', 'gameplay', 'game'}
 PROOF_EVIDENCE_REQUIRED_MODES = {'audio'}
 MIN_VISUAL_DELTA_PERCENT = 0.5
 MIN_VISUAL_CHANGED_PIXELS = 5000
+TARGETED_VISUAL_DELTA_PERCENT = 0.02
+TARGETED_VISUAL_CHANGED_PIXELS = 250
+TARGETED_CHANGED_REGION_MAX_AREA_PERCENT = 20
+TARGETED_SEMANTIC_STOPWORDS = {
+    'about', 'after', 'agent', 'again', 'before', 'browser', 'button',
+    'change', 'changed', 'click', 'copy', 'delta', 'does', 'from', 'into',
+    'layout', 'mode', 'page', 'proof', 'route', 'screen', 'shows', 'small',
+    'target', 'that', 'this', 'until', 'update', 'user', 'verify', 'view',
+    'visual', 'with',
+}
 VISUAL_DELTA_PERCENT_KEYS = {
     'change_pct', 'change_percent', 'changed_percent', 'percent_changed',
     'diff_percent', 'visual_delta_percent', 'pixel_change_percent',
@@ -82,6 +96,18 @@ VISUAL_TOTAL_PIXEL_KEYS = {
 }
 VISUAL_WIDTH_KEYS = {'width', 'image_width', 'screenshot_width'}
 VISUAL_HEIGHT_KEYS = {'height', 'image_height', 'screenshot_height'}
+VISUAL_CHANGED_REGION_KEYS = {
+    'changed_region', 'changedregion', 'diff_region', 'diffregion',
+    'difference_region', 'differenceregion', 'changed_bounds',
+    'changedbounds', 'diff_bounds', 'diffbounds', 'difference_bounds',
+    'differencebounds', 'bounding_box', 'boundingbox', 'bbox', 'bounds',
+}
+VISUAL_REGION_X_KEYS = {'x', 'left', 'min_x', 'minx'}
+VISUAL_REGION_Y_KEYS = {'y', 'top', 'min_y', 'miny'}
+VISUAL_REGION_WIDTH_KEYS = {'width', 'w'}
+VISUAL_REGION_HEIGHT_KEYS = {'height', 'h'}
+VISUAL_REGION_RIGHT_KEYS = {'right', 'max_x', 'maxx'}
+VISUAL_REGION_BOTTOM_KEYS = {'bottom', 'max_y', 'maxy'}
 
 
 def capture_script_saves_screenshot(script):
@@ -133,7 +159,7 @@ def audit_current_capture_url(state, prod_url, expected_path):
 
 
 def capture_current_target(state, target_url, label, capture_script, timeout=300):
-    script = build_capture_script(target_url, capture_script, label, state.get('wait_for_selector', ''))
+    script = build_capture_script(target_url, capture_script, label, state.get('wait_for_selector', ''), state.get('viewport_matrix'))
     args = {'script': script, 'timeout_sec': 60}
     apply_auth_context(state, args)
     shot = invoke_retry('riddle_script', args, retries=3, timeout=max(timeout, 120))
@@ -312,9 +338,10 @@ def abort_capture_failure(state, results, expected_path, message, raw_payload):
     raise SystemExit(summary)
 
 
-def build_probe_capture_script(base_script='', verification_mode='proof', proof_session_seed=None):
+def build_probe_capture_script(base_script='', verification_mode='proof', proof_session_seed=None, viewport_matrix=None):
     pieces = []
     script = (base_script or '').strip()
+    pieces.extend(viewport_matrix_setup_js(viewport_matrix))
     pieces.append('let __riddleProofCaptureScriptError = null;')
     pieces.append('let __riddleProofCaptureScriptResult = null;')
     if script:
@@ -374,7 +401,10 @@ def build_probe_capture_script(base_script='', verification_mode='proof', proof_
         '  catch (err) { console.log(' + json.dumps(PROOF_EVIDENCE_PREFIX) + ' + JSON.stringify({ serialization_error: String(err) })); }',
         '}',
     ])
-    if auto_screenshot_for_mode(verification_mode) and not capture_script_saves_screenshot(script):
+    viewport_screenshot_lines = viewport_matrix_screenshot_js('after-proof', viewport_matrix)
+    if auto_screenshot_for_mode(verification_mode) and viewport_screenshot_lines:
+        pieces.extend(viewport_screenshot_lines)
+    elif auto_screenshot_for_mode(verification_mode) and not capture_script_saves_screenshot(script):
         pieces.append("await saveScreenshot('after-proof');")
     if isinstance(proof_session_seed, dict):
         pieces.append(
@@ -383,7 +413,7 @@ def build_probe_capture_script(base_script='', verification_mode='proof', proof_
             '); } catch {}'
         )
     pieces.append('if (__riddleProofCaptureScriptError) throw __riddleProofCaptureScriptError;')
-    pieces.append('return { pageState, proofEvidence: __riddleProofEvidenceValue };')
+    pieces.append('return { pageState, proofEvidence: __riddleProofEvidenceValue, viewportMatrix: ' + viewport_matrix_return_js() + ' };')
     return ' '.join(pieces)
 
 
@@ -885,7 +915,274 @@ def find_metric_value(value, key_names, depth=0):
     return None
 
 
-def extract_visual_delta(payload):
+def targeted_semantic_tokens(value, limit=24):
+    text = ''
+    try:
+        text = json.dumps(value, sort_keys=True) if isinstance(value, (dict, list)) else str(value or '')
+    except Exception:
+        text = str(value or '')
+    tokens = []
+    for token in re.findall(r'[a-z0-9]+', text.lower()):
+        if len(token) < 4 or token in TARGETED_SEMANTIC_STOPWORDS or token in tokens:
+            continue
+        tokens.append(token)
+        if len(tokens) >= limit:
+            break
+    return tokens
+
+
+def semantic_visible_text_for_delta(state=None, semantic_context=None):
+    chunks = []
+    after = (semantic_context or {}).get('after') if isinstance(semantic_context, dict) else {}
+    for source in [after or {}]:
+        if not isinstance(source, dict):
+            continue
+        for key in ('visible_text_sample', 'title'):
+            if source.get(key):
+                chunks.append(str(source.get(key)))
+        for key in ('headings', 'buttons', 'links', 'large_visible_elements'):
+            value = source.get(key)
+            try:
+                chunks.append(json.dumps(value, sort_keys=True))
+            except Exception:
+                chunks.append(str(value))
+    return ' '.join(chunks).lower()
+
+
+def targeted_assertion_text_sources(value, depth=0):
+    if depth > 8:
+        return []
+    sources = []
+    if isinstance(value, list):
+        for item in value:
+            sources.extend(targeted_assertion_text_sources(item, depth + 1))
+        return sources
+    if not isinstance(value, dict):
+        return sources
+
+    assertion_type = str(value.get('type') or value.get('kind') or '').strip().lower()
+    text_keys = (
+        'text', 'contains', 'pattern', 'label', 'copy', 'expected',
+        'expected_text', 'expectedText', 'visible_text', 'visibleText',
+    )
+    text_values = [
+        value.get(key)
+        for key in text_keys
+        if isinstance(value.get(key), str) and value.get(key).strip()
+    ]
+    type_is_textual = any(marker in assertion_type for marker in (
+        'text', 'copy', 'visible', 'contains', 'label', 'heading', 'button', 'link', 'badge',
+    ))
+    if text_values and (type_is_textual or not assertion_type):
+        sources.extend(text_values)
+
+    for key in ('assertions', 'checks', 'expected', 'match', 'matches'):
+        nested = value.get(key)
+        if isinstance(nested, (dict, list)):
+            sources.extend(targeted_assertion_text_sources(nested, depth + 1))
+    return sources
+
+
+def visual_delta_semantic_support(state=None, semantic_context=None):
+    state = state if isinstance(state, dict) else {}
+    visible_text = semantic_visible_text_for_delta(state, semantic_context)
+    if not visible_text:
+        return {
+            'supported': False,
+            'matched_tokens': [],
+            'reason': 'no semantic text sample was available for targeted visual-delta thresholds',
+        }
+
+    assertion_sources = targeted_assertion_text_sources(state.get('parsed_assertions'))
+    assertion_tokens = []
+    for source in assertion_sources:
+        for token in targeted_semantic_tokens(source):
+            if token not in assertion_tokens:
+                assertion_tokens.append(token)
+    if not assertion_tokens:
+        return {
+            'supported': False,
+            'matched_tokens': [],
+            'reason': 'targeted visual-delta thresholds require text/visible assertions for the intended small change',
+        }
+
+    matched_assertion_tokens = [token for token in assertion_tokens if token in visible_text]
+    context_tokens = []
+    for source in (state.get('success_criteria'), state.get('change_request'), state.get('proof_plan')):
+        for token in targeted_semantic_tokens(source):
+            if token not in context_tokens:
+                context_tokens.append(token)
+    matched_context_tokens = [token for token in context_tokens if token in visible_text]
+    return {
+        'supported': len(matched_assertion_tokens) >= 1,
+        'matched_tokens': (matched_assertion_tokens + [token for token in matched_context_tokens if token not in matched_assertion_tokens])[:12],
+        'matched_assertion_tokens': matched_assertion_tokens[:12],
+        'matched_context_tokens': matched_context_tokens[:12],
+        'reason': 'text assertions matched visible after evidence' if matched_assertion_tokens else 'no text assertion tokens matched visible after evidence',
+    }
+
+
+def normalize_changed_region(value, total_pixels=None, changed_pixels=None, image_width=None, image_height=None, dimension_mismatch=False):
+    if not isinstance(value, dict):
+        return None
+
+    x = find_metric_value(value, VISUAL_REGION_X_KEYS)
+    y = find_metric_value(value, VISUAL_REGION_Y_KEYS)
+    width = find_metric_value(value, VISUAL_REGION_WIDTH_KEYS)
+    height = find_metric_value(value, VISUAL_REGION_HEIGHT_KEYS)
+    right = find_metric_value(value, VISUAL_REGION_RIGHT_KEYS)
+    bottom = find_metric_value(value, VISUAL_REGION_BOTTOM_KEYS)
+
+    if width is None and x is not None and right is not None and right > x:
+        width = right - x
+    if height is None and y is not None and bottom is not None and bottom > y:
+        height = bottom - y
+    if x is None and width is not None and right is not None:
+        x = right - width
+    if y is None and height is not None and bottom is not None:
+        y = bottom - height
+
+    if x is None or y is None or width is None or height is None:
+        return None
+    if width <= 0 or height <= 0:
+        return None
+
+    x = int(round(x))
+    y = int(round(y))
+    width = int(round(width))
+    height = int(round(height))
+    area_pixels = width * height
+    changed = metric_number(changed_pixels)
+    total = metric_number(total_pixels)
+    image_w = metric_number(image_width)
+    image_h = metric_number(image_height)
+    area_percent = (area_pixels / total) * 100 if total and total > 0 else None
+    width_percent = (width / image_w) * 100 if image_w and image_w > 0 else None
+    height_percent = (height / image_h) * 100 if image_h and image_h > 0 else None
+    density = (changed / area_pixels) if changed is not None and area_pixels > 0 else None
+    absolute_small_region = area_pixels <= max(TARGETED_VISUAL_CHANGED_PIXELS, int(changed or 0), 1)
+    percent_localized = area_percent is not None and area_percent <= TARGETED_CHANGED_REGION_MAX_AREA_PERCENT
+    localized = bool(not dimension_mismatch and (absolute_small_region or percent_localized))
+    if dimension_mismatch:
+        classification = 'geometry_change'
+    elif absolute_small_region or (area_percent is not None and area_percent <= 1):
+        classification = 'point_or_icon'
+    elif localized:
+        classification = 'localized'
+    else:
+        classification = 'broad'
+
+    return {
+        'present': True,
+        'x': x,
+        'y': y,
+        'width': width,
+        'height': height,
+        'right': x + width,
+        'bottom': y + height,
+        'area_pixels': area_pixels,
+        'area_percent': round(area_percent, 4) if area_percent is not None else None,
+        'width_percent': round(width_percent, 4) if width_percent is not None else None,
+        'height_percent': round(height_percent, 4) if height_percent is not None else None,
+        'changed_pixel_density': round(density, 6) if density is not None else None,
+        'localized_for_targeted_change': localized,
+        'classification': classification,
+        'dimension_mismatch': bool(dimension_mismatch),
+    }
+
+
+def find_changed_region(value, total_pixels=None, changed_pixels=None, image_width=None, image_height=None, depth=0):
+    if depth > 7:
+        return None
+    if isinstance(value, dict):
+        for raw_key, raw_value in value.items():
+            if normalize_metric_key(raw_key) in VISUAL_CHANGED_REGION_KEYS:
+                region = normalize_changed_region(
+                    raw_value,
+                    total_pixels=total_pixels,
+                    changed_pixels=changed_pixels,
+                    image_width=image_width,
+                    image_height=image_height,
+                )
+                if region is not None:
+                    return region
+        for raw_value in value.values():
+            region = find_changed_region(raw_value, total_pixels, changed_pixels, image_width, image_height, depth + 1)
+            if region is not None:
+                return region
+    elif isinstance(value, list):
+        for item in value[:60]:
+            region = find_changed_region(item, total_pixels, changed_pixels, image_width, image_height, depth + 1)
+            if region is not None:
+                return region
+    return None
+
+
+def visual_delta_region_support(changed_region=None):
+    if not isinstance(changed_region, dict) or not changed_region.get('present'):
+        return {
+            'available': False,
+            'supported': None,
+            'reason': 'no changed-region metadata was available for targeted visual-delta localization',
+        }
+    if changed_region.get('dimension_mismatch'):
+        return {
+            'available': True,
+            'supported': False,
+            'reason': 'changed-region metadata reports a screenshot geometry change',
+            'classification': changed_region.get('classification'),
+        }
+    if changed_region.get('localized_for_targeted_change') is True:
+        return {
+            'available': True,
+            'supported': True,
+            'reason': 'changed pixels are localized enough for a targeted visual change',
+            'classification': changed_region.get('classification'),
+            'area_percent': changed_region.get('area_percent'),
+        }
+    return {
+        'available': True,
+        'supported': False,
+        'reason': 'changed pixels are too broad for a targeted visual change',
+        'classification': changed_region.get('classification'),
+        'area_percent': changed_region.get('area_percent'),
+    }
+
+
+def visual_delta_thresholds_for_context(state=None, semantic_context=None, changed_region=None):
+    semantic = visual_delta_semantic_support(state, semantic_context)
+    localization = visual_delta_region_support(changed_region)
+    if semantic.get('supported') and localization.get('supported') is not False:
+        return {
+            'mode': 'targeted_semantic',
+            'min_change_percent': TARGETED_VISUAL_DELTA_PERCENT,
+            'min_changed_pixels': TARGETED_VISUAL_CHANGED_PIXELS,
+            'default_min_change_percent': MIN_VISUAL_DELTA_PERCENT,
+            'default_min_changed_pixels': MIN_VISUAL_CHANGED_PIXELS,
+            'semantic_support': semantic,
+            'localization_support': localization,
+        }
+    return {
+        'mode': 'default',
+        'min_change_percent': MIN_VISUAL_DELTA_PERCENT,
+        'min_changed_pixels': MIN_VISUAL_CHANGED_PIXELS,
+        'semantic_support': semantic,
+        'localization_support': localization,
+    }
+
+
+def visual_delta_pass_reason(source_label, passed, thresholds):
+    mode = (thresholds or {}).get('mode')
+    if passed and mode == 'targeted_semantic':
+        return source_label + ' clears the targeted-change threshold with matching semantic/text evidence.'
+    if passed:
+        return source_label + ' clears the legibility threshold.'
+    if mode == 'targeted_semantic':
+        return source_label + ' is below even the targeted-change threshold; capture success alone is not proof.'
+    return source_label + ' is below the legibility threshold; capture success alone is not proof.'
+
+
+def extract_visual_delta(payload, state=None, semantic_context=None):
     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 {}
@@ -934,6 +1231,14 @@ def extract_visual_delta(payload):
     if percent is None and changed_pixels is not None and total_pixels:
         percent = (changed_pixels / total_pixels) * 100
 
+    changed_region = None
+    for candidate in candidates:
+        if candidate is None:
+            continue
+        changed_region = find_changed_region(candidate, total_pixels, changed_pixels, width, height)
+        if changed_region is not None:
+            break
+
     if percent is None and changed_pixels is None:
         has_artifacts = bool(
             screenshot_url
@@ -975,8 +1280,11 @@ def extract_visual_delta(payload):
             },
         }
 
-    percent_pass = percent is not None and percent >= MIN_VISUAL_DELTA_PERCENT
-    pixel_pass = changed_pixels is not None and changed_pixels >= MIN_VISUAL_CHANGED_PIXELS
+    thresholds = visual_delta_thresholds_for_context(state, semantic_context, changed_region)
+    min_percent = thresholds['min_change_percent']
+    min_pixels = thresholds['min_changed_pixels']
+    percent_pass = percent is not None and percent >= min_percent
+    pixel_pass = changed_pixels is not None and changed_pixels >= min_pixels
     passed = percent_pass or pixel_pass
     return {
         'status': 'measured',
@@ -984,13 +1292,13 @@ def extract_visual_delta(payload):
         'change_percent': round(percent, 4) if percent is not None else None,
         'changed_pixels': int(changed_pixels) if changed_pixels is not None else None,
         'total_pixels': int(total_pixels) if total_pixels is not None else None,
-        'min_change_percent': MIN_VISUAL_DELTA_PERCENT,
-        'min_changed_pixels': MIN_VISUAL_CHANGED_PIXELS,
-        'reason': (
-            'Measured visual delta clears the legibility threshold.'
-            if passed else
-            'Measured visual delta is below the legibility threshold; capture success alone is not proof.'
-        ),
+        'min_change_percent': min_percent,
+        'min_changed_pixels': min_pixels,
+        'threshold_mode': thresholds.get('mode'),
+        'semantic_support': thresholds.get('semantic_support'),
+        'localization_support': thresholds.get('localization_support'),
+        'changed_region': changed_region,
+        'reason': visual_delta_pass_reason('Measured visual delta', passed, thresholds),
     }
 
 
@@ -1140,6 +1448,14 @@ def compare_rgba_images(before_image, after_image, threshold=10):
     overlap_height = min(before_height, after_height)
     total_pixels = max(before_width * before_height, after_width * after_height)
     changed_pixels = total_pixels - (overlap_width * overlap_height)
+    min_x = min_y = None
+    max_x = max_y = None
+    dimension_mismatch = before_width != after_width or before_height != after_height
+    if dimension_mismatch and total_pixels > 0:
+        min_x = 0
+        min_y = 0
+        max_x = max(before_width, after_width) - 1
+        max_y = max(before_height, after_height) - 1
     for y in range(overlap_height):
         before_row = y * before_width * 4
         after_row = y * after_width * 4
@@ -1153,11 +1469,31 @@ def compare_rgba_images(before_image, after_image, threshold=10):
                 abs(before_rgba[b + 3] - after_rgba[a + 3]),
             ) > threshold:
                 changed_pixels += 1
+                min_x = x if min_x is None else min(min_x, x)
+                min_y = y if min_y is None else min(min_y, y)
+                max_x = x if max_x is None else max(max_x, x)
+                max_y = y if max_y is None else max(max_y, y)
     change_percent = (changed_pixels / total_pixels) * 100 if total_pixels else None
+    changed_region = None
+    if min_x is not None and min_y is not None and max_x is not None and max_y is not None:
+        changed_region = normalize_changed_region(
+            {
+                'x': min_x,
+                'y': min_y,
+                'width': max_x - min_x + 1,
+                'height': max_y - min_y + 1,
+            },
+            total_pixels=total_pixels,
+            changed_pixels=changed_pixels,
+            image_width=max(before_width, after_width),
+            image_height=max(before_height, after_height),
+            dimension_mismatch=dimension_mismatch,
+        )
     return {
         'changed_pixels': changed_pixels,
         'total_pixels': total_pixels,
         'change_percent': change_percent,
+        'changed_region': changed_region,
         'before_width': before_width,
         'before_height': before_height,
         'after_width': after_width,
@@ -1165,7 +1501,7 @@ def compare_rgba_images(before_image, after_image, threshold=10):
     }
 
 
-def measure_visual_delta_from_image_artifacts(before_url, after_url):
+def measure_visual_delta_from_image_artifacts(before_url, after_url, state=None, semantic_context=None):
     if not (image_artifact_url(before_url) and image_artifact_url(after_url)):
         return {
             'status': 'skipped',
@@ -1183,8 +1519,12 @@ def measure_visual_delta_from_image_artifacts(before_url, after_url):
     changed_pixels = comparison.get('changed_pixels')
     total_pixels = comparison.get('total_pixels')
     percent = comparison.get('change_percent')
-    percent_pass = percent is not None and percent >= MIN_VISUAL_DELTA_PERCENT
-    pixel_pass = changed_pixels is not None and changed_pixels >= MIN_VISUAL_CHANGED_PIXELS
+    changed_region = comparison.get('changed_region')
+    thresholds = visual_delta_thresholds_for_context(state, semantic_context, changed_region)
+    min_percent = thresholds['min_change_percent']
+    min_pixels = thresholds['min_changed_pixels']
+    percent_pass = percent is not None and percent >= min_percent
+    pixel_pass = changed_pixels is not None and changed_pixels >= min_pixels
     passed = bool(percent_pass or pixel_pass)
     return {
         'status': 'measured',
@@ -1192,14 +1532,14 @@ def measure_visual_delta_from_image_artifacts(before_url, after_url):
         'change_percent': round(percent, 4) if percent is not None else None,
         'changed_pixels': int(changed_pixels) if changed_pixels is not None else None,
         'total_pixels': int(total_pixels) if total_pixels is not None else None,
-        'min_change_percent': MIN_VISUAL_DELTA_PERCENT,
-        'min_changed_pixels': MIN_VISUAL_CHANGED_PIXELS,
+        'min_change_percent': min_percent,
+        'min_changed_pixels': min_pixels,
+        'threshold_mode': thresholds.get('mode'),
+        'semantic_support': thresholds.get('semantic_support'),
+        'localization_support': thresholds.get('localization_support'),
+        'changed_region': changed_region,
         'source': 'riddle_artifact_image_diff',
-        'reason': (
-            'Measured visual delta from before/after screenshot artifacts clears the legibility threshold.'
-            if passed else
-            'Measured visual delta from before/after screenshot artifacts is below the legibility threshold.'
-        ),
+        'reason': visual_delta_pass_reason('Measured visual delta from before/after screenshot artifacts', passed, thresholds),
         'comparison': {
             'before_url': before_url,
             'after_url': after_url,
@@ -1219,7 +1559,7 @@ def add_visual_delta_diagnostic(visual_delta, key, value):
     return updated
 
 
-def measure_visual_delta_against_baseline(state, results, after_payload, current_visual_delta):
+def measure_visual_delta_against_baseline(state, results, after_payload, current_visual_delta, semantic_context=None):
     if not visual_delta_required_for_state(state):
         return current_visual_delta
     if isinstance(current_visual_delta, dict) and current_visual_delta.get('status') == 'measured':
@@ -1246,7 +1586,7 @@ def measure_visual_delta_against_baseline(state, results, after_payload, current
             },
         )
 
-    artifact_delta = measure_visual_delta_from_image_artifacts(before_url, after_url)
+    artifact_delta = measure_visual_delta_from_image_artifacts(before_url, after_url, state, semantic_context)
     append_capture_diagnostic(state, 'visual_delta', 'riddle_artifact_image_diff', {
         'baseline_label': baseline.get('label') or '',
         'before_url': before_url,
@@ -1281,7 +1621,7 @@ def measure_visual_delta_against_baseline(state, results, after_payload, current
             },
         )
 
-    measured = extract_visual_delta(payload)
+    measured = extract_visual_delta(payload, state, semantic_context)
     if isinstance(measured, dict) and measured.get('status') == 'measured':
         measured['source'] = 'riddle_visual_diff'
         measured['comparison'] = {
@@ -1895,6 +2235,8 @@ def build_evidence_bundle(state, results, after_payload, after_observation, requ
     proof_evidence = extract_proof_evidence(after_payload)
     playability_assessment = assess_playability_evidence(proof_evidence)
     playability_evidence = extract_playability_evidence(proof_evidence)
+    semantic_context = build_semantic_context(state, results, after_observation, expected_path)
+    viewport_matrix = (results.get('after') or {}).get('viewport_matrix') or capture_viewport_matrix_status(state, after_payload, 'after-proof')
     if audit_no_diff_mode(state):
         visual_delta = {
             'status': 'not_applicable',
@@ -1903,12 +2245,11 @@ def build_evidence_bundle(state, results, after_payload, after_observation, requ
         }
     else:
         visual_delta = (
-            extract_visual_delta(after_payload)
+            extract_visual_delta(after_payload, state, semantic_context)
             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)
+    visual_delta = measure_visual_delta_against_baseline(state, results, after_payload, visual_delta, semantic_context)
     artifact_contract = artifact_contract_for_state(state)
     artifact_production = artifact_production_summary(after_payload, supporting)
     artifact_usage = artifact_usage_summary(
@@ -1948,6 +2289,7 @@ def build_evidence_bundle(state, results, after_payload, after_observation, requ
             'semantic_context': semantic_context,
             'artifact_contract': artifact_contract,
             'artifact_usage': artifact_usage,
+            'viewport_matrix': viewport_matrix,
         },
         status='evidence_captured' if after_observation.get('valid') else 'capture_incomplete',
     )
@@ -1958,6 +2300,7 @@ def build_evidence_bundle(state, results, after_payload, after_observation, requ
         'required_baseline_present': required_baseline_present,
         'baseline': results.get('baseline') or {},
         'semantic_context': semantic_context,
+        'viewport_matrix': viewport_matrix,
         'artifact_contract': artifact_contract,
         'artifact_production': artifact_production,
         'artifact_usage': artifact_usage,
@@ -2023,6 +2366,7 @@ def build_supervisor_assessment_request(state, payload, after_observation, requi
         semantic_context,
         evidence_basis,
     )
+    viewport_matrix = (evidence_bundle or {}).get('viewport_matrix') if isinstance(evidence_bundle, dict) else None
     if isinstance(evidence_bundle, dict):
         evidence_bundle['artifact_contract'] = artifact_contract
         evidence_bundle['artifact_production'] = artifact_production
@@ -2071,6 +2415,7 @@ def build_supervisor_assessment_request(state, payload, after_observation, requi
         'supporting_artifacts': supporting,
         'visual_delta': visual_delta,
         'semantic_context': semantic_context,
+        'viewport_matrix': viewport_matrix,
         'evidence_bundle': evidence_bundle or {},
         'evidence_basis': evidence_basis,
         'artifact_contract': artifact_contract,
@@ -2124,7 +2469,7 @@ expected_path = (
 )
 verification_mode = normalized_verification_mode(s.get('verification_mode'))
 proof_session_seed = capture_proof_session_seed(s, expected_path)
-probe_capture_script = build_probe_capture_script(capture_script, verification_mode, proof_session_seed)
+probe_capture_script = build_probe_capture_script(capture_script, verification_mode, proof_session_seed, s.get('viewport_matrix'))
 results = {
     'baseline': {
         'reference': reference,
@@ -2297,9 +2642,30 @@ else:
         results['after'] = {'screenshots': [{'url': capture.get('url', '')}] if capture.get('url') else [], 'raw': capture.get('raw')}
         s['after_cdn'] = capture.get('url', '')
 
+after_viewport_matrix = capture_viewport_matrix_status(s, after_payload, 'after-proof')
 after_observation = evaluate_capture_quality(after_payload, expected_path, verification_mode)
+details = after_observation.get('details') if isinstance(after_observation.get('details'), dict) else {}
+details['viewport_matrix'] = after_viewport_matrix
+after_observation['details'] = details
+if after_viewport_matrix.get('status') == 'incomplete':
+    missing_names = [
+        str(item.get('name') or item.get('slug') or '').strip()
+        for item in after_viewport_matrix.get('missing') or []
+        if str(item.get('name') or item.get('slug') or '').strip()
+    ]
+    missing_text = ', '.join(missing_names[:8]) or 'requested viewport screenshots'
+    reason = 'missing requested viewport evidence: ' + missing_text
+    after_observation['valid'] = False
+    after_observation['telemetry_ready'] = False
+    after_observation['reason'] = (
+        (after_observation.get('reason') + '; ' + reason)
+        if after_observation.get('reason') and after_observation.get('reason') != 'ok'
+        else reason
+    )
+s['viewport_matrix_status'] = after_viewport_matrix
 results['after']['observation'] = after_observation
 results['after']['supporting_artifacts'] = collect_supporting_artifacts(after_payload)
+results['after']['viewport_matrix'] = after_viewport_matrix
 record_verify_phase('capture', 'completed', 'After-proof capture completed.')
 
 # Structured proof summary
@@ -2338,6 +2704,8 @@ if existing_before:
 if existing_prod:
     summary_lines.append('Prod baseline (recon): ' + existing_prod)
 summary_lines.append('After screenshot: ' + (s.get('after_cdn') or '(none)'))
+if after_viewport_matrix.get('status') not in ('not_requested', ''):
+    summary_lines.append('Viewport matrix: ' + after_viewport_matrix.get('status', 'unknown') + ' (' + str(len(after_viewport_matrix.get('executed') or [])) + '/' + str(len(after_viewport_matrix.get('requested') or [])) + ' captured)')
 summary_lines.append('Expected proof path from recon: ' + expected_path)
 summary_lines.append('After observation: ' + after_observation['reason'])
 supporting = results['after'].get('supporting_artifacts') or {}