takomi 2.1.37 → 2.1.39

package/plugins/takomi-flow/scripts/lib/browser.mjs

@@ -0,0 +1,39 @@
+import path from 'node:path';
+import { ensureDir } from './paths.mjs';
+import { loadPlaywright } from './playwright-loader.mjs';
+
+export async function launchFlowBrowser(options = {}) {
+  const { chromium } = await loadPlaywright();
+  const profileDir = ensureDir(path.resolve(options.profileDir));
+  const downloadsDir = ensureDir(path.resolve(options.downloadsDir));
+  const headless = options.headless === true;
+  if (options.cdpUrl) {
+    const browser = await chromium.connectOverCDP(options.cdpUrl);
+    const context = browser.contexts()[0] || await browser.newContext({ acceptDownloads: true });
+    const page = context.pages()[0] || await context.newPage();
+    return { browser, context, page, profileDir, downloadsDir, cdpUrl: options.cdpUrl, attached: true };
+  }
+  const channel = options.browserChannel || process.env.TAKOMI_FLOW_BROWSER_CHANNEL || defaultBrowserChannel();
+  const context = await chromium.launchPersistentContext(profileDir, {
+    headless,
+    ...(channel ? { channel } : {}),
+    acceptDownloads: true,
+    downloadsPath: downloadsDir,
+    viewport: { width: 1440, height: 960 },
+  });
+  const page = context.pages()[0] || await context.newPage();
+  return { context, page, profileDir, downloadsDir, browserChannel: channel };
+}
+
+export async function closeFlowBrowser(browser) {
+  if (browser.attached) {
+    await browser.browser?.close?.().catch(() => {});
+    return;
+  }
+  await browser.context.close().catch(() => {});
+}
+
+function defaultBrowserChannel() {
+  if (process.platform === 'win32' || process.platform === 'darwin') return 'chrome';
+  return undefined;
+}

package/plugins/takomi-flow/scripts/lib/capabilities.mjs

@@ -0,0 +1,11 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = path.resolve(MODULE_DIR, '..', '..');
+const CAPABILITIES_PATH = path.join(PLUGIN_ROOT, 'assets', 'capabilities.json');
+
+export function loadCapabilities() {
+  return JSON.parse(fs.readFileSync(CAPABILITIES_PATH, 'utf8'));
+}

package/plugins/takomi-flow/scripts/lib/collect.mjs

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensureDir, writeJson } from './paths.mjs';
+import { reviewRun } from './review.mjs';
+
+export async function collectRun(args = {}) {
+  if (!args.run) throw new Error('collect requires --run <run.json|run-dir>');
+  if (!args.targetDir) throw new Error('collect requires --target-dir <path>');
+  const targetDir = ensureDir(path.resolve(args.targetDir));
+  const review = await reviewRun({
+    run: args.run,
+    frames: args.frames || 0,
+    reportPath: args.reportPath,
+  });
+  const copied = [];
+  for (const asset of review.catalog.assets || []) {
+    if (asset.exists) copied.push(copyFile(asset.path, path.join(targetDir, 'assets')));
+    if (args.includeFrames) {
+      for (const frame of asset.frames || []) copied.push(copyFile(frame, path.join(targetDir, 'frames')));
+    }
+  }
+  if (review.reportPath && fs.existsSync(review.reportPath)) {
+    copied.push(copyFile(review.reportPath, targetDir, 'report.md'));
+  }
+  const manifest = {
+    schemaVersion: 1,
+    status: copied.length ? 'collected' : 'empty',
+    runId: review.runId,
+    sourceRunDir: review.runDir,
+    targetDir,
+    copied,
+    review,
+  };
+  manifest.manifestPath = writeJson(path.join(targetDir, 'takomi-flow-collection.json'), manifest);
+  return manifest;
+}
+
+function copyFile(source, targetDir, name = path.basename(source)) {
+  ensureDir(targetDir);
+  const target = uniquePath(path.join(targetDir, name));
+  fs.copyFileSync(source, target);
+  return { source, target };
+}
+
+function uniquePath(filePath) {
+  if (!fs.existsSync(filePath)) return filePath;
+  const parsed = path.parse(filePath);
+  for (let i = 1; i < 1000; i += 1) {
+    const candidate = path.join(parsed.dir, `${parsed.name}-${i}${parsed.ext}`);
+    if (!fs.existsSync(candidate)) return candidate;
+  }
+  throw new Error(`Could not create unique path for ${filePath}`);
+}

