zdymak 0.4.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zdymak",
-  "version": "0.4.0",
+  "version": "0.7.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": {

package/src/capture/index.mjs

@@ -19,8 +19,9 @@ import { spawn, spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { createCanvas, loadImage } from '@napi-rs/canvas';
+import { rgbPngBuffer } from '../png.mjs';
 
-/** Flatten alpha over black and rewrite as an opaque PNG (App Store & Play reject alpha on screenshots). */
+/** Flatten over black and rewrite as a NO-ALPHA RGB PNG (App Store & Play reject alpha on screenshots). */
 async function stripAlpha(file) {
   const img = await loadImage(file);
   const c = createCanvas(img.width, img.height);
@@ -28,7 +29,7 @@ async function stripAlpha(file) {
   ctx.fillStyle = '#000';
   ctx.fillRect(0, 0, img.width, img.height);
   ctx.drawImage(img, 0, 0);
-  fs.writeFileSync(file, c.toBuffer('image/png'));
+  fs.writeFileSync(file, rgbPngBuffer(c)); // colour-type-2 PNG, no alpha channel
 }
 
 function sh(cmd, args) {
@@ -68,9 +69,16 @@ function bootIosSim(flags) {
   return udid;
 }
 
+const simctlOk = () => spawnSync('xcrun', ['simctl', 'help'], { stdio: 'ignore' }).status === 0;
+
 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.');
+  if (!simctlOk()) {
+    // Common when xcode-select points at the CommandLineTools (no simctl): fall back to Xcode.app.
+    const xc = '/Applications/Xcode.app/Contents/Developer';
+    if (!process.env.DEVELOPER_DIR && fs.existsSync(xc)) process.env.DEVELOPER_DIR = xc;
+    if (!simctlOk()) {
+      throw new Error('xcrun/simctl unavailable — point DEVELOPER_DIR at Xcode (e.g. xcode-select -s /Applications/Xcode.app).');
+    }
   }
   const outDir = path.resolve(flags.out || 'shots');
   fs.mkdirSync(outDir, { recursive: true });
@@ -93,7 +101,7 @@ async function captureIos(flags) {
     }
     const states = flags.states.split(',').map((s) => s.trim()).filter(Boolean);
     const suffix = flags.suffix || '';
-    const settle = Number(flags.settle || 3);
+    const settle = Number(flags.settle || 4);
     const udid = bootIosSim(flags);
 
     if (flags.build !== undefined) {
@@ -108,9 +116,10 @@ async function captureIos(flags) {
       sh('xcrun', ['simctl', 'install', udid, app]);
     }
 
-    // Pin the canonical 9:41 marketing status bar (best-effort).
+    // Pin 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', 'charging', '--batteryLevel', '100', '--cellularBars', '4', '--wifiBars', '3'], { stdio: 'ignore' });
+      '--batteryState', 'discharging', '--batteryLevel', '100', '--cellularBars', '4', '--wifiBars', '3'], { stdio: 'ignore' });
 
     console.log(`▶︎ Driving ${states.length} screens via "${flags.arg} <id>" on ${flags.bundle}…`);
     for (const st of states) {
@@ -133,6 +142,20 @@ async function captureIos(flags) {
   console.log(`✓ ${out}  (alpha stripped, store-ready)`);
 }
 
+/** Toggle Android SystemUI Demo Mode → a clean, Play-native status bar (Google's own convention):
+ *  pinned clock, full battery UNPLUGGED (no charging), full signal/wifi, notifications hidden. */
+function androidDemo(on, flags) {
+  const b = (...args) => spawnSync('adb', ['shell', 'am', 'broadcast', '-a', 'com.android.systemui.demo', ...args], { stdio: 'ignore' });
+  if (!on) return void b('-e', 'command', 'exit');
+  spawnSync('adb', ['shell', 'settings', 'put', 'global', 'sysui_demo_allowed', '1'], { stdio: 'ignore' });
+  b('-e', 'command', 'enter');
+  b('-e', 'command', 'clock', '-e', 'hhmm', (flags.time || '09:41').replace(':', ''));
+  b('-e', 'command', 'battery', '-e', 'level', '100', '-e', 'plugged', 'false'); // full, NOT charging
+  b('-e', 'command', 'network', '-e', 'wifi', 'show', '-e', 'level', '4');
+  b('-e', 'command', 'network', '-e', 'mobile', 'show', '-e', 'datatype', 'none', '-e', 'level', '4');
+  b('-e', 'command', 'notifications', '-e', 'visible', 'false');
+}
+
 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.');
@@ -151,18 +174,69 @@ async function captureAndroid(flags) {
     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)`);
+  const grab = async (file) => {
+    const b = spawnSync('adb', ['exec-out', 'screencap', '-p'], { maxBuffer: 64 * 1024 * 1024 });
+    if (b.status !== 0) throw new Error(`adb screencap failed: ${b.stderr}`);
+    fs.writeFileSync(file, b.stdout);
+    await stripAlpha(file);
+  };
+
+  androidDemo(true, flags); // clean marketing status bar (Google convention)
+  try {
+    // Full workflow: drive the app through screens via an intent-extra HANDLE (--component + --arg).
+    if (flags.states) {
+      if (!flags.component || !flags.arg) {
+        throw new Error('android state capture needs --component <pkg/activity> and --arg <extra-key>.');
+      }
+      const states = flags.states.split(',').map((s) => s.trim()).filter(Boolean);
+      const suffix = flags.suffix || '';
+      const settle = Number(flags.settle || 4);
+      console.log(`▶︎ Driving ${states.length} screens via "--es ${flags.arg} <id>" on ${flags.component}…`);
+      for (const st of states) {
+        sh('adb', ['shell', 'am', 'start', '-n', flags.component, '--es', flags.arg, st]);
+        await sleep(settle * 1000);
+        const out = path.join(outDir, `${st}${suffix}.png`);
+        await grab(out);
+        console.log(`   ✓ ${st}${suffix}.png`);
+      }
+      console.log(`Done → ${outDir}`);
+    } else {
+      const out = path.join(outDir, `${flags.name || 'shot'}.png`);
+      await grab(out);
+      console.log(`✓ ${out}  (alpha stripped, store-ready)`);
+    }
+  } finally {
+    androidDemo(false, flags);
+  }
 }
 
+/**
+ * Platform dispatch. NOTE — there is intentionally NO `--platform macos` capture:
+ *
+ * macOS has no `simctl io screenshot` / `adb screencap` equivalent for snapshotting a *driven* app.
+ * Reading a specific native window's pixels requires a macOS TCC permission grant — either **Screen
+ * Recording** (for the `screencapture` CLI, which otherwise returns black frames) or **Accessibility**
+ * (to drive the UI + use XCUITest's own screenshot). Neither is a clean one-command capture like the
+ * mobile SDKs give us.
+ *
+ * The robust, TCC-correct way to capture a Mac app's marketing screens is an **XCUITest** run on the
+ * native-macOS build that drives the same launch-arg handle (`-marketingScreen <id>`) and saves each
+ * screen as an **XCTAttachment** — the sandboxed Mac test-runner can't write PNGs into your repo — then
+ * exports them from the `.xcresult`. That lives project-side (see Asilak's `Scripts/capture-mac.sh`,
+ * which already owns the one-time Accessibility grant + signing). zdymak still **composes** the Mac
+ * screenshots/reels from those captures (premium/bleed at 2880×1800, etc.).
+ *
+ * Folding that xcodebuild-test + xcresult-export flow into zdymak would just wrap an app-specific test
+ * with no real gain; a `screencapture` path would need a *second* TCC grant and is fragile. So Mac
+ * capture is deliberately left to the project's XCUITest script; zdymak captures iOS/Android (clean CLI)
+ * and composes every platform. (Web/Playwright capture is on the roadmap.)
+ */
 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>.');
+  if (platform === 'macos' || platform === 'mac') {
+    throw new Error('macOS capture is intentionally out of scope (see the note above runCapture): use an XCUITest capture (e.g. Scripts/capture-mac.sh) that drives the launch-arg handle + exports .xcresult attachments, then `zdymak build` composes the Mac assets.');
+  }
+  throw new Error('capture needs --platform ios|android. Boot a simulator/emulator (or connect a device) first, then run a single --name <screen> or the full-workflow form (--bundle --arg --states).');
 }

package/src/cli.mjs

@@ -23,8 +23,15 @@ function parseFlags(argv) {
   const rest = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a.startsWith('--')) flags[a.slice(2)] = argv[++i];
-    else rest.push(a);
+    if (a.startsWith('--')) {
+      const next = argv[i + 1];
+      // Boolean flag when followed by nothing or another --flag (e.g. `--build --project …`); else it
+      // takes the next token as its value. Single-dash values like `-marketingScreen` ARE values.
+      if (next === undefined || next.startsWith('--')) flags[a.slice(2)] = true;
+      else flags[a.slice(2)] = argv[++i];
+    } else {
+      rest.push(a);
+    }
   }
   return { flags, rest };
 }
@@ -72,7 +79,7 @@ async function cmdScreenshots(flags) {
   }
   console.log(`zdymak screenshots • ${cfg.devices.length} device group(s)`);
   for (const device of cfg.devices) {
-    const written = await buildDeviceScreenshots({ device, brand: cfg.brand, theme: device.theme ?? cfg.theme, outDir });
+    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'}`);
   }
   console.log('Done.');
@@ -96,7 +103,7 @@ async function cmdBuild(flags) {
       }
     }
     if (device.screenshots.length) {
-      const written = await buildDeviceScreenshots({ device, brand: cfg.brand, theme: device.theme ?? cfg.theme, outDir });
+      const written = await buildDeviceScreenshots({ device, brand: cfg.brand, theme: device.theme ?? cfg.stillTheme ?? cfg.theme, outDir });
       console.log(`  • ${device.name} screenshots: ${written.length}${written.length ? '' : ' — no captures found, skipped'}`);
     }
   }

