@riddledc/riddle-proof 0.7.178 → 0.7.180

package/README.md

@@ -192,6 +192,10 @@ riddle-proof-loop run-profile \
 Hosted profile runs emit Riddle poll progress to stderr while waiting. Use
 `--quiet` to suppress progress lines, or `--progress-every-ms` to tune the
 heartbeat cadence for long route-inventory or workflow profiles.
+By default, `run-profile` writes the full JSON result to stdout for automation.
+For agent loops where the saved artifacts are the source of truth, use
+`--result-format summary` to print the same compact Markdown summary that is
+written to `summary.md`, or `--result-format none` to leave stdout empty.
 Hosted `run-profile` submits package-generated profile scripts with
 `strict=false` by default because the generated runner is larger than Riddle's
 generic inline-script warning threshold. Use `--strict=true` when you
@@ -240,6 +244,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 +492,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

@@ -15765,7 +15765,7 @@ function usage() {
     "  riddle-proof-loop respond --state-path <path> --response-json <file|json|->",
     "  riddle-proof-loop respond --state-path <path> --decision <decision> --summary <text> [--payload-json <file|json|->]",
     "  riddle-proof-loop status --state-path <path>",
-    "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--runner riddle] [--strict true|false; default false] [--split-viewports true|false; default false] [--poll-attempts n] [--output <dir>|--output-dir <dir>] [--quiet]",
+    "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--runner riddle] [--strict true|false; default false] [--split-viewports true|false; default false] [--poll-attempts n] [--output <dir>|--output-dir <dir>] [--result-format json|summary|none; default json] [--quiet]",
     "  riddle-proof-loop profile-body-assertions --artifact <file|url|-> --candidates-json <file|json|-> [--required-json <file|json|->] [--format json|body-contains]",
     "  riddle-proof-loop profile-http-status-preflight --profile <file|json|-> --url <base-url> [--format json|summary]",
     "  riddle-proof-loop riddle-preview-deploy <build-dir> <label> [--framework spa|static]",
@@ -15842,6 +15842,21 @@ function optionInteger(options, fallback, ...keys) {
 function profileOutputDirOption(options) {
   return optionString(options, "output") ?? optionString(options, "outputDir");
 }
+function runProfileResultFormatOption(options) {
+  const format = optionString(options, "resultFormat") ?? "json";
+  if (format === "json" || format === "summary" || format === "none") return format;
+  throw new Error("--result-format must be json, summary, or none.");
+}
+function writeRunProfileResult(result, options) {
+  const format = runProfileResultFormatOption(options);
+  if (format === "none") return;
+  if (format === "summary") {
+    process.stdout.write(profileResultMarkdown(result));
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+}
 function previewFrameworkOption(options) {
   const framework = optionString(options, "framework") ?? "static";
   if (framework === "spa" || framework === "static") return framework;
@@ -17600,8 +17615,7 @@ async function main() {
       process.stderr.write(`${diagnosticLine}
 `);
     }
-    process.stdout.write(`${JSON.stringify(result, null, 2)}
-`);
+    writeRunProfileResult(result, options);
     process.exitCode = profileStatusExitCode(profile, result.status);
     return;
   }

package/dist/cli.js

@@ -48,7 +48,7 @@ function usage() {
     "  riddle-proof-loop respond --state-path <path> --response-json <file|json|->",
     "  riddle-proof-loop respond --state-path <path> --decision <decision> --summary <text> [--payload-json <file|json|->]",
     "  riddle-proof-loop status --state-path <path>",
-    "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--runner riddle] [--strict true|false; default false] [--split-viewports true|false; default false] [--poll-attempts n] [--output <dir>|--output-dir <dir>] [--quiet]",
+    "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--runner riddle] [--strict true|false; default false] [--split-viewports true|false; default false] [--poll-attempts n] [--output <dir>|--output-dir <dir>] [--result-format json|summary|none; default json] [--quiet]",
     "  riddle-proof-loop profile-body-assertions --artifact <file|url|-> --candidates-json <file|json|-> [--required-json <file|json|->] [--format json|body-contains]",
     "  riddle-proof-loop profile-http-status-preflight --profile <file|json|-> --url <base-url> [--format json|summary]",
     "  riddle-proof-loop riddle-preview-deploy <build-dir> <label> [--framework spa|static]",
@@ -125,6 +125,21 @@ function optionInteger(options, fallback, ...keys) {
 function profileOutputDirOption(options) {
   return optionString(options, "output") ?? optionString(options, "outputDir");
 }
+function runProfileResultFormatOption(options) {
+  const format = optionString(options, "resultFormat") ?? "json";
+  if (format === "json" || format === "summary" || format === "none") return format;
+  throw new Error("--result-format must be json, summary, or none.");
+}
+function writeRunProfileResult(result, options) {
+  const format = runProfileResultFormatOption(options);
+  if (format === "none") return;
+  if (format === "summary") {
+    process.stdout.write(profileResultMarkdown(result));
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+}
 function previewFrameworkOption(options) {
   const framework = optionString(options, "framework") ?? "static";
   if (framework === "spa" || framework === "static") return framework;
@@ -1883,8 +1898,7 @@ async function main() {
       process.stderr.write(`${diagnosticLine}
 `);
     }
-    process.stdout.write(`${JSON.stringify(result, null, 2)}
-`);
+    writeRunProfileResult(result, options);
     process.exitCode = profileStatusExitCode(profile, result.status);
     return;
   }

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.178",
+  "version": "0.7.180",
   "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
   "license": "MIT",
   "author": "RiddleDC",