zdymak 0.7.0 → 0.10.0

package/README.md

@@ -6,6 +6,8 @@ Turn a handful of app screenshots into a cinematic, **spec-compliant** store pre
 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.
 
+<p align="center"><em>▶︎ <b>See it in action:</b> run <code>npm run example</code> to render the demo reel from three flat screenshots — a hosted preview lands in a later release.</em></p>
+
 > 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.
@@ -26,16 +28,25 @@ small config per project; the engine lives here, shared across all your apps.
 
 ## 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>
+npm i -g zdymak      # global CLI → `zdymak <command>`
+# …or per-project:
+npm i -D zdymak      # → `npx zdymak <command>`
 ```
 
+Also needs **Node ≥18** and **ffmpeg** on your `PATH`:
+
+| Platform | Install ffmpeg |
+|---|---|
+| **macOS** | `brew install ffmpeg` |
+| **Linux** — Debian/Ubuntu | `sudo apt install ffmpeg` |
+| **Linux** — Fedora | `sudo dnf install ffmpeg` |
+| **Windows** | `winget install Gyan.FFmpeg`  ·  or `choco install ffmpeg` / `scoop install ffmpeg` |
+
+zdymak finds ffmpeg on `PATH`, or set `$FFMPEG` to an explicit binary. Video generation is pure Node +
+ffmpeg — no platform SDKs. Screenshot **capture** additionally needs that platform's toolchain: **Xcode**
+for `--platform ios`, the **Android SDK / `adb`** for `--platform android`.
+
 <br>
 
 ## Quickstart
@@ -102,39 +113,66 @@ navigation.
 | `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. |
+| `theme` | **Video** matte styling — the premium-technique block (see **Theme options** below). Brand-driven defaults. |
+| `stillTheme` | **Screenshot** matte styling — same option shape as `theme`; falls back to `theme` when unset. |
+| `timing` | Reel-mode timeline override `{ coldOpen, scene, endCard, xfade }` for the `social-reel` bookends. |
 | `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. |
+| `reel` | **Live-footage reel** — composite driven video `clip`s / `images` on a clean light matte, cross-dissolves (see **Live-footage reel** below). |
 | `out` | Output directory. |
 
+### Theme options (`theme` / `stillTheme`)
+
+Both accept the same block; every key is optional with a brand-driven default. **Screenshots assume the
+premium store-shot shape by default** — `captionAnchor: 'top'`, and `fit: 'contain'` for frameless windows —
+so a typical `stillTheme` only sets colours. Override any key per shot.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `bgTop` / `bgBottom` | brand | Matte gradient top / bottom colour. |
+| `glow` / `glowAlpha` | brand.sub / `0.16` | Soft radial brand-glow colour + strength. |
+| `vignette` | `0.3` | 0..1 edge darkening (use `0` on a light matte). |
+| `inset` | `0.955` | Fraction of the frame the screen fills (lower floats it with a wider matte border). |
+| `label` | `true` | Show the caption on a pill; `false` = plain text, no pill. |
+| `labelColor` / `subColor` | brand.title / brand.sub | Caption title + subtitle colour. |
+| `handle` | — | Optional persistent top handle text (e.g. `@yourapp`). |
+| `captionAnchor` | `bottom` (video) · `top` (stills) | Caption above (`top`) or below (`bottom`) the device. |
+| `fit` | `cover` · `contain` (frameless stills) | `cover` fills + crops; `contain` shows the **whole** capture (e.g. a Mac window) with matte margins. |
+| `headlineScale` | `0.062` | Caption headline size as a fraction of the frame's short edge — bump it for bigger, bolder headlines. |
+| `frame` | `phone` (reel) | Device frame around a reel screen: `'phone'` iPhone bezel, or `false` for a bare rounded screen. |
+| `bleed` | `false` | Reel only: the source **fills the whole frame** (no matte / frame / shadow) — a compliant full-bleed App Store App Preview. |
+
 <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:
+configure, 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. **The style is inferred from the target**, so a device is usually just
+its captures + target(s):
 
 ```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' }] },
+  iphone: { capturesDir: './shots/iphone', suffix: '', screenshots: [{ target: 'appstore-iphone-6.9' }] },
+  ipad:   { capturesDir: './shots/ipad',   suffix: '', screenshots: [{ target: 'appstore-ipad-13' }] },
+  mac:    { capturesDir: './shots/mac',     suffix: '', screenshots: [{ target: 'appstore-mac' }] },        // window on the matte
   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] }] },
