@crievo/omni 0.0.0-stage → 0.1.1

package/tools/carousel.mjs

@@ -0,0 +1,558 @@
+#!/usr/bin/env node
+/* ============================================================================
+   Instagram carousel in code: one HTML per slide → PNG → JPEG.
+
+     node tools/carousel.mjs init   videos/<slug> [--format 4:5] [--from-video]
+     node tools/carousel.mjs build  videos/<slug> [--slide s01,s03] [--strip]
+     node tools/carousel.mjs export videos/<slug>
+     node tools/carousel.mjs status videos/<slug> [--json]
+
+   Lives in videos/<slug>/carousel/, next to the video (if any): the same
+   content can become a video, a carousel or both. Contract in
+   reference/carousel-contract.md; Claude decides the text and the design
+   (skill av-carousel). This tool is the mechanical part:
+
+   init      creates carousel/{src,png,export}, carousel.json and copies the
+             script and composition templates. --from-video inherits title and
+             references from the dir's video scenes.json.
+   build     carousel/src/<id>.html + _common.html → carousel/<id>.html (with
+             --slide-i, --slide-n, --slide-w, --slide-h and window.OMNICAROUSEL
+             injected) → carousel/png/<id>.png, and the sheet carousel/_sheet.png
+             with every slide in order. Measures each slide: text outside the
+             margin, text too small for the phone, a box that clips its
+             content. --strip also writes _strip.png, the slides joined with no
+             gap, to check what crosses the seam.
+   export    png/ → export/<NN>.jpg (Instagram wants JPEG) and export/caption.txt;
+             refuses an outdated slide or one with warnings.
+   status    which stage the carousel is in (script, composition, export).
+
+   Size by ratio (carousel.formats in the config): 4:5 → 1080×1350,
+   1:1 → 1080×1080, 3:4 → 1080×1440. Every slide has the first one's.
+   ============================================================================ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  rmSync,
+  copyFileSync,
+  renameSync,
+  readdirSync,
+  statSync,
+} from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { join, resolve, basename, relative } from "node:path";
+import { CODE_ROOT, isMainModule, DATA_ROOT as ROOT } from "./lib/paths.mjs";
+
+const RENDER = join(CODE_ROOT, "tools", "render.mjs");
+const CFG = JSON.parse(readFileSync(join(ROOT, "omnivideo.config.json"), "utf8")).carousel ?? {};
+const FORMATS = CFG.formats ?? {
+  "4:5": { w: 1080, h: 1350 },
+  "1:1": { w: 1080, h: 1080 },
+  "3:4": { w: 1080, h: 1440 },
+};
+const LIMIT = { min: 2, max: 20, publish: 10, ...(CFG.slides ?? {}) };
+const MARGIN = CFG.min_margin_px ?? 64;
+const MIN_FONT = CFG.min_font_px ?? 26;
+const PARALLEL = 4;
+const MARKER = "<!-- omnivideo:common -->";
+const LEGACY_MARKER = "<!-- omnivideo:comum -->";
+
+/* on the command line, an error exits with 1; imported (the studio), it throws */
+const CLI = isMainModule(import.meta.url);
+class Failure extends Error {}
+const fail = msg => {
+  throw new Failure(msg);
+};
+const readJson = file => {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+};
+function writeJson(file, data) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n");
+  renameSync(tmp, file);
+}
+const hash = s => createHash("sha256").update(s).digest("hex").slice(0, 16);
+
+const argv = CLI ? process.argv.slice(2) : [];
+const opt = n => {
+  const i = argv.indexOf(`--${n}`);
+  return i < 0 ? null : (argv[i + 1] ?? "");
+};
+const has = n => argv.includes(`--${n}`);
+
+/* the content dir in use: the command line's, or the one the studio asks for */
+let target, VIDEO_DIR, DIR, JSON_FILE, BUILD_FILE;
+function use(p) {
+  target = p;
+  VIDEO_DIR = resolve(p);
+  DIR = join(VIDEO_DIR, "carousel");
+  JSON_FILE = join(DIR, "carousel.json");
+  BUILD_FILE = join(DIR, "build.json");
+}
+const rel = p => relative(process.cwd(), p) || ".";
+const paths = {
+  src: id => join(DIR, "src", `${id}.html`),
+  html: id => join(DIR, `${id}.html`),
+  png: id => join(DIR, "png", `${id}.png`),
+};
+/* _comum.html: the name before the English migration */
+const commonFile = () =>
+  [join(DIR, "src", "_common.html"), join(DIR, "src", "_comum.html")].find(f => existsSync(f)) ?? null;
+
+/* --- init ---------------------------------------------------------------------- */
+function init() {
+  if (!existsSync(VIDEO_DIR)) fail(`${target} não existe (abra a pasta do conteúdo antes: skill omnivideo, passo 0)`);
+  for (const d of ["src", "png", "export"]) mkdirSync(join(DIR, d), { recursive: true });
+  const ratio = opt("format") ?? CFG.default_format ?? "4:5";
+  if (!FORMATS[ratio]) fail(`formato desconhecido: ${ratio} (use ${Object.keys(FORMATS).join(", ")})`);
+
+  const scenes = readJson(join(VIDEO_DIR, "scenes.json"));
+  const fromVideo = has("from-video");
+  if (fromVideo && !scenes && !existsSync(join(VIDEO_DIR, "script.md")))
+    fail("--from-video: a pasta não tem scenes.json nem script.md de vídeo");
+
+  if (!existsSync(JSON_FILE)) {
+    const script = existsSync(join(VIDEO_DIR, "script.md")) ? readFileSync(join(VIDEO_DIR, "script.md"), "utf8") : "";
+    const title = scenes?.title ?? /^#\s*Roteiro\s*·\s*(.+)$/m.exec(script)?.[1]?.trim() ?? basename(VIDEO_DIR);
+    writeJson(JSON_FILE, {
+      slug: basename(VIDEO_DIR),
+      title,
+      format: { ratio, ...FORMATS[ratio] },
+      origin: fromVideo ? "video" : "script",
+      references: fromVideo ? (scenes?.references ?? []) : [],
+      goal: null,
+      caption: "",
+      slides: [],
+    });
+    console.log(
+      `criado ${rel(JSON_FILE)} (${ratio}, ${FORMATS[ratio].w}×${FORMATS[ratio].h}${fromVideo ? ", do vídeo da pasta" : ""})`,
+    );
+  } else console.log(`${rel(JSON_FILE)} já existe: mantido`);
+
+  for (const [template, dest] of [
+    ["carousel-script.md", "script.md"],
+    ["carousel-composition.md", "composition.md"],
+  ]) {
+    const d = join(DIR, dest);
+    if (existsSync(d)) continue;
+    copyFileSync(join(CODE_ROOT, "templates", template), d);
+    console.log(`copiado templates/${template} → ${rel(d)}`);
+  }
+  console.log(`próximo: escreva ${rel(join(DIR, "script.md"))} e os slides no carousel.json (skill av-carousel)`);
+}
+
+/* --- load ---------------------------------------------------------------------- */
+function load() {
+  const c = readJson(JSON_FILE);
+  if (!c) fail(`${target} não tem carousel/carousel.json (rode: node tools/carousel.mjs init ${target})`);
+  const f = c.format ?? {};
+  const base = FORMATS[f.ratio];
+  if (!f.w || !f.h) {
+    if (!base) fail(`formato inválido no carousel.json: ${JSON.stringify(f)}`);
+    Object.assign(f, base);
+  }
+  c.format = f;
+  c.slides ??= [];
+  const ids = c.slides.map(s => s.id);
+  const dup = ids.filter((id, i) => ids.indexOf(id) !== i);
+  if (dup.length) fail(`slide repetido no carousel.json: ${[...new Set(dup)].join(", ")}`);
+  const bad = ids.filter(id => !/^s\d{2}$/.test(id ?? ""));
+  if (bad.length) fail(`id de slide fora do padrão sNN: ${bad.join(", ")}`);
+  return c;
+}
+
+const LEGACY_ROLE = { cover: "capa", content: "conteudo" };
+
+/* A slide's final HTML: _common.html at the marker and the slide's variables before
+   </head>. Its hash is what says whether the PNG is up to date. */
+function finalHtml(c, i) {
+  const s = c.slides[i];
+  const file = paths.src(s.id);
+  if (!existsSync(file)) return null;
+  let html = readFileSync(file, "utf8");
+  const common = commonFile();
+  if (common) {
+    const marker = html.includes(MARKER) ? MARKER : html.includes(LEGACY_MARKER) ? LEGACY_MARKER : null;
+    if (!marker) console.warn(`aviso: ${s.id}: sem o marcador ${MARKER}; o ${basename(common)} não entrou`);
+    /* the common <style>s go up to the start of the head: they are the base, and the
+       slide's <style>, which comes after, overrides. The rest (frame, scripts) goes at the marker. */
+    const text = readFileSync(common, "utf8");
+    const styles = text.match(/<style[\s\S]*?<\/style>/gi) ?? [];
+    if (marker) html = html.replace(marker, () => text.replace(/<style[\s\S]*?<\/style>/gi, ""));
+    html = html.replace(/<head[^>]*>/i, m => `${m}\n${styles.join("\n")}`);
+  }
+  const { w, h } = c.format;
+  const data = {
+    slide: s.id,
+    index: i,
+    total: c.slides.length,
+    format: c.format,
+    slides: c.slides.map(({ id, role }) => ({ id, role: role ?? null })),
+  };
+  /* OMNICARROSSEL: the PT keys, read by slide code written before the English migration */
+  const legacy = {
+    slide: s.id,
+    indice: i,
+    total: c.slides.length,
+    formato: { proporcao: c.format.ratio, w, h },
+    slides: c.slides.map(({ id, role }) => ({ id, papel: LEGACY_ROLE[role] ?? role ?? null })),
+  };
+  const inject =
+    `<style id="omnivideo-slide">:root{ --slide-i:${i}; --slide-n:${c.slides.length}; --slide-w:${w}px; --slide-h:${h}px; }</style>\n` +
+    `<script>window.OMNICAROUSEL = ${JSON.stringify(data)}; window.OMNICARROSSEL = ${JSON.stringify(legacy)};</script>\n`;
+  /* the last </head>: a comment before it may mention the tag */
+  const end = html.toLowerCase().lastIndexOf("</head>");
+  if (end < 0) fail(`${s.id}: src sem </head> (parta de templates/slide.html)`);
+  return html.slice(0, end) + inject + html.slice(end);
+}
+/* Slide measurement, run in the page after the still (render.mjs --eval). Text is
+   whatever has its own text node; its box is the text's (Range), not the block's.
+   data-free (legacy data-livre) exempts a decoration that bleeds on purpose. */
+const MEASURE = `(() => {
+  const W = innerWidth, H = innerHeight, M = ${MARGIN}, FMIN = ${MIN_FONT};
+  const warnings = new Set();
+  const short = e => { const t = e.textContent.trim().replace(/\\s+/g, " "); return "«" + (t.length > 36 ? t.slice(0, 36) + "…" : t) + "»"; };
+  const visible = e => { for (let a = e; a; a = a.parentElement) { const cs = getComputedStyle(a); if (cs.display === "none" || cs.visibility === "hidden" || +cs.opacity < 0.05) return false; } return true; };
+  for (const e of document.body.querySelectorAll("*")) {
+    if (["SCRIPT", "STYLE", "TEMPLATE"].includes(e.tagName) || !visible(e)) continue;
+    const cs = getComputedStyle(e);
+    const nodes = [...e.childNodes].filter(n => n.nodeType === 3 && n.textContent.trim());
+    if (nodes.length && !e.closest("[data-free],[data-livre]")) {
+      let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+      for (const n of nodes) { const r = document.createRange(); r.selectNodeContents(n);
+        for (const q of r.getClientRects()) { x0 = Math.min(x0, q.left); y0 = Math.min(y0, q.top); x1 = Math.max(x1, q.right); y1 = Math.max(y1, q.bottom); } }
+      if (x1 > x0) {
+        const out = [x0 < M - 0.5 && "esquerda", x1 > W - M + 0.5 && "direita", y0 < M - 0.5 && "topo", y1 > H - M + 0.5 && "base"].filter(Boolean);
+        if (out.length) warnings.add("texto " + short(e) + " fora da margem de " + M + " px (" + out.join(", ") + ")");
+      }
+      if (!e.closest("svg")) { const fs = parseFloat(cs.fontSize); if (fs < FMIN) warnings.add("texto " + short(e) + " em " + fs + " px: pequeno demais no celular (mín. " + FMIN + " px)"); }
+    }
+    if (e !== document.body && /hidden|clip/.test(cs.overflowX + cs.overflowY) && e.textContent.trim()
+        && (e.scrollWidth > e.clientWidth + 1 || e.scrollHeight > e.clientHeight + 1)) warnings.add(short(e) + " cortado: o conteúdo não cabe na caixa");
+  }
+  return [...warnings].slice(0, 12);
+})()`;
+
+const render = args =>
+  new Promise(ok => {
+    let out = "",
+      err = "";
+    const p = spawn(process.execPath, [RENDER, ...args], { stdio: ["ignore", "pipe", "pipe"] });
+    p.stdout.on("data", d => {
+      out += d;
+    });
+    p.stderr.on("data", d => {
+      err += d;
+    });
+    p.on("exit", code => ok({ code, out, err }));
+  });
+
+/* --- build --------------------------------------------------------------------- */
+async function build() {
+  const c = load();
+  if (!c.slides.length) fail("o carousel.json não tem slides: escreva o roteiro do carrossel antes");
+  if (c.slides.length > LIMIT.max) fail(`${c.slides.length} slides: o Instagram aceita até ${LIMIT.max}`);
+  const only = opt("slide")?.split(",").filter(Boolean) ?? null;
+  if (only) {
+    const out = only.filter(id => !c.slides.some(s => s.id === id));
+    if (out.length) fail(`não são slides do carousel.json: ${out.join(", ")}`);
+  }
+  const { w, h } = c.format;
+  const previous = readJson(BUILD_FILE);
+  const same = previous?.format?.w === w && previous?.format?.h === h;
+  const record = { format: c.format, slides: same ? (previous.slides ?? {}) : {} };
+
+  const queue = c.slides.map((s, i) => ({ s, i })).filter(({ s }) => !only || only.includes(s.id));
+  const noSource = queue.filter(({ s }) => !existsSync(paths.src(s.id))).map(({ s }) => s.id);
+  if (noSource.length)
+    console.warn(`aviso: sem src para ${noSource.join(", ")} (copie templates/slide.html para carousel/src/<id>.html)`);
+  const pending = queue.filter(({ s }) => !noSource.includes(s.id));
+  const start = Date.now();
+  await Promise.all(
+    Array.from({ length: Math.min(PARALLEL, pending.length) }, async () => {
+      while (pending.length) {
+        const { s, i } = pending.shift();
+        const html = finalHtml(c, i);
+        writeFileSync(paths.html(s.id), html);
+        const r = await render([
+          paths.html(s.id),
+          "--still",
+          paths.png(s.id),
+          "--at",
+          "0",
+          "--w",
+          String(w),
+          "--h",
+          String(h),
+          "--eval",
+          MEASURE,
+        ]);
+        if (r.code !== 0) {
+          console.error(`${s.id}: o render saiu com ${r.code}\n${(r.err || r.out).trim().slice(-600)}`);
+          process.exitCode = 1;
+          continue;
+        }
+        const line = r.out.split("\n").find(l => l.startsWith("EVAL "));
+        const warnings = [
+          ...(line ? (JSON.parse(line.slice(5)) ?? []) : []),
+          ...r.err
+            .split("\n")
+            .filter(l => l.startsWith("aviso:"))
+            .map(l => l.slice(7)),
+        ];
+        record.slides[s.id] = { hash: hash(html), warnings, generated_at: new Date().toISOString() };
+        console.log(
+          `${s.id}: ${rel(paths.png(s.id))}${warnings.length ? warnings.map(a => `\n  ⚠ ${a}`).join("") : ""}`,
+        );
+      }
+    }),
+  );
+  /* a slide that left carousel.json does not stay in the record */
+  for (const id of Object.keys(record.slides)) if (!c.slides.some(s => s.id === id)) delete record.slides[id];
+  writeJson(BUILD_FILE, record);
+
+  await sheet(c, false);
+  if (has("strip")) await sheet(c, true);
+  const n = c.slides.length;
+  if (n < LIMIT.min) console.warn(`aviso: ${n} slide(s): carrossel tem pelo menos ${LIMIT.min}`);
+  if (n > LIMIT.publish)
+    console.warn(`aviso: ${n} slides, acima de carousel.slides.publish (${LIMIT.publish}) da config`);
+  console.log(
+    `${queue.length - noSource.length} slide(s) em ${((Date.now() - start) / 1000).toFixed(1)}s · folha: ${rel(join(DIR, "_sheet.png"))} (leia com Read)`,
+  );
+}
+
+/* Sheet: the slides in swipe order, with id and title. Strip: joined, no gap,
+   to see what crosses the seam. */
+async function sheet(c, strip) {
+  const { w, h } = c.format;
+  const withPng = c.slides.filter(s => existsSync(paths.png(s.id)));
+  if (!withPng.length) return;
+  const cellW = strip ? 360 : 300,
+    cellH = Math.round((cellW * h) / w);
+  const cols = strip ? withPng.length : Math.min(5, withPng.length),
+    rows = Math.ceil(withPng.length / cols);
+  const gap = strip ? 0 : 16,
+    label = strip ? 0 : 40;
+  const FW = cols * cellW + (cols - 1) * gap + 32,
+    FH = rows * (cellH + label) + (rows - 1) * gap + 32;
+  const esc = s =>
+    String(s ?? "").replace(/[&<>"]/g, ch => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[ch]);
+  const tmp = join(DIR, ".tmp-sheet.html");
+  writeFileSync(
+    tmp,
+    `<!doctype html><meta charset="utf-8"><style>
+body{margin:0;background:#fff;font:600 15px/1.2 "Schibsted Grotesk",Helvetica,Arial,sans-serif;color:#222}
+.g{display:grid;grid-template-columns:repeat(${cols},${cellW}px);gap:${gap}px;padding:16px}
+figure{margin:0} img{width:${cellW}px;height:${cellH}px;display:block;${strip ? "" : "outline:1px solid #ccc"}}
+figcaption{height:24px;margin-top:8px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+figcaption b{font-family:ui-monospace,Menlo,monospace;color:#888;margin-right:6px}
+</style><div class="g">${withPng.map(s => `<figure><img src="png/${s.id}.png?${Date.now()}">${strip ? "" : `<figcaption><b>${s.id}</b>${esc(s.title)}</figcaption>`}</figure>`).join("")}</div>
+<script>Promise.all([document.fonts.ready, ...[...document.images].map(i => i.decode().catch(() => {}))]).then(() => { window.__ready = true; });</script>`,
+  );
+  const out = join(DIR, strip ? "_strip.png" : "_sheet.png");
+  const r = await render([tmp, "--still", out, "--at", "0", "--w", String(FW), "--h", String(FH)]);
+  rmSync(tmp, { force: true });
+  if (r.code !== 0) console.error(`folha: o render saiu com ${r.code}\n${r.err.trim().slice(-400)}`);
+}
+
+/* --- diagnosis ----------------------------------------------------------------- */
+function diagnose() {
+  const c = readJson(JSON_FILE);
+  const stages = [];
+  const warnings = [];
+  if (!c)
+    return {
+      exists: false,
+      stages: [{ id: "script", name: "roteiro do carrossel", ok: false, missing: "carousel.mjs init" }],
+      warnings,
+      next: "script",
+    };
+  const slides = c.slides ?? [];
+  const scriptMd = existsSync(join(DIR, "script.md"));
+  const incomplete = slides.filter(s => !s.title || !s.role).map(s => s.id);
+  const scriptOk = scriptMd && slides.length >= LIMIT.min && !incomplete.length && !!c.goal;
+  stages.push({
+    id: "script",
+    name: "roteiro do carrossel",
+    ok: scriptOk,
+    missing: !scriptMd
+      ? "carousel/script.md"
+      : slides.length < LIMIT.min
+        ? `slides no carousel.json (${slides.length})`
+        : !c.goal
+          ? "goal no carousel.json"
+          : incomplete.length
+            ? `role e title em ${incomplete.join(", ")}`
+            : null,
+  });
+
+  let compOk = scriptOk;
+  const missing = [];
+  if (!existsSync(join(DIR, "composition.md"))) {
+    compOk = false;
+    missing.push("carousel/composition.md");
+  }
+  if (!(c.references ?? []).length) {
+    compOk = false;
+    missing.push("references no carousel.json");
+  }
+  const reg = readJson(BUILD_FILE)?.slides ?? {};
+  const noSrc = [],
+    stale = [],
+    withWarnings = [];
+  slides.forEach((s, i) => {
+    let html = null;
+    try {
+      html = existsSync(paths.src(s.id)) ? quietFinalHtml(c, i) : null;
+    } catch {
+      /* broken src */
+    }
+    if (!html) {
+      noSrc.push(s.id);
+      return;
+    }
+    if (!existsSync(paths.png(s.id)) || reg[s.id]?.hash !== hash(html)) stale.push(s.id);
+    else if (reg[s.id]?.warnings?.length) withWarnings.push(s.id);
+  });
+  if (noSrc.length) {
+    compOk = false;
+    missing.push(`src de ${noSrc.join(", ")}`);
+  }
+  if (stale.length) {
+    compOk = false;
+    missing.push(`build de ${stale.join(", ")}`);
+  }
+  if (withWarnings.length) {
+    compOk = false;
+    missing.push(`avisos em ${withWarnings.join(", ")}`);
+  }
+  stages.push({
+    id: "composition",
+    name: "composição (slides em código)",
+    ok: compOk,
+    missing: missing.join(" · ") || null,
+  });
+
+  const exp = readJson(join(DIR, "export", "export.json"));
+  const expOk =
+    compOk &&
+    !!exp &&
+    slides.length === exp.slides?.length &&
+    slides.every((s, i) => exp.slides[i]?.id === s.id && exp.slides[i]?.hash === reg[s.id]?.hash);
+  stages.push({
+    id: "export",
+    name: "export (JPEG para o Instagram)",
+    ok: expOk,
+    missing: expOk ? null : "carousel.mjs export",
+  });
+  const pub = readJson(join(DIR, "publication.json"))?.instagram;
+  stages.push({
+    id: "publish",
+    name: "publicar no Instagram",
+    ok: !!pub?.id,
+    missing: pub?.id ? null : "publicar (botão da tela, ou publish.mjs carousel --confirm)",
+  });
+
+  for (const [id, r] of Object.entries(reg)) for (const a of r.warnings ?? []) warnings.push(`${id}: ${a}`);
+  if (slides.length > LIMIT.publish)
+    warnings.push(`${slides.length} slides, acima de carousel.slides.publish (${LIMIT.publish})`);
+  const next = stages.find(e => !e.ok)?.id ?? null;
+  return { exists: true, title: c.title, format: c.format, slides: slides.length, stages, warnings, next };
+}
+
+function quietFinalHtml(c, i) {
+  const warn = console.warn;
+  console.warn = () => {};
+  try {
+    return finalHtml(c, i);
+  } finally {
+    console.warn = warn;
+  }
+}
+
+function status() {
+  const d = diagnose();
+  if (has("json")) {
+    console.log(JSON.stringify(d, null, 2));
+    return;
+  }
+  if (d.exists) console.log(`${d.title} · ${d.slides} slide(s) · ${d.format.ratio} ${d.format.w}×${d.format.h}`);
+  for (const e of d.stages)
+    console.log(`${e.ok ? "✓" : "·"} ${e.name}${e.ok || !e.missing ? "" : ` — falta: ${e.missing}`}`);
+  for (const a of d.warnings) console.log(`⚠ ${a}`);
+  console.log(d.next ? `próxima etapa: ${d.next}` : "publicado");
+}
+
+/* --- export -------------------------------------------------------------------- */
+function exportJpegs() {
+  const d = diagnose();
+  const comp = d.stages.find(e => e.id === "composition");
+  if (!comp?.ok) fail(`a composição não está pronta: ${comp?.missing ?? "rode o build"}`);
+  const c = load();
+  const reg = readJson(BUILD_FILE).slides;
+  const out = join(DIR, "export");
+  mkdirSync(out, { recursive: true });
+  for (const f of readdirSync(out)) if (/^\d{2}\.jpg$/.test(f)) rmSync(join(out, f));
+  const q = String(CFG.jpeg_quality ?? 2);
+  c.slides.forEach((s, i) => {
+    const jpg = join(out, `${String(i + 1).padStart(2, "0")}.jpg`);
+    const r = spawnSync(
+      "ffmpeg",
+      ["-y", "-loglevel", "error", "-i", paths.png(s.id), "-pix_fmt", "yuvj444p", "-q:v", q, jpg],
+      { encoding: "utf8" },
+    );
+    if (r.status !== 0) fail(`${s.id}: ffmpeg saiu com ${r.status}\n${r.stderr}`);
+  });
+  if ((c.caption ?? "").trim()) writeFileSync(join(out, "caption.txt"), c.caption.trim() + "\n");
+  else console.warn("aviso: carousel.json sem caption (o texto do post)");
+  writeJson(join(out, "export.json"), {
+    exported_at: new Date().toISOString(),
+    format: c.format,
+    slides: c.slides.map((s, i) => ({
+      id: s.id,
+      jpg: `export/${String(i + 1).padStart(2, "0")}.jpg`,
+      hash: reg[s.id].hash,
+    })),
+  });
+  const kb =
+    c.slides.reduce((t, _, i) => t + statSync(join(out, `${String(i + 1).padStart(2, "0")}.jpg`)).size, 0) / 1024;
+  console.log(
+    `${c.slides.length} JPEG(s) em ${rel(out)}/ (${Math.round(kb)} KB no total)${c.caption ? " + caption.txt" : ""}`,
+  );
+}
+
+/* --- for the studio and publish.mjs ----------------------------------------------- */
+export function diagnosisOf(dir) {
+  use(dir);
+  return diagnose();
+}
+export function exportOf(dir) {
+  use(dir);
+  exportJpegs();
+}
+export const LIMITS = LIMIT;
+
+if (CLI) {
+  const [cmd, cliTarget] = argv;
+  try {
+    if (!cmd || !cliTarget) fail("uso: carousel.mjs init|build|export|status videos/<slug> [opções]");
+    use(cliTarget);
+    if (cmd === "init") init();
+    else if (cmd === "build") await build();
+    else if (cmd === "export") exportJpegs();
+    else if (cmd === "status") status();
+    else fail(`comando desconhecido: ${cmd}`);
+  } catch (e) {
+    if (!(e instanceof Failure)) throw e;
+    console.error(`erro: ${e.message}`);
+    process.exit(1);
+  }
+}