wizz-method 2.16.0 → 2.17.1

package/src/skills-lib/wizz-video-styles/assets/remotion/editorial/primitives.tsx

@@ -0,0 +1,241 @@
+import React, { useId } from "react";
+import { AbsoluteFill, Easing, Img, interpolate, spring, staticFile, useCurrentFrame } from "remotion";
+import { FPS, H, W, useTheme } from "./theme";
+
+// Vocabulário do estilo: fundo claro com grade, cards escuros com sombra funda,
+// serifa itálica bicolor, pílula digitada, conector tracejado, raios, contador.
+
+export const clamp = { extrapolateLeft: "clamp", extrapolateRight: "clamp" } as const;
+export const ease = Easing.bezier(0.22, 1, 0.36, 1);
+export const useSeconds = (): number => useCurrentFrame() / FPS;
+export const pop = (frame: number, delay = 0): number =>
+  spring({ frame: frame - Math.round(delay * FPS), fps: FPS, config: { damping: 15, mass: 0.7 } });
+
+const CX = W / 2;
+
+// Envelope de cena: entra subindo com mola, sai subindo e sumindo (sem corte seco).
+export const Stage: React.FC<{ dur: number; children: React.ReactNode }> = ({ dur, children }) => {
+  const frame = useCurrentFrame();
+  const t = frame / FPS;
+  const s = pop(frame);
+  const out = interpolate(t, [dur - 0.3, dur], [0, 1], { ...clamp, easing: Easing.in(Easing.cubic) });
+  const cam = interpolate(t, [0, dur], [1, 1.035], clamp);
+  return (
+    <AbsoluteFill
+      style={{
+        opacity: Math.min(1, s * 1.4) * (1 - out),
+        transform: `translateY(${(1 - s) * 70 - out * 60}px) scale(${(0.94 + 0.06 * s) * cam})`,
+      }}
+    >
+      {children}
+    </AbsoluteFill>
+  );
+};
+
+export const Backdrop: React.FC = () => {
+  const c = useTheme();
+  return (
+    <AbsoluteFill
+      style={{
+        background: c.bg,
+        backgroundImage: `linear-gradient(${c.grid} 2px, transparent 2px), linear-gradient(90deg, ${c.grid} 2px, transparent 2px)`,
+        backgroundSize: "72px 72px",
+      }}
+    >
+      <AbsoluteFill style={{ background: `radial-gradient(ellipse at 50% 45%, ${c.glow}, rgba(0,0,0,0) 60%, ${c.vignette})` }} />
+    </AbsoluteFill>
+  );
+};
+
+// Título serifado em duas linhas: a primeira na cor do texto, a segunda no destaque.
+export const Headline: React.FC<{ a: string; b: string; top?: number; delay?: number; size?: number }> = ({
+  a, b, top = 300, delay = 0, size = 104,
+}) => {
+  const c = useTheme();
+  const frame = useCurrentFrame();
+  const s1 = pop(frame, delay);
+  const s2 = pop(frame, delay + 0.18);
+  const base = { fontFamily: c.serif, fontWeight: 700, fontSize: size, lineHeight: 1.0, letterSpacing: -2 } as const;
+  return (
+    <div style={{ position: "absolute", top, left: 0, right: 0, textAlign: "center" }}>
+      <div style={{ ...base, color: c.ink, opacity: s1, transform: `translateY(${(1 - s1) * 30}px)` }}>{a}</div>
+      <div style={{ ...base, color: c.accent, opacity: s2, transform: `translateY(${(1 - s2) * 30}px)` }}>{b}</div>
+    </div>
+  );
+};
+
+// Raios que "acendem" abaixo de uma pílula (o agente trabalhando). grow: 0..1.
+export const Rays: React.FC<{ grow: number; y: number; size?: number }> = ({ grow, y, size = 300 }) => {
+  const c = useTheme();
+  const frame = useCurrentFrame();
+  const n = 11;
+  return (
+    <div style={{ position: "absolute", left: CX - size, top: y, width: size * 2, height: size, overflow: "hidden" }}>
+      {Array.from({ length: n }, (_, i) => {
+        const angle = -80 + (160 / (n - 1)) * i;
+        const wobble = Math.sin(frame / 9 + i) * 0.06;
+        const len = size * (0.62 + (0.3 * ((i * 7) % 5)) / 4) * grow * (1 + wobble);
+        return (
+          <div
+            key={i}
+            style={{
+              position: "absolute", left: size - 17, top: 0, width: 34, height: len, borderRadius: 17,
+              background: `linear-gradient(${c.accentWarm}, ${c.accentLight})`,
+              transformOrigin: "50% 0%", transform: `rotate(${angle}deg)`,
+              boxShadow: `0 10px 18px ${c.accentShadow}`,
+            }}
+          />
+        );
+      })}
+    </div>
+  );
+};
+
+// Anel girando: objeto-símbolo de abertura.
+export const Ring: React.FC<{ y?: number; size?: number }> = ({ y = 760, size = 420 }) => {
+  const c = useTheme();
+  const frame = useCurrentFrame();
+  const s = pop(frame, 0.1);
+  return (
+    <div style={{ position: "absolute", left: CX - size / 2, top: y, width: size, height: size, transform: `scale(${s}) rotate(${frame * 0.8}deg)` }}>
+      <div style={{ position: "absolute", inset: 0, borderRadius: "50%", border: `${size * 0.186}px solid ${c.accent}`, borderRightColor: "transparent", boxShadow: `0 50px 80px ${c.accentShadow}` }} />
+    </div>
+  );
+};
+
+// Pílula escura com texto digitado (input de prompt). Tempos em segundos da cena.
+export const Pill: React.FC<{
+  text: string; typeFrom: number; typeDur: number; y: number; w?: number; icon?: string; serif?: boolean;
+}> = ({ text, typeFrom, typeDur, y, w = 820, icon = "✦", serif = true }) => {
+  const c = useTheme();
+  const t = useSeconds();
+  const n = Math.round(interpolate(t, [typeFrom, typeFrom + typeDur], [0, text.length], clamp));
+  const caret = n < text.length && Math.floor(t * 3) % 2 === 0;
+  return (
+    <div style={{ position: "absolute", left: CX - w / 2, top: y, width: w, height: 150, borderRadius: 40, background: `linear-gradient(${c.cardHi}, ${c.card})`, boxShadow: c.shadow, display: "flex", alignItems: "center", padding: "0 44px", gap: 28 }}>
+      <div style={{ width: 62, height: 62, borderRadius: 18, background: c.accent, color: c.onAccent, display: "flex", alignItems: "center", justifyContent: "center", fontSize: 34 }}>{icon}</div>
+      <div style={{ fontFamily: serif ? c.serif : c.sans, fontWeight: 600, fontSize: 56, color: c.line, whiteSpace: "nowrap" }}>
+        {text.slice(0, n)}
+        <span style={{ color: c.accentLight, opacity: caret ? 1 : 0 }}>|</span>
+      </div>
+    </div>
+  );
+};
+
+// Chip pequeno, centrado em (x, y). Entra com mola em `delay` (s).
+export const Chip: React.FC<{
+  label: string; x: number; y: number; delay: number; accent?: boolean; big?: boolean; icon?: string;
+}> = ({ label, x, y, delay, accent, big, icon = "▤" }) => {
+  const c = useTheme();
+  const s = pop(useCurrentFrame(), delay);
+  return (
+    <div style={{ position: "absolute", left: x, top: y, transform: `translate(-50%,-50%) scale(${s})`, opacity: s > 0.02 ? 1 : 0, background: accent ? c.accent : `linear-gradient(${c.cardHi}, ${c.card})`, color: accent ? c.onAccent : c.line, borderRadius: 26, padding: big ? "26px 40px" : "20px 32px", boxShadow: c.shadow, display: "flex", alignItems: "center", gap: 18, fontFamily: c.serif, fontWeight: 600, fontSize: big ? 52 : 44, whiteSpace: "nowrap" }}>
+      {icon ? <span style={{ fontFamily: c.sans, fontSize: big ? 34 : 28, opacity: 0.8 }}>{icon}</span> : null}
+      {label}
+    </div>
+  );
+};
+
+// Conector tracejado que se desenha de (x1,y1) a (x2,y2) a partir de `from` (s).
+export const Dash: React.FC<{ x1: number; y1: number; x2: number; y2: number; from: number; dur?: number }> = ({
+  x1, y1, x2, y2, from, dur = 0.45,
+}) => {
+  const c = useTheme();
+  const t = useSeconds();
+  const id = `dash${useId().replace(/[^a-zA-Z0-9]/g, "")}`;
+  const p = interpolate(t, [from, from + dur], [0, 1], { ...clamp, easing: ease });
+  const len = Math.hypot(x2 - x1, y2 - y1);
+  const d = `M ${x1} ${y1} C ${x1} ${(y1 + y2) / 2}, ${(x1 + x2) / 2} ${y2}, ${x2} ${y2}`;
+  return (
+    <svg style={{ position: "absolute", inset: 0 }} width={W} height={H}>
+      <defs>
+        <mask id={id}>
+          <path d={d} stroke="#fff" strokeWidth={10} fill="none" strokeDasharray={len * 1.5} strokeDashoffset={len * 1.5 * (1 - p)} />
+        </mask>
+      </defs>
+      <path d={d} stroke={c.dash} strokeWidth={4} fill="none" strokeDasharray="10 12" mask={`url(#${id})`} />
+    </svg>
+  );
+};
+
+const resolveSrc = (src: string): string => (/^(https?:|data:)/.test(src) ? src : staticFile(src));
+
+// Celular-card com screenshot em proporção real. `ratio` = altura/largura da imagem
+// (iPhone 1206x2622 = 2.174). Sem `src`, desenha uma tela de exemplo (o molde roda sem assets).
+export const PhoneCard: React.FC<{
+  src?: string; y?: number; scale?: number; focusY?: number; maxH?: number; ratio?: number;
+}> = ({ src, y = 250, scale = 1, focusY = 0, maxH = 1180, ratio = 2622 / 1206 }) => {
+  const c = useTheme();
+  const w = 600 * scale;
+  const h = w * ratio;
+  const viewH = Math.min(h, maxH);
+  return (
+    <div style={{ position: "absolute", left: CX - w / 2 - 16, top: y, width: w + 32, height: viewH + 32, borderRadius: 74 * scale, background: c.card, padding: 16, boxShadow: c.shadow }}>
+      <div style={{ width: w, height: viewH, borderRadius: 60 * scale, overflow: "hidden", background: c.bg }}>
+        {src ? (
+          <Img src={resolveSrc(src)} style={{ width: w, height: h, transform: `translateY(${-focusY * scale}px)` }} />
+        ) : (
+          <div style={{ padding: `${60 * scale}px ${40 * scale}px`, display: "flex", flexDirection: "column", gap: 28 * scale }}>
+            <div style={{ height: 70 * scale, borderRadius: 20 * scale, background: c.accent }} />
+            {Array.from({ length: 6 }, (_, i) => (
+              <div key={i} style={{ height: 120 * scale, borderRadius: 24 * scale, background: c.line, opacity: 1 - i * 0.1 }} />
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+};
+
+// Card com número que sobe até `to` a partir de `delay` (s).
+export const Counter: React.FC<{ to: number; label: string; y: number; delay: number }> = ({ to, label, y, delay }) => {
+  const c = useTheme();
+  const frame = useCurrentFrame();
+  const s = pop(frame, delay);
+  const v = Math.round(interpolate(frame / FPS, [delay, delay + 1.0], [0, to], { ...clamp, easing: Easing.out(Easing.cubic) }));
+  return (
+    <div style={{ position: "absolute", left: 140, right: 140, top: y, height: 330, borderRadius: 44, background: `linear-gradient(${c.cardHi}, ${c.card})`, boxShadow: c.shadow, transform: `scale(${s})`, opacity: s > 0.02 ? 1 : 0, display: "flex", flexDirection: "column", alignItems: "center", justifyContent: "center" }}>
+      <div style={{ fontFamily: c.serif, fontWeight: 700, fontSize: 180, color: c.accentLight, lineHeight: 1 }}>{v}</div>
+      <div style={{ fontFamily: c.serif, fontWeight: 600, fontSize: 52, color: c.line, marginTop: 6 }}>{label}</div>
+    </div>
+  );
+};
+
+export type DocPage = { lines: string[]; at: number; mono?: boolean }; // `at` em s da cena
+const REVIEW_SPOTS = [
+  { x: 175, y: 560 }, { x: 905, y: 700 }, { x: 175, y: 1020 }, { x: 905, y: 1160 },
+] as const;
+
+// Card alto escuro (documento). Cada página troca o conteúdo e digita as linhas;
+// `reviewers` pendura até 4 chips conectados por tracejado ao redor do card.
+export const DocCard: React.FC<{
+  pages: DocPage[]; title: string; altTitle?: string; reviewers?: { labels: string[]; at: number };
+}> = ({ pages, title, altTitle, reviewers }) => {
+  const c = useTheme();
+  const t = useSeconds();
+  const page = [...pages].reverse().find((p) => t >= p.at) ?? pages[0];
+  const isAlt = page !== pages[0];
+  const shown = page.lines.slice(0, Math.round(interpolate(t, [page.at + 0.2, page.at + 1.2], [0, page.lines.length], clamp)));
+  return (
+    <>
+      <div style={{ position: "absolute", left: 220, top: 380, width: 640, height: 980, borderRadius: 48, background: `linear-gradient(${c.cardHi}, ${c.card})`, boxShadow: c.shadow, padding: "130px 48px 0", overflow: "hidden" }}>
+        {shown.map((l, i) => (
+          <div key={`${page.at}-${i}`} style={{ fontFamily: page.mono ? c.mono : c.sans, fontSize: 25, lineHeight: page.mono ? "46px" : "42px", color: i === 0 && !page.mono ? c.accentLight : c.line, whiteSpace: "nowrap", overflow: "hidden", opacity: 0.92 }}>
+            {l}
+          </div>
+        ))}
+      </div>
+      <Chip label={isAlt && altTitle ? altTitle : title} x={CX} y={380} delay={0.05} accent={isAlt} />
+      {(reviewers?.labels ?? []).slice(0, 4).map((label, i) => {
+        const spot = REVIEW_SPOTS[i];
+        const from = (reviewers?.at ?? 0) + i * 0.22;
+        return (
+          <React.Fragment key={label}>
+            <Dash x1={spot.x < CX ? 230 : 850} y1={spot.y} x2={spot.x} y2={spot.y} from={from} dur={0.2} />
+            <Chip label={label} x={spot.x} y={spot.y} delay={from} accent />
+          </React.Fragment>
+        );
+      })}
+    </>
+  );
+};

package/src/skills-lib/wizz-video-styles/assets/remotion/editorial/scenes.tsx

@@ -0,0 +1,113 @@
+import React from "react";
+import { interpolate } from "remotion";
+import {
+  Chip, Counter, Dash, DocCard, Headline, PhoneCard, Pill, Rays, Ring, clamp, ease, useSeconds,
+  type DocPage,
+} from "./primitives";
+import { useTheme } from "./theme";
+import type { Anchored } from "./timeline";
+
+// Cenas como DADOS: cada objeto do array vira um componente. `at` é a palavra-âncora
+// onde a cena começa; `marks` nomeia palavras internas (ex.: quando o contador sobe).
+
+export type SceneDef = Anchored &
+  (
+    | { kind: "hook"; a: string; b: string }
+    | { kind: "prompt"; a: string; b: string; prompt: string; typedMark?: string }
+    | { kind: "phone"; src?: string; ratio?: number; scale?: number; y?: number; focusY?: number }
+    | { kind: "numbers"; chip: string; counters: { to: number; label: string; mark: string }[] }
+    | { kind: "steps"; prompt: string; items: [string, string, string]; typedMark?: string }
+    | { kind: "doc"; title: string; altTitle?: string; pages: (Omit<DocPage, "at"> & { mark?: string })[]; reviewers?: { labels: string[]; mark: string } }
+    | { kind: "cta"; a: string; b: string; keyword: string; footer: string; hideCaptions?: boolean }
+  );
+
+export type SceneCtx = { dur: number; mark: (name: string | undefined, fallback?: number) => number };
+
+const Hook: React.FC<{ a: string; b: string }> = ({ a, b }) => (
+  <>
+    <Headline a={a} b={b} />
+    <Ring />
+  </>
+);
+
+const Prompt: React.FC<{ a: string; b: string; prompt: string; typed: number; dur: number }> = ({ a, b, prompt, typed, dur }) => {
+  const t = useSeconds();
+  return (
+    <>
+      <Headline a={a} b={b} />
+      <Pill text={prompt} typeFrom={0.2} typeDur={Math.min(typed, dur * 0.6)} y={820} />
+      <Rays grow={interpolate(t, [0.4, 1.0], [0, 1], { ...clamp, easing: ease })} y={970} />
+    </>
+  );
+};
+
+const Numbers: React.FC<{ chip: string; counters: { to: number; label: string; delay: number }[] }> = ({ chip, counters }) => (
+  <>
+    <Chip label={chip} x={540} y={330} delay={0.05} accent />
+    {counters.slice(0, 2).map((c, i) => (
+      <Counter key={c.label} to={c.to} label={c.label} y={470 + i * 390} delay={c.delay} />
+    ))}
+  </>
+);
+
+const Steps: React.FC<{ prompt: string; items: [string, string, string]; typed: number }> = ({ prompt, items, typed }) => {
+  const t = useSeconds();
+  const spots = [
+    { x: 230, y: 1000, from: [300, 760] as const, delay: 0.25 },
+    { x: 540, y: 1100, from: [540, 760] as const, delay: 0.55 },
+    { x: 850, y: 1000, from: [780, 760] as const, delay: 0.85 },
+  ];
+  return (
+    <>
+      <Pill text={prompt} typeFrom={0.1} typeDur={Math.max(0.6, typed - 0.1)} y={330} w={700} />
+      <Rays grow={interpolate(t, [0.1, 0.6], [0, 1], { ...clamp, easing: ease })} y={480} size={260} />
+      {spots.map((s, i) => (
+        <React.Fragment key={items[i]}>
+          <Dash x1={s.from[0]} y1={s.from[1]} x2={s.x} y2={s.y - 40} from={s.delay - 0.05} />
+          <Chip label={items[i]} x={s.x} y={s.y} delay={s.delay} />
+        </React.Fragment>
+      ))}
+    </>
+  );
+};
+
+const Cta: React.FC<{ a: string; b: string; keyword: string; footer: string }> = ({ a, b, keyword, footer }) => {
+  const c = useTheme();
+  const t = useSeconds();
+  return (
+    <>
+      <Headline a={a} b={b} top={360} />
+      <Pill text={keyword} typeFrom={0.35} typeDur={0.5} y={760} w={520} />
+      <Rays grow={interpolate(t, [0.6, 1.1], [0, 1], { ...clamp, easing: ease })} y={910} />
+      <div style={{ position: "absolute", top: 1290, left: 120, right: 120, textAlign: "center", fontFamily: c.serif, fontWeight: 600, fontSize: 54, color: c.ink, lineHeight: 1.2 }}>
+        {footer}
+      </div>
+    </>
+  );
+};
+
+export const SceneView: React.FC<{ scene: SceneDef; ctx: SceneCtx }> = ({ scene, ctx }) => {
+  switch (scene.kind) {
+    case "hook":
+      return <Hook a={scene.a} b={scene.b} />;
+    case "prompt":
+      return <Prompt a={scene.a} b={scene.b} prompt={scene.prompt} typed={ctx.mark(scene.typedMark, 1.1)} dur={ctx.dur} />;
+    case "phone":
+      return <PhoneCard src={scene.src} ratio={scene.ratio} scale={scene.scale ?? 1} y={scene.y ?? 260} focusY={scene.focusY} maxH={1200} />;
+    case "numbers":
+      return <Numbers chip={scene.chip} counters={scene.counters.map((c) => ({ ...c, delay: ctx.mark(c.mark, 0.3) }))} />;
+    case "steps":
+      return <Steps prompt={scene.prompt} items={scene.items} typed={ctx.mark(scene.typedMark, 0.8)} />;
+    case "doc":
+      return (
+        <DocCard
+          title={scene.title}
+          altTitle={scene.altTitle}
+          pages={scene.pages.map((p, i) => ({ lines: p.lines, mono: p.mono, at: i === 0 ? 0.2 : ctx.mark(p.mark, 1) }))}
+          reviewers={scene.reviewers ? { labels: scene.reviewers.labels, at: ctx.mark(scene.reviewers.mark, 2) } : undefined}
+        />
+      );
+    case "cta":
+      return <Cta a={scene.a} b={scene.b} keyword={scene.keyword} footer={scene.footer} />;
+  }
+};

package/src/skills-lib/wizz-video-styles/assets/remotion/editorial/theme.ts

@@ -0,0 +1,68 @@
+import { createContext, useContext } from "react";
+import { loadFont as loadInter } from "@remotion/google-fonts/Inter";
+import { loadFont as loadJetBrainsMono } from "@remotion/google-fonts/JetBrainsMono";
+import { loadFont as loadPlayfair } from "@remotion/google-fonts/PlayfairDisplay";
+
+// Tema do estilo "motion editorial". Tudo que é cor, fonte e sombra mora aqui;
+// as peças leem via useTheme() e a composição aceita um tema parcial por props.
+
+export const W = 1080;
+export const H = 1920;
+export const FPS = 30;
+
+const playfair = loadPlayfair("italic", { weights: ["600", "700"], subsets: ["latin"] });
+const inter = loadInter("normal", { weights: ["400", "700", "800"], subsets: ["latin"] });
+const mono = loadJetBrainsMono("normal", { weights: ["500", "700"], subsets: ["latin"] });
+
+export const waitForFonts = (): Promise<unknown[]> =>
+  Promise.all([playfair.waitUntilDone(), inter.waitUntilDone(), mono.waitUntilDone()]);
+
+export type EditorialTheme = {
+  bg: string; // fundo claro
+  grid: string; // linhas da grade (rgba bem sutil)
+  glow: string; // luz central do fundo
+  vignette: string; // escurecimento das bordas
+  ink: string; // texto principal sobre o fundo
+  card: string; // base dos cards escuros
+  cardHi: string; // topo do gradiente dos cards
+  line: string; // texto claro sobre card escuro
+  onAccent: string; // texto sobre a cor de destaque
+  accent: string; // cor de destaque (palavra-chave, chips, anel)
+  accentWarm: string; // início do gradiente dos raios
+  accentLight: string; // fim do gradiente, contadores, cursor
+  accentShadow: string; // sombra dos raios e do anel
+  dash: string; // conector tracejado
+  shadow: string; // sombra funda dos cards
+  serif: string;
+  sans: string;
+  mono: string;
+};
+
+export const defaultTheme: EditorialTheme = {
+  bg: "#EEE7DA",
+  grid: "rgba(60,40,20,.045)",
+  glow: "rgba(255,255,255,.55)",
+  vignette: "rgba(80,50,20,.10)",
+  ink: "#1A1A1A",
+  card: "#1C1916",
+  cardHi: "#2A2521",
+  line: "#DFD8C6",
+  onAccent: "#FFFFFF",
+  accent: "#B5541C",
+  accentWarm: "#C9622A",
+  accentLight: "#E39A6C",
+  accentShadow: "rgba(150,70,20,.25)",
+  dash: "#6B5A4A",
+  shadow: "0 50px 90px rgba(70,40,15,.32), 0 12px 24px rgba(40,20,5,.22)",
+  serif: playfair.fontFamily,
+  sans: inter.fontFamily,
+  mono: mono.fontFamily,
+};
+
+export const mergeTheme = (overrides?: Partial<EditorialTheme>): EditorialTheme => ({
+  ...defaultTheme,
+  ...overrides,
+});
+
+export const ThemeContext = createContext<EditorialTheme>(defaultTheme);
+export const useTheme = (): EditorialTheme => useContext(ThemeContext);

package/src/skills-lib/wizz-video-styles/assets/remotion/editorial/timeline.ts

@@ -0,0 +1,65 @@
+import { FPS } from "./theme";
+
+// Timing vem do ctc-align: { words: [{ text, start, end }], total } em segundos.
+// Trocar a voz = realinhar o JSON; as cenas seguem as palavras-âncora, não segundos.
+
+export type Word = { text: string; start: number; end: number };
+export type WordsData = { words: Word[]; total: number };
+
+export const norm = (s: string): string => s.toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
+
+// Início (s) da primeira palavra `text` que começa em `after` ou depois.
+// A busca é monotônica: sempre passe o tempo da âncora anterior como `after`,
+// assim palavras repetidas ("e", "o") não casam com uma ocorrência antiga.
+export const at = (words: readonly Word[], text: string, after = 0): number => {
+  const target = norm(text);
+  const hit = words.find((w) => w.start >= after - 0.001 && norm(w.text) === target);
+  if (!hit) throw new Error(`palavra não encontrada depois de ${after}s: "${text}"`);
+  return hit.start;
+};
+
+// Resolve um mapa nome -> palavra em tempos absolutos (monotônico na ordem de declaração).
+export const resolveMarks = (
+  words: readonly Word[],
+  marks: Readonly<Record<string, string>> | undefined,
+  from: number,
+): Record<string, number> =>
+  Object.entries(marks ?? {}).reduce<{ cursor: number; out: Record<string, number> }>(
+    (acc, [name, text]) => {
+      const t = at(words, text, acc.cursor);
+      return { cursor: t, out: { ...acc.out, [name]: t } };
+    },
+    { cursor: from, out: {} },
+  ).out;
+
+export type Anchored = { at: string; marks?: Record<string, string> };
+
+export type TimedScene<T extends Anchored> = {
+  def: T;
+  from: number; // s, absoluto
+  dur: number; // s
+  marks: Record<string, number>; // s, RELATIVO ao início da cena (usa direto dentro da Sequence)
+};
+
+// Monta as cenas por âncora: cada cena começa na sua palavra e vai até a âncora da
+// próxima. `overlap` faz a cena seguinte entrar um pouco antes enquanto a anterior sobe.
+export const buildScenes = <T extends Anchored>(
+  words: readonly Word[],
+  defs: readonly T[],
+  opts: { end: number; overlap?: number },
+): TimedScene<T>[] => {
+  const overlap = opts.overlap ?? 0.12;
+  const starts = defs.reduce<number[]>((acc, d) => [...acc, at(words, d.at, acc[acc.length - 1] ?? 0)], []);
+  return defs.map((def, i) => {
+    const from = Math.max(0, starts[i] - (i ? overlap : 0));
+    const to = starts[i + 1] ?? opts.end;
+    const abs = resolveMarks(words, def.marks, starts[i]);
+    const marks = Object.fromEntries(Object.entries(abs).map(([k, v]) => [k, v - from]));
+    return { def, from, dur: to - from + overlap, marks };
+  });
+};
+
+export const toFrames = (seconds: number): number => Math.round(seconds * FPS);
+
+// Duração total do filme: fim da fala + respiro final.
+export const totalSeconds = (data: WordsData, tail = 1.4): number => data.total + tail;