capture-flow 0.1.0 → 0.1.1

package/README.md

@@ -25,6 +25,24 @@ 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.
@@ -130,7 +148,7 @@ Because steps are plain commands, a native flow is just as natural as a web one:
 | `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`.
+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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capture-flow",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Turn raw simulator and browser captures into App Store and Google Play screenshots.",
   "type": "module",
   "license": "MIT",
@@ -31,7 +31,8 @@
   "files": [
     "bin",
     "src",
-    "vendor"
+    "vendor",
+    "skills"
   ],
   "scripts": {
     "build": "tsx src/cli.ts build",

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.

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 | — |