zdymak 0.7.0 → 0.13.0

package/src/capture/web.mjs

@@ -0,0 +1,137 @@
+/**
+ * Web capture driver (Playwright) — the browser sibling of the iOS/Android drivers.
+ *
+ * A web app's "handle" for reaching a seeded screen is simply its URL, so `--states` here is a list of
+ * paths (or absolute URLs) rather than launch-arg ids:
+ *
+ *   zdymak capture --platform web --url http://localhost:3000 \
+ *     --states /,/today,/study --suffix -light --out marketing/web/captures
+ *
+ * Playwright is an OPTIONAL dependency: it pulls a browser binary (hundreds of MB), which nobody
+ * capturing only iOS/Android should pay for. It's imported lazily, with an install hint when absent.
+ *
+ * Marketing shots must be reproducible — a re-run should differ only where the UI did. So every page is
+ * loaded with animations disabled, `prefers-reduced-motion: reduce`, a fixed viewport + device scale
+ * factor, and the shot waits for fonts to finish loading (a webfont swapping in one frame late is the
+ * classic source of "why is this screenshot different").
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Lazily load Playwright, turning the module-not-found case into an actionable message. */
+async function loadPlaywright() {
+  try {
+    return await import('playwright');
+  } catch {
+    throw new Error(
+      'web capture needs Playwright (optional dependency — it downloads a browser).\n' +
+        '  npm i -D playwright && npx playwright install chromium',
+    );
+  }
+}
+
+/**
+ * `/` → `home`, `/today` → `today`, `/decks/new` → `decks-new`, `?a=1` dropped. Absolute URLs use their
+ * pathname. Keeps capture filenames stable and scene-id-shaped, so they line up with a `scenes` list.
+ */
+export function stateToName(state) {
+  const p = (state.includes('://') ? new URL(state).pathname : state.split('?')[0].split('#')[0])
+    .replace(/^\/+|\/+$/g, '')
+    .replace(/\.html?$/i, ''); // static exports (`/today.html`) get the same id as a routed `/today`
+  const name = p ? p.replace(/[/\\]+/g, '-').replace(/[^\w.-]+/g, '-') : 'home';
+  return name === 'index' ? 'home' : name; // `/index.html` is the landing page, same as `/`
+}
+
+/** Join a base URL with a state that may be a path or an absolute URL. */
+export function resolveUrl(base, state) {
+  if (state.includes('://')) return state;
+  if (!base) throw new Error(`web capture: --url is required to resolve the relative state "${state}".`);
+  return new URL(state, base).href;
+}
+
+const parseViewport = (v) => {
+  const m = /^(\d+)\s*[x×]\s*(\d+)$/i.exec(String(v || '').trim());
+  if (!m) throw new Error(`--viewport must look like 1280x800 (got "${v}").`);
+  return { width: Number(m[1]), height: Number(m[2]) };
+};
+
+export async function captureWeb(flags, { stripAlpha, sleep }) {
+  const { chromium, devices } = await loadPlaywright();
+
+  const outDir = path.resolve(flags.out || 'shots');
+  fs.mkdirSync(outDir, { recursive: true });
+  if (flags.clean) {
+    let cleared = 0;
+    for (const f of fs.readdirSync(outDir)) {
+      if (/\.png$/i.test(f)) { fs.rmSync(path.join(outDir, f), { force: true }); cleared++; }
+    }
+    console.log(`🧹 cleaned ${cleared} stale capture(s) in ${path.relative(process.cwd(), outDir) || outDir}`);
+  }
+
+  // A Playwright device descriptor (`--device "iPhone 15 Pro"`) brings its own viewport, scale factor and
+  // user agent — the honest way to shoot a mobile-web screen. Otherwise: an explicit desktop viewport.
+  const descriptor = flags.device ? devices[flags.device] : undefined;
+  if (flags.device && !descriptor) {
+    throw new Error(`--device "${flags.device}" is not a Playwright device. Try e.g. "iPhone 15 Pro", "Pixel 7", "iPad Pro 11".`);
+  }
+  const contextOptions = {
+    ...(descriptor || {
+      viewport: parseViewport(flags.viewport || '1280x800'),
+      deviceScaleFactor: Number(flags.dsf || 2), // 2 = retina-sharp; store shots get downscaled, never upscaled
+    }),
+    colorScheme: flags.theme === 'dark' ? 'dark' : 'light',
+    reducedMotion: 'reduce',
+    locale: flags.locale || undefined,
+  };
+
+  const browser = await chromium.launch();
+  const context = await browser.newContext(contextOptions);
+  // Kill CSS/SMIL animation and caret blink outright — `reducedMotion` is only a hint the app may ignore.
+  await context.addInitScript(() => {
+    const css = `*,*::before,*::after{animation-duration:0s!important;animation-delay:0s!important;
+      transition-duration:0s!important;transition-delay:0s!important;caret-color:transparent!important}`;
+    document.addEventListener('DOMContentLoaded', () => {
+      const s = document.createElement('style');
+      s.textContent = css;
+      document.head.appendChild(s);
+    });
+  });
+  const page = await context.newPage();
+
+  const settle = Number(flags.settle ?? 1);
+  const shoot = async (url, file) => {
+    await page.goto(url, { waitUntil: 'networkidle' });
+    if (flags.wait) await page.waitForSelector(String(flags.wait), { state: 'visible' });
+    // Webfonts + lazy images are the two things that land after `networkidle` and silently change a shot.
+    await page.evaluate(() => document.fonts?.ready);
+    await page.evaluate(() => Promise.all(
+      Array.from(document.images).filter((i) => !i.complete).map((i) => i.decode().catch(() => {})),
+    ));
+    if (settle) await sleep(settle * 1000);
+    await page.screenshot({ path: file, fullPage: !!flags['full-page'] });
+    await stripAlpha(file); // stores reject transparency
+  };
+
+  try {
+    const suffix = flags.suffix || '';
+    if (flags.states) {
+      const states = String(flags.states).split(',').map((s) => s.trim()).filter(Boolean);
+      const { width, height } = page.viewportSize() || {};
+      console.log(`▶︎ Capturing ${states.length} page(s) at ${width}×${height}${flags.device ? ` (${flags.device})` : ''}…`);
+      for (const state of states) {
+        const file = path.join(outDir, `${stateToName(state)}${suffix}.png`);
+        await shoot(resolveUrl(flags.url, state), file);
+        console.log(`   ✓ ${path.basename(file)}`);
+      }
+      console.log(`Done → ${outDir}`);
+    } else {
+      if (!flags.url) throw new Error('web capture needs --url <page> (plus --states for the full workflow).');
+      const file = path.join(outDir, `${flags.name || stateToName(flags.url)}${suffix}.png`);
+      await shoot(flags.url, file);
+      console.log(`✓ ${file}  (alpha stripped, store-ready)`);
+    }
+  } finally {
+    await context.close();
+    await browser.close();
+  }
+}

