primocode 10.16.0 → 10.17.1

package/editor/helpers/motion/engine.py

@@ -0,0 +1,1915 @@
+"""Motion design engine: drawing, easing and timing for the animated templates (SPEC Contract 12).
+
+Everything is drawn with Pillow + numpy. Shapes get analytic anti-aliasing from signed distance
+fields (exact coverage per pixel, sub-pixel positions, no supersampling); text is FreeType through
+Pillow with float sizes and sub-pixel origins, using only the fonts in assets/fonts. Output is
+straight-alpha RGBA, deterministic (no clock, no global random state).
+
+Coordinates: templates draw in DESIGN pixels, box-local (origin = top-left of the box, y down).
+Design space is the output canvas divided by `k = min(W, H) / 1080`, so 1080x1920 for every vertical
+render (full or 540x960 preview). The Canvas multiplies by the render scale itself.
+
+Main pieces:
+    Box, Theme, Canvas (rect, circle, ring, line, polyline, polygon, arrow, check, cross, text,
+    rich_text, image, group), fonts (font, measure, fit_text, wrap_text), easing (EASINGS, ease, spring),
+    timing (seconds, frame_of, progress, eased, stagger, keyframes, pulse, shake, typewriter),
+    paths (ellipse_points, bezier_points, trim_points, path_length, wobble), numbers (format_number,
+    format_money, format_percent, format_compact, auto_decimals), regions (REGIONS, region_box, safe_area).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import random
+import re
+import sys
+import threading
+from contextlib import contextmanager
+from dataclasses import dataclass, field, replace
+from decimal import ROUND_HALF_UP, Decimal, InvalidOperation
+from pathlib import Path
+from typing import Callable, Iterable, Sequence
+
+import numpy as np
+from PIL import Image, ImageDraw, ImageFilter, ImageFont
+
+HELPERS = Path(__file__).resolve().parent.parent
+if str(HELPERS) not in sys.path:
+    sys.path.insert(0, str(HELPERS))
+from common import FONTS_DIR, SAFE_ZONE_VERTICAL, hex_to_rgb, load_json  # noqa: E402
+
+ENGINE_VERSION = 2            # part of every cache key: bump when drawing changes
+REF = 1080.0                  # design units: the short side of the canvas is 1080
+DEFAULT_ACCENT = "#FFC400"
+DEFAULT_BLEED = 80.0          # design px drawn around the box (shadows, overshoot)
+
+RGBA = tuple  # (r, g, b, a) ints 0-255
+
+
+class MotionError(Exception):
+    """A problem with a PT-BR message. `code` 2 = something to fix in the request, 1 = ffmpeg or disk trouble."""
+
+    def __init__(self, message: str, code: int = 2):
+        super().__init__(message)
+        self.code = code
+
+
+# ============================================================== colors and theme
+
+def _clamp8(v: float) -> int:
+    return int(max(0, min(255, round(v))))
+
+
+def rgba(value, alpha: float | None = None) -> RGBA:
+    """'#RRGGBB' | '#RRGGBBAA' | (r, g, b) | (r, g, b, a) -> (r, g, b, a). `alpha` (0-1) replaces the alpha."""
+    if isinstance(value, str):
+        h = value.strip().lstrip("#")
+        try:
+            if len(h) == 8:
+                r, g, b = hex_to_rgb(h[:6])
+                a = int(h[6:], 16)
+            else:
+                r, g, b = hex_to_rgb(h)
+                a = 255
+        except ValueError:
+            raise MotionError(f"cor inválida: {value!r} (use #RRGGBB)") from None
+    elif isinstance(value, (tuple, list)) and len(value) in (3, 4):
+        r, g, b = (_clamp8(c) for c in value[:3])
+        a = _clamp8(value[3]) if len(value) == 4 else 255
+    else:
+        raise MotionError(f"cor inválida: {value!r} (use #RRGGBB)")
+    if alpha is not None:
+        a = _clamp8(255 * alpha)
+    return (r, g, b, a)
+
+
+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
+
+    return 0.2126 * lin(rgb[0]) + 0.7152 * lin(rgb[1]) + 0.0722 * lin(rgb[2])
+
+
+def readable_on(bg) -> RGBA:
+    """Text color (near-black or white) with the best contrast on a solid color."""
+    lum = luminance(bg)
+    return (17, 17, 17, 255) if (lum + 0.05) / 0.05 >= 1.05 / (lum + 0.05) else (255, 255, 255, 255)
+
+
+def mix_color(a, b, p: float) -> RGBA:
+    a, b = rgba(a), rgba(b)
+    return tuple(_clamp8(x + (y - x) * p) for x, y in zip(a, b))  # type: ignore[return-value]
+
+
+def contrast(a, b) -> float:
+    """WCAG contrast ratio of two solid colors (1 to 21). Below about 2.4 an accent does not read on a card."""
+    la, lb = luminance(rgba(a) if isinstance(a, str) else a), luminance(rgba(b) if isinstance(b, str) else b)
+    return (max(la, lb) + 0.05) / (min(la, lb) + 0.05)
+
+
+@dataclass(frozen=True)
+class Theme:
+    """Palette of one render. `dark` (default) is the glass card of the "vidro" hook; `light` a white card."""
+    name: str
+    accent: RGBA
+    on_accent: RGBA
+    card: RGBA
+    card_border: RGBA
+    text: RGBA
+    muted: RGBA
+    ink: RGBA
+    track: RGBA
+    danger: RGBA
+    success: RGBA
+    shadow: RGBA
+    white: RGBA = (255, 255, 255, 255)
+    black: RGBA = (0, 0, 0, 255)
+    fonts: tuple[tuple[str, str], ...] = ()   # font key -> key the theme draws it with
+    clay: RGBA | None = None                  # papel: the solid "clay" base under every card
+    style: str = "vidro"                      # how card() draws: vidro, papel, pop, neon
+    dark: bool = True                         # dark card (white text): templates pick their greys by it
+
+    def get(self, name: str) -> RGBA:
+        return getattr(self, name)
+
+
+# Looks of the animations. "escuro" and "claro" are the original glass and white cards. The "papel" family is
+# the Vit VSL look (off-white paper card on a solid colored "clay" base, dark ink, Montserrat) in several
+# colors, so it is not only lilac: (clay base, ink, default accent, track, hand font). "pop" is a cream card
+# with a thick black outline and a hard offset shadow (cut-out look); "neon" a dark card with a glowing
+# border in the accent color.
+PAPEL = {
+    "papelaria": ((199, 183, 239), (53, 44, 64), "#665080", (230, 221, 248), "hand"),       # lilás (Vit)
+    "papel_azul": ((169, 199, 242), (31, 42, 68), "#2457C5", (219, 231, 250), "marker"),
+    "papel_verde": ((168, 220, 192), (30, 58, 47), "#1F8A5B", (217, 240, 227), "marker"),
+    "papel_laranja": ((246, 194, 155), (61, 42, 30), "#E0591F", (251, 227, 209), "hand"),
+    "papel_grafite": ((201, 204, 209), (29, 31, 35), "#D6452B", (228, 230, 233), "marker"),
+}
+THEME_NAMES = ("escuro", "claro", *PAPEL, "pop", "neon")
+PAPELARIA_ACCENT = PAPEL["papelaria"][2]
+PAPELARIA_FONTS = (("text_bold", "sans_extrabold"), ("text_semibold", "sans_bold"), ("marker", "hand"),
+                   ("display_condensed", "sans_black"))
+POP_ACCENT, NEON_ACCENT = "#E8412C", "#22D3EE"
+COLOR_NAMES = {  # names a template (or a "color" param) may use instead of #RRGGBB
+    "accent": "accent", "destaque": "accent", "on_accent": "on_accent", "card": "card", "card_border": "card_border",
+    "text": "text", "texto": "text", "muted": "muted", "ink": "ink", "track": "track", "danger": "danger",
+    "perigo": "danger", "vermelho": "danger", "success": "success", "sucesso": "success", "verde": "success",
+    "shadow": "shadow", "white": "white", "branco": "white", "black": "black", "preto": "black",
+}
+
+
+def make_theme(accent=DEFAULT_ACCENT, name: str = "escuro") -> Theme:
+    def own(default: str) -> RGBA:      # the video's accent, or the look's own when the video keeps the default
+        return rgba(default if rgba(accent) == rgba(DEFAULT_ACCENT) else accent)
+
+    if name in PAPEL:
+        clay, ink, acc_default, track, hand = PAPEL[name]
+        acc = own(acc_default)
+        fonts = tuple((k, hand if k == "marker" else v) for k, v in PAPELARIA_FONTS)
+        return Theme(name=name, accent=acc, on_accent=readable_on(acc), card=(255, 253, 253, 250),
+                     card_border=(*clay, 255), text=(*ink, 255), muted=(*ink, 190), ink=(*ink, 255),
+                     track=(*track, 255), danger=(229, 62, 45, 255), success=(46, 158, 91, 255),
+                     shadow=(*ink, 255), fonts=fonts, clay=(*clay, 255), style="papel", dark=False)
+    if name == "pop":
+        acc = own(POP_ACCENT)
+        return Theme(name="pop", accent=acc, on_accent=readable_on(acc), card=(255, 248, 231, 255),
+                     card_border=(17, 17, 17, 255), text=(17, 17, 17, 255), muted=(17, 17, 17, 175),
+                     ink=(17, 17, 17, 255), track=(17, 17, 17, 40), danger=(235, 45, 45, 255),
+                     success=(22, 163, 74, 255), shadow=(17, 17, 17, 255), fonts=PAPELARIA_FONTS[:2] +
+                     (("display_condensed", "sans_black"),), style="pop", dark=False)
+    if name == "neon":
+        acc = own(NEON_ACCENT)
+        return Theme(name="neon", accent=acc, on_accent=readable_on(acc), card=(10, 10, 18, 238),
+                     card_border=acc, text=(255, 255, 255, 255), muted=(255, 255, 255, 190),
+                     ink=(17, 17, 17, 255), track=(255, 255, 255, 38), danger=(255, 69, 58, 255),
+                     success=(52, 211, 104, 255), shadow=(0, 0, 0, 255), style="neon", dark=True)
+    acc = rgba(accent)
+    if name == "claro":
+        return Theme(name="claro", accent=acc, on_accent=readable_on(acc), card=(255, 255, 255, 246),
+                     card_border=(0, 0, 0, 22), text=(17, 17, 17, 255), muted=(17, 17, 17, 165),
+                     ink=(17, 17, 17, 255), track=(17, 17, 17, 34), danger=(235, 45, 45, 255),
+                     success=(22, 163, 74, 255), shadow=(0, 0, 0, 255), dark=False)
+    if name != "escuro":
+        raise MotionError(f"tema '{name}' não existe (use {' ou '.join(THEME_NAMES)})")
+    return Theme(name="escuro", accent=acc, on_accent=readable_on(acc), card=(18, 18, 20, 226),
+                 card_border=(255, 255, 255, 30), text=(255, 255, 255, 255), muted=(255, 255, 255, 196),
+                 ink=(17, 17, 17, 255), track=(255, 255, 255, 44), danger=(255, 69, 58, 255),
+                 success=(52, 211, 104, 255), shadow=(0, 0, 0, 255))
+
+
+# ============================================================== regions and the box
+
+# Named regions on the vertical design canvas (1080x1920): x, y, w, h. They sit inside the platform-safe
+# band (SAFE_ZONE_VERTICAL: top 210, bottom 1550) and clear of the right rail (140 px on each side
+# keeps the content centered and off the like/comment column).
+REGIONS: dict[str, tuple[float, float, float, float]] = {
+    "topo": (140.0, 250.0, 800.0, 520.0),
+    "centro": (140.0, 640.0, 800.0, 640.0),
+    "baixo": (140.0, 1000.0, 800.0, 520.0),
+    "faixa_topo": (90.0, 230.0, 900.0, 300.0),
+    "tela": (90.0, 230.0, 900.0, 1300.0),
+}
+REGION_LABELS = {"topo": "parte de cima", "centro": "meio da tela", "baixo": "parte de baixo",
+                 "faixa_topo": "faixa no alto (notificação)", "tela": "área segura inteira"}
+# English names accepted everywhere a region is given (edit_data.json "motion" uses them)
+REGION_ALIASES = {"top": "topo", "middle": "centro", "center": "centro", "bottom": "baixo", "screen": "tela",
+                  "top_band": "faixa_topo"}
+
+
+def design_size(canvas: Sequence[int]) -> tuple[float, float]:
+    k = min(canvas[0], canvas[1]) / REF
+    return canvas[0] / k, canvas[1] / k
+
+
+def canvas_shape(canvas: Sequence[int]) -> str:
+    w, h = canvas[0], canvas[1]
+    if h > w * 1.05:
+        return "vertical"
+    if w > h * 1.05:
+        return "horizontal"
+    return "square"
+
+
+def safe_area(canvas: Sequence[int] = (1080, 1920)) -> tuple[float, float, float, float]:
+    """(x0, y0, x1, y1) in design px where content is safe from the platform UI."""
+    dw, dh = design_size(canvas)
+    if canvas_shape(canvas) == "vertical":
+        top = SAFE_ZONE_VERTICAL["top"] * dh / 1920.0
+        bottom = SAFE_ZONE_VERTICAL["bottom"] * dh / 1920.0
+        return 90.0, top, dw - 90.0, bottom
+    return 0.05 * dw, 0.06 * dh, 0.95 * dw, 0.94 * dh
+
+
+def region_box(spec, canvas: Sequence[int] = (1080, 1920)) -> tuple[float, float, float, float]:
+    """A named region or [x, y, w, h] (design px of a vertical 1080x1920 canvas) -> (x, y, w, h) on `canvas`.
+
+    Named regions keep their place relative to the safe area on horizontal and square canvases."""
+    dw, dh = design_size(canvas)
+    if isinstance(spec, dict) and set(spec) == {"x", "y", "w", "h"}:
+        spec = [spec["x"], spec["y"], spec["w"], spec["h"]]
+    if isinstance(spec, str):
+        spec = REGION_ALIASES.get(spec.strip().lower(), spec.strip().lower())
+        if spec not in REGIONS:
+            raise MotionError(f"região '{spec}' não existe (use {', '.join(REGIONS)} ou [x, y, largura, altura])")
+        x, y, w, h = REGIONS[spec]
+        if canvas_shape(canvas) == "vertical":
+            return x, y * dh / 1920.0, w, h * dh / 1920.0
+        sx0, sy0, sx1, sy1 = safe_area(canvas)
+        v0, v1 = REGIONS["tela"][1], REGIONS["tela"][1] + REGIONS["tela"][3]
+        fy0 = (y - v0) / (v1 - v0)
+        fy1 = (y + h - v0) / (v1 - v0)
+        ww = min(w, sx1 - sx0)
+        return (dw - ww) / 2.0, sy0 + fy0 * (sy1 - sy0), ww, (fy1 - fy0) * (sy1 - sy0)
+    try:
+        x, y, w, h = (float(v) for v in spec)
+    except (TypeError, ValueError):
+        raise MotionError(f"região inválida: {spec!r} (use um nome ou [x, y, largura, altura])") from None
+    if not all(math.isfinite(v) for v in (x, y, w, h)) or w < 20 or h < 20:
+        raise MotionError(f"região inválida: {spec!r} (largura e altura de pelo menos 20)")
+    if x + w <= 0 or y + h <= 0 or x >= dw or y >= dh:
+        raise MotionError(f"região {spec!r} fica fora da tela ({dw:.0f}x{dh:.0f})")
+    return x, y, w, h
+
+
+@dataclass(frozen=True)
+class Box:
+    """Where and how one template instance is drawn. Geometry in design px of the output canvas."""
+    x: float
+    y: float
+    w: float
+    h: float
+    scale: float = 1.0                    # render px per design px
+    canvas: tuple[int, int] = (1080, 1920)  # render canvas in px
+    fps: int = 30
+    frames: int = 90                      # length of the item on screen
+    theme: Theme = field(default_factory=make_theme)
+    bleed: float = DEFAULT_BLEED
+
+    @property
+    def cx(self) -> float:                # box-local center
+        return self.w / 2.0
+
+    @property
+    def cy(self) -> float:
+        return self.h / 2.0
+
+    @property
+    def duration(self) -> float:
+        return self.frames / float(self.fps)
+
+    @property
+    def accent(self) -> RGBA:
+        return self.theme.accent
+
+    @property
+    def design(self) -> tuple[float, float]:
+        return design_size(self.canvas)
+
+    @property
+    def safe(self) -> tuple[float, float, float, float]:
+        """Safe area in BOX-LOCAL design px (x0, y0, x1, y1)."""
+        x0, y0, x1, y1 = safe_area(self.canvas)
+        return x0 - self.x, y0 - self.y, x1 - self.x, y1 - self.y
+
+    def to_canvas(self, u: float, v: float) -> tuple[float, float]:
+        """Box-local design point -> design point on the whole canvas."""
+        return self.x + u, self.y + v
+
+    def from_canvas(self, x: float, y: float) -> tuple[float, float]:
+        """Canvas design point (e.g. a target in 1080x1920) -> box-local design point."""
+        return x - self.x, y - self.y
+
+
+def make_box(region, canvas: Sequence[int] = (1080, 1920), fps: int = 30, frames: int = 90,
+             accent=DEFAULT_ACCENT, theme: str = "escuro", bleed: float = DEFAULT_BLEED) -> Box:
+    canvas = (int(canvas[0]), int(canvas[1]))
+    x, y, w, h = region_box(region, canvas)
+    return Box(x=x, y=y, w=w, h=h, scale=min(canvas) / REF, canvas=canvas, fps=int(fps), frames=int(frames),
+               theme=make_theme(accent, theme), bleed=float(bleed))
+
+
+# ============================================================== easing
+
+def clamp01(x: float) -> float:
+    return 0.0 if x <= 0.0 else 1.0 if x >= 1.0 else float(x)
+
+
+def lerp(a: float, b: float, p: float) -> float:
+    return a + (b - a) * p
+
+
+def remap(x: float, a0: float, a1: float, b0: float = 0.0, b1: float = 1.0, clamp: bool = True) -> float:
+    p = (x - a0) / (a1 - a0) if a1 != a0 else (1.0 if x >= a1 else 0.0)
+    if clamp:
+        p = clamp01(p)
+    return b0 + (b1 - b0) * p
+
+
+def linear(t: float) -> float:
+    return clamp01(t)
+
+
+def in_quad(t: float) -> float:
+    t = clamp01(t)
+    return t * t
+
+
+def out_quad(t: float) -> float:
+    t = clamp01(t)
+    return 1 - (1 - t) * (1 - t)
+
+
+def in_out_quad(t: float) -> float:
+    t = clamp01(t)
+    return 2 * t * t if t < 0.5 else 1 - (-2 * t + 2) ** 2 / 2
+
+
+def in_cubic(t: float) -> float:
+    return clamp01(t) ** 3
+
+
+def out_cubic(t: float) -> float:
+    return 1 - (1 - clamp01(t)) ** 3
+
+
+def in_out_cubic(t: float) -> float:
+    t = clamp01(t)
+    return 4 * t ** 3 if t < 0.5 else 1 - (-2 * t + 2) ** 3 / 2
+
+
+def out_quart(t: float) -> float:
+    return 1 - (1 - clamp01(t)) ** 4
+
+
+def out_quint(t: float) -> float:
+    return 1 - (1 - clamp01(t)) ** 5
+
+
+def out_expo(t: float) -> float:
+    t = clamp01(t)
+    if t >= 1.0:
+        return 1.0
+    # normalized so out_expo(1) == 1 exactly
+    return (1 - 2 ** (-10 * t)) / (1 - 2 ** -10)
+
+
+def in_out_sine(t: float) -> float:
+    return 0.5 - 0.5 * math.cos(math.pi * clamp01(t))
+
+
+def out_sine(t: float) -> float:
+    return math.sin(math.pi / 2 * clamp01(t))
+
+
+def out_back(t: float, overshoot: float = 1.70158) -> float:
+    t = clamp01(t) - 1.0
+    return 1 + (overshoot + 1) * t ** 3 + overshoot * t ** 2
+
+
+def in_back(t: float, overshoot: float = 1.70158) -> float:
+    t = clamp01(t)
+    return (overshoot + 1) * t ** 3 - overshoot * t ** 2
+
+
+def out_elastic(t: float) -> float:
+    t = clamp01(t)
+    if t in (0.0, 1.0):
+        return t
+    return 2 ** (-10 * t) * math.sin((t * 10 - 0.75) * (2 * math.pi / 3)) + 1
+
+
+def out_bounce(t: float) -> float:
+    t = clamp01(t)
+    n1, d1 = 7.5625, 2.75
+    if t < 1 / d1:
+        return n1 * t * t
+    if t < 2 / d1:
+        t -= 1.5 / d1
+        return n1 * t * t + 0.75
+    if t < 2.5 / d1:
+        t -= 2.25 / d1
+        return n1 * t * t + 0.9375
+    t -= 2.625 / d1
+    return n1 * t * t + 0.984375
+
+
+def spring(t: float, damping: float = 0.5, frequency: float = 2.2) -> float:
+    """Damped spring from 0 to 1. `t` in SECONDS since the start, `frequency` in Hz, `damping` 0-1
+    (0.3 bouncy, 0.5 lively, 0.8 soft, 1 no overshoot). spring(0) == 0; it settles on 1."""
+    if t <= 0:
+        return 0.0
+    w0 = 2 * math.pi * frequency
+    z = min(max(damping, 0.01), 1.0)
+    if z >= 0.999:
+        return 1 - math.exp(-w0 * t) * (1 + w0 * t)
+    wd = w0 * math.sqrt(1 - z * z)
+    return 1 - math.exp(-z * w0 * t) * (math.cos(wd * t) + z * w0 / wd * math.sin(wd * t))
+
+
+def spring_settle(damping: float = 0.5, frequency: float = 2.2, tolerance: float = 0.002) -> float:
+    """Seconds until the spring stays within `tolerance` of 1 (envelope bound)."""
+    w0 = 2 * math.pi * frequency
+    z = min(max(damping, 0.01), 1.0)
+    if z >= 0.999:
+        t = 0.0
+        while abs(1 - spring(t, damping, frequency)) > tolerance and t < 30:
+            t += 0.005
+        return t
+    return math.log(1.0 / (tolerance * math.sqrt(1 - z * z))) / (z * w0)
+
+
+EASINGS: dict[str, Callable[[float], float]] = {
+    "linear": linear, "in_quad": in_quad, "out_quad": out_quad, "in_out_quad": in_out_quad,
+    "in_cubic": in_cubic, "out_cubic": out_cubic, "in_out_cubic": in_out_cubic, "out_quart": out_quart,
+    "out_quint": out_quint, "out_expo": out_expo, "in_out_sine": in_out_sine, "out_sine": out_sine,
+    "out_back": out_back, "in_back": in_back, "out_elastic": out_elastic, "out_bounce": out_bounce,
+}
+
+
+def ease(name_or_fn, t: float) -> float:
+    fn = EASINGS[name_or_fn] if isinstance(name_or_fn, str) else name_or_fn
+    return fn(t)
+
+
+# ============================================================== timing
+
+def seconds(frame_index: int, fps: float) -> float:
+    return frame_index / float(fps)
+
+
+def frame_of(t: float, fps: float) -> int:
+    """Seconds -> frame with the same rounding compose_final uses (Plan.fr)."""
+    return int(round(float(t) * fps + 1e-6))
+
+
+def progress(t: float, start: float, duration: float) -> float:
+    """0 before `start`, 1 after `start + duration`, linear in between."""
+    if duration <= 0:
+        return 1.0 if t >= start else 0.0
+    return clamp01((t - start) / duration)
+
+
+def eased(t: float, start: float, duration: float, fn="out_cubic") -> float:
+    return ease(fn, progress(t, start, duration))
+
+
+def stagger(index: int, step: float, start: float = 0.0) -> float:
+    """Start time of the index-th element of a list that enters one by one."""
+    return start + index * step
+
+
+def keyframes(t: float, keys: Sequence[tuple[float, float]], fn="in_out_cubic") -> float:
+    """Value at time t from [(time, value), ...] (sorted), eased between neighbours; held outside."""
+    if not keys:
+        return 0.0
+    if t <= keys[0][0]:
+        return float(keys[0][1])
+    for (t0, v0), (t1, v1) in zip(keys, keys[1:]):
+        if t <= t1:
+            return v0 + (v1 - v0) * ease(fn, (t - t0) / (t1 - t0) if t1 > t0 else 1.0)
+    return float(keys[-1][1])
+
+
+def pulse(t: float, start: float, duration: float) -> float:
+    """0 -> 1 -> 0 (half sine) inside [start, start + duration]."""
+    p = progress(t, start, duration)
+    return math.sin(math.pi * p) if 0 < p < 1 else 0.0
+
+
+def stable_seed(*parts) -> int:
+    return int.from_bytes(hashlib.sha1(repr(parts).encode("utf-8")).digest()[:8], "big")
+
+
+def rng(*parts) -> random.Random:
+    """Deterministic random generator for one purpose (never the global one)."""
+    return random.Random(stable_seed(*parts))
+
+
+def shake(t: float, start: float, duration: float, amplitude: float = 14.0, frequency: float = 18.0,
+          seed=0) -> tuple[float, float]:
+    """Decaying pseudo-random shake (dx, dy) in design px, deterministic by `seed`."""
+    p = progress(t, start, duration)
+    if p <= 0 or p >= 1:
+        return 0.0, 0.0
+    r = rng("shake", seed)
+    ph = [r.uniform(0, 2 * math.pi) for _ in range(4)]
+    env = (1 - p) ** 2
+    tt = (t - start) * 2 * math.pi * frequency
+    dx = math.sin(tt + ph[0]) * 0.7 + math.sin(tt * 1.7 + ph[1]) * 0.3
+    dy = math.sin(tt * 1.3 + ph[2]) * 0.7 + math.sin(tt * 2.1 + ph[3]) * 0.3
+    return amplitude * env * dx, amplitude * env * dy
+
+
+def typewriter(text: str, t: float, start: float, chars_per_second: float = 14.0) -> str:
+    n = int(math.floor(max(0.0, t - start) * chars_per_second + 1e-6))
+    return text[:max(0, min(len(text), n))]
+
+
+# ============================================================== paths
+
+Point = tuple[float, float]
+
+
+def path_length(points: Sequence[Point]) -> float:
+    return sum(math.dist(a, b) for a, b in zip(points, points[1:]))
+
+
+def trim_points(points: Sequence[Point], start: float = 0.0, end: float = 1.0) -> list[Point]:
+    """The part of a polyline between two fractions of its length (for drawing it by progress)."""
+    pts = [tuple(map(float, p)) for p in points]
+    if len(pts) < 2:
+        return list(pts)
+    start, end = clamp01(start), clamp01(end)
+    if end <= start:
+        return []
+    total = path_length(pts)
+    if total <= 0:
+        return [pts[0], pts[0]]
+    a, b = start * total, end * total
+    out: list[Point] = []
+    run = 0.0
+    for p, q in zip(pts, pts[1:]):
+        seg = math.dist(p, q)
+        s0, s1 = run, run + seg
+        run = s1
+        if s1 < a or seg <= 0:
+            continue
+        if s0 > b:
+            break
+        u0 = max(0.0, (a - s0) / seg)
+        u1 = min(1.0, (b - s0) / seg)
+        p0 = (p[0] + (q[0] - p[0]) * u0, p[1] + (q[1] - p[1]) * u0)
+        p1 = (p[0] + (q[0] - p[0]) * u1, p[1] + (q[1] - p[1]) * u1)
+        if not out:
+            out.append(p0)
+        out.append(p1)
+    if len(out) == 1:
+        out.append(out[0])
+    return out
+
+
+def point_at(points: Sequence[Point], fraction: float) -> tuple[Point, float]:
+    """(point, direction angle in radians) at a fraction of the polyline length."""
+    pts = trim_points(points, 0.0, max(1e-6, clamp01(fraction)))
+    if len(pts) < 2:
+        return (tuple(points[0]) if points else (0.0, 0.0)), 0.0
+    (x0, y0), (x1, y1) = pts[-2], pts[-1]
+    if (x0, y0) == (x1, y1) and len(points) >= 2:
+        (x0, y0), (x1, y1) = points[0], points[1]
+    return pts[-1], math.atan2(y1 - y0, x1 - x0)
+
+
+def bezier_points(p0: Point, p1: Point, p2: Point, p3: Point | None = None, n: int = 32) -> list[Point]:
+    """Quadratic (3 points) or cubic (4 points) Bezier sampled into n+1 points."""
+    out = []
+    for i in range(n + 1):
+        u = i / n
+        if p3 is None:
+            x = (1 - u) ** 2 * p0[0] + 2 * (1 - u) * u * p1[0] + u * u * p2[0]
+            y = (1 - u) ** 2 * p0[1] + 2 * (1 - u) * u * p1[1] + u * u * p2[1]
+        else:
+            x = ((1 - u) ** 3 * p0[0] + 3 * (1 - u) ** 2 * u * p1[0] + 3 * (1 - u) * u * u * p2[0] + u ** 3 * p3[0])
+            y = ((1 - u) ** 3 * p0[1] + 3 * (1 - u) ** 2 * u * p1[1] + 3 * (1 - u) * u * u * p2[1] + u ** 3 * p3[1])
+        out.append((x, y))
+    return out
+
+
+def ellipse_points(cx: float, cy: float, rx: float, ry: float, start_deg: float = -90.0, sweep_deg: float = 360.0,
+                   n: int | None = None, wobble: float = 0.0, seed=0) -> list[Point]:
+    """Points on an ellipse (clockwise on screen), optionally hand-drawn: `wobble` = radius noise as a
+    fraction, and a sweep over 360 overlaps the start like a marker circle."""
+    if n is None:
+        n = max(24, int(abs(sweep_deg) / 6))
+    r = rng("ellipse", seed)
+    harm = [(r.uniform(0.6, 1.0), r.uniform(0, 2 * math.pi), k) for k in (2, 3, 5)]
+    out = []
+    for i in range(n + 1):
+        u = i / n
+        a = math.radians(start_deg + sweep_deg * u)
+        k = 1.0
+        if wobble:
+            k += wobble * sum(amp * math.sin(kk * a + ph) for amp, ph, kk in harm) / 2.2
+            k += wobble * 0.6 * u      # the end drifts outwards, like a pen that overshoots
+        out.append((cx + rx * k * math.cos(a), cy + ry * k * math.sin(a)))
+    return out
+
+
+def wobble_points(points: Sequence[Point], amount: float, seed=0, step: float = 18.0) -> list[Point]:
+    """Resample a polyline every `step` px and nudge it sideways (hand-drawn look), deterministic."""
+    total = path_length(points)
+    if total <= 0 or amount <= 0:
+        return [tuple(p) for p in points]
+    n = max(2, int(total / step))
+    r = rng("wobble", seed)
+    ph1, ph2 = r.uniform(0, 6.28), r.uniform(0, 6.28)
+    out = []
+    for i in range(n + 1):
+        (x, y), ang = point_at(points, i / n)
+        off = amount * (0.65 * math.sin(i * 0.9 + ph1) + 0.35 * math.sin(i * 2.3 + ph2))
+        out.append((x - math.sin(ang) * off, y + math.cos(ang) * off))
+    return out
+
+
+# ============================================================== numbers (Brazilian style)
+
+def auto_decimals(value: float, max_decimals: int = 2) -> int:
+    """0 for whole numbers, else up to max_decimals (1.5 -> 1, 1904152.87 -> 2)."""
+    try:
+        d = Decimal(repr(float(value))).normalize()
+    except (InvalidOperation, ValueError):
+        return 0
+    exp = d.as_tuple().exponent
+    return 0 if not isinstance(exp, int) or exp >= 0 else min(max_decimals, -exp)
+
+
+def format_number(value: float, decimals: int = 0, thousands: str = ".", decimal: str = ",") -> str:
+    """1904152.87 -> '1.904.152,87' (half-up rounding, no '-0')."""
+    decimals = max(0, int(decimals))
+    try:
+        d = Decimal(repr(float(value)))
+    except (InvalidOperation, ValueError):
+        raise MotionError(f"número inválido: {value!r}") from None
+    if not d.is_finite():
+        raise MotionError(f"número inválido: {value!r}")
+    q = d.quantize(Decimal(1).scaleb(-decimals), rounding=ROUND_HALF_UP)
+    neg = q < 0
+    q = abs(q)
+    whole, _, frac = f"{q:f}".partition(".")
+    groups = []
+    while len(whole) > 3:
+        groups.insert(0, whole[-3:])
+        whole = whole[:-3]
+    groups.insert(0, whole)
+    out = thousands.join(groups)
+    if decimals:
+        out += decimal + frac.ljust(decimals, "0")[:decimals]
+    if neg and any(c not in "0.," for c in out):
+        out = "-" + out
+    return out
+
+
+MONEY_SYMBOLS = ("R$", "US$", "$", "€", "£")
+
+
+def looks_like_money(*texts: str) -> bool:
+    """True when a prefix or suffix is a currency (R$, US$, $, €, £): counters then show cents when they have them."""
+    return any(sym in str(t) for t in texts for sym in MONEY_SYMBOLS)
+
+
+def format_money(value: float, decimals: int = 2, prefix: str = "R$ ") -> str:
+    s = format_number(value, decimals)
+    if s.startswith("-"):
+        return "-" + prefix + s[1:]
+    return prefix + s
+
+
+def format_percent(value: float, decimals: int = 0) -> str:
+    return format_number(value, decimals) + "%"
+
+
+_COMPACT_UNITS = ((1.0, ""), (1e3, "mil"), (1e6, "mi"), (1e9, "bi"), (1e12, "tri"))
+
+
+def _compact_unit(v: float, decimals: int) -> int:
+    k = max(i for i, (limit, _) in enumerate(_COMPACT_UNITS) if i == 0 or abs(v) >= limit)
+    while k + 1 < len(_COMPACT_UNITS):
+        d = auto_decimals(v, decimals) if k == 0 else decimals
+        shown = format_number(abs(v) / _COMPACT_UNITS[k][0], d)
+        if len(shown.split(",")[0].replace(".", "")) < 4:      # rounding did not reach 1000 of this unit
+            break
+        k += 1
+    return k
+
+
+def format_compact(value: float, decimals: int = 1, like: float | None = None) -> str:
+    """12500 -> '12,5 mil', 1904152 -> '1,9 mi', 2.4e9 -> '2,4 bi', 999999.99 -> '1 mi' (never '1.000 mil').
+    `like` = use the unit of that other number (a count keeps the unit of its final value: '0,4 mi' -> '1,9 mi')."""
+    v = float(value)
+    k = _compact_unit(float(like) if like is not None else v, decimals)
+    if k == 0:
+        return format_number(v, auto_decimals(v, decimals))
+    limit, word = _COMPACT_UNITS[k]
+    s = format_number(v / limit, decimals)
+    if "," in s:
+        s = s.rstrip("0").rstrip(",")
+    return f"{s} {word}"
+
+
+# ============================================================== fonts and text metrics
+
+_tls = threading.local()
+_FONT_MANIFEST: dict | None = None
+
+
+def font_keys() -> list[str]:
+    return sorted(_manifest())
+
+
+def _manifest() -> dict:
+    global _FONT_MANIFEST
+    if _FONT_MANIFEST is None:
+        _FONT_MANIFEST = load_json(FONTS_DIR / "fonts.json", default={}) or {}
+    return _FONT_MANIFEST
+
+
+@contextmanager
+def theme_fonts(theme: "Theme"):
+    """While drawing or measuring an item, font keys resolve through its theme (papelaria swaps them)."""
+    prev = getattr(_tls, "font_map", None)
+    _tls.font_map = dict(theme.fonts) if theme.fonts else None
+    try:
+        yield
+    finally:
+        _tls.font_map = prev
+
+
+def font(key: str, size: float) -> ImageFont.FreeTypeFont:
+    """Bundled font (assets/fonts/fonts.json key) at a float pixel size, cached per thread."""
+    fmap = getattr(_tls, "font_map", None)
+    if fmap:
+        key = fmap.get(key, key)
+    cache = getattr(_tls, "fonts", None)
+    if cache is None:
+        cache = _tls.fonts = {}
+    px = max(4.0, round(float(size) * 8) / 8)
+    f = cache.get((key, px))
+    if f is None:
+        entry = _manifest().get(key)
+        if not entry:
+            raise MotionError(f"fonte '{key}' não existe (use {', '.join(font_keys())})")
+        f = ImageFont.truetype(str(FONTS_DIR / entry["file"]), size=px)
+        if entry.get("variation") is not None:
+            try:
+                f.set_variation_by_axes([entry["variation"]])
+            except Exception:  # noqa: BLE001  (a static build of the font: keep its default weight)
+                pass
+        if len(cache) > 512:
+            cache.clear()
+        cache[(key, px)] = f
+    return f
+
+
+@dataclass(frozen=True)
+class TextMetrics:
+    width: float        # advance width (design px)
+    cap: float          # cap height
+    ascent: float
+    descent: float
+    x_height: float
+
+
+def _digit_cell(f: ImageFont.FreeTypeFont) -> float:
+    return max(f.getlength(d) for d in "0123456789")
+
+
+def _advance(f: ImageFont.FreeTypeFont, text: str, tabular: bool, tracking: float) -> float:
+    if not tabular and not tracking:
+        return f.getlength(text)
+    cell = _digit_cell(f) if tabular else 0.0
+    w = sum(cell if (tabular and ch.isdigit()) else f.getlength(ch) for ch in text)
+    return w + tracking * max(0, len(text) - 1)
+
+
+def measure(text: str, font_key: str = "sans_black", size: float = 64.0, tabular: bool = False,
+            tracking: float = 0.0) -> TextMetrics:
+    """Metrics in design px (size is in design px too) of the text as the Canvas draws it."""
+    text = clean_text(text, font_key)
+    f = font(font_key, size)
+    cap = -f.getbbox("H", anchor="ls")[1]
+    xh = -f.getbbox("x", anchor="ls")[1]
+    asc, desc = f.getmetrics()
+    return TextMetrics(width=_advance(f, text, tabular, tracking * 1.0), cap=float(cap), ascent=float(asc),
+                       descent=float(desc), x_height=float(xh))
+
+
+def clean_text(text: str, font_key: str) -> str:
+    """Characters the font cannot draw (emoji...) become a look-alike or go away (text_render rules)."""
+    try:
+        import text_render as tr  # noqa: PLC0415
+        fmap = getattr(_tls, "font_map", None)
+        return tr.sanitize_text(str(text), fmap.get(font_key, font_key) if fmap else font_key)[0]
+    except Exception:  # noqa: BLE001
+        return str(text)
+
+
+def fit_text(text: str, font_key: str, max_width: float, max_size: float, min_size: float = 12.0,
+             tabular: bool = False, tracking: float = 0.0) -> float:
+    """Largest size (<= max_size, >= min_size) whose advance fits max_width."""
+    w = measure(text, font_key, max_size, tabular, tracking).width
+    if w <= max_width or w <= 0:
+        return float(max_size)
+    size = max_size * max_width / w
+    for _ in range(4):
+        w = measure(text, font_key, size, tabular, tracking).width
+        if w <= max_width:
+            break
+        size *= max_width / w * 0.995
+    return float(max(min_size, size))
+
+
+def wrap_text(text: str, font_key: str, size: float, max_width: float, max_lines: int = 2) -> list[str]:
+    """Balanced lines (the widest line as short as possible), at most max_lines; words never split."""
+    words = str(text).split()
+    if not words:
+        return []
+    f = font(font_key, size)
+
+    def width(ws):
+        return f.getlength(" ".join(ws))
+
+    if width(words) <= max_width or max_lines <= 1:
+        return [" ".join(words)]
+    best = None
+    n = len(words)
+
+    def splits(start, lines_left):
+        if lines_left == 1:
+            yield [words[start:]]
+            return
+        for cut in range(start + 1, n - lines_left + 2):
+            for rest in splits(cut, lines_left - 1):
+                yield [words[start:cut]] + rest
+
+    for count in range(2, min(max_lines, n) + 1):
+        for parts in splits(0, count):
+            widest = max(width(p) for p in parts)
+            score = (widest > max_width, widest, count)
+            if best is None or score < best[0]:
+                best = (score, parts)
+        if best and not best[0][0]:
+            break
+    return [" ".join(p) for p in best[1]] if best else [" ".join(words)]
+
+
+def parse_accent(text: str) -> list[tuple[str, bool]]:
+    """'Compra. *Conecta.* Usa.' -> [('Compra.', False), ('Conecta.', True), ('Usa.', False)] (per word;
+    a word touched by the markup is accented whole; '\\*' is a real asterisk)."""
+    out = []
+    on = False
+    for raw in re.split(r"(\s+)", str(text)):
+        if not raw or raw.isspace():
+            continue
+        word, touched = [], False
+        i = 0
+        while i < len(raw):
+            ch = raw[i]
+            if ch == "\\" and i + 1 < len(raw) and raw[i + 1] == "*":
+                word.append("*")
+                i += 2
+                continue
+            if ch == "*":
+                on = not on
+                touched = True
+                i += 1
+                continue
+            if on:
+                touched = True
+            word.append(ch)
+            i += 1
+        if word:
+            out.append(("".join(word), touched))
+    return out
+
+
+# ============================================================== rasterizing helpers (render px)
+
+def _grid(x0: float, y0: float, x1: float, y1: float, W: int, H: int, pad: int = 2):
+    ix0, iy0 = max(0, int(math.floor(x0)) - pad), max(0, int(math.floor(y0)) - pad)
+    ix1, iy1 = min(W, int(math.ceil(x1)) + pad), min(H, int(math.ceil(y1)) + pad)
+    if ix1 <= ix0 or iy1 <= iy0:
+        return None
+    xs = np.arange(ix0, ix1, dtype=np.float32) + 0.5
+    ys = np.arange(iy0, iy1, dtype=np.float32) + 0.5
+    return ix0, iy0, xs[None, :], ys[:, None]
+
+
+def _coverage(d: np.ndarray) -> np.ndarray:
+    """Signed distance (px, negative inside) -> coverage 0..1 (1 px wide anti-aliased edge)."""
+    return np.clip(0.5 - d, 0.0, 1.0)
+
+
+def _rrect_sd(px, py, x0, y0, x1, y1, r):
+    cx, cy = (x0 + x1) / 2.0, (y0 + y1) / 2.0
+    hx, hy = (x1 - x0) / 2.0 - r, (y1 - y0) / 2.0 - r
+    qx = np.abs(px - cx) - hx
+    qy = np.abs(py - cy) - hy
+    outside = np.sqrt(np.maximum(qx, 0) ** 2 + np.maximum(qy, 0) ** 2)
+    inside = np.minimum(np.maximum(qx, qy), 0)
+    return outside + inside - r
+
+
+def _seg_dist(px, py, ax, ay, bx, by):
+    vx, vy = bx - ax, by - ay
+    l2 = vx * vx + vy * vy
+    wx, wy = px - ax, py - ay
+    if l2 <= 1e-12:
+        return np.sqrt(wx * wx + wy * wy)
+    t = np.clip((wx * vx + wy * vy) / l2, 0.0, 1.0)
+    dx, dy = wx - t * vx, wy - t * vy
+    return np.sqrt(dx * dx + dy * dy)
+
+
+def _inset_convex(pts: list[Point], r: float) -> list[Point] | None:
+    """A convex polygon moved inwards by r (None when it would vanish)."""
+    n = len(pts)
+    area = sum(pts[i][0] * pts[(i + 1) % n][1] - pts[(i + 1) % n][0] * pts[i][1] for i in range(n)) / 2.0
+    if abs(area) < 1e-9:
+        return None
+    sign = 1.0 if area > 0 else -1.0
+    lines = []
+    for i in range(n):
+        (ax, ay), (bx, by) = pts[i], pts[(i + 1) % n]
+        dx, dy = bx - ax, by - ay
+        ln = math.hypot(dx, dy)
+        if ln < 1e-9:
+            continue
+        nx, ny = -dy / ln * sign, dx / ln * sign        # inward normal
+        lines.append((ax + nx * r, ay + ny * r, dx, dy))
+    out = []
+    for (ax, ay, adx, ady), (bx, by, bdx, bdy) in zip(lines, lines[1:] + lines[:1]):
+        den = adx * bdy - ady * bdx
+        if abs(den) < 1e-12:
+            continue
+        t = ((bx - ax) * bdy - (by - ay) * bdx) / den
+        out.append((ax + adx * t, ay + ady * t))
+    if len(out) < 3:
+        return None
+    new_area = sum(out[i][0] * out[(i + 1) % len(out)][1] - out[(i + 1) % len(out)][0] * out[i][1]
+                   for i in range(len(out))) / 2.0
+    if new_area * area <= 0 or abs(new_area) < 1.0:
+        return None
+    return out
+
+
+@dataclass
+class Mask:
+    """Coverage (float32 0..1) placed at integer render px (x, y)."""
+    a: np.ndarray
+    x: int
+    y: int
+
+    @property
+    def bbox(self):
+        return self.x, self.y, self.x + self.a.shape[1], self.y + self.a.shape[0]
+
+
+def blur_mask(m: Mask, radius: float, W: int, H: int) -> Mask:
+    """Gaussian-blurred copy of a mask (grown by 3 radii), computed at half resolution for big radii."""
+    if radius < 0.5:
+        return m
+    pad = int(math.ceil(radius * 3)) + 2
+    x0, y0 = max(0, m.x - pad), max(0, m.y - pad)
+    x1, y1 = min(W, m.x + m.a.shape[1] + pad), min(H, m.y + m.a.shape[0] + pad)
+    if x1 <= x0 or y1 <= y0:
+        return Mask(np.zeros((1, 1), np.float32), 0, 0)
+    buf = np.zeros((y1 - y0, x1 - x0), np.float32)
+    # the mask may pass the canvas edge (a word scaled up near the border): copy only the part inside
+    sx0, sy0 = max(m.x, x0), max(m.y, y0)
+    sx1, sy1 = min(m.x + m.a.shape[1], x1), min(m.y + m.a.shape[0], y1)
+    if sx1 <= sx0 or sy1 <= sy0:
+        return Mask(np.zeros((1, 1), np.float32), 0, 0)
+    buf[sy0 - y0:sy1 - y0, sx0 - x0:sx1 - x0] = m.a[sy0 - m.y:sy1 - m.y, sx0 - m.x:sx1 - m.x]
+    img = Image.fromarray(np.clip(buf * 255.0 + 0.5, 0, 255).astype(np.uint8), "L")
+    if radius >= 6:
+        small = img.resize((max(1, img.width // 2), max(1, img.height // 2)), Image.BILINEAR)
+        small = small.filter(ImageFilter.GaussianBlur(radius / 2.0))
+        img = small.resize(img.size, Image.BILINEAR)
+    else:
+        img = img.filter(ImageFilter.GaussianBlur(radius))
+    return Mask(np.asarray(img, np.float32) / 255.0, x0, y0)
+
+
+def clip_mask(m: Mask | None, x0: float | None = None, x1: float | None = None, y0: float | None = None,
+              y1: float | None = None) -> Mask | None:
+    """The part of a mask inside render-px limits (any of them may be None), with partial coverage on the cut
+    lines. A bar rounded on its free end and flat on the axis is a rounded rect cut at the axis."""
+    if m is None:
+        return None
+    a = m.a
+    if x0 is not None or x1 is not None:
+        cols = np.arange(a.shape[1], dtype=np.float32) + m.x
+        k = np.ones_like(cols)
+        if x0 is not None:
+            k *= np.clip(cols + 1.0 - x0, 0.0, 1.0)
+        if x1 is not None:
+            k *= np.clip(x1 - cols, 0.0, 1.0)
+        a = a * k[None, :]
+    if y0 is not None or y1 is not None:
+        rows = np.arange(a.shape[0], dtype=np.float32) + m.y
+        k = np.ones_like(rows)
+        if y0 is not None:
+            k *= np.clip(rows + 1.0 - y0, 0.0, 1.0)
+        if y1 is not None:
+            k *= np.clip(y1 - rows, 0.0, 1.0)
+        a = a * k[:, None]
+    if not a.any():
+        return None
+    return Mask(a, m.x, m.y)
+
+
+def union_masks(masks: Iterable[Mask | None]) -> Mask | None:
+    """Union (the highest coverage) of several masks, e.g. a scalloped seal made of circles."""
+    ms = [m for m in masks if m is not None]
+    if not ms:
+        return None
+    x0 = min(m.x for m in ms)
+    y0 = min(m.y for m in ms)
+    x1 = max(m.x + m.a.shape[1] for m in ms)
+    y1 = max(m.y + m.a.shape[0] for m in ms)
+    out = np.zeros((y1 - y0, x1 - x0), np.float32)
+    for m in ms:
+        sub = out[m.y - y0:m.y - y0 + m.a.shape[0], m.x - x0:m.x - x0 + m.a.shape[1]]
+        np.maximum(sub, m.a, out=sub)
+    return Mask(out, x0, y0)
+
+
+def intersect_masks(a: Mask | None, b: Mask | None) -> Mask | None:
+    """Coverage inside both masks (clips a shape to another, e.g. a silhouette to its round avatar)."""
+    if a is None or b is None:
+        return None
+    x0, y0 = max(a.x, b.x), max(a.y, b.y)
+    x1 = min(a.x + a.a.shape[1], b.x + b.a.shape[1])
+    y1 = min(a.y + a.a.shape[0], b.y + b.a.shape[0])
+    if x1 <= x0 or y1 <= y0:
+        return None
+    return Mask(a.a[y0 - a.y:y1 - a.y, x0 - a.x:x1 - a.x] * b.a[y0 - b.y:y1 - b.y, x0 - b.x:x1 - b.x], x0, y0)
+
+
+# Masks and blurred shadows of plain shapes, reused while a card stands still (a card's shadow blur is
+# 10-20 ms at 1080x1920). Keyed by the exact render-px geometry; the arrays are read-only.
+_MASK_CACHE: "dict[tuple, Mask]" = {}
+_MASK_CACHE_LOCK = threading.Lock()
+_MASK_CACHE_MAX = 96
+
+
+def _cached_mask(key: tuple, make: Callable[[], "Mask | None"]) -> "Mask | None":
+    with _MASK_CACHE_LOCK:
+        hit = _MASK_CACHE.get(key)
+        if hit is not None:
+            _MASK_CACHE[key] = _MASK_CACHE.pop(key)          # most recent last
+            return Mask(hit.a, hit.x, hit.y)
+    m = make()
+    if m is None:
+        return None
+    m.a.flags.writeable = False
+    with _MASK_CACHE_LOCK:
+        _MASK_CACHE[key] = m
+        while len(_MASK_CACHE) > _MASK_CACHE_MAX:
+            _MASK_CACHE.pop(next(iter(_MASK_CACHE)))
+    return Mask(m.a, m.x, m.y)
+
+
+def heart_points(cx: float, cy: float, size: float, n: int = 64, closed: bool = True) -> list[Point]:
+    """Outline of a heart centered on (cx, cy), `size` wide (generic 'like' glyph)."""
+    s = size / 34.0
+    pts = []
+    for i in range(n + 1 if closed else n):
+        t = 2 * math.pi * i / n
+        x = 16 * math.sin(t) ** 3
+        y = 13 * math.cos(t) - 5 * math.cos(2 * t) - 2 * math.cos(3 * t) - math.cos(4 * t)
+        pts.append((cx + x * s, cy - (y + 2.5) * s))
+    return pts
+
+
+@dataclass(frozen=True)
+class Shadow:
+    blur: float = 26.0       # design px
+    dy: float = 14.0
+    dx: float = 0.0
+    opacity: float = 0.42
+    color: tuple = (0, 0, 0)
+
+
+@dataclass(frozen=True)
+class Gradient:
+    """Linear gradient fill: color c0 at `start`, c1 at `end` (box-local design px), clamped outside."""
+    c0: object
+    c1: object
+    start: tuple = (0.0, 0.0)
+    end: tuple = (0.0, 100.0)
+
+
+SOFT_SHADOW = Shadow()
+TEXT_SHADOW = Shadow(blur=10.0, dy=5.0, opacity=0.55)
+
+
+def _shadow_of(value) -> Shadow | None:
+    if value is None or value is False:
+        return None
+    if value is True:
+        return SOFT_SHADOW
+    if isinstance(value, Shadow):
+        return value
+    if isinstance(value, dict):
+        return Shadow(**value)
+    raise MotionError(f"sombra inválida: {value!r}")
+
+
+# ============================================================== canvas
+
+@dataclass
+class _Layer:
+    image: Image.Image
+    dirty: list[int] | None = None
+
+
+@dataclass
+class _Transform:
+    a: float = 1.0      # uniform scale (design -> design)
+    bx: float = 0.0
+    by: float = 0.0
+
+    def point(self, u: float, v: float) -> tuple[float, float]:
+        return self.a * u + self.bx, self.a * v + self.by
+
+
+class Canvas:
+    """Transparent drawing surface for one frame of one box (the box plus `bleed` all around).
+
+    Every coordinate and size is in box-local DESIGN px. Colors: '#RRGGBB', (r, g, b[, a]) or a theme
+    name ('accent', 'text', 'muted', 'card', 'danger', 'success', 'on_accent', 'track', 'white', 'black',
+    and the Portuguese 'destaque', 'texto', 'perigo', 'sucesso', 'branco', 'preto').
+    """
+
+    def __init__(self, box: Box, full: bool = False):
+        self.box = box
+        s = box.scale
+        self.s = s
+        self.full = bool(full)
+        if self.full:          # the whole output canvas (full-screen flash, drawing far from the box)
+            self.origin_x = self.origin_y = 0
+            self.W, self.H = int(box.canvas[0]), int(box.canvas[1])
+        else:
+            self.origin_x = int(math.floor((box.x - box.bleed) * s))
+            self.origin_y = int(math.floor((box.y - box.bleed) * s))
+            self.W = int(math.ceil((box.x + box.w + box.bleed) * s)) - self.origin_x
+            self.H = int(math.ceil((box.y + box.h + box.bleed) * s)) - self.origin_y
+        self.image = Image.new("RGBA", (self.W, self.H), (0, 0, 0, 0))
+        self._targets: list[Image.Image] = [self.image]
+        self._dirty: list[list[int] | None] = [None]     # drawn area of each target (render px)
+        self._tf = [_Transform()]
+
+    # ---------------------------------------------------------- basics
+    @property
+    def w(self) -> float:
+        return self.box.w
+
+    @property
+    def h(self) -> float:
+        return self.box.h
+
+    @property
+    def cx(self) -> float:
+        return self.box.w / 2.0
+
+    @property
+    def cy(self) -> float:
+        return self.box.h / 2.0
+
+    @property
+    def theme(self) -> Theme:
+        return self.box.theme
+
+    @property
+    def offset(self) -> tuple[int, int]:
+        """Render px of this canvas' top-left on the output canvas."""
+        return self.origin_x, self.origin_y
+
+    def color(self, value, opacity: float = 1.0) -> RGBA:
+        if isinstance(value, str) and not value.startswith("#"):
+            key = COLOR_NAMES.get(value.strip().lower())
+            if key is None:
+                raise MotionError(f"cor '{value}' não existe (use #RRGGBB ou {', '.join(sorted(set(COLOR_NAMES)))})")
+            c = self.theme.get(key)
+        else:
+            c = rgba(value)
+        return (c[0], c[1], c[2], _clamp8(c[3] * opacity))
+
+    def px(self, u: float, v: float) -> tuple[float, float]:
+        """Box-local design point (through the group transform) -> render px of this canvas."""
+        x, y = self._tf[-1].point(u, v)
+        s = self.s
+        return (self.box.x + x) * s - self.origin_x, (self.box.y + y) * s - self.origin_y
+
+    def len(self, d: float) -> float:
+        """Design length -> render px (through the group scale)."""
+        return d * self._tf[-1].a * self.s
+
+    @property
+    def _target(self) -> Image.Image:
+        return self._targets[-1]
+
+    def _mark(self, x0: int, y0: int, x1: int, y1: int) -> None:
+        d = self._dirty[-1]
+        if d is None:
+            self._dirty[-1] = [x0, y0, x1, y1]
+        else:
+            d[0], d[1], d[2], d[3] = min(d[0], x0), min(d[1], y0), max(d[2], x1), max(d[3], y1)
+
+    def _paste_layer(self, img: Image.Image, x: int, y: int) -> None:
+        """alpha_composite an image at (x, y) of the current target, clipped, marking the drawn area."""
+        tgt = self._target
+        x0, y0 = max(0, x), max(0, y)
+        x1, y1 = min(tgt.width, x + img.width), min(tgt.height, y + img.height)
+        if x1 <= x0 or y1 <= y0:
+            return
+        part = img if (x0, y0, x1, y1) == (x, y, x + img.width, y + img.height) else \
+            img.crop((x0 - x, y0 - y, x1 - x, y1 - y))
+        tgt.alpha_composite(part, (x0, y0))
+        self._mark(x0, y0, x1, y1)
+
+    def fill_mask(self, m: Mask | None, color, opacity: float = 1.0) -> None:
+        """Composite a color (or a Gradient) through a coverage mask (straight alpha, real blending)."""
+        if m is None or opacity <= 0:
+            return
+        tgt = self._target
+        x0, y0 = max(0, m.x), max(0, m.y)
+        x1, y1 = min(tgt.width, m.x + m.a.shape[1]), min(tgt.height, m.y + m.a.shape[0])
+        if x1 <= x0 or y1 <= y0:
+            return
+        a = m.a[y0 - m.y:y1 - m.y, x0 - m.x:x1 - m.x]
+        if isinstance(color, Gradient):
+            c0, c1 = self.color(color.c0, opacity), self.color(color.c1, opacity)
+            sx, sy = self.px(*color.start)
+            ex, ey = self.px(*color.end)
+            vx, vy = ex - sx, ey - sy
+            l2 = max(1e-9, vx * vx + vy * vy)
+            xs = np.arange(x0, x1, dtype=np.float32)[None, :] + 0.5
+            ys = np.arange(y0, y1, dtype=np.float32)[:, None] + 0.5
+            t = np.clip(((xs - sx) * vx + (ys - sy) * vy) / l2, 0.0, 1.0)
+            lo, hi = np.array(c0, np.float32), np.array(c1, np.float32)
+            rgba_px = lo[None, None, :] + (hi - lo)[None, None, :] * t[..., None]
+            rgba_px[..., 3] *= a
+            arr = np.clip(rgba_px + 0.5, 0, 255).astype(np.uint8)
+            if not arr[..., 3].any():
+                return
+            tgt.alpha_composite(Image.fromarray(np.ascontiguousarray(arr), "RGBA"), (x0, y0))
+            self._mark(x0, y0, x1, y1)
+            return
+        c = self.color(color, opacity)
+        if c[3] <= 0:
+            return
+        if c[3] < 255:
+            a = a * (c[3] / 255.0)
+        a8 = np.clip(a * 255.0 + 0.5, 0, 255).astype(np.uint8)
+        if not a8.any():
+            return
+        src = Image.new("RGBA", (x1 - x0, y1 - y0), (c[0], c[1], c[2], 255))
+        src.putalpha(Image.fromarray(np.ascontiguousarray(a8), "L"))
+        tgt.alpha_composite(src, (x0, y0))
+        self._mark(x0, y0, x1, y1)
+
+    def erase_mask(self, m: Mask | None, amount: float = 1.0) -> None:
+        """Cut a hole: the drawing under the mask becomes transparent (amount 0-1)."""
+        if m is None or amount <= 0:
+            return
+        tgt = self._target
+        x0, y0 = max(0, m.x), max(0, m.y)
+        x1, y1 = min(tgt.width, m.x + m.a.shape[1]), min(tgt.height, m.y + m.a.shape[0])
+        if x1 <= x0 or y1 <= y0:
+            return
+        a = m.a[y0 - m.y:y1 - m.y, x0 - m.x:x1 - m.x] * min(1.0, amount)
+        region = tgt.crop((x0, y0, x1, y1))
+        al = np.asarray(region.getchannel("A"), np.float32) * (1.0 - a)
+        region.putalpha(Image.fromarray(np.clip(al + 0.5, 0, 255).astype(np.uint8), "L"))
+        tgt.paste(region, (x0, y0))
+        self._mark(x0, y0, x1, y1)
+
+    def erase_circle(self, cx: float, cy: float, r: float, amount: float = 1.0) -> None:
+        self.erase_mask(self.circle_mask(cx, cy, r), amount)
+
+    def erase_rect(self, x: float, y: float, w: float, h: float, radius: float = 0.0, amount: float = 1.0) -> None:
+        self.erase_mask(self.rect_mask(x, y, w, h, radius), amount)
+
+    def fill(self, color="white", opacity: float = 1.0) -> None:
+        """Paint the whole canvas (a full-screen flash needs Canvas(box, full=True))."""
+        self.fill_mask(Mask(np.ones((self.H, self.W), np.float32), 0, 0), color, opacity)
+
+    def _cast_shadow(self, m: Mask | None, shadow: Shadow | None, opacity: float, key: tuple | None = None) -> None:
+        """Soft shadow of a mask. `key` (the exact render-px geometry of a plain shape) reuses the blur."""
+        if m is None or shadow is None or opacity <= 0:
+            return
+        radius = self.len(shadow.blur)
+        if key is not None:
+            b = _cached_mask(("blur", key, round(radius, 4), self.W, self.H), lambda: blur_mask(m, radius, self.W, self.H))
+            if b is None:
+                return
+        else:
+            b = blur_mask(m, radius, self.W, self.H)
+        b = Mask(b.a, b.x + int(round(self.len(shadow.dx))), b.y + int(round(self.len(shadow.dy))))
+        self.fill_mask(b, tuple(shadow.color), shadow.opacity * opacity)
+
+    # ---------------------------------------------------------- shape masks (render px)
+    def _rect_geometry(self, x: float, y: float, w: float, h: float, radius: float, inset: float) -> tuple | None:
+        X0, Y0 = self.px(x, y)
+        X1, Y1 = self.px(x + w, y + h)
+        ins = self.len(inset)
+        X0, Y0, X1, Y1 = X0 + ins, Y0 + ins, X1 - ins, Y1 - ins
+        if X1 - X0 <= 0.05 or Y1 - Y0 <= 0.05:
+            return None
+        r = max(0.0, min(self.len(radius) - ins, (X1 - X0) / 2.0, (Y1 - Y0) / 2.0))
+        return ("rect", X0, Y0, X1, Y1, r, self.W, self.H)
+
+    @staticmethod
+    def _rect_from(geo: tuple) -> Mask | None:
+        _, X0, Y0, X1, Y1, r, W, H = geo
+        g = _grid(X0, Y0, X1, Y1, W, H)
+        if g is None:
+            return None
+        ix, iy, px, py = g
+        return Mask(_coverage(_rrect_sd(px, py, X0, Y0, X1, Y1, r)).astype(np.float32), ix, iy)
+
+    def rect_mask(self, x: float, y: float, w: float, h: float, radius: float = 0.0, inset: float = 0.0) -> Mask | None:
+        geo = self._rect_geometry(x, y, w, h, radius, inset)
+        if geo is None:
+            return None
+        return _cached_mask(geo, lambda: self._rect_from(geo))
+
+    def circle_mask(self, cx: float, cy: float, r: float) -> Mask | None:
+        X, Y = self.px(cx, cy)
+        R = self.len(r)
+        if R <= 0.05:
+            return None
+
+        def make() -> Mask | None:
+            g = _grid(X - R, Y - R, X + R, Y + R, self.W, self.H)
+            if g is None:
+                return None
+            ix, iy, px, py = g
+            d = np.sqrt((px - X) ** 2 + (py - Y) ** 2) - R
+            return Mask(_coverage(d).astype(np.float32), ix, iy)
+
+        return _cached_mask(("circle", X, Y, R, self.W, self.H), make)
+
+    def stroke_mask(self, points: Sequence[Point], width: float, widths: Sequence[float] | None = None) -> Mask | None:
+        """Round-capped, round-joined stroke through points (union, so crossings never double the alpha)."""
+        pts = [self.px(*p) for p in points]
+        if len(pts) == 1:
+            pts = pts * 2
+        if len(pts) < 2:
+            return None
+        rads = [self.len(wd) / 2.0 for wd in widths] if widths else [self.len(width) / 2.0] * len(pts)
+        if len(rads) != len(pts):
+            raise MotionError("widths precisa ter um valor por ponto")
+        rmax = max(rads)
+        if rmax <= 0.02:
+            return None
+        xs = [p[0] for p in pts]
+        ys = [p[1] for p in pts]
+        g = _grid(min(xs) - rmax, min(ys) - rmax, max(xs) + rmax, max(ys) + rmax, self.W, self.H)
+        if g is None:
+            return None
+        ix, iy, gx, gy = g
+        hgt, wid = gy.shape[0], gx.shape[1]
+        best = np.full((hgt, wid), np.inf, np.float32)
+        for (ax, ay), (bx, by), ra, rb in zip(pts, pts[1:], rads, rads[1:]):
+            r = max(ra, rb)
+            sx0 = max(0, int(math.floor(min(ax, bx) - r)) - 1 - ix)
+            sx1 = min(wid, int(math.ceil(max(ax, bx) + r)) + 2 - ix)
+            sy0 = max(0, int(math.floor(min(ay, by) - r)) - 1 - iy)
+            sy1 = min(hgt, int(math.ceil(max(ay, by) + r)) + 2 - iy)
+            if sx1 <= sx0 or sy1 <= sy0:
+                continue
+            px = gx[:, sx0:sx1]
+            py = gy[sy0:sy1, :]
+            if abs(ra - rb) < 1e-6:
+                d = _seg_dist(px, py, ax, ay, bx, by) - ra
+            else:   # tapered: radius interpolated along the segment
+                vx, vy = bx - ax, by - ay
+                l2 = max(1e-12, vx * vx + vy * vy)
+                t = np.clip(((px - ax) * vx + (py - ay) * vy) / l2, 0.0, 1.0)
+                dx, dy = px - ax - t * vx, py - ay - t * vy
+                d = np.sqrt(dx * dx + dy * dy) - (ra + (rb - ra) * t)
+            sub = best[sy0:sy1, sx0:sx1]
+            np.minimum(sub, d.astype(np.float32), out=sub)
+        return Mask(_coverage(best).astype(np.float32), ix, iy)
+
+    def polygon_mask(self, points: Sequence[Point], radius: float = 0.0) -> Mask | None:
+        """Filled polygon; `radius` rounds the corners of a CONVEX polygon."""
+        pts = [self.px(*p) for p in points]
+        if len(pts) < 3:
+            return None
+        grow = 0.0
+        if radius > 0:
+            r = self.len(radius)
+            inner = _inset_convex(pts, r)
+            if inner is not None:
+                pts, grow = inner, r
+        xs = [p[0] for p in pts]
+        ys = [p[1] for p in pts]
+        g = _grid(min(xs) - grow, min(ys) - grow, max(xs) + grow, max(ys) + grow, self.W, self.H)
+        if g is None:
+            return None
+        ix, iy, px, py = g
+        px = np.broadcast_to(px, (py.shape[0], px.shape[1]))
+        py = np.broadcast_to(py, px.shape)
+        d = np.full(px.shape, np.inf, np.float32)
+        inside = np.zeros(px.shape, bool)
+        for (ax, ay), (bx, by) in zip(pts, pts[1:] + pts[:1]):
+            np.minimum(d, _seg_dist(px, py, ax, ay, bx, by).astype(np.float32), out=d)
+            cond = (ay > py) != (by > py)
+            with np.errstate(divide="ignore", invalid="ignore"):
+                xint = (bx - ax) * (py - ay) / (by - ay) + ax
+            inside ^= cond & (px < xint)
+        sd = np.where(inside, -d, d) - grow
+        return Mask(_coverage(sd).astype(np.float32), ix, iy)
+
+    # ---------------------------------------------------------- shapes
+    def rect(self, x: float, y: float, w: float, h: float, radius: float = 0.0, fill="card", opacity: float = 1.0,
+             stroke=None, stroke_width: float = 0.0, shadow=None) -> None:
+        """Rounded rectangle; `stroke` draws an inner border of `stroke_width`. With `fill=None` the shadow is
+        the border's own (an outline casts no filled shadow)."""
+        geo = self._rect_geometry(x, y, w, h, radius, 0.0)
+        m = self.rect_mask(x, y, w, h, radius)
+        if m is None:
+            return
+        ring = None
+        if stroke is not None and stroke_width > 0:
+            inner = self.rect_mask(x, y, w, h, radius, inset=stroke_width)
+            a = m.a.copy()
+            if inner is not None:
+                oy, ox = inner.y - m.y, inner.x - m.x
+                a[oy:oy + inner.a.shape[0], ox:ox + inner.a.shape[1]] -= inner.a
+            ring = Mask(np.clip(a, 0, 1), m.x, m.y)
+        if fill is not None:
+            self._cast_shadow(m, _shadow_of(shadow), opacity, key=geo)
+            self.fill_mask(m, fill, opacity)
+        elif ring is not None:
+            self._cast_shadow(ring, _shadow_of(shadow), opacity, key=(geo, "ring", self.len(stroke_width)))
+        if ring is not None:
+            self.fill_mask(ring, stroke, opacity)
+
+    def pill(self, x: float, y: float, w: float, h: float, **kw) -> None:
+        self.rect(x, y, w, h, radius=h / 2.0, **kw)
+
+    def card(self, x: float, y: float, w: float, h: float, radius: float = 40.0, opacity: float = 1.0,
+             shadow=True, fill="card", border: bool = True) -> None:
+        """The standard card of the templates: theme fill, hairline border, soft shadow. In papelaria the
+        card sits on a solid lilac clay base 10 px lower, as in the VSL pieces."""
+        th = self.theme
+        if fill == "card" and th.style == "papel" and th.clay is not None:
+            self.rect(x, y + 10.0, w, h, radius=radius, fill=th.clay, opacity=opacity,
+                      shadow=Shadow(blur=26.0, dy=14.0, opacity=0.22, color=tuple(th.ink[:3])) if shadow else None)
+            shadow = False
+        elif fill == "card" and th.style == "pop":       # hard black shadow, thick black outline
+            self.rect(x + 9.0, y + 9.0, w, h, radius=radius, fill=(17, 17, 17, 255), opacity=opacity)
+            self.rect(x, y, w, h, radius=radius, fill=fill, opacity=opacity, stroke="card_border", stroke_width=4.5)
+            return
+        elif fill == "card" and th.style == "neon":      # glow in the accent color around a thin bright border
+            self.rect(x, y, w, h, radius=radius, fill=fill, opacity=opacity,
+                      shadow=Shadow(blur=34.0, dy=0.0, opacity=0.75, color=tuple(th.accent[:3])),
+                      stroke="accent", stroke_width=3.0)
+            return
+        self.rect(x, y, w, h, radius=radius, fill=fill, opacity=opacity, shadow=shadow,
+                  stroke="card_border" if border else None, stroke_width=2.0 if border else 0.0)
+
+    def circle(self, cx: float, cy: float, r: float, fill="accent", opacity: float = 1.0, stroke=None,
+               stroke_width: float = 0.0, shadow=None) -> None:
+        m = self.circle_mask(cx, cy, r)
+        if m is None:
+            return
+        X, Y = self.px(cx, cy)
+        if fill is not None:
+            self._cast_shadow(m, _shadow_of(shadow), opacity, key=("circle", X, Y, self.len(r), self.W, self.H))
+            self.fill_mask(m, fill, opacity)
+        if stroke is not None and stroke_width > 0:
+            if fill is None and shadow:
+                ring = self._ring_mask(cx, cy, r - stroke_width / 2.0, stroke_width)
+                self._cast_shadow(ring, _shadow_of(shadow), opacity,
+                                  key=("ring", X, Y, self.len(r), self.len(stroke_width), self.W, self.H))
+            self.ring(cx, cy, r - stroke_width / 2.0, stroke_width, color=stroke, opacity=opacity)
+
+    def _ring_mask(self, cx: float, cy: float, r: float, width: float) -> Mask | None:
+        X, Y = self.px(cx, cy)
+        R, half = self.len(r), self.len(width) / 2.0
+
+        def make() -> Mask | None:
+            g = _grid(X - R - half, Y - R - half, X + R + half, Y + R + half, self.W, self.H)
+            if g is None:
+                return None
+            ix, iy, px, py = g
+            d = np.abs(np.sqrt((px - X) ** 2 + (py - Y) ** 2) - R) - half
+            return Mask(_coverage(d).astype(np.float32), ix, iy)
+
+        return _cached_mask(("ringmask", X, Y, R, half, self.W, self.H), make)
+
+    def ring(self, cx: float, cy: float, r: float, width: float, color="accent", opacity: float = 1.0,
+             progress: float = 1.0, start_deg: float = -90.0) -> None:
+        """Circle outline (centered on r); progress < 1 draws an arc clockwise from start_deg with round caps."""
+        if progress <= 0:
+            return
+        if progress >= 1:
+            self.fill_mask(self._ring_mask(cx, cy, r, width), color, opacity)
+            return
+        pts = ellipse_points(cx, cy, r, r, start_deg, 360.0 * clamp01(progress))
+        self.polyline(pts, width, color=color, opacity=opacity)
+
+    def line(self, x0: float, y0: float, x1: float, y1: float, width: float = 8.0, color="accent",
+             opacity: float = 1.0, progress: float = 1.0, shadow=None) -> None:
+        self.polyline([(x0, y0), (x1, y1)], width, color=color, opacity=opacity, progress=progress, shadow=shadow)
+
+    def polyline(self, points: Sequence[Point], width: float = 8.0, color="accent", opacity: float = 1.0,
+                 progress: float = 1.0, start: float = 0.0, widths: Sequence[float] | None = None,
+                 shadow=None) -> None:
+        """Stroke with round caps; draws the [start, progress] part of the path (by length)."""
+        if progress <= start or opacity <= 0:
+            return
+        pts = list(points)
+        ws = None
+        if progress < 1 or start > 0:
+            if widths:
+                # keep one width per kept point: resample widths along the trimmed path
+                total = path_length(pts)
+                cum = [0.0]
+                for p, q in zip(pts, pts[1:]):
+                    cum.append(cum[-1] + math.dist(p, q))
+                pts = trim_points(pts, start, progress)
+                run = start * total
+                ws = []
+                for i, p in enumerate(pts):
+                    if i:
+                        run += math.dist(pts[i - 1], p)
+                    ws.append(float(np.interp(run, cum, list(widths))))
+            else:
+                pts = trim_points(pts, start, progress)
+        elif widths:
+            ws = list(widths)
+        m = self.stroke_mask(pts, width, ws)
+        self._cast_shadow(m, _shadow_of(shadow), opacity)
+        self.fill_mask(m, color, opacity)
+
+    def polygon(self, points: Sequence[Point], fill="accent", opacity: float = 1.0, shadow=None,
+                radius: float = 0.0) -> None:
+        """Filled polygon (radius rounds the corners of a convex one)."""
+        m = self.polygon_mask(points, radius)
+        self._cast_shadow(m, _shadow_of(shadow), opacity)
+        self.fill_mask(m, fill, opacity)
+
+    def arrow(self, x0: float, y0: float, x1: float, y1: float, width: float = 10.0, color="accent",
+              opacity: float = 1.0, progress: float = 1.0, head: float | None = None, curve: float = 0.0,
+              filled: bool = False, shadow=None) -> None:
+        """Arrow from (x0, y0) to (x1, y1), drawn by progress; `curve` bends it sideways (fraction of its length).
+        The head grows in over the last 25% of the progress."""
+        if progress <= 0:
+            return
+        L = math.dist((x0, y0), (x1, y1))
+        if curve:
+            mx, my = (x0 + x1) / 2.0, (y0 + y1) / 2.0
+            nx, ny = -(y1 - y0) / max(L, 1e-6), (x1 - x0) / max(L, 1e-6)
+            pts = bezier_points((x0, y0), (mx + nx * curve * L, my + ny * curve * L), (x1, y1), n=40)
+        else:
+            pts = [(x0, y0), (x1, y1)]
+        head = head if head is not None else max(width * 3.2, 26.0)
+        self.polyline(pts, width, color=color, opacity=opacity, progress=progress, shadow=shadow)
+        hp = remap(progress, 0.75, 1.0)
+        if hp <= 0:
+            return
+        (tx, ty), ang = point_at(pts, progress)
+        size = head * out_back(hp, 2.2)
+        wing = math.radians(32)
+        a1, a2 = ang + math.pi - wing, ang + math.pi + wing
+        p1 = (tx + size * math.cos(a1), ty + size * math.sin(a1))
+        p2 = (tx + size * math.cos(a2), ty + size * math.sin(a2))
+        if filled:
+            tip = (tx + width * 0.6 * math.cos(ang), ty + width * 0.6 * math.sin(ang))
+            self.polygon([tip, p1, p2], fill=color, opacity=opacity)
+        else:
+            self.polyline([p1, (tx, ty), p2], width, color=color, opacity=opacity)
+
+    def check(self, cx: float, cy: float, size: float, width: float | None = None, color="white",
+              opacity: float = 1.0, progress: float = 1.0) -> None:
+        """Check mark centered on (cx, cy), `size` = its width; drawn stroke by stroke with progress."""
+        s = size
+        pts = [(cx - 0.40 * s, cy + 0.02 * s), (cx - 0.12 * s, cy + 0.28 * s), (cx + 0.42 * s, cy - 0.30 * s)]
+        self.polyline(pts, width if width is not None else s * 0.16, color=color, opacity=opacity,
+                      progress=out_quad(progress) if progress < 1 else 1.0)
+
+    def cross(self, cx: float, cy: float, size: float, width: float | None = None, color="white",
+              opacity: float = 1.0, progress: float = 1.0) -> None:
+        """X mark: first stroke in the first half of the progress, the second in the other half."""
+        q = size / 2.0
+        wd = width if width is not None else size * 0.16
+        self.polyline([(cx - q, cy - q), (cx + q, cy + q)], wd, color=color, opacity=opacity,
+                      progress=clamp01(progress * 2))
+        if progress > 0.5:
+            self.polyline([(cx + q, cy - q), (cx - q, cy + q)], wd, color=color, opacity=opacity,
+                          progress=clamp01(progress * 2 - 1))
+
+    def glow(self, draw: Callable[[], None], radius: float = 24.0, opacity: float = 0.6, color="accent") -> None:
+        """Soft colored glow behind whatever `draw()` paints, then the sharp drawing on top."""
+        with self._layer() as lay:
+            draw()
+        if lay.dirty is None:
+            return
+        x0, y0, x1, y1 = lay.dirty
+        part = lay.image.crop((x0, y0, x1, y1))
+        if opacity > 0:
+            a = np.asarray(part.getchannel("A"), np.float32) / 255.0
+            m = blur_mask(Mask(a, x0, y0), self.len(radius), self.W, self.H)
+            self.fill_mask(Mask(np.clip(m.a * 1.6, 0, 1), m.x, m.y), color, opacity)
+        self._paste_layer(part, x0, y0)
+
+    # ---------------------------------------------------------- text
+    def _text_mask(self, x: float, y: float, text: str, f: ImageFont.FreeTypeFont, stroke_px: float,
+                   tabular: bool, tracking_px: float) -> Mask | None:
+        """Mask of a text whose baseline-left origin is at render px (x, y)."""
+        if not text:
+            return None
+        asc, desc = f.getmetrics()
+        pad = int(math.ceil(stroke_px)) + 4
+        adv = _advance(f, text, tabular, tracking_px)
+        left = int(math.floor(x)) - pad - int(f.size * 0.25)
+        top = int(math.floor(y - asc * 1.25)) - pad
+        wpx = int(math.ceil(adv + f.size * 0.5)) + 2 * pad
+        hpx = int(math.ceil((asc * 1.25) + desc * 1.4)) + 2 * pad
+        if left >= self.W or top >= self.H or left + wpx <= 0 or top + hpx <= 0:
+            return None
+        img = Image.new("L", (wpx, hpx), 0)
+        d = ImageDraw.Draw(img)
+        ox, oy = x - left, y - top
+        kw = {"stroke_width": stroke_px, "stroke_fill": 255} if stroke_px > 0 else {}
+        if tabular or tracking_px:
+            cell = _digit_cell(f) if tabular else 0.0
+            for ch in text:
+                wch = f.getlength(ch)
+                if tabular and ch.isdigit():
+                    d.text((ox + (cell - wch) / 2.0, oy), ch, font=f, fill=255, anchor="ls", **kw)
+                    ox += cell
+                else:
+                    d.text((ox, oy), ch, font=f, fill=255, anchor="ls", **kw)
+                    ox += wch
+                ox += tracking_px
+        else:
+            d.text((ox, oy), text, font=f, fill=255, anchor="ls", **kw)
+        return Mask(np.asarray(img, np.float32) / 255.0, left, top)
+
+    def text(self, x: float, y: float, text: str, font_key: str = "sans_black", size: float = 64.0, color="text",
+             opacity: float = 1.0, anchor: str = "ls", stroke: float = 0.0, stroke_color="black",
+             shadow=None, tabular: bool = False, tracking: float = 0.0, upper: bool = False) -> tuple[float, float, float, float]:
+        """Draw one line. anchor = horizontal (l, m, r) + vertical (a ascender, t cap top, c cap middle,
+        s baseline, d descender). Returns the laid-out box (x0, y0, x1, y1) in box-local design px:
+        advance width by cap top to baseline."""
+        s = clean_text(text, font_key)
+        if upper:
+            s = s.upper()
+        m = measure(s, font_key, size, tabular, tracking)
+        h, v = (anchor + "s")[0], (anchor + "s")[1]
+        dx = {"l": 0.0, "m": -m.width / 2.0, "r": -m.width}.get(h)
+        dy = {"a": m.ascent, "t": m.cap, "c": m.cap / 2.0, "s": 0.0, "d": -m.descent}.get(v)
+        if dx is None or dy is None:
+            raise MotionError(f"âncora de texto inválida: {anchor!r}")
+        bx, by = x + dx, y + dy
+        if opacity > 0 and s:
+            k = self._tf[-1].a * self.s
+            f = font(font_key, size * k)
+            X, Y = self.px(bx, by)
+            sh = _shadow_of(shadow)
+            stroke_px = stroke * k
+            body = self._text_mask(X, Y, s, f, 0.0, tabular, tracking * k)
+            outline = self._text_mask(X, Y, s, f, stroke_px, tabular, tracking * k) if stroke_px > 0 else None
+            self._cast_shadow(outline or body, sh, opacity)
+            if outline is not None:
+                self.fill_mask(outline, stroke_color, opacity)
+            self.fill_mask(body, color, opacity)
+        return bx, by - m.cap, bx + m.width, by
+
+    def rich_text(self, x: float, y: float, text: str, font_key: str = "sans_black", size: float = 64.0,
+                  color="text", accent_color="accent", opacity: float = 1.0, anchor: str = "ls",
+                  stroke: float = 0.0, stroke_color="black", shadow=None, upper: bool = False,
+                  highlight: bool = False) -> tuple[float, float, float, float]:
+        """One line where *marked* words get the accent color, or (highlight=True) an accent box behind them
+        with readable text on it."""
+        parts = parse_accent(clean_text(text, font_key))
+        if upper:
+            parts = [(w.upper(), a) for w, a in parts]
+        f = font(font_key, size)
+        space = f.getlength(" ")
+        widths = [f.getlength(w) for w, _ in parts]
+        total = sum(widths) + space * max(0, len(parts) - 1)
+        m = measure("H", font_key, size)
+        h, v = (anchor + "s")[0], (anchor + "s")[1]
+        dx = {"l": 0.0, "m": -total / 2.0, "r": -total}.get(h)
+        dy = {"a": m.ascent, "t": m.cap, "c": m.cap / 2.0, "s": 0.0, "d": -m.descent}.get(v)
+        if dx is None or dy is None:
+            raise MotionError(f"âncora de texto inválida: {anchor!r}")
+        bx, by = x + dx, y + dy
+        cur = bx
+        for (word, acc), wd in zip(parts, widths):
+            col = color
+            if acc and highlight:
+                padx, pady = size * 0.14, size * 0.16
+                self.rect(cur - padx, by - m.cap - pady, wd + 2 * padx, m.cap + 2 * pady, radius=size * 0.12,
+                          fill=accent_color, opacity=opacity)
+                col = readable_on(self.color(accent_color))
+            elif acc:
+                col = accent_color
+            self.text(cur, by, word, font_key, size, color=col, opacity=opacity, anchor="ls", stroke=stroke,
+                      stroke_color=stroke_color, shadow=shadow)
+            cur += wd + space
+        return bx, by - m.cap, bx + total, by
+
+    def paragraph(self, x: float, y: float, text: str, font_key: str = "text_bold", size: float = 44.0,
+                  max_width: float = 700.0, max_lines: int = 3, line_height: float = 1.22, align: str = "l",
+                  color="text", opacity: float = 1.0, min_size: float | None = None, **kw) -> tuple[float, float, float, float]:
+        """Wrapped text (balanced lines) with its first cap top at y. `align` l/m/r relative to x. The size
+        shrinks (down to min_size, default 55%) until the text fits max_lines x max_width; a text that still does
+        not fit is drawn at min_size (limit the text length in the params). Returns (x0, y0, x1, y1)."""
+        size = float(size)
+        floor = float(min_size) if min_size is not None else size * 0.55
+        clean = clean_text(text, font_key)
+        lines = wrap_text(clean, font_key, size, max_width, max_lines)
+        while size > floor and (len(lines) > max_lines or any(
+                measure(ln, font_key, size).width > max_width + 0.5 for ln in lines)):
+            size = max(floor, size * 0.94)
+            lines = wrap_text(clean, font_key, size, max_width, max_lines)
+        m = measure("H", font_key, size)
+        pitch = size * line_height
+        x0, x1 = float("inf"), float("-inf")
+        for i, ln in enumerate(lines[:max(1, max_lines)]):
+            bx0, _, bx1, _ = self.text(x, y + m.cap + pitch * i, ln, font_key, size, color=color, opacity=opacity,
+                                       anchor=align + "s", **kw)
+            x0, x1 = min(x0, bx0), max(x1, bx1)
+        n = min(len(lines), max(1, max_lines))
+        return (x0 if n else x), y, (x1 if n else x), y + m.cap + pitch * max(0, n - 1)
+
+    def paste_sprite(self, sprite: "Sprite | None", opacity: float = 1.0) -> None:
+        """Paste a part drawn once (`static_sprite`) at its place. Outside a scaled group it is pixel-identical to
+        drawing it again."""
+        if sprite is None:
+            return
+        k = self.box.scale
+        self.paste_image(sprite.image, sprite.x, sprite.y, w=sprite.image.width / k, h=sprite.image.height / k,
+                         opacity=opacity)
+
+    def paste_image(self, img: Image.Image, x: float, y: float, w: float | None = None, h: float | None = None,
+                    opacity: float = 1.0) -> None:
+        """Paste an RGBA image with its top-left at (x, y), resized to w x h design px (keeps ratio if one is None).
+        (`cv.image` is the frame itself, a PIL image.)"""
+        if opacity <= 0:
+            return
+        src = img.convert("RGBA")
+        if w is None and h is None:
+            w, h = src.width / self.box.scale, src.height / self.box.scale
+        elif w is None:
+            w = h * src.width / src.height
+        elif h is None:
+            h = w * src.height / src.width
+        X0, Y0 = self.px(x, y)
+        tw, th = max(1, int(round(self.len(w)))), max(1, int(round(self.len(h))))
+        if (tw, th) != src.size:
+            src = src.resize((tw, th), Image.LANCZOS)
+        if opacity < 1:
+            a = np.asarray(src.getchannel("A"), np.float32) * opacity
+            src.putalpha(Image.fromarray(np.clip(a + 0.5, 0, 255).astype(np.uint8), "L"))
+        self._paste_layer(src, int(round(X0)), int(round(Y0)))
+
+    # ---------------------------------------------------------- groups
+    @contextmanager
+    def _layer(self):
+        lay = _Layer(Image.new("RGBA", (self.W, self.H), (0, 0, 0, 0)))
+        self._targets.append(lay.image)
+        self._dirty.append(None)
+        try:
+            yield lay
+        finally:
+            self._targets.pop()
+            lay.dirty = self._dirty.pop()
+
+    @contextmanager
+    def group(self, opacity: float = 1.0, scale: float = 1.0, pivot: Point | None = None, dx: float = 0.0,
+              dy: float = 0.0, rotate: float = 0.0):
+        """Draw the block inside as one piece: moved by (dx, dy), scaled around `pivot` (default: the box
+        center), rotated by `rotate` degrees (clockwise, as a picture) and faded as a whole."""
+        px_, py_ = pivot if pivot is not None else (self.cx, self.cy)
+        cur = self._tf[-1]
+        # new(u) = cur(pivot + (u - pivot) * scale + d)
+        nb = cur.point(px_ * (1 - scale) + dx, py_ * (1 - scale) + dy)
+        self._tf.append(_Transform(cur.a * scale, nb[0], nb[1]))
+        needs_layer = opacity < 0.999 or abs(rotate) > 1e-3
+        try:
+            if not needs_layer:
+                yield self
+                return
+            with self._layer() as lay:
+                yield self
+            if opacity <= 0.001 or lay.dirty is None:
+                return
+            x0, y0, x1, y1 = lay.dirty
+            part = lay.image.crop((x0, y0, x1, y1))
+            if abs(rotate) > 1e-3:
+                # rotate on a square around the pivot that holds the drawing in every angle
+                cx, cy = self.px(px_, py_)
+                reach = max(math.hypot(x - cx, y - cy) for x in (x0, x1) for y in (y0, y1))
+                half = int(math.ceil(reach)) + 2
+                sx0, sy0 = int(math.floor(cx)) - half, int(math.floor(cy)) - half
+                square = Image.new("RGBA", (2 * half + 2, 2 * half + 2), (0, 0, 0, 0))
+                square.paste(part, (x0 - sx0, y0 - sy0))
+                part = square.convert("RGBa").rotate(-rotate, resample=Image.BICUBIC,
+                                                     center=(cx - sx0, cy - sy0)).convert("RGBA")
+                x0, y0 = sx0, sy0
+            if opacity < 0.999:
+                a = np.asarray(part.getchannel("A"), np.float32) * opacity
+                part.putalpha(Image.fromarray(np.clip(a + 0.5, 0, 255).astype(np.uint8), "L"))
+            self._paste_layer(part, x0, y0)
+        finally:
+            self._tf.pop()
+
+    def visible(self, opacity: float) -> bool:
+        return opacity > 0.001
+
+    def result(self) -> "Canvas":
+        return self
+
+
+# ============================================================== parts drawn once
+
+@dataclass(frozen=True)
+class Sprite:
+    """A drawn part: RGBA image at render px, its top-left in box-local design px."""
+    image: Image.Image
+    x: float
+    y: float
+
+
+_SPRITES: "dict[tuple, Sprite | None]" = {}
+_SPRITES_LOCK = threading.Lock()
+_SPRITES_MAX = 24
+
+
+def static_sprite(key: tuple, box: Box, draw: Callable[[Canvas], None]) -> Sprite | None:
+    """Draw `draw(canvas)` once for this box and keep it (the card, title and axes of a chart that never move
+    after the entrance). `key` must name everything the drawing depends on besides the box, e.g.
+    ("grafico_barras", json.dumps(params, sort_keys=True)). Paste it with `cv.paste_sprite(sprite)`.
+    None when nothing was drawn."""
+    full_key = (key, box)
+    with _SPRITES_LOCK:
+        if full_key in _SPRITES:
+            return _SPRITES[full_key]
+    c = Canvas(box)
+    draw(c)
+    bb = c.image.getbbox()
+    sprite = None
+    if bb is not None:
+        s = box.scale
+        sprite = Sprite(c.image.crop(bb), (bb[0] + c.origin_x) / s - box.x, (bb[1] + c.origin_y) / s - box.y)
+    with _SPRITES_LOCK:
+        _SPRITES[full_key] = sprite
+        while len(_SPRITES) > _SPRITES_MAX:
+            _SPRITES.pop(next(iter(_SPRITES)))
+    return sprite
+
+
+# ============================================================== frame helpers for the renderer
+
+def blank_frame(canvas: Sequence[int]) -> Image.Image:
+    return Image.new("RGBA", (int(canvas[0]), int(canvas[1])), (0, 0, 0, 0))
+
+
+def with_box(box: Box, **changes) -> Box:
+    return replace(box, **changes)
+
+
+def iter_frames(n: int) -> Iterable[int]:
+    return range(max(0, int(n)))