package/plugins/takomi-flow/scripts/lib/commands.mjs

@@ -0,0 +1,175 @@
+import { defaultProfileDir, defaultRunsDir, FLOW_URL, resolvePath } from './paths.mjs';
+import { closeFlowBrowser, launchFlowBrowser } from './browser.mjs';
+import { createRun, baseResult, saveResult } from './result.mjs';
+import { capture, inspectFlowState, openFlow } from './flow-ui.mjs';
+import { launchTrustedChrome } from './trusted-chrome.mjs';
+import * as api from './api.mjs';
+
+export async function handleCommand(command, args) {
+  if (command === 'prepare') return prepare(args);
+  if (command === 'workflow') return printJson(await api.workflow({
+    ...args,
+    outputDir: args['output-dir'],
+    allowSpend: Boolean(args['allow-spend']),
+    extractFrames: args['extract-frames'],
+    sourceAssets: args.assets,
+    allowBrowser: Boolean(args['allow-browser']),
+    profileDir: args['profile-dir'],
+    browserChannel: args['browser-channel'],
+    cdpUrl: args['cdp-url'],
+    submit: Boolean(args.submit),
+  }));
+  if (command === 'template') return template(args);
+  if (command === 'examples') return printJson(api.examples({ name: args.name }));
+  if (command === 'trusted-chrome') return printJson(launchTrustedChrome({
+    profileDir: args['profile-dir'],
+    chromePath: args['chrome-path'],
+    port: args.port,
+    url: args.url,
+    printCommand: Boolean(args['print-command']),
+  }));
+  if (command === 'validate') return printJson(api.validate({ request: args.request }));
+  if (command === 'bootstrap') return bootstrap(args);
+  if (command === 'doctor') return doctor(args);
+  if (command === 'audit') return printJson(await api.audit({
+    profileDir: args['profile-dir'],
+    outputDir: args['output-dir'],
+    limit: args.limit,
+  }));
+  if (command === 'capabilities') return printJson(api.capabilities());
+  if (command === 'plan') return printJson(api.plan({
+    ...args,
+    outputDir: args['output-dir'],
+    allowSpend: Boolean(args['allow-spend']),
+    extractFrames: args['extract-frames'],
+    sourceAssets: args.assets,
+    submit: Boolean(args.submit),
+    targetDir: args['target-dir'],
+  }));
+  if (command === 'observe') return observe(args);
+  if (command === 'smoke') return smoke(args);
+  if (command === 'generate') return printJson(await api.generate({
+    request: args.request,
+    profileDir: args['profile-dir'],
+    browserChannel: args['browser-channel'],
+    cdpUrl: args['cdp-url'],
+    headless: Boolean(args.headless),
+  }));
+  if (command === 'selftest') return printJson(await api.selftest({ outputDir: args['output-dir'] }));
+  if (command === 'inspect') return printJson(api.inspect({ run: args.run }));
+  if (command === 'latest') return printJson(api.latest({ outputDir: args['output-dir'] }));
+  if (command === 'runs') return printJson(api.runs({ outputDir: args['output-dir'], limit: args.limit }));
+  if (command === 'assets') return assets(args);
+  if (command === 'review') return printJson(await api.review({
+    run: args.run,
+    frames: args.frames || 0,
+    reportPath: args['report-path'],
+  }));
+  if (command === 'collect') return printJson(await api.collect({
+    run: args.run,
+    targetDir: args['target-dir'],
+    frames: args.frames || 0,
+    includeFrames: Boolean(args['include-frames']),
+    reportPath: args['report-path'],
+  }));
+  if (command === 'report') return printJson(api.report({
+    run: args.run,
+    outputDir: args['output-dir'],
+    limit: args.limit,
+    reportPath: args['report-path'],
+  }));
+  throw new Error(`Unknown command: ${command}`);
+}
+
+async function observe(cliArgs) {
+  printJson(await api.observe({
+    profileDir: cliArgs['profile-dir'],
+    outputDir: cliArgs['output-dir'],
+    browserChannel: cliArgs['browser-channel'],
+    cdpUrl: cliArgs['cdp-url'],
+    headless: Boolean(cliArgs.headless),
+  }));
+}
+
+async function doctor(cliArgs) {
+  const report = await api.doctor({
+    profileDir: cliArgs['profile-dir'],
+    outputDir: cliArgs['output-dir'],
+  });
+  printJson(report);
+}
+
+async function assets(cliArgs) {
+  printJson(await api.assets({ run: cliArgs.run, frames: cliArgs.frames || 0 }));
+}
+
+async function prepare(cliArgs) {
+  printJson(api.prepare(cliArgs));
+}
+
+function template(cliArgs) {
+  printJson(api.template({ kind: cliArgs.kind, outputDir: cliArgs['output-dir'] }));
+}
+
+async function bootstrap(cliArgs) {
+  const outputDir = resolvePath(cliArgs['output-dir'], defaultRunsDir());
+  const run = createRun({ outputDir }, 'bootstrap');
+  const profileDir = resolvePath(cliArgs['profile-dir'], defaultProfileDir());
+  const result = baseResult('manual_action_required', run, {
+    command: 'bootstrap',
+    flowUrl: FLOW_URL,
+    profileDir,
+    manualActions: ['Log into Google Flow in the opened browser, then close it when finished.'],
+  });
+  const browser = await launchFlowBrowser({
+    profileDir,
+    downloadsDir: run.downloadsDir,
+    browserChannel: cliArgs['browser-channel'],
+    cdpUrl: cliArgs['cdp-url'],
+    headless: Boolean(cliArgs.headless),
+  });
+  try {
+    await openFlow(browser.page);
+    result.screenshots.push(await capture(browser.page, run, 'bootstrap-opened'));
+    Object.assign(result, await inspectFlowState(browser.page));
+    console.log(`[TakomiFlow] Browser opened for login/profile setup: ${FLOW_URL}`);
+    console.log('[TakomiFlow] Close the browser window when login/setup is complete.');
+    if (!browser.attached) await browser.context.waitForEvent('close', { timeout: 30 * 60 * 1000 }).catch(() => {});
+  } finally {
+    await closeFlowBrowser(browser);
+    saveResult(run, result);
+    console.log(`[TakomiFlow] Result: ${result.metadataPath}`);
+  }
+}
+
+async function smoke(cliArgs) {
+  const outputDir = resolvePath(cliArgs['output-dir'], defaultRunsDir());
+  const run = createRun({ outputDir }, 'smoke');
+  const profileDir = resolvePath(cliArgs['profile-dir'], defaultProfileDir());
+  const browser = await launchFlowBrowser({
+    profileDir,
+    downloadsDir: run.downloadsDir,
+    browserChannel: cliArgs['browser-channel'],
+    cdpUrl: cliArgs['cdp-url'],
+    headless: Boolean(cliArgs.headless),
+  });
+  const result = baseResult('ok', run, { command: 'smoke', flowUrl: FLOW_URL, profileDir });
+  try {
+    await openFlow(browser.page);
+    result.screenshots.push(await capture(browser.page, run, 'smoke-flow'));
+    const state = await inspectFlowState(browser.page);
+    Object.assign(result, state);
+    if (state.manualActions.length) result.status = 'manual_action_required';
+  } catch (error) {
+    result.status = 'failed';
+    result.errors.push(error.message);
+  } finally {
+    await closeFlowBrowser(browser);
+    saveResult(run, result);
+    printJson(result);
+  }
+}
+
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}

