capture-flow 0.0.0-stage → 0.1.1

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,257 @@
-# 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
+```
+
+## Install as an agent skill
+
+The repository ships a `capture-flow` skill so coding agents know the manifest
+contract, capture rules, and failure fixes without reading this README first.
+
+```bash
+npx skills add adelpro/capture-flow
+```
+
+Add `-g` for a global install, or `-a claude-code -a codex -a opencode` to target
+specific agents. The skill also ships inside the npm package, so a local install works:
+
+```bash
+npx skills add ./node_modules/capture-flow
+```
+
+Skill source: [`skills/capture-flow/SKILL.md`](skills/capture-flow/SKILL.md).
+
+## 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`, `apple-tv`, `vision`, `play-feature`.
+
+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,58 @@
 {
   "name": "capture-flow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "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",
+    "skills"
+  ],
+  "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/skills/capture-flow/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: capture-flow
+description: Turn raw device or browser captures into App Store and Google Play screenshot sets. Use when asked to generate, polish, resize, frame, or validate store screenshots, to add headlines and device frames to app screens, or to set up a repeatable screenshot pipeline with Playwright, simctl, adb, or Maestro.
+metadata:
+  author: adelpro
+  version: "0.1.1"
+---
+
+# capture-flow
+
+`capture-flow` is a CLI that takes plain screenshots plus a small JSON manifest and
+renders exact-size store assets with device frames and composed copy.
+
+It has three stages:
+
+1. **capture** — run your own screenshot commands (Playwright, `simctl`, `adb`, Maestro, anything).
+2. **build** — map each raw capture to a slide and render every store size.
+3. **verify** — check that every PNG is the exact size, 8-bit RGB, and has no alpha.
+
+Do not invent your own resizing pipeline. Capture at native resolution, let `build` do the rest.
+
+## Setup
+
+```bash
+npm install --save-dev capture-flow
+npx capture-flow --help
+```
+
+Node.js **22.18+** is required. Playwright, Xcode, or Android tools are only needed for
+the capture stage; `build` and `verify` run on Node alone.
+
+If the project already has `capture-flow` in `package.json`, use `npx capture-flow`
+or the local `node_modules/.bin/capture-flow`.
+
+## Workflow
+
+1. **Decide the target set** — device families, store sizes, languages, and slide count.
+2. **Write a capture command** that saves full-resolution PNGs into a folder.
+3. **Write `flow.json`** to run that command (or run it manually first).
+4. **Write `shots.json`** mapping captures to slides.
+5. **Run** everything and read the warnings.
+6. **Fix** overflow / missing-screen warnings, rebuild.
+7. **Verify** and inspect the first image of each output folder.
+
+```bash
+npx capture-flow run --flow flow.json
+npx capture-flow verify --dir store-assets
+```
+
+Use `--json` on `build`, `run`, or `verify` when another program consumes the result.
+
+## Capture rules
+
+These prevent the most common bad output.
+
+- Capture at the device's **native pixel size**, never upscale. The renderer can scale
+  down but cannot invent detail.
+- Match the frame's screen aspect ratio. A mismatched capture is cropped or distorted.
+- No transparency. `verify` rejects alpha; use an opaque background when capturing.
+- One file per screen per family. Name them predictably (`iphone-01.png`, `android-01.png`, …).
+- Hide dev tooling, cursors, toasts, cookie banners, and consent dialogs before the shot.
+- Wait for real content (fonts, data, animation end) before `screenshot()`. A skeleton
+  or empty state is not a store screenshot.
+- Keep text in screenshots readable at thumbnail size; avoid dense tables.
+
+Reference dimensions (portrait):
+
+| Family | Capture at | Typical CSS viewport |
+| --- | --- | --- |
+| `iphone` | 1320 × 2868 | 440 × 956 @3 |
+| `ipad` | 2064 × 2752 | 768 × 1024 @2.6875 |
+| `android-phone` | 1080 × 1920 or higher (9:16) | 360 × 640 @3 |
+| `android-tablet` | 1600 × 2560 (16:10) | 800 × 1280 @2 |
+| `mac` | 2880 × 1800 | — |
+
+Native capture recipes for Playwright, iOS Simulator, and Android are in
+[references/capture-recipes.md](references/capture-recipes.md).
+
+## flow.json
+
+A flow is an ordered list of shell commands. Paths are relative to the flow file.
+
+```json
+{
+  "manifest": "./shots.json",
+  "out": "./store-assets",
+  "captures": [
+    { "name": "web (Playwright)", "command": "node capture.mjs" },
+    { "name": "iOS", "command": "xcrun simctl io booted screenshot captures/ios-01.png" }
+  ]
+}
+```
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `captures[].command` | yes | Shell command, run with the system shell. |
+| `captures[].name` | no | Label in the log. |
+| `captures[].cwd` | no | Working directory, relative to the flow file. |
+| `captures[].env` | no | Extra environment variables for the step. |
+| `manifest` | no | Manifest used by `run`. |
+| `out` | no | Output directory used by `run`. |
+
+Steps stop at the first non-zero exit code. Use `capture-flow capture --flow flow.json`
+to run only the capture stage.
+
+## shots.json
+
+```json
+{
+  "app": "My App",
+  "template": "noor",
+  "languages": ["ar-SA"],
+  "sizes": ["ios-6.9", "ios-6.3", "ipad-13", "play-phone", "play-tablet-10"],
+  "slides": [
+    {
+      "templateSlide": 0,
+      "headline": "استمع *بخشوع*",
+      "subtitle": "تلاوات كاملة ومؤشر طيفي.",
+      "captures": {
+        "iphone": "captures/iphone-01.png",
+        "android-phone": "captures/android-01.png",
+        "ipad": "captures/ipad-01.png",
+        "android-tablet": "captures/android-tablet-01.png"
+      }
+    }
+  ]
+}
+```
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `app` | yes | Project name; also used in the report and fastlane paths. |
+| `template` | yes | Built-in template id. |
+| `languages` | yes | Store locales, e.g. `["en-US", "ar-SA"]`. `ar-SA` exports as `ar` on Google Play. |
+| `slides` | yes | Ordered slides; each maps device family → 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 the default size of every family used. |
+| `slides[].headline` | yes | `*word*` marks the accent run; `\n` is a hard break. |
+| `slides[].subtitle` | no | Secondary copy. |
+| `slides[].templateSlide` | no | Which template layout to use; defaults to the slide index. |
+| `slides[].captures` | yes | Device family → image path (`png`, `jpg`, `jpeg`, `webp`). |
+
+Families: `iphone`, `iphone-landscape`, `ipad`, `ipad-landscape`, `android-phone`,
+`android-landscape`, `android-tablet`, `mac`, `watch`, `apple-tv`, `vision`, `play-feature`.
+
+Store limits: App Store accepts up to 10 slides per size, Google Play up to 8.
+Respect them before designing a long story.
+
+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 `-land` variants. Full pixel dimensions are in
+[references/store-sizes.md](references/store-sizes.md).
+
+Every slide must supply every family you want in the output. A slide without a family
+produces a placeholder warning and an image with an empty frame — treat that as a bug.
+
+## Choosing a template
+
+| 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` |
+
+- Arabic-first copy: `noor` (Cairo + Noto Sans Arabic, emerald and gold).
+- Native tablet composition: `mono-swiss`, `noir-gold`, `obsidian`, `panorama-*`.
+- Phone-first templates adapt to iPad/Android tablet by swapping the frame and
+  reflowing the tall layout. This is acceptable but less deliberate.
+
+A template owns the palette and typefaces. There are deliberately no per-manifest colour
+or font overrides — mixing arbitrary colours into a designed system usually breaks it.
+To customize, copy a template from `node_modules/capture-flow/vendor/wajha/templates/builtin/`,
+edit its `theme`/`typeset`, and register it in your own build. Ask the user before
+forking a template.
+
+`templateSlide` selects a composition (hero, tilted, pair, hanging, …). Layouts differ
+per template. To see the available layouts and their default copy, read the template
+file:
+
+```bash
+sed -n '/slides: \[/,/^  ]/p' node_modules/capture-flow/vendor/wajha/templates/builtin/noor.ts
+```
+
+Out-of-range values fail with `"<template>" has <n>` — that number is the layout count.
+
+## Output
+
+The default `stores` structure is store-upload ready:
+
+```text
+store-assets/
+  App Store/
+    ar-SA/
+      iPhone 6.9/01.png … 10.png
+      iPhone 6.3/01.png …
+      iPad 13/01.png …
+  Google Play/
+    ar/
+      Phone/01.png …
+      Tablet 10/01.png …
+  capture-flow-report.json
+```
+
+`capture-flow-report.json` lists every file with its `width`, `height`, `family`,
+`lang`, and `slide`, plus `warnings`. Read it instead of guessing what was produced.
+
+`flat` writes `01-iphone-en-US.png`-style names; `fastlane` writes
+`fastlane/screenshots/<locale>/`.
+
+## Warnings and failures
+
+| Symptom | Fix |
+| --- | --- |
+| `text overflows at WxH` | Shorten copy, remove a line break, use a different `templateSlide`, or pick a template with more copy room. |
+| `uses a placeholder screen` | That slide has no capture for the family. Add one or drop the family/size. |
+| `has no screenshot` | Slide → family mapping is incomplete for an exported size. |
+| `Unknown device family` | Use a family from the list above. |
+| `Unknown export size` | Use a size id from the table; `-land` is a suffix, not a family. |
+| `capture not found` | Manifest paths are relative to the manifest file, not the terminal's cwd. |
+| `verify` alpha error | Flatten the capture onto an opaque background; PNG must be 8-bit RGB. |
+| Wrong dimensions in `verify` | Do not post-process built files; re-run `build` for that size. |
+
+## Library use
+
+```ts
+import { build, verify, runCaptureFlow } from 'capture-flow';
+
+await runCaptureFlow('flow.json');
+const report = await build({ manifestPath: 'shots.json', outDir: 'store-assets' });
+const result = verify('store-assets');
+```
+
+The package ships TypeScript, so run it through `tsx` or a bundler.
+
+## Example
+
+A complete, real setup (Playwright capture of a web app, Arabic RTL, five device
+sizes, 20 output files) lives in the repository:
+
+<https://github.com/adelpro/capture-flow/tree/main/examples/open-tilawa>
+
+It shows consent-dialog dismissal, waiting for hydration, live audio state, and the
+`عرض الكل` reciter flow. Adapt it rather than starting from a blank page.