zdymak 0.3.0

package/src/specs.mjs

@@ -0,0 +1,88 @@
+/**
+ * Store spec matrix — the single source of truth for every store's asset requirements.
+ *
+ * VERIFY before each release: store forms change. Sources are cited inline; re-check the Apple and
+ * Google help pages when a submission bounces on dimensions.
+ */
+
+/** Video targets that produce an actual .mp4 file. */
+export const VIDEO_TARGETS = {
+  'appstore-preview': {
+    store: 'App Store',
+    label: 'App Store App Preview (iPhone 6.5" + 6.9")',
+    w: 886,
+    h: 1920,
+    fps: 30,
+    codec: 'h264',
+    profile: 'high',
+    level: '4.0', // Apple requires High @ 4.0 for App Previews
+    minSec: 15,
+    maxSec: 30,
+    slot: 'App Store Connect → your app → (localization) → App Previews. One 886×1920 file fills BOTH the 6.5" and 6.9" slots.',
+    // Apple: https://developer.apple.com/help/app-store-connect/reference/app-preview-specifications/
+  },
+  'play-promo': {
+    store: 'Google Play',
+    label: 'Google Play promo video (portrait 1080×1920 → upload to YouTube)',
+    w: 1080,
+    h: 1920,
+    fps: 30,
+    codec: 'h264',
+    profile: 'high',
+    level: '4.1', // 1080×1920@30 needs level ≥4.1
+    minSec: null,
+    maxSec: null,
+    slot: 'Play does NOT take a file: upload this to YouTube, then paste the URL in Play Console → Main store listing → Preview video.',
+    // Google: https://support.google.com/googleplay/android-developer/answer/9866151
+  },
+  'social-reel': {
+    store: 'Web / Social',
+    label: 'Device-framed promo reel (1080×1920) — website, X/IG/TikTok, or YouTube for Play',
+    w: 1080,
+    h: 1920,
+    fps: 30,
+    codec: 'h264',
+    profile: 'high',
+    level: '4.1',
+    minSec: null,
+    maxSec: null,
+    style: 'reel', // ← device bezel + brand background + logo bookends (buildReel, not buildVideo)
+    slot: 'For your website, X / Instagram / TikTok, or YouTube (Play listing). NOT the App Store App Preview slot — the device bezel is rejected there.',
+  },
+  'premium-reel': {
+    store: 'Web / Social',
+    label: 'Premium Apple-style reel (1080×1920) — matte + vignette + label pills + palette-aware cuts',
+    w: 1080,
+    h: 1920,
+    fps: 30,
+    codec: 'h264',
+    profile: 'high',
+    level: '4.1',
+    minSec: null,
+    maxSec: null,
+    style: 'premium', // ← the Apple editing-vocabulary preset (buildPremium); themeable via `theme`
+    slot: 'The "one device, many apps" marketing reel for web/social/YouTube. Full-bleed screens on a brand matte (no bezel) — but the label pill/matte make it a marketing asset, not an App Store App Preview.',
+  },
+};
+
+/** Screenshot / graphic targets that produce still images (v0.2 — dimensions locked in now). */
+export const IMAGE_TARGETS = {
+  'appstore-iphone-6.9': { store: 'App Store', w: 1320, h: 2868, alpha: false, format: 'png', label: 'iPhone 6.9" (largest — Apple scales down for smaller iPhones)' },
+  'appstore-iphone-6.5': { store: 'App Store', accepts: [[1242, 2688], [1284, 2778]], alpha: false, format: 'png', label: 'iPhone 6.5" (accepts 1242×2688 or 1284×2778)' },
+  'appstore-ipad-13': { store: 'App Store', w: 2064, h: 2752, alpha: false, format: 'png', label: 'iPad 13" (largest iPad class)' },
+  'appstore-watch': { store: 'App Store', accepts: [[422, 514], [410, 502], [416, 496], [396, 484], [368, 448], [312, 390]], alpha: false, format: 'png', label: 'Apple Watch (any one accepted size; alpha NOT allowed)' },
+  'appstore-mac': { store: 'Mac App Store', w: 2880, h: 1800, alpha: false, format: 'png', label: 'Mac (2880×1800, 16:10 landscape — largest required class)' },
+  'play-phone': { store: 'Google Play', w: 1080, h: 1920, alpha: false, format: 'png', label: 'Play phone (9:16, min 1080px, no alpha)' },
+  'play-tablet': { store: 'Google Play', w: 2560, h: 1440, alpha: false, format: 'png', label: 'Play tablet (16:9, 1080–7680px, no alpha)' },
+  'play-feature-graphic': { store: 'Google Play', w: 1024, h: 500, alpha: false, format: 'png', graphic: true, label: 'Play feature graphic (1024×500, no alpha) — brand banner, not a per-scene shot' },
+  'play-icon': { store: 'Google Play', w: 512, h: 512, alpha: true, format: 'png', label: 'Play app icon (32-bit PNG, alpha OK)' },
+};
+
+/** Resolve a video target by id, throwing a helpful error listing valid ids. */
+export function videoTarget(id) {
+  const t = VIDEO_TARGETS[id];
+  if (!t) {
+    throw new Error(`Unknown video target "${id}". Valid: ${Object.keys(VIDEO_TARGETS).join(', ')}`);
+  }
+  return t;
+}

