@tandryukha/aidemo 0.8.0 → 0.14.1

package/src/setup.ts

@@ -0,0 +1,248 @@
+/**
+ * Pre-take preparation (issue #44): seed cookies / a Playwright storageState
+ * into the recording profile, and run an optional preflight hook — the two
+ * things a cookie-gated or fixture-rotating site otherwise forces you to
+ * script by hand around the engine.
+ *
+ * Seeding happens INSIDE the launched context (after Chrome is up, before the
+ * first storyboard action), so it composes with `--fresh` (the wipe comes
+ * first) and with a logged-in shared profile alike. The preflight hook runs
+ * before Chrome launches, with the resolved profile dir in its env, so a
+ * script that wants to seed the profile its own way still can.
+ */
+
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import type { BrowserContext, Page } from "playwright";
+import type { SeedCookie, Storyboard } from "./types.js";
+import { log } from "./util.js";
+
+/** Playwright's storageState file shape (the subset we consume). */
+interface StorageStateFile {
+  cookies?: SeedCookie[];
+  origins?: Array<{
+    origin: string;
+    localStorage?: Array<{ name: string; value: string }>;
+  }>;
+}
+
+/** Everything to inject into the context before the first action. */
+export interface Seeds {
+  cookies: SeedCookie[];
+  origins: Array<{ origin: string; localStorage: Array<{ name: string; value: string }> }>;
+  /** Where each seed came from, for the log line. */
+  sources: string[];
+}
+
+/**
+ * Parse one `--cookie` flag: `name=value;domain=host;path=/;secure;httpOnly;
+ * sameSite=Lax;url=https://host/` — the first `k=v` is the cookie, the rest
+ * are attributes (cookie-header style, so it can be pasted from DevTools).
+ */
+export function parseCookieFlag(spec: string): SeedCookie {
+  const parts = spec
+    .split(";")
+    .map((p) => p.trim())
+    .filter(Boolean);
+  if (parts.length === 0) throw new Error(`--cookie: empty spec`);
+  const eq = parts[0].indexOf("=");
+  if (eq <= 0) {
+    throw new Error(`--cookie: expected name=value first, got "${parts[0]}"`);
+  }
+  const cookie: SeedCookie = {
+    name: parts[0].slice(0, eq).trim(),
+    value: parts[0].slice(eq + 1).trim(),
+  };
+  for (const attr of parts.slice(1)) {
+    const i = attr.indexOf("=");
+    const key = (i < 0 ? attr : attr.slice(0, i)).trim().toLowerCase();
+    const val = i < 0 ? "" : attr.slice(i + 1).trim();
+    switch (key) {
+      case "domain":
+        cookie.domain = val;
+        break;
+      case "path":
+        cookie.path = val;
+        break;
+      case "url":
+        cookie.url = val;
+        break;
+      case "expires":
+        cookie.expires = Number(val);
+        break;
+      case "secure":
+        cookie.secure = val === "" || val === "true";
+        break;
+      case "httponly":
+        cookie.httpOnly = val === "" || val === "true";
+        break;
+      case "samesite": {
+        const v = val.toLowerCase();
+        cookie.sameSite = v === "strict" ? "Strict" : v === "none" ? "None" : "Lax";
+        break;
+      }
+      default:
+        throw new Error(`--cookie: unknown attribute "${key}" in "${spec}"`);
+    }
+  }
+  if (!cookie.domain && !cookie.url) {
+    throw new Error(
+      `--cookie "${cookie.name}": add domain=<host> (or url=<origin>) so the ` +
+        `browser knows which site it belongs to`
+    );
+  }
+  return cookie;
+}
+
+/** Normalize a seed cookie into the shape `context.addCookies` accepts. */
+function toPlaywrightCookie(c: SeedCookie) {
+  if (c.url) {
+    return {
+      name: c.name,
+      value: c.value,
+      url: c.url,
+      ...(c.expires != null ? { expires: c.expires } : {}),
+      ...(c.httpOnly != null ? { httpOnly: c.httpOnly } : {}),
+      ...(c.secure != null ? { secure: c.secure } : {}),
+      ...(c.sameSite ? { sameSite: c.sameSite } : {}),
+    };
+  }
+  return {
+    name: c.name,
+    value: c.value,
+    domain: c.domain!,
+    path: c.path ?? "/",
+    ...(c.expires != null ? { expires: c.expires } : {}),
+    ...(c.httpOnly != null ? { httpOnly: c.httpOnly } : {}),
+    ...(c.secure != null ? { secure: c.secure } : {}),
+    ...(c.sameSite ? { sameSite: c.sameSite } : {}),
+  };
+}
+
+export interface SeedInputs {
+  /** CLI/MCP `--storage-state <file>` (in addition to the storyboard's). */
+  storageState?: string;
+  /** CLI/MCP `--cookie` specs, already parsed. */
+  cookies?: SeedCookie[];
+}
+
+/**
+ * Collect every seed the take should inject: the storyboard `setup` block
+ * first, then CLI/MCP overrides on top. Relative storageState paths resolve
+ * against the demo dir. Returns null when nothing is to be seeded.
+ */
+export async function collectSeeds(
+  demoDir: string,
+  storyboard: Storyboard,
+  inputs: SeedInputs = {}
+): Promise<Seeds | null> {
+  const seeds: Seeds = { cookies: [], origins: [], sources: [] };
+  const files = [storyboard.setup?.storageState, inputs.storageState].filter(
+    (f): f is string => !!f
+  );
+  for (const f of files) {
+    const path = isAbsolute(f) ? f : resolve(demoDir, f);
+    let parsed: StorageStateFile;
+    try {
+      parsed = JSON.parse(await fs.readFile(path, "utf8")) as StorageStateFile;
+    } catch (err) {
+      throw new Error(`storageState ${path}: ${(err as Error).message}`);
+    }
+    const cookies = parsed.cookies ?? [];
+    const origins = (parsed.origins ?? []).map((o) => ({
+      origin: o.origin,
+      localStorage: o.localStorage ?? [],
+    }));
+    seeds.cookies.push(...cookies);
+    seeds.origins.push(...origins.filter((o) => o.localStorage.length > 0));
+    seeds.sources.push(
+      `${path} (${cookies.length} cookie(s), ${origins.length} origin(s))`
+    );
+  }
+  const inline = [...(storyboard.setup?.cookies ?? []), ...(inputs.cookies ?? [])];
+  if (inline.length) {
+    seeds.cookies.push(...inline);
+    seeds.sources.push(`${inline.length} inline cookie(s)`);
+  }
+  return seeds.cookies.length || seeds.origins.length ? seeds : null;
+}
+
+/**
+ * Inject the seeds into a live context. Cookies go straight into the profile's
+ * cookie jar; localStorage is per-origin and can only be written from a page
+ * ON that origin, so each origin is visited once (about:blank is restored
+ * afterwards — the visits land in the recording's trimmed lead-in).
+ */
+export async function applySeeds(
+  context: BrowserContext,
+  page: Page,
+  seeds: Seeds
+): Promise<void> {
+  if (seeds.cookies.length) {
+    await context.addCookies(seeds.cookies.map(toPlaywrightCookie));
+  }
+  for (const o of seeds.origins) {
+    await page.goto(o.origin, { waitUntil: "domcontentloaded" });
+    await page.evaluate((entries) => {
+      for (const { name, value } of entries) localStorage.setItem(name, value);
+    }, o.localStorage);
+  }
+  if (seeds.origins.length) await page.goto("about:blank");
+  log(
+    `seeded profile: ${seeds.cookies.length} cookie(s), ` +
+      `${seeds.origins.length} origin(s) of localStorage ← ${seeds.sources.join("; ")}`
+  );
+}
+
+export interface PreflightEnv {
+  demoDir: string;
+  storyboardPath: string;
+  profileDir: string;
+}
+
+/**
+ * Run the storyboard's `setup.preflight` shell command from the demo dir.
+ * Output is streamed into the engine log (prefixed), a non-zero exit aborts
+ * the take with the command's stderr tail.
+ */
+export async function runPreflight(command: string, env: PreflightEnv): Promise<void> {
+  log(`preflight: ${command}`);
+  const started = Date.now();
+  await new Promise<void>((resolvePromise, reject) => {
+    const proc = spawn(command, {
+      cwd: env.demoDir,
+      shell: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        AIDEMO_DEMO_DIR: env.demoDir,
+        AIDEMO_STORYBOARD: env.storyboardPath,
+        AIDEMO_PROFILE: env.profileDir,
+      },
+    });
+    const tail: string[] = [];
+    const relay = (chunk: Buffer) => {
+      for (const line of chunk.toString().split(/\r?\n/)) {
+        if (!line.trim()) continue;
+        log(`  │ ${line}`);
+        tail.push(line);
+        if (tail.length > 20) tail.shift();
+      }
+    };
+    proc.stdout.on("data", relay);
+    proc.stderr.on("data", relay);
+    proc.on("error", reject);
+    proc.on("close", (code, signal) => {
+      if (code === 0) return resolvePromise();
+      reject(
+        new Error(
+          `preflight exited ${code ?? signal} — the take was not started.\n` +
+            `  command: ${command}\n` +
+            (tail.length ? `  last output:\n    ${tail.join("\n    ")}` : "")
+        )
+      );
+    });
+  });
+  log(`preflight ok (${Date.now() - started}ms)`);
+}

