capture-flow 0.0.0-stage → 0.1.1

package/skills/capture-flow/references/capture-recipes.md

@@ -0,0 +1,155 @@
+# Capture recipes
+
+`capture-flow` never takes screenshots itself. Each flow step is a shell command, so
+use whatever produces correct native-resolution images.
+
+Before building, check every raw capture:
+
+```bash
+magick identify -format '%f %wx%h %[channels]\n' captures/*.png
+# macOS without ImageMagick:
+sips -g pixelWidth -g pixelHeight captures/iphone-01.png
+```
+
+The output must be opaque (no alpha). Flatten if needed:
+
+```bash
+magick in.png -background '#000000' -alpha remove -alpha off out.png
+```
+
+## Web app with Playwright
+
+Install Playwright outside the project if you do not want it in dependencies:
+
+```bash
+npm install --prefix /tmp/pw playwright
+PLAYWRIGHT_BROWSERS_PATH=/tmp/pw npx --prefix /tmp/pw playwright install chromium
+```
+
+`capture.mjs`:
+
+```js
+import { chromium } from 'playwright';
+
+const browser = await chromium.launch();
+const context = await browser.newContext({
+  viewport: { width: 440, height: 956 },
+  deviceScaleFactor: 3,          // 440×956 → 1320×2868
+  isMobile: true,
+  hasTouch: true,
+  locale: 'ar-SA',
+  timezoneId: 'Asia/Riyadh',
+  colorScheme: 'dark',
+  serviceWorkers: 'block',       // stale caches hide new UI
+});
+const page = await context.newPage();
+
+// Seed settings before the app boots (consent, theme, onboarding).
+await context.addInitScript(() => {
+  localStorage.setItem('app:telemetry', 'off');
+  localStorage.setItem('app:onboarded', 'true');
+});
+
+await page.goto('https://example.com', { waitUntil: 'commit', timeout: 120_000 });
+await page.getByRole('button', { name: 'تشغيل' }).waitFor({ timeout: 120_000 });
+await page.waitForTimeout(700);  // let fonts, audio state, and animation settle
+
+await page.screenshot({ path: 'captures/iphone-01.png' });
+await browser.close();
+```
+
+Rules of thumb:
+
+- `waitUntil: 'commit'` plus an explicit UI wait beats `networkidle` on hydrated apps.
+- Hydration on a cold CDN can take 20 s. Give `waitFor` a real timeout.
+- Take one browser context per family, or resize the viewport and repeat.
+- Keep `omitBackground` off; transparency fails `verify`.
+- If a consent dialog appears, dismiss it once with a real click **and** seed the
+  setting, so retries stay clean.
+- For audio/video states, start playback and wait for the visible time counter to move.
+
+### When the app depends on a service worker or peer transport
+
+If playback in the browser uses a transport the headless run cannot provide (WebTorrent,
+WebRTC), point the request at a local/web seed instead of screenshotting an empty player:
+
+```js
+await context.route('**/webtorrent/**', async (route) => {
+  const url = new URL(route.request().url());
+  await route.continue({ url: url.toString().replace('/webtorrent/', '/media/') });
+});
+```
+
+Document the fallback in the capture script so the next person knows why it exists.
+
+## iOS Simulator
+
+```bash
+xcrun simctl boot "iPhone 17 Pro Max" 2>/dev/null || true
+xcrun simctl bootstatus booted -b
+
+# Deterministic status bar.
+xcrun simctl status_bar booted override \
+  --time "9:41" --batteryState charged --batteryLevel 100 \
+  --wifiBars 3 --cellularBars 4
+
+# Drive the app: deep link, Maestro, or XCTest.
+xcrun simctl openurl booted "myapp://player"
+
+xcrun simctl io booted screenshot captures/iphone-01.png
+xcrun simctl status_bar booted clear
+```
+
+`simctl io screenshot` captures at the simulated device's native pixel size. Pick a
+device whose native resolution matches the size you export (iPhone 17 Pro Max →
+1320 × 2868). For iPad, boot an iPad Pro 13″ simulator.
+
+## Android emulator or device
+
+```bash
+adb shell screencap -p /sdcard/shot.png
+adb pull /sdcard/shot.png captures/android-01.png
+# or, without a temp file:
+adb exec-out screencap -p > captures/android-01.png
+```
+
+Deterministic status bar:
+
+```bash
+adb shell settings put global sysui_demo_allowed 1
+adb shell am broadcast -a com.android.systemui.demo -e command enter
+adb shell am broadcast -a com.android.systemui.demo -e command clock -e hhmm 0941
+adb shell am broadcast -a com.android.systemui.demo -e command battery -e level 100 -e plugged false
+adb shell am broadcast -a com.android.systemui.demo -e command network -e wifi show -e level 4
+```
+
+Use an emulator profile with the right resolution (1080 × 2400 for a modern phone,
+1600 × 2560 for a 10-inch tablet in landscape) and set the locale:
+
+```bash
+adb shell "setprop persist.sys.locale ar-SA; setprop persist.sys.language ar; setprop persist.sys.country SA"
+adb shell am force-stop com.example.app
+```
+
+## Maestro
+
+```yaml
+appId: com.example.app
+---
+- launchApp:
+    clearState: false
+- tapOn: "Get started"
+- takeScreenshot: captures/android-01
+```
+
+`takeScreenshot` writes `<name>.png` in the working directory of the Maestro run.
+
+## Native app deep links
+
+Prefer a deep link or launch argument over scripted tapping: it is stable across UI
+changes and skips onboarding.
+
+```bash
+xcrun simctl openurl booted "myapp://track/123?autoplay=1"
+adb shell am start -a android.intent.action.VIEW -d "myapp://track/123?autoplay=1" com.example.app
+```

