@riddledc/riddle-proof 0.7.177 → 0.7.179

package/README.md

@@ -240,6 +240,7 @@ The package includes generic starter profiles:
 - `examples/profiles/handled-recovery-list-load.json` for failed or malformed list-load recovery profiles.
 - `examples/profiles/handled-recovery-action-malformed-success.json` for action recovery profiles where the request succeeds at HTTP level but returns an unusable body.
 - `examples/profiles/terminal-result-partial-evidence.json` for API-console terminal error or timeout receipts that preserve partial screenshot, console, and HAR evidence.
+- `examples/profiles/gameplay-window-call-until.json` for gameplay profiles that wait on a runtime state contract instead of a fixed sleep.
 
 Copy one of those shapes into a repository profile directory and replace the
 routes, selectors, mock URLs, and text checks with app-specific invariants.
@@ -487,6 +488,10 @@ progressive state until a window-state receipt is true. It accepts `path` plus
 optional `args`, `until_path`, `until_expected_value`, `max_calls` from 1 to
 100, and optional `interval_ms`; the action stops early when the predicate is
 met and records `call_count`, final `returned`, and final `until_value`.
+For gameplay progression, prefer this to a fixed `wait` when frame cadence or
+hosted-runner timing can vary by viewport; install a small `window` helper that
+returns JSON-safe state, stores the latest receipt, and makes the pass condition
+explicit. See `examples/profiles/gameplay-window-call-until.json`.
 Use `screenshot` with an optional `label` to capture durable Riddle screenshots
 at important setup milestones, such as after a route switch, terminal state, or
 reset. These labels are recorded in setup evidence and included in profile

package/dist/cli.cjs

@@ -16646,6 +16646,19 @@ function profileSetupSummaryMarkdown(result) {
     return receipts.map((receipt) => ({ name, receipt }));
   });
   const pressDetails = pressGroups.flat();
+  for (const group of pressGroups.slice(0, 8)) {
+    if (!group.length) continue;
+    const name = group[0].name;
+    const keys = group.map(({ receipt }) => cliString(receipt.key) || "key").filter(Boolean);
+    const ordinals = group.map(({ receipt }) => cliFiniteNumber(receipt.ordinal)).filter((value) => value !== void 0);
+    const visibleKeys = keys.slice(0, 16);
+    const omittedKeyCount = Math.max(0, keys.length - visibleKeys.length);
+    const visibleOrdinals = ordinals.slice(0, 16);
+    const omittedOrdinalCount = Math.max(0, ordinals.length - visibleOrdinals.length);
+    const keyText = visibleKeys.join(",");
+    const ordinalText = visibleOrdinals.join(",");
+    lines.push(`- ${name} press_sequence: keys ${markdownInlineCode(keyText, 200)}${omittedKeyCount ? ` (+${omittedKeyCount} omitted)` : ""}${ordinalText ? `, ordinals ${markdownInlineCode(ordinalText, 120)}${omittedOrdinalCount ? ` (+${omittedOrdinalCount} omitted)` : ""}` : ""}`);
+  }
   const sampledPressDetails = balancedSetupReceiptDetails(pressGroups, 12);
   for (const { name, receipt } of sampledPressDetails) {
     const key = cliString(receipt.key) || "key";

package/dist/cli.js

@@ -929,6 +929,19 @@ function profileSetupSummaryMarkdown(result) {
     return receipts.map((receipt) => ({ name, receipt }));
   });
   const pressDetails = pressGroups.flat();