package/src/config.mjs

@@ -88,7 +88,8 @@ export async function loadConfig(configPath) {
     sceneDur: raw.sceneDur ?? 3.1,
     xfade: raw.xfade ?? 0.32,
     timing: raw.timing, // reel-mode timeline override { coldOpen, scene, endCard, xfade }
-    theme: raw.theme, // premium-technique styling override (matte, vignette, label, cuts) — defaults apply
+    theme: raw.theme, // premium-technique styling override for VIDEOS (matte, vignette, label, cuts)
+    stillTheme: raw.stillTheme, // screenshot-only matte override; falls back to `theme` when unset
     out: path.resolve(baseDir, raw.out || 'store-assets'),
     baseDir,
   };

package/src/premium.mjs

@@ -45,6 +45,8 @@ const DEFAULT_THEME = {
   cutHard: 0.05, // dissolve seconds when adjacent screens share a palette (≈ hard cut)
   cutSoft: 0.24, // dissolve seconds at a palette shift
   cutThreshold: 42, // RGB-distance above which a boundary counts as a palette shift
+  captionAnchor: 'bottom', // 'top' places the caption above the device (the bright store-shot layout)
+  fit: 'cover', // screenLayer image fit: 'cover' (fill + crop) | 'contain' (whole capture, matte margins)
 };
 
 /** Average RGB of a canvas (coarse grid sample) — used to decide hard-cut vs dissolve. */