package/skills/capture-flow/references/store-sizes.md

@@ -0,0 +1,91 @@
+# Store sizes
+
+Pixel sizes exported by `capture-flow build`. `default` means the size is produced
+when `sizes` is omitted and the family has a capture. `required` marks the size the
+store currently requires.
+
+## App Store — iPhone
+
+| id | pixels | devices | default | required |
+| --- | --- | --- | --- | --- |
+| `ios-6.9` | 1320 × 2868 | iPhone 17 Pro Max, 16 Pro Max | yes | yes |
+| `ios-6.9-b` | 1290 × 2796 | iPhone 16 Plus, 15 Pro Max, 15 Plus, 14 Pro Max | no | no |
+| `ios-6.5` | 1284 × 2778 | iPhone 14 Plus, 13 Pro Max, 12 Pro Max | no | no |
+| `ios-6.5-b` | 1242 × 2688 | iPhone 11 Pro Max, XS Max | no | no |
+| `ios-6.3` | 1206 × 2622 | iPhone 17 Pro, 17, 16 Pro | yes | yes |
+| `ios-6.1` | 1170 × 2532 | iPhone 17e, 16e, 14, 13, 13 Pro, 12, 12 Pro | no | no |
+
+## App Store — iPad
+
+| id | pixels | devices | default | required |
+| --- | --- | --- | --- | --- |
+| `ipad-13` | 2064 × 2752 | iPad Pro 13″ (M4, M5), iPad Air 13″ | yes | yes |
+| `ipad-12.9` | 2048 × 2732 | iPad Pro 12.9″ (2nd–6th gen) | no | no |
+| `ipad-11` | 1668 × 2420 | iPad Pro 11″ (M4), iPad Air 11″ | no | no |
+
+## Google Play — phone
+
+| id | pixels | devices | default | required |
+| --- | --- | --- | --- | --- |
+| `play-phone` | 1080 × 1920 | all Android phones (9:16) | yes | yes |
+| `play-phone-hd` | 1440 × 2560 | all Android phones (9:16, high resolution) | no | no |
+
+## Google Play — tablet
+
+| id | pixels | devices | default | required |
+| --- | --- | --- | --- | --- |
+| `play-tablet-7` | 1080 × 1920 | 7-inch Android tablets | yes | no |
+| `play-tablet-10` | 1440 × 2560 | 10-inch Android tablets | yes | no |
+
+## App Store — Mac
+
+| id | pixels | default | required |
+| --- | --- | --- | --- |
+| `mac-2880` | 2880 × 1800 | yes | yes |
+| `mac-2560` | 2560 × 1600 | no | no |
+| `mac-1440` | 1440 × 900 | no | no |
+| `mac-1280` | 1280 × 800 | no | no |
+
+## Apple Watch
+
+| id | pixels | default | required |
+| --- | --- | --- | --- |
+| `watch-ultra-3` | 422 × 514 | yes | yes |
+| `watch-11` | 416 × 496 | no | no |
+| `watch-ultra-2` | 410 × 502 | no | no |
+| `watch-9` | 396 × 484 | no | no |
+| `watch-6` | 368 × 448 | no | no |
+| `watch-3` | 312 × 390 | no | no |
+
+## Apple TV and Vision Pro
+
+| id | pixels | default | required |
+| --- | --- | --- | --- |
+| `tv-4k` | 3840 × 2160 | yes | yes |
+| `tv-hd` | 1920 × 1080 | no | no |
+| `vision-pro` | 3840 × 2160 | yes | yes |
+
+## Google Play feature graphic
+
+| id | pixels | default | required |
+| --- | --- | --- | --- |
+| `play-feature` | 1024 × 500 | yes | yes |
+
+## Landscape
+
+Append `-land` and swap width and height. Supported for `iphone*`, `ipad*`, and
+`play-phone*` sizes (for example `ios-6.9-land` = 2868 × 1320). Use the matching
+`*-landscape` family with the capture taken in landscape.
+
+## Capture aspect ratios
+
+The device screen area uses these ratios. Match them to avoid cropping:
+
+| Family | Screen aspect (w:h) | Notes |
+| --- | --- | --- |
+| `iphone` | 1320:2868 | 19.5:9, capture at 1320 × 2868 |
+| `ipad` | 3:4 | 2064 × 2752 |
+| `android-phone` | 20:9 | 1080 × 2400 or 1080 × 1920; 9:16 export crops top/bottom |
+| `android-tablet` | 16:10 | 1600 × 2560 |
+| `mac` | 16:10 | 2880 × 1800 |
+| `watch` | 422:514 | — |

