@riddledc/riddle-proof 0.8.35 → 0.8.37

package/dist/profile.cjs

@@ -1378,6 +1378,8 @@ function normalizeSetupAction(input, index) {
     expect_changed: booleanValue(valueFromOwn(input, "expect_changed", "expectChanged", "should_change", "shouldChange", "changed")),
     until_path: untilPath,
     until_expected_value: hasUntilExpectedValue ? toJsonValue(valueFromOwn(input, "until_expected_value", "untilExpectedValue", "until_expected", "untilExpected", "until_value", "untilValue", "expected_value", "expectedValue", "expected")) : void 0,
+    expected_path: stringFromOwn(input, "expected_path", "expectedPath", "expected_terminal_path", "expectedTerminalPath"),
+    expected_url: stringFromOwn(input, "expected_url", "expectedUrl", "expected_terminal_url", "expectedTerminalUrl"),
     max_calls: maxCalls,
     tap_burst_size: tapBurstSize,
     settle_ms: settleMs,
@@ -3735,6 +3737,80 @@ function routePathMatches(observed, expected, targetUrl) {
   if (normalizedObserved === normalizedExpected) return true;
   return normalizedObserved === normalizeRoutePath(mountedExpectedRoutePath(targetUrl, expected));
 }
+function setupActionExpectedRoute(action) {
+  const expectedUrl = typeof action.expected_url === "string" && action.expected_url.trim()
+    ? action.expected_url.trim()
+    : typeof action.expectedUrl === "string" && action.expectedUrl.trim()
+      ? action.expectedUrl.trim()
+      : "";
+  const expectedPath = typeof action.expected_path === "string" && action.expected_path.trim()
+    ? action.expected_path.trim()
+    : typeof action.expectedPath === "string" && action.expectedPath.trim()
+      ? action.expectedPath.trim()
+      : "";
+  if (!expectedUrl && !expectedPath) return null;
+  return { expected_url: expectedUrl || undefined, expected_path: expectedPath || undefined };
+}
+function setupUrlMatchesExpectedRoute(href, expected) {
+  if (!expected) return true;
+  let observedUrl;
+  try {
+    observedUrl = new URL(href, targetUrl);
+  } catch {
+    return false;
+  }
+  if (expected.expected_url) {
+    let expectedUrl;
+    try {
+      expectedUrl = new URL(expected.expected_url, targetUrl);
+    } catch {
+      return false;
+    }
+    return observedUrl.href === expectedUrl.href;
+  }
+  const expectedPath = expected.expected_path || "/";
+  if (/[?#]/.test(expectedPath)) {
+    const observedRoute = observedUrl.pathname + observedUrl.search + observedUrl.hash;
+    const normalizedObservedRoute = observedRoute === "/" ? "/" : observedRoute.replace(/\/+(?=[?#]|$)/, "");
+    const normalizedExpectedRoute = expectedPath === "/" ? "/" : expectedPath.replace(/\/+(?=[?#]|$)/, "");
+    return normalizedObservedRoute === normalizedExpectedRoute;
+  }
+  return routePathMatches(observedUrl.pathname, expectedPath, targetUrl);
+}
+function setupObservedRouteEvidence(expected, waitError) {
+  let observedUrl = page.url();
+  let observedPath = "";
+  let observedRoute = "";
+  try {
+    const url = new URL(observedUrl, targetUrl);
+    observedUrl = url.href;
+    observedPath = url.pathname;
+    observedRoute = url.pathname + url.search + url.hash;
+  } catch {
+    observedPath = "";
+    observedRoute = "";
+  }
+  return {
+    expected_url: expected && expected.expected_url || undefined,
+    expected_path: expected && expected.expected_path || undefined,
+    observed_url: observedUrl,
+    observed_path: observedPath,
+    observed_route: observedRoute,
+    route_matched: setupUrlMatchesExpectedRoute(observedUrl, expected),
+    route_wait_error: waitError ? String(waitError && waitError.message ? waitError.message : waitError).slice(0, 1000) : undefined,
+  };
+}
+async function waitForSetupActionRoute(action, timeout) {
+  const expected = setupActionExpectedRoute(action);
+  if (!expected) return null;
+  let waitError;
+  try {
+    await page.waitForURL((url) => setupUrlMatchesExpectedRoute(url.href, expected), { timeout: Math.min(timeout, 20000) });
+  } catch (error) {
+    waitError = error;
+  }
+  return setupObservedRouteEvidence(expected, waitError);
+}
 function routeOk(route, targetUrl) {
   return Boolean(route && (route.matched || routePathMatches(route.observed, route.expected_path, targetUrl)) && !route.error && (route.http_status == null || route.http_status < 400));
 }
@@ -6628,11 +6704,22 @@ async function executeSetupAction(action, ordinal, viewport) {
       const prepared = await resolveSetupTapTarget(action, base, scope, timeout);
       if (prepared.result) return prepared.result;
       await dispatchSetupTapPoint(prepared.target.point, prepared.target.pointerType, prepared.target.durationMs);
+      const routeEvidence = await waitForSetupActionRoute(action, timeout);
+      if (routeEvidence && !routeEvidence.route_matched) {
+        return {
+          ...base,
+          ...setupScopeEvidence(scope),
+          ...setupTapTargetEvidence(prepared.target),
+          ...routeEvidence,
+          reason: "expected_route_not_reached",
+        };
+      }
       return {
         ...base,
         ...setupScopeEvidence(scope),
         ok: true,
         ...setupTapTargetEvidence(prepared.target),
+        ...routeEvidence,
       };
     }
     if (type === "tap_until") {
@@ -7493,6 +7580,26 @@ async function executeSetupAction(action, ordinal, viewport) {
           : { x: box.x + box.width / 2, y: box.y + box.height / 2 };
         if (clickCount > 1) await page.mouse.click(fallbackPoint.x, fallbackPoint.y, { clickCount });
         else await page.mouse.click(fallbackPoint.x, fallbackPoint.y);
+        const routeEvidence = await waitForSetupActionRoute(action, timeout);
+        if (routeEvidence && !routeEvidence.route_matched) {
+          return {
+            ...base,
+            ...setupScopeEvidence(scope),
+            count,
+            target_index: targetIndex,
+            text: matchedText,
+            force: action.force === true || undefined,
+            fallback_to_tap: true,
+            input_dispatch: "playwright_mouse",
+            click_error: String(error && error.message ? error.message : error).slice(0, 1000),
+            click_count: clickCount > 1 ? clickCount : undefined,
+            coordinate_mode: mode,
+            x: position ? fromX : undefined,
+            y: position ? fromY : undefined,
+            ...routeEvidence,
+            reason: "expected_route_not_reached",
+          };
+        }
         return {
           ...base,
           ...setupScopeEvidence(scope),
@@ -7508,6 +7615,24 @@ async function executeSetupAction(action, ordinal, viewport) {
           coordinate_mode: mode,
           x: position ? fromX : undefined,
           y: position ? fromY : undefined,
+          ...routeEvidence,
+        };
+      }
+      const routeEvidence = await waitForSetupActionRoute(action, timeout);
+      if (routeEvidence && !routeEvidence.route_matched) {
+        return {
+          ...base,
+          ...setupScopeEvidence(scope),
+          count,
+          target_index: targetIndex,
+          text: matchedText,
+          force: action.force === true || undefined,
+          click_count: clickCount > 1 ? clickCount : undefined,
+          coordinate_mode: mode,
+          x: position ? fromX : undefined,
+          y: position ? fromY : undefined,
+          ...routeEvidence,
+          reason: "expected_route_not_reached",
         };
       }
       return {
@@ -7522,6 +7647,7 @@ async function executeSetupAction(action, ordinal, viewport) {
         coordinate_mode: mode,
         x: position ? fromX : undefined,
         y: position ? fromY : undefined,
+        ...routeEvidence,
       };
     }
     if (type === "fill" || type === "set_input_value") {

package/dist/profile.d.cts

@@ -145,6 +145,8 @@ interface RiddleProofProfileSetupAction {
     expect_changed?: boolean;
     until_path?: string;
     until_expected_value?: JsonValue;
+    expected_path?: string;
+    expected_url?: string;
     max_calls?: number;
     tap_burst_size?: number;
     settle_ms?: number;

package/dist/profile.d.ts

@@ -145,6 +145,8 @@ interface RiddleProofProfileSetupAction {
     expect_changed?: boolean;
     until_path?: string;
     until_expected_value?: JsonValue;
+    expected_path?: string;
+    expected_url?: string;
     max_calls?: number;
     tap_burst_size?: number;
     settle_ms?: number;

package/dist/profile.js

@@ -23,7 +23,7 @@ import {
   resolveRiddleProofProfileTimeoutSec,
   slugifyRiddleProofProfileName,
   summarizeRiddleProofProfileResult
-} from "./chunk-PEWAIEER.js";
+} from "./chunk-Z2LCVROU.js";
 import "./chunk-MLKGABMK.js";
 export {
   RIDDLE_PROOF_PROFILE_CHECK_TYPES,

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,

package/dist/runtime/index.cjs

@@ -132,10 +132,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,
@@ -157,7 +215,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 })
@@ -165,10 +233,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" },
@@ -177,14 +277,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;
@@ -194,7 +317,9 @@ async function deployRiddlePreview(config, directory, label, framework = "static
       framework,
       expiresAt,
       publishError: error,
-      warnings
+      warnings,
+      localSummary,
+      emitProgress
     });
   }
 }

package/dist/runtime/index.d.cts

@@ -1 +1 @@
-export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleApiKeySource, RiddleBalanceResult, RiddleClientConfig, RiddleFetch, RiddlePollJobOptions, RiddlePollJobResult, RiddlePollProgressSnapshot, RiddlePollSummary, RiddlePreviewDeployResult, RiddlePreviewFramework, RiddleRunScriptInput, RiddleServerPreviewInput, RiddleServerPreviewResult, collectRiddlePreviewDeployWarnings, createRiddleApiClient, deployRiddlePreview, deployRiddleStaticPreview, getRiddleBalance, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, resolveRiddleApiKeySource, riddleRequestJson, runRiddleScript, runRiddleServerPreview } from '../riddle-client.cjs';
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleApiKeySource, RiddleBalanceResult, RiddleClientConfig, RiddleFetch, RiddlePollJobOptions, RiddlePollJobResult, RiddlePollProgressSnapshot, RiddlePollSummary, RiddlePreviewDeployProgressSnapshot, RiddlePreviewDeployResult, RiddlePreviewDeployStage, RiddlePreviewFramework, RiddleRunScriptInput, RiddleServerPreviewInput, RiddleServerPreviewResult, collectRiddlePreviewDeployWarnings, createRiddleApiClient, deployRiddlePreview, deployRiddleStaticPreview, getRiddleBalance, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, resolveRiddleApiKeySource, riddleRequestJson, runRiddleScript, runRiddleServerPreview } from '../riddle-client.cjs';

package/dist/runtime/index.d.ts

@@ -1 +1 @@
-export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleApiKeySource, RiddleBalanceResult, RiddleClientConfig, RiddleFetch, RiddlePollJobOptions, RiddlePollJobResult, RiddlePollProgressSnapshot, RiddlePollSummary, RiddlePreviewDeployResult, RiddlePreviewFramework, RiddleRunScriptInput, RiddleServerPreviewInput, RiddleServerPreviewResult, collectRiddlePreviewDeployWarnings, createRiddleApiClient, deployRiddlePreview, deployRiddleStaticPreview, getRiddleBalance, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, resolveRiddleApiKeySource, riddleRequestJson, runRiddleScript, runRiddleServerPreview } from '../riddle-client.js';
+export { DEFAULT_RIDDLE_API_BASE_URL, DEFAULT_RIDDLE_API_KEY_FILE, RiddleApiError, RiddleApiKeySource, RiddleBalanceResult, RiddleClientConfig, RiddleFetch, RiddlePollJobOptions, RiddlePollJobResult, RiddlePollProgressSnapshot, RiddlePollSummary, RiddlePreviewDeployProgressSnapshot, RiddlePreviewDeployResult, RiddlePreviewDeployStage, RiddlePreviewFramework, RiddleRunScriptInput, RiddleServerPreviewInput, RiddleServerPreviewResult, collectRiddlePreviewDeployWarnings, createRiddleApiClient, deployRiddlePreview, deployRiddleStaticPreview, getRiddleBalance, isTerminalRiddleJobStatus, parseRiddleViewport, pollRiddleJob, resolveRiddleApiKey, resolveRiddleApiKeySource, riddleRequestJson, runRiddleScript, runRiddleServerPreview } from '../riddle-client.js';

package/dist/runtime/index.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,