kinescript 1.1.0__py3-none-any.whl

kinescript/shaders.py

@@ -0,0 +1,79 @@
+"""SkSL shader layers. Built-in uniforms: iTime (layer seconds), iResolution (w, h), iProgress (0..1).
+Colour uniforms are float4 (premultiply is not needed; alpha stays 1 unless you set it)."""
+from __future__ import annotations
+
+PRESETS = {
+    # Four soft colour fields drifting over each other.
+    "mesh": ("""
+uniform float iTime; uniform float2 iResolution; uniform float iProgress;
+uniform float4 c1; uniform float4 c2; uniform float4 c3; uniform float4 c4; uniform float speed;
+half4 main(float2 p) {
+  float2 uv = p / iResolution; float t = iTime * speed;
+  float2 a = float2(0.25 + 0.15 * sin(t * 0.7), 0.3 + 0.2 * cos(t * 0.5));
+  float2 b = float2(0.75 + 0.15 * cos(t * 0.6), 0.25 + 0.15 * sin(t * 0.8));
+  float2 c = float2(0.3 + 0.2 * cos(t * 0.4), 0.8 + 0.1 * sin(t * 0.9));
+  float2 d = float2(0.8 + 0.1 * sin(t * 0.5), 0.75 + 0.15 * cos(t * 0.3));
+  float wa = 1.0 / (0.02 + pow(distance(uv, a), 2.0)); float wb = 1.0 / (0.02 + pow(distance(uv, b), 2.0));
+  float wc = 1.0 / (0.02 + pow(distance(uv, c), 2.0)); float wd = 1.0 / (0.02 + pow(distance(uv, d), 2.0));
+  float4 col = (c1 * wa + c2 * wb + c3 * wc + c4 * wd) / (wa + wb + wc + wd);
+  return half4(col.rgb, 1.0);
+}""", {"c1": "#ff633f", "c2": "#b9f45d", "c3": "#242832", "c4": "#0a0c10", "speed": 1.0}),
+    # Horizontal light bands with a slow vertical sway.
+    "aurora": ("""
+uniform float iTime; uniform float2 iResolution; uniform float iProgress;
+uniform float4 base; uniform float4 glow; uniform float4 glow2; uniform float speed;
+half4 main(float2 p) {
+  float2 uv = p / iResolution; float t = iTime * speed;
+  float band = 0.0;
+  for (int i = 0; i < 3; i++) {
+    float fi = float(i);
+    float y = 0.35 + 0.12 * fi + 0.08 * sin(uv.x * (3.0 + fi) + t * (0.6 + 0.2 * fi));
+    band += exp(-pow((uv.y - y) * (9.0 - fi * 2.0), 2.0)) * (0.7 - 0.15 * fi);
+  }
+  float4 g = mix(glow, glow2, 0.5 + 0.5 * sin(uv.x * 2.0 + t * 0.3));
+  float4 col = mix(base, g, clamp(band * 0.75, 0.0, 0.85));
+  return half4(col.rgb, 1.0);
+}""", {"base": "#0a0c10", "glow": "#b9f45d", "glow2": "#ff633f", "speed": 1.0}),
+    # Receding floor grid, like a stage.
+    "grid": ("""
+uniform float iTime; uniform float2 iResolution; uniform float iProgress;
+uniform float4 base; uniform float4 line; uniform float speed; uniform float density;
+half4 main(float2 p) {
+  float2 uv = p / iResolution;
+  float horizon = 0.42;
+  float4 col = base;
+  if (uv.y > horizon) {
+    float z = 1.0 / (uv.y - horizon + 0.001);
+    float gx = (uv.x - 0.5) * z * density;
+    float gz = z * density * 0.5 + iTime * speed;
+    float lx = abs(fract(gx) - 0.5); float lz = abs(fract(gz) - 0.5);
+    float w = 0.004 * z;
+    float g = max(smoothstep(w + 0.012, w, lx), smoothstep(w + 0.012, w, lz));
+    float fade = clamp((uv.y - horizon) * 2.4, 0.0, 1.0);
+    col = mix(base, line, g * fade);
+  }
+  return half4(col.rgb, 1.0);
+}""", {"base": "#0a0c10", "line": "#ff633f", "speed": 0.6, "density": 1.0}),
+    # Timing grid: beat lines, bar lines every fourth beat, faint lanes, registration crosses.
+    # It advances one beat at a time (discrete steps), never drifts.
+    "score": ("""
+uniform float iTime; uniform float2 iResolution; uniform float iProgress;
+uniform float4 base; uniform float4 line; uniform float4 mark; uniform float beat; uniform float rate;
+uniform float lane;
+half4 main(float2 p) {
+  float shift = floor(iTime * rate) * beat;
+  float x = p.x + shift;
+  float bx = abs(fract(x / beat) - 0.5) * beat;
+  float barx = abs(fract(x / (beat * 4.0)) - 0.5) * beat * 4.0;
+  float ly = abs(fract(p.y / lane) - 0.5) * lane;
+  float beatLine = smoothstep(1.2, 0.2, bx) * 0.35;
+  float barLine = smoothstep(1.4, 0.3, barx) * 0.8;
+  float laneLine = smoothstep(1.0, 0.2, ly) * 0.25;
+  float cross = 0.0;
+  if (barx < 9.0 && ly < 9.0) { cross = max(smoothstep(1.3, 0.3, barx), smoothstep(1.3, 0.3, ly)); }
+  float4 col = base;
+  col = mix(col, line, clamp(max(max(beatLine, barLine), laneLine), 0.0, 1.0));
+  col = mix(col, mark, cross * 0.9);
+  return half4(col.rgb, 1.0);
+}""", {"base": "#0a0c10", "line": "#242832", "mark": "#9299a8", "beat": 48.0, "rate": 2.0, "lane": 216.0}),
+}

