@crievo/omni 0.0.0-stage → 0.1.1

package/studio/api/services/approval.ts

@@ -0,0 +1,134 @@
+/* Approval from the UI: of the motion script scenes and of the content script.
+
+   The rules live in tools/approval.mjs, which the session also runs: it stays
+   in `wait` while the deadline runs (and while the countdown is paused for
+   a short while) and moves on by itself when the round ends. If it left earlier (the
+   pause went past the deadline, or the video is the chat's), the video session
+   resumes from here: when the decision ends on the UI or when the deadline expires. */
+
+import { relative } from "node:path";
+import { ROOT } from "./root";
+import { latestSessionFor, replyToSession } from "./sessions";
+import { read, summarize, decide, approveAll, pause, resume, mark, edit } from "../../../tools/approval.mjs";
+
+type ApprovalKind = "scenes" | "script";
+
+export const scenesApprovalOf = (dir: string) => summarize(read(dir));
+export const scriptApprovalOf = (dir: string) => summarize(read(dir, "script"));
+
+export const SCENE_ACTIONS = ["decide", "approve-all", "pause", "resume"] as const;
+type SceneAction = (typeof SCENE_ACTIONS)[number];
+type DecisionBody = { scene?: string; decision?: string; comment?: string };
+
+export function decideScenes(dir: string, action: SceneAction, b: DecisionBody) {
+  const r =
+    action === "decide"
+      ? decide(dir, String(b.scene ?? ""), String(b.decision ?? ""), String(b.comment ?? ""))
+      : action === "approve-all"
+        ? approveAll(dir)
+        : action === "pause"
+          ? pause(dir)
+          : resume(dir);
+  if (!r.ok) return r;
+  const e = summarize(r.approval);
+  const output =
+    action === "pause"
+      ? "contagem pausada enquanto você edita"
+      : action === "resume"
+        ? "a contagem voltou de onde parou"
+        : e.status === "pending"
+          ? `gravado · ${e.pending_count} cena(s) ainda esperando`
+          : e.status === "change_requested"
+            ? `pronto · ${e.change_requests.length} cena(s) pedem alteração`
+            : "pronto · todas aprovadas";
+  return { ok: true, output };
+}
+
+/* the script is a single item: approve, request a change or edit the text (which approves it) */
+export const SCRIPT_ACTIONS = ["decide", "pause", "resume", "edit"] as const;
+type ScriptAction = (typeof SCRIPT_ACTIONS)[number];
+
+export function decideScript(dir: string, action: ScriptAction, b: DecisionBody & { text?: string }) {
+  const r =
+    action === "decide"
+      ? decide(dir, "script", String(b.decision ?? ""), String(b.comment ?? ""), "script")
+      : action === "edit"
+        ? edit(dir, String(b.text ?? ""))
+        : action === "pause"
+          ? pause(dir, "script")
+          : resume(dir, "script");
+  if (!r.ok) return r;
+  const e = summarize(r.approval);
+  const output =
+    action === "pause"
+      ? "contagem pausada enquanto você edita"
+      : action === "resume"
+        ? "a contagem voltou de onde parou"
+        : action === "edit"
+          ? "pronto · sua edição gravada no script.md e aprovada"
+          : e.status === "change_requested"
+            ? "pronto · o roteiro pede alteração"
+            : "pronto · roteiro aprovado";
+  return { ok: true, output };
+}
+
+/* what the resumed session reads, per round */
+const RESUME_PROMPTS: Record<ApprovalKind, { origin: string; text: (rel: string) => string }> = {
+  scenes: {
+    origin: "scenes-approval",
+    text: rel =>
+      `A aprovação das cenas do roteiro de motion terminou na tela. Rode \`node tools/approval.mjs wait ${rel}\` para ler o resultado e siga a skill omnivideo (Aprovação das cenas).`,
+  },
+  script: {
+    origin: "script-approval",
+    text: rel =>
+      `A aprovação do roteiro terminou na tela. Rode \`node tools/approval.mjs wait ${rel} --script\` para ler o resultado e siga a skill omnivideo (Aprovação do roteiro).`,
+  },
+};
+
+/* A finished round Claude hasn't read yet: resumes the video's stopped
+   session. A running session is in `wait` (which reads by itself) or finishing the
+   turn; in that case the end of the turn calls again. Without `kind`, checks both
+   rounds. */
+export function resumeAfterApproval(slug: string, dir: string, kind?: ApprovalKind): string {
+  if (!kind) return resumeAfterApproval(slug, dir, "script") || resumeAfterApproval(slug, dir, "scenes");
+  const a = read(dir, kind);
+  if (!a?.completed_at || a.delivered_at || a.resumed_at) return "";
+  /* a forgotten round from before (studio off, video driven by the chat) doesn't wake an old session */
+  if (Date.now() - Date.parse(a.completed_at) > 3_600_000) return "";
+  const s = latestSessionFor("video", slug);
+  if (!s || s.state === "running") return "";
+  const rel = relative(ROOT, dir).startsWith("..") ? dir : relative(ROOT, dir);
+  const r = replyToSession(s.id, RESUME_PROMPTS[kind].text(rel), RESUME_PROMPTS[kind].origin);
+  if (r.ok) mark(dir, "resumed_at", kind);
+  return r.ok ? " · o Claude retomou a sessão deste vídeo" : ` · o Claude não retomou: ${r.error}`;
+}
+
+/* One alarm per round with the countdown running: at the deadline, reading applies the
+   auto approval and a session that isn't in `wait` resumes. Redone on
+   every change in the video dir (the file is the source; the timer only wakes up).
+   Scenes and script have separate alarms: one doesn't cancel the other. */
+const alarms = new Map<string, ReturnType<typeof setTimeout>>();
+export function watchDeadline(slug: string, dir: string, kind?: ApprovalKind) {
+  if (!kind) {
+    watchDeadline(slug, dir, "script");
+    watchDeadline(slug, dir, "scenes");
+    return;
+  }
+  const key = `${slug}#${kind}`;
+  clearTimeout(alarms.get(key));
+  alarms.delete(key);
+  const a = read(dir, kind);
+  if (!a || a.completed_at || a.mode !== "auto") {
+    if (a?.completed_at) resumeAfterApproval(slug, dir, kind);
+    return;
+  }
+  const left = Math.max(0, Date.parse(a.deadline) - Date.now()) + 500;
+  alarms.set(
+    key,
+    setTimeout(() => {
+      alarms.delete(key);
+      watchDeadline(slug, dir, kind);
+    }, left),
+  );
+}

