@spark-apps/quickpeek 1.2.3 → 1.2.5

package/dist/web.mjs

@@ -74,8 +74,27 @@ function parsePartial(partial) {
 function getErrorMessage(err) {
   return err instanceof Error ? err.message : String(err);
 }
+var STOCK_PHRASES = [
+  [/\bfree to start\b/gi, "free to try"],
+  [/\bget started today\b/gi, "start now"],
+  [/\bsay goodbye to\b/gi, "no more"],
+  [/\bsupercharge\b/gi, "speed up"],
+  [/\beffortlessly\b/gi, "easily"],
+  [/\bseamlessly\b/gi, ""]
+];
+function deStock(text) {
+  let out = text;
+  for (const [re, replacement] of STOCK_PHRASES) out = out.replace(re, replacement);
+  return out.replace(/\s{2,}/g, " ").replace(/\s+([,.!?])/g, "$1").trim();
+}
+function stripLongDashes(text) {
+  return text.replace(/(\d)\s*[\u2013\u2014]\s*(\d)/g, "$1-$2").replace(/\s*[\u2013\u2014]\s*/g, ", ").replace(/,\s*,/g, ",").replace(/\s+([,.!?])/g, "$1").replace(/\s{2,}/g, " ").trim();
+}
 function toTitleCase(text) {
-  return text.replace(/\w+(?:'\w+)*/g, (word, index) => {
+  return deStock(stripLongDashes(text)).replace(/\w+(?:'\w+)*/g, (word, index) => {
+    if (/[A-Z]/.test(word.slice(1))) {
+      return word;
+    }
     if (index === 0) {
       return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
     }
@@ -85,8 +104,19 @@ function toTitleCase(text) {
     return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
   });
 }
+async function runPooled(count, size, task) {
+  let cursor = 0;
+  const worker = async () => {
+    while (cursor < count) {
+      const index = cursor++;
+      await task(index);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(size, count)) }, worker));
+}
 
 // src/lib/api-client.ts
+var PLAN_MAX_TOKENS = 1500;
 var SERVER_BACKOFF_MS = [2e3, 4e3];
 var SPARK_AI_BASE = "https://sparkbrain.app";
 var SPARK_AI_CHAT = `${SPARK_AI_BASE}/api/chat`;
@@ -139,7 +169,7 @@ async function getOrRefreshDirectToken() {
   }
 }
 async function executeChat(chatUrl, bearerToken, systemPrompt, userPrompt, tier, opts = {}) {
-  const { onRetry, backoffMs = SERVER_BACKOFF_MS } = opts;
+  const { onRetry, backoffMs = SERVER_BACKOFF_MS, maxTokens } = opts;
   let lastRetriableError = null;
   const host = hostOf(chatUrl);
   for (let attempt = 1; attempt <= 3; attempt++) {
@@ -154,7 +184,11 @@ async function executeChat(chatUrl, bearerToken, systemPrompt, userPrompt, tier,
           messages: [
             { role: "system", content: systemPrompt },
             { role: "user", content: userPrompt }
-          ]
+          ],
+          // Explicit numeric test, not truthiness: a 0 or negative budget is a
+          // caller bug, and silently falling back to the tiny backend default
+          // reproduces exactly the failure this option exists to prevent.
+          ...typeof maxTokens === "number" && maxTokens > 0 ? { max_tokens: Math.floor(maxTokens) } : {}
         })
       });
       const bodyText = await response.text().catch(() => "");
@@ -367,6 +401,75 @@ function shouldSkipLink(text, href, currentPath) {
 }
 
 // src/lib/crawl.ts