+            screenshots: [{ target: 'appstore-watch', style: 'bleed', size: [422, 514] }] }, // override: raw fill
   android:{ capturesDir: './shots/android', suffix: '', screenshots: [
-            { target: 'play-phone', style: 'framed' },           // Android punch-hole frame
-            { target: 'play-tablet', style: 'premium' },
+            { target: 'play-phone' }, { target: 'play-tablet' },
             { 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.
+**Inferred style** (override per shot with `style`): a **framed** device — iPhone (Dynamic Island), Android
+(punch-hole), iPad/tablet, Watch ring — for phone/tablet/watch targets; a **premium** window-on-the-matte for
+Mac/desktop (its capture is already a window, so `fit: 'contain'` shows the whole thing). Screenshots put the
+**caption on top** by default. Override any of it via `stillTheme` / a per-shot `theme`, or `style: 'bleed'`
+for a raw full-frame shot (Watch). **`play-feature-graphic`** is special: one 1024×500 brand banner (logo +
+tagline + a tilted hero device), not a per-scene screenshot.
 
 Commands:
 
@@ -142,13 +180,52 @@ Commands:
 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 reel           # LIVE-FOOTAGE montage (real motion) from the `reel` block — see below
+zdymak build --clean  # wipe the output folder first, so ONLY this run's assets remain (no stale files)
 ```
 
+**`--clean`** (on `build` / `screenshots` / `video` / `capture`) empties the target folder before writing,
+so a removed target or renamed scene can't leave a stale screenshot behind — every file is produced by this
+run. On `capture` it clears only stale PNG/MOV captures and keeps the `.dd` build cache (rebuilds stay
+incremental).
+
 `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>
 
+## Live-footage reel — real motion, not Ken Burns
+
+The video *targets* above animate a **static screenshot** (a subtle dolly) — inherently Ken Burns. For a
+genuinely premium reel, feed **real motion**: `zdymak reel` composites short **recordings** of your app (or
+an image sequence) on a clean matte, floats each with a rounded frame + soft shadow, puts the headline **on
+top**, and **cross-dissolves** between beats — the restrained, Apple-App-Preview language. The matte defaults
+to **light** (consistent with the store screenshots) and stills get a slow, never-freezing push-in.
+Source-agnostic, like the two screenshot modes: each segment's footage can be **brought by you** or
+**captured** by `zdymak capture --record`.
+
+```js
+reel: {
+  size: [1080, 1920], bpm: 120, beatsPerCut: 4,   // hold = beatsPerCut × 60/bpm seconds per segment
+  transition: 'dissolve',                          // default; 'cut' for beat-matched hard cuts
+  music: { path: './bed.mp3', volume: 0.9, fadeIn: 0.6, fadeOut: 0.8 }, // optional, faded
+  // theme: { bgTop: '#0e1a12', bgBottom: '#0b0b0a', label: true },     // override to a DARK bed if you want
+  segments: [
+    { clip: './rec/study.mov',   caption: { title: 'Recall it.', sub: 'Right before you forget.' } },
+    { images: ['a.png', 'b.png'], caption: { title: 'Many cards.', sub: 'One page.' } }, // multi-photo page
+  ],
+}
+```
+
+- **`clip`** = a recording (real motion). **`image`** / **`images`** = one still or a sequence shown within
+  the segment (a "multiple photos per page" beat). **`transition`** = `dissolve` (default) or `cut`. The screen
+  sits in an **iPhone frame** by default (`theme.frame`: `'phone'` | `false` for a bare rounded screen). Matte
+  colours / `inset` / `radius` / `shadow` / caption anchor default to a clean **light** look; override via the
+  reel `theme`. Run `zdymak reel` → `<out>/reel.mp4`.
+- **Compliant App Store App Preview** — Apple's in-store slot wants *real footage, full-bleed, no device
+  frame*. Point the reel at recordings (not stills) with `theme: { bleed: true }`, `size: [886, 1920]`,
+  `level: '4.0'`, and no captions. (The framed light reel above is the marketing/social asset, not the slot.)
+
 ## Where each file goes
 
 - **App Store** — `appstore-preview.mp4` → App Store Connect → your app → *(localization)* → **App
@@ -199,10 +276,10 @@ await buildVideo({ scenes: cfg.scenes, spec: videoTarget('appstore-preview'), br
 
 - [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] **Device-framed stills** — inferred per target (iPhone/iPad/Android/Watch bezel, Mac window), caption
+      on top, `contain`-fit windows; all overridable via `stillTheme` / per-shot `theme`.
 - [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.
 

package/SKILL.md

@@ -11,8 +11,12 @@ 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.
+promo video, **or store screenshots**. `zdymak video` builds the previews; `zdymak build` *also* renders
+**multi-device store screenshots** (iPhone / iPad / Mac / Watch / Android) — style inferred per target,
+caption on top, `contain`-fit windows, no-alpha PNG. Dimensions are in `zdymak specs`. Add **`--clean`** to
+any build/capture command to wipe the output folder first, so only this run's assets remain (no stale files).
+For a premium reel with REAL motion (not a Ken-Burns zoom of a still), use **`zdymak reel`** — it composites
+app RECORDINGS/clips (or an image sequence) on the matte with beat-matched hard cuts (the `reel` config block).
 
 ## Prerequisites (check first)
 - `ffmpeg` on PATH (`brew install ffmpeg`) — the encode needs it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zdymak",
-  "version": "0.7.0",
+  "version": "0.10.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": {
@@ -16,6 +16,8 @@
   ],
   "scripts": {
     "example": "node bin/zdymak.mjs video --config examples/asilak.config.mjs",
+    "check:docs": "node scripts/check-docs.mjs",
+    "prepublishOnly": "node scripts/check-docs.mjs",
     "release:patch": "node scripts/release.mjs patch",
     "release:minor": "node scripts/release.mjs minor",
     "release:major": "node scripts/release.mjs major"
@@ -23,6 +25,12 @@
   "engines": {
     "node": ">=18"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lonli-Lokli/zdymak.git"
+  },
+  "homepage": "https://github.com/Lonli-Lokli/zdymak#readme",
+  "bugs": "https://github.com/Lonli-Lokli/zdymak/issues",
   "dependencies": {
     "@napi-rs/canvas": "^0.1.60"
   },

package/src/capture/index.mjs

@@ -82,8 +82,17 @@ async function captureIos(flags) {
   }
   const outDir = path.resolve(flags.out || 'shots');
   fs.mkdirSync(outDir, { recursive: true });
+  // --clean removes stale capture images first so the folder holds ONLY this run's screenshots. Keeps the
+  // `.dd` build cache (and any subdirs) so a rebuild stays incremental — only loose PNG/MOV files are cleared.
+  if (flags.clean) {
+    let cleared = 0;
+    for (const f of fs.readdirSync(outDir)) {
+      if (/\.(png|mov)$/i.test(f)) { fs.rmSync(path.join(outDir, f), { force: true }); cleared++; }
+    }
+    console.log(`🧹 cleaned ${cleared} stale capture(s) in ${path.relative(process.cwd(), outDir) || outDir}`);
+  }
 
-  if (flags.record !== undefined) {
+  if (flags.record !== undefined && !flags.states) {
     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' });
@@ -116,20 +125,45 @@ async function captureIos(flags) {
       sh('xcrun', ['simctl', 'install', udid, app]);
     }
 
-    // Pin Apple's canonical marketing status bar: 9:41, full signal/wifi, FULL battery but NOT charging
+    // Apple's canonical marketing status bar: 9:41, full signal/wifi, FULL battery but NOT charging
     // (a charging bolt reads as a simulator override; Apple's own shots show an unplugged full battery).
-    spawnSync('xcrun', ['simctl', 'status_bar', udid, 'override', '--time', '9:41',
-      '--batteryState', 'discharging', '--batteryLevel', '100', '--cellularBars', '4', '--wifiBars', '3'], { stdio: 'ignore' });
+    const pinStatusBar = () =>
+      spawnSync('xcrun', ['simctl', 'status_bar', udid, 'override', '--time', '9:41',
+        '--batteryState', 'discharging', '--batteryLevel', '100', '--cellularBars', '4', '--wifiBars', '3'], { stdio: 'ignore' });
+    pinStatusBar();
 
-    console.log(`▶︎ Driving ${states.length} screens via "${flags.arg} <id>" on ${flags.bundle}…`);
+    // --record turns each screen into a short CLIP (real motion) instead of a still. The app must move
+    // during the window: pass the reel handle (default `-marketingReel`) so the harness auto-animates
+    // (auto-flip the card, auto-scroll a list, reveal the paywall). The reel engine (`zdymak reel`) then
+    // composites these clips on the matte. See SKILL/README "produce mode".
+    const recording = flags.record !== undefined;
+    const dur = Number(flags.duration || 3);
+    const reelArg = flags['reel-arg'] || '-marketingReel';
+    const verb = recording ? `Recording ${dur}s clips` : 'Driving';
+    console.log(`▶︎ ${verb} for ${states.length} screens via "${flags.arg} <id>" on ${flags.bundle}…`);
     for (const st of states) {
       spawnSync('xcrun', ['simctl', 'terminate', udid, flags.bundle], { stdio: 'ignore' });
-      sh('xcrun', ['simctl', 'launch', udid, flags.bundle, flags.arg, st]);
+      const launch = ['simctl', 'launch', udid, flags.bundle, flags.arg, st];
+      if (recording) launch.push(reelArg, 'YES'); // tell the harness to auto-animate this screen
+      sh('xcrun', launch);
       await sleep(settle * 1000);
-      const out = path.join(outDir, `${st}${suffix}.png`);
-      sh('xcrun', ['simctl', 'io', udid, 'screenshot', out]);
-      await stripAlpha(out);
-      console.log(`   ✓ ${st}${suffix}.png`);
+      // Re-assert RIGHT BEFORE capture: a launch + the settle lets the sim re-sync the battery to the host
+      // (a charging bolt creeps back on later screens). Re-pinning per screen keeps every shot clean.
+      pinStatusBar();
+      if (recording) {
+        const out = path.join(outDir, `${st}${suffix}.mov`);
+        const rec = spawn('xcrun', ['simctl', 'io', udid, 'recordVideo', '--codec=h264', '--force', out], { stdio: 'ignore' });
+        await sleep(dur * 1000);
+        rec.kill('SIGINT'); // simctl finalizes the mp4/mov on SIGINT
+        await new Promise((res) => rec.on('close', res));
+        console.log(`   ✓ ${st}${suffix}.mov (${dur}s)`);
+      } else {
+        await sleep(500); // let the pinned bar paint before the screenshot
+        const out = path.join(outDir, `${st}${suffix}.png`);
+        sh('xcrun', ['simctl', 'io', udid, 'screenshot', out]);
+        await stripAlpha(out);
+        console.log(`   ✓ ${st}${suffix}.png`);
+      }
     }
     console.log(`Done → ${outDir}`);
     return;
@@ -162,6 +196,15 @@ async function captureAndroid(flags) {
   }
   const outDir = path.resolve(flags.out || 'shots');
   fs.mkdirSync(outDir, { recursive: true });
+  // --clean removes stale capture images first so the folder holds ONLY this run's screenshots. Keeps the
+  // `.dd` build cache (and any subdirs) so a rebuild stays incremental — only loose PNG/MOV files are cleared.
+  if (flags.clean) {
+    let cleared = 0;
+    for (const f of fs.readdirSync(outDir)) {
+      if (/\.(png|mov)$/i.test(f)) { fs.rmSync(path.join(outDir, f), { force: true }); cleared++; }
+    }
+    console.log(`🧹 cleaned ${cleared} stale capture(s) in ${path.relative(process.cwd(), outDir) || outDir}`);
+  }
 
   if (flags.record !== undefined) {
     const remote = '/sdcard/zdymak-rec.mp4';

package/src/cli.mjs

@@ -9,11 +9,13 @@
  *   zdymak help
  */
 import path from 'node:path';
+import fs from 'node:fs';
 import { registerFonts } from './fonts.mjs';
 import { loadConfig } from './config.mjs';
 import { buildVideo } from './video.mjs';
 import { buildReel } from './reel.mjs';
 import { buildPremium } from './premium.mjs';
+import { buildMontage } from './montage.mjs';
 import { buildDeviceScreenshots } from './screenshots.mjs';
 import { VIDEO_TARGETS, IMAGE_TARGETS, videoTarget } from './specs.mjs';
 import { runCapture } from './capture/index.mjs';
@@ -42,9 +44,26 @@ async function open(flags) {
   const cfg = await loadConfig(flags.config || DEFAULT_CONFIG);
   registerFonts(cfg.brand.fontPaths);
   const outDir = flags.out ? path.resolve(flags.out) : cfg.out;
+  // --clean wipes the output folder first, so a run can't leave stale assets from a removed target/scene
+  // behind (every screenshot/video in the folder is then freshly produced by THIS run).
+  if (flags.clean && fs.existsSync(outDir)) {
+    fs.rmSync(outDir, { recursive: true, force: true });
+    console.log(`🧹 cleaned ${path.relative(process.cwd(), outDir) || outDir}`);
+  }
   return { cfg, outDir };
 }
 
+/** Warn when the audio expectation and the config disagree: a video/reel that should carry a music score
+ *  has none (Apple recommends a single score for continuity), or `music` is set where nothing consumes it. */
+function warnAudio({ videoCount, hasMusic, label }) {
+  if (videoCount > 0 && !hasMusic) {
+    console.warn(`⚠︎ audio: ${label} ${videoCount === 1 ? 'plays' : 'play'} SILENT — no music. Apple recommends a single music score for continuity; set \`music.path\`.`);
+  }
+  if (videoCount === 0 && hasMusic) {
+    console.warn('⚠︎ audio: `music.path` is set but this run builds no video/reel — the audio is ignored (screenshots have no sound).');
+  }
+}
+
 /** Build one video target (optionally at an overridden device size / scene set / theme). */
 async function buildVideoTarget({ id, scenes, brand, cfg, outFile, size, theme }) {
   const base = videoTarget(id);
@@ -68,6 +87,29 @@ async function cmdVideo(flags) {
   for (const id of targets) {
     await buildVideoTarget({ id, scenes: cfg.scenes, brand: cfg.brand, cfg, outFile: path.join(outDir, `${id}.mp4`) });
   }
+  warnAudio({ videoCount: targets.length, hasMusic: !!cfg.music, label: 'videos' });
+  console.log('Done.');
+}
+
+async function cmdReel(flags) {
+  const { cfg, outDir } = await open(flags);
+  const reel = cfg.reel;
+  if (!reel?.segments?.length) {
+    console.warn('No `reel.segments` in the config — nothing to build. (See README: live-footage reel.)');
+    return;
+  }
+  const [w, h] = reel.size || [1080, 1920];
+  const spec = { w, h, fps: reel.fps || 30, profile: reel.profile || 'high', level: reel.level || '4.1' };
+  const outFile = path.join(outDir, `${flags.name || 'reel'}.mp4`);
+  fs.mkdirSync(outDir, { recursive: true });
+  console.log(`zdymak reel • ${reel.segments.length} segment(s) → ${w}×${h}${reel.music ? ', ♪' : ''}`);
+  const { totalDur } = await buildMontage({
+    segments: reel.segments, brand: cfg.brand, theme: reel.theme, spec, // reel theme (light default), NOT cfg.theme
+    music: reel.music, sceneDur: reel.sceneDur, bpm: reel.bpm, beatsPerCut: reel.beatsPerCut,
+    transition: reel.transition, xfadeDur: reel.xfadeDur, outFile,
+  });
+  console.log(`  ✓ ${totalDur.toFixed(1)}s → ${path.relative(process.cwd(), outFile)}`);
+  warnAudio({ videoCount: 1, hasMusic: !!reel.music, label: 'the reel' });
   console.log('Done.');
 }
 
@@ -82,6 +124,7 @@ async function cmdScreenshots(flags) {
     const written = await buildDeviceScreenshots({ device, brand: cfg.brand, theme: device.theme ?? cfg.stillTheme ?? cfg.theme, outDir });
     console.log(`  • ${device.name}: ${written.length} shot(s)${written[0] ? ` (${written[0].W}×${written[0].H}…)` : ' — no captures found, skipped'}`);
   }
+  warnAudio({ videoCount: 0, hasMusic: !!cfg.music, label: 'screenshots' });
   console.log('Done.');
 }
 
@@ -107,6 +150,9 @@ async function cmdBuild(flags) {
       console.log(`  • ${device.name} screenshots: ${written.length}${written.length ? '' : ' — no captures found, skipped'}`);
     }
   }
+  const videoCount = (cfg.targets.length && cfg.scenes.length ? cfg.targets.length : 0)
+    + cfg.devices.reduce((a, d) => a + d.videos.length, 0);
+  warnAudio({ videoCount, hasMusic: !!cfg.music, label: 'videos' });
   console.log('Done.');
 }
 
@@ -128,17 +174,20 @@ function cmdHelp() {
   console.log(`zdymak — premium App Store, Google Play & social videos + screenshots, from your captures
 
 Usage:
-  zdymak build       [--config <path>] [--out <dir>]   # everything: videos + per-device screenshots
-  zdymak video       [--config <path>] [--target <ids>] [--out <dir>]
-  zdymak screenshots [--config <path>] [--out <dir>]
+  zdymak build       [--config <path>] [--out <dir>] [--clean]   # everything: videos + per-device screenshots
+  zdymak video       [--config <path>] [--target <ids>] [--out <dir>] [--clean]
+  zdymak reel        [--config <path>] [--out <dir>] [--clean]   # LIVE-FOOTAGE montage from clips/images
+  zdymak screenshots [--config <path>] [--out <dir>] [--clean]
   zdymak specs
   zdymak capture  --platform ios --bundle <id> --arg <handle> --states <a,b,c> [--suffix -light]
-                  [--build --project <.xcodeproj> --scheme <name>] [--device <sim>] [--out <dir>]
+                  [--build --project <.xcodeproj> --scheme <name>] [--device <sim>] [--out <dir>] [--clean]
                   # full workflow: start the app, drive each screen by a launch handle, snap store-ready PNGs
   zdymak capture  --platform ios|android --name <screen>          # single snapshot of the booted device
   zdymak help
 
 Defaults: --config ${DEFAULT_CONFIG}. Needs ffmpeg on PATH (or $FFMPEG).
+--clean: wipe the output folder first (capture clears stale PNGs but keeps the .dd build cache) — so the
+folder ends up holding ONLY this run's assets, never a stale screenshot from a removed target/scene.
 README.md documents the config (brand, scenes, targets, theme, music, devices); SKILL.md is for agents.`);
 }
 
@@ -149,6 +198,7 @@ export async function run(argv = process.argv.slice(2)) {
     switch (cmd) {
       case 'build': await cmdBuild(flags); break;
       case 'video': await cmdVideo(flags); break;
+      case 'reel': await cmdReel(flags); break;
       case 'screenshots': await cmdScreenshots(flags); break;
       case 'specs': cmdSpecs(); break;
       case 'capture': await runCapture(flags, rest); break;

package/src/config.mjs

@@ -23,6 +23,14 @@ const DEFAULT_BRAND = {
   name: 'App', tagline: '', endline: '', endsub: '', logo: null, reel: {},
 };
 
+/** Every top-level config field an app author can set. The doc-sync guard (`scripts/check-docs.mjs`)
+ *  asserts each appears in README.md/SKILL.md, so adding a field forces a doc line. Keep in sync with the
+ *  `raw.*` reads below. */
+export const CONFIG_KEYS = [
+  'brand', 'screenshotsDir', 'suffix', 'scenes', 'targets', 'sceneDur', 'xfade',
+  'timing', 'theme', 'stillTheme', 'music', 'devices', 'reel', 'out',
+];
+
 /** Map raw scenes → resolved scenes with absolute image paths (`${dir}/${id}${suffix}.png` or explicit). */
 function resolveScenes(rawScenes, baseDir, dir, suffix) {
   return (rawScenes || []).map((s, i) => {
@@ -56,9 +64,9 @@ export async function loadConfig(configPath) {
   const screenshotsDir = raw.screenshotsDir ? path.resolve(baseDir, raw.screenshotsDir) : baseDir;
   const suffix = raw.suffix ?? '';
 
-  // Top-level scenes are required UNLESS a `devices` map supplies its own per-device scenes.
-  if (!raw.devices && (!Array.isArray(raw.scenes) || raw.scenes.length === 0)) {
-    throw new Error('Config error: `scenes` must be a non-empty array (or use a `devices` map).');
+  // Top-level scenes are required UNLESS a `devices` map or a live-footage `reel` supplies the content.
+  if (!raw.devices && !raw.reel && (!Array.isArray(raw.scenes) || raw.scenes.length === 0)) {
+    throw new Error('Config error: provide `scenes`, a `devices` map, or a `reel` block.');
   }
   const scenes = resolveScenes(raw.scenes, baseDir, screenshotsDir, suffix);
 
@@ -79,8 +87,25 @@ export async function loadConfig(configPath) {
     };
   });
 
+  // Live-footage reel: resolve each segment's clip/image(s) + the music bed relative to the config file.
+  const reel = raw.reel
+    ? {
+        ...raw.reel,
+        music: raw.reel.music?.path
+          ? { ...raw.reel.music, path: path.resolve(baseDir, raw.reel.music.path) }
+          : undefined,
+        segments: (raw.reel.segments || []).map((s) => ({
+          ...s,
+          clip: s.clip ? path.resolve(baseDir, s.clip) : undefined,
+          image: s.image ? path.resolve(baseDir, s.image) : undefined,
+          images: s.images ? s.images.map((p) => path.resolve(baseDir, p)) : undefined,
+        })),
+      }
+    : undefined;
+
   return {
     brand,
+    reel,
     scenes,
     devices,
     music,

package/src/montage.mjs

@@ -0,0 +1,419 @@
+/**
+ * LIVE-FOOTAGE reel (montage) — uspamin's ad-video technique, generalized and made source-agnostic.
+ *
+ * Composite driven video CLIPS (real motion) or IMAGE sequences on a clean matte — floating rounded screen
+ * + soft shadow, a headline caption above it, and a short cross-DISSOLVE between beats (Apple App-Preview
+ * style; `transition:'cut'` for beat-matched hard cuts). The matte defaults to LIGHT (consistent with the
+ * light store screenshots), and STILLS get a slow never-freezing push-in (a frozen still reads as dead).
+ * Unlike the premium/social reels — which Ken-Burns a single screenshot — this shows real motion + premium
+ * framing. Optional ducked music.
+ *
+ * Source-agnostic (mirrors zdymak's two screenshot modes): each segment's `clip` / `image` / `images` can be
+ * BROUGHT by the user or CAPTURED by `zdymak capture --record`.
+ *
+ * Config (a `reel` block; `sceneDur`/`bpm`/`beatsPerCut` set the beat-matched hold):
+ *   reel: {
+ *     bpm: 120, beatsPerCut: 4,                    // hold = beatsPerCut × 60/bpm seconds per segment
+ *     transition: 'dissolve' | 'cut', xfadeDur: 0.3,
+ *     theme: { ... },                              // matte override; defaults LIGHT + caption on top
+ *     music: { path, volume, fadeIn, fadeOut, offset },
+ *     segments: [
+ *       { clip: './rec/study.mov',   caption: { title, sub } },  // real motion (a recording)
+ *       { images: ['a.png','b.png'], caption: { title, sub } },  // multiple photos / page
+ *       { image: './shots/welcome.png', caption: { title, sub } }, // one still (gets a slow push-in)
+ *     ],
+ *   }
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { createCanvas } from '@napi-rs/canvas';
+import { font, hexA, roundRectPath, fillVerticalGradient, radialGlow, wrapLines } from './canvas.mjs';
+
+// The reel matte defaults to LIGHT — consistent with the light store screenshots (a dark matte behind
+// light-theme screens reads as inconsistent). Apple's app marketing favours clean, minimal, untextured
+// backgrounds; the screen floats via a soft SHADOW, not a heavy vignette. Override any key via `reel.theme`.
+const REEL_LIGHT_DEFAULT = {
+  bgTop: '#eef2ef', // soft, faintly cool light
+  bgBottom: '#ffffff',
+  glow: null, // → brand.sub, kept very subtle on light
+  glowAlpha: 0.05,
+  vignette: 0, // no filter-y vignette on a light matte
+  inset: 0.8,
+  radius: 0.05,
+  shadow: 0.24, // the float cue on light
+  frame: 'phone', // iPhone bezel around the screen (like the framed screenshots); false = bare rounded screen
+  label: false, // plain caption text, no pill (matches the light screenshots)
+  pillFill: null,
+  pillOpacity: 0.9,
+  labelColor: '#0b0b0a', // near-black headline
+  subColor: '#52606d', // muted slate subhead
+  captionAnchor: 'top', // headline ON TOP, matching the store screenshots
+};
+function resolveReelTheme(brand, theme) {
+  const th = { ...REEL_LIGHT_DEFAULT, ...(theme || {}) };
+  th.glow = th.glow || brand.sub;
+  th.pillFill = th.pillFill || brand.ink;
+  return th;
+}
+
+const FF = process.env.FFMPEG || 'ffmpeg';
+const FFPROBE = process.env.FFPROBE || 'ffprobe';
+
+function ff(args) {
+  const r = spawnSync(FF, ['-y', '-loglevel', 'error', ...args], { stdio: ['ignore', 'inherit', 'inherit'] });
+  if (r.status !== 0) throw new Error(`ffmpeg failed (exit ${r.status})`);
+}
+function probe(file, entries) {
+  const r = spawnSync(FFPROBE, ['-v', 'error', '-select_streams', 'v:0',
+    '-show_entries', entries, '-of', 'default=nw=1:nk=1', file], { encoding: 'utf8' });
+  return String(r.stdout || '').trim().split('\n');
+}
+const isVideo = (p) => /\.(mov|mp4|m4v|webm|mkv)$/i.test(p);
+
+/** Contain-fit (w,h) into the inset box of the frame, preserving the source aspect. */
+function fit(srcW, srcH, boxW, boxH) {
+  const a = srcH / srcW;
+  let w = boxW;
+  let h = Math.round(boxW * a);
+  if (h > boxH) {
+    h = boxH;
+    w = Math.round(boxH / a);
+  }
+  return [w % 2 ? w + 1 : w, h % 2 ? h + 1 : h];
+}
+
+/** Vertical layout: reserve a BAND for the caption (top or bottom); the screen floats in the remaining
+ *  area, so the caption never sits on the app UI. No caption → a thin symmetric matte all round. */
+function layout(W, H, hasCaption, inset, top) {
+  const capBand = Math.round(H * (hasCaption ? 0.2 : 0.06));
+  const otherPad = Math.round(H * 0.06);
+  const availTop = top ? capBand : otherPad;
+  const availH = H - capBand - otherPad;
+  const boxW = Math.round(W * inset);
+  const capCenterY = top ? Math.round(H * 0.09) : H - Math.round(capBand * 0.56);
+  return { availTop, availH, boxW, capCenterY };
+}
+
+// ── Canvas furniture (rendered once / per segment, written as PNGs for ffmpeg overlay) ───────────────────
+function writePng(canvas, file) {
+  fs.writeFileSync(file, canvas.toBuffer('image/png'));
+}
+function mattePng(W, H, th) {
+  const c = createCanvas(W, H);
+  const ctx = c.getContext('2d');
+  fillVerticalGradient(ctx, W, H, th.bgTop, th.bgBottom);
+  radialGlow(ctx, W * 0.5, H * 0.4, W * 0.85, th.glow, th.glowAlpha);
+  return c;
+}
+function vignettePng(W, H, strength) {
+  const c = createCanvas(W, H);
+  if (strength > 0) {
+    const ctx = c.getContext('2d');
+    const g = ctx.createRadialGradient(W / 2, H / 2, Math.min(W, H) * 0.32, W / 2, H / 2, Math.max(W, H) * 0.72);
+    g.addColorStop(0, 'rgba(0,0,0,0)');
+    g.addColorStop(1, `rgba(0,0,0,${strength})`);
+    ctx.fillStyle = g;
+    ctx.fillRect(0, 0, W, H);
+  }
+  return c;
+}
+/** Opaque grayscale mask (white rounded-rect on black) — its luma becomes the screen's alpha via
+ *  `alphamerge`, rounding the corners. Must be OPAQUE (not transparent) so ffmpeg reads a clean luma. */
+function maskPng(w, h, radius) {
+  const c = createCanvas(w, h);
+  const ctx = c.getContext('2d');
+  ctx.fillStyle = '#000';
+  ctx.fillRect(0, 0, w, h);
+  roundRectPath(ctx, 0, 0, w, h, radius);
+  ctx.fillStyle = '#fff';
+  ctx.fill();
+  return c;
+}
+/** A soft drop-shadow for the floating screen, at its placed rect, on a transparent full frame. */
+function shadowPng(W, H, x, y, w, h, radius, alpha) {
+  const c = createCanvas(W, H);
+  const ctx = c.getContext('2d');
+  ctx.save();
+  ctx.shadowColor = `rgba(0,0,0,${alpha})`;
+  ctx.shadowBlur = Math.round(W * 0.045);
+  ctx.shadowOffsetY = Math.round(W * 0.012);
+  roundRectPath(ctx, x, y, w, h, radius);
+  ctx.fillStyle = '#000';
+  ctx.fill();
+  ctx.restore();
+  return c;
+}
+/** iPhone frame BACK plate: drop shadow + black unibody at the body rect (its screen area is then covered
+ *  by the clip). Proportions mirror `frames.mjs` drawPhoneFrame so the reel matches the framed screenshots. */
+function frameBackPng(W, H, bx, by, bw, bh, bodyRadius, screenW) {
+  const c = createCanvas(W, H);
+  const ctx = c.getContext('2d');
+  ctx.save();
+  ctx.shadowColor = 'rgba(0,0,0,0.4)';
+  ctx.shadowBlur = Math.round(screenW * 0.09);
+  ctx.shadowOffsetY = Math.round(screenW * 0.035);
+  roundRectPath(ctx, bx, by, bw, bh, bodyRadius);
+  ctx.fillStyle = '#0b0b0a';
+  ctx.fill();
+  ctx.restore();
+  return c;
+}
+/** iPhone Dynamic Island, drawn OVER the clip (front plate). */
+function frameFrontPng(W, H, sx, sy, screenW, bezel) {
+  const c = createCanvas(W, H);
+  const ctx = c.getContext('2d');
+  const iw = Math.round(screenW * 0.3);
+  const ih = Math.round(screenW * 0.085);
+  roundRectPath(ctx, Math.round(sx + (screenW - iw) / 2), Math.round(sy + bezel * 1.1), iw, ih, ih / 2);
+  ctx.fillStyle = '#050505';
+  ctx.fill();
+  return c;
+}
+/** A fully transparent full frame — the front plate when there's no device frame (keeps input indices stable). */
+function transparentPng(W, H) {
+  return createCanvas(W, H);
+}
+/** Bottom caption pill + subtitle (Apple launch-montage label) on a transparent full frame. */
+function captionPng(W, H, caption, th, capCenterY) {
+  const c = createCanvas(W, H);
+  if (!caption || (!caption.title && !caption.sub)) return c;
+  const ctx = c.getContext('2d');
+  ctx.textAlign = 'center';
+  ctx.textBaseline = 'middle';
+  const titleSize = Math.round(Math.min(W, H * 0.9) * (th.headlineScale ?? 0.062)); // bolder headline (top listings go big)
+  const subSize = Math.round(Math.min(W, H * 0.9) * 0.033);
+  const cx = W / 2;
+  let y = capCenterY;
+  if (caption.title && th.label) {
+    // pill treatment (dark bed) — only when `label` is on; on a light matte it'd be dark-on-dark
+    ctx.font = font(titleSize, 'bold');
+    const tw = ctx.measureText(caption.title).width;
+    const padX = Math.round(titleSize * 0.7);
+    const padY = Math.round(titleSize * 0.42);
+    const pillW = tw + padX * 2;
+    const pillH = titleSize + padY * 2;
+    roundRectPath(ctx, cx - pillW / 2, y - pillH / 2, pillW, pillH, pillH / 2);
+    ctx.fillStyle = hexA(th.pillFill, th.pillOpacity);
+    ctx.fill();
+    ctx.fillStyle = th.labelColor;
+    ctx.fillText(caption.title, cx, y + 1);
+    y += pillH / 2 + subSize * 1.15;
+  } else if (caption.title) {
+    // plain bold headline (matches the light store screenshots)
+    ctx.font = font(titleSize, 'bold');
+    ctx.fillStyle = th.labelColor;
+    ctx.fillText(caption.title, cx, y);
+    y += titleSize * 0.62 + subSize * 1.15;
+  }
+  if (caption.sub) {
+    ctx.font = font(subSize, 'regular');
+    ctx.fillStyle = th.subColor;
+    for (const ln of wrapLines(ctx, caption.sub, W * 0.82)) {
+      ctx.fillText(ln, cx, y);
+      y += subSize * 1.3;
+    }
+  }
+  return c;
+}
+
+// ── Per-segment composite: one source (clip or still) floating on the matte, captioned ───────────────────
+/**
+ * Composite ONE source (video clip or still image) onto the matte for `dur` seconds → an intermediate mp4.
+ * A video plays its real motion (held on the last frame if shorter than `dur`); a still holds.
+ */
+function compositeSource({ src, dur, W, H, fps, th, tmp, idx, sub, lay, mattePath, vignettePath, captionPath }) {
+  const vid = isVideo(src);
+  const [sw, sh] = probe(src, 'stream=width,height').map(Number); // ffprobe reads video + image dims alike
+  // `bleed`: the source FILLS the whole frame (no matte / frame / shadow) — for a compliant App Store App
+  // Preview (real footage, full-bleed, no device frame). Otherwise: framed device, or a plain floating screen.
+  const bleed = !!th.bleed;
+  const framed = !bleed && th.frame && th.frame !== 'none' && th.frame !== false;
+
+  // Geometry. Framed: fit the SCREEN so the phone BODY (screen + 2×bezel ≈ 6.4%) still fits the box.
+  const [fw, fh] = bleed
+    ? [W, H]
+    : framed
+      ? fit(sw, sh, Math.round(lay.boxW / 1.064), Math.round(lay.availH / 1.064))
+      : fit(sw, sh, lay.boxW, lay.availH);
+  const bezel = framed ? Math.round(fw * 0.032) : 0;
+  const bodyW = fw + bezel * 2;
+  const bodyH = fh + bezel * 2;
+  const bodyX = bleed ? 0 : Math.round((W - bodyW) / 2);
+  const bodyY = bleed ? 0 : Math.round(lay.availTop + (lay.availH - bodyH) / 2);
+  const sx = bleed ? 0 : bodyX + bezel; // the screen (clip) top-left
+  const sy = bleed ? 0 : bodyY + bezel;
+  const screenRadius = bleed ? 0 : framed ? Math.round(fw * 0.135) : Math.round(W * th.radius);
+
+  const tag = `${idx}${sub != null ? `_${sub}` : ''}`;
+  const maskP = path.join(tmp, `mask-${tag}.png`);
+  const backP = path.join(tmp, `back-${tag}.png`); // shadow + phone body (framed) OR a plain drop shadow
+  const frontP = path.join(tmp, `front-${tag}.png`); // Dynamic Island (framed) OR transparent
+  writePng(maskPng(fw, fh, screenRadius), maskP);
+  if (framed) {
+    writePng(frameBackPng(W, H, bodyX, bodyY, bodyW, bodyH, Math.round(fw * 0.155), fw), backP);
+    writePng(frameFrontPng(W, H, sx, sy, fw, bezel), frontP);
+  } else if (bleed) {
+    writePng(transparentPng(W, H), backP); // no shadow — the source fills the frame
+    writePng(transparentPng(W, H), frontP);
+  } else {
+    writePng(shadowPng(W, H, sx, sy, fw, fh, screenRadius, th.shadow), backP);
+    writePng(transparentPng(W, H), frontP);
+  }
+  const out = path.join(tmp, `seg-${tag}.mp4`);
+
+  // A video plays its own motion; a STILL gets a slow, never-freezing push-in (a frozen still reads as
+  // dead — the Ken-Burns trap Apple avoids by keeping the camera always subtly moving).
+  const frames = Math.ceil(dur * fps) + 4;
+  const screenFilter = bleed
+    ? `[1:v]scale=${W}:${H}:force_original_aspect_ratio=increase,crop=${W}:${H},setsar=1,format=rgba[s]` // cover
+    : vid
+      ? `[1:v]scale=${fw}:${fh},setsar=1,format=rgba[s]`
+      : `[1:v]scale=${Math.round(fw * 1.14)}:${Math.round(fh * 1.14)},zoompan=z='min(zoom+0.0008,1.12)':`
+        + `d=${frames}:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':s=${fw}x${fh}:fps=${fps},setsar=1,format=rgba[s]`;
+
+  // Inputs: 0 matte · 1 src · 2 mask · 3 back(shadow+body) · 4 front(island) · 5 caption · 6 vignette
+  const srcIn = vid ? ['-i', src] : ['-loop', '1', '-i', src];
+  const args = [
+    '-loop', '1', '-i', mattePath,
+    ...srcIn,
+    '-loop', '1', '-i', maskP,
+    '-loop', '1', '-i', backP,
+    '-loop', '1', '-i', frontP,
+    '-loop', '1', '-i', captionPath,
+    '-loop', '1', '-i', vignettePath,
+    '-filter_complex',
+    [
+      screenFilter,
+      `[s][2:v]alphamerge[scr]`, //           round the screen's corners to the phone-screen radius
+      `[0:v]scale=${W}:${H},setsar=1[bg]`,
+      `[bg][3:v]overlay=0:0[b0]`, //          shadow + phone body (framed) / plain shadow
+      // the floating screen plays here; eof_action=repeat holds the last frame if the clip is shorter
+      `[b0][scr]overlay=${sx}:${sy}:eof_action=repeat[b1]`,
+      `[b1][4:v]overlay=0:0[b2]`, //          Dynamic Island over the screen (transparent if unframed)
+      `[b2][5:v]overlay=0:0[b3]`, //          caption
+      `[b3][6:v]overlay=0:0,` + //            vignette
+      `trim=0:${dur.toFixed(3)},setpts=PTS-STARTPTS,fps=${fps},format=yuv420p[v]`,
+    ].join(';'),
+    '-map', '[v]', '-t', dur.toFixed(3),
+    '-c:v', 'libx264', '-preset', 'medium', '-crf', '18', '-pix_fmt', 'yuv420p', out,
+  ];
+  ff(args);
+  return out;
+}
+
+/** Concat several already-composited sub-clips (used for an `images` segment) into one segment clip. */
+function concatClips(clips, tmp, idx) {
+  if (clips.length === 1) return clips[0];
+  const listFile = path.join(tmp, `list-${idx}.txt`);
+  fs.writeFileSync(listFile, clips.map((c) => `file '${c}'`).join('\n'));
+  const out = path.join(tmp, `seg-${idx}-joined.mp4`);
+  ff(['-f', 'concat', '-safe', '0', '-i', listFile, '-c', 'copy', out]);
+  return out;
+}
+
+/**
+ * Build one live-footage reel. `segments[]` each carry a `clip` | `image` | `images` source + `caption` +
+ * optional `palette`. Hard cuts between same-palette neighbours, a short dissolve at a palette change.
+ */
+export async function buildMontage({ segments, brand, theme, spec, music, sceneDur, bpm, beatsPerCut, transition, xfadeDur, outFile }) {
+  const th = resolveReelTheme(brand, theme);
+  const W = spec.w;
+  const H = spec.h;
+  const fps = spec.fps || 30;
+  const hold = sceneDur || (bpm ? (beatsPerCut || 4) * 60 / bpm : 3.0);
+  // Dissolve by default (Apple App-Preview style — restrained, never a jarring hard cut); `transition:'cut'`
+  // gives beat-matched hard cuts. `tail` extends each segment so the xfade always has overlap material.
+  const D = transition === 'cut' ? 0 : (xfadeDur ?? 0.3);
+  const tail = D > 0 ? D + 0.2 : 0;
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'zdymak-montage-'));
+  try {
+    const mattePath = path.join(tmp, 'matte.png');
+    const vignettePath = path.join(tmp, 'vignette.png');
+    writePng(mattePng(W, H, th), mattePath);
+    writePng(vignettePng(W, H, th.vignette), vignettePath);
+
+    // 1) composite every segment (a clip, one image, or an image sequence) → an intermediate clip.
+    const segClips = [];
+    segments.forEach((seg, i) => {
+      const hasCap = !!(seg.caption && (seg.caption.title || seg.caption.sub));
+      const lay = layout(W, H, hasCap, th.inset, th.captionAnchor === 'top');
+      const captionPath = path.join(tmp, `cap-${i}.png`);
+      writePng(captionPng(W, H, seg.caption, th, lay.capCenterY), captionPath);
+      const sources = seg.images || (seg.clip ? [seg.clip] : seg.image ? [seg.image] : []);
+      if (!sources.length) throw new Error(`reel segment[${i}] needs a clip, image, or images`);
+      const per = hold / sources.length;
+      const subs = sources.map((src, j) => compositeSource({
+        // the LAST sub of the segment carries the dissolve tail so the segment has xfade overlap material
+        src, dur: per + (j === sources.length - 1 ? tail : 0), W, H, fps, th, tmp,
+        idx: i, sub: sources.length > 1 ? j : null, lay, mattePath, vignettePath, captionPath,
+      }));
+      segClips.push({ file: concatClips(subs, tmp, i), palette: seg.palette ?? null });
+    });
+
+    // 2) assemble. NORMALIZE every segment first (fps / timebase / format / SAR) so VFR `recordVideo`
+    //    clips and image stills mix cleanly. All-hard-cut reels CONCAT end-to-end (robust — no fragile
+    //    near-zero-margin xfade offsets); a palette change uses an xfade dissolve on those boundaries.
+    const inputs = [];
+    segClips.forEach((s) => inputs.push('-i', s.file));
+
+    let filter = '';
+    segClips.forEach((_, i) => {
+      filter += `[${i}:v]fps=${fps},format=yuv420p,setsar=1,settb=AVTB,setpts=PTS-STARTPTS[n${i}];`;
+    });
+
+    let totalDur;
+    if (segClips.length === 1) {
+      filter += '[n0]copy[vout];';
+      totalDur = hold;
+    } else if (D === 0) {
+      // transition:'cut' → robust end-to-end concat (beat-matched hard cuts)
+      filter += `${segClips.map((_, i) => `[n${i}]`).join('')}concat=n=${segClips.length}:v=1[vout];`;
+      totalDur = segClips.length * hold;
+    } else {
+      // dissolve → xfade chain; each shows solo for `hold`, then a D-second cross-dissolve into the next
+      let cur = 'n0';
+      let offset = 0;
+      for (let i = 1; i < segClips.length; i++) {
+        offset += hold;
+        const out = i === segClips.length - 1 ? 'vout' : `x${i}`;
+        filter += `[${cur}][n${i}]xfade=transition=fade:duration=${D.toFixed(3)}:offset=${offset.toFixed(3)}[${out}];`;
+        cur = out;
+      }
+      totalDur = segClips.length * hold + tail;
+    }
+
+    // 3) optional music bed (trim/loop to length, fade, volume).
+    const audioArgs = [];
+    let map = ['-map', '[vout]'];
+    if (music?.path) {
+      inputs.push('-stream_loop', '-1', '-i', music.path);
+      const ai = segClips.length;
+      const fadeOut = music.fadeOut ?? 0.6;
+      const a = [
+        `[${ai}:a]atrim=${(music.offset || 0).toFixed(3)}:${(( music.offset || 0) + totalDur).toFixed(3)},asetpts=PTS-STARTPTS`,
+        `volume=${music.volume ?? 0.9}`,
+        `afade=t=in:st=0:d=${(music.fadeIn ?? 0.6)}`,
+        `afade=t=out:st=${Math.max(0, totalDur - fadeOut).toFixed(3)}:d=${fadeOut}[aout]`,
+      ].join(',');
+      filter += a;
+      map = ['-map', '[vout]', '-map', '[aout]'];
+      audioArgs.push('-c:a', 'aac', '-b:a', '192k', '-shortest');
+    }
+
+    ff([
+      ...inputs,
+      '-filter_complex', filter.replace(/;$/, ''),
+      ...map,
+      '-c:v', 'libx264', '-profile:v', spec.profile || 'high', '-level:v', spec.level || '4.0',
+      '-pix_fmt', 'yuv420p', '-crf', '17', '-preset', 'slow', '-r', String(fps), '-movflags', '+faststart',
+      ...audioArgs,
+      outFile,
+    ]);
+    return { outFile, totalDur, warnings: [] };
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}

package/src/premium.mjs

@@ -27,7 +27,7 @@ const lerp = (a, b, t) => a + (b - a) * t;
 const clamp01 = (t) => Math.min(1, Math.max(0, t));
 
 /** Defaults — brand-driven where a value is null (resolved in buildPremium against `brand`). */
-const DEFAULT_THEME = {
+export const DEFAULT_THEME = {
   bgTop: '#17161c', // matte gradient top
   bgBottom: '#0b0b0a', // matte gradient bottom
   glow: null, // radial brand glow colour → defaults to brand.sub
@@ -49,6 +49,16 @@ const DEFAULT_THEME = {
   fit: 'cover', // screenLayer image fit: 'cover' (fill + crop) | 'contain' (whole capture, matte margins)
 };
 
+/** The `theme`/`stillTheme` options an app author is expected to set — the doc-sync guard
+ *  (`scripts/check-docs.mjs`) asserts each appears in README.md/SKILL.md, so adding a public knob forces a
+ *  doc line. (The rest of DEFAULT_THEME — radius, shadow, the pill and cut knobs — are advanced/internal
+ *  and not enforced.) */
+export const PUBLIC_THEME_KEYS = [
+  'bgTop', 'bgBottom', 'glow', 'glowAlpha', 'vignette', 'inset',
+  'label', 'labelColor', 'subColor', 'handle', 'captionAnchor', 'fit',
+  'headlineScale', 'frame', 'bleed',
+];
+
 /** Average RGB of a canvas (coarse grid sample) — used to decide hard-cut vs dissolve. */
 function avgColor(canvas) {
   const { width: w, height: h } = canvas;
@@ -109,7 +119,7 @@ function drawLabel(ctx, W, H, caption, th, alpha) {
 
   // Scale type to the SHORTER edge so landscape (Mac) doesn't get huge text, and anchor high enough that
   // the pill + subtitle never clip the bottom on wide aspects.
-  const titleSize = Math.round(Math.min(W, H * 0.9) * 0.05);
+  const titleSize = Math.round(Math.min(W, H * 0.9) * (th.headlineScale ?? 0.062)); // bolder headline (top listings go big)
   const subSize = Math.round(Math.min(W, H * 0.9) * 0.033);
   const cx = W / 2;
   // Bottom by default (anchored higher on wide/landscape so the pill clears the app's own bottom UI);