package/plugins/takomi-flow/scripts/lib/doctor.mjs

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { defaultProfileDir, defaultRunsDir, ensureDir, FLOW_URL } from './paths.mjs';
+import { loadPlaywright } from './playwright-loader.mjs';
+
+const execFileAsync = promisify(execFile);
+
+export async function runDoctor(options = {}) {
+  const profileDir = path.resolve(options.profileDir || defaultProfileDir());
+  const outputDir = path.resolve(options.outputDir || defaultRunsDir());
+  const checks = [];
+  checks.push({ name: 'node', status: 'ok', version: process.version });
+  checks.push(await checkPlaywright());
+  checks.push(await checkExecutable('ffmpeg', ['-version']));
+  checks.push(await checkExecutable('ffprobe', ['-version']));
+  checks.push(checkPath('profileDir', profileDir, false));
+  checks.push(checkPath('outputDir', outputDir, true));
+  const failed = checks.some(check => check.status === 'failed');
+  return {
+    schemaVersion: 1,
+    status: failed ? 'failed' : 'ok',
+    flowUrl: FLOW_URL,
+    profileDir,
+    outputDir,
+    checks,
+    recommendations: recommendations(checks),
+  };
+}
+
+async function checkPlaywright() {
+  try {
+    await loadPlaywright();
+    return { name: 'playwright', status: 'ok' };
+  } catch (error) {
+    return { name: 'playwright', status: 'failed', message: error.message };
+  }
+}
+
+async function checkExecutable(name, args) {
+  try {
+    const { stdout, stderr } = await execFileAsync(name, args, { timeout: 10000 });
+    const version = `${stdout || stderr}`.split(/\r?\n/).find(Boolean) || '';
+    return { name, status: 'ok', version };
+  } catch (error) {
+    return { name, status: 'warning', message: `${name} is unavailable: ${error.message}` };
+  }
+}
+
+function checkPath(name, targetPath, createIfMissing) {
+  if (fs.existsSync(targetPath)) {
+    return { name, status: 'ok', path: targetPath, exists: true };
+  }
+  if (createIfMissing) {
+    ensureDir(targetPath);
+    return { name, status: 'ok', path: targetPath, exists: true, created: true };
+  }
+  return {
+    name,
+    status: 'warning',
+    path: targetPath,
+    exists: false,
+    message: 'Profile does not exist yet. Run bootstrap to create it and log into Flow.',
+  };
+}
+
+function recommendations(checks) {
+  return checks
+    .filter(check => check.status !== 'ok')
+    .map(check => {
+      if (check.name === 'playwright') return 'Run pnpm install in the TakomiFlow plugin folder.';
+      if (check.name === 'ffmpeg' || check.name === 'ffprobe') return 'Install FFmpeg if media metadata or frame extraction is needed.';
+      if (check.name === 'profileDir') return 'Run bootstrap in headed mode and log into Google Flow manually.';
+      return check.message || `Review ${check.name}.`;
+    });
+}

