zdymak 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zdymak 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

@@ -0,0 +1,211 @@
+# zdymak
+
+**Premium App Store & Google Play preview videos — from your screenshots, in one command.**
+
+Turn a handful of app screenshots into a cinematic, **spec-compliant** store preview: spring-eased camera
+moves, kinetic captions, and an encode that App Store Connect and Google Play accept without a fight. One
+small config per project; the engine lives here, shared across all your apps.
+
+> Why it exists: a plain "Ken-Burns zoom over screenshots" reads as amateur, and hand-encoding to each
+> store's exact spec (Apple: 886×1920, H.264 High@4.0, 15–30s, **no device frame**) is fiddly and easy to
+> get rejected. This bakes the premium motion and the store rules in.
+
+<br>
+
+## What you get
+
+| | |
+|---|---|
+| 🎬 **Premium motion** | Per-scene **spring dolly** (push-in / pull-back / drift) that eases and *settles* — not a flat pan. Captions sit **outside** the camera so they stay steady while the screen drifts (parallax), and rise in with a spring. |
+| ✅ **Store-compliant** | Full-bleed (no bezel — Apple rejects bezels), exact resolution, H.264 High @ the right level, yuv420p, faststart. |
+| 🍎 **App Store + 🤖 Play** | One 886×1920 file fills both iPhone App Preview slots; a 1080×1920 file is ready for a Play/YouTube promo. |
+| 🧩 **Two input modes** | **Bring your own** screenshots, *or* **capture** them from a booted simulator / device. |
+| ⚙️ **Config-driven** | Everything project-specific is one `zdymak.config.mjs`. The tool is otherwise generic. |
+
+<br>
+
+## Install
+
+Needs **Node ≥18** and **ffmpeg** on your `PATH` (`brew install ffmpeg`).
+
+```sh
+# from a checkout (until published to npm):
+npm i --prefix /path/to/zdymak
+npm link --prefix /path/to/zdymak        # gives you the `zdymak` command
+# …or just call it directly:
+node /path/to/zdymak/bin/zdymak.mjs <command>
+```
+
+<br>
+
+## Quickstart
+
+**1. Add a config** to your project root (copy `examples/example.config.mjs` → `zdymak.config.mjs`):
+
+```js
+export default {
+  brand: { ink: '#0b0b0a', title: '#F5F5F4', sub: '#9ae6b4' },
+  screenshotsDir: './screenshots',       // where your PNGs live
+  suffix: '',                             // scene id "welcome" → screenshots/welcome.png
+  scenes: [
+    { id: 'welcome',  title: 'Your hook.',        sub: 'The promise, briefly.', move: 'pushInSlow' },
+    { id: 'feature-1', title: 'What it does.',     sub: 'Why it matters.',       move: 'driftUp' },
+    { id: 'offer',    title: 'The honest offer.',  sub: 'Price / trial, plainly.', move: 'pullBackSlow' },
+  ],
+  targets: ['appstore-preview', 'play-promo'],
+  out: './store-assets',
+};
+```
+
+**2. Build:**
+
+```sh
+zdymak video
+# → store-assets/appstore-preview.mp4   (886×1920, upload to App Store Connect)
+# → store-assets/play-promo.mp4         (1080×1920, upload to YouTube, link in Play Console)
+```
+
+That's it. `zdymak specs` prints every target and its exact dimensions.
+
+<br>
+
+## The two ways to get screenshots
+
+**Mode A — bring your own** (default). Point `screenshotsDir` at any folder of PNGs — from Xcode, an
+XCUITest capture, Android Studio, Figma, anywhere.
+
+**Mode B — capture from a running app.** Boot a simulator/emulator (or connect a device), navigate to a
+screen, and snap it. The tool strips the alpha channel (stores reject transparency) and writes a
+store-ready PNG straight into your screenshots folder:
+
+```sh
+zdymak capture --platform ios      --name welcome --out ./screenshots
+zdymak capture --platform android  --name welcome --out ./screenshots
+zdymak capture --platform ios      --record       --out ./screenshots   # screen-record; Ctrl-C to stop
+```
+
+It does **not** build your app — that's your toolchain. It captures whatever's on screen, so you drive the
+navigation.
+
+<br>
+
+## Config reference
+
+| Key | Meaning |
+|---|---|
+| `brand.ink` / `.title` / `.sub` | Hex colours for the caption scrim + title + subtitle. |
+| `brand.fontPaths` | Optional custom TTFs (else: system font — San Francisco on macOS). |
+| `brand.name` / `.tagline` / `.endline` / `.endsub` / `.logo` | **Reel target only** — wordmark, cold-open tagline, end-card lines, and the icon PNG for the device-framed `social-reel` bookends. |
+| `brand.reel` | **Reel target only** — optional palette overrides (`bgTop`, `bgBottom`, `glowLight`, `matteTop`, `matteBottom`, `glowDark`, `titleColor`, `subColor`, `bookendTitle`, `bookendSub`). |
+| `screenshotsDir` + `suffix` | Resolve `scene.id` → `${screenshotsDir}/${id}${suffix}.png`. |
+| `scenes[]` | `{ id \| image, title, sub, move }`. `image` overrides the id lookup. |
+| `scenes[].move` | `pushIn` · `pushInSlow` · `pullBack` · `pullBackSlow` · `driftUp` · `driftDown` · `driftLeft` · `driftRight` · `still`. Omit to auto-vary. |
+| `targets[]` | Which videos to build from the top-level scenes (`zdymak specs` lists them). |
+| `sceneDur` / `xfade` | Seconds per scene / cross-dissolve. Tune total length to the store's 15–30s window. |
+| `theme` | Premium-technique styling (matte, `vignette`, `inset`, `handle`, cut timings). Brand-driven defaults. |
+| `music` | Optional bed for **every** video: `{ path, offset, fadeIn, fadeOut, volume }` (silent if omitted). |
+| `devices` | Per-device **screenshots + reels** (see below). Configure only the devices you ship. |
+| `out` | Output directory. |
+
+<br>
+
+## Screenshots & multiple devices
+
+Videos are only half the set. `zdymak build` also renders **store screenshots** for each device you
+configure, in the same styles (premium / bleed), at each store's exact dimensions, as **no-alpha PNGs**
+(App Store & Play reject alpha). Each device points at its own captures; scenes with no matching capture
+are **skipped cleanly**, so an app lists only the devices it actually ships:
+
+```js
+devices: {
+  iphone: { capturesDir: './shots/iphone', suffix: '', screenshots: [{ target: 'appstore-iphone-6.9', style: 'premium' }] },
+  ipad:   { capturesDir: './shots/ipad',   suffix: '', screenshots: [{ target: 'appstore-ipad-13',    style: 'premium' }] },
+  mac:    { capturesDir: './shots/mac',     suffix: '', screenshots: [{ target: 'appstore-mac',        style: 'premium' }] },
+  watch:  { capturesDir: './shots/watch',   suffix: '',
+            scenes: [{ id: '01-study' }, { id: '02-answer' }],   // per-device scene override (raw, no caption)
+            screenshots: [{ target: 'appstore-watch', style: 'bleed', size: [422, 514] }] },
+  android:{ capturesDir: './shots/android', suffix: '', screenshots: [
+            { target: 'play-phone', style: 'framed' },           // Android punch-hole frame
+            { target: 'play-tablet', style: 'premium' },
+            { target: 'play-feature-graphic' } ] },              // the 1024×500 Play banner (not per-scene)
+  // a device may also carry `videos: [{ target: 'premium-reel', size: [2064, 2752] }]` at its own dimensions
+},
+```
+
+The **`framed`** style picks the right bezel per target — iPhone (Dynamic Island), Android (punch-hole),
+iPad/tablet, or Watch ring — and Mac stays plain (its captures are already windowed). **`play-feature-graphic`**
+is special: one 1024×500 brand banner (logo + tagline + a tilted hero device), not a per-scene screenshot.
+
+Commands:
+
+```sh
+zdymak build          # EVERYTHING: top-level videos + every device's screenshots (+ device videos)
+zdymak screenshots    # just the per-device screenshots
+zdymak video          # just the top-level video targets
+```
+
+`zdymak specs` lists every image target and its exact dimensions. A device that only ships iPhone simply
+omits the others — that's the "use only part of it" contract.
+
+<br>
+
+## Where each file goes
+
+- **App Store** — `appstore-preview.mp4` → App Store Connect → your app → *(localization)* → **App
+  Previews**. One 886×1920 file fills **both** the 6.5" and 6.9" slots. Optional at launch; screenshots
+  alone are a valid submission.
+- **Google Play** — Play takes a **YouTube URL**, not a file. Upload `play-promo.mp4` to YouTube, then
+  paste the link in Play Console → Main store listing → **Preview video**.
+- **Web / social** — `social-reel.mp4` (**device-framed**: iPhone bezel + logo bookends) or
+  `premium-reel.mp4` (**premium**: matte + vignette + label pills). For your website, X / Instagram /
+  TikTok, or YouTube. **Never** put either in the App Store App Preview slot — the bezel/label make them
+  marketing assets, not App Previews; that's what the full-bleed `appstore-preview` is for.
+
+> **Three styles, one config.** Every target reads the same `scenes`; the style is fixed per target:
+> - **full-bleed** (`appstore-preview`, `play-promo`) — the screen fills the frame; required for App Previews.
+> - **device-framed** (`social-reel`) — an iPhone bezel + brand background + logo cold-open/end-card.
+> - **premium** (`premium-reel`) — the **Apple editing-vocabulary** preset: every screen floats on a brand
+>   matte with a soft glow + vignette, a motion-then-freeze spring dolly, **palette-aware cuts** (hard cut
+>   within a palette, dissolve only at a shift), and a bottom title **pill**. Tune it with the optional
+>   `theme` block (matte colours, `vignette`, `inset`, `handle`, cut timings) — brand-driven defaults apply
+>   if you omit it.
+
+<br>
+
+## Programmatic use
+
+```js
+import { buildVideo, loadConfig, registerFonts, videoTarget } from 'zdymak';
+
+const cfg = await loadConfig('zdymak.config.mjs');
+registerFonts(cfg.brand.fontPaths);
+await buildVideo({ scenes: cfg.scenes, spec: videoTarget('appstore-preview'), brand: cfg.brand, outFile: 'out.mp4' });
+```
+
+<br>
+
+## Troubleshooting
+
+- **`ffmpeg failed to start`** — install it (`brew install ffmpeg`) or set `$FFMPEG`.
+- **Captions look like a fallback font** — pass `brand.fontPaths` to your own TTF; on Linux install a
+  system sans (DejaVu).
+- **Duration warning** — the tool warns if a video falls outside a store's min/max; adjust `sceneDur` or
+  the number of scenes.
+- **`Truncating packet …` line** — harmless ffmpeg notice from the raw-frame pipe; the output is correct.
+
+<br>
+
+## Roadmap
+
+- [x] Video engine — three styles (full-bleed, device-framed, premium), App Store + Play + social targets.
+- [x] **Multi-device screenshots** — iPhone / iPad / Mac / Watch, no-alpha PNG, modular `devices` config.
+- [x] **Music bed** — `{ path, offset, fadeIn, fadeOut, volume }` across every video.
+- [x] Automated publishing — npm trusted publishing (OIDC), see `RELEASING.md`.
+- [ ] **Device-framed stills** — iPhone/iPad bezel, Mac window, Watch ring for the `framed` screenshot style
+      (premium/bleed already cover every device).
+- [ ] Capture: **Playwright (web)** driver (adb / iOS-sim snapshot already ship).
+- [ ] Play feature graphic (1024×500) + per-locale caption sets.
+
+See **SKILL.md** if you drive this with Claude Code.
+
+MIT.