kinescript/space.py

@@ -0,0 +1,81 @@
+"""Depth for layers: 4x4 matrices in canvas pixels with x right, y down and z toward the viewer, the
+convention CSS transforms use, and the camera that projects them onto the canvas."""
+from __future__ import annotations
+
+import math
+
+import numpy as np
+import skia
+
+DEFAULT_FOV = 40.0
+# A point is drawn only while its w (distance from the camera over the focus distance) is above
+# this: closer than 1/20 of the way, a layer is magnified 20x and soon passes behind the lens.
+NEAR = 0.05
+
+
+def translate(x: float, y: float, z: float = 0.0) -> np.ndarray:
+    m = np.eye(4)
+    m[:3, 3] = x, y, z
+    return m
+
+
+def scale(sx: float, sy: float) -> np.ndarray:
+    return np.diag([sx, sy, 1.0, 1.0])
+
+
+def rotate_x(deg: float) -> np.ndarray:
+    c, s = math.cos(math.radians(deg)), math.sin(math.radians(deg))
+    return np.array([[1, 0, 0, 0], [0, c, -s, 0], [0, s, c, 0], [0, 0, 0, 1]], float)
+
+
+def rotate_y(deg: float) -> np.ndarray:
+    c, s = math.cos(math.radians(deg)), math.sin(math.radians(deg))
+    return np.array([[c, 0, s, 0], [0, 1, 0, 0], [-s, 0, c, 0], [0, 0, 0, 1]], float)
+
+
+def rotate_z(deg: float) -> np.ndarray:
+    """Clockwise on screen, like Canvas.rotate."""
+    c, s = math.cos(math.radians(deg)), math.sin(math.radians(deg))
+    return np.array([[c, -s, 0, 0], [s, c, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]], float)
+
+
+def tilt(z: float, rx: float, ry: float) -> np.ndarray:
+    """The depth part of a layer transform, applied between its translate and its rotate."""
+    return translate(0, 0, z) @ rotate_x(rx) @ rotate_y(ry)
+
+
+def camera(w: float, h: float, fov: float = DEFAULT_FOV, x: float = 0.0, y: float = 0.0, z: float = 0.0,
+           rx: float = 0.0, ry: float = 0.0, rz: float = 0.0) -> np.ndarray:
+    """World to canvas. The default camera looks at the canvas centre from the distance at which
+    `fov` (vertical, degrees) spans the canvas height, so z=0 maps to itself. x, y pan the camera
+    (and the point it orbits); z moves it back; ry orbits it right, rx up (looking down), rz rolls it."""
+    orbit = rotate_z(-rz) @ rotate_x(-rx) @ rotate_y(-ry)
+    return lens(w, h, fov) @ translate(0, 0, -z) @ orbit @ translate(-w / 2 - x, -h / 2 - y)
+
+
+def lens(w: float, h: float, fov: float = DEFAULT_FOV) -> np.ndarray:
+    """The projection part of `camera`: camera space (origin at the canvas centre) to canvas."""
+    focus = (h / 2) / math.tan(math.radians(min(max(fov, 1.0), 179.0)) / 2)
+    persp = np.eye(4)
+    persp[3, 2] = -1.0 / focus
+    return translate(w / 2, h / 2) @ persp
+
+
+def to_skia(m: np.ndarray) -> skia.M44:
+    return skia.M44.Rows(*(skia.V4(*row) for row in m.tolist()))
+
+
+def project(m: np.ndarray, box) -> tuple[np.ndarray, np.ndarray]:
+    """Canvas positions and w of a local rect's corners (TL, TR, BR, BL) at z=0."""
+    bx, by, bw, bh = box
+    bw, bh = bw or 1.0, bh or 1.0
+    pts = np.array([[bx, by, 0, 1], [bx + bw, by, 0, 1], [bx + bw, by + bh, 0, 1], [bx, by + bh, 0, 1]], float)
+    out = pts @ m.T
+    w = out[:, 3]
+    return out[:, :2] / np.where(np.abs(w) < 1e-9, 1e-9, w)[:, None], w
+
+
+def facing(xy: np.ndarray) -> bool:
+    """True while the rect whose projected corners are `xy` shows its front."""
+    (x0, y0), (x1, y1), _, (x3, y3) = xy
+    return (x1 - x0) * (y3 - y0) - (y1 - y0) * (x3 - x0) >= 0

