@tandryukha/aidemo 0.15.0 → 0.15.2

package/docs/AUTHORING.md

@@ -70,6 +70,12 @@ scan inside them). Use it instead of reading source or guessing: copy the
 first selector of the element you mean. It writes `logs/inspect-<ts>.json`
 and a screenshot next to it. Elements below the fold are listed too (marked
 `↓` on the CLI); a `scrollTo` on them works as usual.
+The result includes `target.status` (`available` or `blocked`). Common
+security-verification and login pages return `blocked` with a reason: their
+selectors describe the interstitial, not the requested product. Inspection
+still writes its JSON and screenshot for diagnosis; `init --from-url` stops
+instead of drafting scenes from a blocked page. Open the page with an
+authenticated profile or use supported setup seeding, then inspect again.
 
 `inspect` runs the storyboard's **`setup`** block by default — preflight hook,
 `storageState`, cookies — so a gated app scans as the logged-in user instead of
@@ -763,7 +769,7 @@ for UI that re-renders under the cursor) and `anchor?` (land this action on a
   out of the way before a reveal, or point at what the narration names.
 - `{op:"assert", target?, textMatches?, url?, timeoutMs?=5000}` — **prove the
   payoff happened**: polls until `target` is visible (and its text matches
-  `textMatches`, JS regex, no inline flags — use `[Cc]onfirmed`) and/or the
+  `textMatches`, RE2-compatible regex, no inline flags — use `[Cc]onfirmed`) and/or the
   page URL matches `url`; otherwise **fails the take with a named error**
   (`assert failed after 5000ms: text "…" does not match /…/`). Put one after
   the moment the demo exists to show (order confirmed, item added) so a
@@ -1319,6 +1325,15 @@ all) using each scene's measured duration from `voice.json`; only the timing
 measured speech rhythm). `captions` logs a one-line reminder of this whenever
 the resolved language isn't English.
 
+The STT caption step compares each scene's recognized words with its known
+script and warns when at least 20% differ. Review those captions before
+publishing. `aidemo captions <dir> --align-script` uses the script's spelling
+and punctuation while retaining the measured STT word times; words missing
+from the transcript are placed between their nearest timed neighbours. This
+is useful for misheard names and inflected words. If the spoken narration
+actually differs from the script, correct the script or use the original STT
+captions instead.
+
 **Cue segmentation.** Cues are broken at sentence ends first, then at clause
 punctuation, then before a conjunction, and only then on length — so a cue
 stops reading like it was cut mid-thought ("we open the" / "settings panel").

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tandryukha/aidemo",
-  "version": "0.15.0",
+  "version": "0.15.2",
   "license": "MIT",
   "description": "AI Demo Engine — turn a storyboard into a narrated, captioned product demo video",
   "type": "module",
@@ -36,7 +36,8 @@
     "@modelcontextprotocol/sdk": "1.30.0",
     "commander": "^12.1.0",
     "openai": "^4.67.0",
-    "playwright": "^1.48.0",
+    "playwright": "^1.55.1",
+    "re2js": "2.8.6",
     "tsx": "^4.23.1",
     "zod": "^3.23.8",
     "zod-to-json-schema": "3.25.2"

package/src/captions.ts

