zdymak 0.3.0

package/src/premium.mjs

@@ -0,0 +1,324 @@
+/**
+ * The PREMIUM technique — the Apple-marketing editing vocabulary (as codified in production
+ * "Apple-Vision-Pro-reel" ad pipelines), generalized and fully themeable.
+ *
+ * Effects applied (all tunable via `theme`, sensible brand-driven defaults if unset):
+ *   • One-device MATTE — every screen floats, gently inset, on a constant brand matte + soft radial glow,
+ *     so N different screens read as "one device, many apps" (the Apple ecosystem-reel look).
+ *   • VIGNETTE — subtle edge darkening for depth.
+ *   • Motion-then-FREEZE — an over-damped spring dolly that moves ~1s then holds ("cut on motion, rest").
+ *   • PALETTE-AWARE cuts — a near-hard cut between screens that share a palette, a soft dissolve only at a
+ *     palette shift (no decorative transitions — the #1 amateur tell).
+ *   • Label PILL — the scene title on a soft rounded pill (Apple's launch-montage app labels); optional
+ *     brand HANDLE along the top.
+ *
+ * Output is full-bleed frame at the target resolution (the app screen itself is inset on the matte, but no
+ * device bezel), H.264 High @ the target level, yuv420p, silent.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createCanvas, loadImage } from '@napi-rs/canvas';
+import { font, hexA, hexRgb, springSeries, roundRectPath, fillVerticalGradient, radialGlow, wrapLines } from './canvas.mjs';
+import { spawnEncoder } from './encode.mjs';
+import { frameFor } from './frames.mjs';
+
+const smooth = (t) => t * t * (3 - 2 * t);
+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 = {
+  bgTop: '#17161c', // matte gradient top
+  bgBottom: '#0b0b0a', // matte gradient bottom
+  glow: null, // radial brand glow colour → defaults to brand.sub
+  glowAlpha: 0.16,
+  vignette: 0.3, // 0..1 edge darkening strength
+  inset: 0.955, // screen fills this fraction of the frame width (thin matte border)
+  radius: 0.03, // screen corner radius as a fraction of frame width
+  shadow: 0.42, // floating-screen drop-shadow alpha
+  label: true, // show the bottom title pill
+  pillFill: null, // → brand.ink
+  pillOpacity: 0.9,
+  labelColor: null, // → brand.title
+  subColor: null, // → brand.sub
+  handle: null, // optional persistent top handle text (e.g. '@yourapp')
+  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
+};
+
+/** Average RGB of a canvas (coarse grid sample) — used to decide hard-cut vs dissolve. */
+function avgColor(canvas) {
+  const { width: w, height: h } = canvas;
+  const data = canvas.getContext('2d').getImageData(0, 0, w, h).data;
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  let n = 0;
+  const step = Math.max(1, Math.floor((w * h) / 4000)) * 4; // ~4k samples
+  for (let i = 0; i < data.length; i += step) {
+    r += data[i];
+    g += data[i + 1];
+    b += data[i + 2];
+    n++;
+  }
+  return [r / n, g / n, b / n];
+}
+const colorDist = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+
+/** Full-bleed cover of a source image onto a W×H canvas (crop tiny overflow). */
+function coverCanvas(img, W, H) {
+  const c = createCanvas(W, H);
+  const ctx = c.getContext('2d');
+  const ia = img.height / img.width;
+  let dw = W;
+  let dh = W * ia;
+  if (dh < H) {
+    dh = H;
+    dw = H / ia;
+  }
+  ctx.drawImage(img, (W - dw) / 2, (H - dh) / 2, dw, dh);
+  return c;
+}
+
+/** Paint the matte background (gradient + radial brand glow) onto the frame ctx. */
+function paintMatte(ctx, W, H, th) {
+  fillVerticalGradient(ctx, W, H, th.bgTop, th.bgBottom);
+  radialGlow(ctx, W * 0.5, H * 0.4, W * 0.85, th.glow, th.glowAlpha);
+}
+
+/** Radial vignette (transparent centre → dark edges) over the whole frame. */
+function paintVignette(ctx, W, H, strength) {
+  if (strength <= 0) return;
+  const g = ctx.createRadialGradient(W / 2, H / 2, Math.min(W, H) * 0.35, 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);
+}
+
+/** Bottom title pill + subtitle (Apple launch-montage label), fixed position, own fade. */
+function drawLabel(ctx, W, H, caption, th, alpha) {
+  if (alpha <= 0.01 || (!caption.title && !caption.sub)) return;
+  ctx.save();
+  ctx.globalAlpha = alpha;
+  ctx.textAlign = 'center';
+  ctx.textBaseline = 'middle';
+
+  // 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 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;
+
+  if (caption.title && th.label) {
+    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.05;
+  } else if (caption.title) {
+    ctx.font = font(titleSize, 'bold');
+    ctx.fillStyle = th.labelColor;
+    ctx.fillText(caption.title, cx, y);
+    y += titleSize * 0.9 + subSize * 1.2;
+  }
+
+  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;
+    }
+  }
+  ctx.restore();
+}
+
+/** Persistent top handle (optional brand chrome). */
+function drawHandle(ctx, W, H, text, color) {
+  if (!text) return;
+  ctx.save();
+  ctx.textAlign = 'center';
+  ctx.textBaseline = 'middle';
+  ctx.font = font(Math.round(W * 0.03), 'semibold');
+  ctx.fillStyle = hexA(color, 0.9);
+  ctx.fillText(text, W / 2, H * 0.035);
+  ctx.restore();
+}
+
+/** Resolve theme defaults against the brand (shared by the video + still renderers). */
+export function resolvePremiumTheme(brand, theme) {
+  const th = { ...DEFAULT_THEME, ...(theme || {}) };
+  th.glow = th.glow || brand.sub;
+  th.pillFill = th.pillFill || brand.ink;
+  th.labelColor = th.labelColor || brand.title;
+  th.subColor = th.subColor || brand.sub;
+  th.handle = th.handle ?? brand.handle ?? null;
+  return th;
+}
+
+/** The floating, inset, rounded, shadowed app-screen layer on its own transparent canvas. */
+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);
+  const radius = Math.round(W * th.radius);
+  const layer = createCanvas(W, H);
+  const lctx = layer.getContext('2d');
+  lctx.save();
+  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);
+  lctx.fillStyle = '#000';
+  lctx.fill();
+  lctx.restore();
+  lctx.save();
+  roundRectPath(lctx, insetX, insetY, insetW, insetH, radius);
+  lctx.clip();
+  lctx.drawImage(coverCanvas(img, insetW, insetH), insetX, insetY);
+  lctx.restore();
+  return layer;
+}
+
+/** Render ONE premium still → canvas. Static, no motion. With `frame` (phone|ipad|watch) the screen is
+ *  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);
+  const c = createCanvas(W, H);
+  const ctx = c.getContext('2d');
+  paintMatte(ctx, W, H, th);
+
+  const drawFrame = frame ? frameFor(frame) : null;
+  if (drawFrame) {
+    const cy = H * 0.42; // sit high so the framed body clears the bottom label
+    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 screenW = Math.min(budgetH / (img.height / img.width), W * 0.8);
+      drawFrame(ctx, img, W / 2, cy, screenW);
+    }
+  } else {
+    ctx.drawImage(screenLayer(W, H, img, th), 0, 0);
+  }
+
+  drawLabel(ctx, W, H, caption, th, 1);
+  paintVignette(ctx, W, H, th.vignette);
+  drawHandle(ctx, W, H, th.handle, th.labelColor);
+  return c;
+}
+
+/** Build one premium-technique video. Signature mirrors buildVideo/buildReel. */
+export async function buildPremium({ scenes, spec, brand, theme, outFile, sceneDur = 3.0, music }) {
+  if (!scenes?.length) throw new Error('buildPremium: no scenes');
+  const { w: W, h: H, fps } = spec;
+  const th = { ...DEFAULT_THEME, ...(theme || {}) };
+  th.glow = th.glow || brand.sub;
+  th.pillFill = th.pillFill || brand.ink;
+  th.labelColor = th.labelColor || brand.title;
+  th.subColor = th.subColor || brand.sub;
+  th.handle = th.handle ?? brand.handle ?? null;
+
+  const CAM = springSeries(Math.ceil(sceneDur * fps) + 2, fps, { stiffness: 55, damping: 24, mass: 1.5 });
+  const camAt = (t) => CAM[Math.min(CAM.length - 1, Math.max(0, Math.round(t * fps)))];
+
+  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);
+  const radius = Math.round(W * th.radius);
+
+  // Pre-render each scene's floating screen (cover-fit into the inset rect) onto its own transparent layer.
+  const clips = [];
+  for (const s of scenes) {
+    if (!fs.existsSync(s.image)) throw new Error(`Screenshot not found: ${s.image}`);
+    const img = await loadImage(s.image);
+    const layer = createCanvas(W, H);
+    const lctx = layer.getContext('2d');
+    // soft drop shadow
+    lctx.save();
+    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);
+    lctx.fillStyle = '#000';
+    lctx.fill();
+    lctx.restore();
+    // clip + draw the cover-fit screenshot
+    lctx.save();
+    roundRectPath(lctx, insetX, insetY, insetW, insetH, radius);
+    lctx.clip();
+    lctx.drawImage(coverCanvas(img, insetW, insetH), insetX, insetY);
+    lctx.restore();
+    clips.push({ layer, caption: { title: s.title || '', sub: s.sub || '' }, dur: sceneDur, avg: avgColor(layer) });
+  }
+
+  // Palette-aware per-boundary cut durations.
+  const xfadeIn = clips.map((c, i) => {
+    if (i === 0) return 0;
+    return colorDist(clips[i - 1].avg, c.avg) < th.cutThreshold ? th.cutHard : th.cutSoft;
+  });
+  const starts = [0];
+  for (let i = 1; i < clips.length; i++) starts.push(starts[i - 1] + clips[i - 1].dur - xfadeIn[i]);
+  const totalDur = starts[starts.length - 1] + clips[clips.length - 1].dur;
+  const totalFrames = Math.round(totalDur * fps);
+
+  const frame = createCanvas(W, H);
+  const fctx = frame.getContext('2d');
+
+  fs.mkdirSync(path.dirname(outFile), { recursive: true });
+  const { proc, done } = spawnEncoder({ W, H, fps, spec, outFile, music, totalDur });
+
+  for (let k = 0; k < totalFrames; k++) {
+    const t = k / fps;
+    // Matte + glow every frame (screens float over it).
+    paintMatte(fctx, W, H, th);
+
+    for (let i = 0; i < clips.length; i++) {
+      const start = starts[i];
+      const end = start + clips[i].dur;
+      if (t < start || t >= end) continue;
+      const localT = t - start;
+      const clipAlpha = i > 0 && localT < xfadeIn[i] ? smooth(localT / xfadeIn[i]) : 1;
+
+      // Motion-then-freeze: alternating spring push-in / pull-back, settles then holds.
+      const p = camAt(localT);
+      const z = i % 2 === 0 ? lerp(1.0, 1.05, p) : lerp(1.05, 1.0, p);
+      fctx.save();
+      fctx.globalAlpha = clipAlpha;
+      fctx.translate(W / 2, H / 2);
+      fctx.scale(z, z);
+      fctx.translate(-W / 2, -H / 2);
+      fctx.drawImage(clips[i].layer, 0, 0);
+      fctx.restore();
+
+      // Label (kinetic fade in, gentle fade before the cut) — not under the camera transform.
+      const inA = smooth(clamp01((localT - 0.1) / 0.45));
+      const outA = smooth(clamp01((clips[i].dur - localT) / 0.35));
+      drawLabel(fctx, W, H, clips[i].caption, th, clipAlpha * inA * outA);
+    }
+
+    paintVignette(fctx, W, H, th.vignette);
+    drawHandle(fctx, W, H, th.handle, th.labelColor);
+
+    const buf = Buffer.from(fctx.getImageData(0, 0, W, H).data.buffer);
+    if (!proc.stdin.write(buf)) {
+      await new Promise((r) => proc.stdin.once('drain', r));
+    }
+  }
+  proc.stdin.end();
+  await done;
+  return { outFile, totalDur, frames: totalFrames, warnings: [] };
+}

