zdymak 0.7.0 → 0.13.0

package/src/effects.mjs

@@ -0,0 +1,335 @@
+/**
+ * EFFECT REGISTRY — per-scene looks for the reel.
+ *
+ * An effect has two optional halves, either of which may be omitted:
+ *
+ *   { label, filter, overlay(ctx, { W, H, t, p }) }
+ *
+ *   filter  — a CSS filter string applied to the CAPTURE as it's drawn (colour grading)
+ *   overlay — drawn over the finished frame (vignette, grain, particles, light)
+ *
+ * `t` is elapsed seconds within the scene and `p` its 0→1 progress, so overlays can animate. Everything
+ * random here is derived from a hashed index, never `Math.random()` — a re-render must be identical to
+ * the last one or you can't diff two versions of a video.
+ *
+ * ── Where these belong ──────────────────────────────────────────────────────────────────────────
+ * Effects are a REEL/social-ad feature and are deliberately not applied to store screenshots. Google
+ * requires Play screenshots to show the app interface unaltered, and a graded or grain-covered UI
+ * misrepresents what the user will see. Grade your ads, not your store listing.
+ *
+ * Ported from uspamin's collage effects (CSS filters + React overlay panes) onto Skia canvas ops.
+ */
+import { hexA } from './canvas.mjs';
+import { softPeak } from './easings.mjs';
+
+/** Deterministic pseudo-random in [0,1). */
+const rnd = (n) => {
+  const x = Math.sin(n * 12.9898) * 43758.5453;
+  return x - Math.floor(x);
+};
+
+/** Radial gradient helper. */
+function radial(ctx, cx, cy, r, stops) {
+  const g = ctx.createRadialGradient(cx, cy, 0, cx, cy, r);
+  for (const [at, colour] of stops) g.addColorStop(at, colour);
+  return g;
+}
+
+/** Draw an overlay pass with a blend mode + alpha, then restore. */
+function blended(ctx, mode, alpha, draw) {
+  ctx.save();
+  ctx.globalCompositeOperation = mode;
+  ctx.globalAlpha = alpha;
+  draw(ctx);
+  ctx.restore();
+}
+
+/** A field of drifting particles — the shared engine behind snow / sparkles / hearts / confetti. */
+function particles(ctx, { W, H, t }, { count, seed = 0, speed, size, drift = 0.4, draw }) {
+  for (let i = 0; i < count; i++) {
+    const s = i + seed;
+    const x0 = rnd(s) * W;
+    const phase = rnd(s + 101);
+    // Floor-mod, NOT `%`: JS remainder keeps the dividend's sign, so an upward field (negative speed)
+    // wraps into [-1.2, 0) and the particle leaves the frame forever instead of re-entering from below.
+    const cycle = ((((rnd(s + 7) + (t * speed) / H + phase) % 1.2) + 1.2) % 1.2);
+    const y = cycle * H - H * 0.1;
+    const x = x0 + Math.sin(t * 0.6 + phase * Math.PI * 2) * W * drift * 0.06;
+    draw(ctx, x, y, size * (0.6 + rnd(s + 31) * 0.8), s);
+  }
+}
+
+/** Accent colour for effects that tint: the consuming project's brand, not zdymak's own greens. */
+const accent = (o, fallback = '#ffffff') => o?.brand?.sub || fallback;
+
+export const EFFECTS = {
+  none: { label: 'No effect' },
+
+  // ── Colour grades (filter only — no per-frame cost) ────────────────────────────────────────────
+  bw: { label: 'Black & white', filter: 'grayscale(1) contrast(1.05)' },
+  sepia: { label: 'Sepia', filter: 'sepia(0.75) contrast(1.02)' },
+  cool: { label: 'Cool cast', filter: 'saturate(1.05) hue-rotate(-8deg) brightness(1.02)' },
+  vibrant: { label: 'Vibrant', filter: 'saturate(1.35) contrast(1.06)' },
+  'soft-faded': {
+    label: 'Soft faded film',
+    filter: 'contrast(0.92) brightness(1.06) saturate(0.9)',
+    overlay: (ctx, { W, H }) => blended(ctx, 'source-over', 0.06, (c) => {
+      c.fillStyle = '#fff8f0';
+      c.fillRect(0, 0, W, H);
+    }),
+  },
+  'warm-film': {
+    label: 'Warm film',
+    filter: 'sepia(0.22) saturate(1.12) contrast(1.03)',
+    overlay: (ctx, { W, H }) => blended(ctx, 'soft-light', 0.35, (c) => {
+      c.fillStyle = '#ffb367';
+      c.fillRect(0, 0, W, H);
+    }),
+  },
+  duotone: {
+    label: 'Duotone',
+    filter: 'grayscale(1) contrast(1.1)',
+    overlay(ctx, { W, H }) {
+      blended(ctx, 'multiply', 0.55, (c) => { c.fillStyle = '#2b1e5c'; c.fillRect(0, 0, W, H); });
+      blended(ctx, 'screen', 0.35, (c) => { c.fillStyle = '#22c55e'; c.fillRect(0, 0, W, H); });
+    },
+  },
+
+  // ── Optical ────────────────────────────────────────────────────────────────────────────────────
+  vignette: {
+    label: 'Vignette — darkens the corners',
+    overlay: (ctx, { W, H }) => blended(ctx, 'source-over', 1, (c) => {
+      c.fillStyle = radial(c, W / 2, H / 2, Math.hypot(W, H) * 0.62, [
+        [0.55, 'rgba(0,0,0,0)'], [1, 'rgba(0,0,0,0.45)'],
+      ]);
+      c.fillRect(0, 0, W, H);
+    }),
+  },
+
+  'soft-glow': {
+    label: 'Soft glow — light blooms out of the highlights',
+    overlay: (ctx, { W, H }) => blended(ctx, 'screen', 0.18, (c) => {
+      c.fillStyle = radial(c, W / 2, H * 0.42, Math.hypot(W, H) * 0.5, [
+        [0, 'rgba(255,255,255,0.9)'], [1, 'rgba(255,255,255,0)'],
+      ]);
+      c.fillRect(0, 0, W, H);
+    }),
+  },
+
+  'dreamy-haze': {
+    label: 'Dreamy haze - soft-focus bloom',
+    filter: 'brightness(1.04) saturate(1.05)',
+    overlay(ctx) {
+      // A real soft focus, not a second radial white wash: `soft-glow` already owns that, and two ids
+      // rendering the same overlay is how a library gets padded rather than useful.
+      blended(ctx, 'screen', 0.2, (c) => {
+        c.filter = 'blur(26px)';
+        c.drawImage(c.canvas, 0, 0);
+      });
+    },
+  },
+
+  bokeh: {
+    label: 'Bokeh — drifting out-of-focus lights',
+    overlay: (ctx, o) => blended(ctx, 'screen', 0.5, (c) => {
+      c.filter = 'blur(6px)';
+      particles(c, o, {
+        count: 18, seed: 11, speed: -6, size: o.W * 0.05, drift: 1,
+        draw: (cc, x, y, r, s) => {
+          cc.fillStyle = hexA(s % 3 === 0 ? accent(o) : '#ffffff', 0.5 + rnd(s) * 0.4);
+          cc.beginPath();
+          cc.arc(x, y, r, 0, Math.PI * 2);
+          cc.fill();
+        },
+      });
+    }),
+  },
+
+  glare: {
+    label: 'Glare — a static lens streak',
+    overlay: (ctx, { W, H }) => blended(ctx, 'screen', 0.35, (c) => {
+      const g = c.createLinearGradient(W * 0.1, 0, W * 0.5, H);
+      g.addColorStop(0, 'rgba(255,255,255,0)');
+      g.addColorStop(0.5, 'rgba(255,255,255,0.55)');
+      g.addColorStop(1, 'rgba(255,255,255,0)');
+      c.fillStyle = g;
+      c.fillRect(0, 0, W, H);
+    }),
+  },
+
+  floodlight: {
+    label: 'Floodlight — a warm pool of stage light',
+    overlay: (ctx, { W, H }) => blended(ctx, 'screen', 0.4, (c) => {
+      c.fillStyle = radial(c, W / 2, H * 0.35, Math.hypot(W, H) * 0.55, [
+        [0, 'rgba(255,214,160,0.8)'], [1, 'rgba(255,214,160,0)'],
+      ]);
+      c.fillRect(0, 0, W, H);
+    }),
+  },
+
+  'light-leak': {
+    label: 'Light leak — warm bleed from the edge',
+    overlay: (ctx, { W, H, t }) => blended(ctx, 'screen', 0.4 + 0.15 * Math.sin(t * 0.8), (c) => {
+      const g = c.createLinearGradient(W, 0, W * 0.45, H * 0.5);
+      g.addColorStop(0, 'rgba(255,170,90,0.75)');
+      g.addColorStop(1, 'rgba(255,170,90,0)');
+      c.fillStyle = g;
+      c.fillRect(0, 0, W, H);
+    }),
+  },
+
+  // ── Film texture ───────────────────────────────────────────────────────────────────────────────
+  'film-grain': {
+    label: 'Film grain',
+    overlay(ctx, { W, H, t }) {
+      // Coarse procedural grain: a sparse field of 2px specks, re-seeded per frame so it shimmers the
+      // way real grain does. Cheaper than a turbulence texture and deterministic per frame index.
+      const frame = Math.round(t * 60); // finer than any output fps, so no frame reuses a pattern
+      blended(ctx, 'overlay', 0.5, (c) => {
+        for (let i = 0; i < 1400; i++) {
+          const s = i + frame * 1400;
+          c.fillStyle = rnd(s + 5) > 0.5 ? 'rgba(255,255,255,0.5)' : 'rgba(0,0,0,0.5)';
+          c.fillRect(rnd(s) * W, rnd(s + 2) * H, 2, 2);
+        }
+      });
+    },
+  },
+
+  scanlines: {
+    label: 'Scanlines — CRT texture',
+    overlay: (ctx, { W, H }) => blended(ctx, 'overlay', 0.22, (c) => {
+      c.fillStyle = '#000000';
+      for (let y = 0; y < H; y += 4) c.fillRect(0, y, W, 2);
+    }),
+  },
+
+  'dust-scratches': {
+    label: 'Dust & scratches — projected-print wear',
+    overlay(ctx, { W, H, t }) {
+      const frame = Math.round(t * 12);
+      blended(ctx, 'screen', 0.4, (c) => {
+        for (let i = 0; i < 3; i++) {
+          const s = i + frame * 13;
+          if (rnd(s) > 0.55) continue;
+          const x = rnd(s + 1) * W;
+          c.strokeStyle = 'rgba(255,255,255,0.35)';
+          c.lineWidth = 1 + rnd(s + 2);
+          c.beginPath();
+          c.moveTo(x, rnd(s + 3) * H * 0.4);
+          c.lineTo(x + (rnd(s + 4) - 0.5) * 12, H * (0.5 + rnd(s + 5) * 0.5));
+          c.stroke();
+        }
+        for (let i = 0; i < 14; i++) {
+          const s = i + frame * 29;
+          c.fillStyle = 'rgba(255,255,255,0.5)';
+          c.fillRect(rnd(s) * W, rnd(s + 1) * H, 2, 2);
+        }
+      });
+    },
+  },
+
+  'camera-shake': {
+    label: 'Camera shake - handheld energy',
+    overlay(ctx, { t }) {
+      // Deterministic per frame index, so a re-render is identical. The one energy tool every ad editor
+      // reaches for, and the only obvious hole in this set.
+      const f = Math.round(t * 60);
+      const dx = (rnd(f) - 0.5) * ctx.canvas.width * 0.012;
+      const dy = (rnd(f + 51) - 0.5) * ctx.canvas.width * 0.012;
+      ctx.save();
+      ctx.globalCompositeOperation = 'copy';
+      ctx.drawImage(ctx.canvas, dx, dy);
+      ctx.restore();
+    },
+  },
+
+  letterbox: {
+    label: 'Letterbox - cinematic bars',
+    overlay: (ctx, { W, H }) => blended(ctx, 'source-over', 1, (c) => {
+      const bar = Math.round(H * 0.055);
+      c.fillStyle = '#000000';
+      c.fillRect(0, 0, W, bar);
+      c.fillRect(0, H - bar, W, bar);
+    }),
+  },
+
+  // ── Particles ──────────────────────────────────────────────────────────────────────────────────
+  'falling-snow': {
+    label: 'Falling snow',
+    overlay: (ctx, o) => blended(ctx, 'source-over', 0.85, (c) => particles(c, o, {
+      count: 60, seed: 3, speed: 55, size: o.W * 0.006, drift: 1,
+      draw: (cc, x, y, r) => { cc.fillStyle = 'rgba(255,255,255,0.9)'; cc.beginPath(); cc.arc(x, y, r, 0, Math.PI * 2); cc.fill(); },
+    })),
+  },
+
+  'sparkles-fireflies': {
+    label: 'Sparkles / fireflies',
+    overlay: (ctx, o) => blended(ctx, 'screen', 0.9, (c) => particles(c, o, {
+      count: 34, seed: 21, speed: -18, size: o.W * 0.008, drift: 1.6,
+      draw: (cc, x, y, r, s) => {
+        const tw = 0.35 + 0.65 * softPeak(((o.t * 0.7 + rnd(s)) % 1));
+        cc.fillStyle = hexA('#fff7c2', tw);
+        cc.beginPath();
+        cc.arc(x, y, r, 0, Math.PI * 2);
+        cc.fill();
+      },
+    })),
+  },
+
+  'heart-drift': {
+    label: 'Drifting hearts',
+    overlay: (ctx, o) => blended(ctx, 'source-over', 0.8, (c) => particles(c, o, {
+      count: 16, seed: 41, speed: -26, size: o.W * 0.016, drift: 1.4,
+      draw: (cc, x, y, r) => {
+        cc.fillStyle = 'rgba(244,114,182,0.85)';
+        cc.beginPath();
+        for (let i = 0; i <= 24; i++) {
+          const a = (i / 24) * Math.PI * 2;
+          const hx = 16 * Math.pow(Math.sin(a), 3);
+          const hy = -(13 * Math.cos(a) - 5 * Math.cos(2 * a) - 2 * Math.cos(3 * a) - Math.cos(4 * a));
+          const px = x + (hx * r) / 16;
+          const py = y + (hy * r) / 16;
+          if (i === 0) cc.moveTo(px, py); else cc.lineTo(px, py);
+        }
+        cc.closePath();
+        cc.fill();
+      },
+    })),
+  },
+
+  'confetti-drift': {
+    label: 'Drifting confetti',
+    overlay: (ctx, o) => blended(ctx, 'source-over', 0.9, (c) => particles(c, o, {
+      count: 40, seed: 61, speed: 42, size: o.W * 0.012, drift: 1.8,
+      draw: (cc, x, y, r, s) => {
+        const colours = [accent(o, '#22c55e'), '#f59e0b', '#38bdf8', '#f472b6', '#facc15'];
+        cc.save();
+        cc.translate(x, y);
+        cc.rotate(rnd(s + 9) * Math.PI * 2 + o.t * 2);
+        cc.fillStyle = colours[s % colours.length];
+        cc.fillRect(-r / 2, -r / 4, r, r / 2);
+        cc.restore();
+      },
+    })),
+  },
+
+  'clouds-drift': {
+    label: 'Drifting clouds',
+    overlay: (ctx, o) => blended(ctx, 'screen', 0.28, (c) => {
+      c.filter = 'blur(18px)';
+      particles(c, o, {
+        count: 10, seed: 77, speed: -9, size: o.W * 0.16, drift: 2.2,
+        draw: (cc, x, y, r) => { cc.fillStyle = 'rgba(255,255,255,0.6)'; cc.beginPath(); cc.arc(x, y, r, 0, Math.PI * 2); cc.fill(); },
+      });
+    }),
+  },
+};
+
+/** Resolve an effect id, with a helpful error listing what's available. */
+export function effectFor(id) {
+  const e = EFFECTS[id || 'none'];
+  if (!e) throw new Error(`Unknown effect "${id}". Available: ${Object.keys(EFFECTS).join(', ')}.`);
+  return e;
+}
+
+export const EFFECT_IDS = Object.keys(EFFECTS);