kinescript/svgpath.py

@@ -0,0 +1,80 @@
+"""SVG path data ('M10 10 L 90 90 Q ...') to skia.Path. skia-python ships no parser."""
+from __future__ import annotations
+
+import re
+
+import skia
+
+_TOK = re.compile(r"[MmLlHhVvCcSsQqTtAaZz]|-?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?")
+_ARGS = {"M": 2, "L": 2, "H": 1, "V": 1, "C": 6, "S": 4, "Q": 4, "T": 2, "A": 7, "Z": 0}
+
+
+def parse(d: str) -> skia.Path:
+    toks = _TOK.findall(d)
+    path = skia.Path()
+    i, cmd = 0, None
+    cx = cy = sx = sy = 0.0
+    last_ctrl: tuple[float, float] | None = None
+    last_cmd = ""
+    while i < len(toks):
+        if toks[i].isalpha():
+            cmd = toks[i]
+            i += 1
+            if cmd in "Zz":
+                path.close()
+                cx, cy = sx, sy
+                last_cmd = "Z"
+                continue
+        if cmd is None:
+            raise ValueError(f"path data must start with a command: {d[:40]!r}")
+        n = _ARGS[cmd.upper()]
+        vals = [float(v) for v in toks[i:i + n]]
+        if len(vals) < n:
+            raise ValueError(f"path command {cmd} needs {n} numbers")
+        i += n
+        rel = cmd.islower()
+        U = cmd.upper()
+        ox, oy = (cx, cy) if rel else (0.0, 0.0)
+        if U == "M":
+            cx, cy = vals[0] + ox, vals[1] + oy
+            path.moveTo(cx, cy)
+            sx, sy = cx, cy
+            cmd = "l" if rel else "L"  # extra pairs after M are line-tos
+        elif U == "L":
+            cx, cy = vals[0] + ox, vals[1] + oy
+            path.lineTo(cx, cy)
+        elif U == "H":
+            cx = vals[0] + (cx if rel else 0)
+            path.lineTo(cx, cy)
+        elif U == "V":
+            cy = vals[0] + (cy if rel else 0)
+            path.lineTo(cx, cy)
+        elif U == "C":
+            x1, y1, x2, y2, x, y = vals
+            path.cubicTo(x1 + ox, y1 + oy, x2 + ox, y2 + oy, x + ox, y + oy)
+            last_ctrl = (x2 + ox, y2 + oy)
+            cx, cy = x + ox, y + oy
+        elif U == "S":
+            x2, y2, x, y = vals
+            x1, y1 = (2 * cx - last_ctrl[0], 2 * cy - last_ctrl[1]) if last_ctrl and last_cmd in "CS" else (cx, cy)
+            path.cubicTo(x1, y1, x2 + ox, y2 + oy, x + ox, y + oy)
+            last_ctrl = (x2 + ox, y2 + oy)
+            cx, cy = x + ox, y + oy
+        elif U == "Q":
+            x1, y1, x, y = vals
+            path.quadTo(x1 + ox, y1 + oy, x + ox, y + oy)
+            last_ctrl = (x1 + ox, y1 + oy)
+            cx, cy = x + ox, y + oy
+        elif U == "T":
+            x, y = vals
+            x1, y1 = (2 * cx - last_ctrl[0], 2 * cy - last_ctrl[1]) if last_ctrl and last_cmd in "QT" else (cx, cy)
+            path.quadTo(x1, y1, x + ox, y + oy)
+            last_ctrl = (x1, y1)
+            cx, cy = x + ox, y + oy
+        elif U == "A":
+            rx, ry, rot, large, sweep, x, y = vals
+            path.arcTo(rx, ry, rot, skia.Path.ArcSize.kLarge_ArcSize if large else skia.Path.ArcSize.kSmall_ArcSize,
+                       skia.PathDirection.kCW if sweep else skia.PathDirection.kCCW, x + ox, y + oy)
+            cx, cy = x + ox, y + oy
+        last_cmd = U
+    return path