@@ -96,6 +96,8 @@ const MAX_PROMPT_CHARS = 900;
 export interface CaptionsSttOptions extends SceneProgress {
   /** ISO-639-1/BCP-47 language hint for Whisper, overriding --lang / storyboard.language. */
   language?: string;
+  /** Use storyboard spelling/punctuation while retaining STT word timing. */
+  alignScript?: boolean;
 }
 
 /**
@@ -168,6 +170,7 @@ export async function generateCaptions(
     config,
     prompt,
     language,
+    ...(opts.alignScript ? { alignScript: true } : {}),
   });
   const prior = await readCaptionsManifest(project);
   if (prior && prior.mode === "stt" && prior.inputHash === inputHash) {
@@ -197,13 +200,32 @@ export async function generateCaptions(
   if (words.length === 0) {
     log("no word timestamps returned; captions may be empty");
   }
-  const cues = groupWords(words, sceneEnds, seg);
+  const sceneWords = splitWordsByScene(words, ids, sceneEnds, config.gapMs);
+  let captionWords = words;
+  if (storyboard && sceneEnds.length === storyboard.scenes.length) {
+    const aligned: Word[] = [];
+    let sceneStartMs = 0;
+    for (let i = 0; i < storyboard.scenes.length; i++) {
+      const scene = storyboard.scenes[i];
+      const timed = sceneWords[i]?.words ?? [];
+      const result = alignCaptionWords(scene.narration, timed, sceneEnds[i] - sceneStartMs);
+      if (result.driftPct >= 20) {
+        log(`⚠ caption drift in scene ${scene.id}: ${result.driftPct}% of script words differ from STT; ${opts.alignScript ? "script text aligned to STT timing — review against the audio" : "review captions or use --align-script"}`);
+      }
+      for (const w of result.words) aligned.push({ ...w, start: w.start + sceneStartMs / 1000, end: w.end + sceneStartMs / 1000 });
+      sceneStartMs = sceneEnds[i] + config.gapMs;
+    }
+    if (opts.alignScript) captionWords = aligned;
+  } else if (opts.alignScript) {
+    throw new Error("--align-script requires a storyboard and matching voice scene timings");
+  }
+  const cues = groupWords(captionWords, sceneEnds, seg);
   await writeCaptionFiles(project, cues);
   await writeCaptionsManifest(project, {
     mode: "stt",
     inputHash,
     config,
-    scenes: splitWordsByScene(words, ids, sceneEnds, config.gapMs),
+    scenes: opts.alignScript ? splitWordsByScene(captionWords, ids, sceneEnds, config.gapMs) : sceneWords,
     cues,
   });
   reportDone();
@@ -245,6 +267,62 @@ function splitWordsByScene(
   return out;
 }
 
+/** Align written words to measured STT timestamps. Inserted script words share
+ * the space between their nearest timed neighbours; STT-only words are dropped. */
+export function alignCaptionWords(
+  narration: string,
+  spoken: Word[],
+  durationMs: number
+): { words: Word[]; driftPct: number } {
+  const script = narration.split(/\s+/).filter(Boolean);
+  if (!script.length) return { words: [], driftPct: spoken.length ? 100 : 0 };
+  if (!spoken.length) return { words: deriveSceneWords(narration, durationMs), driftPct: 100 };
+  const norm = (s: string) => s.normalize("NFKC").toLocaleLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
+  const n = script.length, m = spoken.length;
+  const dp = Array.from({ length: n + 1 }, () => new Uint16Array(m + 1));
+  for (let i = 0; i <= n; i++) dp[i][0] = i;
+  for (let j = 0; j <= m; j++) dp[0][j] = j;
+  for (let i = 1; i <= n; i++) for (let j = 1; j <= m; j++) {
+    dp[i][j] = Math.min(
+      dp[i - 1][j - 1] + (norm(script[i - 1]) === norm(spoken[j - 1].word) ? 0 : 1),
+      dp[i - 1][j] + 1,
+      dp[i][j - 1] + 1
+    );
+  }
+  const matched: Array<number | undefined> = Array(n).fill(undefined);
+  let i = n, j = m;
+  while (i && j) {
+    const cost = norm(script[i - 1]) === norm(spoken[j - 1].word) ? 0 : 1;
+    if (dp[i][j] === dp[i - 1][j - 1] + cost) {
+      matched[--i] = --j;
+    } else if (dp[i][j] === dp[i - 1][j] + 1) {
+      i--;
+    } else {
+      j--;
+    }
+  }
+  const duration = Math.max(0, durationMs / 1000);
+  const words: Word[] = script.map((word, k) => {
+    const at = matched[k];
+    return at === undefined ? { word, start: 0, end: 0 } : {
+      word, start: Math.max(0, spoken[at].start), end: Math.min(duration, spoken[at].end),
+    };
+  });
+  for (let k = 0; k < n;) {
+    if (matched[k] !== undefined) { k++; continue; }
+    const first = k;
+    while (k < n && matched[k] === undefined) k++;
+    const start = first ? words[first - 1].end : 0;
+    const end = k < n ? words[k].start : duration;
+    const span = Math.max(0, end - start);
+    for (let t = first; t < k; t++) {
+      words[t].start = start + span * (t - first) / (k - first);
+      words[t].end = start + span * (t - first + 1) / (k - first);
+    }
+  }
+  return { words, driftPct: Math.round(100 * dp[n][m] / Math.max(n, m)) };
+}
+
 /** Scene-relative words for a scene; script-timed fallback when the manifest has none. */
 export async function sceneWordsFor(
   project: Project,

package/src/cli.ts

@@ -664,6 +664,9 @@ program
         process.stdout.write(JSON.stringify(res, null, 2) + "\n");
         return;
       }
