primocode 10.16.0 → 10.17.1

package/editor/helpers/motion/templates/contador.py

@@ -0,0 +1,222 @@
+"""contador: a number that counts up (or down) to its value, with prefix, suffix and a label.
+
+REFERENCE TEMPLATE. Copy this file to write a new one (SPEC Contract 12):
+  1. TEMPLATE describes the template (id = file name) and its params; the registry checks it.
+  2. render(frame_index, fps, params, box) draws ONE frame on a fresh Canvas and returns it.
+     Time is frame_index / fps. `params` is already complete and checked. `box` gives the place
+     (design px, 1080 wide), the theme colors and the item length (box.frames).
+  3. Optional: sfx(params, fps, frames), suggested_duration(params), settle(params, fps).
+Keep the layout math in a cached function (it runs once per item, not once per frame).
+"""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+
+from motion import engine as E
+
+TEMPLATE = {
+    "id": "contador",
+    "label_pt": "Contador de número",
+    "description_pt": "Um número que sobe até o valor final num cartão, com prefixo (R$), sufixo (%, x, pessoas) "
+                      "e uma legenda curta embaixo. Uma barra acompanha a contagem e o número dá um pulinho no fim.",
+    "use_when_pt": "Quando a fala cita um número que precisa ficar na cabeça: quantidade de alunos, porcentagem, "
+                   "tempo, preço, faturamento. Use o número que a pessoa disse ou mostrou, sem inventar.",
+    "category": "números",
+    "version": 1,
+    "params": {
+        "value": {"type": "number", "default": 1000, "min": -1e13, "max": 1e13,
+                  "label_pt": "Número final (use ponto para decimais: 1904152.87)"},
+        "start_value": {"type": "number", "default": 0, "min": -1e13, "max": 1e13,
+                        "label_pt": "Número onde a contagem começa"},
+        "prefix": {"type": "text", "default": "", "max_len": 6, "label_pt": "Antes do número, ex.: R$ ou +"},
+        "suffix": {"type": "text", "default": "", "max_len": 12, "label_pt": "Depois do número, ex.: %, x ou pessoas"},
+        "decimals": {"type": "integer", "default": None, "nullable": True, "min": 0, "max": 3,
+                     "label_pt": "Casas decimais (vazio: automático; dinheiro com centavos usa 2)"},
+        "label": {"type": "text", "default": "", "max_len": 40, "label_pt": "Legenda curta embaixo do número"},
+        "duration": {"type": "number", "default": 1.4, "min": 0.3, "max": 10,
+                     "label_pt": "Segundos da contagem"},
+        "delay": {"type": "number", "default": 0.15, "min": 0, "max": 5,
+                  "label_pt": "Segundos antes de começar a contar"},
+        "ease": {"type": "choice", "choices": ["suave", "linear"], "default": "suave",
+                 "label_pt": "Ritmo: suave (rápido e freia no fim) ou linear (constante, bom para tempo)"},
+        "size": {"type": "choice", "choices": ["normal", "grande"], "default": "normal",
+                 "label_pt": "Tamanho do número"},
+        "card": {"type": "bool", "default": True, "label_pt": "Cartão atrás do número (sem cartão: contorno e sombra)"},
+        "bar": {"type": "bool", "default": True, "label_pt": "Barra que enche junto com a contagem"},
+    },
+    "default_duration": 3.0,
+    "default_region": "centro",
+    "sfx": [{"at": 0.0, "name": "pop"}, {"at": 0.15, "name": "count", "volume": 1.3}],
+    "example": {"value": 1250, "suffix": "alunos", "label": "na primeira turma"},
+}
+
+LAND = 0.32          # seconds of the landing pop
+
+
+def _decimals(p: dict) -> int:
+    if p["decimals"] is not None:
+        return int(p["decimals"])
+    money = E.looks_like_money(p["prefix"], p["suffix"])
+    d = max(E.auto_decimals(p["value"]), E.auto_decimals(p["start_value"]))
+    return 2 if money and d else d
+
+
+def _affix_scale(text: str) -> float:
+    """Small symbols (%, x, +) sit almost at number size; words and currencies are smaller."""
+    return 0.82 if len(text.strip()) <= 1 else 0.52
+
+
+@lru_cache(maxsize=64)
+def _layout(params_json: str, box: E.Box) -> dict:
+    p = json.loads(params_json)
+    dec = _decimals(p)
+    prefix, suffix = p["prefix"].strip(), p["suffix"].strip()
+    label = p["label"].strip()
+    card = p["card"]
+    theme = box.theme
+    pad_x = 64.0 if card else 12.0
+    max_size = 200.0 if p["size"] == "grande" else 150.0
+
+    widest = max((E.format_number(v, dec) for v in (p["value"], p["start_value"])),
+                 key=lambda s: E.measure(s, "sans_black", 100, tabular=True).width)
+
+    def block(size: float) -> dict:
+        num_w = E.measure(widest, "sans_black", size, tabular=True).width
+        pre_size, suf_size = size * _affix_scale(prefix), size * _affix_scale(suffix)
+        pre_w = E.measure(prefix, "sans_black", pre_size).width if prefix else 0.0
+        suf_w = E.measure(suffix, "sans_black", suf_size).width if suffix else 0.0
+        gap_p = size * (0.02 if len(prefix) <= 1 else 0.14) if prefix else 0.0
+        gap_s = size * (0.02 if len(suffix) <= 1 else 0.14) if suffix else 0.0
+        return {"size": size, "num_w": num_w, "pre_size": pre_size, "suf_size": suf_size, "pre_w": pre_w,
+                "suf_w": suf_w, "gap_p": gap_p, "gap_s": gap_s,
+                "width": pre_w + gap_p + num_w + gap_s + suf_w}
+
+    avail = box.w - 2 * pad_x
+    b = block(max_size)
+    if b["width"] > avail:
+        b = block(max(44.0, max_size * avail / b["width"] * 0.995))
+    size = b["size"]
+    cap = E.measure("0", "sans_black", size).cap
+    label_size = max(36.0, min(54.0, size * 0.40))
+    if label:
+        label_size = E.fit_text(label, "text_semibold", avail, label_size, 24.0)
+    label_cap = E.measure("H", "text_semibold", label_size).cap if label else 0.0
+    bar_h = max(8.0, size * 0.07) if p["bar"] else 0.0
+    gap_bar = size * 0.30 if p["bar"] else 0.0
+    gap_label = (size * 0.26 if p["bar"] else size * 0.30) if label else 0.0
+    pad_y = max(52.0, size * 0.50) if card else 0.0
+    content_h = cap + gap_bar + bar_h + gap_label + label_cap + (label_size * 0.25 if label else 0.0)
+    card_h = content_h + 2 * pad_y
+    card_w = min(box.w, max(b["width"], E.measure(label, "text_semibold", label_size).width if label else 0.0)
+                 + 2 * pad_x)
+    top = (box.h - card_h) / 2.0
+    x0 = (box.w - b["width"]) / 2.0
+    baseline = top + pad_y + cap
+    bar_y = baseline + gap_bar
+    number_color = "accent"
+    if card and E.contrast(theme.accent, theme.card) < 2.4:
+        number_color = "text"          # a light accent on a white card: the bar keeps the accent
+    return {
+        "dec": dec, "prefix": prefix, "suffix": suffix, "label": label, "card": card,
+        "size": size, "cap": cap, "block": b, "x0": x0, "baseline": baseline,
+        "bar_y": bar_y, "bar_h": bar_h, "label_size": label_size,
+        "label_base": bar_y + bar_h + gap_label + label_cap,
+        "card_box": ((box.w - card_w) / 2.0, top, card_w, card_h), "number_color": number_color,
+        "radius": min(48.0, card_h * 0.22),
+    }
+
+
+def _count(p: dict, t: float) -> float:
+    fn = "linear" if p["ease"] == "linear" else "out_expo"
+    return E.eased(t, p["delay"], p["duration"], fn)
+
+
+def render(frame_index: int, fps: int, params: dict, box: E.Box) -> E.Canvas:
+    cv = E.Canvas(box)
+    t = frame_index / fps
+    L = _layout(json.dumps(params, sort_keys=True), box)
+    b = L["block"]
+    t_end = params["delay"] + params["duration"]
+
+    # entrance of the whole card: fade, rise and a small overshoot. It starts one frame early, so
+    # frame 0 (where the entrance sound lands) already shows the card.
+    t_in = t + 1.0 / fps
+    alpha = E.eased(t_in, 0.0, 0.18, "out_quad")
+    scale = 0.88 + 0.12 * E.out_back(E.progress(t_in, 0.0, 0.5), 1.4)
+    rise = 36.0 * (1.0 - E.eased(t_in, 0.0, 0.45))
+    with cv.group(opacity=alpha, scale=scale, dy=rise):
+        cx0, cy0, cw, ch = L["card_box"]
+        if L["card"]:
+            cv.card(cx0, cy0, cw, ch, radius=L["radius"])
+
+        p = _count(params, t)
+        value = params["start_value"] + (params["value"] - params["start_value"]) * p
+        digits = E.format_number(value, L["dec"])
+        size = L["size"]
+        prefix, pre_w = L["prefix"], b["pre_w"]
+        if prefix and digits.startswith("-"):
+            # a negative amount is written -R$ 37,00, not R$ -37,00
+            prefix, digits = ("-" if prefix == "+" else "-" + prefix), digits[1:]
+            pre_w = E.measure(prefix, "sans_black", b["pre_size"]).width
+        num_w = E.measure(digits, "sans_black", size, tabular=True).width
+        # the line is centered on what it shows now; tabular digits keep it still once the digit count is final
+        x_pre = (cv.w - (pre_w + b["gap_p"] + num_w + b["gap_s"] + b["suf_w"])) / 2.0
+        x_num = x_pre + pre_w + b["gap_p"]
+        base = L["baseline"]
+        outline = {} if L["card"] else {"stroke": size * 0.05, "stroke_color": "black", "shadow": E.TEXT_SHADOW}
+
+        land = E.pulse(t, t_end - 0.02, LAND)
+        pivot = (cv.cx, base - L["cap"] / 2.0)
+
+        def number() -> None:
+            cv.text(x_num, base, digits, "sans_black", size, color=L["number_color"], tabular=True, **outline)
+            if prefix:
+                cv.text(x_pre, base, prefix, "sans_black", b["pre_size"], color="text", opacity=0.92, **outline)
+            if L["suffix"]:
+                cv.text(x_num + num_w + b["gap_s"], base, L["suffix"], "sans_black", b["suf_size"], color="text",
+                        opacity=0.92, **outline)
+
+        with cv.group(scale=1.0 + 0.07 * land, pivot=pivot):
+            if land > 0.02:
+                cv.glow(number, radius=30, opacity=0.5 * land)
+            else:
+                number()
+
+        if L["bar_h"]:
+            bw, bh = b["width"], L["bar_h"]
+            bx = L["x0"]
+            track = "track" if L["card"] else (0, 0, 0, 110)
+            cv.pill(bx, L["bar_y"], bw, bh, fill=track)
+            if p > 0:
+                cv.pill(bx, L["bar_y"], max(bh, bw * p), bh, fill="accent")
+
+        if L["label"]:
+            la = E.eased(t, 0.12, 0.35)
+            if cv.visible(la):
+                cv.text(cv.cx, L["label_base"] + 14.0 * (1.0 - la), L["label"], "text_semibold", L["label_size"],
+                        color="muted" if L["card"] else "text", opacity=la, anchor="ms",
+                        **({} if L["card"] else {"stroke": L["label_size"] * 0.08, "stroke_color": "black"}))
+    return cv
+
+
+def sfx(params: dict, fps: int, frames: int) -> list[dict]:
+    cues = [{"at": 0.0, "name": "pop", "why": "entrada"}]
+    if params["value"] != params["start_value"]:
+        start, dur = params["delay"], params["duration"]
+        # the ticking follows the count: once for the fast "suave" count, every 0.6 s for a linear one
+        steps = 1 if params["ease"] != "linear" else max(1, int(dur / 0.6 + 0.5))
+        for k in range(steps):
+            cues.append({"at": start + k * 0.6, "name": "count", "volume": 1.3, "why": "contagem"})
+    return [{"frame": E.frame_of(c.pop("at"), fps), **c} for c in cues]
+
+
+def suggested_duration(params: dict) -> float:
+    """Count, landing, and about 1.5 s to read the number."""
+    return round(max(TEMPLATE["default_duration"], params["delay"] + params["duration"] + LAND + 1.5), 2)
+
+
+def settle(params: dict, fps: int) -> float:
+    """From here on every frame is the same (until the exit)."""
+    return params["delay"] + params["duration"] + LAND + 0.05