package/plugins/takomi-flow/scripts/lib/examples.mjs

@@ -0,0 +1,17 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = path.resolve(MODULE_DIR, '..', '..');
+const EXAMPLES_PATH = path.join(PLUGIN_ROOT, 'assets', 'examples.json');
+
+export function loadExamples(name = undefined) {
+  const data = JSON.parse(fs.readFileSync(EXAMPLES_PATH, 'utf8'));
+  if (!name) return data;
+  const example = data.examples.find(item => item.name === name);
+  if (!example) {
+    throw new Error(`Unknown example "${name}". Available: ${data.examples.map(item => item.name).join(', ')}`);
+  }
+  return { schemaVersion: data.schemaVersion, example };
+}

package/plugins/takomi-flow/scripts/lib/flow-outcome.mjs

@@ -0,0 +1,90 @@
+import { hasText, openGeneratedMedia } from './flow-ui.mjs';
+
+export async function handleGenerationFollowups(page, request) {
+  if (await hasText(page, /which of these durations would you prefer/i)) {
+    await chooseDuration(page, request.durationSeconds || 4);
+    await page.waitForTimeout(2000);
+  }
+  if (await hasText(page, /costing\s+\d+\s+credits/i)) {
+    return clickApprove(page);
+  }
+  return false;
+}
+
+export async function waitForGenerationOutcome(page, request, options = {}) {
+  const timeoutMs = Number(options.timeoutMs || process.env.TAKOMI_FLOW_WAIT_MS || 300000);
+  const intervalMs = Number(options.intervalMs || process.env.TAKOMI_FLOW_POLL_MS || 5000);
+  const started = Date.now();
+  let approved = false;
+  while (Date.now() - started < timeoutMs) {
+    if (await hasText(page, /which of these durations would you prefer/i)) {
+      await chooseDuration(page, request.durationSeconds || 4);
+    }
+    if (await hasText(page, /costing\s+\d+\s+credits/i)) {
+      approved = await clickApprove(page) || approved;
+    }
+    if (await page.locator('button').filter({ hasText: /download\s*Download/i }).count().catch(() => 0)) {
+      return { status: 'download_ready', approved };
+    }
+    if (await page.locator('img[src*="media.getMediaUrlRedirect"], video').count().catch(() => 0)) {
+      await openGeneratedMedia(page);
+      return { status: 'media_ready', approved };
+    }
+    if (await hasVisibleText(page, /\b\d{1,3}%\b|generating|waiting in the queue|been scheduled/i)) {
+      await page.waitForTimeout(intervalMs);
+      continue;
+    }
+    if (await hasVisibleText(page, /failed|oops, something went wrong/i)) {
+      return { status: 'failed', approved };
+    }
+    await page.waitForTimeout(intervalMs);
+  }
+  return { status: 'timeout', approved };
+}
+
+async function hasVisibleText(page, pattern) {
+  return page.locator('body').evaluate((body, source) => {
+    const regex = new RegExp(source, 'i');
+    const isVisible = element => {
+      const style = window.getComputedStyle(element);
+      const rect = element.getBoundingClientRect();
+      return style.visibility !== 'hidden' && style.display !== 'none' && rect.width > 0 && rect.height > 0;
+    };
+    const walker = document.createTreeWalker(body, NodeFilter.SHOW_ELEMENT);
+    let node = walker.nextNode();
+    while (node) {
+      const visibleChildCount = [...node.children].filter(isVisible).length;
+      if (visibleChildCount === 0 && isVisible(node) && regex.test(node.innerText || node.textContent || '')) {
+        return true;
+      }
+      node = walker.nextNode();
+    }
+    return false;
+  }, pattern.source).catch(() => false);
+}
+
+async function chooseDuration(page, requested) {
+  const options = [4, 6, 8, 10];
+  const closest = options.reduce((best, item) => (
+    Math.abs(item - requested) < Math.abs(best - requested) ? item : best
+  ), options[0]);
+  const option = page.getByText(new RegExp(`^${closest} seconds$`, 'i')).first();
+  if (await option.count().catch(() => 0)) await option.click({ timeout: 10000 }).catch(() => {});
+}
+
+async function clickApprove(page) {
+  const candidates = [
+    page.getByText('Approve', { exact: true }).first(),
+    page.locator('div,button,[role="button"]').filter({ hasText: /^\s*check\s*Approve\s*$/i }).first(),
+    page.locator('text=Approve').first(),
+  ];
+  for (const locator of candidates) {
+    if (!(await locator.count().catch(() => 0))) continue;
+    try {
+      await locator.click({ timeout: 10000, force: true });
+      await page.waitForTimeout(1000);
+      return true;
+    } catch {}
+  }
+  return false;
+}