package/src/starter.ts

@@ -139,3 +139,247 @@ export const STARTER_STORYBOARD = (name: string): string =>
     null,
     2
   ) + "\n";
+
+// ---------------------------------------------------------------------------
+// `init --from-url`: a draft built from what `inspect` saw on the page — real
+// headings become scenes, real unique selectors become the beats. No LLM: the
+// agent still writes the narration and decides the flow; this only removes
+// the selector archaeology from the first draft.
+// ---------------------------------------------------------------------------
+
+import type { InspectElement, InspectResult } from "./inspect.js";
+
+function slug(text: string, max = 24): string {
+  const s = text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, max)
+    .replace(/-+$/g, "");
+  return s || "scene";
+}
+
+function jsonText(text: string): string {
+  return text.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+/**
+ * A selector that reaches exactly this heading. `:has-text()` is a substring
+ * match, so a long heading is trimmed at a word boundary (shorter = less
+ * brittle against a line break or a trailing badge); a page that repeats the
+ * same heading text gets an explicit `nth=` so probe doesn't hit Playwright's
+ * strict-mode "resolved to N elements".
+ */
+function headingSelector(
+  h: { level: number; text: string },
+  all: Array<{ level: number; text: string }>
+): string {
+  let text = h.text;
+  if (text.length > 40) {
+    const cut = text.slice(0, 40);
+    const sp = cut.lastIndexOf(" ");
+    text = (sp > 16 ? cut.slice(0, sp) : cut).trim();
+  }
+  const sel = `h${h.level}:has-text("${jsonText(text)}")`;
+  // Count what that selector would also match: same level, containing the text.
+  const matches = all.filter((o) => o.level === h.level && o.text.includes(text));
+  if (matches.length < 2) return sel;
+  const idx = Math.max(0, matches.findIndex((o) => o.text === h.text));
+  return `${sel} >> nth=${idx}`;
+}
+
+/** Headings worth a scene: h1/h2 (h3 when there are too few), deduped, ≤ 4. */
+function sceneHeadings(res: InspectResult): Array<{ level: number; text: string }> {
+  const clean = res.headings
+    .map((h) => ({ level: h.level, text: h.text.replace(/\s+/g, " ").trim() }))
+    .filter((h) => h.text.length >= 3 && h.text.length <= 80);
+  const seen = new Set<string>();
+  const pick = (maxLevel: number) =>
+    clean.filter((h) => {
+      if (h.level > maxLevel || seen.has(h.text.toLowerCase())) return false;
+      seen.add(h.text.toLowerCase());
+      return true;
+    });
+  let out = pick(2);
+  if (out.length < 2) out = [...out, ...pick(3)];
+  return out.slice(0, 4);
+}
+
+/** The most promising interactive elements: named, unique, in the viewport first. */
+function candidateElements(res: InspectResult, max = 8): InspectElement[] {
+  const score = (e: InspectElement): number =>
+    (e.selectors.length ? 2 : 0) +
+    (e.inViewport ? 2 : 0) +
+    (e.role === "button" || e.role === "textbox" || e.role === "searchbox" ? 1 : 0) +
+    (e.name ? 1 : 0) +
+    (e.testid ? 1 : 0);
+  return [...res.elements]
+    .filter((e) => e.selectors.length && e.name)
+    .sort((a, b) => score(b) - score(a))
+    .slice(0, max);
+}
+
+export function storyboardFromInspect(name: string, res: InspectResult): string {
+  const allHeadings = res.headings.map((h) => ({
+    level: h.level,
+    text: h.text.replace(/\s+/g, " ").trim(),
+  }));
+  const headings = sceneHeadings(res);
+  const cands = candidateElements(res);
+  const search = cands.find((e) => e.role === "textbox" || e.role === "searchbox");
+  const cta = cands.find((e) => e.role === "button" || e.role === "link");
+  const title = res.title?.trim() || name;
+  const scenes: unknown[] = [];
+
+  scenes.push({
+    id: "s1-open",
+    narration: `<hook: what ${title} does, in one sentence>`,
+    actions: [
+      { op: "goto", url: res.finalUrl || res.url },
+      { op: "pause", ms: 1200 },
+      ...(search
+        ? [
+            {
+              op: "type",
+              target: { selector: search.selector },
+              humanize: false,
+              text: "<a realistic query>",
+              comment: `textbox "${search.name}" — delete this beat if the story doesn't start with a search`,
+            },
+            { op: "press", key: "Enter" },
+            { op: "pause", ms: 1400 },
+          ]
+        : []),
+    ],
+  });
+
+  headings.slice(search ? 0 : 1).forEach((h, i) => {
+    scenes.push({
+      id: `s${scenes.length + 1}-${slug(h.text)}`,
+      narration: `<narrate the "${h.text}" section>`,
+      actions: [
+        {
+          op: "scrollTo",
+          target: { selector: headingSelector(h, allHeadings) },
+          easing: "smooth",
+        },
+        { op: "pause", ms: 1400 },
+      ],
+      ...(i === 0 ? {} : {}),
+    });
+  });
+
+  // Heading-less page (a single-page app that paints its own layout): there is
+  // nothing to name a section by, so walk the page instead — two viewport-sized
+  // scroll beats give the agent a real skeleton to rewrite, rather than a
+  // one-scene draft that hides how long the page is.
+  if (headings.length === 0) {
+    const step = Math.round(res.viewport.height * 0.8);
+    for (const [i, label] of ["what's on the page", "further down the page"].entries()) {
+      scenes.push({
+        id: `s${scenes.length + 1}-scroll-${i + 1}`,
+        narration: `<narrate ${label} — no headings on this page, so name the section yourself>`,
+        actions: [
+          { op: "scrollBy", dy: step, easing: "smooth" },
+          { op: "pause", ms: 1400 },
+        ],
+      });
+    }
+  }
+
+  if (cta) {
+    scenes.push({
+      id: `s${scenes.length + 1}-${slug(cta.name)}`,
+      narration: `<the payoff: what happens after "${cta.name}">`,
+      actions: [
+        {
+          op: "hover",
+          target: { selector: cta.selector },
+          comment: `${cta.role} "${cta.name}" — change to click once the flow after it is known, then assert the result`,
+        },
+        { op: "pause", ms: 1400 },
+      ],
+    });
+  }
+
+  const frames: Record<string, string> = {};
+  for (const f of res.iframes.slice(0, 3)) frames[f.name || `frame${Object.keys(frames).length + 1}`] = f.selector;
+
+  const doc = {
+    _README:
+      `Draft from \`inspect ${res.url}\` — headings became scenes, unique selectors became beats. ` +
+      "Write the narration (one idea per scene, ~2.5 words/s), turn the candidate hover into the real click + an assert, " +
+      "drop scenes that don't serve the story, then `aidemo probe`. `_candidates` lists more selectors seen on the page." +
+      (headings.length === 0
+        ? " No headings were found (single-page app?) — the scroll scenes are placeholders; point them at real elements with `scrollTo`."
+        : ""),
+    title,
+    targetLengthSeconds: 45,
+    video: { width: res.viewport.width, height: res.viewport.height },
+    ...(Object.keys(frames).length ? { frames } : {}),
+    voice: {
+      voiceId: "marin",
+      instructions: "Confident, friendly founder. Clear and warm, brisk but not rushed.",
+      speed: 1.05,
+    },
+    zoom: { scale: 1.55, easeMs: 600, holdMs: 1700 },
+    intro: { title, subtitle: "<one-line value prop>", durationMs: 2600 },
+    outro: { title: "<call to action>", subtitle: "<your-domain.example>", durationMs: 2600 },
+    scenes,
+    _candidates: cands.map((e) => ({
+      role: e.role,
+      name: e.name,
+      selector: e.selector,
+      ...(e.frame ? { frame: e.frame } : {}),
+      ...(e.inViewport ? {} : { belowFold: true }),
+    })),
+  };
+  return JSON.stringify(doc, null, 2) + "\n";
+}
+
+export function briefFromInspect(name: string, res: InspectResult): string {
+  const headings = res.headings.map((h) => `${"  ".repeat(Math.max(0, h.level - 1))}- h${h.level} ${h.text}`);
+  const cands = candidateElements(res, 12).map(
+    (e) => `| ${e.role} | ${e.name.replace(/\|/g, "/")} | \`${e.selector}\` | ${e.inViewport ? "" : "below fold"} |`
+  );
+  return `# Demo Brief — ${name}
+
+Drafted from \`aidemo inspect ${res.url}\` (page title: ${res.title || "—"}).
+Fill in the product, audience, tone and CTA; the storyboard next to this file
+already has the page's real selectors.
+
+## Product
+<your product>
+
+## Demo goal
+<the core flow, end to end>
+
+## Audience
+<who is this for>
+
+## Tone
+Friendly, practical, founder-style. Brisk.
+
+## Length
+~45-60 seconds.
+
+## CTA
+<what should the viewer do next>
+
+---
+
+## What inspect saw
+
+Headings:
+${headings.join("\n") || "- (none)"}
+
+Interactive elements (unique selectors):
+
+| role | name | selector | |
+|---|---|---|---|
+${cands.join("\n") || "| — | — | — | |"}
+${res.iframes.length ? `\niframes: ${res.iframes.map((f) => `${f.name || "?"} → \`${f.selector}\``).join(", ")}\n` : ""}
+Next: write the narration, replace the candidate hover with the real click +
+\`assert\`, then \`aidemo probe\` (or the MCP \`probe\` job).
+`;
+}

package/src/stills.ts

@@ -14,6 +14,8 @@ interface StillMarker {
   sceneId: string;
   name: string;
   tMs: number;
+  source?: string;
+  leadInMs?: number;
 }
 
 /** True if any scene declares a `still` action (drives auto-extract in render). */
@@ -65,7 +67,14 @@ export async function extractStills(
         );
       }
       seen.set(ev.name, scene.id);