package/editor/helpers/motion/templates/destaque.py

@@ -0,0 +1,263 @@
+"""destaque: a marker stroke that draws itself at a place on the screen: a circle around it, an underline
+under it or an arrow pointing at it, with an optional handwritten note.
+
+The place is `target` = [x, y, w, h] in design px of the output canvas (1080x1920 for vertical video),
+measured on a frame of the video. The template never moves (`movable: False`), draws on the whole safe
+area ("tela") and uses a large bleed so a target near the edges is still covered.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from functools import lru_cache
+
+from motion import engine as E
+from motion.engine import MotionError
+
+TEMPLATE = {
+    "id": "destaque",
+    "label_pt": "Destaque desenhado",
+    "description_pt": "Um traço de caneta que se desenha sozinho num ponto da tela: círculo em volta, sublinhado "
+                      "embaixo ou seta apontando para a área escolhida. Pode ter um texto escrito à mão ao lado.",
+    "use_when_pt": "Para levar o olho a algo que já aparece no vídeo: um preço, um botão, um número num print, uma "
+                   "palavra na tela. Meça a área num quadro do vídeo (pixels da tela 1080x1920) e passe em target.",
+    "notes_pt": "Fica exatamente no alvo e não sai do lugar para fugir do rosto. Se o alvo se mexe no vídeo, o "
+                "traço não acompanha: use num trecho parado. A cor do traço é a cor de destaque do vídeo; troque "
+                "só neste item com cor (ex.: vermelho).",
+    "category": "marcações",
+    "version": 1,
+    "params": {
+        "target": {"type": "box", "default": [290, 1040, 500, 160],
+                   "label_pt": "Área a destacar: [x, y, largura, altura] em pixels da tela 1080x1920"},
+        "mode": {"type": "choice", "choices": ["circulo", "sublinhado", "seta"], "default": "circulo",
+                 "label_pt": "Traço: círculo em volta, sublinhado embaixo ou seta apontando"},
+        "side": {"type": "choice", "choices": ["auto", "baixo", "cima", "esquerda", "direita"], "default": "auto",
+                 "label_pt": "Só para a seta: de que lado ela vem (auto: o lado com mais espaço na tela; sem "
+                              "espaço no lado pedido, usa o de mais espaço)"},
+        "label": {"type": "text", "default": "", "max_len": 22,
+                  "label_pt": "Texto escrito à mão junto do traço (opcional), ex.: olha isso"},
+        "thickness": {"type": "number", "default": 12, "min": 4, "max": 32,
+                      "label_pt": "Espessura do traço em pixels"},
+        "duration": {"type": "number", "default": 0.6, "min": 0.2, "max": 3,
+                     "label_pt": "Segundos para desenhar o traço"},
+        "shadow": {"type": "bool", "default": True,
+                   "label_pt": "Sombra leve atrás do traço (ajuda a ler em fundo claro)"},
+    },
+    "default_duration": 2.0,
+    "default_region": "tela",
+    "movable": False,
+    "bleed": 160,
+    "sfx": [{"at": 0.15, "name": "whoosh", "volume": 0.7}],
+    "example": {"target": [240, 900, 600, 200], "mode": "circulo", "label": "olha isso"},
+}
+
+LABEL_FONT = "marker"
+LABEL_SIZE = 72.0
+EDGE = 14.0            # the stroke keeps this far from the screen edges
+LABEL_IN = 0.32
+SIDES = ("baixo", "cima", "esquerda", "direita")
+MIN_ROOM = 90.0        # a forced arrow side with less room than this falls back to the side with the most room
+LABEL_APPEAR = {"circulo": 0.55, "sublinhado": 0.7, "seta": 0.0}   # fraction of the draw time
+
+
+def _smooth(x: float) -> float:
+    x = E.clamp01(x)
+    return x * x * (3 - 2 * x)
+
+
+def _draw_curve(u: float) -> float:
+    """A hand stroke: leaves fast and eases into the end."""
+    return 0.6 * E.out_cubic(u) + 0.4 * E.in_out_cubic(u)
+
+
+def _taper(n: int, start: float = 0.55, end: float = 0.55) -> list[float]:
+    """Width factor per point: thin at the pen-down, full in the middle, thinning at the lift."""
+    out = []
+    for k in range(n):
+        u = k / max(1, n - 1)
+        out.append((start + (1 - start) * _smooth(u / 0.14)) * (1 - (1 - end) * _smooth((u - 0.82) / 0.18)))
+    return out
+
+
+def _rotate(points, cx: float, cy: float, deg: float):
+    a = math.radians(deg)
+    c, s = math.cos(a), math.sin(a)
+    return [(cx + (x - cx) * c - (y - cy) * s, cy + (x - cx) * s + (y - cy) * c) for x, y in points]
+
+
+def _check_target(target, design) -> None:
+    x, y, w, h = target
+    dw, dh = design
+    if x + w <= 0 or y + h <= 0 or x >= dw or y >= dh:
+        raise MotionError(f"destaque.params.target [{x:g}, {y:g}, {w:g}, {h:g}] fica fora da tela "
+                          f"({dw:.0f}x{dh:.0f}); meça a área num quadro do vídeo")
+
+
+def _pick_side(side: str, target, safe) -> tuple[str, dict]:
+    x, y, w, h = target
+    sx0, sy0, sx1, sy1 = safe
+    room = {"baixo": sy1 - (y + h), "cima": y - sy0, "esquerda": x - sx0, "direita": sx1 - (x + w)}
+    if side != "auto" and room[side] >= MIN_ROOM:
+        return side, room
+    # vertical arrows read more naturally on a phone: horizontal ones need clearly more room to win
+    weight = {"baixo": 1.0, "cima": 0.95, "esquerda": 0.8, "direita": 0.8}
+    return max(SIDES, key=lambda k: (room[k] * weight[k], -SIDES.index(k))), room
+
+
+@lru_cache(maxsize=64)
+def _geometry(params_json: str, box: E.Box) -> dict:
+    """Stroke paths and the label place, in CANVAS design px (converted to box-local when drawing)."""
+    p = json.loads(params_json)
+    target = p["target"]
+    dw, dh = box.design
+    _check_target(target, (dw, dh))
+    tx, ty, tw, th = target
+    cx, cy = tx + tw / 2.0, ty + th / 2.0
+    thick = p["thickness"]
+    seed = E.stable_seed("destaque", tuple(target), p["mode"])
+    safe = E.safe_area(box.canvas)
+    label = p["label"].strip()
+    lsize = 0.0
+    lw = lcap = 0.0
+    if label:
+        lsize = E.fit_text(label, LABEL_FONT, (safe[2] - safe[0]) * 0.9, LABEL_SIZE, 30.0)
+        m = E.measure(label, LABEL_FONT, lsize)
+        lw, lcap = m.width, m.cap
+    strokes = []           # (points, width factors, start fraction, end fraction of the draw time)
+    label_at = None        # (x center, y baseline, rotation, appear time fraction)
+
+    if p["mode"] == "circulo":
+        pad = thick * 0.5 + 14.0
+        rx = tw / 2.0 * 1.22 + pad
+        ry = th / 2.0 * 1.22 + pad
+        rx = min(rx, max(tw / 2.0 + thick, min(cx, dw - cx) - EDGE))
+        ry = min(ry, max(th / 2.0 + thick, min(cy, dh - cy) - EDGE))
+        pts = E.ellipse_points(cx, cy, rx, ry, start_deg=-128.0, sweep_deg=382.0, n=72, wobble=0.035, seed=seed)
+        pts = _rotate(pts, cx, cy, -3.0)
+        strokes.append((pts, _taper(len(pts), 0.5, 0.45), 0.0, 1.0))
+        if label:
+            above = cy - ry - 22.0
+            if above - lcap - 30.0 >= safe[1]:
+                label_at = (cx + rx * 0.25, above, -5.0, LABEL_APPEAR["circulo"])
+            else:
+                label_at = (cx + rx * 0.25, cy + ry + 22.0 + lcap, -5.0, LABEL_APPEAR["circulo"])
+    elif p["mode"] == "sublinhado":
+        gap = thick * 0.6 + 12.0
+        x0 = max(EDGE, tx - tw * 0.03)
+        x1 = min(dw - EDGE, tx + tw * 1.03)
+        rise = min(24.0, (x1 - x0) * 0.045)
+        y = ty + th + gap + rise          # the rising end stays under the target
+        pts = E.bezier_points((x0, y + rise * 0.15), ((x0 + x1) / 2.0, y + rise * 0.75), (x1, y - rise), n=40)
+        pts = E.wobble_points(pts, max(0.8, thick * 0.10), seed=seed, step=14.0)
+        strokes.append((pts, _taper(len(pts), 0.55, 0.5), 0.0, 0.78))
+        # a second, shorter swash under the first: the classic marker emphasis
+        y2 = y + thick * 1.35 + 6.0
+        a2, b2 = x0 + (x1 - x0) * 0.10, x0 + (x1 - x0) * 0.86
+        pts2 = E.bezier_points((a2, y2 + rise * 0.1), ((a2 + b2) / 2.0, y2 + rise * 0.55), (b2, y2 - rise * 0.7), n=30)
+        pts2 = E.wobble_points(pts2, max(0.8, thick * 0.08), seed=seed + 1, step=14.0)
+        strokes.append((pts2, [w * 0.72 for w in _taper(len(pts2), 0.55, 0.45)], 0.62, 1.0))
+        if label:
+            below = y2 + thick + 22.0 + lcap
+            if below + 20.0 <= safe[3]:
+                label_at = (cx, below, -4.0, LABEL_APPEAR["sublinhado"])
+            else:
+                label_at = (cx, ty - 24.0, -4.0, LABEL_APPEAR["sublinhado"])
+    else:
+        side, room = _pick_side(p["side"], target, safe)
+        g = 16.0 + thick
+        label_room = (lcap + 40.0) if label else 10.0
+        length = max(110.0, min(300.0, room[side] - g - label_room))
+        right_half = cx > dw / 2.0
+        if side in ("baixo", "cima"):
+            sign = 1.0 if side == "baixo" else -1.0
+            tip = (cx, (ty + th + g) if side == "baixo" else (ty - g))
+            lateral = -1.0 if right_half else 1.0
+            tail = (tip[0] + lateral * length * 0.42, tip[1] + sign * length)
+        else:
+            sign = -1.0 if side == "esquerda" else 1.0
+            tip = ((tx - g) if side == "esquerda" else (tx + tw + g), cy)
+            down = 1.0 if room["baixo"] >= room["cima"] else -1.0
+            tail = (tip[0] + sign * length, tip[1] + down * length * 0.38)
+        # keep the tail on the screen (shorten along the arrow)
+        tail = (min(max(tail[0], safe[0] + EDGE), safe[2] - EDGE), min(max(tail[1], EDGE), dh - EDGE))
+        L = math.dist(tail, tip)
+        mx, my = (tail[0] + tip[0]) / 2.0, (tail[1] + tip[1]) / 2.0
+        nx, ny = -(tip[1] - tail[1]) / max(L, 1e-6), (tip[0] - tail[0]) / max(L, 1e-6)
+        bend = 0.22 * L * (1.0 if (side in ("baixo", "direita")) != right_half else -1.0)
+        shaft = E.bezier_points(tail, (mx + nx * bend, my + ny * bend), tip, n=40)
+        shaft = E.wobble_points(shaft, max(0.6, thick * 0.08), seed=seed, step=16.0)
+        shaft[-1] = tip
+        strokes.append((shaft, _taper(len(shaft), 0.6, 1.0), 0.0, 0.72))
+        (x_a, y_a), (x_b, y_b) = shaft[-4], shaft[-1]
+        ang = math.atan2(y_b - y_a, x_b - x_a)
+        hl = max(thick * 3.4, 40.0)
+        w1 = (tip[0] + hl * math.cos(ang + math.pi - math.radians(30)), tip[1] + hl * math.sin(ang + math.pi - math.radians(30)))
+        w2 = (tip[0] + hl * math.cos(ang + math.pi + math.radians(33)), tip[1] + hl * math.sin(ang + math.pi + math.radians(33)))
+        strokes.append(([w1, tip, w2], [0.8, 1.0, 0.85], 0.66, 1.0))
+        if label:
+            # on the far side of the tail from the shaft, nudged away from the tip on horizontal arrows
+            lx = tail[0] if side in ("baixo", "cima") else tail[0] + sign * lw * 0.25
+            if tail[1] < tip[1] - 1.0:
+                label_at = (lx, tail[1] - 24.0, -4.0, LABEL_APPEAR["seta"])
+            else:
+                label_at = (lx, tail[1] + 22.0 + lcap, -4.0, LABEL_APPEAR["seta"])
+    if label_at is not None:
+        lx, ly, rot, appear = label_at
+        lx = min(max(lx, safe[0] + lw / 2.0 + 6.0), safe[2] - lw / 2.0 - 6.0)
+        ly = min(max(ly, EDGE + lcap), dh - EDGE)
+        label_at = (lx, ly, rot, appear)
+    return {"strokes": strokes, "label": label, "label_size": lsize, "label_cap": lcap, "label_at": label_at,
+            "thick": thick}
+
+
+def render(frame_index: int, fps: int, params: dict, box: E.Box) -> E.Canvas:
+    cv = E.Canvas(box)
+    t = frame_index / fps
+    t_in = t + 1.0 / fps
+    G = _geometry(json.dumps(params, sort_keys=True), box)
+    dur = params["duration"]
+    shadow = E.Shadow(blur=8.0, dy=3.0, opacity=0.45) if params["shadow"] else None
+    thick = G["thick"]
+    u = E.clamp01(t_in / dur)
+    for pts, widths, a, b in G["strokes"]:
+        prog = _draw_curve(E.remap(u, a, b))
+        if prog <= 0:
+            continue
+        local = [box.from_canvas(x, y) for x, y in pts]
+        cv.polyline(local, thick, color="accent", progress=prog, widths=[thick * w for w in widths],
+                    shadow=shadow)
+    if G["label_at"] is not None:
+        lx, ly, rot, appear = G["label_at"]
+        la = E.progress(t_in, appear * dur, LABEL_IN)
+        if la > 0:
+            x, y = box.from_canvas(lx, ly)
+            pivot = (x, y - G["label_cap"] / 2.0)
+            with cv.group(opacity=E.out_quad(min(1.0, la * 1.6)), scale=0.85 + 0.15 * E.out_back(la, 2.0),
+                          pivot=pivot, rotate=rot):
+                cv.text(x, y, G["label"], LABEL_FONT, G["label_size"], color="accent", anchor="ms",
+                        stroke=4.0, stroke_color=(0, 0, 0, 150),
+                        shadow=E.Shadow(blur=8.0, dy=3.0, opacity=0.5) if params["shadow"] else None)
+    return cv
+
+
+def sfx(params: dict, fps: int, frames: int) -> list[dict]:
+    dur = params["duration"]
+    if params["mode"] == "seta":
+        cues = [{"at": dur * 0.2, "name": "whoosh", "volume": 0.7, "why": "seta se desenhando"},
+                {"at": dur * 0.72, "name": "pop", "volume": 0.8, "why": "ponta da seta"}]
+    else:
+        cues = [{"at": dur * 0.25, "name": "whoosh", "volume": 0.7, "why": "traço se desenhando"}]
+    return [{"frame": E.frame_of(c.pop("at"), fps), **c} for c in cues]
+
+
+def suggested_duration(params: dict) -> float:
+    return round(max(TEMPLATE["default_duration"], params["duration"] + LABEL_IN + 1.4), 2)
+
+
+def settle(params: dict, fps: int) -> float:
+    """The drawing runs on t + 1/fps: it is complete one frame before `end`; half a frame of margin for rounding."""
+    end = params["duration"]
+    if params["label"].strip():
+        end = max(end, LABEL_APPEAR[params["mode"]] * params["duration"] + LABEL_IN)
+    return end - 0.5 / fps + 0.01