@spark-apps/quickpeek 1.2.0 → 1.2.2

package/dist/{scraping-BK8pIJhm.d.mts → scraping-BgepklP3.d.mts}

@@ -1,7 +1,7 @@
 /**
  * Configuration types and defaults for QuickPeek
  */
-declare const VERSION = "1.1.1";
+declare const VERSION = "1.2.1";
 declare const CONFIG_FILE = "quickpeek.config.json";
 type UserTier = 'free' | 'pro';
 interface Config {
@@ -27,6 +27,8 @@ interface Config {
         contrast: number;
         tempo: number;
         stepDelay: number;
+        outro?: string;
+        zoom?: number;
     };
     audio?: {
         voice?: string;
@@ -91,18 +93,48 @@ interface AIError {
     isRateLimit?: boolean;
     isAuthError?: boolean;
     retryAfterSeconds?: number;
+    /** Upstream HTTP status, when the failure was an HTTP response. */
+    status?: number;
+    /** Host that produced the failure, so relay vs backend is distinguishable. */
+    host?: string;
+    /** Raw response body (truncated), for the error log. */
+    detail?: string;
 }
 type AIResult = AIResponse | AIError;
+/** Called before each backoff so the CLI can explain a long pause. */
+type RetryNotice = (info: {
+    attempt: number;
+    status: number;
+    delayMs: number;
+    host: string;
+}) => void;
+interface ChatOptions {
+    onRetry?: RetryNotice;
+    /**
+     * Backoff before each 5xx retry. Defaults to SERVER_BACKOFF_MS, which is
+     * sized to fit inside a serverless function budget — callAI runs inside the
+     * quickpeek-web routes as well as the CLI. Interactive callers should pass
+     * CLI_BACKOFF_MS, which can afford to outwait the backend's closed window.
+     */
+    backoffMs?: number[];
+}
+/** Short enough to stay well inside a serverless maxDuration. */
+declare const SERVER_BACKOFF_MS: number[];
+/**
+ * Long enough to outlast the AI backend's ~45-60s closed window (measured
+ * 16 Aug 2026). Only safe where a human is waiting on a spinner.
+ */
+declare const CLI_BACKOFF_MS: number[];
 /**
  * Direct Spark AI call using the runtime SPARK_AI_KEY (dev + server-side use).
  */
-declare function callAI(systemPrompt: string, userPrompt: string, tier?: UserTier): Promise<AIResult>;
+declare function callAI(systemPrompt: string, userPrompt: string, tier?: UserTier, opts?: ChatOptions): Promise<AIResult>;
 /**
  * Relayed Spark AI call for the published CLI: authenticates with the user's
  * registered email via quickpeek-web, which holds the real key server-side
  * and enforces per-user daily limits.
  */
-declare function callAIViaRelay(systemPrompt: string, userPrompt: string, email: string, tier?: UserTier): Promise<AIResult>;
+declare function callAIViaRelay(systemPrompt: string, userPrompt: string, email: string, tier?: UserTier, opts?: ChatOptions): Promise<AIResult>;
 /**
  * Parse AI-generated plan JSON from response text
  */
@@ -179,6 +211,15 @@ interface Plan {
  * Page crawling and interactive element extraction
  */
 
+/**
+ * A selector matching one id.
+ *
+ * HTML ids are far more permissive than CSS identifiers: `description-(optional)`
+ * is a perfectly legal id, but `#description-(optional)` is invalid CSS and
+ * Playwright rejects it, so the step silently finds nothing. Anything that is
+ * not identifier-safe gets the attribute form instead.
+ */
+declare function idSelector(id: string): string;
 /**
  * Crawl a page and extract interactive elements with smart selectors
  * Results are cached in-memory for a few minutes to avoid duplicate browser launches
@@ -187,9 +228,13 @@ interface Plan {
  */
 declare function crawlPage(url: string, task?: (text: string) => {
     succeed: (text?: string) => void;
-}, storageStatePath?: string): Promise<{
+}, storageStatePath?: string, viewport?: {
+    width: number;
+    height: number;
+}): Promise<{
     title: string;
     elements: ElementInfo[];
+    scrollable: number;
 }>;
 
 /**
@@ -229,7 +274,7 @@ declare function toTitleCase(text: string): string;
  */
 
 declare function buildSystemPrompt(maxSteps: number): string;
-declare function buildUserPrompt(url: string, title: string, elements: ElementInfo[], langName: string | null, description: string | undefined, maxSteps: number): string;
+declare function buildUserPrompt(url: string, title: string, elements: ElementInfo[], langName: string | null, description: string | undefined, maxSteps: number, scrollable?: number): string;
 
 type Tier = 'free' | 'pro';
 declare const FEATURES: Record<string, string[]>;
@@ -287,4 +332,4 @@ declare function isExcludedLink(text: string, href?: string): boolean;
 /** Check if a link should be skipped during crawling */
 declare function shouldSkipLink(text: string, href: string, currentPath: string): boolean;
 
-export { type AIError as A, isPaid as B, type Config as C, DEFAULT_CAPTIONS as D, EXCLUDED_LINK_PATTERNS as E, FEATURES as F, isVerified as G, type HighlightMode as H, INTERACTIVE_SELECTORS as I, normalizeUrl as J, parseAIPlanResponse as K, parsePartial as L, pricingUrl as M, rgbaToHex as N, shouldSkipLink as O, type Plan as P, showPaywall as Q, type RateLimitInfo as R, type SparkStatus as S, type Tier as T, type UserTier as U, VERSION as V, toTitleCase as W, getTier as X, type AIResponse as a, type AIResult as b, CONFIG_FILE as c, type CaptionStyle as d, type CaptionWordStyle as e, DEFAULT_CONFIG as f, type ElementInfo as g, type ElementType as h, type SparkSubscription as i, type SparkTrial as j, type Step as k, type SuggestedAction as l, buildSystemPrompt as m, buildUserPrompt as n, callAI as o, callAIViaRelay as p, crawlPage as q, getErrorMessage as r, getLanguageName as s, getStatus as t, getStatusCached as u, getTierByEmail as v, hasAccess as w, hasTrialRemaining as x, isCanceling as y, isExcludedLink as z };
+export { toTitleCase as $, type AIError as A, hasAccess as B, type Config as C, DEFAULT_CAPTIONS as D, EXCLUDED_LINK_PATTERNS as E, FEATURES as F, hasTrialRemaining as G, type HighlightMode as H, INTERACTIVE_SELECTORS as I, idSelector as J, isCanceling as K, isExcludedLink as L, isPaid as M, isVerified as N, normalizeUrl as O, type Plan as P, parseAIPlanResponse as Q, type RateLimitInfo as R, SERVER_BACKOFF_MS as S, type Tier as T, type UserTier as U, VERSION as V, parsePartial as W, pricingUrl as X, rgbaToHex as Y, shouldSkipLink as Z, showPaywall as _, type AIResponse as a, getTier as a0, type AIResult as b, CLI_BACKOFF_MS as c, CONFIG_FILE as d, type CaptionStyle as e, type CaptionWordStyle as f, type ChatOptions as g, DEFAULT_CONFIG as h, type ElementInfo as i, type ElementType as j, type RetryNotice as k, type SparkStatus as l, type SparkSubscription as m, type SparkTrial as n, type Step as o, type SuggestedAction as p, buildSystemPrompt as q, buildUserPrompt as r, callAI as s, callAIViaRelay as t, crawlPage as u, getErrorMessage as v, getLanguageName as w, getStatus as x, getStatusCached as y, getTierByEmail as z };

package/dist/web.d.mts

@@ -1,6 +1,46 @@
-export { A as AIError, a as AIResponse, b as AIResult, E as EXCLUDED_LINK_PATTERNS, g as ElementInfo, h as ElementType, F as FEATURES, H as HighlightMode, I as INTERACTIVE_SELECTORS, P as Plan, R as RateLimitInfo, S as SparkStatus, i as SparkSubscription, j as SparkTrial, k as Step, l as SuggestedAction, T as Tier, m as buildSystemPrompt, n as buildUserPrompt, o as callAI, q as crawlPage, r as getErrorMessage, s as getLanguageName, t as getStatus, u as getStatusCached, X as getTier, v as getTierByEmail, w as hasAccess, x as hasTrialRemaining, y as isCanceling, z as isExcludedLink, B as isPaid, G as isVerified, J as normalizeUrl, K as parseAIPlanResponse, L as parsePartial, M as pricingUrl, N as rgbaToHex, O as shouldSkipLink, Q as showPaywall, W as toTitleCase } from './scraping-BK8pIJhm.mjs';
+import { P as Plan } from './scraping-BgepklP3.mjs';
+export { A as AIError, a as AIResponse, b as AIResult, E as EXCLUDED_LINK_PATTERNS, i as ElementInfo, j as ElementType, F as FEATURES, H as HighlightMode, I as INTERACTIVE_SELECTORS, R as RateLimitInfo, l as SparkStatus, m as SparkSubscription, n as SparkTrial, o as Step, p as SuggestedAction, T as Tier, q as buildSystemPrompt, r as buildUserPrompt, s as callAI, u as crawlPage, v as getErrorMessage, w as getLanguageName, x as getStatus, y as getStatusCached, a0 as getTier, z as getTierByEmail, B as hasAccess, G as hasTrialRemaining, K as isCanceling, L as isExcludedLink, M as isPaid, N as isVerified, O as normalizeUrl, Q as parseAIPlanResponse, W as parsePartial, X as pricingUrl, Y as rgbaToHex, Z as shouldSkipLink, _ as showPaywall, $ as toTitleCase } from './scraping-BgepklP3.mjs';
 export { WIDE_VOICES as LANGUAGE_VOICES, hexToAss as hexToASS, windowsDrivePathToWsl as windowsPathToWSL } from '@spark-apps/video-kit';
 
+/**
+ * The plan file, and handing it to the browser editor.
+ *
+ * The JSON on disk is the source of truth: the CLI records from it, and the
+ * editor is a view onto it. The handover travels in a URL fragment, which no
+ * browser sends to a server — so editing a demo costs no upload, no account,
+ * and leaves no stored copy that can drift from the file being recorded.
+ *
+ * Mirrors VidLet's lib/project validate + file-io split, so whoever maintains
+ * both codebases finds the same shape in each.
+ */
+
+type ParseResult = {
+    ok: true;
+    plan: Plan;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Browsers accept far longer URLs than this, but shells, terminals and the
+ * `open` handlers in between are the weak link. Past it, the editor is opened
+ * empty and the user picks the file by hand.
+ */
+declare const MAX_HANDOFF_URL_CHARS = 32000;
+/** Canonical on-disk form: 2-space JSON with a trailing newline. */
+declare function serializePlan(plan: Plan): string;
+/**
+ * Parse plan JSON, rejecting anything the recorder could not act on. Steps
+ * missing an id are numbered rather than refused: the editor drops ids when
+ * a user adds a step by hand, and renumbering is what the CLI would do too.
+ */
+declare function parsePlanText(text: string): ParseResult;
+declare function encodePlan(plan: Plan): string;
+/** Decode a `#plan=` fragment. Same validation as reading the file. */
+declare function decodePlan(encoded: string): ParseResult;
+/** The editor URL carrying a plan, or null when it is too long to hand over. */
+declare function planEditorUrl(baseUrl: string, plan: Plan): string | null;
+
 /**
  * Plan Validation - Shared between CLI and Web
  * Contains validation logic, prompts, and value preservation utilities
@@ -100,4 +140,4 @@ declare function restorePreservedValues<T extends BaseStep & {
     mediaIdx: number;
 };
 
-export { ACTIONS_REQUIRING_TARGET, type BaseStep, type CLIPlan, type CLIStep, FIX_PLAN_SYSTEM_PROMPT, INVALID_TARGETS, type PreservedValues, REFINE_PLAN_SYSTEM_PROMPT, type StepAction, type StepFailure, collectPreservedValues, filterValidSteps, isInvalidTarget, isValidStep, restorePreservedValues, validateStep };
+export { ACTIONS_REQUIRING_TARGET, type BaseStep, type CLIPlan, type CLIStep, FIX_PLAN_SYSTEM_PROMPT, INVALID_TARGETS, MAX_HANDOFF_URL_CHARS, type ParseResult, Plan, type PreservedValues, REFINE_PLAN_SYSTEM_PROMPT, type StepAction, type StepFailure, collectPreservedValues, decodePlan, encodePlan, filterValidSteps, isInvalidTarget, isValidStep, parsePlanText, planEditorUrl, restorePreservedValues, serializePlan, validateStep };

package/dist/web.mjs

@@ -75,7 +75,7 @@ function getErrorMessage(err) {
   return err instanceof Error ? err.message : String(err);
 }
 function toTitleCase(text) {
-  return text.replace(/\w+/g, (word, index) => {
+  return text.replace(/\w+(?:'\w+)*/g, (word, index) => {
     if (index === 0) {
       return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
     }
@@ -87,13 +87,30 @@ function toTitleCase(text) {
 }
 
 // src/lib/api-client.ts
+var SERVER_BACKOFF_MS = [2e3, 4e3];
 var SPARK_AI_BASE = "https://sparkbrain.app";
 var SPARK_AI_CHAT = `${SPARK_AI_BASE}/api/chat`;
 var SPARK_AI_TOKEN = `${SPARK_AI_BASE}/api/models/token`;
 var RELAY_BASE = process.env.QUICKPEEK_API_BASE || "https://quickpeek.co";
 var RELAY_TOKEN_URL = `${RELAY_BASE}/api/cli/token`;
 var RELAY_CHAT_URL = `${RELAY_BASE}/api/cli/ai`;
-var API_KEY = process.env.SPARK_AI_KEY || "";
+function apiKey() {
+  return process.env.SPARK_AI_KEY || "";
+}
+function hostOf(url) {
+  try {
+    return new URL(url).host;
+  } catch {
+    return "AI service";
+  }
+}
+function firstLine(text) {
+  return truncate((text ?? "").trim().split("\n")[0] ?? "", 200);
+}
+function truncate(text, max) {
+  const trimmed = (text ?? "").trim();
+  return trimmed.length > max ? `${trimmed.slice(0, max)}\u2026` : trimmed;
+}
 var cachedDirectToken = null;
 async function getOrRefreshDirectToken() {
   const now = Date.now();
@@ -103,7 +120,7 @@ async function getOrRefreshDirectToken() {
   try {
     const response = await fetch(SPARK_AI_TOKEN, {
       method: "POST",
-      headers: { "X-Api-Key": API_KEY }
+      headers: { "X-Api-Key": apiKey() }
     });
     if (!response.ok) {
       throw new Error(`Token exchange failed: ${response.status} ${response.statusText}`);
@@ -121,8 +138,10 @@ async function getOrRefreshDirectToken() {
     throw new Error(`Failed to get Spark AI token: ${getErrorMessage(err)}`);
   }
 }
-async function executeChat(chatUrl, bearerToken, systemPrompt, userPrompt, tier) {
-  let lastRateLimitError = null;
+async function executeChat(chatUrl, bearerToken, systemPrompt, userPrompt, tier, opts = {}) {
+  const { onRetry, backoffMs = SERVER_BACKOFF_MS } = opts;
+  let lastRetriableError = null;
+  const host = hostOf(chatUrl);
   for (let attempt = 1; attempt <= 3; attempt++) {
     try {
       const response = await fetch(chatUrl, {
@@ -138,36 +157,53 @@ async function executeChat(chatUrl, bearerToken, systemPrompt, userPrompt, tier)
           ]
         })
       });
+      const bodyText = await response.text().catch(() => "");
       let data = {};
-      const contentType = response.headers.get("content-type") ?? "";
-      if (contentType.includes("application/json")) {
-        data = await response.json();
+      try {
+        data = bodyText ? JSON.parse(bodyText) : {};
+      } catch {
       }
       if (!response.ok) {
-        const error = data.error || `Spark AI error: ${response.status} ${response.statusText}`;
-        if (response.status === 429 && attempt < 3) {
-          const retryAfter = response.headers.get("Retry-After");
-          const delayMs = retryAfter ? parseInt(retryAfter, 10) * 1e3 : 1e3 * 2 ** (attempt - 1);
-          lastRateLimitError = {
+        const upstream = data.error || firstLine(bodyText) || response.statusText || "no error body";
+        const error = `${host} ${response.status}: ${upstream}`;
+        const detail = truncate(bodyText, 800);
+        const isRetriable = response.status === 429 || response.status >= 500;
+        if (isRetriable && attempt < 3) {
+          const retryAfter2 = response.headers.get("Retry-After");
+          const delayMs = retryAfter2 ? parseInt(retryAfter2, 10) * 1e3 : response.status >= 500 ? backoffMs[attempt - 1] ?? backoffMs[backoffMs.length - 1] ?? 2e3 : 1e3 * 2 ** (attempt - 1);
+          onRetry?.({ attempt, status: response.status, delayMs, host });
+          lastRetriableError = {
             success: false,
             error,
-            isRateLimit: true,
-            ...retryAfter ? { retryAfterSeconds: parseInt(retryAfter, 10) } : {}
+            isRateLimit: response.status === 429,
+            status: response.status,
+            host,
+            ...detail ? { detail } : {},
+            ...retryAfter2 ? { retryAfterSeconds: parseInt(retryAfter2, 10) } : {}
           };
           await new Promise((resolve) => setTimeout(resolve, Math.min(delayMs, 3e4)));
           continue;
         }
+        const retryAfter = response.headers.get("Retry-After");
+        const retryAfterSeconds = retryAfter ? parseInt(retryAfter, 10) : Number.NaN;
         return {
           success: false,
           error,
           isRateLimit: response.status === 429,
-          isAuthError: response.status === 401 || response.status === 403
+          isAuthError: response.status === 401 || response.status === 403,
+          status: response.status,
+          host,
+          ...detail ? { detail } : {},
+          ...Number.isFinite(retryAfterSeconds) ? { retryAfterSeconds } : {}
         };
       }
       if (!data.success || !data.response) {
         return {
           success: false,
-          error: data.error || "No response from Spark AI"
+          error: `${host} 200 but no content: ${data.error || firstLine(bodyText) || "empty response"}`,
+          status: response.status,
+          host,
+          ...bodyText ? { detail: truncate(bodyText, 800) } : {}
         };
       }
       return {
@@ -181,15 +217,17 @@ async function executeChat(chatUrl, bearerToken, systemPrompt, userPrompt, tier)
         }
       };
     } catch (err) {
-      if (attempt === 3) throw err;
+      if (attempt === 3) {
+        return { success: false, error: `${host} unreachable: ${getErrorMessage(err)}`, host };
+      }
       const delayMs = 1e3 * 2 ** (attempt - 1);
       await new Promise((resolve) => setTimeout(resolve, delayMs));
     }
   }
-  return lastRateLimitError || { success: false, error: "Request failed after retries" };
+  return lastRetriableError || { success: false, error: `${host}: request failed after retries`, host };
 }
-async function callAI(systemPrompt, userPrompt, tier = "free") {
-  if (!API_KEY) {
+async function callAI(systemPrompt, userPrompt, tier = "free", opts = {}) {
+  if (!apiKey()) {
     return {
       success: false,
       error: "AI service is not configured. Please report this issue.",
@@ -198,7 +236,7 @@ async function callAI(systemPrompt, userPrompt, tier = "free") {
   }
   try {
     const token = await getOrRefreshDirectToken();
-    return await executeChat(SPARK_AI_CHAT, token, systemPrompt, userPrompt, tier);
+    return await executeChat(SPARK_AI_CHAT, token, systemPrompt, userPrompt, tier, opts);
   } catch (err) {
     return { success: false, error: `Spark AI error: ${getErrorMessage(err)}` };
   }
@@ -329,6 +367,9 @@ function shouldSkipLink(text, href, currentPath) {
 }
 
 // src/lib/crawl.ts
+function idSelector(id) {
+  return /^[A-Za-z_-][\w-]*$/.test(id) ? `#${id}` : `[id="${id.replace(/(["\\])/g, "\\$1")}"]`;
+}
 function getActionForType(type) {
   switch (type) {
     case "button":
@@ -351,20 +392,29 @@ var noopTask = () => ({ succeed: () => {
 var CRAWL_CACHE_TTL_MS = 5 * 60 * 1e3;
 var CRAWL_CACHE_MAX_ENTRIES = 50;
 var crawlCache = /* @__PURE__ */ new Map();
-async function crawlPage(url, task = noopTask, storageStatePath) {
-  const cached = crawlCache.get(url);
+async function crawlPage(url, task = noopTask, storageStatePath, viewport) {
+  const cacheKey = viewport ? `${url}@${viewport.width}x${viewport.height}` : url;
+  const cached = crawlCache.get(cacheKey);
   if (cached && Date.now() - cached.timestamp < CRAWL_CACHE_TTL_MS) {
     task("Using cached crawl").succeed(`Found ${cached.elements.length} interactive elements (cached)`);
-    return { title: cached.title, elements: [...cached.elements] };
+    return { title: cached.title, elements: [...cached.elements], scrollable: cached.scrollable };
   }
   const browserTask = task("Launching browser");
   const browser = await chromium.launch({ headless: true });
-  const context = await browser.newContext(storageStatePath ? { storageState: storageStatePath } : {});
+  const context = await browser.newContext({
+    ...storageStatePath ? { storageState: storageStatePath } : {},
+    // Crawl at the size we will record at, or the measurements below describe
+    // a page nobody will ever see.
+    ...viewport ? { viewport } : {}
+  });
   const page = await context.newPage();
   browserTask.succeed(storageStatePath ? "Browser launched (signed in)" : "Browser launched");
   const crawlTask = task("Crawling page");
   await page.goto(url, { waitUntil: "networkidle", timeout: 3e4 });
   const title = await page.title();
+  const scrollable = await page.evaluate(
+    "Math.max(0, document.documentElement.scrollHeight - window.innerHeight)"
+  );
   const rawElements = await page.evaluate(`
     (() => {
       const items = [];
@@ -454,9 +504,9 @@ async function crawlPage(url, task = noopTask, storageStatePath) {
     } else if (el.isFile || el.type === "file") {
       selector = 'input[type="file"]';
     } else if (el.type === "range") {
-      selector = el.id ? `#${el.id}` : 'input[type="range"]';
+      selector = el.id ? idSelector(el.id) : 'input[type="range"]';
     } else if (el.type === "checkbox") {
-      selector = el.id ? `#${el.id}` : 'input[type="checkbox"]';
+      selector = el.id ? idSelector(el.id) : 'input[type="checkbox"]';
     } else if (el.type === "button") {
       if (btnTexts[el.text] === 1) {
         selector = `text="${el.text}"`;
@@ -466,7 +516,7 @@ async function crawlPage(url, task = noopTask, storageStatePath) {
     } else if (el.type === "link") {
       selector = `text="${el.text}"`;
     } else if (el.id) {
-      selector = `#${el.id}`;
+      selector = idSelector(el.id);
     } else if (el.name) {
       selector = `[name="${el.name}"]`;
     } else if (el.placeholder) {
@@ -494,12 +544,12 @@ async function crawlPage(url, task = noopTask, storageStatePath) {
   });
   await browser.close();
   crawlTask.succeed(`Found ${elements.length} interactive elements`);
-  crawlCache.set(url, { timestamp: Date.now(), title, elements: [...elements] });
+  crawlCache.set(cacheKey, { timestamp: Date.now(), title, elements: [...elements], scrollable });
   if (crawlCache.size > CRAWL_CACHE_MAX_ENTRIES) {
     const oldest = crawlCache.keys().next().value;
     if (oldest !== void 0) crawlCache.delete(oldest);
   }
-  return { title, elements };
+  return { title, elements, scrollable };
 }
 
 // src/lib/plan-validation.ts
@@ -733,6 +783,80 @@ function restorePreservedValues(step, preserved, indices) {
   return { uploadIdx, mediaIdx };
 }
 
+// src/lib/plan-file.ts
+var MAX_HANDOFF_URL_CHARS = 32e3;
+function serializePlan(plan) {
+  return `${JSON.stringify(plan, null, 2)}
+`;
+}
+function parsePlanText(text) {
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (e) {
+    return { ok: false, error: `Not valid JSON: ${e instanceof Error ? e.message : String(e)}` };
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return { ok: false, error: "A plan must be a JSON object." };
+  }
+  const candidate = raw;
+  if (typeof candidate.url !== "string" || !candidate.url.trim()) {
+    return { ok: false, error: "A plan needs a `url` to record." };
+  }
+  if (!Array.isArray(candidate.steps) || candidate.steps.length === 0) {
+    return { ok: false, error: "A plan needs at least one step." };
+  }
+  const steps = [];
+  for (const [index, step] of candidate.steps.entries()) {
+    if (!step || typeof step !== "object" || Array.isArray(step)) {
+      return { ok: false, error: `Step ${index + 1} is not an object.` };
+    }
+    const typed = step;
+    if (typeof typed.action !== "string" || !typed.action.trim()) {
+      return { ok: false, error: `Step ${index + 1} has no action.` };
+    }
+    const failure = validateStep(typed);
+    if (failure) return { ok: false, error: `Step ${index + 1}: ${failure}` };
+    steps.push({ ...typed, id: typed.id ?? index + 1 });
+  }
+  return {
+    ok: true,
+    plan: {
+      url: candidate.url,
+      title: candidate.title ?? "",
+      description: candidate.description ?? "",
+      ...candidate.lang ? { lang: candidate.lang } : {},
+      steps
+    }
+  };
+}
+function toBase64Url(text) {
+  const bytes = new TextEncoder().encode(text);
+  const binary = Array.from(bytes, (b) => String.fromCharCode(b)).join("");
+  const base64 = typeof btoa === "function" ? btoa(binary) : Buffer.from(text, "utf8").toString("base64");
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(encoded) {
+  const base64 = encoded.replace(/-/g, "+").replace(/_/g, "/");
+  if (typeof atob !== "function") return Buffer.from(base64, "base64").toString("utf8");
+  const binary = atob(base64);
+  return new TextDecoder().decode(Uint8Array.from(binary, (c) => c.charCodeAt(0)));
+}
+function encodePlan(plan) {
+  return toBase64Url(serializePlan(plan));
+}
+function decodePlan(encoded) {
+  try {
+    return parsePlanText(fromBase64Url(encoded));
+  } catch {
+    return { ok: false, error: "That link is damaged \u2014 the plan could not be decoded." };
+  }
+}
+function planEditorUrl(baseUrl, plan) {
+  const url = `${baseUrl.replace(/\/$/, "")}/edit#plan=${encodePlan(plan)}`;
+  return url.length <= MAX_HANDOFF_URL_CHARS ? url : null;
+}
+
 // src/lib/prompts.ts
 function buildSystemPrompt(maxSteps) {
   let scope;
@@ -786,7 +910,8 @@ EXAMPLES:
 \u2022 File upload: "target": "input[type=\\"file\\"]"
 \u2022 Slider: "target": "input[type=\\"range\\"]"`;
 }
-function buildUserPrompt(url, title, elements, langName, description, maxSteps) {
+var MIN_USEFUL_SCROLL_PX = 200;
+function buildUserPrompt(url, title, elements, langName, description, maxSteps, scrollable) {
   const lang = langName ? `
 Language: Write ALL captions in ${langName}.` : "";
   const purpose = description ? `
@@ -824,8 +949,13 @@ ${selectables.map((e) => `\u2022 "${e.text}" \u2192 ${e.selector}`).join("\n")}`
 ${checkables.map((e) => `\u2022 "${e.text}" \u2192 ${e.selector}`).join("\n")}`);
   }
   const elementSummary = elementDict.length > 0 ? elementDict.join("\n\n") : "(no interactive elements found)";
+  const cannotScroll = scrollable !== void 0 && scrollable < MIN_USEFUL_SCROLL_PX;
+  const scrolling = cannotScroll ? `
+
+SCROLLING: this page has only ${scrollable}px of scroll travel at the recording size, so it does not scroll.` : "";
+  const scrollRule = cannotScroll ? "\n\u2022 NEVER use the scroll action: this page does not scroll, so the video would freeze. Use wait and click steps only" : "";
   return `URL: ${url}
-Title: ${title}${purpose}
+Title: ${title}${purpose}${scrolling}
 
 AVAILABLE ELEMENTS (grouped by action):
 ${elementSummary}
@@ -835,7 +965,7 @@ REQUIREMENTS:
 \u2022 Complete ONE user journey: input \u2192 process \u2192 output
 \u2022 For CLICK: use simplified text target like "extract frame" or "download"
 \u2022 For UPLOAD/DRAG/TYPE: use the CSS selector shown above
-\u2022 For buttons that appear after actions: use partial text like "extract" or "download"${lang}
+\u2022 For buttons that appear after actions: use partial text like "extract" or "download"${scrollRule}${lang}
 
 Return JSON:
 {
@@ -861,7 +991,8 @@ TARGET SYNTAX:
 
 // src/lib/SparkStripe-feature-gating.ts
 var APP_ID = process.env.SPARK_APP_ID ?? "quickpeek";
-var BASE = "https://sparkstripe.com";
+var OWNER_SLUG = process.env.SPARK_OWNER_SLUG ?? "spark";
+var BASE = "https://sparkpay.dev";
 var TIERS = {
   price_1TADnPEf9opkuWid9NtqOYON: "pro",
   price_1TADnPEf9opkuWidgbvvX9ma: "pro",
@@ -904,7 +1035,7 @@ async function getStatusCached(email) {
 function getTier(d) {
   if (!d.subscription || !d.registered) return "free";
   if (d.subscription.status === "canceled" || d.subscription.status === "past_due") return "free";
-  return TIERS[d.subscription.price_id] ?? "free";
+  return TIERS[d.subscription.price_id] ?? "pro";
 }
 var isPaid = (d) => getTier(d) !== "free";
 var hasAccess = (d, min) => (RANK[getTier(d)] ?? 0) >= (RANK[min] ?? 0);
@@ -926,7 +1057,7 @@ async function isVerified(email) {
   }
 }
 function pricingUrl(opts) {
-  const u = new URL(`${BASE}/pricing/${APP_ID}`);
+  const u = new URL(`${BASE}/${OWNER_SLUG}/${APP_ID}`);
   if (opts?.email) u.searchParams.set("email", opts.email);
   if (opts?.returnUrl) u.searchParams.set("return_url", opts.returnUrl);
   return u.toString();
@@ -942,12 +1073,15 @@ export {
   INTERACTIVE_SELECTORS,
   INVALID_TARGETS,
   WIDE_VOICES as LANGUAGE_VOICES,
+  MAX_HANDOFF_URL_CHARS,
   REFINE_PLAN_SYSTEM_PROMPT,
   buildSystemPrompt,
   buildUserPrompt,
   callAI,
   collectPreservedValues,
   crawlPage,
+  decodePlan,
+  encodePlan,
   filterValidSteps,
   getErrorMessage,
   getLanguageName,
@@ -967,9 +1101,12 @@ export {
   normalizeUrl,
   parseAIPlanResponse,
   parsePartial,
+  parsePlanText,
+  planEditorUrl,
   pricingUrl,
   restorePreservedValues,
   rgbaToHex,
+  serializePlan,
   shouldSkipLink,
   showPaywall,
   toTitleCase,

package/mcp.mjs

@@ -17,7 +17,7 @@ import { readFileSync } from 'node:fs';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { TOOL_HANDLERS, TOOLS } from './dist/mcp-tools.mjs';
+import { setCanElicit, setElicit, TOOL_HANDLERS, TOOLS } from './dist/mcp-tools.mjs';
 
 const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
 
@@ -67,6 +67,33 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
   const transport = new StdioServerTransport(process.stdin, protocolStdout);
   await server.connect(transport);
+
+  // Elicitation is optional in MCP. The capability is checked per call, not
+  // here: the client only declares it in `initialize`, which arrives after
+  // connect() resolves. null means "cannot prompt" and start_auth then falls
+  // back to a follow-up finish_auth call.
+  setElicit(async (message) => {
+    if (!server.getClientCapabilities()?.elicitation) return null;
+    const result = await server.elicitInput({
+      message,
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          signedIn: {
+            type: 'boolean',
+            title: 'Signed in?',
+            description: 'Confirm once you have finished signing in, so the session can be saved.',
+          },
+        },
+        required: ['signedIn'],
+      },
+    });
+    return result.action === 'accept' && result.content?.signedIn === true;
+  });
+
+  // Read per call for the same reason as above: `initialize` has not arrived
+  // yet. Lets tools skip opening a sign-in window no prompt could ever confirm.
+  setCanElicit(() => !!server.getClientCapabilities()?.elicitation);
 }
 
 main().catch((e) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spark-apps/quickpeek",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Auto-generate demo videos for your web app with AI",
   "main": "dist/qp.js",
   "bin": {