@spark-apps/quickpeek 1.2.0 → 1.2.1

package/dist/{scraping-BK8pIJhm.d.mts → scraping-CHN4ClyT.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 {
@@ -187,9 +187,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 +233,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[]>;

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-CHN4ClyT.mjs';
+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, 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-CHN4ClyT.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();
     }
@@ -93,7 +93,9 @@ 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 || "";
+}
 var cachedDirectToken = null;
 async function getOrRefreshDirectToken() {
   const now = Date.now();
@@ -103,7 +105,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}`);
@@ -189,7 +191,7 @@ async function executeChat(chatUrl, bearerToken, systemPrompt, userPrompt, tier)
   return lastRateLimitError || { success: false, error: "Request failed after retries" };
 }
 async function callAI(systemPrompt, userPrompt, tier = "free") {
-  if (!API_KEY) {
+  if (!apiKey()) {
     return {
       success: false,
       error: "AI service is not configured. Please report this issue.",
@@ -351,20 +353,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 = [];
@@ -494,12 +505,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 +744,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 +871,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 +910,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 +926,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:
 {
@@ -942,12 +1033,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 +1061,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 { 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,29 @@ 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;
+  });
 }
 
 main().catch((e) => {

package/package.json

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