package/studio/api/services/archive.ts

@@ -0,0 +1,38 @@
+/* Archiving a video takes it off the work list without deleting anything: the dir
+   stays as it is, with an archived.json ({ at }) next to scenes.json. Unarchiving
+   deletes that file. No pipeline tool reads it; it belongs to the UI only. */
+
+import { writeFileSync, renameSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { readJson } from "./root";
+import { getQueue } from "./queue";
+
+type Result = { ok: true } | { ok: false; error: string };
+
+export function archiveVideo(dir: string, archived: boolean): Result {
+  const file = join(dir, "archived.json");
+  if (!archived) {
+    try {
+      unlinkSync(file);
+    } catch {
+      /* was not archived */
+    }
+    return { ok: true };
+  }
+
+  /* the launchd scheduler publishes with the studio open or not: a hidden video must
+     not go up unseen. Whoever archives cancels the schedule first. */
+  const sch = readJson(join(dir, "publication.json"))?.schedule;
+  if (sch && (sch.state === "scheduled" || sch.state === "publishing")) {
+    return { ok: false, error: "Este vídeo tem uma publicação agendada: cancele a agenda antes de arquivar." };
+  }
+  const q = getQueue();
+  if (q.running.some(s => s.dir === dir) || q.waiting.some(s => s.dir === dir)) {
+    return { ok: false, error: "Este vídeo tem uma tarefa rodando ou na fila: espere terminar para arquivar." };
+  }
+
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ at: new Date().toISOString() }, null, 2) + "\n");
+  renameSync(tmp, file);
+  return { ok: true };
+}

package/studio/api/services/captions.ts