+      if (res.target.status === "blocked") {
+        process.stdout.write(`⚠ inspect blocked: ${res.target.reason}\n`);
+      }
       process.stdout.write(`${res.title || "(untitled)"} — ${res.finalUrl}\n`);
       if (res.headings.length) {
         process.stdout.write(
@@ -967,6 +970,7 @@ program
   .option("--param <kv>", PARAM_OPT_DESC, collectKv, [])
   .option("--lang <code>", LANG_OPT_DESC)
   .option("--langs <codes>", LANGS_OPT_DESC)
+  .option("--align-script", "restore storyboard spelling and punctuation using STT word timing", false)
   .option(
     "--stt-lang <code>",
     "override the Whisper STT language hint (ISO-639-1, e.g. et) — defaults to " +
@@ -982,6 +986,7 @@ program
         lang?: string;
         langs?: string;
         sttLang?: string;
+        alignScript?: boolean;
       }
     ) => {
       const langs = langsFrom(opts);
@@ -998,7 +1003,7 @@ program
         if (opts.offline) {
           await generateCaptionsOffline(project, sb);
         } else {
-          await generateCaptions(project, sb, { language: opts.sttLang });
+          await generateCaptions(project, sb, { language: opts.sttLang, alignScript: opts.alignScript });
         }
       }
     }

package/src/distribute.ts

@@ -266,6 +266,9 @@ export async function scaffoldDemo(
       screenshotPath: project.p("logs", "inspect-init.png"),
     });
     await fs.writeFile(project.p("logs", "inspect-init.json"), JSON.stringify(res, null, 2));