package/src/reel.mjs

@@ -0,0 +1,245 @@
+/**
+ * The REEL engine — a device-FRAMED, Apple-style "one phone, many apps" promo video for the web, social,
+ * and (via YouTube) Google Play. This is intentionally NOT an App Store App Preview: it draws an iPhone
+ * bezel + brand background + logo bookends, which Apple rejects in the App Preview slot. Use `video.mjs`
+ * (full-bleed) for App Previews and this for marketing reels.
+ *
+ * Composition (ported from a production store-asset pipeline): a captioned phone on a soft brand wash,
+ * gentle alternating Ken-Burns + cross-dissolves, bookended by a logo cold-open and end-card on a dark
+ * matte. Silent by default (commercial-music licensing is a hard rule).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createCanvas, loadImage } from '@napi-rs/canvas';
+import { font, hexA, roundRectPath, fillVerticalGradient, radialGlow, drawCaption, measureCaption } from './canvas.mjs';
+import { spawnEncoder } from './encode.mjs';
+
+const DEVICE_ASPECT = 2.165; // iPhone screen height/width (~19.5:9); screenshots are cover-fit into it.
+
+/** Default reel palette — a calm green/stone brand. Override any key via `brand.reel` in the config. */
+const DEFAULT_REEL = {
+  bgTop: '#FAFAF9', bgBottom: '#DCFCE7', glowLight: '#BBF7D0', // soft light wash for the screen scenes
+  matteTop: '#052E16', matteBottom: '#0b0b0a', glowDark: '#16A34A', // dark matte for cold-open / end-card
+  titleColor: '#1C1917', subColor: '#78716C', // captions on the light wash
+  bookendTitle: '#FAFAF9', bookendSub: '#BBF7D0', // text on the dark matte
+};
+
+const DEFAULT_TIMING = { coldOpen: 1.4, scene: 2.6, endCard: 2.4, xfade: 0.45 };
+
+const easeInOut = (t) => (t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2);
+const smooth = (t) => t * t * (3 - 2 * t);
+
+function backgroundLight(ctx, W, H, p) {
+  fillVerticalGradient(ctx, W, H, p.bgTop, p.bgBottom);
+  radialGlow(ctx, W * 0.5, H * 0.34, W * 0.85, p.glowLight, 0.5);
+}
+function backgroundDark(ctx, W, H, p) {
+  fillVerticalGradient(ctx, W, H, p.matteTop, p.matteBottom);
+  radialGlow(ctx, W * 0.5, H * 0.42, W * 0.8, p.glowDark, 0.28);
+}
+
+/** Draw a clean modern iPhone (dark unibody, thin bezel, centred Dynamic Island) with `screen` cover-fit
+ *  into the display. Geometry scales with `screenW`. */
+function drawPhone(ctx, screen, cx, cy, screenW) {
+  const screenH = screenW * DEVICE_ASPECT;
+  const bezel = Math.round(screenW * 0.032);
+  const bodyW = screenW + bezel * 2;
+  const bodyH = screenH + bezel * 2;
+  const bodyX = Math.round(cx - bodyW / 2);
+  const bodyY = Math.round(cy - bodyH / 2);
+  const screenX = bodyX + bezel;
+  const screenY = bodyY + bezel;
+  const bodyR = Math.round(screenW * 0.155);
+  const screenR = Math.round(screenW * 0.135);
+
+  ctx.save();
+  ctx.shadowColor = 'rgba(0,0,0,0.38)';
+  ctx.shadowBlur = Math.round(screenW * 0.09);
+  ctx.shadowOffsetY = Math.round(screenW * 0.035);
+  roundRectPath(ctx, bodyX, bodyY, bodyW, bodyH, bodyR);
+  ctx.fillStyle = '#0b0b0a';
+  ctx.fill();
+  ctx.restore();
+
+  ctx.save();
+  roundRectPath(ctx, bodyX + 1, bodyY + 1, bodyW - 2, bodyH - 2, bodyR - 1);
+  ctx.lineWidth = 2;
+  ctx.strokeStyle = 'rgba(255,255,255,0.06)';
+  ctx.stroke();
+  ctx.restore();
+
+  ctx.save();
+  roundRectPath(ctx, screenX, screenY, screenW, screenH, screenR);
+  ctx.clip();
+  const sAspect = screen.height / screen.width;
+  let dw = screenW;
+  let dh = screenW * sAspect;
+  if (dh < screenH) {
+    dh = screenH;
+    dw = screenH / sAspect;
+  }
+  ctx.drawImage(screen, screenX + (screenW - dw) / 2, screenY + (screenH - dh) / 2, dw, dh);
+  ctx.restore();
+
+  // Dynamic Island pill.
+  const islandW = Math.round(screenW * 0.3);
+  const islandH = Math.round(screenW * 0.085);
+  roundRectPath(ctx, Math.round(screenX + (screenW - islandW) / 2), Math.round(screenY + bezel * 1.1), islandW, islandH, islandH / 2);
+  ctx.fillStyle = '#050505';
+  ctx.fill();
+
+  return { bodyY, bodyH };
+}
+
+/** Icon + wordmark centred at (cx, y). */
+function drawLockup(ctx, logo, cx, y, iconSize, textSize, name, color) {
+  ctx.font = font(textSize, 'bold');
+  ctx.textBaseline = 'middle';
+  ctx.textAlign = 'left';
+  const gap = Math.round(iconSize * 0.32);
+  const textW = ctx.measureText(name).width;
+  const hasIcon = !!logo;
+  const total = (hasIcon ? iconSize + gap : 0) + textW;
+  const x = cx - total / 2;
+  if (hasIcon) {
+    ctx.save();
+    roundRectPath(ctx, x, y - iconSize / 2, iconSize, iconSize, iconSize * 0.22);
+    ctx.clip();
+    ctx.drawImage(logo, x, y - iconSize / 2, iconSize, iconSize);
+    ctx.restore();
+  }
+  ctx.fillStyle = color;
+  ctx.fillText(name, x + (hasIcon ? iconSize + gap : 0), y + textSize * 0.04);
+}
+
+/** A captioned phone on the light brand wash (one reel scene). */
+function renderScene(W, H, screen, caption, p, S, { zoom = 1 } = {}) {
+  const c = createCanvas(W, H);
+  const ctx = c.getContext('2d');
+  backgroundLight(ctx, W, H, p);
+
+  const bodyH = H * 0.7;
+  const screenW = (bodyH / (DEVICE_ASPECT + 0.064)) * zoom;
+  const cy = H * 0.605;
+  const { bodyY: phoneTop } = drawPhone(ctx, screen, W / 2, cy, screenW);
+
+  const titleSize = Math.round(84 * S);
+  const subSize = Math.round(45 * S);
+  const maxWidth = W * 0.84;
+  const bandTop = H * 0.07;
+  const bandH = phoneTop - bandTop - 34 * S;
+  const probe = measureCaption(ctx, { title: caption.title, subtitle: caption.sub, maxWidth, titleSize, subSize });
+  drawCaption(ctx, {
+    title: caption.title,
+    subtitle: caption.sub,
+    centerX: W / 2,
+    top: bandTop + Math.max(0, (bandH - probe) / 2),
+    maxWidth,
+    titleSize,
+    subSize,
+    titleColor: p.titleColor,
+    subColor: p.subColor,
+  });
+  return c;
+}
+
+function renderColdOpen(W, H, logo, brand, p, S) {
+  const c = createCanvas(W, H);
+  const ctx = c.getContext('2d');
+  backgroundDark(ctx, W, H, p);
+  drawLockup(ctx, logo, W / 2, H * 0.42, Math.round(200 * S), Math.round(138 * S), brand.name, p.bookendTitle);
+  if (brand.tagline) {
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'top';
+    ctx.font = font(Math.round(55 * S), 'regular');
+    ctx.fillStyle = p.bookendSub;
+    ctx.fillText(brand.tagline, W / 2, H * 0.42 + 156 * S);
+  }
+  return c;
+}
+
+function renderEndCard(W, H, logo, brand, p, S) {
+  const c = createCanvas(W, H);
+  const ctx = c.getContext('2d');
+  backgroundDark(ctx, W, H, p);
+  drawLockup(ctx, logo, W / 2, H * 0.4, Math.round(180 * S), Math.round(124 * S), brand.name, p.bookendTitle);
+  ctx.textAlign = 'center';
+  ctx.textBaseline = 'top';
+  if (brand.endline) {
+    ctx.font = font(Math.round(60 * S), 'bold');
+    ctx.fillStyle = p.bookendTitle;
+    ctx.fillText(brand.endline, W / 2, H * 0.4 + 142 * S);
+  }
+  if (brand.endsub) {
+    ctx.font = font(Math.round(45 * S), 'regular');
+    ctx.fillStyle = p.bookendSub;
+    ctx.fillText(brand.endsub, W / 2, H * 0.4 + 235 * S);
+  }
+  return c;
+}
+
+/** Build one device-framed reel. Mirrors buildVideo's signature; `spec` carries w/h/fps/profile/level. */
+export async function buildReel({ scenes, spec, brand, outFile, timing, music }) {
+  if (!scenes?.length) throw new Error('buildReel: no scenes');
+  const { w: W, h: H, fps } = spec;
+  const S = W / 1320; // scale the ported (1320-wide) type/stroke constants to any width
+  const p = { ...DEFAULT_REEL, ...(brand.reel || {}) };
+  const t = { ...DEFAULT_TIMING, ...(timing || {}) };
+
+  const logo = brand.logo && fs.existsSync(brand.logo) ? await loadImage(brand.logo) : null;
+
+  const clips = [{ canvas: renderColdOpen(W, H, logo, brand, p, S), dur: t.coldOpen }];
+  for (let i = 0; i < scenes.length; i++) {
+    const s = scenes[i];
+    if (!fs.existsSync(s.image)) throw new Error(`Screenshot not found: ${s.image}`);
+    const img = await loadImage(s.image);
+    clips.push({ canvas: renderScene(W, H, img, { title: s.title, sub: s.sub }, p, S), dur: t.scene });
+  }
+  clips.push({ canvas: renderEndCard(W, H, logo, brand, p, S), dur: t.endCard });
+
+  const xfade = t.xfade;
+  const starts = [0];
+  let acc = 0;
+  for (let i = 0; i < clips.length - 1; i++) {
+    acc += clips[i].dur - xfade;
+    starts.push(acc);
+  }
+  const totalDur = starts[starts.length - 1] + clips[clips.length - 1].dur;
+  const totalFrames = Math.round(totalDur * fps);
+
+  const frame = createCanvas(W, H);
+  const fctx = frame.getContext('2d');
+
+  fs.mkdirSync(path.dirname(outFile), { recursive: true });
+  const { proc, done } = spawnEncoder({ W, H, fps, spec, outFile, music, totalDur });
+
+  for (let k = 0; k < totalFrames; k++) {
+    const t2 = k / fps;
+    fctx.clearRect(0, 0, W, H);
+    fctx.fillStyle = p.matteBottom;
+    fctx.fillRect(0, 0, W, H);
+    for (let i = 0; i < clips.length; i++) {
+      const start = starts[i];
+      const end = start + clips[i].dur;
+      if (t2 < start || t2 >= end) continue;
+      const localT = t2 - start;
+      const prog = clips[i].dur > 0 ? localT / clips[i].dur : 0;
+      const zoomIn = i % 2 === 0;
+      const z = zoomIn ? 1.0 + 0.06 * easeInOut(prog) : 1.06 - 0.06 * easeInOut(prog);
+      let alpha = 1;
+      if (i > 0 && localT < xfade) alpha = smooth(localT / xfade);
+      const dw = W * z;
+      const dh = H * z;
+      fctx.globalAlpha = alpha;
+      fctx.drawImage(clips[i].canvas, (W - dw) / 2, (H - dh) / 2, dw, dh);
+      fctx.globalAlpha = 1;
+    }
+    const buf = Buffer.from(fctx.getImageData(0, 0, W, H).data.buffer);
+    if (!proc.stdin.write(buf)) {
+      await new Promise((r) => proc.stdin.once('drain', r));
+    }
+  }
+  proc.stdin.end();
+  await done;
+  return { outFile, totalDur, frames: totalFrames, warnings: [] };
+}