package/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: zdymak
+description: Generate premium, spec-compliant App Store & Google Play preview VIDEOS from a project's screenshots. Use when a user wants an "app preview", "store preview video", "App Store trailer", "Play promo video", or is preparing store-listing assets. Produces the exact resolution/codec each store requires (App Store 886×1920 H.264 High@4.0, 15–30s, no bezel; Play 1080×1920 for YouTube) with cinematic spring motion + kinetic captions — not a flat Ken-Burns slideshow.
+---
+
+# zdymak
+
+A standalone CLI that turns app screenshots into premium, store-compliant preview videos. Everything
+project-specific is one `zdymak.config.mjs`; the engine (spring camera moves, parallax captions,
+per-store encode) is shared.
+
+## When to use
+The user is building App Store / Google Play listing assets, or asks for an app-preview / store trailer /
+promo video. If they only need still screenshots resized to store dimensions, note that image targets are
+on the roadmap (dimensions are in `zdymak specs`) and the video flow is what's built.
+
+## Prerequisites (check first)
+- `ffmpeg` on PATH (`brew install ffmpeg`) — the encode needs it.
+- Node ≥18.
+- The tool itself: run via `zdymak …` if linked, else `node <path-to>/zdymak/bin/zdymak.mjs …`.
+
+## Workflow
+
+1. **Confirm the store spec** the user wants: `zdymak specs` lists every target with exact
+   dimensions. App Store App Previews must be **15–30s** and have **no device frame**; the engine already
+   enforces both.
+
+2. **Get screenshots** — two modes:
+   - **Bring-your-own:** point `screenshotsDir` at existing PNGs (Xcode/XCUITest/Android/Figma).
+   - **Capture:** boot a simulator/emulator, navigate to each screen, then
+     `zdymak capture --platform ios|android --name <screen> --out ./screenshots`. It strips alpha
+     (stores reject it). It does NOT build the app — you drive navigation.
+
+3. **Author the config** (`zdymak.config.mjs` at project root). Keep captions **terse** (a preview
+   autoplays muted in search results — it must read in ~2.5s per scene). Order the scenes as a narrative:
+   hook → what it does → the best moment → the honest offer. Pick `move` per scene for variety, or omit to
+   auto-vary. Example:
+   ```js
+   export default {
+     brand: { ink: '#0b0b0a', title: '#F5F5F4', sub: '#9ae6b4' },
+     screenshotsDir: './screenshots', suffix: '',
+     scenes: [
+       { id: 'welcome', title: 'One-line hook.', sub: 'The promise.', move: 'pushInSlow' },
+       { id: 'best',    title: 'The best moment.', sub: 'Show, don’t tell.', move: 'pullBack' },
+       { id: 'offer',   title: 'The honest offer.', sub: 'Price / trial.', move: 'pullBackSlow' },
+     ],
+     targets: ['appstore-preview', 'play-promo'],
+     out: './store-assets',
+   };
+   ```
+
+4. **Build:** `zdymak video`. Then **verify** with ffprobe before telling the user it's ready:
+   ```sh
+   ffprobe -v error -select_streams v:0 \
+     -show_entries stream=width,height,codec_name,profile,level,pix_fmt -show_entries format=duration \
+     -of default=noprint_wrappers=1 store-assets/appstore-preview.mp4
+   ```
+   Confirm width/height/profile/level match the target and duration is in range. Heed any `⚠︎` duration
+   warning the CLI prints (adjust `sceneDur` or scene count).
+
+5. **Tell the user where it goes:**
+   - App Store → App Store Connect → App Previews (one 886×1920 file fills the 6.5" **and** 6.9" slots).
+   - Play → upload the 1080×1920 file to **YouTube**, paste the link in Play Console → Preview video.
+
+## Tuning for quality
+- **Captions overlap busy UI?** Lower them (they sit at ~0.75·height) or pick screenshots with calmer
+  lower thirds.
+- **Feels flat?** Ensure adjacent scenes use *different* moves; the spring dolly is what makes it premium.
+- **Too long/short?** Total = `scenes × sceneDur − (scenes−1) × xfade`. App Store wants 15–30s.
+
+## Three styles (fixed per target; all read the same `scenes`)
+- **Full-bleed** (`appstore-preview`, `play-promo`) — screen fills the frame; required for App Previews.
+- **Device-framed** (`social-reel`) — iPhone bezel + brand background + logo cold-open/end-card
+  (needs `brand.name/tagline/endline/logo`). Web/social/YouTube.
+- **Premium** (`premium-reel`) — the **Apple editing-vocabulary** preset: matte + glow + vignette,
+  motion-then-freeze spring dolly, **palette-aware cuts**, bottom title pill. This is the default premium
+  marketing look; tune via the optional `theme` block (brand-driven defaults apply if omitted). Web/social.
+  Like the framed reel, it's **not** an App Preview (the matte/pill make it a marketing asset).
+
+## Guardrails
+- Never submit the **device-framed** `social-reel` as an App Preview — Apple rejects device bezels there.
+  Use the full-bleed `appstore-preview` for the App Store slot; `social-reel` is web/social/YouTube only.
+- Keep any music **commercially licensed**; the engine is silent by default (previews autoplay muted).
+- Don't fabricate UI or overstate features in captions — App Review checks the preview matches the app.