+    if (res.target.status === "blocked") {
+      throw new Error(`Cannot draft from ${opts.fromUrl}: ${res.target.reason}. See logs/inspect-init.json and inspect-init.png.`);
+    }
     await fs.writeFile(project.p("input", "brief.md"), briefFromInspect(name, res));
     await fs.writeFile(project.storyboardPath, storyboardFromInspect(name, res));
     ok(

package/src/inspect.ts

@@ -36,6 +36,8 @@ export interface InspectElement {
 }
 
 export interface InspectResult {
+  /** Whether the requested product UI was actually available to inspect. */
+  target: { status: "available" | "blocked"; reason?: string };
   url: string;
   finalUrl: string;
   title: string;
@@ -174,11 +176,12 @@ const SCAN_JS = String.raw`(() => {
     src: (f.getAttribute("src") || "").slice(0, 200),
     selector: f.id && stableId(f.id) ? "#" + cssEsc(f.id) : (f.getAttribute("name") ? 'iframe[name="' + q(f.getAttribute("name")) + '"]' : "iframe:nth-of-type(" + (i + 1) + ")"),
   }));
-  return { title: document.title, elements: items, headings, iframes, truncated: all.length > LIMIT && items.length >= LIMIT, total: all.length };
+  return { title: document.title, bodyText: (document.body?.innerText || "").slice(0, 1200), elements: items, headings, iframes, truncated: all.length > LIMIT && items.length >= LIMIT, total: all.length };
 })()`;
 
 interface ScanResult {
   title: string;
+  bodyText: string;
   elements: InspectElement[];
   headings: Array<{ level: number; text: string }>;
   iframes: Array<{ name: string; src: string; selector: string }>;
@@ -186,6 +189,23 @@ interface ScanResult {
   total: number;
 }
 
+/** Conservative signal: report a challenge without guessing how to solve it. */
+export function inspectTargetStatus(scan: Pick<ScanResult, "title" | "headings" | "bodyText">): InspectResult["target"] {
+  const title = scan.title.trim().toLowerCase();
+  const headings = scan.headings.map((h) => h.text.toLowerCase()).join(" ");
+  const body = scan.bodyText.toLowerCase();
+  if (/^(just a moment|attention required|security verification|checking your browser)/i.test(title) ||
+      /performing security verification|verify (you are|that you are) human|checking your browser/i.test(headings) ||
+      (/security verification|verify you are human/i.test(body) && /challenge|cloudflare|captcha/i.test(body))) {
+    return { status: "blocked", reason: "security verification page; the requested product UI was not inspected" };
+  }
+  if (/^(sign in|log in|login|authentication required)$/i.test(scan.title.trim()) &&
+      /sign in|log in|email|password/i.test(body)) {
+    return { status: "blocked", reason: "login page; the requested product UI was not inspected" };
+  }
+  return { status: "available" };
+}
+
 /** Scan one frame for visible interactive elements (see SCAN_JS). */
 export async function scanInteractive(
   target: Page | Frame,
@@ -233,6 +253,7 @@ export async function inspectPage(opts: InspectOptions): Promise<InspectResult>
       screenshot = opts.screenshotPath;
     }
     return {
+      target: inspectTargetStatus(main),
       url: opts.url,
       finalUrl: page.url(),
       title: main.title,

package/src/mcp/server.ts

@@ -1131,6 +1131,7 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
         .boolean()
         .optional()
         .describe("approximate captions from the script — no network/STT"),
+      alignScript: z.boolean().optional().describe("use script spelling and punctuation with STT word timing"),
       params: PARAMS_INPUT,
       lang: LANG_INPUT,
     },
@@ -1142,7 +1143,7 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
         if (args.offline) {
           await generateCaptionsOffline(lp, sb, sceneProgress(job));
         } else {
-          await generateCaptions(lp, sb, sceneProgress(job));
+          await generateCaptions(lp, sb, { ...sceneProgress(job), alignScript: args.alignScript });
         }
         return {
           srt: lp.captionsSrtPath,
@@ -1375,6 +1376,7 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
         });
         const file = project.p("logs", `inspect-${stamp}.json`);
         await writeJson(file, res);
+        if (res.target.status === "blocked") log(`inspect blocked: ${res.target.reason}`);
         log(`inspect: ${res.elements.length} element(s), ${res.headings.length} heading(s) → ${file}`);
         return { ...res, file };
       })

package/src/player.ts

@@ -1,6 +1,7 @@
 import type { Page, Locator, Frame, Request, Response, Dialog } from "playwright";
 import { scanInteractive, rankCandidates, type DriftCandidate } from "./inspect.js";
 import { compileUserRegex } from "./safe-regex.js";
+import { redactUrl, redactSecrets } from "./redact.js";
 import { promises as fs } from "node:fs";
 import { basename, isAbsolute, join, resolve } from "node:path";
 import { existsSync } from "node:fs";