kinescript/timing.py

@@ -0,0 +1,169 @@
+"""Cue-graph timing: start/end times written as references to other layers.
+
+    "at": 1.5               seconds
+    "at": "45f"             frames
+    "at": "0:02.5"          m:ss
+    "at": "title.out+0.2"   0.2 s after layer 'title' ends
+    "at": "prev.in+10f"     10 frames after the previous layer starts
+    "at": "drop"            a named marker from scene "markers"
+
+Change one duration and everything cued from it moves with it.
+"""
+from __future__ import annotations
+
+import re
+
+_TERM = re.compile(r"\s*([+-])\s*(\d+(?:\.\d+)?)\s*(s|f|ms)?\s*")
+_BASE = re.compile(r"^\s*([A-Za-z_][\w-]*)(?:\.(in|out|mid))?")
+
+
+class TimingError(ValueError):
+    def __init__(self, message: str, layer: str | None = None):
+        super().__init__(message)
+        self.layer = layer
+
+
+FORMS = ('a number of seconds (1.5), "45f" (frames), "0:02.5", "title.out+0.2" (0.2 s after layer title ends), '
+         '"title.in", "title.mid", "prev.out", or a marker name')
+
+
+def parse_clock(s: str, fps: float) -> float | None:
+    s = s.strip()
+    m = re.fullmatch(r"(-?\d+(?:\.\d+)?)\s*(s|f|ms)?", s)
+    if m:
+        v = float(m.group(1))
+        return v / fps if m.group(2) == "f" else v / 1000 if m.group(2) == "ms" else v
+    m = re.fullmatch(r"(\d+):(\d+(?:\.\d+)?)", s)
+    if m:
+        return int(m.group(1)) * 60 + float(m.group(2))
+    return None
+
+
+def split_ref(expr: str) -> tuple[str | None, str, str]:
+    """'title.out+0.2' -> ('title', 'out', '+0.2'). Plain clocks return (None, '', expr)."""
+    m = _BASE.match(expr)
+    if not m or parse_clock(expr, 30) is not None:
+        return None, "", expr
+    return m.group(1), m.group(2) or "", expr[m.end():]
+
+
+def offset(rest: str, fps: float) -> float:
+    total, pos = 0.0, 0
+    while pos < len(rest):
+        m = _TERM.match(rest, pos)
+        if not m or m.end() == pos:
+            raise TimingError(f"cannot parse time offset {rest!r}")
+        v = float(m.group(2))
+        v = v / fps if m.group(3) == "f" else v / 1000 if m.group(3) == "ms" else v
+        total += v if m.group(1) == "+" else -v
+        pos = m.end()
+    return total
+
+
+class Timeline:
+    """Resolves in/out for every layer, following references depth-first."""
+
+    def __init__(self, fps: float, markers: dict[str, float] | None = None):
+        self.fps = fps
+        self.markers = {k: float(v) for k, v in (markers or {}).items()}
+        self.nodes: dict[str, dict] = {}
+        self.order: list[str] = []
+        self.resolved: dict[str, tuple[float, float | None]] = {}
+        self._stack: list[str] = []
+
+    def add(self, lid: str, at, dur=None, until=None, natural: float | None = None,
+            prev: str | None = None, parent: str | None = None, default_end: str | None = None):
+        if lid in self.nodes:
+            raise TimingError(f"duplicate layer id '{lid}'; every id must be unique", lid)
+        self.nodes[lid] = dict(at=at, dur=dur, until=until, natural=natural, prev=prev,
+                               parent=parent, default_end=default_end)
+        self.order.append(lid)
+
+    def _time(self, v, owner: str, base: float) -> float:
+        if v is None:
+            return base
+        if isinstance(v, (int, float)):
+            return base + float(v)
+        s = str(v)
+        clk = parse_clock(s, self.fps)
+        if clk is not None:
+            return base + clk
+        name, edge, rest = split_ref(s)
+        if name is None:
+            raise TimingError(f"cannot read the time {s!r}. Write {FORMS}", owner)
+        if name == "prev":
+            name = self.nodes[owner]["prev"] if owner in self.nodes else None
+            if name is None:
+                raise TimingError("'prev' used on the first layer, which has no previous layer", owner)
+        if name in self.markers and not edge:
+            t = self.markers[name]
+        elif name == "start":
+            t = 0.0
+        elif name in self.nodes:
+            t_in, t_out = self.resolve(name)
+            if edge in ("", "in"):
+                t = t_in
+            else:
+                if t_out is None:
+                    raise TimingError(f"refers to '{name}.{edge}', but '{name}' runs to the scene end, so it has "
+                                      f"no end time. Give '{name}' a dur or until", owner)
+                t = t_out if edge == "out" else (t_in + t_out) / 2
+        else:
+            from .schema import suggest
+            options = list(self.nodes) + list(self.markers)
+            close = suggest(name, options)
+            known = ", ".join(options[:16])
+            if " " in s.strip():
+                raise TimingError(f"cannot read the time {s!r}. Write {FORMS}", owner)
+            raise TimingError(f"unknown reference '{name}' in {s!r}." + (f" Did you mean '{close}'?" if close else "")
+                              + f" Layer ids and markers: {known}", owner)
+        try:
+            return t + offset(rest, self.fps)
+        except TimingError as e:
+            raise TimingError(f"{e} in {s!r}. Write {FORMS}", owner) from None
+
+    def resolve(self, lid: str) -> tuple[float, float | None]:
+        if lid in self.resolved:
+            return self.resolved[lid]
+        if lid in self._stack:
+            raise TimingError("timing cycle: " + " -> ".join(self._stack + [lid])
+                              + ". A layer cannot start or end relative to itself", lid)
+        self._stack.append(lid)
+        n = self.nodes[lid]
+        base = self.resolve(n["parent"])[0] if n["parent"] else 0.0
+        t_in = self._time(n["at"], lid, base)
+        until = n["until"]
+        if n["dur"] is not None:
+            d = n["dur"]
+            if isinstance(d, str):
+                clk = parse_clock(d, self.fps)
+                if clk is None:
+                    raise TimingError(f"dur {d!r} is not a length of time; use seconds like 2.5, or \"45f\"", lid)
+                d = clk
+            t_out: float | None = t_in + float(d)
+        elif until is not None and until != "end":
+            t_out = self._time(until, lid, base)
+        elif n["natural"] is not None and until != "end":
+            t_out = t_in + n["natural"]
+        elif n["default_end"] is not None and until != "end":
+            t_out = self.resolve(n["default_end"])[1]
+        else:
+            t_out = None  # open: runs to the scene end
+        if t_out is not None and t_out <= t_in:
+            raise TimingError(f"ends at {t_out:.3f}s, which is not after its start at {t_in:.3f}s", lid)
+        self._stack.pop()
+        self.resolved[lid] = (t_in, t_out)
+        return t_in, t_out
+
+    def solve(self, duration=None) -> float:
+        for lid in self.order:
+            self.resolve(lid)
+        if duration not in (None, "auto"):
+            end = self._time(duration, "canvas", 0.0)
+        else:
+            ends = [o for _, o in self.resolved.values() if o is not None]
+            end = max(ends) if ends else 5.0
+        for lid, (i, o) in list(self.resolved.items()):
+            if o is None:
+                self.resolved[lid] = (i, max(end, i + 1 / self.fps))
+        return end