+var SETTLE_POLL_MS = 400;
+var SETTLE_STABLE_POLLS = 2;
+var SETTLE_CAP_MS = 2e4;
+async function waitForDomStable(page, cap = SETTLE_CAP_MS) {
+  const deadline = Date.now() + cap;
+  let previous = -1;
+  let unchanged = 0;
+  while (Date.now() < deadline) {
+    const count = await page.evaluate(() => document.getElementsByTagName("*").length).catch(() => -1);
+    if (count < 0) return;
+    if (count === previous) {
+      if (++unchanged >= SETTLE_STABLE_POLLS) return;
+    } else {
+      unchanged = 0;
+      previous = count;
+    }
+    await page.waitForTimeout(SETTLE_POLL_MS);
+  }
+}
+var PLACEHOLDER_POLL_MS = 250;
+var PLACEHOLDER_CAP_MS = 8e3;
+var PLACEHOLDER_STATIC_POLLS = 4;
+var PLACEHOLDER_CLEAR_POLLS = 3;
+var PLACEHOLDER_SELECTOR = [
+  '[aria-busy="true"]',
+  '[role="progressbar"]',
+  '[data-loading="true"]',
+  '[class*="skeleton" i]',
+  '[class*="animate-pulse" i]',
+  '[class*="spinner" i]'
+].join(",");
+async function waitForPlaceholdersGone(page, cap = PLACEHOLDER_CAP_MS) {
+  const deadline = Date.now() + cap;
+  let previous = -1;
+  let unchanged = 0;
+  let clear = 0;
+  while (Date.now() < deadline) {
+    const count = await page.evaluate((selector) => {
+      let visible = 0;
+      for (const el of Array.from(document.querySelectorAll(selector))) {
+        const rect = el.getBoundingClientRect();
+        if (rect.width > 0 && rect.height > 0) visible++;
+      }
+      return visible;
+    }, PLACEHOLDER_SELECTOR).catch(() => 0);
+    if (count === 0) {
+      if (++clear >= PLACEHOLDER_CLEAR_POLLS) return;
+      await page.waitForTimeout(PLACEHOLDER_POLL_MS);
+      continue;
+    }
+    clear = 0;
+    if (count === previous) {
+      if (++unchanged >= PLACEHOLDER_STATIC_POLLS) return;
+    } else {
+      unchanged = 0;
+      previous = count;
+    }
+    await page.waitForTimeout(PLACEHOLDER_POLL_MS);
+  }
+}
+async function gotoSettled(page, url, timeout = 3e4) {
+  await page.goto(url, { waitUntil: "domcontentloaded", timeout });
+  await page.waitForLoadState("networkidle", { timeout: 2500 }).catch(() => {
+  });
+  await waitForDomStable(page).catch(() => {
+  });
+  await waitForPlaceholdersGone(page).catch(() => {
+  });
+}
 function idSelector(id) {
   return /^[A-Za-z_-][\w-]*$/.test(id) ? `#${id}` : `[id="${id.replace(/(["\\])/g, "\\$1")}"]`;
 }
@@ -387,6 +490,40 @@ function getActionForType(type) {
       return "type";
   }
 }
+async function sitemapRoutes(pageUrl) {
+  let origin;
+  try {
+    origin = new URL(pageUrl).origin;
+  } catch {
+    return [];
+  }
+  try {
+    const res = await fetch(`${origin}/sitemap.xml`, { signal: AbortSignal.timeout(4e3) });
+    if (!res.ok) return [];
+    const xml = await res.text();
+    const seen = /* @__PURE__ */ new Set();
+    const routes = [];
+    for (const m of xml.matchAll(/<loc>([^<]+)<\/loc>/g)) {
+      const raw = (m[1] ?? "").trim();
+      let u;
+      try {
+        u = new URL(raw);
+      } catch {
+        continue;
+      }
+      if (u.origin !== origin) continue;
+      if (/\.(txt|xml|json|png|jpg|svg|ico|pdf)$/i.test(u.pathname)) continue;
+      const path = u.pathname.replace(/\/+$/, "");
+      if (!path || seen.has(u.href)) continue;
+      seen.add(u.href);
+      routes.push({ text: path.slice(1), href: u.href });
+      if (routes.length >= 20) break;
+    }
+    return routes;
+  } catch {
+    return [];
+  }
+}
 var noopTask = () => ({ succeed: () => {
 } });
 var CRAWL_CACHE_TTL_MS = 5 * 60 * 1e3;
@@ -401,155 +538,180 @@ async function crawlPage(url, task = noopTask, storageStatePath, viewport) {
   }
   const browserTask = task("Launching browser");
   const browser = await chromium.launch({ headless: true });