package/bin/zdymak.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.mjs';
+run();

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "zdymak",
+  "version": "0.3.0",
+  "description": "Generate premium, spec-compliant App Store & Google Play preview videos (and store assets) from screenshots — one config-driven CLI across all your projects.",
+  "type": "module",
+  "bin": {
+    "zdymak": "bin/zdymak.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "SKILL.md"
+  ],
+  "scripts": {
+    "example": "node bin/zdymak.mjs video --config examples/asilak.config.mjs",
+    "release:patch": "node scripts/release.mjs patch",
+    "release:minor": "node scripts/release.mjs minor",
+    "release:major": "node scripts/release.mjs major"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@napi-rs/canvas": "^0.1.60"
+  },
+  "keywords": [
+    "app-store",
+    "google-play",
+    "app-preview",
+    "screenshots",
+    "aso",
+    "marketing",
+    "video",
+    "ffmpeg"
+  ],
+  "license": "MIT"
+}

package/src/canvas.mjs

@@ -0,0 +1,116 @@
+/** Shared canvas primitives (Skia via @napi-rs/canvas) used by the reel renderer. */
+
+export const font = (sizePx, weight = 'bold') => `${weight} ${sizePx}px Brand`;
+
+/** #rrggbb + alpha → rgba() string. */
+export function hexA(hex, a) {
+  const n = parseInt(String(hex).replace('#', ''), 16);
+  return `rgba(${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}, ${a})`;
+}
+
+/** #rrggbb → [r,g,b]. */
+export function hexRgb(hex) {
+  const n = parseInt(String(hex).replace('#', ''), 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+
+/** Numerically integrated damped spring 0→1 (semi-implicit Euler) → per-frame lookup. Over-damped configs
+ *  glide and settle (camera dolly); lighter damping gives a small overshoot. */
+export function springSeries(frames, fps, { stiffness = 55, damping = 24, mass = 1.5 } = {}) {
+  const dt = 1 / fps;
+  let x = 0;
+  let v = 0;
+  const out = new Array(frames);
+  for (let f = 0; f < frames; f++) {
+    const a = (stiffness * (1 - x) - damping * v) / mass;
+    v += a * dt;
+    x += v * dt;
+    out[f] = x;
+  }
+  return out;
+}
+
+/** Rounded-rectangle subpath (no fill/stroke). */
+export function roundRectPath(ctx, x, y, w, h, r) {
+  const rr = Math.min(r, w / 2, h / 2);
+  ctx.beginPath();
+  ctx.moveTo(x + rr, y);
+  ctx.arcTo(x + w, y, x + w, y + h, rr);
+  ctx.arcTo(x + w, y + h, x, y + h, rr);
+  ctx.arcTo(x, y + h, x, y, rr);
+  ctx.arcTo(x, y, x + w, y, rr);
+  ctx.closePath();
+}
+
+/** Vertical linear gradient top→bottom filling the whole canvas. */
+export function fillVerticalGradient(ctx, w, h, top, bottom) {
+  const g = ctx.createLinearGradient(0, 0, 0, h);
+  g.addColorStop(0, top);
+  g.addColorStop(1, bottom);
+  ctx.fillStyle = g;
+  ctx.fillRect(0, 0, w, h);
+}
+
+/** Soft radial brand glow — "something is arriving" depth on a dark matte. */
+export function radialGlow(ctx, cx, cy, radius, color, alpha) {
+  const g = ctx.createRadialGradient(cx, cy, 0, cx, cy, radius);
+  g.addColorStop(0, hexA(color, alpha));
+  g.addColorStop(1, hexA(color, 0));
+  ctx.fillStyle = g;
+  ctx.fillRect(0, 0, ctx.canvas.width, ctx.canvas.height);
+}
+
+/** Word-wrap `text` to `maxWidth` at the current font; returns line array. */
+export function wrapLines(ctx, text, maxWidth) {
+  const words = String(text).split(/\s+/);
+  const lines = [];
+  let line = '';
+  for (const w of words) {
+    const test = line ? `${line} ${w}` : w;
+    if (ctx.measureText(test).width > maxWidth && line) {
+      lines.push(line);
+      line = w;
+    } else {
+      line = test;
+    }
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+
+/** Typeset a centred caption block (bold title + optional lighter subtitle). Returns height drawn. */
+export function drawCaption(ctx, { title, subtitle, centerX, top, maxWidth, titleSize, subSize, titleColor, subColor }) {
+  ctx.textAlign = 'center';
+  ctx.textBaseline = 'top';
+  let y = top;
+  ctx.font = font(titleSize, 'bold');
+  ctx.fillStyle = titleColor;
+  const titleLH = Math.round(titleSize * 1.12);
+  for (const ln of wrapLines(ctx, title, maxWidth)) {
+    ctx.fillText(ln, centerX, y);
+    y += titleLH;
+  }
+  if (subtitle) {
+    y += Math.round(titleSize * 0.28);
+    ctx.font = font(subSize, 'regular');
+    ctx.fillStyle = subColor;
+    const subLH = Math.round(subSize * 1.3);
+    for (const ln of wrapLines(ctx, subtitle, maxWidth)) {
+      ctx.fillText(ln, centerX, y);
+      y += subLH;
+    }
+  }
+  return y - top;
+}
+
+/** Height a caption block WOULD occupy (mirror of drawCaption's layout), for vertical centring. */
+export function measureCaption(ctx, { title, subtitle, maxWidth, titleSize, subSize }) {
+  ctx.font = font(titleSize, 'bold');
+  let h = wrapLines(ctx, title, maxWidth).length * Math.round(titleSize * 1.12);
+  if (subtitle) {
+    h += Math.round(titleSize * 0.28);
+    ctx.font = font(subSize, 'regular');
+    h += wrapLines(ctx, subtitle, maxWidth).length * Math.round(subSize * 1.3);
+  }
+  return h;
+}

package/src/capture/index.mjs

@@ -0,0 +1,91 @@
+/**
+ * Capture mode (mode B) — for devs who'd rather grab frames from a running app than hand-manage a
+ * screenshots folder. Project-agnostic on purpose: it does NOT build your app (that's your toolchain).
+ * It snapshots or screen-records whatever is on the BOOTED simulator / connected device, strips the
+ * alpha channel (Apple & Play reject transparency on screenshots), and writes store-ready PNGs you then
+ * reference from your config's `scenes`.
+ *
+ *   zdymak capture --platform ios      --name welcome            # snap the booted iOS simulator
+ *   zdymak capture --platform android  --name welcome            # snap the connected device/emulator
+ *   zdymak capture --platform ios      --record --out shots/rec  # screen-record (stop with Ctrl-C)
+ *
+ * The two-mode contract: capture writes PNGs; the video engine consumes PNGs. So capture output drops
+ * straight into `screenshotsDir`, and mode A (bring-your-own-screenshots) and mode B share one pipeline.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createCanvas, loadImage } from '@napi-rs/canvas';
+
+/** Flatten alpha over black and rewrite as an opaque PNG (App Store & Play reject alpha on screenshots). */
+async function stripAlpha(file) {
+  const img = await loadImage(file);
+  const c = createCanvas(img.width, img.height);
+  const ctx = c.getContext('2d');
+  ctx.fillStyle = '#000';
+  ctx.fillRect(0, 0, img.width, img.height);
+  ctx.drawImage(img, 0, 0);
+  fs.writeFileSync(file, c.toBuffer('image/png'));
+}
+
+function sh(cmd, args) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8' });
+  if (r.status !== 0) throw new Error(`${cmd} ${args.join(' ')} failed: ${(r.stderr || r.stdout || '').trim()}`);
+  return r.stdout;
+}
+
+async function captureIos(flags) {
+  if (spawnSync('xcrun', ['simctl', 'help'], { stdio: 'ignore' }).status !== 0) {
+    throw new Error('xcrun/simctl not found — install Xcode command-line tools.');
+  }
+  const outDir = path.resolve(flags.out || 'shots');
+  fs.mkdirSync(outDir, { recursive: true });
+
+  if (flags.record !== undefined) {
+    const out = path.join(outDir, `${flags.name || 'recording'}.mov`);
+    console.log(`▶︎ Recording the booted iOS simulator → ${out}\n  Interact with the app, then press Ctrl-C to stop.`);
+    const proc = spawn('xcrun', ['simctl', 'io', 'booted', 'recordVideo', '--codec=h264', '--force', out], { stdio: 'inherit' });
+    await new Promise((res) => proc.on('close', res));
+    console.log(`✓ Saved ${out}. Extract frames with: ffmpeg -i ${out} -vf fps=2 ${outDir}/frame-%03d.png`);
+    return;
+  }
+
+  const out = path.join(outDir, `${flags.name || 'shot'}.png`);
+  sh('xcrun', ['simctl', 'io', 'booted', 'screenshot', out]);
+  await stripAlpha(out);
+  console.log(`✓ ${out}  (alpha stripped, store-ready)`);
+}
+
+async function captureAndroid(flags) {
+  if (spawnSync('adb', ['version'], { stdio: 'ignore' }).status !== 0) {
+    throw new Error('adb not found — install Android platform-tools and connect a device/emulator.');
+  }
+  const outDir = path.resolve(flags.out || 'shots');
+  fs.mkdirSync(outDir, { recursive: true });
+
+  if (flags.record !== undefined) {
+    const remote = '/sdcard/zdymak-rec.mp4';
+    const out = path.join(outDir, `${flags.name || 'recording'}.mp4`);
+    console.log(`▶︎ Recording the device → ${out}\n  Interact with the app, then press Ctrl-C to stop.`);
+    const proc = spawn('adb', ['shell', 'screenrecord', remote], { stdio: 'inherit' });
+    await new Promise((res) => proc.on('SIGINT', res).on('close', res));
+    sh('adb', ['pull', remote, out]);
+    console.log(`✓ Saved ${out}. Extract frames with: ffmpeg -i ${out} -vf fps=2 ${outDir}/frame-%03d.png`);
+    return;
+  }
+
+  const name = flags.name || 'shot';
+  const out = path.join(outDir, `${name}.png`);
+  const buf = spawnSync('adb', ['exec-out', 'screencap', '-p'], { maxBuffer: 64 * 1024 * 1024 });
+  if (buf.status !== 0) throw new Error(`adb screencap failed: ${buf.stderr}`);
+  fs.writeFileSync(out, buf.stdout);
+  await stripAlpha(out);
+  console.log(`✓ ${out}  (alpha stripped, store-ready)`);
+}
+
+export async function runCapture(flags) {
+  const platform = flags.platform;
+  if (platform === 'ios') return captureIos(flags);
+  if (platform === 'android') return captureAndroid(flags);
+  throw new Error('capture needs --platform ios|android. Boot a simulator/emulator (or connect a device) first, navigate to the screen, then run capture --name <screen>.');
+}