+  for (const group of pressGroups.slice(0, 8)) {
+    if (!group.length) continue;
+    const name = group[0].name;
+    const keys = group.map(({ receipt }) => cliString(receipt.key) || "key").filter(Boolean);
+    const ordinals = group.map(({ receipt }) => cliFiniteNumber(receipt.ordinal)).filter((value) => value !== void 0);
+    const visibleKeys = keys.slice(0, 16);
+    const omittedKeyCount = Math.max(0, keys.length - visibleKeys.length);
+    const visibleOrdinals = ordinals.slice(0, 16);
+    const omittedOrdinalCount = Math.max(0, ordinals.length - visibleOrdinals.length);
+    const keyText = visibleKeys.join(",");
+    const ordinalText = visibleOrdinals.join(",");
+    lines.push(`- ${name} press_sequence: keys ${markdownInlineCode(keyText, 200)}${omittedKeyCount ? ` (+${omittedKeyCount} omitted)` : ""}${ordinalText ? `, ordinals ${markdownInlineCode(ordinalText, 120)}${omittedOrdinalCount ? ` (+${omittedOrdinalCount} omitted)` : ""}` : ""}`);
+  }
   const sampledPressDetails = balancedSetupReceiptDetails(pressGroups, 12);
   for (const { name, receipt } of sampledPressDetails) {
     const key = cliString(receipt.key) || "key";

package/examples/profiles/gameplay-window-call-until.json

@@ -0,0 +1,101 @@
+{
+  "version": "riddle-proof.profile.v1",
+  "name": "gameplay-window-call-until",
+  "target": {
+    "route": "/games/example",
+    "viewports": [
+      { "name": "mobile", "width": 390, "height": 844 },
+      { "name": "tablet", "width": 820, "height": 1180 },
+      { "name": "desktop", "width": 1440, "height": 1000 }
+    ],
+    "timeout_sec": 300,
+    "wait_for_selector": "#game-root canvas",
+    "screenshot_mode": "viewport",
+    "setup_actions": [
+      { "type": "clear_storage", "storage": "both", "reload": true },
+      { "type": "wait_for_selector", "selector": "#game-root", "timeout_ms": 20000 },
+      { "type": "wait_for_selector", "selector": "#game-root canvas", "timeout_ms": 20000 },
+      {
+        "type": "window_eval",
+        "label": "install-gameplay-proof-reader",
+        "timeout_ms": 10000,
+        "store_return_to": "__gameplayProof.ready",
+        "script": "window.__riddleGameplayStep=()=>{const api=window.__exampleGameProof;const state=api?.step?.()||api?.read?.()||{};const out={ready:state.ready===true,inputAccepted:state.inputAccepted===true,gameOver:state.gameOver===true,distance:Number(state.distance||0),score:Number(state.score||0),level:Number(state.level||0)};out.ok=out.ready&&out.inputAccepted&&out.gameOver===false&&out.distance>=2&&out.score>=10;window.__gameplayProof={...(window.__gameplayProof||{}),running:out};return out;};const api=window.__exampleGameProof;const initial=api?.read?.()||{};const out={ready:initial.ready===true,inputAccepted:initial.inputAccepted===true,gameOver:initial.gameOver===true,distance:Number(initial.distance||0),score:Number(initial.score||0),level:Number(initial.level||0)};window.__gameplayProof={...(window.__gameplayProof||{}),ready:out};return out;",
+        "return_summary_fields": [
+          { "path": "ready" },
+          { "path": "inputAccepted" },
+          { "path": "distance" },
+          { "path": "score" },
+          { "path": "gameOver" }
+        ]
+      },
+      { "type": "assert_window_value", "path": "__gameplayProof.ready.ready", "expected": true, "timeout_ms": 10000 },
+      {
+        "type": "canvas_signature",
+        "selector": "#game-root canvas",
+        "label": "ready",
+        "store_signature_to": "__gameplayProof.readyCanvas",
+        "timeout_ms": 10000
+      },
+      { "type": "screenshot", "label": "ready", "mode": "viewport" },
+      { "type": "press", "key": "Space", "after_ms": 120 },
+      { "type": "press", "key": "ArrowRight", "after_ms": 120 },
+      {
+        "type": "window_call_until",
+        "path": "__riddleGameplayStep",
+        "until_path": "__gameplayProof.running.ok",
+        "until_expected_value": true,
+        "max_calls": 36,
+        "interval_ms": 250,
+        "timeout_ms": 15000
+      },
+      {
+        "type": "window_eval",
+        "label": "capture-running-proof",
+        "timeout_ms": 10000,
+        "store_return_to": "__gameplayProof.running",
+        "script": "return window.__riddleGameplayStep?.()||{};",
+        "return_summary_fields": [
+          { "path": "ok" },
+          { "path": "distance" },
+          { "path": "score" },
+          { "path": "inputAccepted" },
+          { "path": "gameOver" }
+        ]
+      },
+      { "type": "assert_window_value", "path": "__gameplayProof.running.ok", "expected": true, "timeout_ms": 10000 },
+      { "type": "assert_window_value", "path": "__gameplayProof.running.gameOver", "expected": false, "timeout_ms": 10000 },
+      { "type": "assert_window_number", "path": "__gameplayProof.running.distance", "min_value": 2, "timeout_ms": 10000 },
+      { "type": "assert_window_number", "path": "__gameplayProof.running.score", "min_value": 10, "timeout_ms": 10000 },
+      {
+        "type": "canvas_signature",
+        "selector": "#game-root canvas",
+        "label": "running",
+        "store_signature_to": "__gameplayProof.runningCanvas",
+        "timeout_ms": 10000
+      },
+      { "type": "screenshot", "label": "running", "mode": "viewport" }
+    ]
+  },
+  "checks": [
+    { "type": "route_loaded", "expected_path": "/games/example" },
+    { "type": "selector_visible", "selector": "#game-root" },
+    { "type": "selector_visible", "selector": "#game-root canvas" },
+    { "type": "selector_count_equals", "selector": "#game-root canvas", "expected_count": 1 },
+    { "type": "text_absent", "pattern": "\\bNaN\\b" },
+    { "type": "text_absent", "pattern": "undefined", "flags": "i" },
+    { "type": "no_horizontal_overflow", "max_overflow_px": 1 },
+    { "type": "no_fatal_console_errors" },
+    { "type": "no_console_warnings" }
+  ],
+  "artifacts": ["screenshot", "console", "dom_summary", "proof_json"],
+  "baseline_policy": "invariant_only",
+  "failure_policy": {
+    "environment_blocked": "neutral",
+    "proof_insufficient": "fail",
+    "product_regression": "fail"
+  },
+  "metadata": {
+    "purpose": "Template for gameplay profiles where a route exposes window.__exampleGameProof.read() and optionally step(). Use window_call_until to wait for runtime state such as accepted input, distance, score, or level completion instead of relying on fixed sleeps that vary across hosted browser frame cadence."
+  }
+}

package/package.json

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