-  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 = [];
+  try {
+    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 gotoSettled(page, url, 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 = [];
 
-      // Helper to get parent context
-      const getCtx = (el) => {
-        let p = el.parentElement;
-        while (p && p !== document.body) {
-          if (p.id) return '#' + p.id;
-          const cls = Array.from(p.classList).find(c =>
-            /toolbar|header|footer|sidebar|panel|modal|dialog|nav|menu|controls|actions/i.test(c)
-          );
-          if (cls) return '.' + cls;
-          if (['header', 'footer', 'nav', 'main', 'aside', 'form'].includes(p.tagName.toLowerCase())) {
-            return p.tagName.toLowerCase();
+        // Helper to get parent context
+        const getCtx = (el) => {
+          let p = el.parentElement;
+          while (p && p !== document.body) {
+            if (p.id) return '#' + p.id;
+            const cls = Array.from(p.classList).find(c =>
+              /toolbar|header|footer|sidebar|panel|modal|dialog|nav|menu|controls|actions/i.test(c)
+            );
+            if (cls) return '.' + cls;
+            if (['header', 'footer', 'nav', 'main', 'aside', 'form'].includes(p.tagName.toLowerCase())) {
+              return p.tagName.toLowerCase();
+            }
+            p = p.parentElement;
           }
-          p = p.parentElement;
-        }
-        return '';
-      };
+          return '';
+        };
 
-      // Buttons (use textContent to catch hidden elements too)
-      document.querySelectorAll('button, [role="button"]').forEach(el => {
-        const text = (el.textContent || el.innerText || '').trim().replace(/\\s+/g, ' ').slice(0, 40);
-        const testId = el.getAttribute('data-testid');
-        const ariaLabel = el.getAttribute('aria-label');
-        if (!text && !testId && !ariaLabel) return;
-        items.push({ type: 'button', text: text || ariaLabel || testId, testId, ctx: getCtx(el) });
-      });
+        // Buttons (use textContent to catch hidden elements too)
+        document.querySelectorAll('button, [role="button"]').forEach(el => {
+          const text = (el.textContent || el.innerText || '').trim().replace(/\\s+/g, ' ').slice(0, 40);
+          const testId = el.getAttribute('data-testid');
+          const ariaLabel = el.getAttribute('aria-label');
+          if (!text && !testId && !ariaLabel) return;
+          items.push({ type: 'button', text: text || ariaLabel || testId, testId, ctx: getCtx(el) });
+        });
 
-      // Inputs (including file inputs, range sliders, checkboxes, selects)
-      document.querySelectorAll('input, textarea, select').forEach(el => {
-        if (el.type === 'hidden') return;
-        const testId = el.getAttribute('data-testid');
-        const inputType = el.type || 'text';
+        // Inputs (including file inputs, range sliders, checkboxes, selects)
+        document.querySelectorAll('input, textarea, select').forEach(el => {
+          if (el.type === 'hidden') return;
+          const testId = el.getAttribute('data-testid');
+          const inputType = el.type || 'text';
 
-        // Get label text for any input type
-        let labelText = '';
-        if (el.labels?.[0]) {
-          labelText = el.labels[0].textContent?.trim() || '';
-        } else if (el.id) {
-          const label = document.querySelector('label[for="' + el.id + '"]');
-          if (label) labelText = label.textContent?.trim() || '';
-        }
+          // Get label text for any input type
+          let labelText = '';
+          if (el.labels?.[0]) {
+            labelText = el.labels[0].textContent?.trim() || '';
+          } else if (el.id) {
+            const label = document.querySelector('label[for="' + el.id + '"]');
+            if (label) labelText = label.textContent?.trim() || '';
+          }
 
-        const text = labelText || el.placeholder || el.name || el.id || '';
+          const text = labelText || el.placeholder || el.name || el.id || '';
 
-        // Include file, range, and checkbox inputs even without text
-        const alwaysInclude = ['file', 'range', 'checkbox'].includes(inputType);
-        if (!text && !testId && !alwaysInclude) return;
+          // Include file, range, and checkbox inputs even without text
+          const alwaysInclude = ['file', 'range', 'checkbox'].includes(inputType);
+          if (!text && !testId && !alwaysInclude) return;
 
-        items.push({
-          type: inputType,
-          text: text || (inputType === 'file' ? 'file upload' : inputType === 'range' ? 'slider' : inputType === 'checkbox' ? 'checkbox' : testId),
-          testId,
-          id: el.id,
-          name: el.name,
-          placeholder: el.placeholder,
-          isFile: inputType === 'file'
+          items.push({
+            type: inputType,
+            text: text || (inputType === 'file' ? 'file upload' : inputType === 'range' ? 'slider' : inputType === 'checkbox' ? 'checkbox' : testId),
+            testId,
+            id: el.id,
+            name: el.name,
+            placeholder: el.placeholder,
+            isFile: inputType === 'file'
+          });
         });
-      });
 
-      // Links (use textContent to catch hidden elements too)
-      document.querySelectorAll('a[href]').forEach(el => {
-        const text = (el.textContent || el.innerText || '').trim().replace(/\\s+/g, ' ').slice(0, 40);
-        if (text && text.length >= 2) items.push({ type: 'link', text });
-      });
+        // Links (use textContent to catch hidden elements too)
+        document.querySelectorAll('a[href]').forEach(el => {
+          const text = (el.textContent || el.innerText || '').trim().replace(/\\s+/g, ' ').slice(0, 40);
+          if (!text || text.length < 2) return;
+          // Keep the destination, not just the label. Without it the planner
+          // can name a page in a caption but has no way to go there, so every
+          // line gets forced onto whatever is already on screen.
+          let href = '';
+          try {
+            const u = new URL(el.getAttribute('href') || '', location.href);
+            if (u.origin === location.origin) href = u.href;
+          } catch { /* a javascript: or mailto: href is not somewhere to go */ }
+          items.push({ type: 'link', text, href });
+        });
 
-      return items.slice(0, 40);
-    })()
-  `);
-  const filteredElements = rawElements.filter((el) => {
-    if (!el.text) return true;
-    const text = el.text.toLowerCase().trim();
-    return !EXCLUDED_LINK_PATTERNS.some((pattern) => text.includes(pattern));
-  });
-  const btnTexts = {};
-  for (const el of filteredElements) {
-    if (el.type === "button" && el.text) {
-      btnTexts[el.text] = (btnTexts[el.text] || 0) + 1;
+        return items.slice(0, 40);
+      })()
+    `);
+    const filteredElements = rawElements.filter((el) => {
+      if (!el.text) return true;
+      const text = el.text.toLowerCase().trim();
+      return !EXCLUDED_LINK_PATTERNS.some((pattern) => text.includes(pattern));
+    });
+    const btnTexts = {};
+    for (const el of filteredElements) {
+      if (el.type === "button" && el.text) {
+        btnTexts[el.text] = (btnTexts[el.text] || 0) + 1;
+      }
     }
-  }
-  const elements = filteredElements.map((el) => {
-    let selector;
-    if (el.testId) {
-      selector = `[data-testid="${el.testId}"]`;
-    } else if (el.isFile || el.type === "file") {
-      selector = 'input[type="file"]';
-    } else if (el.type === "range") {
-      selector = el.id ? idSelector(el.id) : 'input[type="range"]';
-    } else if (el.type === "checkbox") {
-      selector = el.id ? idSelector(el.id) : 'input[type="checkbox"]';
-    } else if (el.type === "button") {
-      if (btnTexts[el.text] === 1) {
+    const elements = filteredElements.map((el) => {
+      let selector;
+      if (el.testId) {
+        selector = `[data-testid="${el.testId}"]`;
+      } else if (el.isFile || el.type === "file") {
+        selector = 'input[type="file"]';
+      } else if (el.type === "range") {
+        selector = el.id ? idSelector(el.id) : 'input[type="range"]';
+      } else if (el.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}"`;
+        } else {
+          selector = el.ctx ? `${el.ctx} >> text="${el.text}"` : `button:has-text("${el.text}")`;
+        }
+      } else if (el.type === "link") {
         selector = `text="${el.text}"`;
+      } else if (el.id) {
+        selector = idSelector(el.id);
+      } else if (el.name) {
+        selector = `[name="${el.name}"]`;
+      } else if (el.placeholder) {
+        selector = `[placeholder="${el.placeholder}"]`;
       } else {
-        selector = el.ctx ? `${el.ctx} >> text="${el.text}"` : `button:has-text("${el.text}")`;
+        selector = `text="${el.text}"`;
       }
-    } else if (el.type === "link") {
-      selector = `text="${el.text}"`;
-    } else if (el.id) {
-      selector = idSelector(el.id);
-    } else if (el.name) {
-      selector = `[name="${el.name}"]`;
-    } else if (el.placeholder) {
-      selector = `[placeholder="${el.placeholder}"]`;
-    } else {
-      selector = `text="${el.text}"`;
+      let normalizedType;
+      if (el.isFile || el.type === "file") {
+        normalizedType = "file";
+      } else if (el.type === "range") {
+        normalizedType = "range";
+      } else if (el.type === "checkbox") {
+        normalizedType = "checkbox";
+      } else if (el.type === "select" || el.type === "select-one" || el.type === "select-multiple") {
+        normalizedType = "select";
+      } else if (el.type === "button" || el.type === "link") {
+        normalizedType = el.type;
+      } else {
+        normalizedType = "input";
+      }
+      const action = getActionForType(normalizedType);
+      const target = normalizedType === "file" ? selector : (el.text || "").toLowerCase();
+      return { type: normalizedType, text: el.text, selector, action, target, href: el.href };
+    });
+    await browser.close();
+    for (const route of await sitemapRoutes(url)) {
+      if (elements.some((e) => e.href === route.href)) continue;
+      elements.push({
+        type: "link",
+        text: route.text,
+        selector: "",
+        action: "click",
+        target: route.text,
+        href: route.href
+      });
     }
-    let normalizedType;
-    if (el.isFile || el.type === "file") {
-      normalizedType = "file";
-    } else if (el.type === "range") {
-      normalizedType = "range";
-    } else if (el.type === "checkbox") {
-      normalizedType = "checkbox";
-    } else if (el.type === "select" || el.type === "select-one" || el.type === "select-multiple") {
-      normalizedType = "select";
-    } else if (el.type === "button" || el.type === "link") {
-      normalizedType = el.type;
-    } else {
-      normalizedType = "input";
+    crawlTask.succeed(`Found ${elements.length} interactive 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);
     }
-    const action = getActionForType(normalizedType);
-    const target = normalizedType === "file" ? selector : (el.text || "").toLowerCase();
-    return { type: normalizedType, text: el.text, selector, action, target };
-  });
-  await browser.close();
-  crawlTask.succeed(`Found ${elements.length} interactive 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, scrollable };
+  } finally {
+    await browser.close().catch(() => {
+    });
   }
-  return { title, elements, scrollable };
 }
 
 // src/lib/plan-validation.ts
@@ -747,8 +909,9 @@ function collectPreservedValues(steps) {
         mediaFile: step.mediaFile,
         mediaType: step.mediaType
       });
-    } else if (step.action === "media") {
+    } else if (step.action === "media" || step.action === "image") {
       mediaSteps.push({
+        value: step.value,
         mediaFile: step.mediaFile,
         mediaType: step.mediaType,
         target: step.target
@@ -769,14 +932,15 @@ function restorePreservedValues(step, preserved, indices) {
     if (original.mediaType !== void 0) step.mediaType = original.mediaType;
     uploadIdx++;
   }
-  if (step.action === "media" && mediaIdx < preserved.mediaSteps.length) {
+  if ((step.action === "media" || step.action === "image") && mediaIdx < preserved.mediaSteps.length) {
     const original = preserved.mediaSteps[mediaIdx];
+    if (original.value !== void 0) step.value = original.value;
     if (original.mediaFile !== void 0) step.mediaFile = original.mediaFile;
     if (original.mediaType !== void 0) step.mediaType = original.mediaType;
     if (!step.target && original.target) step.target = original.target;
     mediaIdx++;
   }
-  if (step.action !== "upload" && step.action !== "media" && step.target) {
+  if (step.action !== "upload" && step.action !== "media" && step.action !== "image" && step.target) {
     const original = preserved.otherValues.get(`${step.action}:${step.target}`);
     if (original) step.value = original;
   }
@@ -858,9 +1022,13 @@ function planEditorUrl(baseUrl, plan) {
 }
 
 // src/lib/prompts.ts
-function buildSystemPrompt(maxSteps) {
+function buildSystemPrompt(maxSteps, profile) {
   let scope;
-  if (maxSteps <= 5) {
+  if (profile === "wide") {
+    scope = `SCOPE: Educational tutorial (${maxSteps} steps max) - comprehensive, structured coverage of every major feature area, in a logical teaching order`;
+  } else if (profile === "short") {
+    scope = `SCOPE: Quick-paced short (${maxSteps} steps max) - cover every interesting detail with fast cuts and terse captions; running long is fine, the video is compressed afterwards`;
+  } else if (maxSteps <= 5) {
     scope = `SCOPE: Minimal demo (${maxSteps} steps max) - ONE complete user journey only`;
   } else if (maxSteps <= 8) {
     scope = `SCOPE: Standard demo (${maxSteps} steps max) - One journey with 1-2 options`;
@@ -872,9 +1040,47 @@ function buildSystemPrompt(maxSteps) {
 ${scope}
 
 CORE FLOW (always follow this structure):
-1. wait - Intro (what does this app do?)
+1. wait - the hook, over the app's own card (see OPENING AND CLOSING)
 2. Actions - Complete ONE user journey (upload\u2192process\u2192result)
-3. wait - Outro (what was accomplished?)
+3. Stop. The closing card is appended for you - do not write one
+
+NARRATION STYLE:
+\u2022 Professional and direct, like a good tutorial - never condescending, never explaining as if to a child
+\u2022 NEVER mention step numbers or sequencing ("step one", "first step", "in this step") - just say what is happening
+\u2022 NEVER build the demo out of marketing surfaces. The landing page and the PRICING page are not the product: a viewer wants to see the thing working, not read plans and prices. If the app is behind a sign-in, demo the signed-in app; if that is impossible, demo its functional public pages (tools, docs, editors), not its sales pages
+\u2022 A marketing/landing page earns ONE brief opening caption of about a SECOND - a title card, nothing more. Never scroll it, never hover or highlight anything on it, never describe its sections. Optionally return to it for the closing call to action. The demo lives in the app itself, behind the login when a session exists. Never return to the landing page mid-demo to describe a feature the app can show you doing
+\u2022 NARRATE ONLY WHAT IS ON SCREEN: every caption must describe what the viewer can see at that moment. To talk about a specific component, make it the step's target (hover it, click it, or scroll with that target) so the recorder brings it into frame first
+\u2022 A blind scroll (no target) lands wherever it lands - use it only for "there is more below", never to reveal something the caption names
+\u2022 Never combine scrolling with pointing: a step either moves the page or holds still on a component, so the highlight is never dragged across the screen mid-scroll
+\u2022 A step that starts something asynchronous (processing, generating, analyzing) must WAIT for the result on screen before moving on: give the wait step a "duration" in seconds long enough to show the outcome
+\u2022 Caption length drives step length - keep captions tight so the video moves
+
+OPENING AND CLOSING (a fixed template - both cards are built for you):
+\u2022 Step 1 is ALWAYS a bare { "action": "wait" } with no target. Its caption is the HOOK, and the recorder puts the app's own OG card behind it
+\u2022 The hook names the VIEWER'S problem in the viewer's words - the cost of not having this app, in one line someone would recognise as their own situation. It is the reason to keep watching
+\u2022 NEVER open the hook with the product: no "This is X", no "Meet X", no "X helps you..." and no feature. The problem comes first
+\u2022 Then, in that SAME caption, say the app's address once - "<problem>. <domain> fixes that." A viewer who leaves halfway has to have heard where to go, and the closing card is too late for them. The opening card is both spoken AND captioned, so write the hook to read as well as it sounds: short words, no spelled-out punctuation, and the domain written the way it is typed
+\u2022 The closing card is appended for you: the app's name, tagline, domain and any live offer, narrated. Never write a sign-off step and never end back on the landing page. Apart from the hook, keep the domain and any discount code out of captions - the card carries both, and repeating them mid-demo is the most common way these scripts read as padding
+
+HOW IT SHOULD SOUND (this is read aloud, not printed on a slide):
+\u2022 Write the way a person talks about something they actually like. Warm, quick, a bit of a grin. Never the voice of a landing page
+\u2022 BANNED, because they are what marketing copy sounds like when nobody meant it: "free to start", "get started today", "unlock", "empower", "seamlessly", "effortlessly", "revolutionise", "supercharge", "take your X to the next level", "say goodbye to". If a line could sit on any product's homepage unchanged, it is not about this product
+\u2022 The free tier is "try it free", or just "free". Never "free to start", which reads as a pricing table talking
+\u2022 Short sentences beat long ones out loud. A comma is a breath; a full stop is a beat. Read it back before shipping it
+\u2022 Say the thing, do not build up to it. No "in this video we will", no "let's take a look at"
+
+WHAT TO COVER (a tour of tabs is a menu, not a demo):
+\u2022 Lead with the outcome the app produces, not the screens it has
+\u2022 Say where that outcome ENDS UP when the app puts it somewhere - search results, AI assistant answers, directories, an app store
+\u2022 Name any integration that removes work rather than adding a screen - an MCP server, a browser extension that fills the forms, an API, a CLI. An app that can be driven from an assistant is a headline feature, not a footnote
+\u2022 Do NOT write a pricing step. When the app has a free tier the closing card says so for you, narrated, at the end where it belongs. Never navigate to the pricing page for it
+\u2022 Cover what surrounds the product as well as the product: a community, a network its users list each other on, a support channel, anything published on the user's behalf. These are reasons to sign up and they are never on screen by themselves
+\u2022 Say what a feature DOES, never what it is implemented as. Filenames, formats and protocols are not benefits: "so AI assistants can read your product" lands, "it writes llms.txt and robots.txt" is a changelog line read aloud. Same for sitemap.xml, JSON-LD, schema markup, API endpoints and anything ending in .txt, .xml or .json. If a viewer would have to already know what it is, it is not a selling point
+\u2022 Prefer one feature shown working over three named in passing
+\u2022 When a step types into a URL or domain field, type a REAL domain, never example.com or example.org. A demo that audits "example.com" on camera shows the tool working on nothing. Use a real site the viewer might recognise, or the demo subject's own domain if nothing better is on the page
+\u2022 A plan that is mostly bare wait steps is a failed plan. One real run came back 22 waits out of 26: a slideshow of one static screen, narrating pages it never visited. If a caption names a page, NAVIGATE to it; if it names a control, CLICK it. Use wait only for the opening and closing cards
+\u2022 NEVER narrate a screen you are not on. If a line describes a page the demo has not reached, navigate to it first. A caption saying "start with a free roast" over the dashboard is worse than cutting the line: it makes the whole video look faked
+\u2022 Cover everything worth covering and let it run long. Length is fixed afterwards by playing the demo faster, never by dropping a feature - a plan trimmed to hit a target is the one mistake the compressor cannot undo
 
 TARGET SYNTAX (simplified):
 \u2022 Buttons/Links: Use plain text like "extract frame", "download" (case insensitive, partial match OK)
@@ -897,9 +1103,12 @@ FORBIDDEN:
 
 ACTION FORMATS (STRICT - follow exactly):
 \u2022 click: { "action": "click", "target": "extract frame" } - use simplified button text
+\u2022 hover: { "action": "hover", "target": "pricing card" } - point the cursor at a feature while the caption explains it, without clicking
 \u2022 type: { "action": "type", "target": "input[name=\\"field\\"]", "value": "text to type" }
 \u2022 upload: { "action": "upload", "target": "input[type=\\"file\\"]", "value": "[file]" }
+\u2022 navigate: { "action": "navigate", "target": "https://example.com/roast" } - GO TO ANOTHER PAGE. Use it whenever the caption describes something that is not on the current screen. Any path on the SAME ORIGIN as the demo URL is allowed, not only the NAVIGATE targets listed below: an app's own routes are frequently reached by client-side buttons rather than links, so the list is a hint, not the limit. Never navigate off-origin.
 \u2022 wait: { "action": "wait" } - for intro/outro captions
+\u2022 scroll to a component: { "action": "scroll", "target": "seo files", "value": "down" } - brings that element into frame; PREFER this over a blind scroll whenever the caption names something
 \u2022 scroll: { "action": "scroll", "value": "-80" } - negative=zoom out, positive=zoom in
 \u2022 drag: { "action": "drag", "target": "input[type=\\"range\\"]", "value": "50" }
 \u2022 select: { "action": "select", "target": "select[name=\\"..\\"]", "value": "option" }
@@ -924,6 +1133,17 @@ Purpose: ${description}` : "";
   const selectables = elements.filter((e) => e.action === "select");
   const checkables = elements.filter((e) => e.action === "check");
   const elementDict = [];
+  const navigables = elements.filter((e) => e.href);
+  const seenHref = /* @__PURE__ */ new Set();
+  const linkTargets = navigables.filter((e) => {
+    if (!e.href || seenHref.has(e.href)) return false;
+    seenHref.add(e.href);
+    return true;
+  });
+  if (linkTargets.length > 0) {
+    elementDict.push(`NAVIGATE targets (links found on the page; same-origin paths not listed here are also allowed):
+${linkTargets.map((e) => `\u2022 "${e.text}" -> ${e.href}`).join("\n")}`);
+  }
   if (clickables.length > 0) {
     elementDict.push(`CLICK targets (use simplified text):
 ${clickables.map((e) => `\u2022 "${e.target || e.text.toLowerCase()}"`).join("\n")}`);
@@ -994,26 +1214,23 @@ var APP_ID = process.env.SPARK_APP_ID ?? "quickpeek";
 var OWNER_SLUG = process.env.SPARK_OWNER_SLUG ?? "spark";
 var BASE = "https://sparkpay.dev";
 var TIERS = {
-  price_1TADnPEf9opkuWid9NtqOYON: "pro",
-  price_1TADnPEf9opkuWidgbvvX9ma: "pro",
+  // Essentials
+  price_1TCREmEf9opkuWidvhuqzqDM: "pro",
+  // live monthly
+  price_1TCREmEf9opkuWidacf1tiC7: "pro",
+  // live yearly
   price_1TADm7Ef9opkuWid3I9tquIB: "pro",
+  // test monthly
   price_1TADm8Ef9opkuWid1RSA2wCa: "pro",
-  price_1TCREmEf9opkuWidvhuqzqDM: "pro",
-  price_1TCREmEf9opkuWidacf1tiC7: "pro"
-};
-var RANK = {
-  free: 0,
-  pro: 1
-};
-var FEATURES = {
-  free: [],
-  pro: [
-    "Everything in Free",
-    "No watermark",
-    "Full video composition (voiceover + captions + music + transitions)",
-    "Unlimited videos",
-    "Priority support"
-  ]
+  // test yearly
+  // Elite. These were missing entirely, so an Elite subscriber fell through
+  // the `?? 'pro'` fallback below and got Essentials limits for $29.
+  price_1TrHz8Ef9opkuWid6lh2opD8: "elite",
+  // live monthly
+  price_1TrHz9Ef9opkuWid1qS26iMu: "elite",
+  // live yearly
+  price_1TGPCREf9opkuWidR0iJeJNe: "elite"
+  // test monthly
 };
 async function _fetch(email, init) {
   const r = await fetch(
@@ -1038,7 +1255,6 @@ function getTier(d) {
   return TIERS[d.subscription.price_id] ?? "pro";
 }
 var isPaid = (d) => getTier(d) !== "free";
-var hasAccess = (d, min) => (RANK[getTier(d)] ?? 0) >= (RANK[min] ?? 0);
 var hasTrialRemaining = (d) => isPaid(d) || !!d.trial && !d.trial.is_expired && d.trial.uses_remaining > 0;
 var showPaywall = (d) => !isPaid(d) && !hasTrialRemaining(d);
 var isCanceling = (d) => !!d.subscription && d.subscription.cancel_at_period_end && d.subscription.status !== "canceled";
@@ -1064,22 +1280,43 @@ function pricingUrl(opts) {
 }
 
 // src/lib/voices.ts
-import { WIDE_VOICES } from "@spark-apps/video-kit";
+import { MALE_VOICES, MULTILINGUAL_VOICES, resolveVoice, WIDE_VOICES } from "@spark-apps/video-kit";
+import { MALE_VOICES as MALE_VOICES2, MULTILINGUAL_VOICES as MULTILINGUAL_VOICES2, WIDE_VOICES as WIDE_VOICES2 } from "@spark-apps/video-kit";
+var INTERNATIONAL_VOICE = "international";
+function internationalVoiceFor(lang, gender = "female") {
+  if (!hasVoice(lang)) return null;
+  const raw = lang.trim().toLowerCase();
+  const multilingual = MULTILINGUAL_VOICES[raw] ?? MULTILINGUAL_VOICES[raw.slice(0, 2)];
+  if (gender === "male") return voiceFor(lang, gender);
+  return multilingual ?? voiceFor(lang, gender);
+}
+function hasVoice(lang) {
+  const raw = lang.trim().toLowerCase();
+  return Boolean(WIDE_VOICES[raw] ?? WIDE_VOICES[raw.slice(0, 2)]);
+}
+function voiceFor(lang, gender = "female") {
+  if (!hasVoice(lang)) return null;
+  return resolveVoice(lang, { gender, table: WIDE_VOICES, maleTable: MALE_VOICES });
+}
 export {
   ACTIONS_REQUIRING_TARGET,
   EXCLUDED_LINK_PATTERNS,
-  FEATURES,
   FIX_PLAN_SYSTEM_PROMPT,
   INTERACTIVE_SELECTORS,
+  INTERNATIONAL_VOICE,
   INVALID_TARGETS,
-  WIDE_VOICES as LANGUAGE_VOICES,
+  MALE_VOICES2 as MALE_VOICES,
   MAX_HANDOFF_URL_CHARS,
+  MULTILINGUAL_VOICES2 as MULTILINGUAL_VOICES,
+  PLAN_MAX_TOKENS,
   REFINE_PLAN_SYSTEM_PROMPT,
+  WIDE_VOICES2 as WIDE_VOICES,
   buildSystemPrompt,
   buildUserPrompt,
   callAI,
   collectPreservedValues,
   crawlPage,
+  deStock,
   decodePlan,
   encodePlan,
   filterValidSteps,
@@ -1089,9 +1326,10 @@ export {
   getStatusCached,
   getTier,
   getTierByEmail,
-  hasAccess,
   hasTrialRemaining,
+  hasVoice,
   hexToAss as hexToASS,
+  internationalVoiceFor,
   isCanceling,
   isExcludedLink,
   isInvalidTarget,
@@ -1106,10 +1344,13 @@ export {
   pricingUrl,
   restorePreservedValues,
   rgbaToHex,
+  runPooled,
   serializePlan,
   shouldSkipLink,
   showPaywall,
+  stripLongDashes,
   toTitleCase,
   validateStep,
+  voiceFor,
   windowsDrivePathToWsl as windowsPathToWSL
 };