primocode 10.16.0 → 10.17.0

package/editor/helpers/text_render.py

@@ -0,0 +1,2059 @@
+"""Text rendering for editor-video: captions, hooks, CTA and disclaimer (Contract 7).
+
+Everything is drawn with PIL on a transparent RGBA canvas of the output size and
+composited later with ffmpeg `overlay` (the dev ffmpeg has no drawtext/subtitles/ass).
+
+Public API (see SPEC.md, Contract 7):
+    render_hook, render_caption_track, render_cta, render_disclaimer,
+    render_sample_frame, write_ffconcat
+Extras:
+    hook_fit (lines/size a hook gets, flags too-long text), render_caption_image (one steady
+    caption state), write_blank_png, caption_style_ids, hook_style_ids, caption_style_info,
+    display_words, measure_caption_width, caption_width_limit, is_weak_word, cover_image,
+    layout_defaults / canvas_shape (preferred text positions per canvas shape), caption_extent
+    (how far a caption track reaches above and below its center line), sanitize_text /
+    text_issues (symbols the bundled fonts cannot draw, *markup* problems)
+
+Hook text may mark accent words with asterisks: "Você está *perdendo venda* assim". A word is
+never split by the markup ("*Kiwi*fy" colors the whole word), `\\*` draws a real asterisk and an
+unpaired `*` is ignored (text_issues reports it). The CTA and the disclaimer have no accent
+markup: their asterisks are removed.
+
+Characters a bundled font cannot draw (emoji, ★, ✓ ...) are never drawn as boxes: simple ones get
+a look-alike (→ becomes ›), the rest are removed, and text_issues lists them.
+
+CLI (quick checks, PT-BR messages):
+    text_render.py list
+    text_render.py hook "texto" --style ID [--accent HEX] [--bg frame.png] -o out.png
+    text_render.py caption "texto" --style ID [--active 1] [--bg frame.png] -o out.png
+    text_render.py cta "texto" [--sub "..."] [--bg frame.png] -o out.png
+    text_render.py disclaimer "texto" [--bg frame.png] -o out.png
+    text_render.py track captions.json --style ID -o DIR [--fps 30] [--duration S] [--width 1080 --height 1920]
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import math
+import os
+import re
+import sys
+import threading
+import time
+import unicodedata
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFilter
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from common import SAFE_ZONE_VERTICAL, hex_to_rgb, load_font, load_style_catalog  # noqa: E402
+
+REF_W, REF_H = 1080, 1920
+SIDE_MARGIN = 90
+DEFAULT_ACCENT = "#FFC400"
+
+# Preferred text positions and the platform-safe band per canvas shape, as fractions of the
+# canvas height. The vertical row is the validated 1080x1920 layout (SAFE_ZONE_VERTICAL). Type
+# keeps its size on a horizontal or square canvas (it scales with the short side), so scaling the
+# vertical y values down would squeeze full-size layers into each other: those shapes get their
+# own rows.
+LAYOUT_FRACTIONS: dict[str, dict[str, float]] = {
+    "vertical": {"top": SAFE_ZONE_VERTICAL["top"] / REF_H, "bottom": SAFE_ZONE_VERTICAL["bottom"] / REF_H,
+                 "hook": 430 / REF_H, "caption": SAFE_ZONE_VERTICAL["caption_center_y"] / REF_H,
+                 "cta": 1110 / REF_H, "cta_alone": 1180 / REF_H, "disclaimer": SAFE_ZONE_VERTICAL["disclaimer_y"] / REF_H},
+    "horizontal": {"top": 0.06, "bottom": 0.965, "hook": 0.2, "caption": 0.78, "cta": 0.45, "cta_alone": 0.5,
+                   "disclaimer": 0.935},
+    "square": {"top": 0.07, "bottom": 0.955, "hook": 0.2, "caption": 0.76, "cta": 0.46, "cta_alone": 0.52,
+               "disclaimer": 0.93},
+}
+
+
+def canvas_shape(canvas) -> str:
+    w, h = int(canvas[0]), int(canvas[1])
+    if h > w * 1.05:
+        return "vertical"
+    if w > h * 1.05:
+        return "horizontal"
+    return "square"
+
+
+def layout_defaults(canvas) -> dict[str, float]:
+    """Preferred centers and the safe band in pixels of `canvas`: top, bottom, hook, caption, cta
+    (with captions), cta_alone (without captions), disclaimer."""
+    h = float(canvas[1])
+    return {k: v * h for k, v in LAYOUT_FRACTIONS[canvas_shape(canvas)].items()}
+# Hash of this file: part of every cached PNG name, so a code change never reuses stale art.
+_SRC_HASH = hashlib.sha1(Path(__file__).read_bytes()).hexdigest()[:10]
+
+WHITE = (255, 255, 255, 255)
+BLACK = (0, 0, 0, 255)
+INK = (17, 17, 17, 255)
+
+# Portuguese function words that read badly at the end of a line or cue.
+WEAK_WORDS = {
+    "a", "o", "as", "os", "um", "uma", "uns", "umas", "de", "da", "do", "das", "dos", "em", "no",
+    "na", "nos", "nas", "e", "ou", "que", "pra", "para", "pro", "pros", "pras", "por", "pelo",
+    "pela", "pelos", "pelas", "com", "sem", "se", "mas", "meu", "minha", "meus", "minhas", "seu",
+    "sua", "seus", "suas", "te", "me", "lhe", "não", "nao", "é", "ao", "aos", "à", "às", "num",
+    "numa", "tipo", "cada", "esse", "essa", "este", "esta", "isso", "the",
+}
+
+
+# ============================================================== small utilities
+
+_tls = threading.local()
+
+
+def _font(key: str, size: float):
+    """Per-thread cached bundled font (FreeType faces are not shared across threads)."""
+    cache = getattr(_tls, "fonts", None)
+    if cache is None:
+        cache = _tls.fonts = {}
+    px = max(6, int(round(size)))
+    f = cache.get((key, px))
+    if f is None:
+        f = cache[(key, px)] = load_font(key, px)
+    return f
+
+
+def _cap_height(font) -> float:
+    cache = getattr(_tls, "caps", None)
+    if cache is None:
+        cache = _tls.caps = {}
+    key = (font.path, font.size, id(font))
+    v = cache.get(key)
+    if v is None:
+        _, top, _, _ = font.getbbox("H", anchor="ls")
+        v = cache[key] = float(-top)
+    return v
+
+
+def _rgba(color, alpha: int = 255) -> tuple[int, int, int, int]:
+    if isinstance(color, str):
+        r, g, b = hex_to_rgb(color)
+        return (r, g, b, alpha)
+    if len(color) == 3:
+        return (color[0], color[1], color[2], alpha)
+    return tuple(color)  # type: ignore[return-value]
+
+
+def _luminance(rgb) -> float:
+    def lin(c):
+        c = c / 255.0
+        return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
+
+    r, g, b = rgb[:3]
+    return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b)
+
+
+def _on_color(bg) -> tuple[int, int, int, int]:
+    """Readable text color on top of a solid background color."""
+    lum = _luminance(bg)
+    contrast_black = (lum + 0.05) / 0.05
+    contrast_white = 1.05 / (lum + 0.05)
+    return INK if contrast_black >= contrast_white else WHITE
+
+
+def _new(w: float, h: float) -> Image.Image:
+    return Image.new("RGBA", (max(1, int(math.ceil(w))), max(1, int(math.ceil(h)))), (0, 0, 0, 0))
+
+
+def _mul_alpha(img: Image.Image, factor: float) -> Image.Image:
+    if factor >= 0.999:
+        return img
+    out = img.copy()
+    out.putalpha(img.getchannel("A").point(lambda v: int(v * factor)))
+    return out
+
+
+def _rotate(img: Image.Image, angle: float) -> tuple[Image.Image, float, float]:
+    """Rotate around the center with premultiplied alpha (no dark fringes).
+
+    Returns (image, dx, dy): offset of the new center relative to the old one is zero, so an
+    anchor (ax, ay) maps to (ax' , ay') = rotate((ax-cx, ay-cy)) + new center.
+    """
+    if abs(angle) < 0.01:
+        return img, 0.0, 0.0
+    pm = img.convert("RGBa")
+    rot = pm.rotate(angle, resample=Image.BICUBIC, expand=True).convert("RGBA")
+    return rot, (rot.width - img.width) / 2.0, (rot.height - img.height) / 2.0
+
+
+def _rotate_point(x: float, y: float, cx: float, cy: float, angle: float) -> tuple[float, float]:
+    a = math.radians(angle)
+    dx, dy = x - cx, y - cy
+    # PIL rotates counter-clockwise for positive angles (y axis pointing down).
+    return cx + dx * math.cos(a) + dy * math.sin(a), cy - dx * math.sin(a) + dy * math.cos(a)
+
+
+def _shape(w: int, h: int, draw_fn, color, ss: int = 4) -> Image.Image:
+    """Anti-aliased filled shape: draw_fn(draw, scale) on a supersampled L mask."""
+    w, h = max(1, int(w)), max(1, int(h))
+    mask = Image.new("L", (w * ss, h * ss), 0)
+    draw_fn(ImageDraw.Draw(mask), ss)
+    mask = mask.resize((w, h), Image.LANCZOS)
+    rgba = _rgba(color)
+    solid = Image.new("RGBA", (w, h), rgba)
+    if rgba[3] < 255:
+        mask = mask.point(lambda v, a=rgba[3]: v * a // 255)
+    solid.putalpha(mask)
+    return solid
+
+
+def _rounded_box(layer: Image.Image, box, radius: float, color) -> None:
+    x0, y0, x1, y1 = box
+    ix0, iy0 = int(math.floor(x0)), int(math.floor(y0))
+    w, h = int(math.ceil(x1 - ix0)), int(math.ceil(y1 - iy0))
+    fx0, fy0 = x0 - ix0, y0 - iy0
+    r = max(0.0, min(radius, (x1 - x0) / 2, (y1 - y0) / 2))
+
+    def fn(d, s):
+        d.rounded_rectangle((fx0 * s, fy0 * s, (x1 - ix0) * s - 1, (y1 - iy0) * s - 1), radius=r * s, fill=255)
+
+    _alpha_paste(layer, _shape(w, h, fn, color), ix0, iy0)
+
+
+def _polygon(layer: Image.Image, points, color) -> None:
+    xs = [p[0] for p in points]
+    ys = [p[1] for p in points]
+    ix0, iy0 = int(math.floor(min(xs))), int(math.floor(min(ys)))
+    w, h = int(math.ceil(max(xs) - ix0)) + 1, int(math.ceil(max(ys) - iy0)) + 1
+
+    def fn(d, s):
+        d.polygon([((x - ix0) * s, (y - iy0) * s) for x, y in points], fill=255)
+
+    _alpha_paste(layer, _shape(w, h, fn, color), ix0, iy0)
+
+
+def _alpha_paste(dst: Image.Image, src: Image.Image, x: int, y: int) -> None:
+    """alpha_composite that accepts negative / overflowing positions."""
+    x0, y0 = max(0, x), max(0, y)
+    x1, y1 = min(dst.width, x + src.width), min(dst.height, y + src.height)
+    if x1 <= x0 or y1 <= y0:
+        return
+    crop = src.crop((x0 - x, y0 - y, x1 - x, y1 - y))
+    dst.alpha_composite(crop, (x0, y0))
+
+
+def _shadow_of(layer: Image.Image, blur: float, alpha: float, color=(0, 0, 0)) -> Image.Image:
+    """Soft shadow image (same size) from the alpha of `layer`."""
+    a = layer.getchannel("A")
+    if blur > 0.5:
+        a = a.filter(ImageFilter.GaussianBlur(blur))
+    if alpha < 0.999:
+        a = a.point(lambda v: int(v * alpha))
+    sh = Image.new("RGBA", layer.size, _rgba(color))
+    sh.putalpha(a)
+    return sh
+
+
+# ============================================================== geometry
+
+@dataclass(frozen=True)
+class _Geo:
+    w: int
+    h: int
+
+    @property
+    def k(self) -> float:          # type scale (1.0 on 1080 wide vertical)
+        return min(self.w, self.h) / REF_W
+
+    @property
+    def sy(self) -> float:
+        return self.h / REF_H
+
+    @property
+    def sx(self) -> float:
+        return self.w / REF_W
+
+    @property
+    def cx(self) -> float:
+        return self.w / 2.0
+
+    @property
+    def caption_max_w(self) -> float:
+        rail = SAFE_ZONE_VERTICAL["right_rail"] * self.sx
+        return min(self.w - 2 * SIDE_MARGIN * self.sx, 2 * (self.w / 2.0 - rail))
+
+    @property
+    def safe_top(self) -> float:
+        return LAYOUT_FRACTIONS[canvas_shape((self.w, self.h))]["top"] * self.h
+
+    @property
+    def safe_bottom(self) -> float:
+        return LAYOUT_FRACTIONS[canvas_shape((self.w, self.h))]["bottom"] * self.h
+
+
+# ============================================================== text helpers
+
+_TRAIL_STRIP = ",.;:…"
+_QUOTES = "\"“”«»'‘’()[]{}"
+
+
+def _clean_word(text: str, keep_punct: bool) -> str:
+    t = str(text).strip()
+    if keep_punct:
+        return t
+    t = t.strip(_QUOTES)
+    t = t.rstrip(_TRAIL_STRIP).lstrip("¿¡")
+    t = t.strip(_QUOTES)
+    if t in ("-", "–", "—"):
+        return ""
+    return t
+
+
+def _case(text: str, upper: bool) -> str:
+    return text.upper() if upper else text
+
+
+# ---------------------------------------------------------------- glyph coverage
+
+_GLYPHS: dict[tuple[str, str], bool] = {}
+_NOTDEF = ""          # private use code point: no bundled font has it, so it shows the .notdef glyph
+# look-alikes for symbols some fonts lack (first one the font has wins; nothing fits -> removed)
+_SYMBOL_FALLBACKS = {
+    "→": ("›", ">"), "←": ("‹", "<"), "➜": ("›", ">"), "№": ("Nº", "No"), "…": ("...",),
+    "“": ('"',), "”": ('"',), "„": ('"',), "‘": ("'",), "’": ("'",), "—": ("-",), "–": ("-",),
+    "•": ("·", "-"), "×": ("x",),
+}
+
+
+def _has_glyph(font_key: str, ch: str) -> bool:
+    """True when the bundled font draws `ch` (its mask and advance differ from the .notdef glyph)."""
+    key = (font_key, ch)
+    v = _GLYPHS.get(key)
+    if v is None:
+        f = _font(font_key, 48)
+        nd, m = f.getmask(_NOTDEF), f.getmask(ch)
+        v = not (m.size == nd.size and bytes(m) == bytes(nd) and abs(f.getlength(ch) - f.getlength(_NOTDEF)) < 0.01)
+        _GLYPHS[key] = v
+    return v
+
+
+def sanitize_text(text: str, font_key: str) -> tuple[str, list[str]]:
+    """Text the font can draw: look-alikes for simple symbols, unknown ones removed.
+
+    Returns (clean text, removed characters in order, no repeats). Line breaks are kept, other
+    spaces become plain spaces and invisible format characters (emoji joiners, variation
+    selectors) are dropped silently.
+    """
+    out: list[str] = []
+    removed: list[str] = []
+    for ch in unicodedata.normalize("NFC", str(text)):
+        if ch == "\n":
+            out.append(ch)
+            continue
+        if ch.isspace():
+            out.append(" ")
+            continue
+        cp = ord(ch)
+        if (unicodedata.category(ch) == "Cf" or 0xFE00 <= cp <= 0xFE0F or 0x1F3FB <= cp <= 0x1F3FF
+                or 0xE0020 <= cp <= 0xE007F):
+            continue   # invisible parts of an emoji (joiner, variation selector, skin tone, tag)
+        if _has_glyph(font_key, ch):
+            out.append(ch)
+            continue
+        alt = next((a for a in _SYMBOL_FALLBACKS.get(ch, ()) if all(_has_glyph(font_key, c) for c in a)), None)
+        if alt is not None:
+            out.append(alt)
+        elif ch not in removed:
+            removed.append(ch)
+    clean = "\n".join(re.sub(r" {2,}", " ", ln).strip() for ln in "".join(out).split("\n"))
+    return clean.strip("\n"), removed
+
+
+# ---------------------------------------------------------------- *accent* markup
+
+def _markup_chars(text: str) -> tuple[list[tuple[str, bool]], bool, list[str]]:
+    """Characters with their accent flag. `\\*` is a literal asterisk; an unpaired `*` is ignored.
+    Returns (chars, has_accent_markup, issues)."""
+    s = str(text)
+    marks = [i for i, c in enumerate(s) if c == "*" and not (i and s[i - 1] == "\\")]
+    issues = []
+    if len(marks) % 2:
+        issues.append("tem um * sem par, então o destaque foi ignorado. Use *palavra* para destacar ou \\* para um asterisco")
+        marks = marks[:-1]
+    mark_set = set(marks)
+    chars: list[tuple[str, bool]] = []
+    accent = False
+    i = 0
+    while i < len(s):
+        c = s[i]
+        if c == "\\" and i + 1 < len(s) and s[i + 1] == "*":
+            chars.append(("*", accent))
+            i += 2
+            continue
+        if i in mark_set:
+            accent = not accent
+        elif c != "*":
+            chars.append((c, accent))
+        i += 1
+    return chars, bool(marks), issues
+
+
+def strip_markup(text: str) -> tuple[str, bool]:
+    """Text without accent markers (for the CTA and the disclaimer). -> (text, had markers)."""
+    s = str(text)
+    had = bool(re.search(r"(?<!\\)\*", s))
+    return re.sub(r"(?<!\\)\*", "", s).replace("\\*", "*"), had
+
+
+def is_weak_word(word: str) -> bool:
+    """True for Portuguese function words ("de", "que", "não"...) that should not end a line."""
+    return re.sub(r"[^\wÀ-ÿ]", "", word.lower()) in WEAK_WORDS
+
+
+_is_weak = is_weak_word
+
+
+def _lerp_keys(keys: list[tuple[float, dict]], p: float) -> dict:
+    """Linear interpolation of numeric params between keyframes [(p, {..}), ...]."""
+    keys = sorted(keys, key=lambda kv: kv[0])
+    if p <= keys[0][0]:
+        return dict(keys[0][1])
+    for (p0, v0), (p1, v1) in zip(keys, keys[1:]):
+        if p0 <= p <= p1:
+            t = 0.0 if p1 == p0 else (p - p0) / (p1 - p0)
+            return {k: v0[k] + (v1.get(k, v0[k]) - v0[k]) * t for k in v0}
+    return dict(keys[-1][1])
+
+
+def _anim_frames(keys: list[tuple[float, dict]], dur: float, fps: float) -> list[dict]:
+    """Per-frame params for an entrance lasting `dur` seconds (last frame = steady state)."""
+    if not keys or dur <= 0:
+        return []
+    n = max(0, int(round(dur * fps)) - 1)
+    frames = []
+    for j in range(n):
+        vals = _lerp_keys(keys, (j + 1) / (n + 1))
+        frames.append({k: round(v, 3) for k, v in vals.items()})
+    return frames
+
+
+# ============================================================== caption styles
+
+@dataclass(frozen=True)
+class CaptionStyle:
+    id: str
+    font: str
+    size: float                 # px on the 1080-wide reference canvas
+    upper: bool
+    max_words: int
+    lines: int
+    animated: bool
+    one_word: bool = False
+    keep_punct: bool = False
+    hpad: float = 0.0           # extra horizontal room per side, ratio of size
+    gap: float = 0.3            # extra word gap, ratio of size (added to a space)
+    active_scale: float = 1.0   # the spoken word is drawn this much bigger (grows into the gaps)
+    fit_margin: float = 0.0     # extra width counted when fitting (rotation, glow), ratio of size
+    enter: tuple = ()           # ((p, {param: value}), ...) keyframes
+    enter_dur: float = 0.0
+    change: tuple = ()          # keyframes when the active word changes
+    change_dur: float = 0.0
+    draw: str = ""
+
+
+CAPTION_STYLES: dict[str, CaptionStyle] = {}
+
+
+def _reg(style: CaptionStyle) -> None:
+    CAPTION_STYLES[style.id] = style
+
+
+_reg(CaptionStyle(
+    id="impacto", font="display_condensed", size=134, upper=True, max_words=3, lines=1, animated=True,
+    hpad=0.09, gap=0.14,
+    enter=((0.0, {"scale": 0.70}), (0.34, {"scale": 0.86}), (0.67, {"scale": 1.07}), (1.0, {"scale": 1.0})),
+    enter_dur=0.10, draw="impacto"))
+
+_reg(CaptionStyle(
+    id="caixa_viva", font="sans_black", size=86, upper=True, max_words=3, lines=1, animated=True,
+    hpad=0.26, gap=0.36,
+    enter=((0.0, {"dy": 34.0, "alpha": 0.0}), (0.34, {"dy": 20.0, "alpha": 0.45}),
+           (0.67, {"dy": 6.0, "alpha": 0.9}), (1.0, {"dy": 0.0, "alpha": 1.0})),
+    enter_dur=0.10,
+    change=((0.0, {"slide": 0.0}), (0.5, {"slide": 0.62}), (1.0, {"slide": 1.0})),
+    change_dur=0.10, draw="caixa_viva"))
+
+_reg(CaptionStyle(
+    id="palavra_gigante", font="display_condensed", size=196, upper=True, max_words=1, lines=1,
+    animated=True, one_word=True, hpad=0.12, gap=0.2,
+    enter=((0.0, {"scale": 1.45}), (0.34, {"scale": 1.26}), (0.67, {"scale": 1.07}), (1.0, {"scale": 1.0})),
+    enter_dur=0.10, draw="palavra_gigante"))
+
+_reg(CaptionStyle(
+    id="pulso", font="sans_black", size=78, upper=True, max_words=3, lines=1, animated=True,
+    hpad=0.2, gap=0.42, active_scale=1.12,
+    enter=((0.0, {"dy": 40.0, "alpha": 0.0}), (0.34, {"dy": 22.0, "alpha": 0.5}),
+           (0.67, {"dy": 7.0, "alpha": 0.9}), (1.0, {"dy": 0.0, "alpha": 1.0})),
+    enter_dur=0.10, draw="pulso"))
+
+_reg(CaptionStyle(
+    id="fita", font="sans_black", size=78, upper=True, max_words=3, lines=1, animated=True,
+    hpad=0.42, gap=0.3, fit_margin=0.08,
+    enter=((0.0, {"wipe": 0.15}), (0.34, {"wipe": 0.45}), (0.67, {"wipe": 0.82}), (1.0, {"wipe": 1.0})),
+    enter_dur=0.10, draw="fita"))
+
+_reg(CaptionStyle(
+    id="legenda_limpa", font="text_bold", size=60, upper=False, max_words=8, lines=2, animated=False,
+    keep_punct=True, hpad=0.45, gap=0.0, draw="legenda_limpa"))
+
+# Papelaria: a frase vai se escrevendo palavra por palavra, com contorno escuro grosso; a palavra
+# falada acende na cor de destaque e cresce um pouco. `papelaria_papel` é a mesma coisa para fundo
+# claro (letra escura com halo branco), e `depoimento` marca a fala de outra pessoa.
+_reg(CaptionStyle(
+    id="papelaria", font="sans_black", size=88, upper=False, max_words=3, lines=1, animated=True,
+    hpad=0.18, gap=0.34, active_scale=1.08,
+    enter=((0.0, {"dy": 26.0, "alpha": 0.0}), (0.4, {"dy": 10.0, "alpha": 0.7}),
+           (1.0, {"dy": 0.0, "alpha": 1.0})),
+    enter_dur=0.09,
+    change=((0.0, {"pop": 0.0}), (0.45, {"pop": 1.0}), (1.0, {"pop": 0.0})),
+    change_dur=0.16, draw="papelaria"))
+
+_reg(CaptionStyle(
+    id="papelaria_papel", font="sans_black", size=88, upper=False, max_words=3, lines=1, animated=True,
+    hpad=0.18, gap=0.34, active_scale=1.08,
+    enter=((0.0, {"dy": 26.0, "alpha": 0.0}), (0.4, {"dy": 10.0, "alpha": 0.7}),
+           (1.0, {"dy": 0.0, "alpha": 1.0})),
+    enter_dur=0.09,
+    change=((0.0, {"pop": 0.0}), (0.45, {"pop": 1.0}), (1.0, {"pop": 0.0})),
+    change_dur=0.16, draw="papelaria_papel"))
+
+_reg(CaptionStyle(
+    id="depoimento", font="sans_black", size=82, upper=False, max_words=3, lines=1, animated=True,
+    hpad=0.18, gap=0.34, active_scale=1.06,
+    enter=((0.0, {"dy": 22.0, "alpha": 0.0}), (0.5, {"dy": 8.0, "alpha": 0.8}),
+           (1.0, {"dy": 0.0, "alpha": 1.0})),
+    enter_dur=0.09, draw="depoimento"))
+
+
+# ---------------------------------------------------------------- measuring
+
+def caption_style_ids() -> list[str]:
+    return list(CAPTION_STYLES)
+
+
+def _caption_spec(style_id: str) -> CaptionStyle:
+    spec = CAPTION_STYLES.get(style_id)
+    if spec is None:
+        raise ValueError(f"estilo de legenda '{style_id}' não existe. Opções: {', '.join(CAPTION_STYLES)}")
+    return spec
+
+
+def caption_style_info(style_id: str) -> dict:
+    s = _caption_spec(style_id)
+    return {"id": s.id, "max_words": s.max_words, "lines": s.lines, "animated": s.animated,
+            "upper": s.upper, "one_word": s.one_word, "keep_punct": s.keep_punct}
+
+
+def display_words(words: list[str], style_id: str) -> list[str]:
+    """Words as a style shows them (casing + punctuation cleanup). Empty words are dropped."""
+    s = _caption_spec(style_id)
+    out = []
+    for w in words:
+        t = _display_word(w, s)
+        if t:
+            out.append(t)
+    return _trim_cue_end(out, s)
+
+
+def _display_word(word: str, spec: CaptionStyle) -> str:
+    t = _case(_clean_word(word, spec.keep_punct), spec.upper)
+    return " ".join(sanitize_text(t, spec.font)[0].split()) if t else t
+
+
+def _trim_cue_end(words: list[str], spec: CaptionStyle) -> list[str]:
+    """Subtitle-like styles keep punctuation, but a cue should not end on a dangling comma."""
+    if spec.keep_punct and words:
+        last = words[-1].rstrip(",;:")
+        words = words[:-1] + [last] if last else words[:-1]
+    return words
+
+
+def _line_width(font, words: list[str], size: float, spec: CaptionStyle) -> float:
+    if not words:
+        return 0.0
+    space = font.getlength(" ")
+    widths = [font.getlength(w) for w in words]
+    grow = (spec.active_scale - 1.0) * max(widths)
+    return (sum(widths) + (len(words) - 1) * (space + spec.gap * size) + 2 * spec.hpad * size
+            + grow + 2 * spec.fit_margin * size)
+
+
+def caption_width_limit(style_id: str, canvas=(REF_W, REF_H)) -> float:
+    return _Geo(*canvas).caption_max_w
+
+
+def measure_caption_width(words: list[str], style_id: str, canvas=(REF_W, REF_H),
+                          font_scale: float = 1.0, already_display: bool = False) -> float:
+    """Single-line width in px of `words` at the style's base size (before any shrink-to-fit)."""
+    spec = _caption_spec(style_id)
+    geo = _Geo(*canvas)
+    disp = words if already_display else display_words(words, style_id)
+    size = spec.size * geo.k * font_scale
+    return _line_width(_font(spec.font, size), disp, size, spec)
+
+
+def _fit_size(spec: CaptionStyle, lines: list[list[str]], base: float, max_w: float) -> float:
+    size = base
+    for _ in range(3):
+        f = _font(spec.font, size)
+        widest = max(_line_width(f, ln, size, spec) for ln in lines)
+        if widest <= max_w:
+            break
+        size = max(8.0, math.floor(size * max_w / widest * 0.995))
+    return size
+
+
+def _balanced_split(words: list[str], width_fn) -> list[list[str]]:
+    if len(words) < 2:
+        return [words]
+    best, best_cost = None, None
+    for s in range(1, len(words)):
+        a, b = words[:s], words[s:]
+        wa, wb = width_fn(a), width_fn(b)
+        cost = max(wa, wb)
+        if _is_weak(a[-1]):
+            cost *= 1.12
+        if wa > wb:
+            cost *= 1.01
+        if best_cost is None or cost < best_cost:
+            best, best_cost = [a, b], cost
+    return best  # type: ignore[return-value]
+
+
+# ---------------------------------------------------------------- block drawing
+
+@dataclass
+class _Block:
+    layer: Image.Image
+    ax: float          # anchor inside the layer that goes to (cx, cy)
+    ay: float
+    half_h: float      # nominal half height (for safe-zone clamping)
+    half_w: float = 0.0  # nominal half width of the ink (for scale clamping)
+
+
+def _text_layer_1line(font, words, xs, size, cap_h, pad, colors, stroke, stroke_fill, total_w):
+    above = 0.36 * size
+    below = 0.34 * size
+    w = total_w + 2 * pad
+    h = cap_h + above + below + 2 * pad
+    layer = _new(w, h)
+    base_y = pad + above + cap_h
+    d = ImageDraw.Draw(layer)
+    for x, word, col in zip(xs, words, colors):
+        d.text((pad + x, base_y), word, font=font, fill=col, anchor="ls",
+               stroke_width=stroke, stroke_fill=stroke_fill)
+    return layer, base_y
+
+
+def _word_xs(font, words, size, spec):
+    space = font.getlength(" ") + spec.gap * size
+    xs, x = [], spec.hpad * size
+    widths = []
+    for w in words:
+        xs.append(x)
+        wl = font.getlength(w)
+        widths.append(wl)
+        x += wl + space
+    total = x - space + spec.hpad * size
+    return xs, widths, total
+
+
+def _draw_impacto(spec, geo, words, active, accent, size, variant, anim) -> _Block:
+    f = _font(spec.font, size)
+    cap_h = _cap_height(f)
+    stroke = max(2, int(round(size * 0.085)))
+    xs, widths, total = _word_xs(f, words, size, spec)
+    pad = stroke + int(size * 0.16)
+    colors = [_rgba(accent) if i == active else WHITE for i in range(len(words))]
+    layer, base_y = _text_layer_1line(f, words, xs, size, cap_h, pad, colors, stroke, BLACK, total)
+    sh = _shadow_of(layer, blur=size * 0.07, alpha=0.55)
+    out = _new(layer.width, layer.height)
+    _alpha_paste(out, sh, 0, int(size * 0.05))
+    out.alpha_composite(layer)
+    return _Block(out, pad + total / 2.0, base_y - cap_h / 2.0, cap_h / 2.0 + stroke + size * 0.12, total / 2.0 + stroke)
+
+
+def _draw_caixa_viva(spec, geo, words, active, accent, size, variant, anim) -> _Block:
+    f = _font(spec.font, size)
+    cap_h = _cap_height(f)
+    stroke = max(2, int(round(size * 0.075)))
+    xs, widths, total = _word_xs(f, words, size, spec)
+    pad = stroke + int(size * 0.2)
+    above, below = 0.36 * size, 0.34 * size
+    layer = _new(total + 2 * pad, cap_h + above + below + 2 * pad)
+    base_y = pad + above + cap_h
+    acc = _rgba(accent)
+    padx, pad_top, pad_bot = 0.2 * size, 0.3 * size, 0.24 * size
+
+    def box_for(i):
+        return (pad + xs[i] - padx, base_y - cap_h - pad_top, pad + xs[i] + widths[i] + padx, base_y + pad_bot)
+
+    slide = anim.get("slide", 1.0)
+    prev = variant.get("prev", -1)
+    settled = slide >= 0.999 or prev < 0
+    # text ink (white + stroke) for non-active words, shadow from it
+    ink = _new(layer.width, layer.height)
+    d = ImageDraw.Draw(ink)
+    for i, word in enumerate(words):
+        if i == active and settled:
+            continue
+        d.text((pad + xs[i], base_y), word, font=f, fill=WHITE, anchor="ls", stroke_width=stroke, stroke_fill=BLACK)
+    box_layer = _new(layer.width, layer.height)
+    if 0 <= active < len(words):
+        b1 = box_for(active)
+        if not settled and 0 <= prev < len(words):
+            b0 = box_for(prev)
+            t = slide
+            b1 = tuple(b0[j] + (b1[j] - b0[j]) * t for j in range(4))
+        _rounded_box(box_layer, b1, radius=size * 0.16, color=acc)
+    shadow_src = _new(layer.width, layer.height)
+    shadow_src.alpha_composite(box_layer)
+    shadow_src.alpha_composite(ink)
+    sh = _shadow_of(shadow_src, blur=size * 0.09, alpha=0.5)
+    _alpha_paste(layer, sh, 0, int(size * 0.06))
+    layer.alpha_composite(box_layer)
+    layer.alpha_composite(ink)
+    if 0 <= active < len(words) and settled:
+        ImageDraw.Draw(layer).text((pad + xs[active], base_y), words[active], font=f, fill=_on_color(acc), anchor="ls")
+    return _Block(layer, pad + total / 2.0, base_y - cap_h / 2.0, cap_h / 2.0 + pad_top + size * 0.05)
+
+
+def _draw_palavra_gigante(spec, geo, words, active, accent, size, variant, anim) -> _Block:
+    f = _font(spec.font, size)
+    cap_h = _cap_height(f)
+    stroke = max(2, int(round(size * 0.07)))
+    xs, widths, total = _word_xs(f, words, size, spec)
+    off = max(3, int(round(size * 0.055)))
+    pad = stroke + off + int(size * 0.14)
+    above, below = 0.36 * size, 0.34 * size
+    layer = _new(total + 2 * pad, cap_h + above + below + 2 * pad)
+    base_y = pad + above + cap_h
+    acc = _rgba(accent)
+    d = ImageDraw.Draw(layer)
+    for x, word in zip(xs, words):
+        # hard offset "sticker" shadow in the accent color, then the white word on top
+        for step in range(off, 0, -max(1, off // 4)):
+            d.text((pad + x + step, base_y + step), word, font=f, fill=acc, anchor="ls",
+                   stroke_width=stroke, stroke_fill=BLACK if step == off else acc)
+        d.text((pad + x, base_y), word, font=f, fill=WHITE, anchor="ls", stroke_width=stroke, stroke_fill=BLACK)
+    sh = _shadow_of(layer, blur=size * 0.08, alpha=0.45)
+    out = _new(layer.width, layer.height)
+    _alpha_paste(out, sh, 0, int(size * 0.04))
+    out.alpha_composite(layer)
+    return _Block(out, pad + total / 2.0, base_y - cap_h / 2.0, cap_h / 2.0 + stroke + off + size * 0.1,
+                  total / 2.0 + stroke + off)
+
+
+def _draw_pulso(spec, geo, words, active, accent, size, variant, anim) -> _Block:
+    f = _font(spec.font, size)
+    big = _font(spec.font, size * spec.active_scale)
+    cap_h, cap_big = _cap_height(f), _cap_height(big)
+    stroke = max(2, int(round(size * 0.075)))
+    stroke_big = max(2, int(round(size * spec.active_scale * 0.075)))
+    xs, widths, total = _word_xs(f, words, size, spec)
+    pad = stroke_big + int(size * 0.3)
+    above, below = 0.36 * size * spec.active_scale, 0.34 * size * spec.active_scale
+    layer = _new(total + 2 * pad, cap_big + above + below + 2 * pad)
+    center_y = pad + above + cap_big / 2.0
+    acc = _rgba(accent)
+    d = ImageDraw.Draw(layer)
+    for i, (word, x, wl) in enumerate(zip(words, xs, widths)):
+        if i == active:
+            continue
+        d.text((pad + x, center_y + cap_h / 2.0), word, font=f, fill=WHITE, anchor="ls",
+               stroke_width=stroke, stroke_fill=BLACK)
+    if 0 <= active < len(words):
+        # the spoken word grows around its own center and may eat into the word gaps
+        wl_big = big.getlength(words[active])
+        cx_word = pad + xs[active] + widths[active] / 2.0
+        d.text((cx_word - wl_big / 2.0, center_y + cap_big / 2.0), words[active], font=big, fill=acc, anchor="ls",
+               stroke_width=stroke_big, stroke_fill=BLACK)
+    out = _new(layer.width, layer.height)
+    _alpha_paste(out, _shadow_of(layer, blur=size * 0.1, alpha=0.8), 0, int(size * 0.07))
+    out.alpha_composite(layer)
+    return _Block(out, pad + total / 2.0, center_y, cap_big / 2.0 + stroke_big + size * 0.14)
+
+
+def _papelaria_block(spec, geo, words, active, accent, size, variant, anim, *,
+                     base_color, halo, futuro_alpha: float, ativa_color=None) -> _Block:
+    """Frase que se escreve palavra por palavra: o que ainda não foi falado fica de fora."""
+    f = _font(spec.font, size)
+    pop = float(anim.get("pop", 0.0) or 0.0)
+    escala = spec.active_scale + 0.05 * pop
+    big = _font(spec.font, size * escala)
+    cap_h, cap_big = _cap_height(f), _cap_height(big)
+    stroke = max(2, int(round(size * 0.085)))
+    stroke_big = max(2, int(round(size * escala * 0.085)))
+    xs, widths, total = _word_xs(f, words, size, spec)
+    pad = stroke_big + int(size * 0.3)
+    above, below = 0.36 * size * escala, 0.34 * size * escala
+    layer = _new(total + 2 * pad, cap_big + above + below + 2 * pad)
+    center_y = pad + above + cap_big / 2.0
+    acc = _rgba(ativa_color or accent)
+    d = ImageDraw.Draw(layer)
+    for i, (word, x, wl) in enumerate(zip(words, xs, widths)):
+        if i == active:
+            continue
+        if i > active >= 0 and futuro_alpha <= 0.0:
+            continue                      # ainda não foi falada: não aparece
+        cor = base_color if i < active or active < 0 else _fade(base_color, futuro_alpha)
+        d.text((pad + x, center_y + cap_h / 2.0), word, font=f, fill=cor, anchor="ls",
+               stroke_width=stroke, stroke_fill=halo)
+    if 0 <= active < len(words):
+        wl_big = big.getlength(words[active])
+        cx_word = pad + xs[active] + widths[active] / 2.0
+        d.text((cx_word - wl_big / 2.0, center_y + cap_big / 2.0), words[active], font=big, fill=acc,
+               anchor="ls", stroke_width=stroke_big, stroke_fill=halo)
+    out = _new(layer.width, layer.height)
+    _alpha_paste(out, _shadow_of(layer, blur=size * 0.09, alpha=0.75 if halo == BLACK else 0.35),
+                 0, int(size * 0.06))
+    out.alpha_composite(layer)
+    return _Block(out, pad + total / 2.0, center_y, cap_big / 2.0 + stroke_big + size * 0.14,
+                  total / 2.0 + stroke_big)
+
+
+def _fade(color, alpha: float):
+    r, g, b, a = _rgba(color)
+    return (r, g, b, int(round(a * max(0.0, min(1.0, alpha)))))
+
+
+def _draw_papelaria(spec, geo, words, active, accent, size, variant, anim) -> _Block:
+    return _papelaria_block(spec, geo, words, active, accent, size, variant, anim,
+                            base_color=WHITE, halo=BLACK, futuro_alpha=0.0)
+
+
+def _draw_papelaria_papel(spec, geo, words, active, accent, size, variant, anim) -> _Block:
+    return _papelaria_block(spec, geo, words, active, accent, size, variant, anim,
+                            base_color=(53, 44, 64, 255), halo=(255, 253, 253, 255), futuro_alpha=0.0)
+
+
+def _draw_depoimento(spec, geo, words, active, accent, size, variant, anim) -> _Block:
+    # a fala de outra pessoa: o corpo da frase fica na cor de destaque e a palavra falada, branca
+    return _papelaria_block(spec, geo, words, active, accent, size, variant, anim,
+                            base_color=_rgba(accent), halo=BLACK, futuro_alpha=0.0, ativa_color="#FFFFFF")
+
+
+def _draw_fita(spec, geo, words, active, accent, size, variant, anim) -> _Block:
+    f = _font(spec.font, size)
+    cap_h = _cap_height(f)
+    xs, widths, total = _word_xs(f, words, size, spec)
+    pad_top, pad_bot = 0.42 * size, 0.36 * size
+    tape_h = cap_h + pad_top + pad_bot
+    margin = int(size * 0.3)
+    layer = _new(total + 2 * margin, tape_h + 2 * margin)
+    x0, y0 = margin, margin
+    base_y = y0 + pad_top + cap_h
+    acc = _rgba(accent)
+    wipe = anim.get("wipe", 1.0)
+    tape = _new(layer.width, layer.height)
+    _rounded_box(tape, (x0, y0, x0 + total, y0 + tape_h), radius=size * 0.1, color=(12, 12, 12, 242))
+    d = ImageDraw.Draw(tape)
+    for i, (x, word) in enumerate(zip(xs, words)):
+        d.text((x0 + x, base_y), word, font=f, fill=acc if i == active else WHITE, anchor="ls")
+    # accent edge on the left, clipped to the tape shape
+    edge = Image.new("RGBA", tape.size, acc)
+    edge_a = tape.getchannel("A").point(lambda v: 255 if v > 0 else 0)
+    ImageDraw.Draw(edge_a).rectangle((int(x0 + size * 0.16), 0, tape.width, tape.height), fill=0)
+    edge.putalpha(Image.composite(tape.getchannel("A"), Image.new("L", tape.size, 0), edge_a))
+    tape.alpha_composite(edge)
+    if wipe < 0.999:
+        cut = int(x0 + total * max(0.0, wipe))
+        a = tape.getchannel("A")
+        ImageDraw.Draw(a).rectangle((cut, 0, tape.width, tape.height), fill=0)
+        tape.putalpha(a)
+    sh = _shadow_of(tape, blur=size * 0.14, alpha=0.45)
+    _alpha_paste(layer, sh, 0, int(size * 0.08))
+    layer.alpha_composite(tape)
+    ax, ay = x0 + total / 2.0, y0 + tape_h / 2.0
+    angle = variant.get("angle", 0.0)
+    rot, dx, dy = _rotate(layer, angle)
+    cx, cy = layer.width / 2.0, layer.height / 2.0
+    rax, ray = _rotate_point(ax, ay, cx, cy, angle)
+    return _Block(rot, rax + dx, ray + dy, tape_h / 2.0 + abs(math.sin(math.radians(angle))) * total / 2.0)
+
+
+def _draw_legenda_limpa(spec, geo, lines, active, accent, size, variant, anim) -> _Block:
+    f = _font(spec.font, size)
+    asc, desc = f.getmetrics()
+    pitch = size * 1.22
+    widths = [f.getlength(" ".join(ln)) for ln in lines]
+    padx, pady = spec.hpad * size, 0.3 * size
+    box_w = max(widths) + 2 * padx
+    box_h = pitch * (len(lines) - 1) + asc + desc + 2 * pady - 0.12 * size
+    margin = int(size * 0.3)
+    layer = _new(box_w + 2 * margin, box_h + 2 * margin)
+    bx0, by0 = margin, margin
+    _rounded_box(layer, (bx0, by0, bx0 + box_w, by0 + box_h), radius=size * 0.32, color=(0, 0, 0, 160))
+    d = ImageDraw.Draw(layer)
+    for i, (ln, wl) in enumerate(zip(lines, widths)):
+        y = by0 + pady + asc - 0.06 * size + pitch * i
+        d.text((bx0 + (box_w - wl) / 2.0, y), " ".join(ln), font=f, fill=WHITE, anchor="ls")
+    return _Block(layer, bx0 + box_w / 2.0, by0 + box_h / 2.0, box_h / 2.0)
+
+
+_DRAWERS = {
+    "impacto": _draw_impacto,
+    "caixa_viva": _draw_caixa_viva,
+    "palavra_gigante": _draw_palavra_gigante,
+    "pulso": _draw_pulso,
+    "fita": _draw_fita,
+    "legenda_limpa": _draw_legenda_limpa,
+    "papelaria": _draw_papelaria,
+    "papelaria_papel": _draw_papelaria_papel,
+    "depoimento": _draw_depoimento,
+}
+
+
+def _caption_block(spec: CaptionStyle, geo: _Geo, words: tuple, active: int, accent: str,
+                   font_scale: float, variant: dict, anim: dict) -> _Block:
+    base = spec.size * geo.k * font_scale
+    max_w = geo.caption_max_w
+    wl = list(words)
+    if spec.lines >= 2:
+        f0 = _font(spec.font, base)
+        if _line_width(f0, wl, base, spec) <= max_w:
+            lines = [wl]
+        else:
+            lines = _balanced_split(wl, lambda ws: _line_width(f0, ws, base, spec))
+        size = _fit_size(spec, lines, base, max_w)
+        return _DRAWERS[spec.draw](spec, geo, lines, active, accent, size, variant, anim)
+    size = _fit_size(spec, [wl], base, max_w)
+    return _DRAWERS[spec.draw](spec, geo, wl, active, accent, size, variant, anim)
+
+
+def _place(canvas, block: _Block, cx: float, cy: float, anim: dict, geo: _Geo, clamp=True) -> Image.Image:
+    img = Image.new("RGBA", canvas, (0, 0, 0, 0))
+    if clamp:
+        lo = geo.safe_top + block.half_h
+        hi = min(geo.h, geo.safe_bottom) - block.half_h
+        if hi >= lo:
+            cy = min(max(cy, lo), hi)
+    layer, ax, ay = block.layer, block.ax, block.ay
+    s = anim.get("scale", 1.0)
+    if s > 1.0 and block.half_w > 0:
+        # a scaled-up entrance frame must stay inside the caption safe width (right rail too)
+        room = geo.caption_max_w / 2.0
+        s = max(1.0, min(s, room / block.half_w))
+    if abs(s - 1.0) > 1e-3:
+        nw, nh = max(1, int(round(layer.width * s))), max(1, int(round(layer.height * s)))
+        layer = layer.resize((nw, nh), Image.BICUBIC)
+        ax, ay = ax * nw / block.layer.width, ay * nh / block.layer.height
+    a = anim.get("alpha", 1.0)
+    if a < 0.999:
+        layer = _mul_alpha(layer, max(0.0, a))
+    dy = anim.get("dy", 0.0) * geo.k
+    _alpha_paste(img, layer, int(round(cx - ax)), int(round(cy - ay + dy)))
+    return img
+
+
+# ---------------------------------------------------------------- caption track
+
+def _cue_words(cue: dict) -> list[dict]:
+    ws = cue.get("words") or []
+    if ws:
+        return [{"text": str(w.get("text", "")), "start": float(w["start"]), "end": float(w["end"])} for w in ws]
+    toks = str(cue.get("text", "")).split()
+    if not toks:
+        return []
+    s, e = float(cue["start"]), float(cue["end"])
+    total = sum(len(t) for t in toks) or 1
+    out, t = [], s
+    for tok in toks:
+        d = (e - s) * len(tok) / total
+        out.append({"text": tok, "start": t, "end": t + d})
+        t += d
+    return out
+
+
+HOLD_GAP = 0.6     # a cue stays up until the next one when the silence between them is shorter
+TAIL_HOLD = 0.3    # otherwise it lingers this long after the last word
+INK_ALPHA = 48          # alpha above this counts as drawn when measuring boxes (soft shadow edges do not)
+INK_LUT = [255 if v > INK_ALPHA else 0 for v in range(256)]
+ONE_WORD_MIN_S = 0.16   # one-word styles: shortest time a word state stays on screen (5 frames at 30 fps)
+ONE_WORD_MAX_MERGE = 3  # at most this many words share one state when they are spoken too fast
+
+
+def _track_states(cues: list[dict], spec: CaptionStyle, fps: float, boundaries: list[float]) -> list[tuple]:
+    """Frame-level states: (f0, f1, words_tuple, active, variant_items, anim_items)."""
+    def fr(t: float) -> int:
+        return int(round(t * fps + 1e-6))
+
+    prepared = []
+    for cue in cues:
+        raw = _cue_words(cue)
+        words = []
+        for w in raw:
+            disp = _display_word(w["text"], spec)
+            if not disp:
+                if words:
+                    words[-1]["end"] = max(words[-1]["end"], w["end"])
+                continue
+            words.append({"text": disp, "start": w["start"], "end": max(w["end"], w["start"])})
+        if not words:
+            continue
+        start = float(cue.get("start", words[0]["start"]))
+        end = float(cue.get("end", words[-1]["end"]))
+        prepared.append({"start": min(start, words[0]["start"]), "end": max(end, words[-1]["end"]), "words": words})
+    prepared.sort(key=lambda c: c["start"])
+
+    states: list[tuple] = []
+    enter = _anim_frames(list(spec.enter), spec.enter_dur, fps)
+    change = _anim_frames(list(spec.change), spec.change_dur, fps)
+    for ci, cue in enumerate(prepared):
+        nxt = prepared[ci + 1]["start"] if ci + 1 < len(prepared) else None
+        disp_end = cue["end"] + TAIL_HOLD
+        if nxt is not None:
+            if nxt - cue["end"] <= HOLD_GAP:
+                disp_end = nxt
+            disp_end = min(disp_end, nxt)
+        for b in boundaries:
+            if cue["end"] - 1e-3 <= b < disp_end:
+                disp_end = max(cue["end"], b)
+                break
+        cs, ce = fr(cue["start"]), fr(disp_end)
+        if nxt is not None:
+            ce = min(ce, fr(nxt))
+        if ce <= cs:
+            continue
+        words = cue["words"]
+        variant: dict = {}
+        if spec.draw == "fita":
+            variant["angle"] = -2.6 if ci % 2 == 0 else 1.8
+
+        def emit(f0, f1, wt, act, var, entry_frames, entry_start):
+            """Split [f0, f1) into animated entrance frames + one steady state."""
+            if f1 <= f0:
+                return
+            g = f0
+            while g < f1 and entry_frames and g - entry_start < len(entry_frames):
+                j = g - entry_start
+                if j >= 0:
+                    states.append((g, g + 1, wt, act, tuple(sorted(var.items())), tuple(sorted(entry_frames[j].items()))))
+                g += 1
+            if g < f1:
+                states.append((g, f1, wt, act, tuple(sorted(var.items())), ()))
+
+        if not spec.animated:
+            wt = tuple(_trim_cue_end([w["text"] for w in words], spec))
+            emit(cs, ce, wt, -1, variant, [], cs)
+            continue
+
+        starts = [cs] + [min(max(fr(w["start"]), cs), ce) for w in words[1:]]
+        starts = [max(starts[i], starts[i - 1]) if i else starts[i] for i in range(len(starts))]
+        if spec.one_word:
+            # a word shorter than ONE_WORD_MIN_S flickers (1-3 frames, never seen at full size):
+            # it shares the screen with the next word (or the one before, at the end of a cue)
+            min_frames = max(3, int(round(ONE_WORD_MIN_S * fps)))
+            groups: list[list] = []
+            for i, w in enumerate(words):
+                f0, f1 = starts[i], (starts[i + 1] if i + 1 < len(words) else ce)
+                if groups and groups[-1][1] - groups[-1][0] < min_frames and len(groups[-1][2]) < ONE_WORD_MAX_MERGE:
+                    groups[-1][1] = max(groups[-1][1], f1)
+                    groups[-1][2].append(w["text"])
+                else:
+                    groups.append([f0, f1, [w["text"]]])
+            if (len(groups) >= 2 and groups[-1][1] - groups[-1][0] < min_frames
+                    and len(groups[-2][2]) + len(groups[-1][2]) <= ONE_WORD_MAX_MERGE):
+                last = groups.pop()
+                groups[-1][1] = last[1]
+                groups[-1][2].extend(last[2])
+            for f0, f1, texts in groups:
+                if f1 <= f0:
+                    continue
+                # no entrance bounce on a state too short to settle at its final size
+                entry = enter if f1 - f0 >= len(enter) + 3 else []
+                emit(f0, f1, tuple(texts), 0, variant, entry, f0)
+            continue
+        for i, w in enumerate(words):
+            f0 = starts[i]
+            f1 = starts[i + 1] if i + 1 < len(words) else ce
+            if f1 <= f0:
+                continue
+            wt = tuple(x["text"] for x in words)
+            if f0 < cs + len(enter):
+                # cue entrance frames (take priority over the word-change slide)
+                head_end = min(f1, cs + len(enter))
+                emit(f0, head_end, wt, i, variant, enter, cs)
+                f0 = head_end
+                if f0 >= f1:
+                    continue
+                emit(f0, f1, wt, i, variant, [], f0)
+            elif change and i > 0:
+                var = dict(variant, prev=i - 1)
+                g = f0
+                for j, params in enumerate(change):
+                    if g >= f1:
+                        break
+                    states.append((g, g + 1, wt, i, tuple(sorted(var.items())), tuple(sorted(params.items()))))
+                    g += 1
+                if g < f1:
+                    states.append((g, f1, wt, i, tuple(sorted(variant.items())), ()))
+            else:
+                emit(f0, f1, wt, i, variant, [], f0)
+    states.sort(key=lambda s: s[0])
+    # safety: never overlap
+    clean: list[tuple] = []
+    for st in states:
+        if clean and st[0] < clean[-1][1]:
+            st = (clean[-1][1],) + st[1:]
+        if st[1] > st[0]:
+            clean.append(st)
+    return clean
+
+
+def _apply_windows(states: list[tuple], fps: float, default_cy: float,
+                   layout: list[dict] | None, hide: list[list[float]] | None) -> list[tuple]:
+    """-> (f0, f1, words, active, variant, anim, center_y) with hide windows removed."""
+    def fr(t: float) -> int:
+        return int(round(float(t) * fps + 1e-6))
+
+    lay = sorted(((fr(w["start"]), fr(w["end"]), float(w["center_y"])) for w in (layout or [])), key=lambda x: x[0])
+    hid = sorted((fr(a), fr(b)) for a, b in (hide or []))
+    cuts = sorted({p for a, b, _ in lay for p in (a, b)} | {p for a, b in hid for p in (a, b)})
+    out = []
+    for f0, f1, *rest in states:
+        pts = [f0] + [c for c in cuts if f0 < c < f1] + [f1]
+        for a, b in zip(pts, pts[1:]):
+            if any(h0 <= a and b <= h1 for h0, h1 in hid):
+                continue
+            cy = default_cy
+            for l0, l1, lcy in lay:
+                if l0 <= a and b <= l1:
+                    cy = lcy
+            out.append((a, b, *rest, cy))
+    return out
+
+
+def render_caption_track(cues: dict, style_id: str, accent: str, out_dir: str,
+                         canvas=(1080, 1920), fps: int = 30,
+                         layout: list[dict] | None = None, hide: list[list[float]] | None = None,
+                         font_scale: float = 1.0) -> list[dict]:
+    """Render every distinct visual state of a caption track to PNGs.
+
+    Returns [{"file": "/abs/png", "start": s, "end": e, "bbox": [x0, y0, x1, y1]}] sorted,
+    non-overlapping, only where a caption is visible. `bbox` is the drawn area of that PNG (alpha
+    above INK_ALPHA; null when empty). Times are on the frame grid of `fps`. Identical states share one PNG (named by a
+    content hash, so re-running with the same input reuses the files; their boxes are kept in
+    `bboxes.json` next to them). Default center: layout_defaults(canvas)["caption"].
+    """
+    spec = _caption_spec(style_id)
+    geo = _Geo(int(canvas[0]), int(canvas[1]))
+    out = Path(out_dir).resolve()
+    out.mkdir(parents=True, exist_ok=True)
+    cue_list = cues.get("cues", []) if isinstance(cues, dict) else list(cues)
+    boundaries = sorted(float(b) for b in (cues.get("cut_boundaries") or [])) if isinstance(cues, dict) else []
+    default_cy = layout_defaults((geo.w, geo.h))["caption"]
+    hex_accent = accent or DEFAULT_ACCENT
+    _rgba(hex_accent)  # validate early
+
+    states = _track_states(cue_list, spec, float(fps), boundaries)
+    placed = _apply_windows(states, float(fps), default_cy, layout, hide)
+
+    # merge consecutive identical states
+    merged: list[list] = []
+    for st in placed:
+        if merged and merged[-1][1] == st[0] and tuple(merged[-1][2:]) == tuple(st[2:]):
+            merged[-1][1] = st[1]
+        else:
+            merged.append(list(st))
+
+    jobs: dict[str, tuple] = {}
+    entries = []
+    for f0, f1, words, active, variant, anim, cy in merged:
+        key_src = repr((_SRC_HASH, style_id, hex_accent.upper(), geo.w, geo.h, round(font_scale, 4),
+                        words, active, variant, anim, round(cy, 1)))
+        name = "cap_" + hashlib.sha1(key_src.encode("utf-8")).hexdigest()[:16] + ".png"
+        path = out / name
+        jobs.setdefault(name, (path, words, active, dict(variant), dict(anim), cy))
+        entries.append({"file": str(path), "start": round(f0 / fps, 6), "end": round(f1 / fps, 6)})
+
+    bbox_path = out / "bboxes.json"
+    try:
+        known = json.loads(bbox_path.read_text(encoding="utf-8")) if bbox_path.exists() else {}
+    except (OSError, ValueError):
+        known = {}
+    boxes: dict[str, list | None] = {}
+
+    def work(job):
+        path, words, active, variant, anim, cy = job
+        if path.exists():
+            if path.name in known:
+                boxes[path.name] = known[path.name]
+                return
+            with Image.open(path) as im:
+                bb = ink_bbox(im)
+            boxes[path.name] = list(bb) if bb else None
+            return
+        block = _caption_block(spec, geo, words, active, hex_accent, font_scale, variant, anim)
+        img = _place((geo.w, geo.h), block, geo.cx, cy, anim, geo)
+        bb = ink_bbox(img)
+        boxes[path.name] = list(bb) if bb else None
+        tmp = path.with_name(".tmp-" + path.name)
+        img.save(tmp, "PNG", compress_level=3)
+        os.replace(tmp, path)
+
+    workers = max(1, min(8, (os.cpu_count() or 4)))
+    with ThreadPoolExecutor(max_workers=workers) as ex:
+        list(ex.map(work, jobs.values()))
+    if any(known.get(n, 0) != b for n, b in boxes.items()):
+        known.update(boxes)
+        tmp = bbox_path.with_name(".tmp-" + bbox_path.name)
+        tmp.write_text(json.dumps(known), encoding="utf-8")
+        os.replace(tmp, bbox_path)
+    for e in entries:
+        e["bbox"] = boxes.get(Path(e["file"]).name)
+    return entries
+
+
+def ink_bbox(img: Image.Image) -> tuple[int, int, int, int] | None:
+    """Box of what is really drawn: alpha above INK_ALPHA (the faint edge of soft shadows is left out)."""
+    return img.getchannel("A").point(INK_LUT).getbbox()
+
+
+_REACH_ABOVE = set("ÁÀÂÃÄÉÈÊËÍÌÎÏÓÒÔÕÖÚÙÛÜÑbdfhklt")
+_REACH_BELOW = set("ÇQJgjpqyç,;")
+
+
+def caption_extent(cues: dict | list, style_id: str, canvas=(1080, 1920), font_scale: float = 1.0,
+                   fps: float = 30.0) -> tuple[float, float]:
+    """(above, below): how many px a caption track reaches above and below its center line.
+
+    Measured on drawn blocks of the real cues (the widest one, plus one with accents on top and one
+    with a cedilla or descender), times the biggest entrance scale and slide of the style, so a
+    track can be placed before it is rendered. Empty cues: a sample phrase with accents.
+    """
+    spec = _caption_spec(style_id)
+    geo = _Geo(int(canvas[0]), int(canvas[1]))
+    cue_list = cues.get("cues", []) if isinstance(cues, dict) else list(cues or [])
+    groups: list[list[str]] = []
+    for cue in cue_list:
+        words = display_words([w["text"] for w in _cue_words(cue)], style_id)
+        groups += [[w] for w in words] if spec.one_word else ([words] if words else [])
+    if not groups:
+        groups = [display_words(["ÉÇ", "SÓ"], style_id)]
+    picks: dict[tuple, list[str]] = {}
+    widest, best = groups[0], -1.0
+    for g in groups:
+        chars = set("".join(g))
+        sig = (bool(chars & _REACH_ABOVE), bool(chars & _REACH_BELOW))
+        picks.setdefault(sig, g)
+        width = measure_caption_width(g, style_id, canvas, font_scale, already_display=True)
+        if width > best:
+            best, widest = width, g
+    picks[("widest",)] = widest
+    variant = {"angle": -2.6} if spec.draw == "fita" else {}
+    above = below = 0.0
+    for words in picks.values():
+        block = _caption_block(spec, geo, tuple(words), 0, DEFAULT_ACCENT, font_scale, variant, {})
+        bb = ink_bbox(block.layer) or (0, 0, block.layer.width, block.layer.height)
+        above, below = max(above, block.ay - bb[1]), max(below, bb[3] - block.ay)
+    frames = _anim_frames(list(spec.enter), spec.enter_dur, fps)
+    scale = max([1.0] + [float(f.get("scale", 1.0)) for f in frames])
+    slide = max([0.0] + [float(f.get("dy", 0.0)) for f in frames if f.get("alpha", 1.0) >= 0.5]) * geo.k
+    return above * scale, below * scale + slide
+
+
+def write_blank_png(path: str | Path, canvas=(1080, 1920)) -> Path:
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    Image.new("RGBA", (int(canvas[0]), int(canvas[1])), (0, 0, 0, 0)).save(p, "PNG")
+    return p
+
+
+def write_ffconcat(states: list[dict], path: str, total_duration: float, blank_png: str,
+                   fps: float | None = None) -> Path:
+    """Write an ffconcat playlist that plays the caption states over [0, total_duration].
+
+    Gaps use `blank_png` (created, fully transparent, when it does not exist yet, with the
+    size of the first state PNG). The last entry is repeated without duration, as the concat
+    demuxer requires. Each entry carries `option framerate` so timestamps are not rounded to
+    the image demuxer's default 1/25 time base: pass the output fps when known (exact frame
+    grid); otherwise a 1 microsecond time base is used. Durations are derived from
+    microsecond-floored cumulative positions, so rounding never drifts.
+
+    Use in ffmpeg (frame-accurate, verified):
+        ffmpeg -i base.mp4 -f concat -safe 0 -i captions.ffconcat \\
+          -filter_complex "[1:v]format=rgba[cap];[0:v][cap]overlay=0:0:eof_action=pass[v]" \\
+          -map "[v]" -map 0:a? ...
+    """
+    p = Path(path).resolve()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    blank = Path(blank_png).resolve()
+    if not blank.exists():
+        size = (REF_W, REF_H)
+        if states:
+            with Image.open(states[0]["file"]) as im:
+                size = im.size
+        write_blank_png(blank, size)
+    total = max(0.0, float(total_duration))
+    rate = f"{int(fps)}" if fps and float(fps).is_integer() else (f"{fps}" if fps else "1000000")
+
+    def us(t: float) -> int:
+        return int(math.floor(float(t) * 1_000_000 + 1e-3))
+
+    items: list[tuple[str, int, int]] = []   # (file, start_us, end_us)
+    cursor = 0
+    for st in sorted(states, key=lambda s: s["start"]):
+        a, b = us(st["start"]), us(min(st["end"], total) if total else st["end"])
+        a = max(a, cursor)
+        if b <= a:
+            continue
+        if a > cursor:
+            items.append((str(blank), cursor, a))
+        items.append((str(Path(st["file"]).resolve()), a, b))
+        cursor = b
+    end_us = us(total) if total else cursor
+    if end_us > cursor:
+        items.append((str(blank), cursor, end_us))
+    if not items:
+        items.append((str(blank), 0, max(end_us, 1)))
+
+    def q(f: str) -> str:
+        return "'" + f.replace("'", "'\\''") + "'"
+
+    lines = ["ffconcat version 1.0"]
+    for f, a, b in items:
+        lines += [f"file {q(f)}", f"option framerate {rate}", f"duration {(b - a) / 1_000_000:.6f}"]
+    last = items[-1][0]
+    lines += [f"file {q(last)}", f"option framerate {rate}"]
+    p.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return p
+
+
+# ============================================================== hooks
+
+@dataclass
+class _Tok:
+    text: str
+    accent: bool
+
+
+def _parse_marked(text: str, upper: bool, font_key: str | None = None) -> tuple[list[_Tok], bool]:
+    """Words with their accent flag. A word touched by the markup is accented as a whole, so
+    "*Kiwi*fy" stays one word. With `font_key`, symbols the font cannot draw are removed."""
+    chars, marked, _ = _markup_chars(text)
+    words: list[list] = []          # [text, accent]
+    cur: list[str] = []
+    cur_acc = False
+    for c, acc in chars + [(" ", False)]:
+        if c.isspace():
+            if cur:
+                words.append(["".join(cur), cur_acc])
+            cur, cur_acc = [], False
+            continue
+        cur.append(c)
+        cur_acc = cur_acc or acc
+    toks: list[_Tok] = []
+    for w, acc in words:
+        if font_key:
+            w, _ = sanitize_text(w, font_key)
+            w = w.replace("\n", " ").strip()
+            if not w:
+                continue
+        w = _case(w, upper)
+        if toks and re.fullmatch(r"[,.;:!?…]+", w):
+            toks[-1].text += w
+        else:
+            toks.append(_Tok(w, acc))
+    return toks, marked and any(t.accent for t in toks)
+
+
+_TEXT_FONTS = {"cta": "sans_black", "cta_sub": "text_bold", "disclaimer": "text_semibold"}
+_TEXT_LABELS = {"hook": "gancho", "cta": "chamada", "cta_sub": "linha de apoio da chamada",
+                "disclaimer": "texto do aviso", "caption": "legenda"}
+
+
+def text_issues(kind: str, text: str, style_id: str | None = None) -> list[str]:
+    """PT-BR warnings for text that will not show up exactly as typed.
+
+    kind: "hook" (needs style_id), "caption" (needs style_id), "cta", "cta_sub", "disclaimer".
+    Lists symbols the font cannot draw (they are removed when rendering) and markup problems.
+    """
+    if not str(text or "").strip():
+        return []
+    label = _TEXT_LABELS.get(kind, kind)
+    if kind == "hook":
+        if style_id not in HOOK_STYLES:
+            raise ValueError(f"estilo de gancho '{style_id}' não existe. Opções: {', '.join(HOOK_STYLES)}")
+        font_key = HOOK_STYLES[style_id]["font"]
+    elif kind == "caption":
+        font_key = _caption_spec(str(style_id)).font
+    else:
+        font_key = _TEXT_FONTS[kind]
+    issues = []
+    if kind == "hook":
+        chars, _, problems = _markup_chars(text)
+        plain = "".join(c for c, _ in chars)
+        issues += [f"{label}: {p}" for p in problems]
+    elif kind in ("cta", "cta_sub", "disclaimer"):
+        plain, had = strip_markup(text)
+        if had:
+            issues.append(f"{label}: não tem destaque com *, os asteriscos foram tirados")
+    else:
+        plain = str(text)
+    probe = plain.upper() if kind == "cta" else plain
+    _, removed = sanitize_text(probe, font_key)
+    if removed:
+        issues.append(f"{label}: tirei símbolos que a fonte não desenha ({' '.join(removed)}). Evite emoji e símbolos no texto")
+    return issues
+
+
+HOOK_STYLES: dict[str, dict] = {
+    "manchete": {"font": "display_condensed", "upper": True, "max": 158, "min": 84, "side": 0.08},
+    "tarja": {"font": "sans_black", "upper": True, "max": 94, "min": 50, "side": 0.34},
+    "balao": {"font": "sans_extrabold", "upper": False, "max": 82, "min": 46, "side": 0.62},
+    "marcador": {"font": "marker", "upper": True, "max": 104, "min": 56, "side": 0.34},
+    "vidro": {"font": "sans_extrabold", "upper": False, "max": 78, "min": 44, "side": 0.66},
+}
+
+
+def hook_style_ids() -> list[str]:
+    return list(HOOK_STYLES)
+
+
+def _hook_lines(toks: list[_Tok], font_key: str, content_w: float, max_size: float, min_size: float,
+                side_ratio: float) -> tuple[list[list[_Tok]], float]:
+    """Pick 1 or 2 lines (balanced by measured width) and the fitted font size."""
+    ref = 100.0
+    f = _font(font_key, ref)
+    space = f.getlength(" ")
+
+    def width(ts):
+        return sum(f.getlength(t.text) for t in ts) + space * (len(ts) - 1)
+
+    def size_for(lines):
+        widest = max(width(ln) for ln in lines)
+        per_px = widest / ref + 2 * side_ratio
+        return content_w / per_px if per_px > 0 else max_size
+
+    if not toks:
+        return [[]], max_size
+    one = [toks]
+    s1 = min(max_size, size_for(one))
+    if len(toks) == 1:
+        return one, max(min(s1, max_size), 1.0)
+    best, best_cost = None, None
+    for s in range(1, len(toks)):
+        a, b = toks[:s], toks[s:]
+        wa, wb = width(a), width(b)
+        cost = max(wa, wb)
+        if _is_weak(a[-1].text):
+            cost *= 1.1
+        if len(a) == 1 and len(toks) > 3 and len(a[0].text) <= 3:
+            cost *= 1.15
+        if best_cost is None or cost < best_cost:
+            best, best_cost = [a, b], cost
+    two = best
+    s2 = min(max_size, size_for(two))
+    if s1 >= 0.86 * s2:
+        lines, size = one, s1
+    else:
+        lines, size = two, s2
+    return lines, max(1.0, size)
+
+
+def _refit(font_key: str, lines: list[list[_Tok]], size: float, content_w: float, side_ratio: float) -> float:
+    for _ in range(4):
+        f = _font(font_key, size)
+        space = f.getlength(" ")
+        widest = max(sum(f.getlength(t.text) for t in ln) + space * (len(ln) - 1) for ln in lines)
+        if widest + 2 * side_ratio * size <= content_w:
+            return size
+        size = math.floor(size * content_w / (widest + 2 * side_ratio * size) * 0.995)
+    return size
+
+
+def _line_colors(lines, marked, accent_rgba, default_rgba, rule: str):
+    """Per token colors: marked words get the accent; otherwise a style rule."""
+    cols = []
+    for li, ln in enumerate(lines):
+        row = []
+        for ti, t in enumerate(ln):
+            if marked:
+                row.append(accent_rgba if t.accent else default_rgba)
+            elif rule == "second_line" and len(lines) == 2:
+                row.append(accent_rgba if li == 1 else default_rgba)
+            elif rule in ("second_line", "last_word") and len(lines) == 1 and len(ln) >= 2:
+                row.append(accent_rgba if ti == len(ln) - 1 else default_rgba)
+            else:
+                row.append(default_rgba)
+        cols.append(row)
+    return cols
+
+
+def _draw_token_line(d, f, x, base_y, toks, colors, stroke=0, stroke_fill=BLACK):
+    space = f.getlength(" ")
+    for t, col in zip(toks, colors):
+        d.text((x, base_y), t.text, font=f, fill=col, anchor="ls", stroke_width=stroke, stroke_fill=stroke_fill)
+        x += f.getlength(t.text) + space
+
+
+def _tok_width(f, toks) -> float:
+    return sum(f.getlength(t.text) for t in toks) + f.getlength(" ") * (len(toks) - 1)
+
+
+def _hook_manchete(toks, marked, accent, geo, max_width):
+    st = HOOK_STYLES["manchete"]
+    k = geo.k
+    side = st["side"]
+    lines, size = _hook_lines(toks, st["font"], max_width, st["max"] * k, st["min"] * k, side)
+    size = _refit(st["font"], lines, size, max_width, side)
+    f = _font(st["font"], size)
+    cap = _cap_height(f)
+    stroke = max(2, int(round(size * 0.075)))
+    pitch = cap + size * 0.38
+    widths = [_tok_width(f, ln) for ln in lines]
+    block_w = max(widths)
+    block_h = cap + pitch * (len(lines) - 1)
+    pad = int(stroke + size * 0.4)
+    layer = _new(block_w + 2 * pad, block_h + 2 * pad)
+    acc = _rgba(accent)
+    cols = _line_colors(lines, marked, acc, WHITE, "second_line")
+    d = ImageDraw.Draw(layer)
+    for i, (ln, wl) in enumerate(zip(lines, widths)):
+        base_y = pad + cap + pitch * i
+        _draw_token_line(d, f, pad + (block_w - wl) / 2.0, base_y, ln, cols[i], stroke, BLACK)
+    out = _new(layer.width, layer.height)
+    _alpha_paste(out, _shadow_of(layer, blur=size * 0.09, alpha=0.6), 0, int(size * 0.06))
+    out.alpha_composite(layer)
+    return out, pad + block_w / 2.0, pad + block_h / 2.0, block_h / 2.0 + stroke + size * 0.3
+
+
+def _hook_tarja(toks, marked, accent, geo, max_width):
+    st = HOOK_STYLES["tarja"]
+    k = geo.k
+    side = st["side"]
+    lines, size = _hook_lines(toks, st["font"], max_width, st["max"] * k, st["min"] * k, side)
+    size = _refit(st["font"], lines, size, max_width, side)
+    f = _font(st["font"], size)
+    cap = _cap_height(f)
+    padx, pad_top, pad_bot = side * size, 0.36 * size, 0.3 * size
+    box_h = cap + pad_top + pad_bot
+    gap = 0.1 * size
+    widths = [_tok_width(f, ln) for ln in lines]
+    block_w = max(widths) + 2 * padx
+    block_h = box_h * len(lines) + gap * (len(lines) - 1)
+    margin = int(size * 0.35)
+    layer = _new(block_w + 2 * margin, block_h + 2 * margin)
+    acc = _rgba(accent)
+    has_accent_line = [any(t.accent for t in ln) for ln in lines]
+    boxes = _new(layer.width, layer.height)
+    texts = []
+    for i, (ln, wl) in enumerate(zip(lines, widths)):
+        if marked:
+            bg = acc if has_accent_line[i] else WHITE
+        else:
+            bg = acc if i == len(lines) - 1 else WHITE
+        bw = wl + 2 * padx
+        x0 = margin + (block_w - bw) / 2.0
+        y0 = margin + i * (box_h + gap)
+        _rounded_box(boxes, (x0, y0, x0 + bw, y0 + box_h), radius=size * 0.14, color=bg)
+        texts.append((x0 + padx, y0 + pad_top + cap, ln, _on_color(bg)))
+    _alpha_paste(layer, _shadow_of(boxes, blur=size * 0.16, alpha=0.4), 0, int(size * 0.08))
+    layer.alpha_composite(boxes)
+    d = ImageDraw.Draw(layer)
+    for x, base_y, ln, col in texts:
+        _draw_token_line(d, f, x, base_y, ln, [col] * len(ln))
+    angle = -2.0
+    ax, ay = margin + block_w / 2.0, margin + block_h / 2.0
+    rot, dx, dy = _rotate(layer, angle)
+    rax, ray = _rotate_point(ax, ay, layer.width / 2.0, layer.height / 2.0, angle)
+    half = block_h / 2.0 + abs(math.sin(math.radians(angle))) * block_w / 2.0
+    return rot, rax + dx, ray + dy, half
+
+
+def _hook_balao(toks, marked, accent, geo, max_width):
+    st = HOOK_STYLES["balao"]
+    k = geo.k
+    side = st["side"]
+    lines, size = _hook_lines(toks, st["font"], max_width, st["max"] * k, st["min"] * k, side)
+    size = _refit(st["font"], lines, size, max_width, side)
+    f = _font(st["font"], size)
+    asc, desc = f.getmetrics()
+    cap = _cap_height(f)
+    pitch = size * 1.24
+    padx, pady = side * size, 0.5 * size
+    widths = [_tok_width(f, ln) for ln in lines]
+    card_w = max(widths) + 2 * padx
+    text_h = cap + pitch * (len(lines) - 1)
+    card_h = text_h + 2 * pady + 0.22 * size
+    tail = size * 0.42
+    margin = int(size * 0.5)
+    layer = _new(card_w + 2 * margin, card_h + tail + 2 * margin)
+    acc = _rgba(accent)
+    x0, y0 = margin, margin
+    card = _new(layer.width, layer.height)
+    # speech-bubble tail (bottom left), then the card
+    tx = x0 + card_w * 0.2
+    _polygon(card, [(tx, y0 + card_h - 2), (tx + tail * 1.25, y0 + card_h - 2), (tx - tail * 0.1, y0 + card_h + tail)], WHITE)
+    _rounded_box(card, (x0, y0, x0 + card_w, y0 + card_h), radius=size * 0.46, color=WHITE)
+    _alpha_paste(layer, _shadow_of(card, blur=size * 0.22, alpha=0.38), 0, int(size * 0.1))
+    layer.alpha_composite(card)
+    d = ImageDraw.Draw(layer)
+    top_text = y0 + pady + 0.16 * size
+    space = f.getlength(" ")
+    on_acc = _on_color(acc)
+    for i, (ln, wl) in enumerate(zip(lines, widths)):
+        base_y = top_text + cap + pitch * i
+        x = x0 + (card_w - wl) / 2.0
+        for t in ln:
+            tw = f.getlength(t.text)
+            col = INK
+            if marked and t.accent:
+                _rounded_box(layer, (x - size * 0.12, base_y - cap - size * 0.2, x + tw + size * 0.12, base_y + size * 0.2),
+                             radius=size * 0.12, color=acc)
+                d = ImageDraw.Draw(layer)
+                col = on_acc
+            d.text((x, base_y), t.text, font=f, fill=col, anchor="ls")
+            x += tw + space
+    return layer, x0 + card_w / 2.0, y0 + card_h / 2.0, card_h / 2.0 + tail
+
+
+def _hook_marcador(toks, marked, accent, geo, max_width):
+    st = HOOK_STYLES["marcador"]
+    k = geo.k
+    side = st["side"]
+    lines, size = _hook_lines(toks, st["font"], max_width, st["max"] * k, st["min"] * k, side)
+    size = _refit(st["font"], lines, size, max_width, side)
+    f = _font(st["font"], size)
+    cap = _cap_height(f)
+    pitch = cap + size * 0.46
+    widths = [_tok_width(f, ln) for ln in lines]
+    block_w = max(widths) + 2 * side * size
+    block_h = cap + pitch * (len(lines) - 1) + 0.5 * size
+    margin = int(size * 0.4)
+    layer = _new(block_w + 2 * margin, block_h + 2 * margin)
+    acc = _rgba(accent)
+    strokes = _new(layer.width, layer.height)
+    jit = [(0.03, -0.05, 0.06, 0.02), (-0.04, 0.04, -0.02, 0.05)]
+    texts = []
+    for i, (ln, wl) in enumerate(zip(lines, widths)):
+        base_y = margin + 0.25 * size + cap + pitch * i
+        sx0 = margin + (block_w - wl) / 2.0 - side * size
+        sx1 = sx0 + wl + 2 * side * size
+        top, bot = base_y - cap - 0.2 * size, base_y + 0.2 * size
+        j = jit[i % 2]
+        pts = [(sx0 + j[0] * size, top + j[1] * size), (sx1 + j[2] * size, top + j[3] * size + 0.04 * size),
+               (sx1 - 0.06 * size, bot + j[1] * size), (sx0 - 0.04 * size, bot - j[3] * size)]
+        _polygon(strokes, pts, acc)
+        texts.append((margin + (block_w - wl) / 2.0, base_y, ln))
+    _alpha_paste(layer, _shadow_of(strokes, blur=size * 0.14, alpha=0.35), 0, int(size * 0.06))
+    layer.alpha_composite(strokes)
+    d = ImageDraw.Draw(layer)
+    ink = _on_color(acc)
+    for x, base_y, ln in texts:
+        _draw_token_line(d, f, x, base_y, ln, [ink] * len(ln))
+    angle = 2.2
+    ax, ay = margin + block_w / 2.0, margin + block_h / 2.0
+    rot, dx, dy = _rotate(layer, angle)
+    rax, ray = _rotate_point(ax, ay, layer.width / 2.0, layer.height / 2.0, angle)
+    return rot, rax + dx, ray + dy, block_h / 2.0 + abs(math.sin(math.radians(angle))) * block_w / 2.0
+
+
+def _hook_vidro(toks, marked, accent, geo, max_width):
+    st = HOOK_STYLES["vidro"]
+    k = geo.k
+    side = st["side"]
+    lines, size = _hook_lines(toks, st["font"], max_width, st["max"] * k, st["min"] * k, side)
+    size = _refit(st["font"], lines, size, max_width, side)
+    f = _font(st["font"], size)
+    cap = _cap_height(f)
+    pitch = size * 1.24
+    padx, pady = side * size, 0.62 * size
+    widths = [_tok_width(f, ln) for ln in lines]
+    panel_w = max(widths) + 2 * padx
+    text_h = cap + pitch * (len(lines) - 1) + 0.22 * size
+    panel_h = text_h + 2 * pady
+    margin = int(size * 0.4)
+    layer = _new(panel_w + 2 * margin, panel_h + 2 * margin)
+    acc = _rgba(accent)
+    x0, y0 = margin, margin
+    border = max(2, int(round(size * 0.035)))
+    _rounded_box(layer, (x0, y0, x0 + panel_w, y0 + panel_h), radius=size * 0.42, color=(255, 255, 255, 58))
+    _rounded_box(layer, (x0 + border, y0 + border, x0 + panel_w - border, y0 + panel_h - border),
+                 radius=size * 0.42 - border, color=(14, 14, 16, 196))
+    bar_w, bar_h = size * 1.1, size * 0.12
+    _rounded_box(layer, (x0 + (panel_w - bar_w) / 2.0, y0 + pady * 0.42, x0 + (panel_w + bar_w) / 2.0, y0 + pady * 0.42 + bar_h),
+                 radius=bar_h / 2.0, color=acc)
+    cols = _line_colors(lines, marked, acc, WHITE, "none")
+    d = ImageDraw.Draw(layer)
+    for i, (ln, wl) in enumerate(zip(lines, widths)):
+        base_y = y0 + pady + 0.2 * size + cap + pitch * i
+        _draw_token_line(d, f, x0 + (panel_w - wl) / 2.0, base_y, ln, cols[i])
+    return layer, x0 + panel_w / 2.0, y0 + panel_h / 2.0, panel_h / 2.0
+
+
+_HOOK_DRAWERS = {
+    "manchete": _hook_manchete,
+    "tarja": _hook_tarja,
+    "balao": _hook_balao,
+    "marcador": _hook_marcador,
+    "vidro": _hook_vidro,
+}
+
+
+def hook_fit(text: str, style_id: str, canvas=(1080, 1920), max_width: int = 900) -> dict:
+    """How a hook would be laid out: {"lines": [...], "size": px, "min_size": px, "too_long": bool}.
+
+    Hooks never wrap to 3 lines, so a long text only gets smaller; `too_long` tells the agent to
+    shorten it.
+    """
+    if style_id not in HOOK_STYLES:
+        raise ValueError(f"estilo de gancho '{style_id}' não existe. Opções: {', '.join(HOOK_STYLES)}")
+    st = HOOK_STYLES[style_id]
+    geo = _Geo(int(canvas[0]), int(canvas[1]))
+    width = min(float(max_width), geo.w - 2 * SIDE_MARGIN * geo.sx)
+    toks, _ = _parse_marked(text, st["upper"], st["font"])
+    side = st["side"]
+    lines, size = _hook_lines(toks, st["font"], width, st["max"] * geo.k, st["min"] * geo.k, side)
+    size = _refit(st["font"], lines, size, width, side) if toks else size
+    return {"lines": [" ".join(t.text for t in ln) for ln in lines], "size": int(size),
+            "min_size": int(st["min"] * geo.k), "too_long": size < st["min"] * geo.k}
+
+
+def render_hook(text: str, style_id: str, accent: str, canvas=(1080, 1920), center_y: int = 430,
+                max_width: int = 900) -> Image.Image:
+    """Hook headline: always 1-2 lines, balanced by measured width, font size fitted."""
+    if style_id not in HOOK_STYLES:
+        raise ValueError(f"estilo de gancho '{style_id}' não existe. Opções: {', '.join(HOOK_STYLES)}")
+    geo = _Geo(int(canvas[0]), int(canvas[1]))
+    max_width = min(float(max_width), geo.w - 2 * SIDE_MARGIN * geo.sx)
+    toks, marked = _parse_marked(text, HOOK_STYLES[style_id]["upper"], HOOK_STYLES[style_id]["font"])
+    if not toks:
+        return Image.new("RGBA", (geo.w, geo.h), (0, 0, 0, 0))
+    layer, ax, ay, half = _HOOK_DRAWERS[style_id](toks, marked, accent or DEFAULT_ACCENT, geo, max_width)
+    return _place((geo.w, geo.h), _Block(layer, ax, ay, half), geo.cx, float(center_y), {}, geo)
+
+
+# ============================================================== CTA and disclaimer
+
+def render_cta(text: str, sub: str | None, accent: str, canvas=(1080, 1920),
+               center_y: float | None = None) -> Image.Image:
+    """Call-to-action button (accent pill + arrow) with an optional line below.
+
+    Default center y: layout_defaults(canvas)["cta_alone"] (1180 on 1080x1920). Asterisks and
+    symbols the font cannot draw are removed (text_issues reports them)."""
+    geo = _Geo(int(canvas[0]), int(canvas[1]))
+    k = geo.k
+    acc = _rgba(accent or DEFAULT_ACCENT)
+    on = _on_color(acc)
+    label, _ = sanitize_text(strip_markup(str(text or "").strip())[0].upper(), _TEXT_FONTS["cta"])
+    label = " ".join(label.split())
+    if sub is not None:
+        sub = " ".join(sanitize_text(strip_markup(str(sub))[0], _TEXT_FONTS["cta_sub"])[0].split())
+    max_w = min(860 * geo.sx, geo.w - 2 * SIDE_MARGIN * geo.sx)
+    size = 66 * k
+    for _ in range(6):
+        f = _font("sans_black", size)
+        h = size * 2.05
+        icon = h * 0.64
+        w = f.getlength(label) + size * 1.1 + icon + size * 0.5
+        if w <= max_w or size <= 30 * k:
+            break
+        size = math.floor(size * max_w / w * 0.99)
+    f = _font("sans_black", size)
+    cap = _cap_height(f)
+    h = size * 2.05
+    icon = h * 0.64
+    text_w = f.getlength(label)
+    w = text_w + size * 1.1 + icon + size * 0.5
+    margin = int(size * 0.6)
+    layer = _new(w + 2 * margin, h + 2 * margin)
+    x0, y0 = margin, margin
+    pill = _new(layer.width, layer.height)
+    _rounded_box(pill, (x0, y0, x0 + w, y0 + h), radius=h / 2.0, color=acc)
+    _alpha_paste(layer, _shadow_of(pill, blur=size * 0.3, alpha=0.45), 0, int(size * 0.14))
+    layer.alpha_composite(pill)
+    # inner highlight line for a pressed-button feel
+    _rounded_box(layer, (x0 + h * 0.3, y0 + h * 0.1, x0 + w - h * 0.3, y0 + h * 0.1 + max(2, size * 0.05)),
+                 radius=size * 0.03, color=(255, 255, 255, 70))
+    d = ImageDraw.Draw(layer)
+    tx = x0 + size * 0.75
+    d.text((tx, y0 + h / 2.0 + cap / 2.0), label, font=f, fill=on, anchor="ls")
+    # round icon with an arrow
+    icx = x0 + w - size * 0.32 - icon / 2.0
+    icy = y0 + h / 2.0
+    _rounded_box(layer, (icx - icon / 2, icy - icon / 2, icx + icon / 2, icy + icon / 2), radius=icon / 2, color=on)
+    a = icon * 0.24
+    shaft = icon * 0.09
+    arrow = [(icx - a, icy - shaft), (icx + a * 0.1, icy - shaft), (icx + a * 0.1, icy - a * 0.75), (icx + a * 1.05, icy),
+             (icx + a * 0.1, icy + a * 0.75), (icx + a * 0.1, icy + shaft), (icx - a, icy + shaft)]
+    _polygon(layer, arrow, acc)
+    img = Image.new("RGBA", (geo.w, geo.h), (0, 0, 0, 0))
+    cy = layout_defaults((geo.w, geo.h))["cta_alone"] if center_y is None else float(center_y)
+    _alpha_paste(img, layer, int(round(geo.cx - (x0 + w / 2.0))), int(round(cy - (y0 + h / 2.0))))
+    if sub and str(sub).strip():
+        s_size = 42 * k
+        s_text = str(sub).strip()
+        for _ in range(4):
+            sf = _font("text_bold", s_size)
+            if sf.getlength(s_text) <= max_w or s_size <= 24 * k:
+                break
+            s_size = math.floor(s_size * max_w / sf.getlength(s_text) * 0.99)
+        sf = _font("text_bold", s_size)
+        s_cap = _cap_height(sf)
+        stroke = max(1, int(round(s_size * 0.06)))
+        sw = sf.getlength(s_text)
+        pad = int(s_size * 0.6)
+        sl = _new(sw + 2 * pad, s_size * 1.6 + 2 * pad)
+        ImageDraw.Draw(sl).text((pad, pad + s_size * 0.3 + s_cap), s_text, font=sf, fill=WHITE, anchor="ls",
+                                stroke_width=stroke, stroke_fill=(0, 0, 0, 255))
+        out = _new(sl.width, sl.height)
+        _alpha_paste(out, _shadow_of(sl, blur=s_size * 0.25, alpha=0.75), 0, int(s_size * 0.06))
+        out.alpha_composite(sl)
+        sy = cy + h / 2.0 + s_size * 0.55 + s_cap / 2.0
+        _alpha_paste(img, out, int(round(geo.cx - (pad + sw / 2.0))), int(round(sy - (pad + s_size * 0.3 + s_cap / 2.0))))
+    return img
+
+
+def render_disclaimer(text: str, canvas=(1080, 1920), center_y: float | None = None) -> Image.Image:
+    """Small dark pill with the result disclaimer (up to 2 lines).
+
+    Default center y: layout_defaults(canvas)["disclaimer"] (1548 on 1080x1920)."""
+    geo = _Geo(int(canvas[0]), int(canvas[1]))
+    k = geo.k
+    msg = " ".join(sanitize_text(strip_markup(str(text or ""))[0], _TEXT_FONTS["disclaimer"])[0].split())
+    if center_y is None:
+        center_y = layout_defaults((geo.w, geo.h))["disclaimer"]
+    img = Image.new("RGBA", (geo.w, geo.h), (0, 0, 0, 0))
+    if not msg:
+        return img
+    max_w = geo.w - 2 * SIDE_MARGIN * geo.sx
+    size = 31 * k
+    padx, pady = size * 0.7, size * 0.36
+    words = msg.split()
+    for _ in range(6):
+        f = _font("text_semibold", size)
+        one_w = f.getlength(msg)
+        if one_w + 2 * padx <= max_w:
+            lines = [words]
+        else:
+            lines = _balanced_split(words, lambda ws: f.getlength(" ".join(ws)))
+        widest = max(f.getlength(" ".join(ln)) for ln in lines)
+        if widest + 2 * padx <= max_w or size <= 20 * k:
+            break
+        size = math.floor(size * (max_w - 2 * padx) / widest * 0.99)
+        padx, pady = size * 0.7, size * 0.36
+    f = _font("text_semibold", size)
+    asc, desc = f.getmetrics()
+    pitch = size * 1.25
+    widths = [f.getlength(" ".join(ln)) for ln in lines]
+    box_w = max(widths) + 2 * padx
+    box_h = asc + desc + pitch * (len(lines) - 1) + 2 * pady
+    layer = _new(box_w + 4, box_h + 4)
+    _rounded_box(layer, (2, 2, 2 + box_w, 2 + box_h), radius=min(size * 0.6, box_h / 2), color=(0, 0, 0, 128))
+    d = ImageDraw.Draw(layer)
+    for i, (ln, wl) in enumerate(zip(lines, widths)):
+        d.text((2 + (box_w - wl) / 2.0, 2 + pady + asc + pitch * i), " ".join(ln), font=f,
+               fill=(255, 255, 255, 240), anchor="ls")
+    cy = float(center_y)
+    cy = min(cy, geo.h - box_h / 2.0 - 8 * geo.sy)
+    _alpha_paste(img, layer, int(round(geo.cx - (2 + box_w / 2.0))), int(round(cy - (2 + box_h / 2.0))))
+    return img
+
+
+# ============================================================== samples
+
+def cover_image(img: Image.Image, size: tuple[int, int]) -> Image.Image:
+    """Scale to fill `size` and center-crop (like CSS object-fit: cover)."""
+    w, h = size
+    s = max(w / img.width, h / img.height)
+    nw, nh = max(1, int(round(img.width * s))), max(1, int(round(img.height * s)))
+    r = img.resize((nw, nh), Image.LANCZOS)
+    x, y = (nw - w) // 2, (nh - h) // 2
+    return r.crop((x, y, x + w, y + h))
+
+
+def sample_caption_words(text: str, style_id: str) -> tuple[list[str], int]:
+    """Words shown in a caption sample and which one is active."""
+    spec = _caption_spec(style_id)
+    words = display_words(str(text).split(), style_id)
+    if not words:
+        words = display_words("Olha só isso aqui".split(), style_id)
+    limit = _Geo(REF_W, REF_H).caption_max_w
+    chosen: list[str] = []
+    for w in words:
+        if len(chosen) >= spec.max_words:
+            break
+        trial = chosen + [w]
+        if chosen and spec.lines == 1 and measure_caption_width(trial, style_id, already_display=True) > limit:
+            break
+        if chosen and spec.lines >= 2 and measure_caption_width(trial, style_id, already_display=True) > limit * spec.lines * 0.92:
+            break
+        chosen.append(w)
+    active = -1 if not spec.animated else (0 if spec.one_word else min(1, len(chosen) - 1))
+    return chosen, active
+
+
+def render_caption_image(words: list[str], style_id: str, accent: str, canvas=(1080, 1920),
+                         active: int = 0, center_y: float | None = None, font_scale: float = 1.0) -> Image.Image:
+    """One steady caption state (display words already cased) on a transparent canvas."""
+    spec = _caption_spec(style_id)
+    geo = _Geo(int(canvas[0]), int(canvas[1]))
+    cy = layout_defaults((geo.w, geo.h))["caption"] if center_y is None else center_y
+    variant = {"angle": -2.6} if spec.draw == "fita" else {}
+    block = _caption_block(spec, geo, tuple(words), active, accent or DEFAULT_ACCENT, font_scale, variant, {})
+    return _place((geo.w, geo.h), block, geo.cx, cy, {}, geo)
+
+
+def sample_canvas(background_size) -> tuple[int, int]:
+    """Full-size canvas a style sample is composed on, for a frame of this size."""
+    bw, bh = background_size
+    if bw < bh:
+        return (REF_W, REF_H)
+    if bw > bh:
+        return (REF_H, REF_W)
+    return (REF_W, REF_W)
+
+
+def render_sample_frame(background: Image.Image, kind: str, style_id: str, accent: str,
+                        text: str, center_y: float | None = None) -> Image.Image:
+    """Style preview over a real frame. Returns an RGB image with the background's size.
+
+    `center_y` (pixels on sample_canvas(background.size)) moves the text, e.g. off the face;
+    default: layout_defaults of that canvas."""
+    bw, bh = background.size
+    canvas = sample_canvas((bw, bh))
+    base = cover_image(background.convert("RGB"), canvas).convert("RGBA")
+    lay = layout_defaults(canvas)
+    if kind == "caption":
+        words, active = sample_caption_words(text, style_id)
+        over = render_caption_image(words, style_id, accent, canvas, active=active,
+                                    center_y=lay["caption"] if center_y is None else center_y)
+    elif kind == "hook":
+        over = render_hook(text, style_id, accent, canvas, center_y=lay["hook"] if center_y is None else center_y)
+    else:
+        raise ValueError("kind precisa ser 'caption' ou 'hook'")
+    base.alpha_composite(over)
+    out = base.convert("RGB")
+    if out.size != (bw, bh):
+        out = out.resize((bw, bh), Image.LANCZOS)
+    return out
+
+
+# ============================================================== CLI
+
+def _catalog_check() -> list[str]:
+    cat = load_style_catalog()
+    problems = []
+    for kind, ids in (("caption_styles", set(CAPTION_STYLES)), ("hook_styles", set(HOOK_STYLES))):
+        cat_ids = {s.get("id") for s in cat.get(kind, [])}
+        if cat_ids != ids:
+            problems.append(f"{kind}: catálogo {sorted(cat_ids)} x código {sorted(ids)}")
+    return problems
+
+
+def _save_with_bg(img: Image.Image, out: str, bg: str | None) -> None:
+    if bg:
+        with Image.open(bg) as b:
+            base = cover_image(b.convert("RGB"), img.size).convert("RGBA")
+        base.alpha_composite(img)
+        img = base.convert("RGB")
+    Path(out).parent.mkdir(parents=True, exist_ok=True)
+    img.save(out)
+    print(f"ok: {out}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Renderiza textos (legendas, gancho, chamada, aviso) em PNG transparente.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("list", help="lista os estilos disponíveis")
+
+    def common_args(p):
+        p.add_argument("--accent", default=DEFAULT_ACCENT, help="cor de destaque em hex (padrão #FFC400)")
+        p.add_argument("--width", type=int, default=REF_W)
+        p.add_argument("--height", type=int, default=REF_H)
+        p.add_argument("--bg", help="imagem de fundo para conferir (opcional)")
+        p.add_argument("-o", "--output", required=True, help="PNG de saída")
+
+    p = sub.add_parser("hook", help="gancho (1 ou 2 linhas)")
+    p.add_argument("text")
+    p.add_argument("--style", required=True)
+    p.add_argument("--center-y", type=float, help="centro vertical em pixels (padrão: 430 na tela vertical)")
+    common_args(p)
+    p = sub.add_parser("caption", help="um estado de legenda")
+    p.add_argument("text")
+    p.add_argument("--style", required=True)
+    p.add_argument("--active", type=int, default=1)
+    common_args(p)
+    p = sub.add_parser("cta", help="botão de chamada")
+    p.add_argument("text")
+    p.add_argument("--sub")
+    p.add_argument("--center-y", type=float, help="centro vertical em pixels (padrão: 1180 na tela vertical)")
+    common_args(p)
+    p = sub.add_parser("disclaimer", help="aviso de resultado")
+    p.add_argument("text")
+    p.add_argument("--center-y", type=float, help="centro vertical em pixels (padrão: 1548 na tela vertical)")
+    common_args(p)
+    p = sub.add_parser("track", help="trilha de legendas: PNGs + captions.ffconcat")
+    p.add_argument("captions", help="captions.json")
+    p.add_argument("--style", required=True)
+    p.add_argument("--accent", default=DEFAULT_ACCENT)
+    p.add_argument("--fps", type=int, default=30)
+    p.add_argument("--width", type=int, default=REF_W)
+    p.add_argument("--height", type=int, default=REF_H)
+    p.add_argument("--duration", type=float, help="duração total do vídeo (padrão: fim da última legenda)")
+    p.add_argument("--font-scale", type=float, default=1.0)
+    p.add_argument("-o", "--out-dir", required=True)
+    args = ap.parse_args(argv)
+
+    try:
+        if args.cmd == "list":
+            print("legendas: " + ", ".join(CAPTION_STYLES))
+            print("ganchos:  " + ", ".join(HOOK_STYLES))
+            for msg in _catalog_check():
+                print("AVISO: " + msg)
+            return 0
+        canvas = (args.width, args.height)
+        issues: list[str] = []
+        if args.cmd == "hook":
+            fit = hook_fit(args.text, args.style, canvas)
+            issues = text_issues("hook", args.text, args.style)
+            cy = layout_defaults(canvas)["hook"] if args.center_y is None else args.center_y
+            _save_with_bg(render_hook(args.text, args.style, args.accent, canvas, cy), args.output, args.bg)
+            print(f"linhas: {' / '.join(fit['lines'])} · letra {fit['size']}px")
+            if fit["too_long"]:
+                print(f"aviso: gancho longo demais, a letra ficou pequena ({fit['size']}px, ideal a partir de "
+                      f"{fit['min_size']}px). Encurte o texto.")
+        elif args.cmd == "caption":
+            spec = _caption_spec(args.style)
+            words = display_words(args.text.split(), args.style)
+            active = -1 if not spec.animated else max(-1, min(args.active, len(words) - 1))
+            _save_with_bg(render_caption_image(words, args.style, args.accent, canvas, active=active), args.output, args.bg)
+        elif args.cmd == "cta":
+            issues = text_issues("cta", args.text) + text_issues("cta_sub", args.sub or "")
+            _save_with_bg(render_cta(args.text, args.sub, args.accent, canvas, args.center_y), args.output, args.bg)
+        elif args.cmd == "disclaimer":
+            issues = text_issues("disclaimer", args.text)
+            _save_with_bg(render_disclaimer(args.text, canvas, args.center_y), args.output, args.bg)
+        elif args.cmd == "track":
+            src = Path(args.captions)
+            if not src.exists():
+                print(f"erro: arquivo de legendas não encontrado: {src}", file=sys.stderr)
+                return 2
+            data = json.loads(src.read_text(encoding="utf-8"))
+            t0 = time.time()
+            states = render_caption_track(data, args.style, args.accent, args.out_dir, canvas, args.fps,
+                                          font_scale=args.font_scale)
+            total = args.duration if args.duration else (states[-1]["end"] if states else 0.0)
+            out_dir = Path(args.out_dir).resolve()
+            ff = write_ffconcat(states, str(out_dir / "captions.ffconcat"), total, str(out_dir / "blank.png"), fps=args.fps)
+            uniq = len({s["file"] for s in states})
+            print(f"ok: {len(states)} estados, {uniq} PNGs, {time.time() - t0:.1f}s -> {ff}")
+        for msg in issues:
+            print(f"aviso: {msg}")
+    except (ValueError, FileNotFoundError) as e:
+        print(f"erro: {e}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())