@kaydash9999/banker-plugins 0.27.0 → 0.28.0

package/skills/video-gen/scripts/vg-draw.mjs

@@ -0,0 +1,231 @@
+// vg-draw.mjs: drawing helpers on a CanvasKit canvas for video-gen. A Painter holds the objects one render reuses
+// (paints, laid-out paragraphs, decoded images) and frees them at the end, since CanvasKit memory is not collected.
+import { FAMILIES } from "./vg-engine.mjs";
+
+const PARA_CACHE = 600;
+const IMAGE_CACHE = 4;
+const rgb = (h) => [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+
+export class Painter {
+  constructor(CK, fonts, canvas, width, height) {
+    this.CK = CK;
+    this.fonts = fonts;
+    this.c = canvas;
+    this.W = width;
+    this.H = height;
+    // One unit is a pixel of a 1280 x 720 frame, scaled to fit this frame's shorter side.
+    this.u = Math.min(width / 1280, height / 720);
+    this.paint = new CK.Paint();
+    this.paint.setAntiAlias(true);
+    // Images get a paint of their own: the shape paint's colour alpha would fade them.
+    this.imagePaint = new CK.Paint();
+    this.imagePaint.setAntiAlias(true);
+    this.paras = new Map();
+    this.images = new Map();
+  }
+
+  color(h, a = 1) {
+    const [r, g, b] = rgb(h);
+    return this.CK.Color(r, g, b, Math.max(0, Math.min(1, a)));
+  }
+
+  clear(h) {
+    this.c.clear(this.color(h));
+  }
+
+  rect(x, y, w, h, color, alpha = 1, radius = 0) {
+    if (w <= 0 || h <= 0 || alpha <= 0) return;
+    this.paint.setStyle(this.CK.PaintStyle.Fill);
+    this.paint.setColor(this.color(color, alpha));
+    const r = this.CK.LTRBRect(x, y, x + w, y + h);
+    if (radius > 0) this.c.drawRRect(this.CK.RRectXY(r, radius, radius), this.paint);
+    else this.c.drawRect(r, this.paint);
+  }
+
+  circle(x, y, r, color, alpha = 1) {
+    if (r <= 0 || alpha <= 0) return;
+    this.paint.setStyle(this.CK.PaintStyle.Fill);
+    this.paint.setColor(this.color(color, alpha));
+    this.c.drawCircle(x, y, r, this.paint);
+  }
+
+  line(points, color, width, alpha = 1) {
+    if (points.length < 2) return;
+    // CanvasKit 0.42 paths are immutable: build one, then detach it.
+    const b = new this.CK.PathBuilder();
+    b.moveTo(points[0][0], points[0][1]);
+    for (const p of points.slice(1)) b.lineTo(p[0], p[1]);
+    const path = b.detachAndDelete();
+    this.paint.setStyle(this.CK.PaintStyle.Stroke);
+    this.paint.setStrokeWidth(width);
+    this.paint.setStrokeJoin(this.CK.StrokeJoin.Round);
+    this.paint.setStrokeCap(this.CK.StrokeCap.Round);
+    this.paint.setColor(this.color(color, alpha));
+    this.c.drawPath(path, this.paint);
+    path.delete();
+  }
+
+  /** A laid-out paragraph: size in px, bold, color hex, width px, align left|center|right. Not cached. */
+  build(text, { size, bold = false, color = "FFFFFF", width = this.W, align = "left", lineHeight = 1.25 }) {
+    const CK = this.CK;
+    const style = new CK.ParagraphStyle({
+      textAlign: { left: CK.TextAlign.Left, center: CK.TextAlign.Center, right: CK.TextAlign.Right }[align],
+      textStyle: {
+        color: this.color(color), fontFamilies: FAMILIES, fontSize: size, heightMultiplier: lineHeight,
+        fontStyle: { weight: bold ? CK.FontWeight.Bold : CK.FontWeight.Normal },
+      },
+    });
+    const b = CK.ParagraphBuilder.MakeFromFontProvider(style, this.fonts);
+    b.addText(text);
+    const p = b.build();
+    b.delete();
+    p.layout(width);
+    return p;
+  }
+
+  /**
+   * A cached paragraph. The cache keeps the most recently used PARA_CACHE entries and frees older ones, so a long
+   * video does not run the WASM heap out (a frame uses far fewer).
+   */
+  para(text, opts) {
+    const key = JSON.stringify([text, opts.size, !!opts.bold, opts.color, opts.width, opts.align, opts.lineHeight]);
+    let p = this.paras.get(key);
+    if (p) {
+      this.paras.delete(key);
+    } else {
+      p = this.build(text, opts);
+      while (this.paras.size >= PARA_CACHE) {
+        const [old, q] = this.paras.entries().next().value;
+        q.delete();
+        this.paras.delete(old);
+      }
+    }
+    this.paras.set(key, p);
+    return p;
+  }
+
+  /**
+   * Draws text at (x, y) top-left with alpha and an optional scale about its centre; returns { w, h }.
+   * transient text (a number that changes every frame) is laid out, drawn and freed, never cached.
+   */
+  text(text, x, y, opts, { alpha = 1, scale = 1, transient = false } = {}) {
+    const p = transient ? this.build(text, opts) : this.para(text, opts);
+    const { w, h } = this.size(p, opts);
+    if (alpha > 0 && text) this.place(p, { x, y, w, h, pad: opts.size }, alpha, scale);
+    if (transient) p.delete();
+    return { w, h };
+  }
+
+  /** Draws a laid-out paragraph faded and scaled about its centre, in a layer bounded by its box. */
+  place(p, { x, y, w, h, pad }, alpha, scale) {
+    const cx = x + w / 2;
+    const cy = y + h / 2;
+    const box = [cx - (w / 2) * scale - pad, cy - (h / 2) * scale - pad, cx + (w / 2) * scale + pad, cy + (h / 2) * scale + pad];
+    this.layer(alpha, () => {
+      if (scale !== 1) {
+        this.c.translate(cx, cy);
+        this.c.scale(scale, scale);
+        this.c.translate(-cx, -cy);
+      }
+      this.c.drawParagraph(p, x, y);
+    }, box);
+  }
+
+  /** Width (the text's own for left-aligned text, else the box) and height of a laid-out paragraph. */
+  size(p, opts) {
+    const left = opts.align === "left" || !opts.align;
+    return { w: left ? p.getMaxIntrinsicWidth() : opts.width ?? this.W, h: p.getHeight() };
+  }
+
+  measure(text, opts) {
+    const p = this.para(text, opts);
+    return { w: p.getMaxIntrinsicWidth(), h: p.getHeight() };
+  }
+
+  /**
+   * Runs draw() with everything it draws faded to alpha. Below 1 it draws into a layer, bounded by box
+   * [left, top, right, bottom] when given: an unbounded layer is the whole frame and costs that much per call.
+   */
+  layer(alpha, draw, box) {
+    if (alpha >= 1) {
+      this.c.save();
+      draw();
+      this.c.restore();
+      return;
+    }
+    const p = new this.CK.Paint();
+    p.setAlphaf(Math.max(0, alpha));
+    if (box) this.c.saveLayer(p, this.CK.LTRBRect(...box));
+    else this.c.saveLayer(p);
+    draw();
+    this.c.restore();
+    p.delete();
+  }
+
+  clip(x, y, w, h, draw) {
+    this.c.save();
+    this.c.clipRect(this.CK.LTRBRect(x, y, x + w, y + h), this.CK.ClipOp.Intersect, true);
+    draw();
+    this.c.restore();
+  }
+
+  /**
+   * The image for a scene, decoded once and shrunk to at most 1.15 x the frame's longer side (sharp enough for the
+   * slow zoom, small in memory); only the most recent IMAGE_CACHE images are kept.
+   */
+  decoded(img) {
+    let im = this.images.get(img.file);
+    if (im) {
+      this.images.delete(img.file);
+      this.images.set(img.file, im);
+      return im;
+    }
+    const full = this.CK.MakeImageFromEncoded(img.data);
+    if (!full) throw new Error(`그림을 풀지 못함: ${img.file}`);
+    im = this.shrink(full);
+    while (this.images.size >= IMAGE_CACHE) {
+      const [old, q] = this.images.entries().next().value;
+      q.delete();
+      this.images.delete(old);
+    }
+    this.images.set(img.file, im);
+    return im;
+  }
+
+  shrink(full) {
+    // Down to the size it covers the frame at (plus room for the zoom), so a portrait or panorama is not enlarged again.
+    const k = Math.min(1, Math.max(this.W / full.width(), this.H / full.height()) * 1.15);
+    if (k >= 1) return full;
+    const w = Math.max(1, Math.round(full.width() * k));
+    const h = Math.max(1, Math.round(full.height() * k));
+    const s = this.CK.MakeSurface(w, h);
+    s.getCanvas().drawImageRectOptions(full, this.CK.LTRBRect(0, 0, full.width(), full.height()), this.CK.LTRBRect(0, 0, w, h), this.CK.FilterMode.Linear, this.CK.MipmapMode.Linear, null);
+    const small = s.makeImageSnapshot();
+    s.delete();
+    full.delete();
+    return small;
+  }
+
+  /** Draws an image to cover the box, zoomed by zoom about a point that drifts by pan (-1..1 of the slack). */
+  image(img, box, { zoom = 1, pan = 0, alpha = 1 } = {}) {
+    const im = this.decoded(img);
+    const k = Math.max(box.w / im.width(), box.h / im.height()) * zoom;
+    const w = im.width() * k;
+    const h = im.height() * k;
+    const x = box.x + (box.w - w) / 2 + ((w - box.w) / 2) * pan;
+    const y = box.y + (box.h - h) / 2;
+    this.clip(box.x, box.y, box.w, box.h, () => this.layer(alpha, () => {
+      const src = this.CK.LTRBRect(0, 0, im.width(), im.height());
+      this.c.drawImageRectOptions(im, src, this.CK.LTRBRect(x, y, x + w, y + h), this.CK.FilterMode.Linear, this.CK.MipmapMode.None, this.imagePaint);
+    }, [box.x, box.y, box.x + box.w, box.y + box.h]));
+  }
+
+  free() {
+    for (const p of this.paras.values()) p.delete();
+    for (const im of this.images.values()) im.delete();
+    this.paras.clear();
+    this.images.clear();
+    this.paint.delete();
+    this.imagePaint.delete();
+  }
+}

package/skills/video-gen/scripts/vg-engine.mjs

@@ -0,0 +1,74 @@
+// vg-engine.mjs: the bundled render engine. Skia CanvasKit (WASM) draws each frame on the CPU and the H.264 MP4
+// encoder (WASM) writes the video: no Chrome, no ffmpeg, no native module, the same on every OS.
+// Fonts are the bundled Noto Sans and Noto Sans KR; text asks for Noto Sans first, so Latin letters, digits and
+// symbols use it and Hangul falls through to Noto Sans KR.
+// The encoder's Emscripten glue registers process handlers for uncaught exceptions and unhandled rejections when it
+// is required; the CLI handles its own rejections, so they never reach those handlers.
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const VENDOR = join(dirname(fileURLToPath(import.meta.url)), "..", "vendor");
+const require = createRequire(import.meta.url);
+export const FAMILIES = ["Noto Sans", "Noto Sans KR"];
+const FONTS = [
+  ["NotoSans-Regular.ttf", "Noto Sans"],
+  ["NotoSans-Bold.ttf", "Noto Sans"],
+  ["NotoSansKR-Regular.otf", "Noto Sans KR"],
+  ["NotoSansKR-Bold.otf", "Noto Sans KR"],
+];
+
+let engine = null;
+
+/** CanvasKit with the bundled fonts registered: { CK, fonts }. Loaded once per process. */
+export async function loadEngine() {
+  if (engine) return engine;
+  const init = require(join(VENDOR, "canvaskit", "canvaskit.js"));
+  const wasm = readFileSync(join(VENDOR, "canvaskit", "canvaskit.wasm"));
+  const CK = await init({ wasmBinary: wasm, locateFile: (f) => join(VENDOR, "canvaskit", f) });
+  const fonts = CK.TypefaceFontProvider.Make();
+  for (const [file, family] of FONTS) fonts.registerFont(readFileSync(join(VENDOR, "fonts", file)), family);
+  engine = { CK, fonts };
+  return engine;
+}
+
+/**
+ * An H.264 MP4 writer: add(rgba) per frame, then finish() returns the MP4 bytes. Width and height must be even.
+ * quality is the quantizer (10 best .. 51 smallest); speed 0 (best) .. 10 (fastest).
+ */
+export async function mp4Writer({ width, height, fps, quality = 20, speed = 5 }) {
+  const HME = require(join(VENDOR, "h264-mp4-encoder", "h264-mp4-encoder.node.js"));
+  const enc = await HME.createH264MP4Encoder();
+  enc.width = width;
+  enc.height = height;
+  enc.frameRate = fps;
+  enc.quantizationParameter = quality;
+  enc.speed = speed;
+  enc.initialize();
+  let count = 0;
+  return {
+    add(rgba) {
+      enc.addFrameRgba(rgba);
+      count++;
+    },
+    finish() {
+      enc.finalize();
+      const bytes = Buffer.from(enc.FS.readFile(enc.outputFilename));
+      enc.FS.unlink(enc.outputFilename);
+      enc.delete();
+      return { bytes, frames: count };
+    },
+    // Deleting an unfinished encoder throws inside the WASM glue; finish it first and swallow what it throws, so
+    // the caller's own error is the one reported.
+    abort() {
+      for (const step of [() => enc.finalize(), () => enc.FS.unlink(enc.outputFilename), () => enc.delete()]) {
+        try {
+          step();
+        } catch {
+          // already finished, or never started
+        }
+      }
+    },
+  };
+}

package/skills/video-gen/scripts/vg-fx.mjs

@@ -0,0 +1,106 @@
+// vg-fx.mjs: motion helpers for video-gen. Every value is a pure function of time t (seconds), so any frame can be
+// drawn on its own and the same scene gives the same video.
+//
+// rand, clamp, lerp, smooth, ramp, ease and track are taken from aimotion (github.com/kstost/cokacmotion,
+// skills/aimotion/demos/_lib/stage.js, commit c417b16), MIT License, Copyright (c) 2026 kstost; see
+// vendor/aimotion/LICENSE.md. The rest is written here after techniques its demos describe (staggered entrances
+// with an outBack overshoot, a stinger of staggered stripes, a counter whose digits roll).
+
+/** mulberry32: same seed, same sequence, every run */
+export function rand(seed = 1) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let r = Math.imul(a ^ (a >>> 15), 1 | a);
+    r = (r + Math.imul(r ^ (r >>> 7), 61 | r)) ^ r;
+    return ((r ^ (r >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+export const clamp = (v, a = 0, b = 1) => (v < a ? a : v > b ? b : v);
+export const lerp = (a, b, k) => a + (b - a) * k;
+export const smooth = (v) => {
+  const c = clamp(v);
+  return c * c * (3 - 2 * c);
+};
+/** 0 to 1 over [a, b] with smoothstep */
+export const ramp = (t, a, b) => smooth((t - a) / (b - a));
+export const ease = {
+  inOutCubic: (p) => (p < 0.5 ? 4 * p * p * p : 1 - Math.pow(-2 * p + 2, 3) / 2),
+  outCubic: (p) => 1 - Math.pow(1 - p, 3),
+  inCubic: (p) => p * p * p,
+  outExpo: (p) => (p >= 1 ? 1 : 1 - Math.pow(2, -10 * p)),
+  outBack: (p, c = 1.7) => 1 + (c + 1) * Math.pow(p - 1, 3) + c * Math.pow(p - 1, 2),
+};
+
+/**
+ * Keyframed values as a pure function of t: track([[t0, v0, ease?], [t1, v1, ease?], ...])(t). Each segment uses
+ * the ease of its end key (default inOutCubic). Values may be numbers or number arrays.
+ */
+export function track(keys) {
+  return (t) => {
+    if (t <= keys[0][0]) return keys[0][1];
+    for (let i = 1; i < keys.length; i++) {
+      const [t1, v1, e] = keys[i];
+      if (t <= t1) {
+        const [t0, v0] = keys[i - 1];
+        const p = (e || ease.inOutCubic)(clamp((t - t0) / Math.max(1e-9, t1 - t0)));
+        return Array.isArray(v0) ? v0.map((a, j) => lerp(a, v1[j], p)) : lerp(v0, v1, p);
+      }
+    }
+    return keys[keys.length - 1][1];
+  };
+}
+
+/** Progress 0..1 of item i in a staggered entrance: starts at start + i * gap, lasts dur, eased. */
+export function stagger(t, i, { start = 0, gap = 0.08, dur = 0.5, curve = ease.outCubic } = {}) {
+  return curve(clamp((t - start - i * gap) / dur));
+}
+
+/** Enter at the start and leave before the end of a scene of length d: 0..1..0 with the given in/out times. */
+export function life(t, d, fadeIn = 0.5, fadeOut = 0.4) {
+  return Math.min(smooth(t / fadeIn), smooth((d - t) / fadeOut));
+}
+
+/**
+ * A stinger: n stripes sweep across in a stair, cover the frame around the middle of dur, then leave the other way.
+ * Returns each stripe's covered span [from, to] as fractions of the width (to > from while it shows).
+ */
+export function stripes(t, dur, n = 6) {
+  const gap = dur * 0.06;
+  const half = (dur - gap * (n - 1)) / 2;
+  return Array.from({ length: n }, (_, i) => {
+    const local = t - i * gap;
+    const inP = ease.inOutCubic(clamp(local / half));
+    const outP = ease.inOutCubic(clamp((local - half) / half));
+    return [outP, inP];
+  });
+}
+
+/** Decimal places a list of numbers is written with (the most any of them has), at most 3. */
+export function decimals(values) {
+  return values.reduce((d, v) => {
+    for (let k = 0; k < 3; k++) if (Math.abs(Math.round(v * 10 ** k) - v * 10 ** k) < 1e-9) return Math.max(d, k);
+    return 3;
+  }, 0);
+}
+
+/** The value a counter shows at t: from -> to over [start, start + dur], eased out, rounded to d places. */
+export function counter(t, from, to, start, dur, d = 0) {
+  const p = ease.outExpo(clamp((t - start) / dur));
+  if (p >= 1) return to;
+  return Math.round(lerp(from, to, p) * 10 ** d) / 10 ** d;
+}
+
+/** 1234567.5 with d = 1 -> "1,234,567.5": thousands grouped, exactly d decimal places. */
+export function grouped(n, d = 0) {
+  const [int, frac] = Math.abs(n).toFixed(d).split(".");
+  const sign = n < 0 && Number(Math.abs(n).toFixed(d)) !== 0 ? "-" : "";
+  return `${sign}${int.replace(/\B(?=(\d{3})+(?!\d))/g, ",")}${frac ? `.${frac}` : ""}`;
+}
+
+/** Spreads n staggered starts over the time left before `end`: the gap shrinks so the last one still finishes. */
+export function fitGap(n, wanted, from, dur, end) {
+  if (n <= 1) return wanted;
+  return Math.max(0, Math.min(wanted, (end - from - dur) / (n - 1)));
+}

package/skills/video-gen/scripts/vg-model.mjs

@@ -0,0 +1,236 @@
+// vg-model.mjs: reads a video-gen scene file (JSON), checks it and returns one timeline the renderer draws.
+// Images are read here (local regular files only). No network.
+import { readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, resolve, win32 } from "node:path";
+
+export const TYPES = ["title", "kinetic", "bullets", "chart", "counter", "lowerthird", "quote", "image", "credits"];
+export const TRANSITIONS = ["cut", "fade", "wipe", "stripes"];
+export const SIZES = { "1280x720": [1280, 720], "1920x1080": [1920, 1080], "1080x1920": [1080, 1920], "1080x1080": [1080, 1080] };
+export const THEME = { bg: "1F3864", fg: "FFFFFF", accent: "2E86C1", muted: "D6EAF8", panel: "F4F6F7", ink: "1B2631" };
+export const PALETTE = ["2E86C1", "E67E22", "27AE60", "9B59B6", "E74C3C", "16A085", "F1C40F", "34495E"];
+export const LIMITS = { duration: 600, scene: 60, sceneMin: 0.5, bullets: 7, lines: 6, credits: 60, points: 24, value: 1e15, side: 16384, pixels: 50e6 };
+const HEX = /^#?[0-9A-Fa-f]{6}$/;
+const MAX_IMAGE = 20 * 1024 * 1024;
+
+const obj = (v) => (v && typeof v === "object" && !Array.isArray(v) ? v : {});
+export const hex = (c) => String(c).replace(/^#/, "").toUpperCase();
+
+// Drawn text has no use for control characters; a copied soft line break (U+000B) becomes a line break.
+// Text is put in NFC, so Hangul copied from macOS (jamo apart) draws as syllables.
+export const cleanText = (s) => s.normalize("NFC").replace(/\u{B}/gu, "\n").replace(/[\u{0}-\u{8}\u{C}\u{E}-\u{1F}\u{FFFE}\u{FFFF}]/gu, "").replace(/[\u{D800}-\u{DFFF}]/gu, "");
+
+function text(v, what, ctx) {
+  if (v === undefined || v === null) return "";
+  if (typeof v === "string") return cleanText(v);
+  if (typeof v === "number" && Number.isFinite(v)) return String(v);
+  ctx.errors.push(`${what}: 글이어야 함`);
+  return "";
+}
+
+function list(v, what, ctx) {
+  if (v === undefined || v === null) return [];
+  if (Array.isArray(v)) return v;
+  ctx.errors.push(`${what}: 배열이어야 함`);
+  return [];
+}
+
+function texts(v, what, ctx, max) {
+  const all = list(v, what, ctx).map((x, i) => text(x, `${what}[${i}]`, ctx));
+  const out = all.filter((x) => x.trim());
+  if (out.length < all.length) ctx.warnings.push(`${what}: 빈 항목은 뺌`);
+  if (out.length > max) ctx.warnings.push(`${what}: ${max}개를 넘음(화면에 다 들어가지 않을 수 있음)`);
+  return out;
+}
+
+const inRange = (v, min, max) => typeof v === "number" && Number.isFinite(v) && v >= min && v <= max;
+
+function num(v, what, ctx, { min = -Infinity, max = Infinity, def } = {}) {
+  if (v === undefined && def !== undefined) return def;
+  if (!inRange(v, min, max)) {
+    ctx.errors.push(`${what}: ${min} 이상 ${max} 이하 숫자여야 함`);
+    return def ?? min;
+  }
+  return v;
+}
+
+function themeOf(doc, ctx) {
+  const t = { ...THEME };
+  for (const [k, v] of Object.entries(obj(doc.theme))) {
+    if (!Object.prototype.hasOwnProperty.call(THEME, k)) ctx.errors.push(`theme.${k} 는 없는 칸(${Object.keys(THEME).join(", ")})`);
+    else if (!HEX.test(String(v))) ctx.errors.push(`theme.${k} 색이 6자리 16진수가 아님`);
+    else t[k] = hex(v);
+  }
+  return t;
+}
+
+function chartOf(raw, what, ctx) {
+  const c = obj(raw);
+  const kind = c.kind === undefined ? "bar" : text(c.kind, `${what}.kind`, ctx);
+  if (!["bar", "line"].includes(kind)) ctx.errors.push(`${what}.kind 는 bar, line 중 하나`);
+  const labels = texts(c.labels, `${what}.labels`, ctx, LIMITS.points);
+  const series = list(c.series, `${what}.series`, ctx).map(obj).map((s, k) => {
+    const values = list(s.values, `${what}.series[${k}].values`, ctx);
+    if (values.some((v) => typeof v !== "number" || !Number.isFinite(v))) ctx.errors.push(`${what}: 계열 값은 숫자만(null 이나 글자 안 됨)`);
+    else if (values.some((v) => Math.abs(v) > LIMITS.value)) ctx.errors.push(`${what}: 계열 값은 절댓값 ${LIMITS.value} 이하`);
+    if (values.length !== labels.length) ctx.errors.push(`${what}: 계열마다 값 수가 labels 수와 같아야 함`);
+    return { name: text(s.name, `${what}.series[${k}].name`, ctx), values: values.map((v) => (typeof v === "number" ? v : 0)) };
+  });
+  if (!labels.length || !series.length) ctx.errors.push(`${what}: labels 와 series 가 필요함`);
+  return { kind, labels, series, unit: text(c.unit, `${what}.unit`, ctx) };
+}
+
+/** Pixel size and whether the file ends as its format ends, from the bytes; null when it is no PNG/JPEG/GIF/WebP. */
+export function imageInfo(b) {
+  const at = (sig, off = 0) => sig.every((x, i) => b[off + i] === x);
+  if (at([0x89, 0x50, 0x4e, 0x47]) && b.length > 24) return { w: b.readUInt32BE(16), h: b.readUInt32BE(20), whole: b.includes("IEND", Math.max(0, b.length - 16)) };
+  if (at([0x47, 0x49, 0x46, 0x38]) && b.length > 10) return { w: b.readUInt16LE(6), h: b.readUInt16LE(8), whole: b.lastIndexOf(0x3b) >= b.length - 16 };
+  if (at([0xff, 0xd8, 0xff])) return jpegInfo(b);
+  if (at([0x52, 0x49, 0x46, 0x46]) && b.length > 30 && b.toString("latin1", 8, 12) === "WEBP") return { ...webpSize(b), whole: b.readUInt32LE(4) + 8 <= b.length };
+  return null;
+}
+
+// Walks the JPEG segments to the size (SOF) and the first scan (SOS). The file is whole when an end marker (FF D9)
+// follows that scan: inside scan data FF is only followed by 00 or a restart marker, so the first FF D9 after it is
+// the end, whatever is appended behind it (a phone's motion photo puts a whole MP4 there).
+function jpegInfo(b) {
+  let size = { w: 0, h: 0 };
+  for (let i = 2; i + 3 < b.length;) {
+    if (b[i] !== 0xff) break;
+    if (b[i + 1] === 0xff) {
+      i++;
+      continue;
+    }
+    const marker = b[i + 1];
+    if (marker === 0xda) return { ...size, whole: b.indexOf(Buffer.from([0xff, 0xd9]), i + 2) >= 0 };
+    if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker) && i + 9 < b.length) size = { w: b.readUInt16BE(i + 7), h: b.readUInt16BE(i + 5) };
+    const len = b.readUInt16BE(i + 2);
+    if (len < 2) break;
+    i += 2 + len;
+  }
+  return { ...size, whole: false };
+}
+
+function webpSize(b) {
+  const kind = b.toString("latin1", 12, 16);
+  if (kind === "VP8X") return { w: 1 + b.readUIntLE(24, 3), h: 1 + b.readUIntLE(27, 3) };
+  if (kind === "VP8L") {
+    const v = b.readUInt32LE(21);
+    return { w: 1 + (v & 0x3fff), h: 1 + ((v >> 14) & 0x3fff) };
+  }
+  return { w: b.readUInt16LE(26) & 0x3fff, h: b.readUInt16LE(28) & 0x3fff };
+}
+
+function checkImage(data) {
+  const info = imageInfo(data);
+  if (!info) throw new Error("PNG, JPEG, GIF, WebP 가 아님");
+  if (!(info.w > 0 && info.h > 0)) throw new Error("그림 크기를 읽지 못함");
+  if (info.w > LIMITS.side || info.h > LIMITS.side || info.w * info.h > LIMITS.pixels) throw new Error(`너무 큼(${info.w}x${info.h}, 한 변 ${LIMITS.side}, ${LIMITS.pixels / 1e6}MP 까지)`);
+  if (!info.whole) throw new Error("파일이 잘림(끝 표지가 없음)");
+}
+
+function imageOf(raw, what, ctx) {
+  const p = text(raw, what, ctx);
+  const abs = isAbsolute(p) || win32.isAbsolute(p);
+  if (!p || (!abs && /^[a-z][a-z0-9+.-]+:/i.test(p))) {
+    ctx.errors.push(`${what}: 로컬 파일 경로여야 함(URL 은 받지 않음)`);
+    return null;
+  }
+  const file = abs ? p : resolve(ctx.base, p);
+  try {
+    const st = statSync(file);
+    if (!st.isFile()) throw new Error("보통 파일이 아님");
+    if (st.size > MAX_IMAGE) throw new Error("20MB 를 넘음");
+    const data = readFileSync(file);
+    checkImage(data);
+    return { file, data };
+  } catch (e) {
+    ctx.errors.push(`${what}: 이미지를 읽지 못함 (${file}: ${e.message})`);
+    return null;
+  }
+}
+
+function motionOf(v, what, ctx) {
+  if (v === undefined) return "zoom";
+  if (v === "zoom" || v === "pan") return v;
+  ctx.errors.push(`${what}: zoom, pan 중 하나`);
+  return "zoom";
+}
+
+const FIELDS = {
+  title: (s, w, c) => ({ title: text(s.title, `${w}.title`, c), subtitle: text(s.subtitle, `${w}.subtitle`, c) }),
+  kinetic: (s, w, c) => ({ lines: texts(s.lines, `${w}.lines`, c, LIMITS.lines) }),
+  bullets: (s, w, c) => ({ title: text(s.title, `${w}.title`, c), bullets: texts(s.bullets, `${w}.bullets`, c, LIMITS.bullets) }),
+  chart: (s, w, c) => ({ title: text(s.title, `${w}.title`, c), chart: chartOf(s.chart, `${w}.chart`, c) }),
+  counter: (s, w, c) => ({
+    label: text(s.label, `${w}.label`, c), unit: text(s.unit, `${w}.unit`, c),
+    from: num(s.from, `${w}.from`, c, { def: 0, min: -1e12, max: 1e12 }), to: num(s.to, `${w}.to`, c, { min: -1e12, max: 1e12 }),
+  }),
+  lowerthird: (s, w, c) => ({ name: text(s.name, `${w}.name`, c), role: text(s.role, `${w}.role`, c), image: s.image === undefined ? null : imageOf(s.image, `${w}.image`, c) }),
+  quote: (s, w, c) => ({ quote: text(s.quote, `${w}.quote`, c), by: text(s.by, `${w}.by`, c) }),
+  image: (s, w, c) => ({ image: imageOf(s.image, `${w}.image`, c), caption: text(s.caption, `${w}.caption`, c), motion: motionOf(s.motion, `${w}.motion`, c) }),
+  credits: (s, w, c) => ({ title: text(s.title, `${w}.title`, c), lines: texts(s.lines, `${w}.lines`, c, LIMITS.credits) }),
+};
+
+const NEEDS = { title: "title", kinetic: "lines", bullets: "bullets", chart: "chart", lowerthird: "name", quote: "quote", image: "image", credits: "lines" };
+
+function sceneOf(raw, i, ctx) {
+  const s = obj(raw);
+  const what = `scenes[${i}]`;
+  const type = typeof s.type === "string" ? s.type : "";
+  if (!TYPES.includes(type)) {
+    ctx.errors.push(`${what}: type 은 ${TYPES.join(", ")} 중 하나 (${String(s.type)})`);
+    return null;
+  }
+  const duration = num(s.duration, `${what}.duration`, ctx, { def: 4, min: LIMITS.sceneMin, max: LIMITS.scene });
+  const transition = s.transition === undefined ? "fade" : String(s.transition);
+  if (!TRANSITIONS.includes(transition)) ctx.errors.push(`${what}.transition 은 ${TRANSITIONS.join(", ")} 중 하나`);
+  const scene = { type, duration, transition, ...FIELDS[type](s, what, ctx) };
+  const need = NEEDS[type];
+  if (need && isEmpty(scene[need])) ctx.errors.push(`${what}: ${need} 가 필요함(빈 글 안 됨)`);
+  return scene;
+}
+
+/** Empty: missing, blank text, or a list with no non-blank text (a chart or image object is never empty here). */
+function isEmpty(v) {
+  if (v === null || v === undefined) return true;
+  if (typeof v === "string") return !v.trim();
+  if (Array.isArray(v)) return !v.some((x) => typeof x === "string" && x.trim());
+  return false;
+}
+
+/** Start times: each scene starts where the one before ends. */
+function timeline(scenes) {
+  let at = 0;
+  return scenes.map((s) => {
+    const out = { ...s, start: at };
+    at += s.duration;
+    return out;
+  });
+}
+
+/** Frame size and rate: size is one of SIZES, fps a whole number 12..60. */
+function frameOf(doc, ctx) {
+  const size = doc.size === undefined ? "1280x720" : String(doc.size);
+  if (!Object.prototype.hasOwnProperty.call(SIZES, size)) ctx.errors.push(`size 는 ${Object.keys(SIZES).join(", ")} 중 하나`);
+  const fps = num(doc.fps, "fps", ctx, { def: 30, min: 12, max: 60 });
+  if (!Number.isInteger(fps)) ctx.errors.push("fps 는 정수여야 함");
+  const [width, height] = Object.prototype.hasOwnProperty.call(SIZES, size) ? SIZES[size] : SIZES["1280x720"];
+  return { width, height, fps };
+}
+
+/** Checks a scene file and returns { errors, warnings, model }; model is null when there are errors. */
+export function readScenes(doc, base) {
+  const errors = [];
+  const warnings = [];
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) return { errors: ["scene 파일은 JSON 객체여야 함"], warnings, model: null };
+  const ctx = { errors, warnings, base: base || process.cwd() };
+  const { width, height, fps } = frameOf(doc, ctx);
+  if (!Array.isArray(doc.scenes) || !doc.scenes.length) errors.push("scenes 가 비어 있음");
+  const scenes = timeline((Array.isArray(doc.scenes) ? doc.scenes : []).map((s, i) => sceneOf(s, i, ctx)).filter(Boolean));
+  const duration = scenes.reduce((n, s) => n + s.duration, 0);
+  if (duration > LIMITS.duration) errors.push(`전체 길이가 ${LIMITS.duration}초를 넘음`);
+  const model = { title: text(doc.title, "title", ctx), width, height, fps, theme: themeOf(doc, ctx), scenes, duration, frames: Math.round(duration * fps) };
+  return { errors, warnings, model: errors.length ? null : model };
+}
+
+export const sceneBase = (file) => dirname(resolve(file));