package/src/still.mjs

@@ -0,0 +1,62 @@
+/**
+ * Still-image renderers — one store screenshot per scene, in a chosen style. Aspect-agnostic (cover-fit),
+ * so the same renderers serve iPhone, iPad, Mac and Watch dimensions.
+ *
+ *   premium — the app screen floats on a brand matte (glow + vignette) with a bottom title pill.
+ *   bleed   — the app screen fills the frame, with an optional lower-third caption. Best for Watch (raw).
+ *
+ * (Device-FRAMED stills — iPhone/iPad bezel, Mac window, Watch ring — are the next addition; `framed`
+ *  currently falls back to `bleed`.)
+ */
+import { createCanvas, loadImage } from '@napi-rs/canvas';
+import { premiumStill } from './premium.mjs';
+import { drawCaption, hexA } from './canvas.mjs';
+
+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;
+}
+
+function bleedStill({ W, H, img, caption, brand }) {
+  const c = createCanvas(W, H);
+  const ctx = c.getContext('2d');
+  ctx.fillStyle = brand.ink;
+  ctx.fillRect(0, 0, W, H);
+  ctx.drawImage(coverCanvas(img, W, H), 0, 0);
+  if (caption.title || caption.sub) {
+    const g = ctx.createLinearGradient(0, H * 0.55, 0, H);
+    g.addColorStop(0, hexA(brand.ink, 0));
+    g.addColorStop(1, hexA(brand.ink, 0.85));
+    ctx.fillStyle = g;
+    ctx.fillRect(0, H * 0.55, W, H * 0.45);
+    drawCaption(ctx, {
+      title: caption.title,
+      subtitle: caption.sub,
+      centerX: W / 2,
+      top: H * 0.78,
+      maxWidth: W * 0.86,
+      titleSize: Math.round(W * 0.066),
+      subSize: Math.round(W * 0.036),
+      titleColor: brand.title,
+      subColor: brand.sub,
+    });
+  }
+  return c;
+}
+
+/** Render one still to a canvas. `style`: premium | framed (device bezel) | bleed. */
+export async function renderStill(style, { W, H, imgPath, caption, brand, theme, frame }) {
+  const img = await loadImage(imgPath);
+  if (style === 'framed') return premiumStill({ W, H, img, caption, brand, theme, frame: frame || 'phone' });
+  if (style === 'premium') return premiumStill({ W, H, img, caption, brand, theme });
+  return bleedStill({ W, H, img, caption, brand });
+}

package/src/video.mjs

