@riddledc/riddle-proof 0.5.55 → 0.5.56

package/dist/basic-gameplay.cjs

@@ -21,14 +21,17 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var basic_gameplay_exports = {};
 __export(basic_gameplay_exports, {
   RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION: () => RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
+  RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION: () => RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION,
   RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION: () => RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION,
   assessBasicGameplayEvidence: () => assessBasicGameplayEvidence,
   assessBasicGameplayRoute: () => assessBasicGameplayRoute,
+  createBasicGameplayCatchSummary: () => createBasicGameplayCatchSummary,
   extractBasicGameplayEvidence: () => extractBasicGameplayEvidence
 });
 module.exports = __toCommonJS(basic_gameplay_exports);
 var RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION = "riddle-proof.basic-gameplay.v1";
 var RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION = "riddle-proof.basic-gameplay.assessment.v1";
+var RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION = "riddle-proof.basic-gameplay.catch.v1";
 var BASIC_GAMEPLAY_CONTAINER_KEYS = [
   "basic_gameplay",
   "basicGameplay",
@@ -138,6 +141,37 @@ function assessBasicGameplayRoute(route, options = {}) {
     }
   };
 }
+function createBasicGameplayCatchSummary(input, options = {}) {
+  const before = summarizeAssessment(assessBasicGameplayEvidence(input.before, options));
+  const after = input.after === void 0 ? void 0 : summarizeAssessment(assessBasicGameplayEvidence(input.after, options));
+  const fixed = Boolean(after && before.notable_codes.length > 0 && after.passed && after.notable_codes.length === 0);
+  const title = input.title || [
+    input.site || "Basic gameplay",
+    input.route ? `${input.route} proof catch` : "proof catch"
+  ].join(" ");
+  const beforeCodes = before.notable_codes.length ? before.notable_codes.join(", ") : "no failing or warning codes";
+  const afterCodes = after ? after.notable_codes.length ? after.notable_codes.join(", ") : "no failing or warning codes" : "not verified";
+  const summaryLines = [
+    `Before: ${before.checked_routes} checked, ${before.passing_routes} passing, codes: ${beforeCodes}.`,
+    after ? `After: ${after.checked_routes} checked, ${after.passing_routes} passing, codes: ${afterCodes}.` : "After: not provided."
+  ];
+  if (input.fix?.summary) summaryLines.push(`Fix: ${input.fix.summary}`);
+  if (input.artifacts?.length) summaryLines.push(`Artifacts: ${input.artifacts.length} attached.`);
+  return {
+    version: RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION,
+    title,
+    site: input.site,
+    route: input.route,
+    detected_at: input.detected_at || (/* @__PURE__ */ new Date()).toISOString(),
+    before,
+    after,
+    fixed,
+    fix: input.fix,
+    artifacts: input.artifacts || [],
+    summary_lines: summaryLines,
+    marketing_summary: fixed ? `${title}: Riddle Proof caught ${beforeCodes}; after the fix, ${afterCodes}.` : `${title}: Riddle Proof caught ${beforeCodes}; after evidence is ${after ? "not yet clean" : "not yet attached"}.`
+  };
+}
 function extractBasicGameplayEvidence(...sources) {
   const seen = /* @__PURE__ */ new Set();
   for (const source of sources) {
@@ -146,6 +180,21 @@ function extractBasicGameplayEvidence(...sources) {
   }
   return null;
 }
+function summarizeAssessment(assessment) {
+  return {
+    evidence_present: assessment.evidence_present,
+    passed: assessment.passed,
+    checked_routes: assessment.checked_routes,
+    passing_routes: assessment.passing_routes,
+    failing_routes: assessment.failing_routes,
+    failure_counts: assessment.failure_counts,
+    warning_counts: assessment.warning_counts,
+    notable_codes: [
+      ...Object.keys(assessment.failure_counts),
+      ...Object.keys(assessment.warning_counts)
+    ].sort()
+  };
+}
 function findBasicGameplayEvidence(value, seen, depth = 0) {
   if (depth > 6 || value === null || value === void 0) return null;
   if (typeof value === "string") {
@@ -248,8 +297,10 @@ function parseJson(value) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
+  RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION,
   RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION,
   assessBasicGameplayEvidence,
   assessBasicGameplayRoute,
+  createBasicGameplayCatchSummary,
   extractBasicGameplayEvidence
 });

package/dist/basic-gameplay.d.cts

@@ -1,5 +1,6 @@
 declare const RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION = "riddle-proof.basic-gameplay.v1";
 declare const RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION = "riddle-proof.basic-gameplay.assessment.v1";
+declare const RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION = "riddle-proof.basic-gameplay.catch.v1";
 type BasicGameplayFailureCode = "route_http_error" | "fatal_page_error" | "route_blank_or_thin" | "no_game_surface" | "mobile_horizontal_overflow" | "primary_control_missing" | "primary_control_inert";
 type BasicGameplayWarningCode = "canvas_inert" | "some_actions_failed" | "missing_reset_path" | "critical_console_error";
 interface BasicGameplayCanvasState {
@@ -110,8 +111,59 @@ interface RiddleProofBasicGameplayAssessment {
     warning_counts: Record<string, number>;
     route_results: RiddleProofBasicGameplayRouteAssessment[];
 }
+interface BasicGameplayProofArtifact {
+    name: string;
+    role?: string;
+    kind?: string;
+    url?: string;
+    path?: string;
+    sha256?: string;
+    [key: string]: unknown;
+}
+interface BasicGameplayFixReference {
+    repo?: string;
+    commit?: string;
+    pr_url?: string;
+    summary?: string;
+    [key: string]: unknown;
+}
+interface CreateBasicGameplayCatchSummaryInput {
+    title?: string;
+    site?: string;
+    route?: string;
+    detected_at?: string;
+    before: unknown;
+    after?: unknown;
+    fix?: BasicGameplayFixReference;
+    artifacts?: BasicGameplayProofArtifact[];
+}
+interface BasicGameplayAssessmentSummary {
+    evidence_present: boolean;
+    passed: boolean;
+    checked_routes: number;
+    passing_routes: number;
+    failing_routes: RiddleProofBasicGameplayAssessment["failing_routes"];
+    failure_counts: Record<string, number>;
+    warning_counts: Record<string, number>;
+    notable_codes: string[];
+}
+interface RiddleProofBasicGameplayCatchSummary {
+    version: typeof RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION;
+    title: string;
+    site?: string;
+    route?: string;
+    detected_at: string;
+    before: BasicGameplayAssessmentSummary;
+    after?: BasicGameplayAssessmentSummary;
+    fixed: boolean;
+    fix?: BasicGameplayFixReference;
+    artifacts: BasicGameplayProofArtifact[];
+    summary_lines: string[];
+    marketing_summary: string;
+}
 declare function assessBasicGameplayEvidence(evidence: unknown, options?: AssessBasicGameplayOptions): RiddleProofBasicGameplayAssessment;
 declare function assessBasicGameplayRoute(route: RiddleProofBasicGameplayRouteEvidence, options?: AssessBasicGameplayOptions): RiddleProofBasicGameplayRouteAssessment;
+declare function createBasicGameplayCatchSummary(input: CreateBasicGameplayCatchSummaryInput, options?: AssessBasicGameplayOptions): RiddleProofBasicGameplayCatchSummary;
 declare function extractBasicGameplayEvidence(...sources: unknown[]): RiddleProofBasicGameplayEvidence | null;
 
-export { type AssessBasicGameplayOptions, type BasicGameplayActionResult, type BasicGameplayCanvasState, type BasicGameplayChangeSummary, type BasicGameplayFailureCode, type BasicGameplayMobileEvidence, type BasicGameplaySnapshot, type BasicGameplayWarningCode, RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION, type RiddleProofBasicGameplayAssessment, type RiddleProofBasicGameplayEvidence, type RiddleProofBasicGameplayRouteAssessment, type RiddleProofBasicGameplayRouteEvidence, assessBasicGameplayEvidence, assessBasicGameplayRoute, extractBasicGameplayEvidence };
+export { type AssessBasicGameplayOptions, type BasicGameplayActionResult, type BasicGameplayAssessmentSummary, type BasicGameplayCanvasState, type BasicGameplayChangeSummary, type BasicGameplayFailureCode, type BasicGameplayFixReference, type BasicGameplayMobileEvidence, type BasicGameplayProofArtifact, type BasicGameplaySnapshot, type BasicGameplayWarningCode, type CreateBasicGameplayCatchSummaryInput, RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION, type RiddleProofBasicGameplayAssessment, type RiddleProofBasicGameplayCatchSummary, type RiddleProofBasicGameplayEvidence, type RiddleProofBasicGameplayRouteAssessment, type RiddleProofBasicGameplayRouteEvidence, assessBasicGameplayEvidence, assessBasicGameplayRoute, createBasicGameplayCatchSummary, extractBasicGameplayEvidence };

package/dist/basic-gameplay.d.ts

@@ -1,5 +1,6 @@
 declare const RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION = "riddle-proof.basic-gameplay.v1";
 declare const RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION = "riddle-proof.basic-gameplay.assessment.v1";
+declare const RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION = "riddle-proof.basic-gameplay.catch.v1";
 type BasicGameplayFailureCode = "route_http_error" | "fatal_page_error" | "route_blank_or_thin" | "no_game_surface" | "mobile_horizontal_overflow" | "primary_control_missing" | "primary_control_inert";
 type BasicGameplayWarningCode = "canvas_inert" | "some_actions_failed" | "missing_reset_path" | "critical_console_error";
 interface BasicGameplayCanvasState {
@@ -110,8 +111,59 @@ interface RiddleProofBasicGameplayAssessment {
     warning_counts: Record<string, number>;
     route_results: RiddleProofBasicGameplayRouteAssessment[];
 }
+interface BasicGameplayProofArtifact {
+    name: string;
+    role?: string;
+    kind?: string;
+    url?: string;
+    path?: string;
+    sha256?: string;
+    [key: string]: unknown;
+}
+interface BasicGameplayFixReference {
+    repo?: string;
+    commit?: string;
+    pr_url?: string;
+    summary?: string;
+    [key: string]: unknown;
+}
+interface CreateBasicGameplayCatchSummaryInput {
+    title?: string;
+    site?: string;
+    route?: string;
+    detected_at?: string;
+    before: unknown;
+    after?: unknown;
+    fix?: BasicGameplayFixReference;
+    artifacts?: BasicGameplayProofArtifact[];
+}
+interface BasicGameplayAssessmentSummary {
+    evidence_present: boolean;
+    passed: boolean;
+    checked_routes: number;
+    passing_routes: number;
+    failing_routes: RiddleProofBasicGameplayAssessment["failing_routes"];
+    failure_counts: Record<string, number>;
+    warning_counts: Record<string, number>;
+    notable_codes: string[];
+}
+interface RiddleProofBasicGameplayCatchSummary {
+    version: typeof RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION;
+    title: string;
+    site?: string;
+    route?: string;
+    detected_at: string;
+    before: BasicGameplayAssessmentSummary;
+    after?: BasicGameplayAssessmentSummary;
+    fixed: boolean;
+    fix?: BasicGameplayFixReference;
+    artifacts: BasicGameplayProofArtifact[];
+    summary_lines: string[];
+    marketing_summary: string;
+}
 declare function assessBasicGameplayEvidence(evidence: unknown, options?: AssessBasicGameplayOptions): RiddleProofBasicGameplayAssessment;
 declare function assessBasicGameplayRoute(route: RiddleProofBasicGameplayRouteEvidence, options?: AssessBasicGameplayOptions): RiddleProofBasicGameplayRouteAssessment;
+declare function createBasicGameplayCatchSummary(input: CreateBasicGameplayCatchSummaryInput, options?: AssessBasicGameplayOptions): RiddleProofBasicGameplayCatchSummary;
 declare function extractBasicGameplayEvidence(...sources: unknown[]): RiddleProofBasicGameplayEvidence | null;
 
-export { type AssessBasicGameplayOptions, type BasicGameplayActionResult, type BasicGameplayCanvasState, type BasicGameplayChangeSummary, type BasicGameplayFailureCode, type BasicGameplayMobileEvidence, type BasicGameplaySnapshot, type BasicGameplayWarningCode, RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION, type RiddleProofBasicGameplayAssessment, type RiddleProofBasicGameplayEvidence, type RiddleProofBasicGameplayRouteAssessment, type RiddleProofBasicGameplayRouteEvidence, assessBasicGameplayEvidence, assessBasicGameplayRoute, extractBasicGameplayEvidence };
+export { type AssessBasicGameplayOptions, type BasicGameplayActionResult, type BasicGameplayAssessmentSummary, type BasicGameplayCanvasState, type BasicGameplayChangeSummary, type BasicGameplayFailureCode, type BasicGameplayFixReference, type BasicGameplayMobileEvidence, type BasicGameplayProofArtifact, type BasicGameplaySnapshot, type BasicGameplayWarningCode, type CreateBasicGameplayCatchSummaryInput, RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION, type RiddleProofBasicGameplayAssessment, type RiddleProofBasicGameplayCatchSummary, type RiddleProofBasicGameplayEvidence, type RiddleProofBasicGameplayRouteAssessment, type RiddleProofBasicGameplayRouteEvidence, assessBasicGameplayEvidence, assessBasicGameplayRoute, createBasicGameplayCatchSummary, extractBasicGameplayEvidence };

package/dist/basic-gameplay.js

@@ -1,14 +1,18 @@
 import {
   RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
+  RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION,
   RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION,
   assessBasicGameplayEvidence,
   assessBasicGameplayRoute,
+  createBasicGameplayCatchSummary,
   extractBasicGameplayEvidence
-} from "./chunk-RNGJX62B.js";
+} from "./chunk-53DJMNQ6.js";
 export {
   RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
+  RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION,
   RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION,
   assessBasicGameplayEvidence,
   assessBasicGameplayRoute,
+  createBasicGameplayCatchSummary,
   extractBasicGameplayEvidence
 };

package/dist/{chunk-UR6ADV4Y.js → chunk-3CVGVQTQ.js}

@@ -87,12 +87,94 @@ async function deployRiddleStaticPreview(config, directory, label) {
     raw: published
   };
 }
+function createTarball(directory, label, exclude = []) {
+  const scratch = mkdtempSync(path.join(tmpdir(), "riddle-upload-"));
+  const tarball = path.join(scratch, `${label}.tar.gz`);
+  const excludeArgs = exclude.flatMap((item) => ["--exclude", item]);
+  try {
+    execFileSync("tar", ["czf", tarball, ...excludeArgs, "-C", directory, "."], { stdio: "pipe" });
+    return { scratch, tarball };
+  } catch (error) {
+    rmSync(scratch, { recursive: true, force: true });
+    throw error;
+  }
+}
 function parseRiddleViewport(value) {
   if (!value) return void 0;
   const match = /^(\d+)x(\d+)$/.exec(value.trim());
   if (!match) throw new Error("viewport must look like 1280x720");
   return { width: Number(match[1]), height: Number(match[2]) };
 }
+function scriptErrorFrom(job) {
+  const nested = job?.proof_of_execution && typeof job.proof_of_execution === "object" && !Array.isArray(job.proof_of_execution) ? job.proof_of_execution : null;
+  return typeof job?.script_error === "string" && job.script_error.trim() ? job.script_error : typeof nested?.script_error === "string" && nested.script_error.trim() ? nested.script_error : null;
+}
+async function runRiddleServerPreview(config, input) {
+  if (!input.directory?.trim()) throw new Error("directory is required");
+  if (!input.script?.trim()) throw new Error("script is required");
+  const port = input.port || 3e3;
+  const routePath = input.path || "/";
+  const timeoutSec = input.timeoutSec || 180;
+  const created = await riddleRequestJson(config, "/v1/server-preview", {
+    method: "POST",
+    body: JSON.stringify({
+      image: input.image || "node:22-slim",
+      command: input.command || "node scripts/riddleSpaPreviewServer.mjs build 3000",
+      port,
+      path: routePath,
+      readiness_path: input.readinessPath || routePath,
+      readiness_timeout: input.readinessTimeoutSec || 90,
+      wait_until: input.waitUntil || "domcontentloaded",
+      wait_for_selector: input.waitForSelector || "body",
+      navigation_timeout: input.navigationTimeoutSec || 60,
+      viewport: input.viewport,
+      timeout: timeoutSec,
+      script: input.script
+    })
+  });
+  const jobId = String(created.job_id || "");
+  const uploadUrl = String(created.upload_url || "");
+  if (!jobId || !uploadUrl) {
+    throw new Error(`Riddle server preview create response was missing job_id or upload_url.`);
+  }
+  const { scratch, tarball } = createTarball(input.directory, jobId, [
+    ".git",
+    "node_modules",
+    "test-results",
+    ...input.exclude || []
+  ]);
+  try {
+    const upload = await fetchFor(config)(uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Type": "application/gzip" },
+      body: readFileSync(tarball)
+    });
+    if (!upload.ok) throw new RiddleApiError(uploadUrl, upload.status, await upload.text());
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+  await riddleRequestJson(config, `/v1/server-preview/${jobId}/start`, {
+    method: "POST"
+  });
+  let job = null;
+  const attempts = input.pollAttempts || Math.ceil((timeoutSec + 90) / 2);
+  const intervalMs = input.pollIntervalMs || 2e3;
+  for (let index = 0; index < attempts; index += 1) {
+    job = await riddleRequestJson(config, `/v1/server-preview/${jobId}`);
+    if (isTerminalRiddleJobStatus(job.status)) break;
+    if (index + 1 < attempts) await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  const status = job?.status ? String(job.status) : null;
+  const scriptError = scriptErrorFrom(job);
+  return {
+    ok: (status === "completed" || status === "complete") && !scriptError,
+    job_id: jobId,
+    status,
+    terminal: isTerminalRiddleJobStatus(status),
+    script_error: scriptError,
+    job
+  };
+}
 async function runRiddleScript(config, input) {
   if (!input.url?.trim()) throw new Error("url is required");
   if (!input.script?.trim()) throw new Error("script is required");
@@ -144,6 +226,7 @@ function createRiddleApiClient(config = {}) {
     requestJson: (pathname, init) => riddleRequestJson(config, pathname, init),
     deployStaticPreview: (directory, label) => deployRiddleStaticPreview(config, directory, label),
     runScript: (input) => runRiddleScript(config, input),
+    runServerPreview: (input) => runRiddleServerPreview(config, input),
     pollJob: (jobId, options) => pollRiddleJob(config, jobId, options)
   };
 }
@@ -156,6 +239,7 @@ export {
   riddleRequestJson,
   deployRiddleStaticPreview,
   parseRiddleViewport,
+  runRiddleServerPreview,
   runRiddleScript,
   isTerminalRiddleJobStatus,
   pollRiddleJob,

package/dist/{chunk-RNGJX62B.js → chunk-53DJMNQ6.js}

@@ -1,6 +1,7 @@
 // src/basic-gameplay.ts
 var RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION = "riddle-proof.basic-gameplay.v1";
 var RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION = "riddle-proof.basic-gameplay.assessment.v1";
+var RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION = "riddle-proof.basic-gameplay.catch.v1";
 var BASIC_GAMEPLAY_CONTAINER_KEYS = [
   "basic_gameplay",
   "basicGameplay",
@@ -110,6 +111,37 @@ function assessBasicGameplayRoute(route, options = {}) {
     }
   };
 }
+function createBasicGameplayCatchSummary(input, options = {}) {
+  const before = summarizeAssessment(assessBasicGameplayEvidence(input.before, options));
+  const after = input.after === void 0 ? void 0 : summarizeAssessment(assessBasicGameplayEvidence(input.after, options));
+  const fixed = Boolean(after && before.notable_codes.length > 0 && after.passed && after.notable_codes.length === 0);
+  const title = input.title || [
+    input.site || "Basic gameplay",
+    input.route ? `${input.route} proof catch` : "proof catch"
+  ].join(" ");
+  const beforeCodes = before.notable_codes.length ? before.notable_codes.join(", ") : "no failing or warning codes";
+  const afterCodes = after ? after.notable_codes.length ? after.notable_codes.join(", ") : "no failing or warning codes" : "not verified";
+  const summaryLines = [
+    `Before: ${before.checked_routes} checked, ${before.passing_routes} passing, codes: ${beforeCodes}.`,
+    after ? `After: ${after.checked_routes} checked, ${after.passing_routes} passing, codes: ${afterCodes}.` : "After: not provided."
+  ];
+  if (input.fix?.summary) summaryLines.push(`Fix: ${input.fix.summary}`);
+  if (input.artifacts?.length) summaryLines.push(`Artifacts: ${input.artifacts.length} attached.`);
+  return {
+    version: RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION,
+    title,
+    site: input.site,
+    route: input.route,
+    detected_at: input.detected_at || (/* @__PURE__ */ new Date()).toISOString(),
+    before,
+    after,
+    fixed,
+    fix: input.fix,
+    artifacts: input.artifacts || [],
+    summary_lines: summaryLines,
+    marketing_summary: fixed ? `${title}: Riddle Proof caught ${beforeCodes}; after the fix, ${afterCodes}.` : `${title}: Riddle Proof caught ${beforeCodes}; after evidence is ${after ? "not yet clean" : "not yet attached"}.`
+  };
+}
 function extractBasicGameplayEvidence(...sources) {
   const seen = /* @__PURE__ */ new Set();
   for (const source of sources) {
@@ -118,6 +150,21 @@ function extractBasicGameplayEvidence(...sources) {
   }
   return null;
 }
+function summarizeAssessment(assessment) {
+  return {
+    evidence_present: assessment.evidence_present,
+    passed: assessment.passed,
+    checked_routes: assessment.checked_routes,
+    passing_routes: assessment.passing_routes,
+    failing_routes: assessment.failing_routes,
+    failure_counts: assessment.failure_counts,
+    warning_counts: assessment.warning_counts,
+    notable_codes: [
+      ...Object.keys(assessment.failure_counts),
+      ...Object.keys(assessment.warning_counts)
+    ].sort()
+  };
+}
 function findBasicGameplayEvidence(value, seen, depth = 0) {
   if (depth > 6 || value === null || value === void 0) return null;
   if (typeof value === "string") {
@@ -221,7 +268,9 @@ function parseJson(value) {
 export {
   RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION,
   RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
+  RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION,
   assessBasicGameplayEvidence,
   assessBasicGameplayRoute,
+  createBasicGameplayCatchSummary,
   extractBasicGameplayEvidence
 };

package/dist/cli.cjs

@@ -6487,12 +6487,94 @@ async function deployRiddleStaticPreview(config, directory, label) {
     raw: published
   };
 }
+function createTarball(directory, label, exclude = []) {
+  const scratch = (0, import_node_fs5.mkdtempSync)(import_node_path5.default.join((0, import_node_os2.tmpdir)(), "riddle-upload-"));
+  const tarball = import_node_path5.default.join(scratch, `${label}.tar.gz`);
+  const excludeArgs = exclude.flatMap((item) => ["--exclude", item]);
+  try {
+    (0, import_node_child_process4.execFileSync)("tar", ["czf", tarball, ...excludeArgs, "-C", directory, "."], { stdio: "pipe" });
+    return { scratch, tarball };
+  } catch (error) {
+    (0, import_node_fs5.rmSync)(scratch, { recursive: true, force: true });
+    throw error;
+  }
+}
 function parseRiddleViewport(value) {
   if (!value) return void 0;
   const match = /^(\d+)x(\d+)$/.exec(value.trim());
   if (!match) throw new Error("viewport must look like 1280x720");
   return { width: Number(match[1]), height: Number(match[2]) };
 }
+function scriptErrorFrom(job) {
+  const nested = job?.proof_of_execution && typeof job.proof_of_execution === "object" && !Array.isArray(job.proof_of_execution) ? job.proof_of_execution : null;
+  return typeof job?.script_error === "string" && job.script_error.trim() ? job.script_error : typeof nested?.script_error === "string" && nested.script_error.trim() ? nested.script_error : null;
+}
+async function runRiddleServerPreview(config, input) {
+  if (!input.directory?.trim()) throw new Error("directory is required");
+  if (!input.script?.trim()) throw new Error("script is required");
+  const port = input.port || 3e3;
+  const routePath = input.path || "/";
+  const timeoutSec = input.timeoutSec || 180;
+  const created = await riddleRequestJson(config, "/v1/server-preview", {
+    method: "POST",
+    body: JSON.stringify({
+      image: input.image || "node:22-slim",
+      command: input.command || "node scripts/riddleSpaPreviewServer.mjs build 3000",
+      port,
+      path: routePath,
+      readiness_path: input.readinessPath || routePath,
+      readiness_timeout: input.readinessTimeoutSec || 90,
+      wait_until: input.waitUntil || "domcontentloaded",
+      wait_for_selector: input.waitForSelector || "body",
+      navigation_timeout: input.navigationTimeoutSec || 60,
+      viewport: input.viewport,
+      timeout: timeoutSec,
+      script: input.script
+    })
+  });
+  const jobId = String(created.job_id || "");
+  const uploadUrl = String(created.upload_url || "");
+  if (!jobId || !uploadUrl) {
+    throw new Error(`Riddle server preview create response was missing job_id or upload_url.`);
+  }
+  const { scratch, tarball } = createTarball(input.directory, jobId, [
+    ".git",
+    "node_modules",
+    "test-results",
+    ...input.exclude || []
+  ]);
+  try {
+    const upload = await fetchFor(config)(uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Type": "application/gzip" },
+      body: (0, import_node_fs5.readFileSync)(tarball)
+    });
+    if (!upload.ok) throw new RiddleApiError(uploadUrl, upload.status, await upload.text());
+  } finally {
+    (0, import_node_fs5.rmSync)(scratch, { recursive: true, force: true });
+  }
+  await riddleRequestJson(config, `/v1/server-preview/${jobId}/start`, {
+    method: "POST"
+  });
+  let job = null;
+  const attempts = input.pollAttempts || Math.ceil((timeoutSec + 90) / 2);
+  const intervalMs = input.pollIntervalMs || 2e3;
+  for (let index = 0; index < attempts; index += 1) {
+    job = await riddleRequestJson(config, `/v1/server-preview/${jobId}`);
+    if (isTerminalRiddleJobStatus(job.status)) break;
+    if (index + 1 < attempts) await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  const status = job?.status ? String(job.status) : null;
+  const scriptError = scriptErrorFrom(job);
+  return {
+    ok: (status === "completed" || status === "complete") && !scriptError,
+    job_id: jobId,
+    status,
+    terminal: isTerminalRiddleJobStatus(status),
+    script_error: scriptError,
+    job
+  };
+}
 async function runRiddleScript(config, input) {
   if (!input.url?.trim()) throw new Error("url is required");
   if (!input.script?.trim()) throw new Error("script is required");
@@ -6544,6 +6626,7 @@ function createRiddleApiClient(config = {}) {
     requestJson: (pathname, init) => riddleRequestJson(config, pathname, init),
     deployStaticPreview: (directory, label) => deployRiddleStaticPreview(config, directory, label),
     runScript: (input) => runRiddleScript(config, input),
+    runServerPreview: (input) => runRiddleServerPreview(config, input),
     pollJob: (jobId, options) => pollRiddleJob(config, jobId, options)
   };
 }
@@ -6558,6 +6641,7 @@ function usage() {
     "  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 riddle-preview-deploy <build-dir> <label>",
+    "  riddle-proof-loop riddle-server-preview <directory> --script-file <file> [--path /route] [--wait-for-selector selector]",
     "  riddle-proof-loop riddle-run-script --url <url> --script-file <file> [--viewport 1280x720]",
     "  riddle-proof-loop riddle-poll <job-id> [--wait]",
     "  riddle-proof-loop doctor local [--codex-command <path>]",
@@ -6801,6 +6885,32 @@ async function main() {
 `);
     return;
   }
+  if (command === "riddle-server-preview") {
+    const directory = positional[1];
+    const scriptFile = optionString(options, "scriptFile");
+    if (!directory || !scriptFile) throw new Error("riddle-server-preview requires <directory> and --script-file.");
+    const result = await createRiddleApiClient(riddleClientConfig(options)).runServerPreview({
+      directory,
+      script: (0, import_node_fs6.readFileSync)(scriptFile, "utf-8"),
+      image: optionString(options, "image"),
+      command: optionString(options, "command"),
+      port: optionString(options, "port") ? Number(optionString(options, "port")) : void 0,
+      path: optionString(options, "path"),
+      readinessPath: optionString(options, "readinessPath"),
+      readinessTimeoutSec: optionString(options, "readinessTimeout") ? Number(optionString(options, "readinessTimeout")) : void 0,
+      waitForSelector: optionString(options, "waitForSelector"),
+      navigationTimeoutSec: optionString(options, "navigationTimeout") ? Number(optionString(options, "navigationTimeout")) : void 0,
+      viewport: parseRiddleViewport(optionString(options, "viewport")),
+      timeoutSec: optionString(options, "timeout") ? Number(optionString(options, "timeout")) : void 0,
+      pollAttempts: optionString(options, "pollAttempts") ? Number(optionString(options, "pollAttempts")) : void 0,
+      pollIntervalMs: optionString(options, "pollIntervalMs") ? Number(optionString(options, "pollIntervalMs")) : void 0,
+      exclude: optionString(options, "exclude")?.split(",").map((item) => item.trim()).filter(Boolean)
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    process.exitCode = result.ok ? 0 : 1;
+    return;
+  }
   if (command === "riddle-run-script") {
     const url = optionString(options, "url");
     const scriptFile = optionString(options, "scriptFile");

package/dist/cli.js

@@ -2,7 +2,7 @@
 import {
   createRiddleApiClient,
   parseRiddleViewport
-} from "./chunk-UR6ADV4Y.js";
+} from "./chunk-3CVGVQTQ.js";
 import {
   createDisabledRiddleProofAgentAdapter,
   readRiddleProofRunStatus,
@@ -32,6 +32,7 @@ function usage() {
     "  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 riddle-preview-deploy <build-dir> <label>",
+    "  riddle-proof-loop riddle-server-preview <directory> --script-file <file> [--path /route] [--wait-for-selector selector]",
     "  riddle-proof-loop riddle-run-script --url <url> --script-file <file> [--viewport 1280x720]",
     "  riddle-proof-loop riddle-poll <job-id> [--wait]",
     "  riddle-proof-loop doctor local [--codex-command <path>]",
@@ -275,6 +276,32 @@ async function main() {
 `);
     return;
   }
+  if (command === "riddle-server-preview") {
+    const directory = positional[1];
+    const scriptFile = optionString(options, "scriptFile");
+    if (!directory || !scriptFile) throw new Error("riddle-server-preview requires <directory> and --script-file.");
+    const result = await createRiddleApiClient(riddleClientConfig(options)).runServerPreview({
+      directory,
+      script: readFileSync(scriptFile, "utf-8"),
+      image: optionString(options, "image"),
+      command: optionString(options, "command"),
+      port: optionString(options, "port") ? Number(optionString(options, "port")) : void 0,
+      path: optionString(options, "path"),
+      readinessPath: optionString(options, "readinessPath"),
+      readinessTimeoutSec: optionString(options, "readinessTimeout") ? Number(optionString(options, "readinessTimeout")) : void 0,
+      waitForSelector: optionString(options, "waitForSelector"),
+      navigationTimeoutSec: optionString(options, "navigationTimeout") ? Number(optionString(options, "navigationTimeout")) : void 0,
+      viewport: parseRiddleViewport(optionString(options, "viewport")),
+      timeoutSec: optionString(options, "timeout") ? Number(optionString(options, "timeout")) : void 0,
+      pollAttempts: optionString(options, "pollAttempts") ? Number(optionString(options, "pollAttempts")) : void 0,
+      pollIntervalMs: optionString(options, "pollIntervalMs") ? Number(optionString(options, "pollIntervalMs")) : void 0,
+      exclude: optionString(options, "exclude")?.split(",").map((item) => item.trim()).filter(Boolean)
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    process.exitCode = result.ok ? 0 : 1;
+    return;
+  }
   if (command === "riddle-run-script") {
     const url = optionString(options, "url");
     const scriptFile = optionString(options, "scriptFile");

package/dist/index.cjs

@@ -2779,6 +2779,7 @@ __export(index_exports, {
   DEFAULT_RIDDLE_API_BASE_URL: () => DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE: () => DEFAULT_RIDDLE_API_KEY_FILE,
   RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION: () => RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
+  RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION: () => RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION,
   RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION: () => RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION,
   RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION: () => RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION,
   RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION: () => RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
@@ -2808,6 +2809,7 @@ __export(index_exports, {
   checkpointSummaryFromState: () => checkpointSummaryFromState,
   compactRecord: () => compactRecord,
   compareVisualProofSessionFingerprint: () => compareVisualProofSessionFingerprint,
+  createBasicGameplayCatchSummary: () => createBasicGameplayCatchSummary,
   createCaptureDiagnostic: () => createCaptureDiagnostic,
   createCheckpointResponseTemplate: () => createCheckpointResponseTemplate,
   createCodexExecAgentAdapter: () => createCodexExecAgentAdapter,
@@ -2848,6 +2850,7 @@ __export(index_exports, {
   runRiddleProof: () => runRiddleProof,
   runRiddleProofEngineHarness: () => runRiddleProofEngineHarness,
   runRiddleScript: () => runRiddleScript,
+  runRiddleServerPreview: () => runRiddleServerPreview,
   setRunStatus: () => setRunStatus,
   statePathsForRunState: () => statePathsForRunState,
   summarizeCaptureArtifacts: () => summarizeCaptureArtifacts,
@@ -7619,6 +7622,7 @@ function parseJson(value) {
 // src/basic-gameplay.ts
 var RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION = "riddle-proof.basic-gameplay.v1";
 var RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION = "riddle-proof.basic-gameplay.assessment.v1";
+var RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION = "riddle-proof.basic-gameplay.catch.v1";
 var BASIC_GAMEPLAY_CONTAINER_KEYS = [
   "basic_gameplay",
   "basicGameplay",
@@ -7728,6 +7732,37 @@ function assessBasicGameplayRoute(route, options = {}) {
     }
   };
 }
+function createBasicGameplayCatchSummary(input, options = {}) {
+  const before = summarizeAssessment(assessBasicGameplayEvidence(input.before, options));
+  const after = input.after === void 0 ? void 0 : summarizeAssessment(assessBasicGameplayEvidence(input.after, options));
+  const fixed = Boolean(after && before.notable_codes.length > 0 && after.passed && after.notable_codes.length === 0);
+  const title = input.title || [
+    input.site || "Basic gameplay",
+    input.route ? `${input.route} proof catch` : "proof catch"
+  ].join(" ");
+  const beforeCodes = before.notable_codes.length ? before.notable_codes.join(", ") : "no failing or warning codes";
+  const afterCodes = after ? after.notable_codes.length ? after.notable_codes.join(", ") : "no failing or warning codes" : "not verified";
+  const summaryLines = [
+    `Before: ${before.checked_routes} checked, ${before.passing_routes} passing, codes: ${beforeCodes}.`,
+    after ? `After: ${after.checked_routes} checked, ${after.passing_routes} passing, codes: ${afterCodes}.` : "After: not provided."
+  ];
+  if (input.fix?.summary) summaryLines.push(`Fix: ${input.fix.summary}`);
+  if (input.artifacts?.length) summaryLines.push(`Artifacts: ${input.artifacts.length} attached.`);
+  return {
+    version: RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION,
+    title,
+    site: input.site,
+    route: input.route,
+    detected_at: input.detected_at || (/* @__PURE__ */ new Date()).toISOString(),
+    before,
+    after,
+    fixed,
+    fix: input.fix,
+    artifacts: input.artifacts || [],
+    summary_lines: summaryLines,
+    marketing_summary: fixed ? `${title}: Riddle Proof caught ${beforeCodes}; after the fix, ${afterCodes}.` : `${title}: Riddle Proof caught ${beforeCodes}; after evidence is ${after ? "not yet clean" : "not yet attached"}.`
+  };
+}
 function extractBasicGameplayEvidence(...sources) {
   const seen = /* @__PURE__ */ new Set();
   for (const source of sources) {
@@ -7736,6 +7771,21 @@ function extractBasicGameplayEvidence(...sources) {
   }
   return null;
 }
+function summarizeAssessment(assessment) {
+  return {
+    evidence_present: assessment.evidence_present,
+    passed: assessment.passed,
+    checked_routes: assessment.checked_routes,
+    passing_routes: assessment.passing_routes,
+    failing_routes: assessment.failing_routes,
+    failure_counts: assessment.failure_counts,
+    warning_counts: assessment.warning_counts,
+    notable_codes: [
+      ...Object.keys(assessment.failure_counts),
+      ...Object.keys(assessment.warning_counts)
+    ].sort()
+  };
+}
 function findBasicGameplayEvidence(value, seen, depth = 0) {
   if (depth > 6 || value === null || value === void 0) return null;
   if (typeof value === "string") {
@@ -7925,12 +7975,94 @@ async function deployRiddleStaticPreview(config, directory, label) {
     raw: published
   };
 }
+function createTarball(directory, label, exclude = []) {
+  const scratch = (0, import_node_fs5.mkdtempSync)(import_node_path5.default.join((0, import_node_os2.tmpdir)(), "riddle-upload-"));
+  const tarball = import_node_path5.default.join(scratch, `${label}.tar.gz`);
+  const excludeArgs = exclude.flatMap((item) => ["--exclude", item]);
+  try {
+    (0, import_node_child_process4.execFileSync)("tar", ["czf", tarball, ...excludeArgs, "-C", directory, "."], { stdio: "pipe" });
+    return { scratch, tarball };
+  } catch (error) {
+    (0, import_node_fs5.rmSync)(scratch, { recursive: true, force: true });
+    throw error;
+  }
+}
 function parseRiddleViewport(value) {
   if (!value) return void 0;
   const match = /^(\d+)x(\d+)$/.exec(value.trim());
   if (!match) throw new Error("viewport must look like 1280x720");
   return { width: Number(match[1]), height: Number(match[2]) };
 }
+function scriptErrorFrom(job) {
+  const nested = job?.proof_of_execution && typeof job.proof_of_execution === "object" && !Array.isArray(job.proof_of_execution) ? job.proof_of_execution : null;
+  return typeof job?.script_error === "string" && job.script_error.trim() ? job.script_error : typeof nested?.script_error === "string" && nested.script_error.trim() ? nested.script_error : null;
+}
+async function runRiddleServerPreview(config, input) {
+  if (!input.directory?.trim()) throw new Error("directory is required");
+  if (!input.script?.trim()) throw new Error("script is required");
+  const port = input.port || 3e3;
+  const routePath = input.path || "/";
+  const timeoutSec = input.timeoutSec || 180;
+  const created = await riddleRequestJson(config, "/v1/server-preview", {
+    method: "POST",
+    body: JSON.stringify({
+      image: input.image || "node:22-slim",
+      command: input.command || "node scripts/riddleSpaPreviewServer.mjs build 3000",
+      port,
+      path: routePath,
+      readiness_path: input.readinessPath || routePath,
+      readiness_timeout: input.readinessTimeoutSec || 90,
+      wait_until: input.waitUntil || "domcontentloaded",
+      wait_for_selector: input.waitForSelector || "body",
+      navigation_timeout: input.navigationTimeoutSec || 60,
+      viewport: input.viewport,
+      timeout: timeoutSec,
+      script: input.script
+    })
+  });
+  const jobId = String(created.job_id || "");
+  const uploadUrl = String(created.upload_url || "");
+  if (!jobId || !uploadUrl) {
+    throw new Error(`Riddle server preview create response was missing job_id or upload_url.`);
+  }
+  const { scratch, tarball } = createTarball(input.directory, jobId, [
+    ".git",
+    "node_modules",
+    "test-results",
+    ...input.exclude || []
+  ]);
+  try {
+    const upload = await fetchFor(config)(uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Type": "application/gzip" },
+      body: (0, import_node_fs5.readFileSync)(tarball)
+    });
+    if (!upload.ok) throw new RiddleApiError(uploadUrl, upload.status, await upload.text());
+  } finally {
+    (0, import_node_fs5.rmSync)(scratch, { recursive: true, force: true });
+  }
+  await riddleRequestJson(config, `/v1/server-preview/${jobId}/start`, {
+    method: "POST"
+  });
+  let job = null;
+  const attempts = input.pollAttempts || Math.ceil((timeoutSec + 90) / 2);
+  const intervalMs = input.pollIntervalMs || 2e3;
+  for (let index = 0; index < attempts; index += 1) {
+    job = await riddleRequestJson(config, `/v1/server-preview/${jobId}`);
+    if (isTerminalRiddleJobStatus(job.status)) break;
+    if (index + 1 < attempts) await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  const status = job?.status ? String(job.status) : null;
+  const scriptError = scriptErrorFrom(job);
+  return {
+    ok: (status === "completed" || status === "complete") && !scriptError,
+    job_id: jobId,
+    status,
+    terminal: isTerminalRiddleJobStatus(status),
+    script_error: scriptError,
+    job
+  };
+}
 async function runRiddleScript(config, input) {
   if (!input.url?.trim()) throw new Error("url is required");
   if (!input.script?.trim()) throw new Error("script is required");
@@ -7982,6 +8114,7 @@ function createRiddleApiClient(config = {}) {
     requestJson: (pathname, init) => riddleRequestJson(config, pathname, init),
     deployStaticPreview: (directory, label) => deployRiddleStaticPreview(config, directory, label),
     runScript: (input) => runRiddleScript(config, input),
+    runServerPreview: (input) => runRiddleServerPreview(config, input),
     pollJob: (jobId, options) => pollRiddleJob(config, jobId, options)
   };
 }
@@ -7993,6 +8126,7 @@ function createRiddleApiClient(config = {}) {
   DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE,
   RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
+  RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION,
   RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION,
   RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION,
   RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
@@ -8022,6 +8156,7 @@ function createRiddleApiClient(config = {}) {
   checkpointSummaryFromState,
   compactRecord,
   compareVisualProofSessionFingerprint,
+  createBasicGameplayCatchSummary,
   createCaptureDiagnostic,
   createCheckpointResponseTemplate,
   createCodexExecAgentAdapter,
@@ -8062,6 +8197,7 @@ function createRiddleApiClient(config = {}) {
   runRiddleProof,
   runRiddleProofEngineHarness,
   runRiddleScript,
+  runRiddleServerPreview,
   setRunStatus,
   statePathsForRunState,
   summarizeCaptureArtifacts,

package/dist/index.d.cts

@@ -9,5 +9,5 @@ export { CodexExecAgentConfig, CodexJsonRequest, CodexJsonResult, CodexJsonRunne
 export { CreateCaptureDiagnosticInput, DEFAULT_DIAGNOSTIC_ARRAY_LIMIT, DEFAULT_DIAGNOSTIC_HISTORY_LIMIT, DEFAULT_DIAGNOSTIC_STRING_LIMIT, RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION, RiddleProofArtifactSummary, RiddleProofCaptureArtifactSummary, RiddleProofCaptureDiagnostic, RiddleProofDiagnosticRedactionOptions, appendCaptureDiagnostic, createCaptureDiagnostic, redactForProofDiagnostics, summarizeCaptureArtifacts } from './diagnostics.cjs';
 export { BuildVisualProofSessionInput, RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION, RIDDLE_PROOF_VISUAL_SESSION_VERSION, VisualProofSessionMismatch, buildVisualProofSession, compareVisualProofSessionFingerprint, parseVisualProofSession, visualSessionFingerprint, visualSessionFingerprintBasis } from './proof-session.cjs';
 export { AssessPlayabilityOptions, RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION, RIDDLE_PROOF_PLAYABILITY_VERSION, RiddleProofPlayabilityAssessment, RiddleProofPlayabilityEvidence, assessPlayabilityEvidence, extractPlayabilityEvidence, isRiddleProofPlayabilityMode } from './playability.cjs';
-export { AssessBasicGameplayOptions, BasicGameplayActionResult, BasicGameplayCanvasState, BasicGameplayChangeSummary, BasicGameplayFailureCode, BasicGameplayMobileEvidence, BasicGameplaySnapshot, BasicGameplayWarningCode, RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION, RiddleProofBasicGameplayAssessment, RiddleProofBasicGameplayEvidence, RiddleProofBasicGameplayRouteAssessment, RiddleProofBasicGameplayRouteEvidence, assessBasicGameplayEvidence, assessBasicGameplayRoute, extractBasicGameplayEvidence } from './basic-gameplay.cjs';
-export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleClientConfig, RiddleFetch, RiddlePollJobResult, RiddlePreviewDeployResult, RiddleRunScriptInput, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript } from './riddle-client.cjs';
+export { AssessBasicGameplayOptions, BasicGameplayActionResult, BasicGameplayAssessmentSummary, BasicGameplayCanvasState, BasicGameplayChangeSummary, BasicGameplayFailureCode, BasicGameplayFixReference, BasicGameplayMobileEvidence, BasicGameplayProofArtifact, BasicGameplaySnapshot, BasicGameplayWarningCode, CreateBasicGameplayCatchSummaryInput, RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION, RiddleProofBasicGameplayAssessment, RiddleProofBasicGameplayCatchSummary, RiddleProofBasicGameplayEvidence, RiddleProofBasicGameplayRouteAssessment, RiddleProofBasicGameplayRouteEvidence, assessBasicGameplayEvidence, assessBasicGameplayRoute, createBasicGameplayCatchSummary, extractBasicGameplayEvidence } from './basic-gameplay.cjs';
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleClientConfig, RiddleFetch, RiddlePollJobResult, RiddlePreviewDeployResult, RiddleRunScriptInput, RiddleServerPreviewInput, RiddleServerPreviewResult, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript, runRiddleServerPreview } from './riddle-client.cjs';

package/dist/index.d.ts

@@ -9,5 +9,5 @@ export { CodexExecAgentConfig, CodexJsonRequest, CodexJsonResult, CodexJsonRunne
 export { CreateCaptureDiagnosticInput, DEFAULT_DIAGNOSTIC_ARRAY_LIMIT, DEFAULT_DIAGNOSTIC_HISTORY_LIMIT, DEFAULT_DIAGNOSTIC_STRING_LIMIT, RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION, RiddleProofArtifactSummary, RiddleProofCaptureArtifactSummary, RiddleProofCaptureDiagnostic, RiddleProofDiagnosticRedactionOptions, appendCaptureDiagnostic, createCaptureDiagnostic, redactForProofDiagnostics, summarizeCaptureArtifacts } from './diagnostics.js';
 export { BuildVisualProofSessionInput, RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION, RIDDLE_PROOF_VISUAL_SESSION_VERSION, VisualProofSessionMismatch, buildVisualProofSession, compareVisualProofSessionFingerprint, parseVisualProofSession, visualSessionFingerprint, visualSessionFingerprintBasis } from './proof-session.js';
 export { AssessPlayabilityOptions, RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION, RIDDLE_PROOF_PLAYABILITY_VERSION, RiddleProofPlayabilityAssessment, RiddleProofPlayabilityEvidence, assessPlayabilityEvidence, extractPlayabilityEvidence, isRiddleProofPlayabilityMode } from './playability.js';
-export { AssessBasicGameplayOptions, BasicGameplayActionResult, BasicGameplayCanvasState, BasicGameplayChangeSummary, BasicGameplayFailureCode, BasicGameplayMobileEvidence, BasicGameplaySnapshot, BasicGameplayWarningCode, RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION, RiddleProofBasicGameplayAssessment, RiddleProofBasicGameplayEvidence, RiddleProofBasicGameplayRouteAssessment, RiddleProofBasicGameplayRouteEvidence, assessBasicGameplayEvidence, assessBasicGameplayRoute, extractBasicGameplayEvidence } from './basic-gameplay.js';
-export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleClientConfig, RiddleFetch, RiddlePollJobResult, RiddlePreviewDeployResult, RiddleRunScriptInput, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript } from './riddle-client.js';
+export { AssessBasicGameplayOptions, BasicGameplayActionResult, BasicGameplayAssessmentSummary, BasicGameplayCanvasState, BasicGameplayChangeSummary, BasicGameplayFailureCode, BasicGameplayFixReference, BasicGameplayMobileEvidence, BasicGameplayProofArtifact, BasicGameplaySnapshot, BasicGameplayWarningCode, CreateBasicGameplayCatchSummaryInput, RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION, RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION, RiddleProofBasicGameplayAssessment, RiddleProofBasicGameplayCatchSummary, RiddleProofBasicGameplayEvidence, RiddleProofBasicGameplayRouteAssessment, RiddleProofBasicGameplayRouteEvidence, assessBasicGameplayEvidence, assessBasicGameplayRoute, createBasicGameplayCatchSummary, extractBasicGameplayEvidence } from './basic-gameplay.js';
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleClientConfig, RiddleFetch, RiddlePollJobResult, RiddlePreviewDeployResult, RiddleRunScriptInput, RiddleServerPreviewInput, RiddleServerPreviewResult, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript, runRiddleServerPreview } from './riddle-client.js';

package/dist/index.js

@@ -20,11 +20,13 @@ import {
 } from "./chunk-ODORKNSO.js";
 import {
   RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
+  RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION,
   RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION,
   assessBasicGameplayEvidence,
   assessBasicGameplayRoute,
+  createBasicGameplayCatchSummary,
   extractBasicGameplayEvidence
-} from "./chunk-RNGJX62B.js";
+} from "./chunk-53DJMNQ6.js";
 import {
   DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE,
@@ -36,8 +38,9 @@ import {
   pollRiddleJob,
   resolveRiddleApiKey,
   riddleRequestJson,
-  runRiddleScript
-} from "./chunk-UR6ADV4Y.js";
+  runRiddleScript,
+  runRiddleServerPreview
+} from "./chunk-3CVGVQTQ.js";
 import {
   DEFAULT_DIAGNOSTIC_ARRAY_LIMIT,
   DEFAULT_DIAGNOSTIC_HISTORY_LIMIT,
@@ -109,6 +112,7 @@ export {
   DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE,
   RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
+  RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION,
   RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION,
   RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION,
   RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
@@ -138,6 +142,7 @@ export {
   checkpointSummaryFromState,
   compactRecord,
   compareVisualProofSessionFingerprint,
+  createBasicGameplayCatchSummary,
   createCaptureDiagnostic,
   createCheckpointResponseTemplate,
   createCodexExecAgentAdapter,
@@ -178,6 +183,7 @@ export {
   runRiddleProof,
   runRiddleProofEngineHarness,
   runRiddleScript,
+  runRiddleServerPreview,
   setRunStatus,
   statePathsForRunState,
   summarizeCaptureArtifacts,

package/dist/riddle-client.cjs

@@ -40,7 +40,8 @@ __export(riddle_client_exports, {
   pollRiddleJob: () => pollRiddleJob,
   resolveRiddleApiKey: () => resolveRiddleApiKey,
   riddleRequestJson: () => riddleRequestJson,
-  runRiddleScript: () => runRiddleScript
+  runRiddleScript: () => runRiddleScript,
+  runRiddleServerPreview: () => runRiddleServerPreview
 });
 module.exports = __toCommonJS(riddle_client_exports);
 var import_node_child_process = require("child_process");
@@ -131,12 +132,94 @@ async function deployRiddleStaticPreview(config, directory, label) {
     raw: published
   };
 }
+function createTarball(directory, label, exclude = []) {
+  const scratch = (0, import_node_fs.mkdtempSync)(import_node_path.default.join((0, import_node_os.tmpdir)(), "riddle-upload-"));
+  const tarball = import_node_path.default.join(scratch, `${label}.tar.gz`);
+  const excludeArgs = exclude.flatMap((item) => ["--exclude", item]);
+  try {
+    (0, import_node_child_process.execFileSync)("tar", ["czf", tarball, ...excludeArgs, "-C", directory, "."], { stdio: "pipe" });
+    return { scratch, tarball };
+  } catch (error) {
+    (0, import_node_fs.rmSync)(scratch, { recursive: true, force: true });
+    throw error;
+  }
+}
 function parseRiddleViewport(value) {
   if (!value) return void 0;
   const match = /^(\d+)x(\d+)$/.exec(value.trim());
   if (!match) throw new Error("viewport must look like 1280x720");
   return { width: Number(match[1]), height: Number(match[2]) };
 }
+function scriptErrorFrom(job) {
+  const nested = job?.proof_of_execution && typeof job.proof_of_execution === "object" && !Array.isArray(job.proof_of_execution) ? job.proof_of_execution : null;
+  return typeof job?.script_error === "string" && job.script_error.trim() ? job.script_error : typeof nested?.script_error === "string" && nested.script_error.trim() ? nested.script_error : null;
+}
+async function runRiddleServerPreview(config, input) {
+  if (!input.directory?.trim()) throw new Error("directory is required");
+  if (!input.script?.trim()) throw new Error("script is required");
+  const port = input.port || 3e3;
+  const routePath = input.path || "/";
+  const timeoutSec = input.timeoutSec || 180;
+  const created = await riddleRequestJson(config, "/v1/server-preview", {
+    method: "POST",
+    body: JSON.stringify({
+      image: input.image || "node:22-slim",
+      command: input.command || "node scripts/riddleSpaPreviewServer.mjs build 3000",
+      port,
+      path: routePath,
+      readiness_path: input.readinessPath || routePath,
+      readiness_timeout: input.readinessTimeoutSec || 90,
+      wait_until: input.waitUntil || "domcontentloaded",
+      wait_for_selector: input.waitForSelector || "body",
+      navigation_timeout: input.navigationTimeoutSec || 60,
+      viewport: input.viewport,
+      timeout: timeoutSec,
+      script: input.script
+    })
+  });
+  const jobId = String(created.job_id || "");
+  const uploadUrl = String(created.upload_url || "");
+  if (!jobId || !uploadUrl) {
+    throw new Error(`Riddle server preview create response was missing job_id or upload_url.`);
+  }
+  const { scratch, tarball } = createTarball(input.directory, jobId, [
+    ".git",
+    "node_modules",
+    "test-results",
+    ...input.exclude || []
+  ]);
+  try {
+    const upload = await fetchFor(config)(uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Type": "application/gzip" },
+      body: (0, import_node_fs.readFileSync)(tarball)
+    });
+    if (!upload.ok) throw new RiddleApiError(uploadUrl, upload.status, await upload.text());
+  } finally {
+    (0, import_node_fs.rmSync)(scratch, { recursive: true, force: true });
+  }
+  await riddleRequestJson(config, `/v1/server-preview/${jobId}/start`, {
+    method: "POST"
+  });
+  let job = null;
+  const attempts = input.pollAttempts || Math.ceil((timeoutSec + 90) / 2);
+  const intervalMs = input.pollIntervalMs || 2e3;
+  for (let index = 0; index < attempts; index += 1) {
+    job = await riddleRequestJson(config, `/v1/server-preview/${jobId}`);
+    if (isTerminalRiddleJobStatus(job.status)) break;
+    if (index + 1 < attempts) await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  const status = job?.status ? String(job.status) : null;
+  const scriptError = scriptErrorFrom(job);
+  return {
+    ok: (status === "completed" || status === "complete") && !scriptError,
+    job_id: jobId,
+    status,
+    terminal: isTerminalRiddleJobStatus(status),
+    script_error: scriptError,
+    job
+  };
+}
 async function runRiddleScript(config, input) {
   if (!input.url?.trim()) throw new Error("url is required");
   if (!input.script?.trim()) throw new Error("script is required");
@@ -188,6 +271,7 @@ function createRiddleApiClient(config = {}) {
     requestJson: (pathname, init) => riddleRequestJson(config, pathname, init),
     deployStaticPreview: (directory, label) => deployRiddleStaticPreview(config, directory, label),
     runScript: (input) => runRiddleScript(config, input),
+    runServerPreview: (input) => runRiddleServerPreview(config, input),
     pollJob: (jobId, options) => pollRiddleJob(config, jobId, options)
   };
 }
@@ -203,5 +287,6 @@ function createRiddleApiClient(config = {}) {
   pollRiddleJob,
   resolveRiddleApiKey,
   riddleRequestJson,
-  runRiddleScript
+  runRiddleScript,
+  runRiddleServerPreview
 });

package/dist/riddle-client.d.cts

@@ -29,6 +29,27 @@ interface RiddleRunScriptInput {
     include?: string[];
     options?: Record<string, unknown>;
 }
+interface RiddleServerPreviewInput {
+    directory: string;
+    script: string;
+    image?: string;
+    command?: string;
+    port?: number;
+    path?: string;
+    readinessPath?: string;
+    readinessTimeoutSec?: number;
+    waitForSelector?: string;
+    waitUntil?: "commit" | "domcontentloaded" | "load" | "networkidle";
+    navigationTimeoutSec?: number;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    timeoutSec?: number;
+    pollAttempts?: number;
+    pollIntervalMs?: number;
+    exclude?: string[];
+}
 interface RiddlePollJobResult {
     ok: boolean;
     job_id: string;
@@ -37,6 +58,14 @@ interface RiddlePollJobResult {
     job: Record<string, unknown> | null;
     artifacts?: Record<string, unknown> | null;
 }
+interface RiddleServerPreviewResult {
+    ok: boolean;
+    job_id: string;
+    status: string | null;
+    terminal: boolean;
+    script_error: string | null;
+    job: Record<string, unknown> | null;
+}
 declare class RiddleApiError extends Error {
     readonly status: number;
     readonly body: string;
@@ -50,6 +79,7 @@ declare function parseRiddleViewport(value?: string): {
     width: number;
     height: number;
 } | undefined;
+declare function runRiddleServerPreview(config: RiddleClientConfig, input: RiddleServerPreviewInput): Promise<RiddleServerPreviewResult>;
 declare function runRiddleScript(config: RiddleClientConfig, input: RiddleRunScriptInput): Promise<Record<string, unknown>>;
 declare function isTerminalRiddleJobStatus(status: unknown): boolean;
 declare function pollRiddleJob(config: RiddleClientConfig, jobId: string, options?: {
@@ -61,6 +91,7 @@ declare function createRiddleApiClient(config?: RiddleClientConfig): {
     requestJson: <T = unknown>(pathname: string, init?: RequestInit) => Promise<T>;
     deployStaticPreview: (directory: string, label: string) => Promise<RiddlePreviewDeployResult>;
     runScript: (input: RiddleRunScriptInput) => Promise<Record<string, unknown>>;
+    runServerPreview: (input: RiddleServerPreviewInput) => Promise<RiddleServerPreviewResult>;
     pollJob: (jobId: string, options?: {
         wait?: boolean;
         attempts?: number;
@@ -68,4 +99,4 @@ declare function createRiddleApiClient(config?: RiddleClientConfig): {
     }) => Promise<RiddlePollJobResult>;
 };
 
-export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, type RiddleClientConfig, type RiddleFetch, type RiddlePollJobResult, type RiddlePreviewDeployResult, type RiddleRunScriptInput, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript };
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, type RiddleClientConfig, type RiddleFetch, type RiddlePollJobResult, type RiddlePreviewDeployResult, type RiddleRunScriptInput, type RiddleServerPreviewInput, type RiddleServerPreviewResult, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript, runRiddleServerPreview };

package/dist/riddle-client.d.ts

@@ -29,6 +29,27 @@ interface RiddleRunScriptInput {
     include?: string[];
     options?: Record<string, unknown>;
 }
+interface RiddleServerPreviewInput {
+    directory: string;
+    script: string;
+    image?: string;
+    command?: string;
+    port?: number;
+    path?: string;
+    readinessPath?: string;
+    readinessTimeoutSec?: number;
+    waitForSelector?: string;
+    waitUntil?: "commit" | "domcontentloaded" | "load" | "networkidle";
+    navigationTimeoutSec?: number;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    timeoutSec?: number;
+    pollAttempts?: number;
+    pollIntervalMs?: number;
+    exclude?: string[];
+}
 interface RiddlePollJobResult {
     ok: boolean;
     job_id: string;
@@ -37,6 +58,14 @@ interface RiddlePollJobResult {
     job: Record<string, unknown> | null;
     artifacts?: Record<string, unknown> | null;
 }
+interface RiddleServerPreviewResult {
+    ok: boolean;
+    job_id: string;
+    status: string | null;
+    terminal: boolean;
+    script_error: string | null;
+    job: Record<string, unknown> | null;
+}
 declare class RiddleApiError extends Error {
     readonly status: number;
     readonly body: string;
@@ -50,6 +79,7 @@ declare function parseRiddleViewport(value?: string): {
     width: number;
     height: number;
 } | undefined;
+declare function runRiddleServerPreview(config: RiddleClientConfig, input: RiddleServerPreviewInput): Promise<RiddleServerPreviewResult>;
 declare function runRiddleScript(config: RiddleClientConfig, input: RiddleRunScriptInput): Promise<Record<string, unknown>>;
 declare function isTerminalRiddleJobStatus(status: unknown): boolean;
 declare function pollRiddleJob(config: RiddleClientConfig, jobId: string, options?: {
@@ -61,6 +91,7 @@ declare function createRiddleApiClient(config?: RiddleClientConfig): {
     requestJson: <T = unknown>(pathname: string, init?: RequestInit) => Promise<T>;
     deployStaticPreview: (directory: string, label: string) => Promise<RiddlePreviewDeployResult>;
     runScript: (input: RiddleRunScriptInput) => Promise<Record<string, unknown>>;
+    runServerPreview: (input: RiddleServerPreviewInput) => Promise<RiddleServerPreviewResult>;
     pollJob: (jobId: string, options?: {
         wait?: boolean;
         attempts?: number;
@@ -68,4 +99,4 @@ declare function createRiddleApiClient(config?: RiddleClientConfig): {
     }) => Promise<RiddlePollJobResult>;
 };
 
-export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, type RiddleClientConfig, type RiddleFetch, type RiddlePollJobResult, type RiddlePreviewDeployResult, type RiddleRunScriptInput, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript };
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, type RiddleClientConfig, type RiddleFetch, type RiddlePollJobResult, type RiddlePreviewDeployResult, type RiddleRunScriptInput, type RiddleServerPreviewInput, type RiddleServerPreviewResult, createRiddleApiClient, deployRiddleStaticPreview, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, riddleRequestJson, runRiddleScript, runRiddleServerPreview };

package/dist/riddle-client.js

@@ -9,8 +9,9 @@ import {
   pollRiddleJob,
   resolveRiddleApiKey,
   riddleRequestJson,
-  runRiddleScript
-} from "./chunk-UR6ADV4Y.js";
+  runRiddleScript,
+  runRiddleServerPreview
+} from "./chunk-3CVGVQTQ.js";
 export {
   DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE,
@@ -22,5 +23,6 @@ export {
   pollRiddleJob,
   resolveRiddleApiKey,
   riddleRequestJson,
-  runRiddleScript
+  runRiddleScript,
+  runRiddleServerPreview
 };

package/package.json

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