package/src/screenshots.mjs

@@ -0,0 +1,64 @@
+/**
+ * Multi-device store-screenshot generator. For each configured device group and each of its screenshot
+ * targets, renders one still per scene (in the chosen style, at the target's exact dimensions) and writes a
+ * store-safe **no-alpha PNG**. Scenes whose capture is missing for a device are skipped gracefully, so an
+ * app configures only the devices it actually ships.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { renderStill } from './still.mjs';
+import { rgbPngBuffer } from './png.mjs';
+import { IMAGE_TARGETS } from './specs.mjs';
+import { inferFrame } from './frames.mjs';
+import { buildFeatureGraphic } from './graphic.mjs';
+
+/** Resolve a concrete [w,h] for a screenshot target: explicit override → spec w/h → first accepted size. */
+export function targetSize(spec, override) {
+  if (override) return override;
+  if (spec.w && spec.h) return [spec.w, spec.h];
+  if (spec.accepts?.length) return spec.accepts[0];
+  throw new Error('screenshot target has no resolvable size');
+}
+
+/** Build every screenshot for one resolved device group → array of written file paths. */
+export async function buildDeviceScreenshots({ device, brand, theme, outDir }) {
+  const written = [];
+  for (const shot of device.screenshots || []) {
+    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
+
+    // Feature graphic (Play banner) is a single branded image, not a per-scene shot.
+    if (spec.graphic) {
+      const hero = device.scenes.find((s) => fs.existsSync(s.image));
+      if (!hero) continue;
+      const outFile = path.join(outDir, `${shot.target}.png`);
+      await buildFeatureGraphic({ W, H, brand, theme: shot.theme || theme, heroPath: hero.image, outFile, frame: frame || 'android' });
+      written.push({ file: outFile, W, H, style: 'graphic' });
+      continue;
+    }
+
+    const dir = path.join(outDir, shot.target);
+    fs.mkdirSync(dir, { recursive: true });
+
+    let n = 0;
+    for (const scene of device.scenes) {
+      if (!fs.existsSync(scene.image)) continue; // graceful: this device lacks this scene's capture
+      n++;
+      const still = await renderStill(style, {
+        W, H,
+        imgPath: scene.image,
+        caption: { title: scene.title || '', sub: scene.sub || '' },
+        brand,
+        theme: shot.theme || theme,
+        frame,
+      });
+      const file = path.join(dir, `${String(n).padStart(2, '0')}-${scene.id || n}.png`);
+      fs.writeFileSync(file, rgbPngBuffer(still));
+      written.push({ file, W, H, style });
+    }
+  }
+  return written;
+}