@riddledc/riddle-proof 0.7.80 → 0.7.82

package/dist/types.d.cts

@@ -9,6 +9,20 @@ type RiddleProofVerificationMode = "proof" | "visual" | "interaction" | "playabl
 type RiddleProofDecision = "ready_to_ship" | "needs_richer_proof" | "revise_capture" | "needs_recon" | "needs_implementation" | (string & {});
 type RiddleProofStage = "preflight" | "setup" | "recon" | "author" | "implement" | "prove" | "verify" | "ship" | "notify" | (string & {});
 type RiddleProofArtifactRole = "baseline" | "after_proof" | "incidental" | "diagnostic" | (string & {});
+interface RiddleProofViewportCapture {
+    name?: string;
+    slug?: string;
+    width?: number;
+    height?: number;
+    screenshot_label?: string;
+    screenshot_url?: string;
+}
+interface RiddleProofViewportMatrixStatus {
+    status?: "not_requested" | "not_run" | "complete" | "incomplete" | (string & {});
+    requested?: RiddleProofViewportCapture[];
+    executed?: RiddleProofViewportCapture[];
+    missing?: RiddleProofViewportCapture[];
+}
 interface RiddleProofRunParams {
     repo?: string;
     branch?: string;
@@ -201,6 +215,7 @@ interface RiddleProofRunCard {
         visual_delta?: Record<string, unknown> | null;
         evidence_issue_code?: string | null;
         proof_evidence_present?: boolean;
+        viewport_matrix?: RiddleProofViewportMatrixStatus;
         artifacts?: RiddleProofCheckpointArtifact[];
     };
     observability?: {
@@ -285,6 +300,7 @@ interface RiddleProofRunState {
     implementation_detection_summary?: string | null;
     implementation_detection?: Record<string, unknown> | null;
     proof_session?: RiddleProofVisualSession;
+    viewport_matrix_status?: RiddleProofViewportMatrixStatus;
     finalized?: boolean;
     blocker?: RiddleProofBlocker;
     checkpoint_packet?: RiddleProofCheckpointPacket;
@@ -338,6 +354,7 @@ interface RiddleProofRunResult {
     proof_contract?: RiddleProofProofContract;
     run_card?: RiddleProofRunCard;
     proof_session?: RiddleProofVisualSession;
+    viewport_matrix_status?: RiddleProofViewportMatrixStatus;
     evidence_bundle?: RiddleProofEvidenceBundle;
     raw?: Record<string, unknown>;
 }
@@ -373,6 +390,7 @@ interface RiddleProofRunStatusSnapshot {
     state_paths?: RiddleProofStatePaths;
     proof_contract?: RiddleProofProofContract;
     run_card?: RiddleProofRunCard;
+    viewport_matrix_status?: RiddleProofViewportMatrixStatus;
     latest_event?: RiddleProofEvent;
 }
 interface RiddleProofEvidenceBundle {
@@ -381,6 +399,7 @@ interface RiddleProofEvidenceBundle {
     after?: EvidenceReference;
     artifacts?: EvidenceArtifact[];
     proof_session?: RiddleProofVisualSession;
+    viewport_matrix?: RiddleProofViewportMatrixStatus;
     proof_evidence?: unknown;
     playability_evidence?: unknown;
     proof_evidence_sample?: unknown;
@@ -572,6 +591,7 @@ interface RiddleProofVisualSession {
     };
     evidence?: {
         visual_delta?: JsonValue;
+        viewport_matrix?: RiddleProofViewportMatrixStatus;
         semantic_context?: JsonValue;
         artifact_contract?: JsonValue;
         artifact_usage?: JsonValue;
@@ -593,4 +613,4 @@ interface RiddleProofVisualSessionFingerprintBasis {
     capture_script_hash?: string;
 }
 
-export type { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, PreflightAdapter, PreflightAdapterInput, PreflightAdapterResult, ProofAdapter, ProofAdapterInput, ProofAdapterResult, RiddleProofArtifactRole, RiddleProofAssessment, RiddleProofBlocker, RiddleProofCheckpointArtifact, RiddleProofCheckpointPacket, RiddleProofCheckpointResponse, RiddleProofCheckpointRole, RiddleProofCheckpointRoutingHint, RiddleProofCheckpointSummary, RiddleProofCheckpointVisibility, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofPrLifecycleState, RiddleProofPrLifecycleStatus, RiddleProofProofContract, RiddleProofRunCard, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofRunStatusSnapshot, RiddleProofStage, RiddleProofStatePaths, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, RiddleProofVisualSession, RiddleProofVisualSessionFingerprintBasis, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter };
+export type { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, PreflightAdapter, PreflightAdapterInput, PreflightAdapterResult, ProofAdapter, ProofAdapterInput, ProofAdapterResult, RiddleProofArtifactRole, RiddleProofAssessment, RiddleProofBlocker, RiddleProofCheckpointArtifact, RiddleProofCheckpointPacket, RiddleProofCheckpointResponse, RiddleProofCheckpointRole, RiddleProofCheckpointRoutingHint, RiddleProofCheckpointSummary, RiddleProofCheckpointVisibility, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofPrLifecycleState, RiddleProofPrLifecycleStatus, RiddleProofProofContract, RiddleProofRunCard, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofRunStatusSnapshot, RiddleProofStage, RiddleProofStatePaths, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, RiddleProofViewportCapture, RiddleProofViewportMatrixStatus, RiddleProofVisualSession, RiddleProofVisualSessionFingerprintBasis, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter };

package/dist/types.d.ts

@@ -9,6 +9,20 @@ type RiddleProofVerificationMode = "proof" | "visual" | "interaction" | "playabl
 type RiddleProofDecision = "ready_to_ship" | "needs_richer_proof" | "revise_capture" | "needs_recon" | "needs_implementation" | (string & {});
 type RiddleProofStage = "preflight" | "setup" | "recon" | "author" | "implement" | "prove" | "verify" | "ship" | "notify" | (string & {});
 type RiddleProofArtifactRole = "baseline" | "after_proof" | "incidental" | "diagnostic" | (string & {});
+interface RiddleProofViewportCapture {
+    name?: string;
+    slug?: string;
+    width?: number;
+    height?: number;
+    screenshot_label?: string;
+    screenshot_url?: string;
+}
+interface RiddleProofViewportMatrixStatus {
+    status?: "not_requested" | "not_run" | "complete" | "incomplete" | (string & {});
+    requested?: RiddleProofViewportCapture[];
+    executed?: RiddleProofViewportCapture[];
+    missing?: RiddleProofViewportCapture[];
+}
 interface RiddleProofRunParams {
     repo?: string;
     branch?: string;
@@ -201,6 +215,7 @@ interface RiddleProofRunCard {
         visual_delta?: Record<string, unknown> | null;
         evidence_issue_code?: string | null;
         proof_evidence_present?: boolean;
+        viewport_matrix?: RiddleProofViewportMatrixStatus;
         artifacts?: RiddleProofCheckpointArtifact[];
     };
     observability?: {
@@ -285,6 +300,7 @@ interface RiddleProofRunState {
     implementation_detection_summary?: string | null;
     implementation_detection?: Record<string, unknown> | null;
     proof_session?: RiddleProofVisualSession;
+    viewport_matrix_status?: RiddleProofViewportMatrixStatus;
     finalized?: boolean;
     blocker?: RiddleProofBlocker;
     checkpoint_packet?: RiddleProofCheckpointPacket;
@@ -338,6 +354,7 @@ interface RiddleProofRunResult {
     proof_contract?: RiddleProofProofContract;
     run_card?: RiddleProofRunCard;
     proof_session?: RiddleProofVisualSession;
+    viewport_matrix_status?: RiddleProofViewportMatrixStatus;
     evidence_bundle?: RiddleProofEvidenceBundle;
     raw?: Record<string, unknown>;
 }
@@ -373,6 +390,7 @@ interface RiddleProofRunStatusSnapshot {
     state_paths?: RiddleProofStatePaths;
     proof_contract?: RiddleProofProofContract;
     run_card?: RiddleProofRunCard;
+    viewport_matrix_status?: RiddleProofViewportMatrixStatus;
     latest_event?: RiddleProofEvent;
 }
 interface RiddleProofEvidenceBundle {
@@ -381,6 +399,7 @@ interface RiddleProofEvidenceBundle {
     after?: EvidenceReference;
     artifacts?: EvidenceArtifact[];
     proof_session?: RiddleProofVisualSession;
+    viewport_matrix?: RiddleProofViewportMatrixStatus;
     proof_evidence?: unknown;
     playability_evidence?: unknown;
     proof_evidence_sample?: unknown;
@@ -572,6 +591,7 @@ interface RiddleProofVisualSession {
     };
     evidence?: {
         visual_delta?: JsonValue;
+        viewport_matrix?: RiddleProofViewportMatrixStatus;
         semantic_context?: JsonValue;
         artifact_contract?: JsonValue;
         artifact_usage?: JsonValue;
@@ -593,4 +613,4 @@ interface RiddleProofVisualSessionFingerprintBasis {
     capture_script_hash?: string;
 }
 
-export type { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, PreflightAdapter, PreflightAdapterInput, PreflightAdapterResult, ProofAdapter, ProofAdapterInput, ProofAdapterResult, RiddleProofArtifactRole, RiddleProofAssessment, RiddleProofBlocker, RiddleProofCheckpointArtifact, RiddleProofCheckpointPacket, RiddleProofCheckpointResponse, RiddleProofCheckpointRole, RiddleProofCheckpointRoutingHint, RiddleProofCheckpointSummary, RiddleProofCheckpointVisibility, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofPrLifecycleState, RiddleProofPrLifecycleStatus, RiddleProofProofContract, RiddleProofRunCard, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofRunStatusSnapshot, RiddleProofStage, RiddleProofStatePaths, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, RiddleProofVisualSession, RiddleProofVisualSessionFingerprintBasis, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter };
+export type { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, PreflightAdapter, PreflightAdapterInput, PreflightAdapterResult, ProofAdapter, ProofAdapterInput, ProofAdapterResult, RiddleProofArtifactRole, RiddleProofAssessment, RiddleProofBlocker, RiddleProofCheckpointArtifact, RiddleProofCheckpointPacket, RiddleProofCheckpointResponse, RiddleProofCheckpointRole, RiddleProofCheckpointRoutingHint, RiddleProofCheckpointSummary, RiddleProofCheckpointVisibility, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofPrLifecycleState, RiddleProofPrLifecycleStatus, RiddleProofProofContract, RiddleProofRunCard, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofRunStatusSnapshot, RiddleProofStage, RiddleProofStatePaths, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, RiddleProofViewportCapture, RiddleProofViewportMatrixStatus, RiddleProofVisualSession, RiddleProofVisualSessionFingerprintBasis, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter };

package/package.json

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

package/runtime/lib/preflight.py

@@ -15,6 +15,7 @@ from util import (
     invoke,
     load_package_json,
     load_proof_session_source,
+    normalize_viewport_matrix,
     save_state,
     validate_proof_session_resume,
 )
@@ -130,6 +131,12 @@ if raw_assertions:
         raise SystemExit('assertions_json is not valid JSON: ' + str(e))
 s['parsed_assertions'] = parsed_assertions
 s['viewport_matrix'] = parse_json_arg('viewport_matrix_json', (dict, list), None)
+s['viewport_matrix_status'] = {
+    'status': 'not_run' if normalize_viewport_matrix(s.get('viewport_matrix')) else 'not_requested',
+    'requested': normalize_viewport_matrix(s.get('viewport_matrix')),
+    'executed': [],
+    'missing': [],
+}
 s['deterministic_setup'] = parse_json_arg('deterministic_setup_json', (dict, list), None)
 
 # Generate branch if not provided. The riddle-proof/* namespace is reserved for

package/runtime/lib/recon.py

@@ -19,6 +19,7 @@ from util import (  # noqa: E402
     apply_auth_context,
     build_capture_script,
     capture_static_preview,
+    capture_viewport_matrix_status,
     enrich_capture_payload,
     has_auth_context,
     invoke_retry,
@@ -27,6 +28,9 @@ from util import (  # noqa: E402
     save_state,
     should_use_static_preview,
     summarize_capture_artifacts,
+    viewport_matrix_return_js,
+    viewport_matrix_screenshot_js,
+    viewport_matrix_setup_js,
 )
 import subprocess as sp
 
@@ -514,9 +518,10 @@ def route_matches_expected(expected_path, observed_path):
     return True
 
 
-def build_probe_capture_script(base_script='', screenshot_label=''):
+def build_probe_capture_script(base_script='', screenshot_label='', viewport_matrix=None):
     pieces = []
     script = (base_script or '').strip()
+    pieces.extend(viewport_matrix_setup_js(viewport_matrix))
     if script:
         pieces.append(script.rstrip(';') + ';')
     pieces.extend([
@@ -556,9 +561,12 @@ def build_probe_capture_script(base_script='', screenshot_label=''):
         'console.log(' + json.dumps(PAGE_STATE_PREFIX) + ' + JSON.stringify(pageState));',
     ])
     label = (screenshot_label or '').strip()
-    if label and 'saveScreenshot' not in script:
+    viewport_screenshot_lines = viewport_matrix_screenshot_js(label, viewport_matrix)
+    if label and viewport_screenshot_lines:
+        pieces.extend(viewport_screenshot_lines)
+    elif label and 'saveScreenshot' not in script:
         pieces.append('await saveScreenshot(' + json.dumps(label) + ');')
-    pieces.append('return { pageState };')
+    pieces.append('return { pageState, viewportMatrix: ' + viewport_matrix_return_js() + ' };')
     return ' '.join(pieces)
 
 
@@ -727,7 +735,7 @@ def capture_workspace_baseline(project_dir, label, plan, capture_script=''):
             'exclude': server_exclude,
             'path': target_path,
             'readiness_path': '/' if has_auth_context(s) else target_path,
-            'script': build_probe_capture_script(capture_script, label),
+            'script': build_probe_capture_script(capture_script, label, s.get('viewport_matrix')),
         }
         if s.get('color_scheme'):
             server_args['color_scheme'] = s['color_scheme']
@@ -757,7 +765,7 @@ def capture_workspace_baseline(project_dir, label, plan, capture_script=''):
         print('Recon capture (' + label + ') using static preview fallback: ' + static_reason)
     capture_phase = label + '_capture'
     record_recon_phase(capture_phase, 'running', 'Capturing ' + label + ' recon baseline evidence.')
-    capture = capture_static_preview(state_for_capture, project_dir, label, build_probe_capture_script(capture_script, label), timeout=300, target_path=target_path)
+    capture = capture_static_preview(state_for_capture, project_dir, label, build_probe_capture_script(capture_script, label, s.get('viewport_matrix')), timeout=300, target_path=target_path)
     raw = (capture.get('raw') or {}).get('capture') or {}
     append_capture_diagnostic(
         s,
@@ -787,7 +795,7 @@ def capture_prod_baseline(prod_url, plan, capture_script=''):
     if not target_url:
         raise SystemExit('Requested prod baseline in recon, but prod_url is missing.')
     wait_for_selector = (plan.get('wait_for_selector') or '').strip()
-    script = build_capture_script(target_url, build_probe_capture_script(capture_script, 'prod'), 'prod', wait_for_selector)
+    script = build_capture_script(target_url, build_probe_capture_script(capture_script, 'prod', s.get('viewport_matrix')), 'prod', wait_for_selector, s.get('viewport_matrix'))
     args = {'script': script, 'timeout_sec': 60}
     apply_auth_context(s, args)
     print('Recon capture (prod) at ' + target_url)
@@ -815,6 +823,7 @@ def baseline_record(capture, observation):
         'url': capture.get('url'),
         'static_fallback_reason': capture.get('static_fallback_reason', ''),
         'artifact_summary': summarize_capture_artifacts(capture.get('raw') or {}),
+        'viewport_matrix': capture_viewport_matrix_status(s, capture.get('raw') or {}, str(observation.get('label') or '')),
         'observation': observation,
     }
 
@@ -833,6 +842,24 @@ def build_observation_packet(label, expected_path, capture=None, error=''):
 
     payload = (capture or {}).get('raw') or {}
     quality = evaluate_capture_quality(payload, expected_path)
+    viewport_matrix = capture_viewport_matrix_status(s, payload, label)
+    if viewport_matrix.get('status') == 'incomplete':
+        missing_names = [
+            str(item.get('name') or item.get('slug') or '').strip()
+            for item in 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'
+        quality['valid'] = False
+        quality['telemetry_ready'] = False
+        quality['reason'] = (
+            quality.get('reason') + '; missing requested viewport evidence: ' + missing_text
+            if quality.get('reason') and quality.get('reason') != 'ok'
+            else 'missing requested viewport evidence: ' + missing_text
+        )
+    details = quality.get('details') if isinstance(quality.get('details'), dict) else {}
+    details['viewport_matrix'] = viewport_matrix
+    quality['details'] = details
     return {
         'label': label,
         'ok': bool((capture or {}).get('url')) and quality['valid'],
@@ -1042,6 +1069,13 @@ attempt_record = {
     'captured_baselines': attempt_captured_baselines,
     'result': attempt_result,
 }
+if attempt_captured_baselines:
+    latest_viewport_status = None
+    for baseline in attempt_captured_baselines.values():
+        if isinstance(baseline, dict) and isinstance(baseline.get('viewport_matrix'), dict):
+            latest_viewport_status = baseline.get('viewport_matrix')
+    if latest_viewport_status:
+        s['viewport_matrix_status'] = latest_viewport_status
 attempt_history.append(attempt_record)
 recon_results['attempt_history'] = attempt_history
 recon_results['baselines'] = {}

package/runtime/lib/util.py

@@ -948,8 +948,153 @@ def join_url_path(base_url, target_path=''):
     return urljoin(base.rstrip('/') + '/', path.lstrip('/'))
 
 
-def build_capture_script(url, capture_script, label, wait_for_selector=''):
+def slugify_viewport_name(value, fallback='viewport'):
+    text = re.sub(r'[^a-zA-Z0-9]+', '-', str(value or '').strip().lower()).strip('-')
+    return text or fallback
+
+
+def normalize_viewport_matrix(value):
+    matrix = value
+    if isinstance(matrix, dict):
+        for key in ('viewports', 'viewport_matrix', 'matrix'):
+            if isinstance(matrix.get(key), list):
+                matrix = matrix.get(key)
+                break
+        else:
+            matrix = [matrix]
+    if not isinstance(matrix, list):
+        return []
+
+    normalized = []
+    for index, item in enumerate(matrix):
+        if not isinstance(item, dict):
+            continue
+        try:
+            width = int(item.get('width'))
+            height = int(item.get('height'))
+        except Exception:
+            continue
+        if width <= 0 or height <= 0:
+            continue
+        raw_name = str(item.get('name') or item.get('label') or '').strip()
+        name = raw_name or f'{width}x{height}'
+        slug = slugify_viewport_name(name, f'viewport-{index + 1}')
+        normalized.append({
+            'name': name,
+            'slug': slug,
+            'width': width,
+            'height': height,
+        })
+    return normalized
+
+
+def viewport_screenshot_label(label, viewport):
+    return (str(label or 'screenshot').strip() or 'screenshot') + '-' + str(viewport.get('slug') or viewport.get('name') or 'viewport')
+
+
+def viewport_matrix_setup_js(viewport_matrix):
+    viewports = normalize_viewport_matrix(viewport_matrix)
+    if not viewports:
+        return []
+    return [
+        'const __riddleProofViewportMatrix = ' + json.dumps(viewports) + ';',
+        'const __riddleProofViewportResults = [];',
+        'const __riddleProofApplyViewport = async (vp) => {',
+        '  if (!vp || !vp.width || !vp.height) return;',
+        '  await page.setViewportSize({ width: Number(vp.width), height: Number(vp.height) });',
+        '};',
+        'await __riddleProofApplyViewport(__riddleProofViewportMatrix[0]);',
+    ]
+
+
+def viewport_matrix_screenshot_js(label, viewport_matrix):
+    viewports = normalize_viewport_matrix(viewport_matrix)
+    if not viewports:
+        return []
+    base_label = str(label or 'screenshot').strip() or 'screenshot'
+    return [
+        'for (const __riddleProofViewport of __riddleProofViewportMatrix) {',
+        '  await __riddleProofApplyViewport(__riddleProofViewport);',
+        '  await page.waitForTimeout(250);',
+        '  const __riddleProofViewportLabel = ' + json.dumps(base_label) + ' + "-" + (__riddleProofViewport.slug || __riddleProofViewport.name || "viewport");',
+        '  await saveScreenshot(__riddleProofViewportLabel);',
+        '  __riddleProofViewportResults.push({',
+        '    name: __riddleProofViewport.name || "",',
+        '    slug: __riddleProofViewport.slug || "",',
+        '    width: Number(__riddleProofViewport.width) || null,',
+        '    height: Number(__riddleProofViewport.height) || null,',
+        '    screenshot_label: __riddleProofViewportLabel,',
+        '  });',
+        '}',
+    ]
+
+
+def viewport_matrix_return_js():
+    return 'typeof __riddleProofViewportMatrix !== "undefined" ? { requested: __riddleProofViewportMatrix, executed: __riddleProofViewportResults } : null'
+
+
+def capture_viewport_matrix_status(state, payload, label=''):
+    requested = normalize_viewport_matrix((state or {}).get('viewport_matrix'))
+    if not requested:
+        return {
+            'status': 'not_requested',
+            'requested': [],
+            'executed': [],
+            'missing': [],
+        }
+
+    artifact_summary = summarize_capture_artifacts(payload)
+    image_items = []
+    for key in ('outputs', 'screenshots', 'artifacts'):
+        for item in artifact_summary.get(key) or []:
+            if isinstance(item, dict):
+                image_items.append(item)
+
+    executed = []
+    missing = []
+    for viewport in requested:
+        expected_label = viewport_screenshot_label(label, viewport)
+        expected_names = {
+            expected_label,
+            expected_label + '.png',
+            expected_label + '.jpg',
+            expected_label + '.jpeg',
+            expected_label + '.webp',
+            expected_label + '.gif',
+        }
+        match = None
+        for item in image_items:
+            name = str(item.get('name') or '')
+            url = str(item.get('url') or '')
+            if name in expected_names and url:
+                match = item
+                break
+        record = {
+            'name': viewport.get('name'),
+            'slug': viewport.get('slug'),
+            'width': viewport.get('width'),
+            'height': viewport.get('height'),
+            'screenshot_label': expected_label,
+            'screenshot_url': str((match or {}).get('url') or ''),
+        }
+        if match:
+            executed.append(record)
+        else:
+            missing.append(record)
+
+    return {
+        'status': 'complete' if not missing else 'incomplete',
+        'requested': requested,
+        'executed': executed,
+        'missing': missing,
+    }
+
+
+def build_capture_script(url, capture_script, label, wait_for_selector='', viewport_matrix=None):
+    script_handles_viewport_matrix = '__riddleProofViewportMatrix' in (capture_script or '')
+    effective_viewport_matrix = None if script_handles_viewport_matrix else viewport_matrix
     pieces = [
+        *viewport_matrix_setup_js(effective_viewport_matrix),
         'await page.goto(' + json.dumps(url) + ');',
     ]
     selector = (wait_for_selector or '').strip()
@@ -958,8 +1103,11 @@ def build_capture_script(url, capture_script, label, wait_for_selector=''):
     pieces.append('await page.waitForTimeout(1500);')
     if (capture_script or '').strip():
         pieces.append((capture_script or '').strip().rstrip(';') + ';')
-    if not capture_script_saves_screenshot(capture_script):
+    if normalize_viewport_matrix(effective_viewport_matrix):
+        pieces.extend(viewport_matrix_screenshot_js(label, effective_viewport_matrix))
+    elif not capture_script_saves_screenshot(capture_script):
         pieces.append('await saveScreenshot(' + json.dumps(label) + ');')
+    pieces.append('return { viewportMatrix: ' + viewport_matrix_return_js() + ' };')
     return ' '.join(pieces)
 
 
@@ -987,7 +1135,7 @@ def capture_static_preview(state, project_dir, label, capture_script, timeout=30
     preview_id = preview.get('id', '')
     capture_url = join_url_path(preview_url, target_path or state.get('server_path', ''))
 
-    script = build_capture_script(capture_url, capture_script, label, state.get('wait_for_selector', ''))
+    script = build_capture_script(capture_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))