package/src/encode.mjs

@@ -1,44 +1,70 @@
-/**
- * Shared H.264 encoder — one place every video builder (bleed / reel / premium) pipes raw RGBA frames to.
- * Handles the store-safe encode (High profile at the target level, yuv420p, faststart) and the optional
- * MUSIC bed with the same knobs across all styles: offset into the track, fade-in / fade-out, volume.
- *
- * music = { path, offset=0, fadeIn=0.6, fadeOut=0.8, volume=1 }  (all optional except path)
- */
-import { spawn } from 'node:child_process';
-import fs from 'node:fs';
-
-/** Start the ffmpeg process reading rawvideo from stdin. Returns { proc, done, hasAudio }. */
-export function spawnEncoder({ W, H, fps, spec, outFile, music, totalDur }) {
-  const hasAudio = !!(music && music.path && fs.existsSync(music.path));
-  const args = [
-    '-y', '-loglevel', 'error',
-    '-f', 'rawvideo', '-pix_fmt', 'rgba', '-s', `${W}x${H}`, '-r', String(fps), '-i', '-',
-  ];
-
-  if (hasAudio) {
-    const offset = Number(music.offset) || 0;
-    if (offset > 0) args.push('-ss', String(offset)); // seek INTO the track before it's used as input
-    args.push('-i', music.path);
-    const vol = music.volume ?? 1;
-    const fi = music.fadeIn ?? 0.6;
-    const fo = music.fadeOut ?? 0.8;
-    const outStart = Math.max(0, totalDur - fo).toFixed(2);
-    args.push('-af', `volume=${vol},afade=t=in:st=0:d=${fi},afade=t=out:st=${outStart}:d=${fo}`, '-shortest');
-  }
-
-  args.push(
-    '-c:v', 'libx264', '-profile:v', spec.profile, '-level:v', spec.level,
-    '-pix_fmt', 'yuv420p', '-crf', '17', '-maxrate', '12M', '-bufsize', '12M',
-    '-preset', 'slow', '-r', String(fps), '-movflags', '+faststart',
-    ...(hasAudio ? ['-c:a', 'aac', '-b:a', '192k'] : ['-an']),
-    outFile,
-  );
-
-  const proc = spawn(process.env.FFMPEG || 'ffmpeg', args, { stdio: ['pipe', 'inherit', 'inherit'] });
-  const done = new Promise((res, rej) => {
-    proc.on('close', (code) => (code === 0 ? res() : rej(new Error(`ffmpeg exited ${code}`))));
-    proc.on('error', (e) => rej(new Error(`ffmpeg failed to start (${e.message}). Is ffmpeg on PATH or $FFMPEG set?`)));
-  });
-  return { proc, done, hasAudio };
-}
+/**
+ * Shared H.264 encoder — one place every video builder (bleed / reel / premium) pipes raw RGBA frames to.
+ * Handles the store-safe encode (High profile at the target level, yuv420p, faststart) and the optional
+ * MUSIC bed with the same knobs across all styles: offset into the track, fade-in / fade-out, volume.
+ *
+ * music = { path, offset=0, fadeIn=0.6, fadeOut=0.8, volume=1 }  (all optional except path)
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+
+/** Start the ffmpeg process reading rawvideo from stdin. Returns { proc, done, hasAudio }. */
+/**
+ * Smallest H.264 level that fits this frame size + rate (macroblocks and MB/s per Annex A), floored at
+ * the target's own level so we never *under*-declare what a store asked for.
+ */
+function h264Level(W, H, fps, floor) {
+  const mbs = Math.ceil(W / 16) * Math.ceil(H / 16);
+  const rate = mbs * fps;
+  const TABLE = [
+    ['3.0', 1620, 40500], ['3.1', 3600, 108000], ['3.2', 5120, 216000],
+    ['4.0', 8192, 245760], ['4.1', 8192, 245760], ['4.2', 8704, 522240],
+    ['5.0', 22080, 589824], ['5.1', 36864, 983040], ['5.2', 36864, 2073600],
+    ['6.0', 139264, 4177920],
+  ];
+  const fit = TABLE.find(([, maxMbs, maxRate]) => mbs <= maxMbs && rate <= maxRate);
+  const chosen = fit ? fit[0] : '6.2';
+  return Number(chosen) > Number(floor || 0) ? chosen : floor;
+}
+
+export function spawnEncoder({ W, H, fps, spec, outFile, music, totalDur }) {
+  const hasAudio = !!(music && music.path && fs.existsSync(music.path));
+  const args = [
+    '-y', '-loglevel', 'error',
+    '-f', 'rawvideo', '-pix_fmt', 'rgba', '-s', `${W}x${H}`, '-r', String(fps), '-i', '-',
+  ];
+
+  if (hasAudio) {
+    const offset = Number(music.offset) || 0;
+    if (offset > 0) args.push('-ss', String(offset)); // seek INTO the track before it's used as input
+    args.push('-i', music.path);
+    const vol = music.volume ?? 1;
+    const fi = music.fadeIn ?? 0.6;
+    const fo = music.fadeOut ?? 0.8;
+    const outStart = Math.max(0, totalDur - fo).toFixed(2);
+    args.push('-af', `volume=${vol},afade=t=in:st=0:d=${fi},afade=t=out:st=${outStart}:d=${fo}`, '-shortest');
+  }
+
+  // LEVEL must follow the ACTUAL frame size, not the target's default. A device `size` override (e.g. the
+  // Mac reel at 2880×1800) exceeds the base target's level, and libx264 will still stamp the requested
+  // level_idc into the SPS — a stream that says it's Level 4.1 while carrying 20k macroblocks. Players
+  // mostly cope; strict validators and hardware decoders need not. Recompute, and never go below the spec.
+  const level = h264Level(W, H, fps, spec.level);
+  args.push(
+    '-c:v', 'libx264', '-profile:v', spec.profile, '-level:v', level,
+    // CRF 15, not 17: the stores re-encode whatever you upload, so the master needs headroom — flat UI
+    // gradients are exactly where banding appears after that second pass.
+    '-pix_fmt', 'yuv420p', '-crf', '15', '-maxrate', '12M', '-bufsize', '12M',
+    '-preset', 'slow', '-r', String(fps), '-movflags', '+faststart',
+    // Apple's App Preview spec: stereo AAC at 256 kbps. `-ac 2` guards a mono source.
+    ...(hasAudio ? ['-c:a', 'aac', '-b:a', '256k', '-ac', '2'] : ['-an']),
+    outFile,
+  );
+
+  const proc = spawn(process.env.FFMPEG || 'ffmpeg', args, { stdio: ['pipe', 'inherit', 'inherit'] });
+  const done = new Promise((res, rej) => {
+    proc.on('close', (code) => (code === 0 ? res() : rej(new Error(`ffmpeg exited ${code}`))));
+    proc.on('error', (e) => rej(new Error(`ffmpeg failed to start (${e.message}). Is ffmpeg on PATH or $FFMPEG set?`)));
+  });
+  return { proc, done, hasAudio };
+}