package/src/cli.mjs

@@ -1,165 +1,298 @@
-/**
- * zdymak CLI.
- *
- *   zdymak build       [--config <path>] [--out <dir>]   # EVERYTHING in the config: videos + screenshots
- *   zdymak video       [--config <path>] [--target <ids>] [--out <dir>]
- *   zdymak screenshots [--config <path>] [--out <dir>]   # per-device store screenshots
- *   zdymak specs                                          # print the store spec matrix
- *   zdymak capture --platform ios|android --name <screen> [--record] [--out <dir>]
- *   zdymak help
- */
-import path from 'node:path';
-import { registerFonts } from './fonts.mjs';
-import { loadConfig } from './config.mjs';
-import { buildVideo } from './video.mjs';
-import { buildReel } from './reel.mjs';
-import { buildPremium } from './premium.mjs';
-import { buildDeviceScreenshots } from './screenshots.mjs';
-import { VIDEO_TARGETS, IMAGE_TARGETS, videoTarget } from './specs.mjs';
-import { runCapture } from './capture/index.mjs';
-
-function parseFlags(argv) {
-  const flags = {};
-  const rest = [];
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a.startsWith('--')) {
-      const next = argv[i + 1];
-      // Boolean flag when followed by nothing or another --flag (e.g. `--build --project …`); else it
-      // takes the next token as its value. Single-dash values like `-marketingScreen` ARE values.
-      if (next === undefined || next.startsWith('--')) flags[a.slice(2)] = true;
-      else flags[a.slice(2)] = argv[++i];
-    } else {
-      rest.push(a);
-    }
-  }
-  return { flags, rest };
-}
-
-const DEFAULT_CONFIG = 'zdymak.config.mjs';
-
-async function open(flags) {
-  const cfg = await loadConfig(flags.config || DEFAULT_CONFIG);
-  registerFonts(cfg.brand.fontPaths);
-  const outDir = flags.out ? path.resolve(flags.out) : cfg.out;
-  return { cfg, outDir };
-}
-
-/** Build one video target (optionally at an overridden device size / scene set / theme). */
-async function buildVideoTarget({ id, scenes, brand, cfg, outFile, size, theme }) {
-  const base = videoTarget(id);
-  const spec = size ? { ...base, w: size[0], h: size[1] } : base;
-  const build = spec.style === 'reel' ? buildReel : spec.style === 'premium' ? buildPremium : buildVideo;
-  const tag = spec.style ? `, ${spec.style}` : '';
-  process.stdout.write(`  • ${id} (${spec.w}×${spec.h}${tag}${cfg.music ? ', ♪' : ''}) … `);
-  const { totalDur, warnings } = await build({
-    scenes, spec, brand, outFile,
-    sceneDur: cfg.sceneDur, xfade: cfg.xfade, timing: cfg.timing,
-    theme: theme ?? cfg.theme, music: cfg.music,
-  });
-  console.log(`${totalDur.toFixed(1)}s → ${path.relative(process.cwd(), outFile)}`);
-  for (const w of warnings) console.warn(`    ⚠︎ ${w}`);
-}
-
-async function cmdVideo(flags) {
-  const { cfg, outDir } = await open(flags);
-  const targets = flags.target ? flags.target.split(',').map((s) => s.trim()) : cfg.targets;
-  console.log(`zdymak video • ${cfg.scenes.length} scenes → ${targets.join(', ')}`);
-  for (const id of targets) {
-    await buildVideoTarget({ id, scenes: cfg.scenes, brand: cfg.brand, cfg, outFile: path.join(outDir, `${id}.mp4`) });
-  }
-  console.log('Done.');
-}
-
-async function cmdScreenshots(flags) {
-  const { cfg, outDir } = await open(flags);
-  if (!cfg.devices.length) {
-    console.warn('No `devices` in the config — nothing to screenshot. (See README: devices map.)');
-    return;
-  }
-  console.log(`zdymak screenshots • ${cfg.devices.length} device group(s)`);
-  for (const device of cfg.devices) {
-    const written = await buildDeviceScreenshots({ device, brand: cfg.brand, theme: device.theme ?? cfg.stillTheme ?? cfg.theme, outDir });
-    console.log(`  • ${device.name}: ${written.length} shot(s)${written[0] ? ` (${written[0].W}×${written[0].H}…)` : ' — no captures found, skipped'}`);
-  }
-  console.log('Done.');
-}
-
-async function cmdBuild(flags) {
-  const { cfg, outDir } = await open(flags);
-  // 1) shared (phone) video targets from the top-level scenes
-  if (cfg.targets.length && cfg.scenes.length) {
-    console.log('zdymak build • videos');
-    for (const id of cfg.targets) {
-      await buildVideoTarget({ id, scenes: cfg.scenes, brand: cfg.brand, cfg, outFile: path.join(outDir, `${id}.mp4`) });
-    }
-  }
-  // 2) per-device videos + screenshots
-  for (const device of cfg.devices) {
-    if (device.videos.length) {
-      console.log(`zdymak build • ${device.name} videos`);
-      for (const v of device.videos) {
-        await buildVideoTarget({ id: v.target, scenes: device.scenes, brand: cfg.brand, cfg, size: v.size, theme: device.theme, outFile: path.join(outDir, `${device.name}-${v.target}.mp4`) });
-      }
-    }
-    if (device.screenshots.length) {
-      const written = await buildDeviceScreenshots({ device, brand: cfg.brand, theme: device.theme ?? cfg.stillTheme ?? cfg.theme, outDir });
-      console.log(`  • ${device.name} screenshots: ${written.length}${written.length ? '' : ' — no captures found, skipped'}`);
-    }
-  }
-  console.log('Done.');
-}
-
-function cmdSpecs() {
-  console.log('\nVIDEO targets (produce an .mp4):');
-  for (const [id, s] of Object.entries(VIDEO_TARGETS)) {
-    const dur = s.minSec ? `${s.minSec}–${s.maxSec}s` : 'any length';
-    console.log(`  ${id.padEnd(20)} ${s.w}×${s.h} @${s.fps}  H.264 ${s.profile}@${s.level}  ${dur}  — ${s.store}`);
-  }
-  console.log('\nIMAGE targets (store screenshots — `zdymak screenshots` / `build`):');
-  for (const [id, s] of Object.entries(IMAGE_TARGETS)) {
-    const dim = s.accepts ? s.accepts.map((a) => a.join('×')).join(' | ') : `${s.w}×${s.h}`;
-    console.log(`  ${id.padEnd(24)} ${dim}${s.alpha === false ? '  (no alpha)' : ''}  — ${s.store}`);
-  }
-  console.log('');
-}
-
-function cmdHelp() {
-  console.log(`zdymak — premium App Store, Google Play & social videos + screenshots, from your captures
-
-Usage:
-  zdymak build       [--config <path>] [--out <dir>]   # everything: videos + per-device screenshots
-  zdymak video       [--config <path>] [--target <ids>] [--out <dir>]
-  zdymak screenshots [--config <path>] [--out <dir>]
-  zdymak specs
-  zdymak capture  --platform ios --bundle <id> --arg <handle> --states <a,b,c> [--suffix -light]
-                  [--build --project <.xcodeproj> --scheme <name>] [--device <sim>] [--out <dir>]
-                  # full workflow: start the app, drive each screen by a launch handle, snap store-ready PNGs
-  zdymak capture  --platform ios|android --name <screen>          # single snapshot of the booted device
-  zdymak help
-
-Defaults: --config ${DEFAULT_CONFIG}. Needs ffmpeg on PATH (or $FFMPEG).
-README.md documents the config (brand, scenes, targets, theme, music, devices); SKILL.md is for agents.`);
-}
-
-export async function run(argv = process.argv.slice(2)) {
-  const [cmd, ...rest0] = argv;
-  const { flags, rest } = parseFlags(rest0);
-  try {
-    switch (cmd) {
-      case 'build': await cmdBuild(flags); break;
-      case 'video': await cmdVideo(flags); break;
-      case 'screenshots': await cmdScreenshots(flags); break;
-      case 'specs': cmdSpecs(); break;
-      case 'capture': await runCapture(flags, rest); break;
-      case 'help': case undefined: case '--help': case '-h': cmdHelp(); break;
-      default:
-        console.error(`Unknown command "${cmd}".\n`);
-        cmdHelp();
-        process.exitCode = 1;
-    }
-  } catch (e) {
-    console.error(`\n✗ ${e.message}`);
-    process.exitCode = 1;
-  }
-}
+/**
+ * zdymak CLI.
+ *
+ *   zdymak build       [--config <path>] [--out <dir>] [--locale <ids>]  # EVERYTHING: videos + screenshots
+ *   zdymak video       [--config <path>] [--target <ids>] [--out <dir>]
+ *   zdymak screenshots [--config <path>] [--out <dir>] [--locale <ids>]  # per-device store screenshots
+ *   zdymak specs                                          # print the store spec matrix
+ *   zdymak capture --platform ios|android --name <screen> [--record] [--out <dir>]
+ *   zdymak help
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import { registerFonts } from './fonts.mjs';
+import { loadConfig } from './config.mjs';
+import { buildVideo } from './video.mjs';
+import { buildReel } from './reel.mjs';
+import { buildPremium } from './premium.mjs';
+import { buildMontage } from './montage.mjs';
+import { buildDeviceScreenshots, localizeScenes, localizeBrand, untranslatedScenes } from './screenshots.mjs';
+import { VIDEO_TARGETS, IMAGE_TARGETS, videoTarget } from './specs.mjs';
+import { runCapture } from './capture/index.mjs';
+import { resolveVideo, paletteAt } from './destinations.mjs';
+import { validateVideo, validateImage } from './validate.mjs';
+
+function parseFlags(argv) {
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const next = argv[i + 1];
+      // Boolean flag when followed by nothing or another --flag (e.g. `--build --project …`); else it
+      // takes the next token as its value. Single-dash values like `-marketingScreen` ARE values.
+      if (next === undefined || next.startsWith('--')) flags[a.slice(2)] = true;
+      else flags[a.slice(2)] = argv[++i];
+    } else {
+      rest.push(a);
+    }
+  }
+  return { flags, rest };
+}
+
+const DEFAULT_CONFIG = 'zdymak.config.mjs';
+
+async function open(flags) {
+  const cfg = await loadConfig(flags.config || DEFAULT_CONFIG);
+  registerFonts(cfg.brand.fontPaths);
+  const outDir = flags.out ? path.resolve(flags.out) : cfg.out;
+  // --clean wipes the output folder first, so a run can't leave stale assets from a removed target/scene
+  // behind (every screenshot/video in the folder is then freshly produced by THIS run).
+  if (flags.clean && fs.existsSync(outDir)) {
+    fs.rmSync(outDir, { recursive: true, force: true });
+    console.log(`🧹 cleaned ${path.relative(process.cwd(), outDir) || outDir}`);
+  }
+  return { cfg, outDir };
+}
+
+/** Warn when the audio expectation and the config disagree: a video/reel that should carry a music score
+ *  has none (Apple recommends a single score for continuity), or `music` is set where nothing consumes it. */
+function warnAudio({ videoCount, hasMusic, label, silentByDesign }) {
+  // Never nag about a Play promo: our own guidance is to keep it silent unless the track is cleared,
+  // because a ContentID claim can force ads onto a listing video, which Play forbids.
+  if (silentByDesign) return;
+  if (videoCount > 0 && !hasMusic) {
+    console.warn(`⚠︎ audio: ${label} ${videoCount === 1 ? 'plays' : 'play'} SILENT — no music. Apple recommends a single music score for continuity; set \`music.path\`.`);
+  }
+  if (videoCount === 0 && hasMusic) {
+    console.warn('⚠︎ audio: `music.path` is set but this run builds no video/reel — the audio is ignored (screenshots have no sound).');
+  }
+}
+
+/**
+ * Build one video. `entry` is either the `{ target }` shorthand or the split
+ * `{ destination, preset, transitions, effects }` form — DESTINATION decides what's accepted, PRESET
+ * decides how it looks, and a `transitions`/`effects` list lets the caller supply its own vocabulary
+ * instead of the preset's defaults.
+ */
+async function buildVideoTarget({ entry, scenes, brand, cfg, outFile, size, theme, flags }) {
+  const r = resolveVideo(entry);
+  const base = r.destination;
+  const useSize = size || r.size;
+  const spec = useSize ? { ...base, w: useSize[0], h: useSize[1] } : base;
+  const build = r.engine === 'reel' ? buildReel : r.engine === 'premium' ? buildPremium : buildVideo;
+  const id = r.id;
+  // A caller-supplied palette overrides the per-scene default for scenes that don't name their own.
+  if (r.transitions || r.effects) {
+    scenes = scenes.map((sc, i) => ({
+      ...sc,
+      cut: sc.cut ?? paletteAt(r.transitions, i, undefined),
+      effect: sc.effect ?? paletteAt(r.effects, i, undefined),
+    }));
+  }
+  const tag = r.preset !== 'full-bleed' ? `, ${r.preset}` : '';
+  process.stdout.write(`  • ${id} (${spec.w}×${spec.h}${tag}${cfg.music ? ', ♪' : ''}) … `);
+  const { totalDur, warnings } = await build({
+    scenes, spec, brand, outFile,
+    sceneDur: cfg.sceneDur, xfade: cfg.xfade, timing: cfg.timing,
+    theme: theme ?? cfg.theme, music: cfg.music,
+  });
+  console.log(`${totalDur.toFixed(1)}s → ${path.relative(process.cwd(), outFile)}`);
+  for (const w of warnings) console.warn(`    ⚠︎ ${w}`);
+  // Measure the artefact, don't trust the intent: a renderer or encoder bug is caught here.
+  validateVideo({ file: outFile, destination: base, size: useSize, force: !!flags?.force });
+}
+
+async function cmdVideo(flags) {
+  const { cfg, outDir } = await open(flags);
+  const targets = flags.target ? flags.target.split(',').map((s) => s.trim()) : cfg.targets;
+  console.log(`zdymak video • ${cfg.scenes.length} scenes → ${targets.join(', ')}`);
+  for (const id of targets) {
+    await buildVideoTarget({ id, scenes: cfg.scenes, brand: cfg.brand, cfg, outFile: path.join(outDir, `${id}.mp4`) });
+  }
+  warnAudio({ videoCount: targets.length, hasMusic: !!cfg.music, label: 'videos' });
+  console.log('Done.');
+}
+
+async function cmdReel(flags) {
+  const { cfg, outDir } = await open(flags);
+  const reel = cfg.reel;
+  if (!reel?.segments?.length) {
+    console.warn('No `reel.segments` in the config — nothing to build. (See README: live-footage reel.)');
+    return;
+  }
+  const [w, h] = reel.size || [1080, 1920];
+  const spec = { w, h, fps: reel.fps || 30, profile: reel.profile || 'high', level: reel.level || '4.1' };
+  const outFile = path.join(outDir, `${flags.name || 'reel'}.mp4`);
+  fs.mkdirSync(outDir, { recursive: true });
+  console.log(`zdymak reel • ${reel.segments.length} segment(s) → ${w}×${h}${reel.music ? ', ♪' : ''}`);
+  const { totalDur } = await buildMontage({
+    segments: reel.segments, brand: cfg.brand, theme: reel.theme, spec, // reel theme (light default), NOT cfg.theme
+    music: reel.music, sceneDur: reel.sceneDur, bpm: reel.bpm, beatsPerCut: reel.beatsPerCut,
+    transition: reel.transition, xfadeDur: reel.xfadeDur, outFile,
+  });
+  console.log(`  ✓ ${totalDur.toFixed(1)}s → ${path.relative(process.cwd(), outFile)}`);
+  warnAudio({ videoCount: 1, hasMusic: !!reel.music, label: 'the reel' });
+  console.log('Done.');
+}
+
+/**
+ * Which locales to render, from `captions` + an optional `--locale de,fr` filter. An unknown locale is an
+ * error, not a silent no-op — a typo'd locale would otherwise look like a successful run that shipped
+ * nothing.
+ */
+function localesFor(cfg, flags) {
+  const configured = Object.keys(cfg.captions || {});
+  if (!flags.locale) return configured;
+  const wanted = String(flags.locale).split(',').map((s) => s.trim()).filter(Boolean);
+  const unknown = wanted.filter((l) => !configured.includes(l));
+  if (unknown.length) {
+    throw new Error(
+      `--locale: no captions configured for ${unknown.join(', ')}. ` +
+        (configured.length ? `Configured: ${configured.join(', ')}.` : 'The config has no `captions` block.'),
+    );
+  }
+  return wanted;
+}
+
+/**
+ * Per-locale screenshot sets → `<out>/<locale>/<target>/…`, leaving the base (source-language) set where
+ * it already is. Screenshots only: stores take localized stills far more often than localized previews,
+ * and re-encoding every video per locale costs minutes each.
+ */
+async function buildLocalizedScreenshots({ cfg, outDir, flags }) {
+  for (const locale of localesFor(cfg, flags)) {
+    const table = cfg.captions[locale];
+    console.log(`zdymak • ${locale} screenshots`);
+    const fellBack = new Set();
+    for (const device of cfg.devices) {
+      if (!device.screenshots.length) continue;
+      untranslatedScenes(device.scenes, table).forEach((id) => fellBack.add(id));
+      const written = await buildDeviceScreenshots({
+        device: { ...device, scenes: localizeScenes(device.scenes, table) },
+        brand: localizeBrand(cfg.brand, table),
+        theme: device.theme ?? cfg.stillTheme ?? cfg.theme,
+        outDir: path.join(outDir, locale),
+        force: !!flags.force,
+      });
+      console.log(`  • ${device.name}: ${written.length}${written.length ? '' : ' — no captures found, skipped'}`);
+    }
+    if (fellBack.size) {
+      console.log(`    ↳ ${fellBack.size} scene(s) kept the base caption (no ${locale} translation): ${[...fellBack].join(', ')}`);
+    }
+  }
+}
+
+async function cmdScreenshots(flags) {
+  const { cfg, outDir } = await open(flags);
+  if (!cfg.devices.length) {
+    console.warn('No `devices` in the config — nothing to screenshot. (See README: devices map.)');
+    return;
+  }
+  console.log(`zdymak screenshots • ${cfg.devices.length} device group(s)`);
+  for (const device of cfg.devices) {
+    const written = await buildDeviceScreenshots({ device, brand: cfg.brand, theme: device.theme ?? cfg.stillTheme ?? cfg.theme, outDir, force: !!flags.force });
+    console.log(`  • ${device.name}: ${written.length} shot(s)${written[0] ? ` (${written[0].W}×${written[0].H}…)` : ' — no captures found, skipped'}`);
+  }
+  await buildLocalizedScreenshots({ cfg, outDir, flags });
+  warnAudio({ videoCount: 0, hasMusic: !!cfg.music, label: 'screenshots' });
+  console.log('Done.');
+}
+
+async function cmdBuild(flags) {
+  const { cfg, outDir } = await open(flags);
+  // 1) shared (phone) video targets from the top-level scenes
+  if (cfg.targets.length && cfg.scenes.length) {
+    console.log('zdymak build • videos');
+    for (const id of cfg.targets) {
+      await buildVideoTarget({ entry: id, scenes: cfg.scenes, brand: cfg.brand, cfg, outFile: path.join(outDir, `${id}.mp4`), flags });
+    }
+  }
+  // 2) per-device videos + screenshots
+  let deviceVideos = 0;
+  for (const device of cfg.devices) {
+    // A device the app doesn't ship (or hasn't captured yet) skips cleanly — same contract as its
+    // screenshots. Without this, one uncaptured device aborts the whole build for every other one.
+    const captured = device.scenes.filter((s) => fs.existsSync(s.image));
+    if (device.videos.length) {
+      if (!captured.length) {
+        console.log(`  • ${device.name} videos: skipped — no captures found`);
+      } else {
+        console.log(`zdymak build • ${device.name} videos`);
+        for (const v of device.videos) {
+          const vid = resolveVideo(v);
+          await buildVideoTarget({ entry: v, scenes: captured, brand: cfg.brand, cfg, size: v.size, theme: v.theme ?? device.theme, outFile: path.join(outDir, `${device.name}-${vid.id}.mp4`), flags });
+          deviceVideos++;
+        }
+      }
+    }
+    if (device.screenshots.length) {
+      const written = await buildDeviceScreenshots({ device, brand: cfg.brand, theme: device.theme ?? cfg.stillTheme ?? cfg.theme, outDir, force: !!flags.force });
+      console.log(`  • ${device.name} screenshots: ${written.length}${written.length ? '' : ' — no captures found, skipped'}`);
+    }
+  }
+  // 3) localized screenshot sets (base set already written above)
+  await buildLocalizedScreenshots({ cfg, outDir, flags });
+
+  const videoCount = (cfg.targets.length && cfg.scenes.length ? cfg.targets.length : 0) + deviceVideos;
+  warnAudio({ videoCount, hasMusic: !!cfg.music, label: 'videos' });
+  console.log('Done.');
+}
+
+function cmdSpecs() {
+  console.log('\nVIDEO targets (produce an .mp4):');
+  for (const [id, s] of Object.entries(VIDEO_TARGETS)) {
+    const dur = s.minSec ? `${s.minSec}–${s.maxSec}s` : 'any length';
+    console.log(`  ${id.padEnd(20)} ${s.w}×${s.h} @${s.fps}  H.264 ${s.profile}@${s.level}  ${dur}  — ${s.store}`);
+  }
+  console.log('\nIMAGE targets (store screenshots — `zdymak screenshots` / `build`):');
+  for (const [id, s] of Object.entries(IMAGE_TARGETS)) {
+    const dim = s.accepts ? s.accepts.map((a) => a.join('×')).join(' | ') : `${s.w}×${s.h}`;
+    console.log(`  ${id.padEnd(24)} ${dim}${s.alpha === false ? '  (no alpha)' : ''}  — ${s.store}`);
+  }
+  console.log('');
+}
+
+function cmdHelp() {
+  console.log(`zdymak — premium App Store, Google Play & social videos + screenshots, from your captures
+
+Usage:
+  zdymak build       [--config <path>] [--out <dir>] [--clean] [--locale <ids>] [--force]  # everything
+  zdymak video       [--config <path>] [--target <ids>] [--out <dir>] [--clean]
+  zdymak reel        [--config <path>] [--out <dir>] [--clean]   # LIVE-FOOTAGE montage from clips/images
+  zdymak screenshots [--config <path>] [--out <dir>] [--clean] [--locale <ids>]
+  zdymak specs
+  zdymak capture  --platform ios --bundle <id> --arg <handle> --states <a,b,c> [--suffix -light]
+                  [--build --project <.xcodeproj> --scheme <name>] [--device <sim>] [--out <dir>] [--clean] [--keep]
+                  # full workflow: start the app, drive each screen by a launch handle, snap store-ready PNGs
+  zdymak capture  --platform ios|android --name <screen>          # single snapshot of the booted device
+  zdymak help
+
+Defaults: --config ${DEFAULT_CONFIG}. Needs ffmpeg on PATH (or $FFMPEG).
+--clean: wipe the output folder first (capture clears stale PNGs but keeps the .dd build cache) — so the
+folder ends up holding ONLY this run's assets, never a stale screenshot from a removed target/scene.
+README.md documents the config (brand, scenes, targets, theme, music, devices); SKILL.md is for agents.`);
+}
+
+export async function run(argv = process.argv.slice(2)) {
+  const [cmd, ...rest0] = argv;
+  const { flags, rest } = parseFlags(rest0);
+  try {
+    switch (cmd) {
+      case 'build': await cmdBuild(flags); break;
+      case 'video': await cmdVideo(flags); break;
+      case 'reel': await cmdReel(flags); break;
+      case 'screenshots': await cmdScreenshots(flags); break;
+      case 'specs': cmdSpecs(); break;
+      case 'capture': await runCapture(flags, rest); break;
+      case 'help': case undefined: case '--help': case '-h': cmdHelp(); break;
+      default:
+        console.error(`Unknown command "${cmd}".\n`);
+        cmdHelp();
+        process.exitCode = 1;
+    }
+  } catch (e) {
+    console.error(`\n✗ ${e.message}`);
+    process.exitCode = 1;
+  }
+}