package/src/build.ts

@@ -0,0 +1,186 @@
+/**
+ * capture-flow build: manifest + captures -> exact store screenshots.
+ */
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import type { AssetInfo, FamilyId, LangCode, Project } from '../vendor/wajha/model/types';
+import type { ImageLike } from '../vendor/wajha/engine/types';
+import { FAMILIES, FAMILY_ORDER, sizeById } from '../vendor/wajha/model/catalog';
+import { projectFromTemplate } from '../vendor/wajha/model/instantiate';
+import { registerBundledFonts } from '../vendor/wajha/engine/testing/canvasNode';
+import { BUILTIN_TEMPLATES } from '../vendor/wajha/templates';
+import { exportPath } from '../vendor/wajha/export/paths';
+import type { ShotManifest } from './manifest';
+import { parseManifest } from './manifest';
+import { loadCapture, renderSlidePng } from './render';
+
+export interface BuildOptions {
+  manifestPath: string;
+  outDir?: string;
+  log?: (line: string) => void;
+}
+
+export interface BuildReport {
+  outDir: string;
+  files: { path: string; width: number; height: number; family: FamilyId; lang: LangCode; slide: number }[];
+  warnings: string[];
+}
+
+const isFamily = (value: string): value is FamilyId => Object.prototype.hasOwnProperty.call(FAMILIES, value);
+
+const extOf = (path: string): 'png' | 'jpg' | 'webp' => {
+  const lower = path.toLowerCase();
+  if (lower.endsWith('.jpg') || lower.endsWith('.jpeg')) return 'jpg';
+  if (lower.endsWith('.webp')) return 'webp';
+  return 'png';
+};
+
+const assetId = (bytes: Uint8Array, ext: string) => `${createHash('sha256').update(bytes).digest('hex')}.${ext}`;
+
+function pickTemplate(id: string) {
+  const template = BUILTIN_TEMPLATES.find((t) => t.id === id);
+  if (!template) {
+    throw new Error(`Unknown template "${id}". Built-in templates: ${BUILTIN_TEMPLATES.map((t) => t.id).join(', ')}`);
+  }
+  return template;
+}
+
+/** All sizes the manifest asks for, or every default size of the used families. */
+function pickSizes(manifest: ShotManifest, families: FamilyId[]) {
+  if (manifest.sizes && manifest.sizes.length > 0) {
+    return manifest.sizes.map((id) => {
+      const size = sizeById(id);
+      if (!size) throw new Error(`Unknown export size "${id}"`);
+      return size;
+    });
+  }
+  return FAMILY_ORDER.filter((f) => families.includes(f)).flatMap((f) => FAMILIES[f].sizes.filter((s) => s.default));
+}
+
+export async function build(opts: BuildOptions): Promise<BuildReport> {
+  const log = opts.log ?? (() => {});
+  const manifestPath = resolve(opts.manifestPath);
+  const manifestDir = dirname(manifestPath);
+  const manifest = parseManifest(JSON.parse(readFileSync(manifestPath, 'utf8')));
+
+  const families = FAMILY_ORDER.filter((f) =>
+    manifest.slides.some((slide) => Object.prototype.hasOwnProperty.call(slide.captures, f)),
+  );
+  if (families.length === 0) throw new Error('No slide has a capture for a known device family');
+
+  for (const slide of manifest.slides) {
+    for (const family of Object.keys(slide.captures)) {
+      if (!isFamily(family)) throw new Error(`Unknown device family "${family}" (known: ${FAMILY_ORDER.join(', ')})`);
+    }
+  }
+
+  const template = pickTemplate(manifest.template);
+  const languages = [...new Set(manifest.languages)] as LangCode[];
+  const project: Project = projectFromTemplate(template, {
+    name: manifest.app,
+    families,
+    languages,
+  });
+
+  const chosen = manifest.slides.map((slide, i) => {
+    const index = slide.templateSlide ?? i;
+    const source = project.slides[index];
+    if (!source) throw new Error(`slides[${i}] wants template slide ${index}, but "${template.id}" has ${project.slides.length}`);
+    return source;
+  });
+  project.slides = chosen;
+
+  const images = new Map<string, ImageLike>();
+  const warnings: string[] = [];
+
+  for (const [index, slide] of project.slides.entries()) {
+    const spec = manifest.slides[index];
+    for (const lang of languages) {
+      slide.texts[lang] = {
+        ...(slide.texts[lang] ?? {}),
+        headline: spec.headline,
+        ...(spec.subtitle !== undefined ? { subtitle: spec.subtitle } : {}),
+      };
+    }
+    for (const [family, file] of Object.entries(spec.captures)) {
+      if (!isFamily(family)) continue;
+      const absolute = resolve(manifestDir, file);
+      let bytes: Uint8Array;
+      try {
+        bytes = readFileSync(absolute);
+      } catch {
+        throw new Error(`slides[${index}] capture not found: ${absolute}`);
+      }
+      const ext = extOf(absolute);
+      const id = assetId(bytes, ext);
+      if (!project.assets[id]) {
+        const image = await loadCapture(absolute);
+        const info: AssetInfo = {
+          id,
+          name: file.split(/[\\/]/).pop() ?? `capture.${ext}`,
+          width: image.width,
+          height: image.height,
+          bytes: bytes.byteLength,
+          addedAt: Date.now(),
+        };
+        project.assets[id] = info;
+      }
+      images.set(id, await loadCapture(absolute));
+      for (const lang of languages) {
+        slide.shots[family] = { ...(slide.shots[family] ?? {}), main: { ...(slide.shots[family]?.main ?? {}), [lang]: id } };
+      }
+    }
+  }
+
+  const outDir = resolve(opts.outDir ?? resolve(manifestDir, manifest.out ?? 'store-assets'));
+  const structure = manifest.structure ?? 'stores';
+  const sizes = pickSizes(manifest, families);
+  const files: BuildReport['files'] = [];
+
+  registerBundledFonts();
+
+  for (const size of sizes) {
+    if (!families.includes(size.family)) continue;
+    for (const lang of languages) {
+      for (const [slideIndex, slide] of project.slides.entries()) {
+        const shot = slide.shots[size.family]?.main?.[lang] ?? null;
+        if (!shot) warnings.push(`slide ${slideIndex + 1} (${size.family}, ${lang}) has no screenshot`);
+        const rendered = renderSlidePng({
+          project,
+          slide,
+          slideIndex,
+          family: size.family,
+          lang,
+          width: size.width,
+          height: size.height,
+          images,
+        });
+        if (rendered.result.overflowingText.length > 0) {
+          warnings.push(`slide ${slideIndex + 1} (${size.family}, ${lang}) text overflows at ${size.width}x${size.height}`);
+        }
+        if (rendered.result.missingShots.length > 0) {
+          warnings.push(`slide ${slideIndex + 1} (${size.family}, ${lang}) uses a placeholder screen`);
+        }
+        const relative = exportPath(
+          structure,
+          { family: size.family, sizeId: size.id, width: size.width, height: size.height, lang, slideIndex },
+          'png',
+          manifest.app,
+        );
+        const target = resolve(outDir, relative);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, rendered.bytes);
+        files.push({ path: relative.replaceAll('\\', '/'), width: size.width, height: size.height, family: size.family, lang, slide: slideIndex + 1 });
+        log(`${relative}  ${size.width}x${size.height}`);
+      }
+    }
+  }
+
+  writeFileSync(
+    resolve(outDir, 'capture-flow-report.json'),
+    `${JSON.stringify({ app: manifest.app, template: template.id, structure, files, warnings }, null, 2)}\n`,
+  );
+
+  return { outDir, files, warnings };
+}