kinescript/verify.py

@@ -0,0 +1,261 @@
+"""Agent-side verification: contact sheets, layout lint and frame probes.
+
+An agent cannot watch a video. These turn a scene into things it can read: one image of
+many timestamps, a JSON list of problems with time ranges, and the exact box of every layer.
+"""
+from __future__ import annotations
+
+import math
+
+import numpy as np
+import skia
+
+from . import color as C
+from .render import FONT_DIR, Renderer, _argb
+from .scene import Scene, SceneError, load
+
+# Model triangles one frame may draw before check warns. 100,000 took 71 ms a frame at 1080p on
+# the GPU in the 3D spike (2026-10-29), against about 15 ms at 20,000.
+TRIANGLE_BUDGET = 60_000
+
+
+def _times(scene: Scene, count: int, times=None) -> list[float]:
+    if times:
+        return [float(t) for t in times]
+    count = max(1, count)
+    step = scene.duration / count
+    return [min(scene.duration - 1 / scene.fps, step * (k + 0.5)) for k in range(count)]
+
+
+def contact_sheet(src, out: str, count: int = 12, cols: int | None = None, width: int = 480,
+                  times=None, boxes: bool = False) -> dict:
+    """One PNG of `count` evenly spaced frames, each labelled with its time and frame number.
+    boxes=True outlines every visible layer with its id."""
+    scene = load(src)
+    ts = _times(scene, count, times)
+    cols = cols or min(len(ts), 4)
+    rows = math.ceil(len(ts) / cols)
+    scale = width / scene.w
+    r = Renderer(scene, track=boxes, scale=scale)
+    tw, th = r.w, r.h
+    gap, label_h = 8, 26
+    sheet = skia.Surface(cols * (tw + gap) + gap, rows * (th + label_h + gap) + gap)
+    c = sheet.getCanvas()
+    c.clear(_argb("#0a0c10"))
+    mono = skia.Typeface.MakeFromFile(str(FONT_DIR / "IBMPlexMono-Medium.ttf"))
+    font = skia.Font(mono, 15)
+    small = skia.Font(mono, 11)
+    for k, T in enumerate(ts):
+        n = int(round(T * scene.fps))
+        arr = r.frame(n)
+        img = skia.Image.fromarray(np.ascontiguousarray(arr), colorType=skia.kRGBA_8888_ColorType)
+        x = gap + (k % cols) * (tw + gap)
+        y = gap + (k // cols) * (th + label_h + gap)
+        c.drawImage(img, x, y + label_h)
+        c.drawString(f"{T:6.2f}s  f{n}", x + 2, y + 18, font, skia.Paint(AntiAlias=True, Color=_argb("#f2f0e8")))
+        if boxes:
+            _draw_boxes(c, scene, r.boxes, x, y + label_h, tw, th, small)
+    sheet.makeImageSnapshot().save(out, skia.kPNG)
+    scene.close()
+    return {"out": out, "times": [round(t, 3) for t in ts], "grid": [cols, rows], "backend": r.backend}
+
+
+def _behind(boxes: dict, lid: str, a: list, w: int, h: int) -> str | None:
+    """The shape or media layer drawn before `lid` that covers most of its box, if any.
+    `boxes` is in draw order, so every entry before `lid` is underneath it. Layers that fill the
+    canvas are skipped: under a background the colour is wrong, not the placement."""
+    best, area = None, 0.0
+    for other, b in boxes.items():
+        if other == lid:
+            break
+        r = b["rect"]
+        if (b["type"] in ("text", "counter", "captions", "group") or b["alpha"] < 0.5
+                or (r[0] <= 0 and r[1] <= 0 and r[2] >= w and r[3] >= h)):
+            continue
+        ix, iy = min(a[2], r[2]) - max(a[0], r[0]), min(a[3], r[3]) - max(a[1], r[1])
+        if ix > 0 and iy > 0 and ix * iy > area:
+            best, area = other, ix * iy
+    return best
+
+
+def _draw_boxes(c, scene: Scene, boxes: dict, ox: float, oy: float, tw: float, th: float, font):
+    """Outline every visible layer; label only top-level layers, on a dark tab just outside the box,
+    so labels neither cover the text they name nor pile up for every child of a component."""
+    line = skia.Paint(AntiAlias=True, Style=skia.Paint.kStroke_Style, StrokeWidth=1, Color=_argb("#b9f45d"))
+    tab = skia.Paint(AntiAlias=True, Color=_argb("#0a0c10d8"))
+    ink = skia.Paint(AntiAlias=True, Color=_argb("#b9f45d"))
+    taken: list[skia.Rect] = []
+    c.save()
+    c.clipRect(skia.Rect.MakeXYWH(ox, oy, tw, th))
+    for lid, b in boxes.items():
+        if b["alpha"] < 0.05:
+            continue
+        l, t_, rr, bb = b["rect"]  # already in thumbnail pixels (the renderer is scaled)
+        c.drawRect(skia.Rect(ox + l, oy + t_, ox + rr, oy + bb), line)
+        layer = scene.by_id.get(lid)
+        if layer is not None and layer.parent is not None:
+            continue
+        w = font.measureText(lid) + 6
+        lx = min(max(ox, ox + l), ox + tw - w)
+        ly = oy + t_ - 14 if t_ - 14 >= 0 else oy + bb  # above the box, or below it at the top edge
+        rect = skia.Rect.MakeXYWH(lx, ly, w, 14)
+        if any(rect.intersect(o) for o in taken):
+            continue  # skip a label that would sit on another; the outline still shows
+        taken.append(rect)
+        c.drawRect(rect, tab)
+        c.drawString(lid, lx + 3, ly + 11, font, ink)
+    c.restore()
+
+
+def probe(src, at: float | None = None) -> dict:
+    """Resolved timeline; with `at`, also every visible layer's screen box at that time."""
+    scene = load(src)
+    out = scene.summary()
+    if at is not None:
+        r = Renderer(scene, track=True)
+        r.draw(float(at))
+        out["at"] = float(at)
+        out["visible"] = r.boxes
+    scene.close()
+    return out
+
+
+def _words(text: str) -> int:
+    return len([w for w in text.replace("**", "").split() if any(ch.isalnum() for ch in w)])
+
+
+def check(src, step: float = 0.25, safe: float = 0.05) -> dict:
+    """Lint a scene. Returns {"ok", "errors", "warnings", "issues": [...]} where each issue names
+    the layer, the time range it was seen in, and a suggested fix."""
+    try:
+        scene = load(src)
+    except SceneError as e:
+        return _result(e.issues)
+    except (ValueError, FileNotFoundError, RuntimeError, OSError) as e:
+        return _result([{"level": "error", "code": "load", "layer": None, "message": str(e), "fix": ""}])
+    W, H = scene.w, scene.h
+    r = Renderer(scene, track=True, scale=1.0)
+    found: dict[tuple, dict] = {}
+
+    def add(level, code, lid, T, msg, fix="", until=None):
+        key = (code, lid)
+        it = found.get(key)
+        if it is None:
+            found[key] = {"level": level, "code": code, "layer": lid, "from": round(T, 2),
+                          "to": round(T if until is None else until, 2), "message": msg, "fix": fix}
+        else:
+            it["to"] = round(T, 2)
+
+    n = max(1, int(scene.duration / step))
+    for k in range(n + 1):
+        T = min(scene.duration - 1e-3, k * step)
+        try:
+            r.draw(T)
+        except (ValueError, RuntimeError, OSError) as e:
+            scene.close()
+            return _result(scene.issues + [{"level": "error", "code": "render", "layer": None, "from": round(T, 2),
+                                            "to": round(T, 2), "message": f"{type(e).__name__}: {e}", "fix": ""}],
+                           duration=scene.duration)
+        for lid in r.culled:
+            msg = ("the triangles of this model that cross the camera plane are not drawn"
+                   if scene.by_id[lid].type == "model" else "layer crosses the camera plane, so it is not drawn")
+            add("warning", "behind-camera", lid, T, msg, "lower its z, or move the camera back (a higher camera z)")
+        if r.tris > TRIANGLE_BUDGET:
+            add("warning", "triangle-budget", None, T, f"{r.tris:,} model triangles in one frame; renders slow "
+                f"down past {TRIANGLE_BUDGET:,} (about 70 ms a frame at 100,000 on a GPU)",
+                "use \"detail\": \"low\" or \"medium\", or fewer parts")
+        texts = []
+        for lid, b in r.boxes.items():
+            if b["alpha"] < 0.3:
+                continue
+            l, t, rr, bb = b["rect"]
+            layer = scene.by_id.get(lid)
+            allow = layer is not None and layer.raw.get("allowOffscreen")
+            if b["type"] in ("text", "counter", "captions"):
+                texts.append((lid, b))
+                if b.get("mirrored"):
+                    add("warning", "mirrored-text", lid, T, "text faces away from the camera, so it reads mirrored",
+                        "keep rotateX and rotateY within ±90°, or set \"backface\": \"hidden\" and add a back side")
+                if (l < -1 or t < -1 or rr > W + 1 or bb > H + 1) and not allow:
+                    add("error", "text-offscreen", lid, T, f"text box {b['rect']} leaves the {W}x{H} canvas",
+                        "move it inward, lower size, or set maxWidth")
+                elif (l < W * safe or t < H * safe or rr > W * (1 - safe) or bb > H * (1 - safe)) and not allow:
+                    add("warning", "safe-area", lid, T, f"text is inside the outer {int(safe * 100)}% margin",
+                        "keep titles within the title-safe area")
+                px = b["size"] * b.get("scale", 1)
+                if px < H / 45 and b["alpha"] > 0.9:
+                    add("warning", "tiny-text", lid, T, f"text renders at ~{px:.0f}px, small for {H}p video",
+                        f"use at least {math.ceil(H / 45)}px")
+            elif b["type"] not in ("video", "group") and not allow:
+                if rr < 0 or bb < 0 or l > W or t > H:
+                    add("info", "offscreen", lid, T, "layer is visible but entirely off canvas", "check x/y")
+        for i in range(len(texts)):
+            for j in range(i + 1, len(texts)):
+                a, b2 = texts[i][1]["rect"], texts[j][1]["rect"]
+                ix = min(a[2], b2[2]) - max(a[0], b2[0])
+                iy = min(a[3], b2[3]) - max(a[1], b2[1])
+                if ix > 4 and iy > 4:
+                    area = min((a[2] - a[0]) * (a[3] - a[1]), (b2[2] - b2[0]) * (b2[3] - b2[1])) or 1
+                    if ix * iy / area > 0.15:
+                        add("warning", "text-overlap", f"{texts[i][0]}+{texts[j][0]}", T,
+                            "two text layers overlap", "offset one of them or separate them in time")
+    # Contrast: render the frame without the text layer and its successors, compare luminance under its box.
+    for layer in scene.all_layers():
+        if layer.type not in ("text", "counter"):
+            continue
+        T = min(layer.t_out - 1e-3, layer.t_in + min(layer.dur * 0.6, 1.5))
+        r.draw(T)
+        b = r.boxes.get(layer.id)
+        if not b or b["alpha"] < 0.5 or not b.get("fill") or layer.raw.get("box"):
+            continue
+        r.draw(T, stop_at=layer.id)
+        buf = np.empty((r.h, r.w, 4), np.uint8)
+        r.surface.readPixels(r.info, buf, r.w * 4)
+        l, t, rr, bb = (int(max(0, v)) for v in b["rect"])
+        rr, bb = min(r.w, rr), min(r.h, bb)
+        if rr - l < 2 or bb - t < 2:
+            continue
+        patch = buf[t:bb, l:rr, :3].reshape(-1, 3).astype(np.float32) / 255
+        lin = np.where(patch <= 0.04045, patch / 12.92, ((patch + 0.055) / 1.055) ** 2.4)
+        lum = lin @ np.array([0.2126, 0.7152, 0.0722], np.float32)
+        fg = C.luminance(tuple(b["fill"]))
+        worst = min(C.contrast(fg, float(np.percentile(lum, 10))), C.contrast(fg, float(np.percentile(lum, 90))))
+        if worst < 3.0:
+            under = _behind(r.boxes, layer.id, b["rect"], r.w, r.h)
+            add("warning", "contrast", layer.id, T, f"contrast against what is behind it is {worst:.1f}:1 (want 4.5:1)"
+                + (f"; it overlaps '{under}'" if under else ""),
+                f"move it clear of '{under}', or add a box or a shadow" if under
+                else "add a box, a shadow, or change the colour")
+    # Reading time.
+    for layer in scene.all_layers():
+        if layer.type == "text":
+            words = _words(str(layer.raw.get("text", "")))
+            need = 0.4 + words / 3.3
+            if words >= 3 and layer.dur < need:
+                add("warning", "read-time", layer.id, layer.t_in,
+                    f"{words} words on screen for {layer.dur:.2f}s; viewers need ~{need:.1f}s", "extend dur or cut words",
+                    until=layer.t_out)
+        if layer.type == "captions":
+            for s0, s1, txt in layer.raw.get("cues", []):
+                words = _words(txt)
+                if words and (s1 - s0) < 0.25 + words / 4.5:
+                    add("warning", "read-time", layer.id, layer.t_in + s0,
+                        f"caption '{txt[:30]}' is {s1 - s0:.2f}s for {words} words", "split or lengthen the cue",
+                        until=layer.t_in + s1)
+                    break
+    scene.close()
+    return _result(scene.issues + list(found.values()), duration=scene.duration)
+
+
+_RANK = {"error": 0, "warning": 1, "info": 2}
+
+
+def _result(issues: list[dict], duration: float | None = None) -> dict:
+    """Errors first, then warnings, then info notes. `ok` is true when there are no errors."""
+    issues = sorted(issues, key=lambda i: (_RANK[i["level"]], i.get("from", -1)))
+    errors = sum(1 for i in issues if i["level"] == "error")
+    out = {"ok": errors == 0, "errors": errors, "warnings": sum(1 for i in issues if i["level"] == "warning"),
+           "issues": issues}
+    if duration is not None:
+        out["duration"] = round(duration, 3)
+    return out