@@ -110,8 +112,10 @@ function drawLabel(ctx, W, H, caption, th, alpha) {
   const titleSize = Math.round(Math.min(W, H * 0.9) * 0.05);
   const subSize = Math.round(Math.min(W, H * 0.9) * 0.033);
   const cx = W / 2;
-  // Anchor higher on wide (landscape) aspects so the pill + subtitle clear the app's own bottom UI.
-  let y = (W > H ? 0.7 : 0.82) * H;
+  // Bottom by default (anchored higher on wide/landscape so the pill clears the app's own bottom UI);
+  // captionAnchor:'top' puts it above the device — the bright store-shot layout.
+  const topCaption = th.captionAnchor === 'top';
+  let y = topCaption ? H * 0.085 : (W > H ? 0.7 : 0.82) * H;
 
   if (caption.title && th.label) {
     ctx.font = font(titleSize, 'bold');
@@ -167,12 +171,29 @@ export function resolvePremiumTheme(brand, theme) {
   return th;
 }
 
-/** The floating, inset, rounded, shadowed app-screen layer on its own transparent canvas. */
+/** The floating, inset, rounded, shadowed app-screen layer on its own transparent canvas.
+ *  fit 'cover' fills the inset box (crops overflow); fit 'contain' shows the WHOLE capture — the card
+ *  shrinks to the capture's aspect and floats with matte margins (correct for a Mac window on the matte,
+ *  where a cover-crop would slice off the title bar / traffic lights). */
 function screenLayer(W, H, img, th) {
-  const insetW = Math.round(W * th.inset);
-  const insetH = Math.round(H * th.inset);
-  const insetX = Math.round((W - insetW) / 2);
-  const insetY = Math.round((H - insetH) / 2);
+  // Reserve headroom for a top caption so the window floats BELOW it (else it covers the headline).
+  const topCaption = th.captionAnchor === 'top';
+  const bandTop = topCaption ? H * 0.18 : 0;
+  const bandH = (topCaption ? 0.8 : 1) * H;
+  const boxW = Math.round(W * th.inset);
+  const boxH = Math.round(bandH * th.inset);
+  const ia = img.height / img.width;
+  let dw = boxW;
+  let dh = boxH;
+  if (th.fit === 'contain') {
+    dh = boxW * ia; // fit width, then clamp height so the whole capture fits the box
+    if (dh > boxH) {
+      dh = boxH;
+      dw = boxH / ia;
+    }
+  }
+  const dx = Math.round((W - dw) / 2);
+  const dy = Math.round(bandTop + (bandH - dh) / 2);
   const radius = Math.round(W * th.radius);
   const layer = createCanvas(W, H);
   const lctx = layer.getContext('2d');
@@ -180,14 +201,15 @@ function screenLayer(W, H, img, th) {
   lctx.shadowColor = `rgba(0,0,0,${th.shadow})`;
   lctx.shadowBlur = Math.round(W * 0.05);
   lctx.shadowOffsetY = Math.round(W * 0.012);
-  roundRectPath(lctx, insetX, insetY, insetW, insetH, radius);
+  roundRectPath(lctx, dx, dy, dw, dh, radius);
   lctx.fillStyle = '#000';
   lctx.fill();
   lctx.restore();
   lctx.save();
-  roundRectPath(lctx, insetX, insetY, insetW, insetH, radius);
+  roundRectPath(lctx, dx, dy, dw, dh, radius);
   lctx.clip();
-  lctx.drawImage(coverCanvas(img, insetW, insetH), insetX, insetY);
+  // The card now matches the draw aspect, so cover here fills it exactly (no crop for 'contain').
+  lctx.drawImage(coverCanvas(img, dw, dh), dx, dy);
   lctx.restore();
   return layer;
 }
@@ -196,17 +218,22 @@ function screenLayer(W, H, img, th) {
  *  drawn inside a device bezel floating on the matte; otherwise it's the plain rounded inset. */
 export function premiumStill({ W, H, img, caption, brand, theme, frame }) {
   const th = resolvePremiumTheme(brand, theme);
+  // Store-shot smart defaults (each overridable via `theme`): headline sits ON TOP; a frameless window
+  // (e.g. Mac) shows the WHOLE capture instead of cropping its title bar.
+  if (theme?.captionAnchor === undefined) th.captionAnchor = 'top';
+  if (!frame && theme?.fit === undefined) th.fit = 'contain';
   const c = createCanvas(W, H);
   const ctx = c.getContext('2d');
   paintMatte(ctx, W, H, th);
 
+  const topCaption = th.captionAnchor === 'top';
   const drawFrame = frame ? frameFor(frame) : null;
   if (drawFrame) {
-    const cy = H * 0.42; // sit high so the framed body clears the bottom label
+    const cy = H * (topCaption ? 0.57 : 0.42); // drop the device when the caption sits on top
     if (frame === 'watch') {
       drawFrame(ctx, img, W / 2, cy, Math.min(W, H) * 0.6);
     } else {
-      const budgetH = H * 0.64; // vertical room for the device body
+      const budgetH = H * (topCaption ? 0.66 : 0.64); // vertical room for the device body
       const screenW = Math.min(budgetH / (img.height / img.width), W * 0.8);
       drawFrame(ctx, img, W / 2, cy, screenW);
     }

package/src/screenshots.mjs

@@ -27,8 +27,10 @@ export async function buildDeviceScreenshots({ device, brand, theme, outDir }) {
     const spec = IMAGE_TARGETS[shot.target];
     if (!spec) throw new Error(`Unknown image target "${shot.target}" (device: ${device.name})`);
     const [W, H] = targetSize(spec, shot.size);
-    const style = shot.style || 'premium';
     const frame = shot.frame || inferFrame(shot.target); // device bezel for the `framed` style
+    // Infer the style from the target: a framed device (phone/tablet/watch) → 'framed'; a frameless
+    // target (Mac/desktop) → 'premium' (window on the matte). Overridable per shot (e.g. Watch → 'bleed').
+    const style = shot.style || (frame ? 'framed' : 'premium');
 
     // Feature graphic (Play banner) is a single branded image, not a per-scene shot.
     if (spec.graphic) {