@@ -0,0 +1,240 @@
+/**
+ * The video engine — turns a list of screenshots + captions into a premium, spec-compliant store preview.
+ *
+ * Motion is deliberately cinematic, not a flat slideshow (technique study of production Apple-style reels):
+ *   • Camera = an OVER-DAMPED SPRING that eases toward the screen and SETTLES (velocity→0) — a dolly, not
+ *     a constant-rate Ken-Burns zoom. Each scene MOVES for ~1s then HOLDS ("cut on motion, rest on it").
+ *   • Motion VARIES per scene (push-in / pull-back / vertical & lateral drift) so no effect repeats.
+ *   • Captions live OUTSIDE the camera transform — steady while the screen drifts behind them (parallax),
+ *     and animate in with a small spring rise+fade (kinetic typography).
+ *
+ * Output is full-bleed (no device bezel — Apple rejects bezels in App Previews) at the target's exact
+ * resolution, H.264 High @ the target's level, yuv420p, faststart, silent.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createCanvas, loadImage } from '@napi-rs/canvas';
+import { spawnEncoder } from './encode.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));
+
+/** Numerically integrated damped spring 0→1 (semi-implicit Euler) → per-frame lookup array. Over-damped
+ *  configs glide and settle (camera); lighter damping gives a small overshoot (caption pop). */
+function springSeries(frames, fps, { stiffness = 55, damping = 24, mass = 1.5 } = {}) {
+  const dt = 1 / fps;
+  let x = 0;
+  let v = 0;
+  const out = new Array(frames);
+  for (let f = 0; f < frames; f++) {
+    const a = (stiffness * (1 - x) - damping * v) / mass;
+    v += a * dt;
+    x += v * dt;
+    out[f] = x;
+  }
+  return out;
+}
+
+/** Per-scene camera transform at spring-progress p∈[0,1]. Drifts carry a base zoom so the screen still
+ *  covers the frame when translated (no empty edge). Gentle by design (≤8% scale, ≤18px). */
+function motion(kind, p) {
+  switch (kind) {
+    case 'pushInSlow': return { scale: lerp(1.0, 1.08, p), tx: 0, ty: 0 };
+    case 'pushIn': return { scale: lerp(1.0, 1.06, p), tx: 0, ty: 0 };
+    case 'pullBack': return { scale: lerp(1.08, 1.0, p), tx: 0, ty: 0 };
+    case 'pullBackSlow': return { scale: lerp(1.07, 1.0, p), tx: 0, ty: 0 };
+    case 'driftUp': return { scale: 1.06, tx: 0, ty: lerp(16, -16, p) };
+    case 'driftDown': return { scale: 1.06, tx: 0, ty: lerp(-16, 16, p) };
+    case 'driftRight': return { scale: 1.06, tx: lerp(-16, 16, p), ty: 0 };
+    case 'driftLeft': return { scale: 1.06, tx: lerp(16, -16, p), ty: 0 };
+    case 'still': return { scale: 1.0, tx: 0, ty: 0 };
+    default: return { scale: lerp(1.0, 1.06, p), tx: 0, ty: 0 }; // sensible default = gentle push-in
+  }
+}
+
+/** A rotation of moves so a project that doesn't specify per-scene motion still gets varied rhythm. */
+const AUTO_MOVES = ['pushInSlow', 'driftUp', 'pullBack', 'pushIn', 'driftRight', 'pushIn', 'pullBackSlow'];
+
+/** Cover-fit a source image to fill W×H (crop the tiny overflow) — full-bleed, no letterbox. */
+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;
+}
+
+const font = (size, weight = 'bold') => `${weight} ${size}px Brand`;
+
+/** Word-wrap `text` to at most `maxWidth`, returning the line array (ctx.font must already be set). */
+function wrapLines(ctx, text, maxWidth) {
+  const words = String(text).split(/\s+/);
+  const lines = [];
+  let line = '';
+  for (const w of words) {
+    const test = line ? `${line} ${w}` : w;
+    if (ctx.measureText(test).width > maxWidth && line) {
+      lines.push(line);
+      line = w;
+    } else {
+      line = test;
+    }
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+
+/** Draw the legibility scrim + caption at a FIXED position (never touched by the camera transform). */
+function drawCaptionLayer(ctx, W, H, caption, brand, alpha, rise) {
+  if (alpha <= 0.001 || (!caption.title && !caption.sub)) return;
+  ctx.save();
+  ctx.globalAlpha = alpha;
+
+  // Bottom scrim: transparent → deep ink over the lower half, only where the caption sits.
+  const g = ctx.createLinearGradient(0, H * 0.5, 0, H);
+  g.addColorStop(0, hexA(brand.ink, 0));
+  g.addColorStop(0.55, hexA(brand.ink, 0.55));
+  g.addColorStop(1, hexA(brand.ink, 0.9));
+  ctx.fillStyle = g;
+  ctx.fillRect(0, H * 0.5, W, H * 0.5);
+
+  const titleSize = Math.round(W * 0.066); // 58 @ 886
+  const subSize = Math.round(W * 0.036); //   32 @ 886
+  const maxWidth = W * 0.86;
+  const cx = W / 2;
+  let y = H * 0.75 + rise;
+
+  ctx.textAlign = 'center';
+  ctx.textBaseline = 'top';
+  if (caption.title) {
+    ctx.font = font(titleSize, 'bold');
+    ctx.fillStyle = brand.title;
+    for (const line of wrapLines(ctx, caption.title, maxWidth)) {
+      ctx.fillText(line, cx, y);
+      y += Math.round(titleSize * 1.12);
+    }
+  }
+  if (caption.sub) {
+    y += Math.round(titleSize * 0.18);
+    ctx.font = font(subSize, 'regular');
+    ctx.fillStyle = brand.sub;
+    for (const line of wrapLines(ctx, caption.sub, maxWidth)) {
+      ctx.fillText(line, cx, y);
+      y += Math.round(subSize * 1.3);
+    }
+  }
+  ctx.restore();
+}
+
+/** #rrggbb + alpha → rgba() string. */
+function hexA(hex, a) {
+  const n = parseInt(String(hex).replace('#', ''), 16);
+  return `rgba(${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}, ${a})`;
+}
+
+
+/**
+ * Build one preview video.
+ * @param {object}   o
+ * @param {Array}    o.scenes    [{ image: <path>, title?, sub?, move? }]
+ * @param {object}   o.spec      one VIDEO_TARGETS entry (w,h,fps,profile,level,minSec,maxSec,label)
+ * @param {object}   o.brand     { ink, title, sub }  (hex colours)
+ * @param {string}   o.outFile   absolute path to write the .mp4
+ * @param {number}  [o.sceneDur=3.1]  seconds each scene holds
+ * @param {number}  [o.xfade=0.32]    cross-dissolve seconds
+ * @returns {Promise<{outFile, totalDur, frames, warnings}>}
+ */
+export async function buildVideo({ scenes, spec, brand, outFile, sceneDur = 3.1, xfade = 0.32, music }) {
+  if (!scenes?.length) throw new Error('buildVideo: no scenes');
+  const { w: W, h: H, fps } = spec;
+  const warnings = [];
+
+  // Springs: one slow cinematic glide for the camera, one lively rise for captions.
+  const camFrames = Math.ceil(sceneDur * fps) + 2;
+  const CAM = springSeries(camFrames, fps, { stiffness: 55, damping: 24, mass: 1.5 });
+  const CAP = springSeries(Math.ceil(0.9 * fps) + 2, fps, { stiffness: 120, damping: 18, mass: 1 });
+  const camAt = (t) => CAM[Math.min(CAM.length - 1, Math.max(0, Math.round(t * fps)))];
+  const capAt = (t) => CAP[Math.min(CAP.length - 1, Math.max(0, Math.round(t * fps)))];
+
+  // Load + full-bleed each screenshot; assign a varied move if the scene didn't specify one.
+  const clips = [];
+  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({
+      screen: coverCanvas(img, W, H),
+      caption: { title: s.title || '', sub: s.sub || '' },
+      move: s.move || AUTO_MOVES[i % AUTO_MOVES.length],
+      dur: sceneDur,
+    });
+  }
+
+  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);
+
+  if (spec.minSec && totalDur < spec.minSec) {
+    warnings.push(`Duration ${totalDur.toFixed(1)}s is under ${spec.store} minimum ${spec.minSec}s — add scenes or raise sceneDur.`);
+  }
+  if (spec.maxSec && totalDur > spec.maxSec) {
+    warnings.push(`Duration ${totalDur.toFixed(1)}s exceeds ${spec.store} maximum ${spec.maxSec}s — drop scenes or lower sceneDur.`);
+  }
+
+  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;
+    fctx.clearRect(0, 0, W, H);
+    fctx.fillStyle = brand.ink;
+    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 (t < start || t >= end) continue;
+      const localT = t - start;
+      const clipAlpha = i > 0 && localT < xfade ? smooth(localT / xfade) : 1;
+
+      // Camera: spring-eased move that settles then holds. Captions are NOT under this transform.
+      const { scale, tx, ty } = motion(clips[i].move, camAt(localT));
+      fctx.save();
+      fctx.globalAlpha = clipAlpha;
+      fctx.translate(W / 2 + tx, H / 2 + ty);
+      fctx.scale(scale, scale);
+      fctx.translate(-W / 2, -H / 2);
+      fctx.drawImage(clips[i].screen, 0, 0);
+      fctx.restore();
+
+      // Caption: kinetic rise+fade in over ~0.5s; gentle fade-out before the cut.
+      const inA = smooth(clamp01((localT - 0.12) / 0.5));
+      const rise = (1 - capAt(Math.max(0, localT - 0.12))) * 26;
+      const outA = smooth(clamp01((clips[i].dur - localT) / 0.4));
+      drawCaptionLayer(fctx, W, H, clips[i].caption, brand, clipAlpha * inA * outA, rise);
+    }
+
+    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 };
+}