package/src/fonts.mjs

@@ -1,42 +1,42 @@
-/**
- * Font registration for the canvas renderer. Everything renders under one family name — "Brand" — so the
- * engine never branches on which file won. Resolution order:
- *   1. explicit paths the project passes in (`brand.fontPaths` — e.g. your own Inter/brand TTFs)
- *   2. the host system font: San Francisco on macOS (the Apple system face — ideal for store assets),
- *      Segoe UI on Windows, DejaVu Sans on Linux.
- * No font is bundled, so there is nothing to license or ship; macOS (where you build App Store assets)
- * always resolves to SF.
- */
-import { GlobalFonts } from '@napi-rs/canvas';
-import fs from 'node:fs';
-
-const SYSTEM_CANDIDATES = [
-  '/System/Library/Fonts/SFNS.ttf', // macOS — San Francisco (variable, all weights)
-  '/System/Library/Fonts/SFNSDisplay.ttf',
-  'C:/Windows/Fonts/segoeui.ttf', // Windows — Segoe UI
-  'C:/Windows/Fonts/segoeuib.ttf',
-  '/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf', // Linux
-  '/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf',
-];
-
-/**
- * Register the "Brand" family. `fontPaths` (optional) are tried first, in order.
- * Returns true if at least one face registered (else the canvas default is used, with a warning).
- */
-export function registerFonts(fontPaths = []) {
-  let any = false;
-  for (const p of [...fontPaths, ...SYSTEM_CANDIDATES]) {
-    if (p && fs.existsSync(p)) {
-      try {
-        GlobalFonts.registerFromPath(p, 'Brand');
-        any = true;
-      } catch {
-        /* skip unreadable */
-      }
-    }
-  }
-  if (!any) {
-    console.warn('[zdymak] No brand/system font found — captions use the canvas default. Pass brand.fontPaths to fix.');
-  }
-  return any;
-}
+/**
+ * Font registration for the canvas renderer. Everything renders under one family name — "Brand" — so the
+ * engine never branches on which file won. Resolution order:
+ *   1. explicit paths the project passes in (`brand.fontPaths` — e.g. your own Inter/brand TTFs)
+ *   2. the host system font: San Francisco on macOS (the Apple system face — ideal for store assets),
+ *      Segoe UI on Windows, DejaVu Sans on Linux.
+ * No font is bundled, so there is nothing to license or ship; macOS (where you build App Store assets)
+ * always resolves to SF.
+ */
+import { GlobalFonts } from '@napi-rs/canvas';
+import fs from 'node:fs';
+
+const SYSTEM_CANDIDATES = [
+  '/System/Library/Fonts/SFNS.ttf', // macOS — San Francisco (variable, all weights)
+  '/System/Library/Fonts/SFNSDisplay.ttf',
+  'C:/Windows/Fonts/segoeui.ttf', // Windows — Segoe UI
+  'C:/Windows/Fonts/segoeuib.ttf',
+  '/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf', // Linux
+  '/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf',
+];
+
+/**
+ * Register the "Brand" family. `fontPaths` (optional) are tried first, in order.
+ * Returns true if at least one face registered (else the canvas default is used, with a warning).
+ */
+export function registerFonts(fontPaths = []) {
+  let any = false;
+  for (const p of [...fontPaths, ...SYSTEM_CANDIDATES]) {
+    if (p && fs.existsSync(p)) {
+      try {
+        GlobalFonts.registerFromPath(p, 'Brand');
+        any = true;
+      } catch {
+        /* skip unreadable */
+      }
+    }
+  }
+  if (!any) {
+    console.warn('[zdymak] No brand/system font found — captions use the canvas default. Pass brand.fontPaths to fix.');
+  }
+  return any;
+}