@riddledc/riddle-proof 0.8.36 → 0.8.38

package/dist/pr-comment.cjs

@@ -0,0 +1,235 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/pr-comment.ts
+var pr_comment_exports = {};
+__export(pr_comment_exports, {
+  RIDDLE_PROOF_PR_COMMENT_MARKER: () => RIDDLE_PROOF_PR_COMMENT_MARKER,
+  buildRiddleProofPrCommentMarkdown: () => buildRiddleProofPrCommentMarkdown,
+  summarizeRiddleProofPrComment: () => summarizeRiddleProofPrComment
+});
+module.exports = __toCommonJS(pr_comment_exports);
+var RIDDLE_PROOF_PR_COMMENT_MARKER = "<!-- riddle-proof:pr-comment:v1 -->";
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+function stringValue(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function numberValue(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function booleanValue(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+function artifactKind(name, url) {
+  const target = `${name} ${url}`.toLowerCase();
+  if (/\.(png|jpe?g|gif|webp|avif|svg)(\?|#|$)/.test(target)) return "image";
+  if (/\.(json|har|txt|md|html|log)(\?|#|$)/.test(target)) return "data";
+  return "artifact";
+}
+function artifactDisplayName(value, fallback) {
+  const raw = stringValue(value);
+  if (raw) return raw;
+  return fallback;
+}
+function collectArtifacts(runResponse) {
+  const proofResult = asRecord(runResponse.proofResult);
+  const outputs = asArray(proofResult.outputs);
+  const artifacts = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, item] of outputs.entries()) {
+    const artifact = asRecord(item);
+    const url = stringValue(artifact.url);
+    if (!url || seen.has(url)) continue;
+    seen.add(url);
+    const name = artifactDisplayName(artifact.name, `artifact-${index + 1}`);
+    artifacts.push({
+      name,
+      url,
+      kind: artifactKind(name, url),
+      size_bytes: numberValue(artifact.size)
+    });
+  }
+  return artifacts;
+}
+function pageSummaries(result) {
+  const pages = [];
+  for (const page of asArray(result.pages)) {
+    const record = asRecord(page);
+    const route = stringValue(record.route) || stringValue(record.url) || "page";
+    const checks = asRecord(record.checks);
+    let passed = 0;
+    let failed = 0;
+    for (const value of Object.values(checks)) {
+      if (value === true) passed += 1;
+      if (value === false) failed += 1;
+    }
+    pages.push({ route, passed, failed });
+  }
+  return pages;
+}
+function summarizeExplicitChecks(value) {
+  let passed = 0;
+  let failed = 0;
+  const visit = (current, inChecks = false) => {
+    if (current === true && inChecks) {
+      passed += 1;
+      return;
+    }
+    if (current === false && inChecks) {
+      failed += 1;
+      return;
+    }
+    if (Array.isArray(current)) {
+      for (const item of current) visit(item, inChecks);
+      return;
+    }
+    if (current && typeof current === "object") {
+      for (const [key, item] of Object.entries(current)) {
+        visit(item, inChecks || key === "checks");
+      }
+    }
+  };
+  visit(value);
+  return { passed, failed };
+}
+function selectPrimaryImage(artifacts) {
+  const images = artifacts.filter((artifact) => artifact.kind === "image");
+  return images.find((artifact) => /after|proof|screenshot/i.test(artifact.name)) || images[0];
+}
+function summarizeRiddleProofPrComment(input) {
+  const runResponse = asRecord(input.runResponse);
+  const result = asRecord(input.result);
+  const proofResult = asRecord(runResponse.proofResult);
+  const preview = asRecord(runResponse.preview);
+  const artifacts = collectArtifacts(runResponse);
+  const pages = pageSummaries(result);
+  const checkSource = { ...result };
+  delete checkSource.ok;
+  const nestedChecks = summarizeExplicitChecks(checkSource);
+  const ok = booleanValue(result.ok) ?? booleanValue(runResponse.ok) ?? null;
+  return {
+    ok,
+    status: stringValue(proofResult.status),
+    job_id: stringValue(proofResult.job_id),
+    duration_ms: numberValue(proofResult.duration_ms),
+    proof_url: stringValue(runResponse.proofUrl),
+    preview_id: stringValue(preview.id),
+    preview_url: stringValue(preview.preview_url) || stringValue(preview.url),
+    preview_publish_recovered: booleanValue(preview.publish_recovered),
+    preview_publish_error: stringValue(preview.publish_error),
+    passed_checks: nestedChecks.passed,
+    failed_checks: nestedChecks.failed,
+    pages,
+    artifacts,
+    primary_image: selectPrimaryImage(artifacts)
+  };
+}
+function formatDuration(ms) {
+  if (typeof ms !== "number" || !Number.isFinite(ms)) return "";
+  const seconds = Math.max(0, Math.round(ms / 1e3));
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  return minutes > 0 ? `${minutes}m${String(remainder).padStart(2, "0")}s` : `${seconds}s`;
+}
+function markdownLink(label, url) {
+  return `[${label.replace(/\]/g, "\\]")}](${url})`;
+}
+function resultLabel(summary) {
+  if (summary.ok === true) return "passed";
+  if (summary.ok === false) return "failed";
+  return summary.status || "recorded";
+}
+function artifactRank(artifact) {
+  const name = artifact.name.toLowerCase();
+  if (name === "proof.json") return 0;
+  if (name === "result.json") return 1;
+  if (name.includes("proof") && name.endsWith(".json") && !name.includes("layout")) return 2;
+  if (name === "console.json") return 3;
+  if (artifact.kind === "data") return 10;
+  if (artifact.kind === "image") return 20;
+  return 30;
+}
+function buildRiddleProofPrCommentMarkdown(input) {
+  const summary = summarizeRiddleProofPrComment(input);
+  const title = input.title?.trim() || "Riddle Proof Evidence";
+  const lines = [
+    RIDDLE_PROOF_PR_COMMENT_MARKER,
+    `## ${title}`,
+    "",
+    `**Result:** ${resultLabel(summary)}`
+  ];
+  if (input.goal?.trim()) lines.push(`**Goal:** ${input.goal.trim()}`);
+  if (input.successCriteria?.trim()) lines.push(`**Success criteria:** ${input.successCriteria.trim()}`);
+  if (summary.status) lines.push(`**Riddle job status:** ${summary.status}`);
+  if (summary.job_id) lines.push(`**Riddle job:** \`${summary.job_id}\``);
+  if (summary.duration_ms) lines.push(`**Duration:** ${formatDuration(summary.duration_ms)}`);
+  if (summary.proof_url) lines.push(`**Proof URL:** ${markdownLink(summary.proof_url, summary.proof_url)}`);
+  if (summary.preview_id || summary.preview_url) {
+    const previewLabel = summary.preview_id ? `\`${summary.preview_id}\`` : "preview";
+    lines.push(`**Preview:** ${summary.preview_url ? markdownLink(previewLabel, summary.preview_url) : previewLabel}`);
+  }
+  if (summary.preview_publish_recovered) {
+    const detail = summary.preview_publish_error ? `: ${summary.preview_publish_error}` : "";
+    lines.push(`**Preview publish recovery:** recovered after publish error${detail}`);
+  }
+  lines.push(`**Checks:** ${summary.passed_checks} passed / ${summary.failed_checks} failed`);
+  lines.push("");
+  if (summary.primary_image) {
+    lines.push("### Screenshot");
+    lines.push(`![${summary.primary_image.name}](${summary.primary_image.url})`);
+    lines.push("");
+  }
+  if (summary.pages.length) {
+    lines.push("### Page Checks");
+    for (const page of summary.pages.slice(0, 12)) {
+      lines.push(`- \`${page.route}\`: ${page.passed} passed / ${page.failed} failed`);
+    }
+    if (summary.pages.length > 12) lines.push(`- ${summary.pages.length - 12} more page(s) omitted`);
+    lines.push("");
+  }
+  const linkedArtifacts = summary.artifacts.filter((artifact) => artifact.url !== summary.primary_image?.url).sort((left, right) => artifactRank(left) - artifactRank(right) || left.name.localeCompare(right.name)).slice(0, 20);
+  if (linkedArtifacts.length) {
+    lines.push("### Artifacts");
+    for (const artifact of linkedArtifacts) {
+      lines.push(`- ${markdownLink(artifact.name, artifact.url)}`);
+    }
+    if (summary.artifacts.length - (summary.primary_image ? 1 : 0) > linkedArtifacts.length) {
+      lines.push(`- ${summary.artifacts.length - (summary.primary_image ? 1 : 0) - linkedArtifacts.length} more artifact(s) omitted`);
+    }
+    lines.push("");
+  }
+  if (input.source?.trim()) {
+    lines.push(`_Source: ${input.source.trim()}_`);
+  } else {
+    lines.push("_Updated by `riddle-proof-loop pr-comment`._");
+  }
+  return `${lines.join("\n").trim()}
+`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RIDDLE_PROOF_PR_COMMENT_MARKER,
+  buildRiddleProofPrCommentMarkdown,
+  summarizeRiddleProofPrComment
+});

package/dist/pr-comment.d.cts

@@ -0,0 +1,41 @@
+declare const RIDDLE_PROOF_PR_COMMENT_MARKER = "<!-- riddle-proof:pr-comment:v1 -->";
+type RiddleProofPrCommentArtifactKind = "image" | "data" | "artifact";
+interface RiddleProofPrCommentArtifact {
+    name: string;
+    url: string;
+    kind: RiddleProofPrCommentArtifactKind;
+    size_bytes?: number;
+}
+interface RiddleProofPrCommentPageSummary {
+    route: string;
+    passed: number;
+    failed: number;
+}
+interface RiddleProofPrCommentSummary {
+    ok: boolean | null;
+    status?: string;
+    job_id?: string;
+    duration_ms?: number;
+    proof_url?: string;
+    preview_id?: string;
+    preview_url?: string;
+    preview_publish_recovered?: boolean;
+    preview_publish_error?: string;
+    passed_checks: number;
+    failed_checks: number;
+    pages: RiddleProofPrCommentPageSummary[];
+    artifacts: RiddleProofPrCommentArtifact[];
+    primary_image?: RiddleProofPrCommentArtifact;
+}
+interface RiddleProofPrCommentInput {
+    title?: string;
+    goal?: string;
+    successCriteria?: string;
+    runResponse?: unknown;
+    result?: unknown;
+    source?: string;
+}
+declare function summarizeRiddleProofPrComment(input: RiddleProofPrCommentInput): RiddleProofPrCommentSummary;
+declare function buildRiddleProofPrCommentMarkdown(input: RiddleProofPrCommentInput): string;
+
+export { RIDDLE_PROOF_PR_COMMENT_MARKER, type RiddleProofPrCommentArtifact, type RiddleProofPrCommentArtifactKind, type RiddleProofPrCommentInput, type RiddleProofPrCommentPageSummary, type RiddleProofPrCommentSummary, buildRiddleProofPrCommentMarkdown, summarizeRiddleProofPrComment };

package/dist/pr-comment.d.ts

@@ -0,0 +1,41 @@
+declare const RIDDLE_PROOF_PR_COMMENT_MARKER = "<!-- riddle-proof:pr-comment:v1 -->";
+type RiddleProofPrCommentArtifactKind = "image" | "data" | "artifact";
+interface RiddleProofPrCommentArtifact {
+    name: string;
+    url: string;
+    kind: RiddleProofPrCommentArtifactKind;
+    size_bytes?: number;
+}
+interface RiddleProofPrCommentPageSummary {
+    route: string;
+    passed: number;
+    failed: number;
+}
+interface RiddleProofPrCommentSummary {
+    ok: boolean | null;
+    status?: string;
+    job_id?: string;
+    duration_ms?: number;
+    proof_url?: string;
+    preview_id?: string;
+    preview_url?: string;
+    preview_publish_recovered?: boolean;
+    preview_publish_error?: string;
+    passed_checks: number;
+    failed_checks: number;
+    pages: RiddleProofPrCommentPageSummary[];
+    artifacts: RiddleProofPrCommentArtifact[];
+    primary_image?: RiddleProofPrCommentArtifact;
+}
+interface RiddleProofPrCommentInput {
+    title?: string;
+    goal?: string;
+    successCriteria?: string;
+    runResponse?: unknown;
+    result?: unknown;
+    source?: string;
+}
+declare function summarizeRiddleProofPrComment(input: RiddleProofPrCommentInput): RiddleProofPrCommentSummary;
+declare function buildRiddleProofPrCommentMarkdown(input: RiddleProofPrCommentInput): string;
+
+export { RIDDLE_PROOF_PR_COMMENT_MARKER, type RiddleProofPrCommentArtifact, type RiddleProofPrCommentArtifactKind, type RiddleProofPrCommentInput, type RiddleProofPrCommentPageSummary, type RiddleProofPrCommentSummary, buildRiddleProofPrCommentMarkdown, summarizeRiddleProofPrComment };

package/dist/pr-comment.js

@@ -0,0 +1,11 @@
+import {
+  RIDDLE_PROOF_PR_COMMENT_MARKER,
+  buildRiddleProofPrCommentMarkdown,
+  summarizeRiddleProofPrComment
+} from "./chunk-6KYXX4OE.js";
+import "./chunk-MLKGABMK.js";
+export {
+  RIDDLE_PROOF_PR_COMMENT_MARKER,
+  buildRiddleProofPrCommentMarkdown,
+  summarizeRiddleProofPrComment
+};

package/dist/{proof-run-engine-DYUu2mqY.d.cts → proof-run-engine-4dM37pEx.d.cts}

@@ -292,7 +292,7 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
     blocking?: boolean;
     details?: Record<string, unknown>;
     ok: boolean;
-    action: "setup" | "recon" | "author" | "implement" | "verify" | "ship" | "run";
+    action: "author" | "recon" | "ship" | "implement" | "verify" | "setup" | "run";
     state_path: string;
     stage: any;
     summary: string;
@@ -382,7 +382,7 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
     continueWithStage?: WorkflowStage | null;
     blocking?: boolean;
     details?: Record<string, unknown>;
-    action: "setup" | "recon" | "author" | "implement" | "verify" | "ship" | "run";
+    action: "author" | "recon" | "ship" | "implement" | "verify" | "setup" | "run";
     state_path: string;
     stage: any;
     checkpoint: string;
@@ -659,7 +659,7 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
     error?: undefined;
 } | {
     ok: boolean;
-    action: "setup" | "recon" | "author" | "implement" | "verify" | "ship";
+    action: "author" | "recon" | "ship" | "implement" | "verify" | "setup";
     state_path: string;
     stage: any;
     summary: string;

package/dist/{proof-run-engine-BmNYuOJ7.d.ts → proof-run-engine-BqaeqAze.d.ts}

@@ -292,7 +292,7 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
     blocking?: boolean;
     details?: Record<string, unknown>;
     ok: boolean;
-    action: "setup" | "recon" | "author" | "implement" | "verify" | "ship" | "run";
+    action: "author" | "recon" | "ship" | "implement" | "verify" | "setup" | "run";
     state_path: string;
     stage: any;
     summary: string;
@@ -382,7 +382,7 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
     continueWithStage?: WorkflowStage | null;
     blocking?: boolean;
     details?: Record<string, unknown>;
-    action: "setup" | "recon" | "author" | "implement" | "verify" | "ship" | "run";
+    action: "author" | "recon" | "ship" | "implement" | "verify" | "setup" | "run";
     state_path: string;
     stage: any;
     checkpoint: string;
@@ -659,7 +659,7 @@ declare function executeWorkflow(params: WorkflowParams, pluginConfig: any, reso
     error?: undefined;
 } | {
     ok: boolean;
-    action: "setup" | "recon" | "author" | "implement" | "verify" | "ship";
+    action: "author" | "recon" | "ship" | "implement" | "verify" | "setup";
     state_path: string;
     stage: any;
     summary: string;

package/dist/proof-run-engine.d.cts

@@ -1,2 +1,2 @@
 import './proof-run-core-B1GeqkR8.cjs';
-export { R as RiddleProofEngine, c as createRiddleProofEngine, e as executeWorkflow } from './proof-run-engine-DYUu2mqY.cjs';
+export { R as RiddleProofEngine, c as createRiddleProofEngine, e as executeWorkflow } from './proof-run-engine-4dM37pEx.cjs';

package/dist/proof-run-engine.d.ts

@@ -1,2 +1,2 @@
 import './proof-run-core-B1GeqkR8.js';
-export { R as RiddleProofEngine, c as createRiddleProofEngine, e as executeWorkflow } from './proof-run-engine-BmNYuOJ7.js';
+export { R as RiddleProofEngine, c as createRiddleProofEngine, e as executeWorkflow } from './proof-run-engine-BqaeqAze.js';

package/dist/riddle-client.cjs

@@ -130,10 +130,68 @@ function previewDeployResultFromRecord(input) {
 function canRecoverPreviewPublish(error) {
   return error instanceof RiddleApiError && PREVIEW_PUBLISH_RECOVERY_STATUSES.has(error.status);
 }
+function summarizePreviewDirectory(directory) {
+  const stack = [directory];
+  let fileCount = 0;
+  let totalBytes = 0;
+  while (stack.length) {
+    const current = stack.pop();
+    for (const entry of (0, import_node_fs.readdirSync)(current, { withFileTypes: true })) {
+      const fullPath = import_node_path.default.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const stat = (0, import_node_fs.statSync)(fullPath);
+      fileCount += 1;
+      totalBytes += stat.size;
+    }
+  }
+  return { file_count: fileCount, total_bytes: totalBytes };
+}
+function previewProgressEmitter(config, base) {
+  return async (snapshot) => {
+    if (!config.onPreviewProgress) return;
+    await config.onPreviewProgress({
+      label: base.label,
+      framework: base.framework,
+      directory: base.directory,
+      elapsed_ms: Math.max(0, Date.now() - base.startedAt),
+      warnings: base.warnings?.length ? base.warnings : void 0,
+      ...snapshot
+    });
+  };
+}
 async function waitForPublishedPreview(config, input) {
+  await input.emitProgress?.({
+    stage: "publish_recovering",
+    id: input.id,
+    file_count: input.localSummary?.file_count,
+    total_bytes: input.localSummary?.total_bytes,
+    publish_error: input.publishError.message,
+    message: `publish returned ${input.publishError.status}; polling preview status`
+  });
   for (let attempt = 1; attempt <= PREVIEW_PUBLISH_RECOVERY_ATTEMPTS; attempt += 1) {
     const status = await riddleRequestJson(config, `/v1/preview/${input.id}`);
+    await input.emitProgress?.({
+      stage: "checking_status",
+      id: input.id,
+      attempt,
+      attempts: PREVIEW_PUBLISH_RECOVERY_ATTEMPTS,
+      status: typeof status.status === "string" ? status.status : null,
+      preview_url: typeof status.preview_url === "string" ? status.preview_url : void 0,
+      file_count: typeof status.file_count === "number" ? status.file_count : input.localSummary?.file_count,
+      total_bytes: typeof status.total_bytes === "number" ? status.total_bytes : input.localSummary?.total_bytes
+    });
     if (String(status.status || "") === "ready" && String(status.preview_url || "").trim()) {
+      await input.emitProgress?.({
+        stage: "ready",
+        id: input.id,
+        preview_url: String(status.preview_url),
+        file_count: typeof status.file_count === "number" ? status.file_count : input.localSummary?.file_count,
+        total_bytes: typeof status.total_bytes === "number" ? status.total_bytes : input.localSummary?.total_bytes
+      });
       return previewDeployResultFromRecord({
         record: status,
         id: input.id,
@@ -155,7 +213,17 @@ async function deployRiddlePreview(config, directory, label, framework = "static
   if (!directory?.trim()) throw new Error("directory is required");
   if (!label?.trim()) throw new Error("label is required");
   if (framework !== "spa" && framework !== "static") throw new Error("framework must be spa or static");
+  const startedAt = Date.now();
   const warnings = collectRiddlePreviewDeployWarnings(directory, framework);
+  const emitProgress = previewProgressEmitter(config, { label, framework, directory, startedAt, warnings });
+  await emitProgress({ stage: "validating", message: "checking preview input directory" });
+  const localSummary = summarizePreviewDirectory(directory);
+  await emitProgress({
+    stage: "creating",
+    file_count: localSummary.file_count,
+    total_bytes: localSummary.total_bytes,
+    message: "creating preview upload target"
+  });
   const created = await riddleRequestJson(config, "/v1/preview", {
     method: "POST",
     body: JSON.stringify({ framework, label })
@@ -163,10 +231,42 @@ async function deployRiddlePreview(config, directory, label, framework = "static
   const id = String(created.id || "");
   const uploadUrl = String(created.upload_url || "");
   if (!id || !uploadUrl) throw new Error("Riddle preview create response was missing id or upload_url.");
+  await emitProgress({
+    stage: "created",
+    id,
+    file_count: localSummary.file_count,
+    total_bytes: localSummary.total_bytes,
+    message: "preview upload target created"
+  });
   const scratch = (0, import_node_fs.mkdtempSync)(import_node_path.default.join((0, import_node_os.tmpdir)(), "riddle-preview-upload-"));
   const tarball = import_node_path.default.join(scratch, `${id}.tar.gz`);
+  let tarballBytes = 0;
   try {
+    await emitProgress({
+      stage: "archiving",
+      id,
+      file_count: localSummary.file_count,
+      total_bytes: localSummary.total_bytes,
+      message: "creating preview archive"
+    });
     (0, import_node_child_process.execFileSync)("tar", ["czf", tarball, "-C", directory, "."], { stdio: "pipe" });
+    tarballBytes = (0, import_node_fs.statSync)(tarball).size;
+    await emitProgress({
+      stage: "archived",
+      id,
+      file_count: localSummary.file_count,
+      total_bytes: localSummary.total_bytes,
+      tarball_bytes: tarballBytes,
+      message: "preview archive created"
+    });
+    await emitProgress({
+      stage: "uploading",
+      id,
+      file_count: localSummary.file_count,
+      total_bytes: localSummary.total_bytes,
+      tarball_bytes: tarballBytes,
+      message: "uploading preview archive"
+    });
     const upload = await fetchFor(config)(uploadUrl, {
       method: "PUT",
       headers: { "Content-Type": "application/gzip" },
@@ -175,14 +275,37 @@ async function deployRiddlePreview(config, directory, label, framework = "static
     if (!upload.ok) {
       throw new RiddleApiError(uploadUrl, upload.status, await upload.text());
     }
+    await emitProgress({
+      stage: "uploaded",
+      id,
+      file_count: localSummary.file_count,
+      total_bytes: localSummary.total_bytes,
+      tarball_bytes: tarballBytes,
+      message: "preview archive uploaded"
+    });
   } finally {
     (0, import_node_fs.rmSync)(scratch, { recursive: true, force: true });
   }
   const expiresAt = typeof created.expires_at === "string" ? created.expires_at : void 0;
   try {
+    await emitProgress({
+      stage: "publishing",
+      id,
+      file_count: localSummary.file_count,
+      total_bytes: localSummary.total_bytes,
+      tarball_bytes: tarballBytes || void 0,
+      message: "publishing preview"
+    });
     const published = await riddleRequestJson(config, `/v1/preview/${id}/publish`, {
       method: "POST"
     });
+    await emitProgress({
+      stage: "ready",
+      id,
+      preview_url: String(published.preview_url || ""),
+      file_count: typeof published.file_count === "number" ? published.file_count : localSummary.file_count,
+      total_bytes: typeof published.total_bytes === "number" ? published.total_bytes : localSummary.total_bytes
+    });
     return previewDeployResultFromRecord({ record: published, id, label, framework, expiresAt, warnings });
   } catch (error) {
     if (!canRecoverPreviewPublish(error)) throw error;
@@ -192,7 +315,9 @@ async function deployRiddlePreview(config, directory, label, framework = "static
       framework,
       expiresAt,
       publishError: error,
-      warnings
+      warnings,
+      localSummary,
+      emitProgress
     });
   }
 }

package/dist/riddle-client.d.cts

@@ -6,6 +6,7 @@ interface RiddleClientConfig {
     apiKeyFile?: string;
     apiBaseUrl?: string;
     fetchImpl?: RiddleFetch;
+    onPreviewProgress?: (snapshot: RiddlePreviewDeployProgressSnapshot) => void | Promise<void>;
 }
 interface RiddleApiKeySource {
     source: "option" | "env" | "file";
@@ -54,6 +55,25 @@ interface RiddlePollJobOptions {
     onProgress?: (snapshot: RiddlePollProgressSnapshot) => void | Promise<void>;
 }
 type RiddlePreviewFramework = "spa" | "static";
+type RiddlePreviewDeployStage = "validating" | "creating" | "created" | "archiving" | "archived" | "uploading" | "uploaded" | "publishing" | "publish_recovering" | "checking_status" | "ready";
+interface RiddlePreviewDeployProgressSnapshot {
+    stage: RiddlePreviewDeployStage;
+    label: string;
+    framework: RiddlePreviewFramework;
+    directory: string;
+    elapsed_ms: number;
+    id?: string;
+    preview_url?: string;
+    file_count?: number;
+    total_bytes?: number;
+    tarball_bytes?: number;
+    attempt?: number;
+    attempts?: number;
+    status?: string | null;
+    publish_error?: string;
+    warnings?: string[];
+    message?: string;
+}
 interface RiddlePreviewDeployResult {
     ok: true;
     id: string;
@@ -151,4 +171,4 @@ declare function createRiddleApiClient(config?: RiddleClientConfig): {
     pollJob: (jobId: string, options?: RiddlePollJobOptions) => Promise<RiddlePollJobResult>;
 };
 
-export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, type RiddleApiKeySource, type RiddleBalanceResult, type RiddleClientConfig, type RiddleFetch, type RiddlePollJobOptions, type RiddlePollJobResult, type RiddlePollProgressSnapshot, type RiddlePollSummary, type RiddlePreviewDeployResult, type RiddlePreviewFramework, type RiddleRunScriptInput, type RiddleServerPreviewInput, type RiddleServerPreviewResult, collectRiddlePreviewDeployWarnings, createRiddleApiClient, deployRiddlePreview, deployRiddleStaticPreview, getRiddleBalance, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, resolveRiddleApiKeySource, riddleRequestJson, runRiddleScript, runRiddleServerPreview };
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, type RiddleApiKeySource, type RiddleBalanceResult, type RiddleClientConfig, type RiddleFetch, type RiddlePollJobOptions, type RiddlePollJobResult, type RiddlePollProgressSnapshot, type RiddlePollSummary, type RiddlePreviewDeployProgressSnapshot, type RiddlePreviewDeployResult, type RiddlePreviewDeployStage, type RiddlePreviewFramework, type RiddleRunScriptInput, type RiddleServerPreviewInput, type RiddleServerPreviewResult, collectRiddlePreviewDeployWarnings, createRiddleApiClient, deployRiddlePreview, deployRiddleStaticPreview, getRiddleBalance, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, resolveRiddleApiKeySource, riddleRequestJson, runRiddleScript, runRiddleServerPreview };

package/dist/riddle-client.d.ts

@@ -6,6 +6,7 @@ interface RiddleClientConfig {
     apiKeyFile?: string;
     apiBaseUrl?: string;
     fetchImpl?: RiddleFetch;
+    onPreviewProgress?: (snapshot: RiddlePreviewDeployProgressSnapshot) => void | Promise<void>;
 }
 interface RiddleApiKeySource {
     source: "option" | "env" | "file";
@@ -54,6 +55,25 @@ interface RiddlePollJobOptions {
     onProgress?: (snapshot: RiddlePollProgressSnapshot) => void | Promise<void>;
 }
 type RiddlePreviewFramework = "spa" | "static";
+type RiddlePreviewDeployStage = "validating" | "creating" | "created" | "archiving" | "archived" | "uploading" | "uploaded" | "publishing" | "publish_recovering" | "checking_status" | "ready";
+interface RiddlePreviewDeployProgressSnapshot {
+    stage: RiddlePreviewDeployStage;
+    label: string;
+    framework: RiddlePreviewFramework;
+    directory: string;
+    elapsed_ms: number;
+    id?: string;
+    preview_url?: string;
+    file_count?: number;
+    total_bytes?: number;
+    tarball_bytes?: number;
+    attempt?: number;
+    attempts?: number;
+    status?: string | null;
+    publish_error?: string;
+    warnings?: string[];
+    message?: string;
+}
 interface RiddlePreviewDeployResult {
     ok: true;
     id: string;
@@ -151,4 +171,4 @@ declare function createRiddleApiClient(config?: RiddleClientConfig): {
     pollJob: (jobId: string, options?: RiddlePollJobOptions) => Promise<RiddlePollJobResult>;
 };
 
-export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, type RiddleApiKeySource, type RiddleBalanceResult, type RiddleClientConfig, type RiddleFetch, type RiddlePollJobOptions, type RiddlePollJobResult, type RiddlePollProgressSnapshot, type RiddlePollSummary, type RiddlePreviewDeployResult, type RiddlePreviewFramework, type RiddleRunScriptInput, type RiddleServerPreviewInput, type RiddleServerPreviewResult, collectRiddlePreviewDeployWarnings, createRiddleApiClient, deployRiddlePreview, deployRiddleStaticPreview, getRiddleBalance, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, resolveRiddleApiKeySource, riddleRequestJson, runRiddleScript, runRiddleServerPreview };
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, type RiddleApiKeySource, type RiddleBalanceResult, type RiddleClientConfig, type RiddleFetch, type RiddlePollJobOptions, type RiddlePollJobResult, type RiddlePollProgressSnapshot, type RiddlePollSummary, type RiddlePreviewDeployProgressSnapshot, type RiddlePreviewDeployResult, type RiddlePreviewDeployStage, type RiddlePreviewFramework, type RiddleRunScriptInput, type RiddleServerPreviewInput, type RiddleServerPreviewResult, collectRiddlePreviewDeployWarnings, createRiddleApiClient, deployRiddlePreview, deployRiddleStaticPreview, getRiddleBalance, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, resolveRiddleApiKeySource, riddleRequestJson, runRiddleScript, runRiddleServerPreview };

package/dist/riddle-client.js

@@ -15,7 +15,7 @@ import {
   riddleRequestJson,
   runRiddleScript,
   runRiddleServerPreview
-} from "./chunk-TWTEUS7R.js";
+} from "./chunk-DI2XNGEZ.js";
 import "./chunk-MLKGABMK.js";
 export {
   DEFAULT_RIDDLE_API_BASE_URL,