package/src/capture.ts

@@ -0,0 +1,77 @@
+/**
+ * Capture flow: the tool never pretends to know your simulator.
+ * A flow lists shell commands (Playwright, simctl, adb, Maestro, fastlane,
+ * anything) that write raw captures; `run` executes them, then builds and
+ * verifies. Commands inherit the caller's environment.
+ */
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+export interface CaptureStep {
+  name?: string;
+  command: string;
+  /** Relative to the flow file. */
+  cwd?: string;
+  env?: Record<string, string>;
+}
+
+export interface CaptureFlow {
+  /** Manifest to build after capturing (relative to the flow file). */
+  manifest?: string;
+  out?: string;
+  captures: CaptureStep[];
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+export function parseFlow(raw: unknown): CaptureFlow {
+  if (!isRecord(raw)) throw new Error('Invalid flow: expected an object');
+  if (!Array.isArray(raw.captures) || raw.captures.length === 0) {
+    throw new Error('Invalid flow: "captures" must be a non-empty array of steps');
+  }
+  const captures = raw.captures.map((step, i): CaptureStep => {
+    if (!isRecord(step)) throw new Error(`Invalid flow: captures[${i}] must be an object`);
+    if (typeof step.command !== 'string' || step.command.trim() === '') {
+      throw new Error(`Invalid flow: captures[${i}].command must be a non-empty string`);
+    }
+    if (step.cwd !== undefined && typeof step.cwd !== 'string') throw new Error(`Invalid flow: captures[${i}].cwd must be a string`);
+    let env: Record<string, string> | undefined;
+    if (step.env !== undefined) {
+      if (!isRecord(step.env)) throw new Error(`Invalid flow: captures[${i}].env must be an object`);
+      env = Object.fromEntries(Object.entries(step.env).map(([k, v]) => [k, String(v)]));
+    }
+    return { name: typeof step.name === 'string' ? step.name : undefined, command: step.command, cwd: step.cwd, env };
+  });
+  return {
+    manifest: typeof raw.manifest === 'string' ? raw.manifest : undefined,
+    out: typeof raw.out === 'string' ? raw.out : undefined,
+    captures,
+  };
+}
+
+export function loadFlow(path: string): CaptureFlow {
+  return parseFlow(JSON.parse(readFileSync(path, 'utf8')));
+}
+
+/** Runs each step in order and stops at the first failure. */
+export function runCaptureFlow(flowPath: string, log: (line: string) => void = () => {}): void {
+  const absolute = resolve(flowPath);
+  const base = dirname(absolute);
+  const flow = loadFlow(absolute);
+
+  for (const [index, step] of flow.captures.entries()) {
+    const label = step.name ?? `capture ${index + 1}`;
+    const cwd = step.cwd ? resolve(base, step.cwd) : base;
+    log(`▶ ${label}: ${step.command}`);
+    const result = spawnSync(step.command, {
+      cwd,
+      shell: true,
+      stdio: 'inherit',
+      env: { ...process.env, ...step.env },
+    });
+    if (result.error) throw new Error(`${label} failed to start: ${result.error.message}`);
+    if (result.status !== 0) throw new Error(`${label} exited with code ${result.status ?? 'unknown'}`);
+  }
+}

package/src/cli.ts

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * capture-flow CLI.
+ *
+ *   capture-flow capture --flow flow.json
+ *   capture-flow build   --manifest shots.json [--out dir]
+ *   capture-flow verify  --dir dir
+ *   capture-flow run     --flow flow.json [--manifest shots.json] [--out dir]
+ */
+import { dirname, resolve } from 'node:path';
+import { build } from './build';
+import { loadFlow, runCaptureFlow } from './capture';
+import { verify } from './verify';
+
+interface Args {
+  command: string;
+  manifest?: string;
+  flow?: string;
+  out?: string;
+  dir?: string;
+  json: boolean;
+}
+
+function parseArgs(argv: string[]): Args {
+  const [command = 'help', ...rest] = argv;
+  const args: Args = { command, json: false };
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === '--json') args.json = true;
+    else if (arg === '--manifest') args.manifest = rest[++i];
+    else if (arg === '--flow') args.flow = rest[++i];
+    else if (arg === '--out') args.out = rest[++i];
+    else if (arg === '--dir') args.dir = rest[++i];
+    else if (arg.startsWith('--manifest=')) args.manifest = arg.slice('--manifest='.length);
+    else if (arg.startsWith('--flow=')) args.flow = arg.slice('--flow='.length);
+    else if (arg.startsWith('--out=')) args.out = arg.slice('--out='.length);
+    else if (arg.startsWith('--dir=')) args.dir = arg.slice('--dir='.length);
+    else throw new Error(`Unknown argument "${arg}"`);
+  }
+  return args;
+}
+
+function help(): void {
+  console.log(`capture-flow — store screenshots from raw captures
+
+  capture-flow capture --flow flow.json
+  capture-flow build   --manifest shots.json [--out dir] [--json]
+  capture-flow verify  --dir store-assets [--json]
+  capture-flow run     --flow flow.json [--manifest shots.json] [--out dir] [--json]
+
+Flow and manifest paths are relative to their own file.
+Capture steps are shell commands: Playwright, simctl, adb, Maestro, anything.`);
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.command === 'help' || args.command === '--help' || args.command === '-h') {
+    help();
+    return;
+  }
+
+  const doBuild = async (manifestPath: string, outDir?: string, print = true) => {
+    const report = await build({
+      manifestPath,
+      outDir,
+      log: args.json || !print ? undefined : (line) => console.log(line),
+    });
+    if (!print) return report;
+    if (args.json) {
+      console.log(JSON.stringify({ outDir: report.outDir, files: report.files, warnings: report.warnings }, null, 2));
+    } else {
+      console.log(`\n${report.files.length} files in ${report.outDir}`);
+      for (const warning of report.warnings) console.warn(`warning: ${warning}`);
+    }
+    return report;
+  };
+
+  if (args.command === 'capture') {
+    if (!args.flow) throw new Error('capture needs --flow <file>');
+    runCaptureFlow(args.flow, args.json ? undefined : (line) => console.log(line));
+    return;
+  }
+
+  if (args.command === 'build') {
+    if (!args.manifest) throw new Error('build needs --manifest <file>');
+    await doBuild(args.manifest, args.out);
+    return;
+  }
+
+  if (args.command === 'run') {
+    if (!args.flow) throw new Error('run needs --flow <file>');
+    const flow = loadFlow(resolve(args.flow));
+    runCaptureFlow(args.flow, args.json ? undefined : (line) => console.log(line));
+    const manifest = args.manifest ?? flow.manifest;
+    if (!manifest) throw new Error('run needs a manifest: set "manifest" in the flow or pass --manifest');
+    const base = dirname(resolve(args.flow));
+    const report = await doBuild(
+      resolve(base, manifest),
+      args.out ?? (flow.out ? resolve(base, flow.out) : undefined),
+      !args.json,
+    );
+    const result = verify(report.outDir);
+    if (args.json) {
+      console.log(
+        JSON.stringify({ outDir: report.outDir, files: report.files, warnings: report.warnings, verify: result }, null, 2),
+      );
+    } else {
+      for (const error of result.errors) console.error(`error: ${error}`);
+      console.log(result.ok ? `verified ${result.files.length} files` : `verification failed: ${result.errors.length} errors`);
+    }
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+
+  if (args.command === 'verify') {
+    if (!args.dir) throw new Error('verify needs --dir <directory>');
+    const result = verify(args.dir);
+    if (args.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      for (const file of result.files) {
+        console.log(`${file.path}  ${file.width}x${file.height}  RGB${file.colorType === 2 ? '' : ` (colour type ${file.colorType})`}`);
+      }
+      for (const error of result.errors) console.error(`error: ${error}`);
+      console.log(result.ok ? `\nOK — ${result.files.length} files` : `\nFAILED — ${result.errors.length} errors`);
+    }
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+
+  help();
+  process.exitCode = 1;
+}
+
+main().catch((error: unknown) => {
+  console.error(`capture-flow: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+});

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Library entry point.
+ *
+ * The CLI is the primary interface; these exports are for pipelines that want
+ * to call the stages directly. This package ships TypeScript, so consumers run
+ * it through tsx (or a bundler) just like the CLI does.
+ */
+export { build, type BuildOptions, type BuildReport } from './build';
+export { loadFlow, parseFlow, runCaptureFlow, type CaptureFlow, type CaptureStep } from './capture';
+export { parseManifest, type ShotManifest, type ShotSlide } from './manifest';
+export { verify, type VerifyResult, type VerifiedFile } from './verify';