package/plugins/takomi-flow/scripts/lib/flow-ui.mjs

@@ -0,0 +1,165 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { FLOW_URL } from './paths.mjs';
+
+export async function openFlow(page) {
+  await page.goto(FLOW_URL, { waitUntil: 'domcontentloaded', timeout: 90000 });
+  await page.waitForLoadState('networkidle', { timeout: 30000 }).catch(() => {});
+}
+
+export async function capture(page, run, name) {
+  const filePath = path.join(run.screenshotsDir, `${name}.png`);
+  await page.screenshot({ path: filePath, fullPage: true }).catch(() => null);
+  return filePath;
+}
+
+export async function inspectFlowState(page) {
+  const title = await page.title().catch(() => '');
+  const url = page.url();
+  const text = (await page.locator('body').innerText({ timeout: 5000 }).catch(() => '')).slice(0, 5000);
+  const lower = text.toLowerCase();
+  const manualActions = [];
+  if (lower.includes('sign in') || lower.includes('log in')) {
+    manualActions.push('Sign into Google/Flow in the opened browser.');
+  }
+  if (lower.includes('captcha') || lower.includes('verify')) {
+    manualActions.push('Complete the verification challenge in the browser.');
+  }
+  if (lower.includes('quota') || lower.includes('limit') || lower.includes('credits')) {
+    manualActions.push('Review Flow quota or credits message in the browser.');
+  }
+  return { title, url, manualActions, textSample: text };
+}
+
+export async function ensureProjectEditor(page) {
+  if (page.url().includes('/project/')) return waitForProjectEditor(page);
+  const candidates = [
+    page.getByRole('button', { name: /new project/i }).first(),
+    page.locator('button').filter({ hasText: /new project/i }).first(),
+    page.getByText('New project').first(),
+  ];
+  for (const locator of candidates) {
+    if (!(await locator.count().catch(() => 0))) continue;
+    try {
+      await locator.click({ timeout: 10000 });
+      await page.waitForURL(/\/project\//, { timeout: 30000 }).catch(() => {});
+      await page.waitForLoadState('networkidle', { timeout: 30000 }).catch(() => {});
+      return page.url().includes('/project/') && await waitForProjectEditor(page);
+    } catch {}
+  }
+  return false;
+}
+
+async function waitForProjectEditor(page) {
+  await page.waitForLoadState('networkidle', { timeout: 30000 }).catch(() => {});
+  const ready = page.locator('body').filter({ hasText: /what do you want to create|start creating|add media/i });
+  await ready.waitFor({ state: 'visible', timeout: 60000 }).catch(() => {});
+  return (await page.locator('div[role="textbox"], textarea:not(.g-recaptcha-response)').count().catch(() => 0)) > 0;
+}
+
+export async function fillPrompt(page, prompt) {
+  const candidates = [
+    page.locator('div[role="textbox"]').filter({ hasText: /what do you want to create/i }).last(),
+    page.locator('div[role="textbox"]').last(),
+    page.locator('textarea:not(.g-recaptcha-response):not([name*="recaptcha"])').last(),
+  ];
+  for (const locator of candidates) {
+    if (!(await locator.count().catch(() => 0))) continue;
+    try {
+      await locator.click({ timeout: 8000 });
+      await page.keyboard.press(process.platform === 'darwin' ? 'Meta+A' : 'Control+A').catch(() => {});
+      await page.keyboard.type(prompt, { delay: 2 });
+      const matched = await page.locator('body').filter({ hasText: prompt.slice(0, 40) }).count().catch(() => 0);
+      if (matched) return true;
+    } catch {}
+  }
+  return false;
+}
+
+export async function submitGeneration(page) {
+  const preferred = [
+    page.locator('button').filter({ hasText: /arrow_forward\s*Create/i }).last(),
+    page.getByRole('button', { name: /^Create$/i }).last(),
+    page.locator('button').filter({ hasText: /^Create$/i }).last(),
+  ];
+  for (const button of preferred) {
+    if (!(await button.count().catch(() => 0))) continue;
+    try {
+      await button.click({ timeout: 8000 });
+      return true;
+    } catch {}
+  }
+  const labels = /submit|start/i;
+  const buttons = [
+    page.getByRole('button', { name: labels }).first(),
+    page.locator('button').filter({ hasText: labels }).first(),
+  ];
+  for (const button of buttons) {
+    if (!(await button.count().catch(() => 0))) continue;
+    try {
+      await button.click({ timeout: 8000 });
+      return true;
+    } catch {}
+  }
+  return false;
+}
+
+export async function tryDownloadAssets(page, run, maxDownloads = 1) {
+  const assets = [];
+  await openGeneratedMedia(page);
+  for (let i = 0; i < maxDownloads; i += 1) {
+    const button = page.locator('button').filter({ hasText: /download\s*Download|download/i }).first();
+    if (!(await button.count().catch(() => 0))) break;
+    const [completed] = await Promise.all([
+      page.waitForEvent('download', { timeout: 30000 }).catch(() => null),
+      button.click({ timeout: 5000 }).catch(() => null),
+    ]);
+    if (!completed) {
+      const imagePath = await downloadLargestRenderedImage(page, run, i).catch(() => null);
+      if (!imagePath) break;
+      assets.push(imagePath);
+      continue;
+    }
+    const suggested = completed.suggestedFilename();
+    const filePath = path.join(run.downloadsDir, suggested);
+    await completed.saveAs(filePath);
+    assets.push(filePath);
+  }
+  return assets;
+}
+
+async function downloadLargestRenderedImage(page, run, index) {
+  const images = await page.locator('img').evaluateAll(items => items
+    .map(img => ({ src: img.src, width: img.naturalWidth, height: img.naturalHeight }))
+    .filter(item => item.src && item.width >= 256 && item.height >= 256)
+    .sort((a, b) => (b.width * b.height) - (a.width * a.height)));
+  if (!images.length) return null;
+  const response = await page.context().request.get(images[0].src, { timeout: 30000 });
+  if (!response.ok()) return null;
+  const filePath = path.join(run.downloadsDir, `flow-image-${index + 1}.png`);
+  fs.writeFileSync(filePath, await response.body());
+  return filePath;
+}
+
+export async function openGeneratedMedia(page) {
+  if (await page.locator('button').filter({ hasText: /download\s*Download/i }).count().catch(() => 0)) return true;
+  const candidates = [
+    page.getByAltText(/video thumbnail|generated image/i).first(),
+    page.locator('img[src*="media.getMediaUrlRedirect"]').last(),
+    page.locator('[role="button"]').filter({ hasText: /play_circle/i }).first(),
+    page.locator('button').filter({ hasText: /play_circle/i }).first(),
+  ];
+  for (const locator of candidates) {
+    if (!(await locator.count().catch(() => 0))) continue;
+    try {
+      await locator.click({ timeout: 10000 });
+      await page.waitForTimeout(3000);
+      return true;
+    } catch {}
+  }
+  return false;
+}
+
+export async function hasText(page, pattern) {
+  return (await page.locator('body').filter({ hasText: pattern }).count().catch(() => 0)) > 0;
+}