capture-flow 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 capture-flow contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,239 @@
-# Temporary Holding Version
+# capture-flow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Capture once, ship store-ready screenshots.** `capture-flow` runs your own capture commands (Playwright, `simctl`, `adb`, Maestro, fastlane — anything that writes an image), then frames those captures in a polished template and exports exact App Store and Google Play sizes.
+
+It is a small CLI and library, not a screenshot service. The capture half is bring-your-own so it can live in any pipeline; the build half is deterministic and store-aware.
+
+```text
+your app ──► capture commands ──► raw PNG/JPEG/WebP ──► capture-flow build ──► App Store + Google Play
+             (flow.json)                                  (shots.json)           exact sizes, RGB PNG
+```
+
+## Install
+
+```bash
+npm install --save-dev capture-flow
+npx capture-flow --help
+```
+
+Requires Node **22.18+**. The renderer uses `@napi-rs/canvas` (prebuilt binaries, no system Chrome), and the template fonts ship as dependencies.
+
+To run the included Tilawah example you also need Playwright in your project:
+
+```bash
+npm install --save-dev playwright
+npx playwright install chromium
+```
+
+## Quick start
+
+A **flow** describes how to capture. A **manifest** describes how to frame it.
+
+`flow.json`
+
+```json
+{
+  "manifest": "./shots.json",
+  "out": "./store-assets",
+  "captures": [
+    { "name": "iPhone", "command": "node capture-iphone.mjs" },
+    { "name": "Android", "command": "node capture-android.mjs" }
+  ]
+}
+```
+
+`shots.json`
+
+```json
+{
+  "app": "My App",
+  "template": "noor",
+  "structure": "stores",
+  "languages": ["en-US", "ar-SA"],
+  "sizes": ["ios-6.9", "ios-6.3", "play-phone"],
+  "slides": [
+    {
+      "templateSlide": 0,
+      "headline": "Listen with *focus*",
+      "subtitle": "A calm player for long recordings.",
+      "captures": {
+        "iphone": "captures/iphone-01.png",
+        "android-phone": "captures/android-01.png"
+      }
+    }
+  ]
+}
+```
+
+Run the whole flow:
+
+```bash
+npx capture-flow run --flow flow.json
+```
+
+Or run the stages separately:
+
+```bash
+npx capture-flow capture --flow flow.json
+npx capture-flow build   --manifest shots.json
+npx capture-flow verify  --dir store-assets
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `capture-flow capture --flow <file>` | Runs each flow step in order, stopping on the first failure. |
+| `capture-flow build --manifest <file> [--out <dir>] [--json]` | Renders the manifest to store PNGs and writes `capture-flow-report.json`. |
+| `capture-flow verify --dir <dir> [--json]` | Checks every PNG is 8-bit RGB (no alpha) at the exact size in the report, and that no planned file is missing. |
+| `capture-flow run --flow <file> [--manifest <file>] [--out <dir>] [--json]` | `capture` → `build` → `verify` in one command. |
+
+Paths inside a flow are relative to the flow file; paths inside a manifest are relative to the manifest file. Capture commands run with the caller's environment plus any `env` entries.
+
+## Flow schema
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `captures` | yes | Ordered array of steps. |
+| `captures[].command` | yes | Shell command (run with the system shell). |
+| `captures[].name` | no | Label shown in the log. |
+| `captures[].cwd` | no | Working directory, relative to the flow file. |
+| `captures[].env` | no | Extra environment variables for this step. |
+| `manifest` | no | Manifest to build after capture; used by `run`. |
+| `out` | no | Output directory for `run`. Overrides the manifest's `out`. |
+
+Because steps are plain commands, a native flow is just as natural as a web one:
+
+```json
+{
+  "manifest": "./shots.json",
+  "captures": [
+    { "name": "iOS", "command": "xcrun simctl io booted screenshot captures/ios-01.png" },
+    { "name": "Android", "command": "adb exec-out screencap -p > captures/android-01.png" }
+  ]
+}
+```
+
+## Manifest schema
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `app` | yes | Project name (also used by the renderer). |
+| `template` | yes | Template id from the list below. |
+| `languages` | yes | Store locale codes, e.g. `["en-US", "ar-SA"]`. `ar-SA` exports as `ar` for Google Play. |
+| `slides` | yes | Ordered slides; each maps a device family to a capture. |
+| `out` | no | Output directory, relative to the manifest. Default `store-assets`. |
+| `structure` | no | `stores` (default), `flat`, or `fastlane`. |
+| `sizes` | no | Subset of size ids. Defaults to every default size of the families used. |
+| `slides[].headline` | yes | `*word*` highlights a run; a newline is a hard break. |
+| `slides[].subtitle` | no | Secondary copy. |
+| `slides[].templateSlide` | no | Which template slide layout to use (defaults to the slide's index). |
+| `slides[].captures` | yes | Device family → image path. |
+
+Device families: `iphone`, `iphone-landscape`, `ipad`, `ipad-landscape`, `android-phone`, `android-landscape`, `android-tablet`, `mac`, `watch`.
+
+Store sizes: `ios-6.9`, `ios-6.9-b`, `ios-6.5`, `ios-6.5-b`, `ios-6.3`, `ios-6.1`, `ipad-13`, `ipad-12.9`, `ipad-11`, `play-phone`, `play-phone-hd`, `play-tablet-7`, `play-tablet-10`, plus the corresponding `-land` ids. Run `build` with an unknown id to get the full list in the error.
+
+The default `stores` layout is what the stores expect:
+
+```text
+store-assets/
+  App Store/
+    ar-SA/
+      iPhone 6.9/01.png … 04.png
+      iPhone 6.3/01.png … 04.png
+      iPad 13/01.png … 04.png
+  Google Play/
+    ar/
+      Phone/01.png … 04.png
+      Tablet 10/01.png … 04.png
+  capture-flow-report.json
+```
+
+## Controlling the result
+
+| You want to change | Where it lives |
+| --- | --- |
+| Which app screen is shown | Your capture command (Playwright route, simulator state, deep link). Map it to a slide with `slides[].captures`. |
+| The slide layout / composition | `slides[].templateSlide` — picks one of the template's layouts (hero, tilted, hanging, …). |
+| The copy | `slides[].headline` and `slides[].subtitle`. `*word*` renders as the highlighted accent run; a newline is a hard break. |
+| Colours and fonts | The `template` you pick. Each built-in template ships a fixed palette, background, and heading/body typeface. |
+| App light/dark screenshot | The capture script's stored setting (`settings.theme` in the example's `localStorage` blob). |
+| Which store sizes | `sizes` (or omit it to get every default size of the families you captured). |
+
+Manifest-level colour/font overrides are deliberately not exposed: a template is a designed system, and mixing in arbitrary colours usually breaks it. To go beyond the built-ins, copy a template under `vendor/wajha/templates/builtin/`, change its `theme`/`typeset`, and use its `id` in the manifest.
+
+### Large screens
+
+Capture tables are just another family:
+
+```json
+{
+  "templateSlide": 0,
+  "headline": "…",
+  "captures": {
+    "ipad": "captures/ipad-01.png",
+    "android-tablet": "captures/android-tablet-01.png"
+  }
+}
+```
+
+and export them with `ipad-13` / `play-tablet-10`. Match the frame's screen aspect so nothing is distorted:
+
+- **iPad 13″** — 3:4, e.g. capture at 2064×2752 (CSS 768×1024 @2.6875).
+- **Android tablet** — 16:10 inside a 9:16 export, e.g. capture at 1600×2560 (CSS 800×1280 @2), exported at 1440×2560.
+
+Templates with native tablet layouts (`mono-swiss`, `noir-gold`, `obsidian`, `panorama-*`, …) compose the tablet canvas directly. Phone-first templates such as `noor` adapt their tall layout and swap the frame to iPad/Android tablet automatically.
+
+## Templates
+
+| Category | Templates |
+| --- | --- |
+| `elegant` | `desert-dune`, `noir-gold`, `paper-and-ink` |
+| `dark` | `midnight-neon`, `noor`, `obsidian` |
+| `minimal` | `launchpad`, `mono-swiss`, `sage` |
+| `gradient` | `aurora`, `glass-prism`, `sunset-boulevard` |
+| `playful` | `bubblegum`, `clay-garden` |
+| `bold` | `citrus-pop`, `loud-and-clear`, `split-tone` |
+| `panorama` | `panorama-peaks`, `panorama-ribbon`, `panorama-waves` |
+
+`noor` (deep emerald, gold geometry, Cairo/Noto Sans Arabic) is the template used by the Tilawah example.
+
+## Example: open-tilawa
+
+[`examples/open-tilawa`](examples/open-tilawa) captures the deployed [Tilawah](https://tilawah.cc) web app with Playwright and builds Arabic App Store and Google Play sets:
+
+```bash
+# Playwright lives outside the project in this workspace; point the example at it:
+PLAYWRIGHT_MODULE=/path/to/node_modules/playwright \
+  npx capture-flow run --flow examples/open-tilawa/flow.json
+```
+
+The generated set is checked in at `examples/open-tilawa/store-assets` (20 files: iPhone 6.9″, iPhone 6.3″, iPad 13″, Google Play phone, Google Play tablet). Three details in the example are worth copying:
+
+- **Hydration:** the deployed app needs ~20 s to boot. The script waits for the real UI (`getByRole('button', { name: 'تشغيل' })`) rather than for `load`, and navigates with `waitUntil: 'commit'`.
+- **Audio:** headless Chromium cannot use Tilawah's service-worker WebTorrent stream, so the script points `/webtorrent/…` at Tilawah's own documented `/media/` web seed. The player then shows real playback time and an active spectrum instead of a paused 0:00.
+- **Large screens:** the same four screens are captured at tablet viewports (`ipad`, `android-tablet`) and mapped to `ipad-13` / `play-tablet-10` in the manifest.
+
+## Library
+
+The package ships TypeScript (the CLI runs it through `tsx`), so import it from a `tsx` script or a bundler:
+
+```ts
+import { build } from 'capture-flow';
+
+const report = await build({ manifestPath: 'shots.json', outDir: 'store-assets' });
+console.log(report.files, report.warnings);
+```
+
+Subpaths are available for the pieces: `capture-flow/build`, `capture-flow/capture`, `capture-flow/manifest`, `capture-flow/verify`. `build` returns the files it wrote and any layout warnings (overflowing text, missing screenshots).
+
+## Original idea and credits
+
+This project exists because of **[Wajha](https://github.com/M-Alkassem/Wajha)** by [M-Alkassem](https://github.com/M-Alkassem) and contributors — the original store-screenshot designer with the Canvas engine, templates, device frames and export rules.
+
+capture-flow is a new orchestration layer around that idea: it adds the capture flow, the manifest/CLI contract, verify, and headless Node rendering. The rendering core is **vendored** from Wajha under `vendor/wajha/` (model, engine, export naming, templates, slide sorting) and is used under the MIT License. The full notice is in [`vendor/wajha/LICENSE`](vendor/wajha/LICENSE) and [`vendor/wajha/NOTICE`](vendor/wajha/NOTICE).
+
+Wajha is MIT-licensed, copyright © 2026 Wajha contributors. capture-flow is MIT-licensed too; see [`LICENSE`](LICENSE).
+
+If you only need to design screenshots interactively, use Wajha. If you need screenshots produced repeatedly by a pipeline, use capture-flow — and consider upstreaming improvements to the engine.

package/bin/capture-flow.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * npm entry point.
+ *
+ * The tool ships as TypeScript (its vendored engine is TypeScript too), so the
+ * launcher registers tsx and then loads the CLI. Keeping one source of truth
+ * beats a separate build output that can drift from the examples.
+ */
+import { register } from 'tsx/esm/api';
+
+register();
+await import(new URL('../src/cli.ts', import.meta.url).href);

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "capture-flow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Turn raw simulator and browser captures into App Store and Google Play screenshots.",
+  "type": "module",
+  "license": "MIT",
+  "author": "adelpro",
+  "keywords": [
+    "screenshots",
+    "app-store",
+    "google-play",
+    "store-assets",
+    "fastlane",
+    "playwright",
+    "simctl",
+    "adb"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "capture-flow": "./bin/capture-flow.mjs"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./build": "./src/build.ts",
+    "./manifest": "./src/manifest.ts",
+    "./capture": "./src/capture.ts",
+    "./verify": "./src/verify.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "vendor"
+  ],
+  "scripts": {
+    "build": "tsx src/cli.ts build",
+    "verify": "tsx src/cli.ts verify",
+    "typecheck": "tsc --noEmit",
+    "example:tilawah": "tsx src/cli.ts run --flow examples/open-tilawa/flow.json"
+  },
+  "dependencies": {
+    "@fontsource-variable/cairo": "^5.3.0",
+    "@fontsource-variable/inter": "^5.3.0",
+    "@fontsource-variable/noto-sans-arabic": "^5.3.0",
+    "@napi-rs/canvas": "^1.1.0",
+    "fflate": "^0.8.3",
+    "tsx": "^4.20.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.2",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22.18"
+  }
+}

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'}`);
+  }
+}