zdymak 0.7.0 → 0.13.0

package/src/config.mjs

@@ -1,96 +1,159 @@
-/**
- * Config loading + normalization. A project's `zdymak.config.mjs` (or .json) is the ONLY
- * project-specific input; everything else lives in this reusable package.
- *
- * Shape (all paths are relative to the config file):
- *   export default {
- *     brand: { ink, title, sub, fontPaths? },   // hex colours; fontPaths optional custom TTFs
- *     screenshotsDir: 'marketing/ios/captures', // where the PNGs live
- *     suffix: '-light',                          // appended to scene.id → `${id}${suffix}.png`
- *     scenes: [{ id | image, title, sub, move }],// move: pushIn|pushInSlow|pullBack|driftUp|driftLeft|…
- *     targets: ['appstore-preview', 'play-promo'],
- *     sceneDur: 3.1, xfade: 0.32,
- *     out: 'store-assets',
- *   }
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-
-const DEFAULT_BRAND = {
-  ink: '#0b0b0a', title: '#F5F5F4', sub: '#BBF7D0', fontPaths: [],
-  // Reel-mode fields (device-framed marketing reel) — optional; only used by the `social-reel` target.
-  name: 'App', tagline: '', endline: '', endsub: '', logo: null, reel: {},
-};
-
-/** 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) => {
-    if (!s.image && !s.id) throw new Error(`Config error: scene[${i}] needs an "id" or an "image".`);
-    const image = s.image ? path.resolve(baseDir, s.image) : path.join(dir, `${s.id}${suffix}.png`);
-    return { id: s.id || String(i + 1), image, title: s.title || '', sub: s.sub || '', move: s.move };
-  });
-}
-
-const asList = (arr) => (arr || []).map((x) => (typeof x === 'string' ? { target: x } : x));
-
-export async function loadConfig(configPath) {
-  const abs = path.resolve(configPath);
-  if (!fs.existsSync(abs)) {
-    throw new Error(`Config not found: ${abs}\nCreate one (see the README) or pass --config <path>.`);
-  }
-  const baseDir = path.dirname(abs);
-
-  let raw;
-  if (abs.endsWith('.json')) {
-    raw = JSON.parse(fs.readFileSync(abs, 'utf8'));
-  } else {
-    const mod = await import(pathToFileURL(abs).href);
-    raw = mod.default ?? mod.config ?? mod;
-  }
-
-  const brand = { ...DEFAULT_BRAND, ...(raw.brand || {}) };
-  brand.fontPaths = (brand.fontPaths || []).map((p) => path.resolve(baseDir, p));
-  if (brand.logo) brand.logo = path.resolve(baseDir, brand.logo); // reel-mode logo (cold-open / end-card)
-
-  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).');
-  }
-  const scenes = resolveScenes(raw.scenes, baseDir, screenshotsDir, suffix);
-
-  // Optional music bed shared by every video target — path is relative to the config file.
-  const music = raw.music?.path ? { ...raw.music, path: path.resolve(baseDir, raw.music.path) } : undefined;
-
-  // Modular per-device config. An app lists ONLY the devices it ships; each has its own captures dir,
-  // optional scene overrides, screenshot targets (+ style) and video targets. Missing captures skip cleanly.
-  const devices = Object.entries(raw.devices || {}).map(([name, d]) => {
-    const dir = d.capturesDir ? path.resolve(baseDir, d.capturesDir) : screenshotsDir;
-    const suf = d.suffix ?? suffix;
-    return {
-      name,
-      scenes: resolveScenes(d.scenes || raw.scenes, baseDir, dir, suf),
-      screenshots: asList(d.screenshots),
-      videos: asList(d.videos),
-      theme: d.theme,
-    };
-  });
-
-  return {
-    brand,
-    scenes,
-    devices,
-    music,
-    targets: raw.targets?.length ? raw.targets : ['appstore-preview'],
-    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 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,
-  };
-}
+/**
+ * Config loading + normalization. A project's `zdymak.config.mjs` (or .json) is the ONLY
+ * project-specific input; everything else lives in this reusable package.
+ *
+ * Shape (all paths are relative to the config file):
+ *   export default {
+ *     brand: { ink, title, sub, fontPaths? },   // hex colours; fontPaths optional custom TTFs
+ *     screenshotsDir: 'marketing/ios/captures', // where the PNGs live
+ *     suffix: '-light',                          // appended to scene.id → `${id}${suffix}.png`
+ *     scenes: [{ id | image, title, sub, move }],// move: pushIn|pushInSlow|pullBack|driftUp|driftLeft|…
+ *     targets: ['appstore-preview', 'play-promo'],
+ *     sceneDur: 3.1, xfade: 0.32,
+ *     out: 'store-assets',
+ *   }
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const DEFAULT_BRAND = {
+  ink: '#0b0b0a', title: '#F5F5F4', sub: '#BBF7D0', fontPaths: [],
+  // Reel-mode fields (device-framed marketing reel) — optional; only used by the `social-reel` target.
+  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', 'captions', 'reel', 'out',
+];
+
+/**
+ * Per-locale caption tables: `captions: { de: './captions/de.json' | { sceneId: { title, sub } } }`.
+ * A JSON path is read here so a bad path fails at config load, not halfway through a render. The
+ * reserved `$brand` key carries the localized wordmark lines used by the feature graphic.
+ */
+function loadCaptions(rawCaptions, baseDir) {
+  const out = {};
+  for (const [locale, value] of Object.entries(rawCaptions)) {
+    let table = value;
+    if (typeof value === 'string') {
+      const file = path.resolve(baseDir, value);
+      if (!fs.existsSync(file)) {
+        throw new Error(`Config error: captions["${locale}"] → file not found: ${file}`);
+      }
+      try {
+        table = JSON.parse(fs.readFileSync(file, 'utf8'));
+      } catch (e) {
+        throw new Error(`Config error: captions["${locale}"] → ${file} is not valid JSON (${e.message})`);
+      }
+    }
+    if (!table || typeof table !== 'object' || Array.isArray(table)) {
+      throw new Error(`Config error: captions["${locale}"] must be a JSON path or an object of sceneId → { title, sub }.`);
+    }
+    out[locale] = table;
+  }
+  return out;
+}
+
+/**
+ * Map raw scenes → resolved scenes with absolute image paths (`${dir}/${id}${suffix}.png` or explicit).
+ *
+ * SPREAD the source scene rather than picking known keys: this used to whitelist
+ * `{id, image, title, sub, move}`, which silently swallowed every per-scene knob added since
+ * (`cut`, `effect`, `push`, `scroll`) — the config looked right, no error was raised, and the renderer
+ * just never saw them. Anything a scene carries now reaches the engine untouched.
+ */
+function resolveScenes(rawScenes, baseDir, dir, suffix) {
+  return (rawScenes || []).map((s, i) => {
+    if (!s.image && !s.id) throw new Error(`Config error: scene[${i}] needs an "id" or an "image".`);
+    const image = s.image ? path.resolve(baseDir, s.image) : path.join(dir, `${s.id}${suffix}.png`);
+    return { ...s, id: s.id || String(i + 1), image, title: s.title || '', sub: s.sub || '' };
+  });
+}
+
+const asList = (arr) => (arr || []).map((x) => (typeof x === 'string' ? { target: x } : x));
+
+export async function loadConfig(configPath) {
+  const abs = path.resolve(configPath);
+  if (!fs.existsSync(abs)) {
+    throw new Error(`Config not found: ${abs}\nCreate one (see the README) or pass --config <path>.`);
+  }
+  const baseDir = path.dirname(abs);
+
+  let raw;
+  if (abs.endsWith('.json')) {
+    raw = JSON.parse(fs.readFileSync(abs, 'utf8'));
+  } else {
+    const mod = await import(pathToFileURL(abs).href);
+    raw = mod.default ?? mod.config ?? mod;
+  }
+
+  const brand = { ...DEFAULT_BRAND, ...(raw.brand || {}) };
+  brand.fontPaths = (brand.fontPaths || []).map((p) => path.resolve(baseDir, p));
+  if (brand.logo) brand.logo = path.resolve(baseDir, brand.logo); // reel-mode logo (cold-open / end-card)
+
+  const screenshotsDir = raw.screenshotsDir ? path.resolve(baseDir, raw.screenshotsDir) : baseDir;
+  const suffix = raw.suffix ?? '';
+
+  // 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);
+
+  // Optional music bed shared by every video target — path is relative to the config file.
+  const music = raw.music?.path ? { ...raw.music, path: path.resolve(baseDir, raw.music.path) } : undefined;
+
+  // Modular per-device config. An app lists ONLY the devices it ships; each has its own captures dir,
+  // optional scene overrides, screenshot targets (+ style) and video targets. Missing captures skip cleanly.
+  const devices = Object.entries(raw.devices || {}).map(([name, d]) => {
+    const dir = d.capturesDir ? path.resolve(baseDir, d.capturesDir) : screenshotsDir;
+    const suf = d.suffix ?? suffix;
+    return {
+      name,
+      scenes: resolveScenes(d.scenes || raw.scenes, baseDir, dir, suf),
+      screenshots: asList(d.screenshots),
+      videos: asList(d.videos),
+      theme: d.theme,
+    };
+  });
+
+  // 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,
+    captions: raw.captions ? loadCaptions(raw.captions, baseDir) : undefined,
+    music,
+    // `?? ` not `?.length ?` — an explicit `targets: []` means "no top-level videos" (a devices-only
+    // config renders each device's own), whereas omitting the key entirely still gets the sane default.
+    targets: raw.targets ?? ['appstore-preview'],
+    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 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/destinations.mjs

@@ -0,0 +1,103 @@
+/**
+ * DESTINATIONS vs PRESETS — the separation this tool needed.
+ *
+ * A store *destination* answers "will this be accepted?" — pixel size, codec profile/level, duration
+ * bounds, alpha, file size. It has nothing to say about how the asset looks.
+ *
+ * A *preset* answers "how does it look?" — full-bleed, device-framed, or the premium matte treatment —
+ * and carries our opinionated defaults for motion. It has nothing to say about what a store accepts.
+ *
+ * They were previously welded together in one `target` id, so "the premium look at Play dimensions" or
+ * "App Store validation with my own transitions" were unsayable. Now:
+ *
+ *   videos: [{ destination: 'appstore-preview', preset: 'premium', transitions: ['blur-dissolve'] }]
+ *   videos: [{ target: 'appstore-preview' }]   // shorthand — resolves to the pair above's defaults
+ *
+ * `target` remains a first-class shorthand: every existing config keeps working unchanged.
+ */
+import { VIDEO_TARGETS, IMAGE_TARGETS } from './specs.mjs';
+
+/** How an asset is rendered. Independent of where it's going. */
+export const PRESETS = {
+  'full-bleed': {
+    label: 'Full-bleed — the screen fills the frame, no bezel (required for App Previews)',
+    engine: 'video',
+  },
+  framed: {
+    label: 'Device-framed — bezel + brand wash + logo bookends (marketing reels)',
+    engine: 'reel',
+  },
+  premium: {
+    label: 'Premium — the screen floats on a brand matte, Apple editing vocabulary',
+    engine: 'premium',
+  },
+};
+
+/** The preset each legacy target implied, so `target:` keeps behaving exactly as before. */
+const TARGET_PRESET = {
+  'appstore-preview': 'full-bleed',
+  'appstore-preview-ipad': 'full-bleed',
+  'appstore-preview-mac': 'full-bleed',
+  'play-promo': 'full-bleed',
+  'social-reel': 'framed',
+  'premium-reel': 'premium',
+};
+
+/**
+ * Normalize a video entry into `{ destination, preset, size, theme, transitions, effects }`.
+ * Accepts the shorthand (`{ target }`) or the split form (`{ destination, preset }`).
+ */
+export function resolveVideo(entry) {
+  const e = typeof entry === 'string' ? { target: entry } : entry || {};
+  const destId = e.destination || e.target;
+  if (!destId) {
+    throw new Error("A video entry needs `destination` (or the `target` shorthand). See `zdymak specs`.");
+  }
+  const destination = VIDEO_TARGETS[destId];
+  if (!destination) {
+    throw new Error(`Unknown video destination "${destId}". Valid: ${Object.keys(VIDEO_TARGETS).join(', ')}`);
+  }
+  const presetId = e.preset || TARGET_PRESET[destId] || 'full-bleed';
+  if (!PRESETS[presetId]) {
+    throw new Error(`Unknown preset "${presetId}". Valid: ${Object.keys(PRESETS).join(', ')}`);
+  }
+  // A destination may forbid a preset: Apple rejects a device bezel in the App Preview slot, so the
+  // combination is refused here rather than at review.
+  if (destination.noFrame && presetId === 'framed') {
+    throw new Error(
+      `"${destId}" cannot use the "framed" preset — ${destination.store} rejects a device bezel in that ` +
+      'slot. Use "full-bleed" (or "premium") there, and keep the framed reel for your site and ads.',
+    );
+  }
+  return {
+    id: destId,
+    destination,
+    preset: presetId,
+    engine: PRESETS[presetId].engine,
+    size: e.size,
+    theme: e.theme,
+    transitions: e.transitions,
+    effects: e.effects,
+  };
+}
+
+/** Normalize a screenshot entry the same way (images have no preset beyond their render `style`). */
+export function resolveImage(entry) {
+  const e = typeof entry === 'string' ? { target: entry } : entry || {};
+  const destId = e.destination || e.target;
+  const destination = IMAGE_TARGETS[destId];
+  if (!destination) {
+    throw new Error(`Unknown image destination "${destId}". Valid: ${Object.keys(IMAGE_TARGETS).join(', ')}`);
+  }
+  return { ...e, target: destId, destination };
+}
+
+/**
+ * A user-supplied transition/effect palette. When a video carries `transitions: [...]`, scenes that
+ * don't name their own `cut` cycle through that list — the "bring your own vocabulary" path, as opposed
+ * to a preset's built-in choices. Deterministic by index so re-renders match.
+ */
+export function paletteAt(list, index, fallback) {
+  if (!Array.isArray(list) || !list.length) return fallback;
+  return list[index % list.length];
+}

package/src/easings.mjs

@@ -0,0 +1,74 @@
+/**
+ * Easing + numeric helpers.
+ *
+ * Ported from a production video pipeline (uspamin's collage player), where each of these earned its
+ * place by fixing a specific visible artefact rather than by being mathematically tidy:
+ *
+ *   • `smoothstep` on opacity kills the luminance valley in the middle of a cross-dissolve — a linear
+ *     blend of two images dips visibly darker at 50%.
+ *   • `qPct` quantises percentage transforms; sub-0.01% jitter makes shadows and hairlines shimmer
+ *     between frames even when the motion itself is correct.
+ *   • `softPeak` replaces `sin(x)^4`-style pulses, which land their peak on a single frame and read as
+ *     a judder rather than a swell.
+ */
+
+/** Decelerating — the default for anything entering. */
+export const easeOutCubic = (t) => 1 - Math.pow(1 - t, 3);
+
+/** Accelerating — for anything leaving. */
+export const easeInCubic = (t) => t * t * t;
+
+/** Symmetric ease; the workhorse for camera moves and slides. */
+export const easeInOutCubic = (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
+
+/** Sharper deceleration than cubic — good for a snap that still lands softly. */
+export const easeOutQuint = (t) => 1 - Math.pow(1 - t, 5);
+
+/** Gentle both ends, no overshoot. */
+export const easeInOutSine = (t) => -(Math.cos(Math.PI * t) - 1) / 2;
+
+/** Hermite S-curve. Use on OPACITY during a dissolve (see the note above). */
+export const smoothstep = (t) => {
+  const x = Math.min(1, Math.max(0, t));
+  return x * x * (3 - 2 * x);
+};
+
+/** Second-order smoothstep — zero first AND second derivative at both ends. */
+export const smootherstep = (t) => {
+  const x = Math.min(1, Math.max(0, t));
+  return x * x * x * (x * (x * 6 - 15) + 10);
+};
+
+/** Overshoot-and-settle, for something that should feel physical on arrival. */
+export const easeOutBack = (t, s = 1.2) => {
+  const c3 = s + 1;
+  return 1 + c3 * Math.pow(t - 1, 3) + s * Math.pow(t - 1, 2);
+};
+
+/** A swell that HOLDS near its peak instead of spiking on one frame. */
+export const softPeak = (t) => {
+  const x = Math.min(1, Math.max(0, t));
+  const bell = Math.sin(Math.PI * x);
+  return bell * bell * (3 - 2 * bell) * 0.5 + bell * 0.5;
+};
+
+/** Quantise a percentage to 0.01% — kills inter-frame shimmer on shadows and hairlines. */
+export const qPct = (v) => Math.round(v * 10000) / 10000;
+
+/**
+ * Overdamped spring 0→1, integrated per frame (semi-implicit Euler) — the "one earned camera move".
+ * Overdamped on purpose: it settles without a bounce, which on a product shot reads as confidence.
+ */
+export function springSeries(frames, fps, { stiffness = 26, damping = 26, mass = 1.4 } = {}) {
+  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;
+}