@@ -242,39 +243,51 @@ class NetworkWatch {
     private readonly page: Page,
     private readonly t0: number
   ) {
+    // A listener that throws surfaces as an unhandled rejection on the page
+    // and can abort a take, so each one is wrapped: diagnostics are strictly
+    // best-effort and must never take the recording down with them.
     this.onResponse = (res: Response) => {
-      if (res.status() < 400) return;
-      const req = res.request();
-      const entry: FailedRequest = {
-        tMs: Date.now() - t0,
-        method: req.method(),
-        url: truncateUrl(res.url(), 200),
-        status: res.status(),
-        resourceType: req.resourceType(),
-      };
-      this.push(entry);
-      if (/^(xhr|fetch)$/.test(entry.resourceType)) {
-        res
-          .text()
-          .then((b) => {
-            const snippet = b.replace(/\s+/g, " ").trim().slice(0, NET_BODY_MAX);
-            if (snippet) entry.body = snippet;
-          })
-          .catch(() => {});
+      try {
+        if (res.status() < 400) return;
+        const req = res.request();
+        const entry: FailedRequest = {
+          tMs: Date.now() - t0,
+          method: req.method(),
+          url: redactUrl(res.url(), 200),
+          status: res.status(),
+          resourceType: req.resourceType(),
+        };
+        this.push(entry);
+        if (/^(xhr|fetch)$/.test(entry.resourceType)) {
+          res
+            .text()
+            .then((b) => {
+              const snippet = redactSecrets(b.replace(/\s+/g, " ").trim()).slice(0, NET_BODY_MAX);
+              if (snippet) entry.body = snippet;
+            })
+            // The body is gone once the page navigates; that's expected.
+            .catch(() => {});
+        }
+      } catch {
+        /* diagnostics only — a broken response record is not a take failure */
       }
     };
     this.onFailed = (req: Request) => {
-      const err = req.failure()?.errorText ?? "failed";
-      // Navigations cancel in-flight requests; that's not an app failure.
-      if (/ERR_ABORTED/.test(err)) return;
-      this.push({
-        tMs: Date.now() - t0,
-        method: req.method(),
-        url: truncateUrl(req.url(), 200),
-        status: null,
-        error: err,
-        resourceType: req.resourceType(),
-      });
+      try {
+        const err = req.failure()?.errorText ?? "failed";
+        // Navigations cancel in-flight requests; that's not an app failure.
+        if (/ERR_ABORTED/.test(err)) return;
+        this.push({
+          tMs: Date.now() - t0,
+          method: req.method(),
+          url: redactUrl(req.url(), 200),
+          status: null,
+          error: err,
+          resourceType: req.resourceType(),
+        });
+      } catch {
+        /* diagnostics only */
+      }
     };
   }
 
@@ -1900,7 +1913,9 @@ async function waitForChange(
 // ---------------------------------------------------------------------------
 
 function truncateUrl(url: string, n = 90): string {
-  return url.length > n ? url.slice(0, n) + "…" : url;
+  // Same masking as the network watch: every URL that reaches a log or a
+  // fail-*.json goes through redaction, not just the ones from failed requests.
+  return redactUrl(url, n);
 }
 
 /** Never returns — enriches the error with scene/action context + diagnostics. */

package/src/redact.ts

@@ -0,0 +1,72 @@
+/**
+ * Redaction for diagnostics.
+ *
+ * A failed take writes `logs/fail-*.json` (and log lines) containing live URLs
+ * and, for XHR/fetch failures, a snippet of the response body. Those come from
+ * whatever app was being recorded — a magic-link callback, an OAuth redirect or
+ * an error payload can easily carry a session token. The logs are meant to be
+ * pasted into an issue, so anything that looks like a credential is masked
+ * before it is written. This is a best-effort net, not a guarantee: it never
+ * throws, and it errs toward masking.
+ */
+
+const MASK = "REDACTED";
+
+/** Query/form parameter names whose *value* is never printed. */
+const SECRET_PARAM =
+  /^(?:.*[-_])?(?:token|access[-_]?token|id[-_]?token|refresh[-_]?token|secret|password|passwd|pwd|api[-_]?key|apikey|key|auth|authorization|session|sig|signature|code|credential|assertion)$/i;
+
+/** Free-text shapes that are credentials wherever they appear. */
+const SECRET_SHAPES: Array<[RegExp, string]> = [
+  [/\b(bearer|basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi, `$1 ${MASK}`],
+  // Provider-prefixed keys (sk-…, ghp_…, xoxb-…, AKIA…).
+  [/\b(?:sk|pk|rk)-[A-Za-z0-9_-]{16,}/g, MASK],
+  [/\bgh[pousr]_[A-Za-z0-9]{16,}/g, MASK],
+  [/\bxox[abposr]-[A-Za-z0-9-]{10,}/g, MASK],
+  [/\bAKIA[0-9A-Z]{16}\b/g, MASK],
+  // JWTs.
+  [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, MASK],
+  // JSON/pair values under a secret-looking name.
+  [
+    /("?)([A-Za-z0-9_-]*(?:token|secret|password|passwd|api[-_]?key|apikey|authorization|credential)[A-Za-z0-9_-]*)\1(\s*[:=]\s*)("?)[^"\s,}&]+\4/gi,
+    `$1$2$1$3$4${MASK}$4`,
+  ],
+];
+
+/** Mask credential-shaped substrings in free text (response bodies, errors). */
+export function redactSecrets(text: string): string {
+  if (!text) return text;
+  let out = text;
+  for (const [re, to] of SECRET_SHAPES) out = out.replace(re, to);
+  return out;
+}
+
+/**
+ * Mask secret-bearing query/fragment parameters, then truncate to `n` chars.
+ * Anything that doesn't parse as a URL still goes through {@link redactSecrets}.
+ */
+export function redactUrl(url: string, n = 90): string {
+  let safe: string;
+  try {
+    const u = new URL(url);
+    for (const params of [u.searchParams, new URLSearchParams(u.hash.replace(/^#/, ""))]) {
+      let touched = false;
+      for (const name of [...params.keys()]) {
+        if (SECRET_PARAM.test(name)) {
+          params.set(name, MASK);
+          touched = true;
+        }
+      }
+      if (touched && params !== u.searchParams) u.hash = params.toString();
+    }
+    if (u.username || u.password) {
+      u.username = "";
+      u.password = "";
+    }
+    safe = redactSecrets(u.toString());
+  } catch {
+    // Not an absolute URL (about:blank, a relative href, a data: blob).
+    safe = redactSecrets(url);
+  }
+  return safe.length > n ? safe.slice(0, n) + "…" : safe;
+}

package/src/safe-regex.ts

@@ -1,3 +1,5 @@
+import { RE2JS } from "re2js";
+
 /**
  * Storyboard-supplied regex patterns (`assert.textMatches`, `assert.url`, and
  * the `textMatches` option the player threads through) are compiled at replay
@@ -29,8 +31,19 @@ export function isUnsafeRegexSource(pattern: string): string | null {
  * Compile a storyboard-supplied pattern, or throw with `where` naming the
  * field so the author can see which matcher to fix.
  */
-export function compileUserRegex(pattern: string, flags: string, where: string): RegExp {
+export function compileUserRegex(pattern: string, flags: string, where: string): RE2JS {
+  if (typeof pattern !== "string" || pattern === "")
+    throw new Error(`${where}: regex must be a non-empty string`);
   const unsafe = isUnsafeRegexSource(pattern);
   if (unsafe) throw new Error(`${where}: unsafe regex — ${unsafe}`);
-  return new RegExp(pattern, flags);
+  try {
+    // RE2JS guarantees linear-time matching for storyboard supplied patterns.
+    // The replay path only uses `test`, so its API is interchangeable here.
+    if (flags && flags !== "i") throw new Error(`unsupported regex flags ${flags}`);
+    return RE2JS.compile(pattern, flags === "i" ? RE2JS.CASE_INSENSITIVE : 0);
+  } catch (e) {
+    // A raw SyntaxError names neither the field nor the storyboard, which is
+    // the only thing the author can act on.
+    throw new Error(`${where}: invalid regex ${JSON.stringify(pattern)} — ${(e as Error).message}`);
+  }
 }