@@ -0,0 +1,268 @@
+/* Position and text of the burned-in captions, edited from the UI. The rules (safe area,
+   anchor, x/y, video → scene → caption) and the HTML live in tools/captions.mjs, the
+   same one assemble.mjs uses when rendering: the preview here is the frame that comes out. */
+
+import { existsSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { readJson } from "./root";
+import { loadVideo } from "../../../tools/timing.mjs";
+import { keepPrevious } from "../../../tools/history.mjs";
+import {
+  ANCHORS,
+  STYLE_KEYS,
+  STYLE_COLORS,
+  STYLES,
+  SIDES,
+  STYLE_LIMITS,
+  captionsHtml,
+  captionsOf,
+  maxChars,
+  styleDefaults,
+  positionOf,
+  safeAreas,
+  replaceSrtText,
+} from "../../../tools/captions.mjs";
+
+type Result = { ok: true; output: string } | { ok: false; error: string };
+
+export function getCaptionsData(dir: string) {
+  const video = loadVideo(dir);
+  /* `texts` belongs to the text, not the position: editing a caption doesn't touch the position draft */
+  const { texts: _, ...position } = positionOf(video);
+  return {
+    format: video.format,
+    safes: safeAreas(video.format),
+    anchors: ANCHORS,
+    styles: STYLES,
+    defaults: styleDefaults(video.format),
+    limits: STYLE_LIMITS,
+    max_chars: maxChars(video.format),
+    position,
+    captions_in_motion: !!video.captions_in_motion,
+    scenes: video.scenes.map((c: any) => ({
+      id: c.id,
+      title: c.title ?? null,
+      start: c.start,
+      duration: c.duration,
+      mp4: !!c.mp4 && existsSync(join(dir, c.mp4)),
+    })),
+    captions: captionsOf(dir, video),
+  };
+}
+
+export function captionsPage(dir: string): Response {
+  const { html } = captionsHtml(dir, loadVideo(dir));
+  return new Response(html, { headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" } });
+}
+
+/* the motion frame at t (video time), from the scene MP4, to sit behind the preview */
+export async function frameAt(dir: string, t: number): Promise<Response> {
+  const video = loadVideo(dir);
+  const scene = video.scenes.find((c: any) => t >= c.start && t < c.start + c.duration) ?? video.scenes.at(-1);
+  const mp4 = scene?.mp4 ? join(dir, scene.mp4) : null;
+  if (!scene || !mp4 || !existsSync(mp4)) return new Response("sem MP4 da cena", { status: 404 });
+  const local = Math.min(Math.max(0, t - scene.start), Math.max(0, scene.duration - 1 / video.format.fps));
+  const p = Bun.spawn(
+    [
+      "ffmpeg",
+      "-loglevel",
+      "error",
+      "-ss",
+      local.toFixed(3),
+      "-i",
+      mp4,
+      "-frames:v",
+      "1",
+      "-vf",
+      "scale=720:-2",
+      "-f",
+      "image2pipe",
+      "-vcodec",
+      "mjpeg",
+      "-q:v",
+      "4",
+      "-",
+    ],
+    { stdout: "pipe", stderr: "ignore" },
+  );
+  const img = await new Response(p.stdout).arrayBuffer();
+  if ((await p.exited) !== 0 || !img.byteLength) return new Response("ffmpeg não tirou o quadro", { status: 500 });
+  return new Response(img, { headers: { "content-type": "image/jpeg", "cache-control": "no-store" } });
+}
+
+/* one position level: only known keys, integer x/y inside the frame */
+function sanitizePosition(
+  value: any,
+  w: number,
+  h: number,
+  keys: string[],
+  safes: Record<string, unknown>,
+): { ok: true; v: Record<string, unknown> } | { ok: false; error: string } {
+  if (value == null || typeof value !== "object") return { ok: false, error: "posição inválida" };
+  const v: Record<string, unknown> = {};
+  for (const k of keys) {
+    const x = value[k];
+    if (x == null) continue;
+    if (k === "anchor" && !ANCHORS.includes(x)) return { ok: false, error: `âncora desconhecida: ${x}` };
+    if (k === "style" && !STYLES.includes(x)) return { ok: false, error: `estilo desconhecido: ${x}` };
+    if (k === "platform" && !(x in safes)) return { ok: false, error: `sem safe area para ${x} neste formato` };
+    if (STYLE_COLORS.includes(k)) {
+      if (typeof x !== "string" || !/^#[0-9a-fA-F]{6}$/.test(x))
+        return { ok: false, error: `${k}: cor inválida (use #rrggbb): ${x}` };
+      v[k] = x.toLowerCase();
+      continue;
+    }
+    if (k in STYLE_LIMITS) {
+      const [min, max, digits] = (STYLE_LIMITS as Record<string, number[]>)[k];
+      const n = Number(x);
+      if (!Number.isFinite(n) || n < min || n > max) return { ok: false, error: `${k}: ${x} fora de ${min} a ${max}` };
+      v[k] = +n.toFixed(digits);
+      continue;
+    }
+    if (k === "hidden") {
+      if (typeof x !== "boolean") return { ok: false, error: "oculta: use true ou false" };
+      if (x) v.hidden = true; /* shown is the default: the key only exists when hidden */
+      continue;
+    }
+    if (k === "x" || k === "y") {
+      const n = Math.round(Number(x));
+      const lim = k === "x" ? w : h;
+      if (!Number.isFinite(n) || Math.abs(n) > lim) return { ok: false, error: `${k} fora do quadro: ${x}` };
+      v[k] = n;
+      continue;
+    }
+    v[k] = x;
+  }
+  return { ok: true, v };
+}
+
+/* safe area override: only the sides the video wants to change, as a fraction of the frame */
+function sanitizeSafeArea(value: any): { ok: true; v: Record<string, number> } | { ok: false; error: string } {
+  if (value == null) return { ok: true, v: {} };
+  if (typeof value !== "object") return { ok: false, error: "safe area inválida" };
+  const v: Record<string, number> = {};
+  for (const side of SIDES) {
+    if (value[side] == null) continue;
+    const n = Number(value[side]);
+    if (!Number.isFinite(n) || n < 0 || n > 0.8)
+      return { ok: false, error: `safe area ${side}: ${value[side]} fora de 0 a 0,8 do quadro` };
+    v[side] = Math.round(n * 10000) / 10000;
+  }
+  return { ok: true, v };
+}
+
+/* scope "video" changes the position of all; "scene" and "caption" write (or, with a
+   null or empty value, remove) the override for that scene or that caption */
+export function saveCaptionPosition(dir: string, body: any): Result {
+  const file = join(dir, "scenes.json");
+  const raw = readJson<any>(file);
+  if (!raw) return { ok: false, error: "scenes.json não existe" };
+  const video = loadVideo(dir);
+  const { w, h } = video.format;
+  const safes = safeAreas(video.format);
+  const cap: Record<string, any> = { ...(raw.captions ?? {}) };
+  const scope = String(body?.scope ?? "");
+  const target = String(body?.target ?? "");
+  let output: string;
+
+  if (scope === "video") {
+    const r = sanitizePosition(body.value, w, h, ["platform", "anchor", "x", "y", "style", ...STYLE_KEYS], safes);
+    if (!r.ok) return r;
+    Object.assign(cap, r.v);
+    /* the video sends the whole state: a style key that didn't come back is back to default */
+    for (const k of STYLE_KEYS as string[]) if (!(k in r.v)) delete cap[k];
+    if ("safe" in body.value) {
+      const sf = sanitizeSafeArea(body.value.safe);
+      if (!sf.ok) return sf;
+      if (Object.keys(sf.v).length) cap.safe = sf.v;
+      else delete cap.safe;
+    }
+    output = "posição de todas as legendas gravada";
+  } else if (scope === "scene" || scope === "caption") {
+    const group = scope === "scene" ? "scenes" : "individual";
+    const exists =
+      scope === "scene"
+        ? video.scenes.some((c: any) => c.id === target)
+        : captionsOf(dir, video).some((l: any) => l.id === target);
+    if (!exists) return { ok: false, error: `${scope === "scene" ? "cena" : "legenda"} ${target} não existe` };
+    if (scope === "scene" && body.value?.hidden != null)
+      return { ok: false, error: "oculta só vale para uma legenda (individuais), não para a cena" };
+    const map: Record<string, unknown> = { ...(cap[group] ?? {}) };
+    const r =
+      body.value == null
+        ? { ok: true as const, v: {} }
+        : sanitizePosition(
+            body.value,
+            w,
+            h,
+            ["anchor", "x", "y", ...STYLE_KEYS, ...(scope === "caption" ? ["hidden"] : [])],
+            safes,
+          );
+    if (!r.ok) return r;
+    if (Object.keys(r.v).length) map[target] = r.v;
+    else delete map[target];
+    if (Object.keys(map).length) cap[group] = map;
+    else delete cap[group];
+    output = Object.keys(r.v).length
+      ? `ajuste de ${target} gravado`
+      : `${target} volta a seguir ${scope === "scene" ? "o vídeo" : "a cena"}`;
+  } else return { ok: false, error: `escopo desconhecido: ${scope}` };
+
+  writeScenes(file, raw, cap);
+  return { ok: true, output };
+}
+
+/* changes a caption's text: goes straight to captions.srt (the previous one stays in
+   the stage history) and `captions.texts` keeps the change for the next generation.
+   Going back to what the line generated removes the change. */
+export function saveCaptionText(dir: string, body: any): Result {
+  const file = join(dir, "scenes.json");
+  const raw = readJson<any>(file);
+  if (!raw) return { ok: false, error: "scenes.json não existe" };
+  const srt = join(dir, "captions.srt");
+  if (!existsSync(srt)) return { ok: false, error: "captions.srt não existe: gere a legenda antes" };
+  const video = loadVideo(dir);
+  const id = String(body?.id ?? "");
+  const captions = captionsOf(dir, video);
+  const index = captions.findIndex((l: any) => l.id === id);
+  if (index < 0) return { ok: false, error: `legenda ${id} não existe` };
+  const text = String(body?.text ?? "")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!text) return { ok: false, error: "texto vazio: para tirar a legenda do vídeo, desligue-a" };
+  const current = captions[index];
+  if (text === current.text) return { ok: true, output: "já era esse o texto" };
+
+  const cap: Record<string, any> = { ...(raw.captions ?? {}) };
+  const texts: Record<string, { text: string; original: string }> = { ...(cap.texts ?? {}) };
+  const original = current.original ?? current.text;
+  if (text === original) delete texts[id];
+  else texts[id] = { text, original };
+  if (Object.keys(texts).length) cap.texts = texts;
+  else delete cap.texts;
+
+  const previous = keepPrevious(dir, "captions", null, ["captions.srt"]);
+  replaceSrtText(srt, index, text);
+  previous.close();
+  writeScenes(file, raw, cap);
+  return {
+    ok: true,
+    output: text === original ? `${id} voltou ao texto da fala` : `texto de ${id} gravado: vale na próxima montagem`,
+  };
+}
+
+/* `captions` right after captions_in_motion (or format), like the rest of the contract */
+function writeScenes(file: string, raw: Record<string, unknown>, cap: Record<string, unknown>) {
+  const next: Record<string, unknown> = {};
+  const after = "captions_in_motion" in raw ? "captions_in_motion" : "format";
+  const empty = !Object.keys(cap).length;
+  for (const [k, v] of Object.entries(raw)) {
+    if (k === "captions") continue;
+    next[k] = v;
+    if (k === after && !empty) next.captions = cap;
+  }
+  if (!empty && !("captions" in next)) next.captions = cap;
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n");
+  renameSync(tmp, file);
+}

package/studio/api/services/carousel.ts

@@ -0,0 +1,206 @@
+/* A content's Instagram carousel (videos/<slug>/carousel/): what the UI shows and
+   what it requests. State and stages come from tools/carousel.mjs's diagnosis
+   (imported, no process spawned); Claude writes and composes it (skill
+   av-carousel) through the content's session; publish.mjs carousel publishes it.
+
+   What a content delivers (video, carousel or both) lives in content.json, written
+   by the UI request. Content from before it: video, plus carousel if the dir has one. */
+
+import { existsSync, readdirSync, statSync, writeFileSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { NODE, TOOLS_DIR, run, readJson, readText } from "./root";
+import { openSession, replyToSession, latestSessionFor, type ApiResult } from "./sessions";
+import { diagnosisOf } from "../../../tools/carousel.mjs";
+
+export type Deliverable = "video" | "carousel";
+const DELIVERABLES: Deliverable[] = ["video", "carousel"];
+/* content.json written before the rename may still say "carrossel" */
+const LEGACY_DELIVERABLE: Record<string, Deliverable> = { carrossel: "carousel" };
+
+export function deliverables(dir: string): Deliverable[] {
+  const stored = readJson<{ deliverables?: unknown; entregas?: unknown }>(join(dir, "content.json"));
+  const list = stored?.deliverables ?? stored?.entregas;
+  if (Array.isArray(list)) {
+    const names = list.map(e => LEGACY_DELIVERABLE[String(e)] ?? e);
+    const valid = DELIVERABLES.filter(e => names.includes(e));
+    if (valid.length) return valid;
+  }
+  const hasCarousel = existsSync(join(dir, "carousel", "carousel.json"));
+  const hasVideo = !hasCarousel || existsSync(join(dir, "scenes.json")) || existsSync(join(dir, "script.md"));
+  return DELIVERABLES.filter(e => (e === "video" ? hasVideo : hasCarousel));
+}
+
+function writeJson(file: string, data: unknown) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n");
+  renameSync(tmp, file);
+}
+
+/* "Sem narração e voz" (content.json `narration: false`): the video skips the spoken script, the narration, the
+   voice and the captions, and goes from the request to the motion script, the composition and the editor.
+   Absent means narrated. */
+export const narration = (dir: string) =>
+  readJson<{ narration?: unknown }>(join(dir, "content.json"))?.narration !== false;
+
+export function writeNarration(dir: string, on: boolean) {
+  const file = join(dir, "content.json");
+  const { narration: _old, ...rest } = readJson<Record<string, unknown>>(file) ?? {};
+  writeJson(file, on ? rest : { ...rest, narration: false });
+}
+
+export function writeDeliverables(dir: string, list: Deliverable[]) {
+  const file = join(dir, "content.json");
+  const { entregas: _legacy, ...rest } = readJson<Record<string, unknown>>(file) ?? {};
+  writeJson(file, { ...rest, deliverables: DELIVERABLES.filter(e => list.includes(e)) });
+}
+
+const fileEntry = (dir: string, path: string) => {
+  try {
+    return { path, size: 0, mtime: Math.round(statSync(join(dir, path)).mtimeMs) };
+  } catch {
+    return null;
+  }
+};
+
+/* the list summary: stages and the cover (the first slide's PNG) */
+export function carouselSummary(dir: string) {
+  if (!existsSync(join(dir, "carousel", "carousel.json"))) return null;
+  let diag: any;
+  try {
+    diag = diagnosisOf(dir);
+  } catch (e: any) {
+    return { error: e.message, stages: [], next: null, slides: 0, cover: null, publication: null };
+  }
+  const c = readJson<any>(join(dir, "carousel", "carousel.json"));
+  const first = c?.slides?.[0]?.id;
+  return {
+    title: diag.title ?? null,
+    format: diag.format ?? null,
+    slides: diag.slides ?? 0,
+    stages: diag.stages as { id: string; name: string; ok: boolean; missing: string | null }[],
+    warnings: diag.warnings as string[],
+    next: diag.next as string | null,
+    cover: first ? fileEntry(dir, `carousel/png/${first}.png`) : null,
+    publication: readJson<any>(join(dir, "carousel", "publication.json")),
+  };
+}
+
+/* the page detail: slides with PNG and warnings, the texts, the export */
+export function carouselDetail(dir: string) {
+  const base = carouselSummary(dir);
+  if (!base) return null;
+  const cdir = join(dir, "carousel");
+  const c = readJson<any>(join(cdir, "carousel.json")) ?? {};
+  const build = readJson<any>(join(cdir, "build.json"))?.slides ?? {};
+  const exp = readJson<any>(join(cdir, "export", "export.json"));
+  let jpgs: string[] = [];
+  try {
+    jpgs = readdirSync(join(cdir, "export"))
+      .filter(n => /^\d{2}\.jpg$/.test(n))
+      .sort();
+  } catch {
+    /* no export */
+  }
+  return {
+    ...base,
+    goal: c.goal ?? null,
+    caption: c.caption ?? "",
+    origin: c.origin ?? null,
+    references: c.references ?? [],
+    slide_list: (c.slides ?? []).map((s: any) => ({
+      id: s.id,
+      role: s.role ?? null,
+      title: s.title ?? null,
+      text: s.text ?? null,
+      hero: s.hero ?? null,
+      png: fileEntry(dir, `carousel/png/${s.id}.png`),
+      warnings: build[s.id]?.warnings ?? [],
+      generated_at: build[s.id]?.generated_at ?? null,
+    })),
+    sheet: fileEntry(dir, "carousel/_sheet.png"),
+    export: exp
+      ? { at: exp.exported_at, jpgs: jpgs.map(n => fileEntry(dir, `carousel/export/${n}`)).filter(Boolean) }
+      : null,
+    texts: { script: readText(join(cdir, "script.md")), composition: readText(join(cdir, "composition.md")) },
+  };
+}
+
+/* --- UI requests -----------------------------------------------------------------------
+   Everything goes to the content's session (the same as the video's): resume the latest, or open one. */
+function askAgent(slug: string, dir: string, title: string, message: string, origin: string): ApiResult {
+  const latest = latestSessionFor("video", slug);
+  if (latest) return replyToSession(latest.id, message, origin);
+  return openSession("video", slug, dir, title, `/omnivideo\n${message}`, origin);
+}
+
+/* create the carousel: from the dir's video (if any) or from the request */
+export function createCarousel(slug: string, dir: string, title: string, note: string): ApiResult {
+  const list = deliverables(dir);
+  const hasVideo = existsSync(join(dir, "script.md")) || existsSync(join(dir, "scenes.json"));
+  if (!list.includes("carousel")) writeDeliverables(dir, [...list, "carousel"]);
+  const extra = note.trim();
+  const msg = [
+    `Carrossel do Instagram para o conteúdo videos/${slug}, pedido pela tela do studio.`,
+    hasVideo
+      ? `Ele nasce do vídeo da pasta: chame a skill av-carousel com \`videos/${slug} do vídeo\` (init com --from-video). O vídeo não muda.`
+      : `Chame a skill av-carousel com \`videos/${slug}\`; o pedido está em videos/${slug}/source/request.md.`,
+    extra ? `O que o usuário quer no carrossel: ${extra}` : "",
+    "Vá até o export (carousel.mjs export) e pare: publicar é pelo botão da tela.",
+  ]
+    .filter(Boolean)
+    .join("\n");
+  return askAgent(slug, dir, title, msg, "carousel");
+}
+
+/* change requested on one slide (or on the whole carousel, without slide) */
+export function adjustCarousel(slug: string, dir: string, title: string, body: any): ApiResult {
+  if (!existsSync(join(dir, "carousel", "carousel.json")))
+    return { ok: false, error: "este conteúdo ainda não tem carrossel" };
+  const request = String(body?.request ?? "").trim();
+  if (!request) return { ok: false, error: "diga o que mudar" };
+  const slide = String(body?.slide ?? "").trim();
+  if (slide && !/^s\d{2}$/.test(slide)) return { ok: false, error: "slide inválido" };
+  const stage = body?.stage === "script" ? "script" : "composition";
+  const target = slide ? `${slide} «${request}»` : `«${request}»`;
+  const msg = [
+    `Alteração no carrossel de videos/${slug}, pedida pela tela do studio (${stage === "script" ? "etapa Roteiro" : "etapa Composição"}).`,
+    `Chame a skill av-carousel com \`videos/${slug} ajustar: ${target}\`: mude só isso, refaça o build do que mudou, leia os PNG e exporte de novo.`,
+  ].join("\n");
+  return askAgent(slug, dir, title, msg, "carousel");
+}
+
+/* the post caption, edited in the UI: overrides the one in carousel.json */
+export function saveCaption(dir: string, caption: unknown): ApiResult {
+  const cdir = join(dir, "carousel");
+  if (!existsSync(join(cdir, "carousel.json"))) return { ok: false, error: "este conteúdo ainda não tem carrossel" };
+  const text = String(caption ?? "").trim();
+  if (text.length > 2200)
+    return { ok: false, error: `a legenda tem ${text.length} caracteres (o Instagram aceita até 2200)` };
+  const file = join(cdir, "publication.json");
+  writeJson(file, { ...(readJson<object>(file) ?? {}), caption: text });
+  return { ok: true, output: "legenda gravada" };
+}
+
+const publishing = new Set<string>();
+export async function publishCarousel(dir: string, body: any): Promise<ApiResult> {
+  if (publishing.has(dir)) return { ok: false, error: "este carrossel já está sendo publicado" };
+  if (body?.caption != null) {
+    const saved = saveCaption(dir, body.caption);
+    if (!saved.ok) return saved;
+  }
+  publishing.add(dir);
+  try {
+    const r = await run(
+      [NODE, join(TOOLS_DIR, "publish.mjs"), "carousel", dir, "--confirm", ...(body?.republish ? ["--again"] : [])],
+      { OMNIVIDEO_ORIGIN: "studio" },
+    );
+    const output = [r.stdout, r.stderr]
+      .map(s => s.trim())
+      .filter(Boolean)
+      .join("\n")
+      .replace(/^erro: /gm, "");
+    return r.code === 0 ? { ok: true, output } : { ok: false, error: output || `publish.mjs saiu com ${r.code}` };
+  } finally {
+    publishing.delete(dir);
+  }
+}