-      markers.push({ sceneId: scene.id, name: ev.name, tMs: ev.tMs });
+      markers.push({
+        sceneId: scene.id,
+        name: ev.name,
+        tMs: ev.tMs,
+        // Resumed takes: a reused scene's still lives in its own raw file.
+        source: scene.source ? resolve(project.dir, scene.source) : undefined,
+        leadInMs: scene.leadInMs,
+      });
     }
   }
 
@@ -96,8 +105,10 @@ export async function extractStills(
     // The same timeline→video mapping compose uses (rawT = tMs + leadInMs).
     // Clamp just inside the recording so a marker at the very tail still yields
     // a decodable frame rather than an ffmpeg seek past EOF.
-    const rawMs = m.tMs + timeline.leadInMs;
-    const seekMs = Math.max(0, Math.min(rawMs, Math.max(0, videoMs - 60)));
+    const src = m.source ?? rawVideo;
+    const srcMs = m.source ? await probeDurationMs(src) : videoMs;
+    const rawMs = m.tMs + (m.leadInMs ?? timeline.leadInMs);
+    const seekMs = Math.max(0, Math.min(rawMs, Math.max(0, srcMs - 60)));
     const out = resolve(outDir, `${m.name}.png`);
     // -ss before -i is a fast, accurate seek (accurate_seek is on by default);
     // -frames:v 1 grabs exactly one frame. No overlay/drawtext filters, so this
@@ -106,7 +117,7 @@ export async function extractStills(
       "-ss",
       (seekMs / 1000).toFixed(3),
       "-i",
-      rawVideo,
+      src,
       "-frames:v",
       "1",
       out,