wizz-method 2.21.0 → 2.22.0

package/src/skills-lib/wizz-video-effects/scripts/test_chrome.py

@@ -0,0 +1,181 @@
+# -*- coding: utf-8 -*-
+"""Tests of check_chrome.py: the page-chrome / slide-look rules on a layout
+snapshot (DOM of a HyperFrames composition) and on the text layers of a
+Remotion timeline."""
+import io
+import json
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+
+import check_chrome as CC
+from config import TEMPLATE, load
+
+CFG = load(TEMPLATE)
+RULES = CC.rules(CFG)[0]
+W, H = 1080, 1920
+
+
+def block(text, x0, y0, x1, y1, font=60, **kw):
+    return {"text": text, "box": [x0 * W, y0 * H, x1 * W, y1 * H], "font_px": font, **kw}
+
+
+def snap(*blocks, shapes=(), t=1.0):
+    return {"width": W, "height": H, "samples": [{"t": t, "blocks": list(blocks), "shapes": list(shapes)}]}
+
+
+def lint(data, allow=()):
+    samples = CC.samples_from_snapshot(data)
+    return CC.lint(samples, RULES, set(allow))
+
+
+def rules_hit(rep):
+    return {h["rule"] for h in rep["hits"]}
+
+
+class TestPageChrome(unittest.TestCase):
+    def test_clean_reel_passes(self):
+        rep = lint(snap(block("O erro que custa caro", 0.1, 0.40, 0.9, 0.48, font=96, align="center"),
+                        block("custa", 0.35, 0.70, 0.65, 0.74, font=72, role="caption")))
+        self.assertTrue(rep["passed"], rep["hits"])
+
+    def test_corner_brand_label_fails(self):
+        rep = lint(snap(block("WIZZ", 0.05, 0.03, 0.15, 0.05, font=30)))
+        self.assertIn("C1", rules_hit(rep))
+        self.assertFalse(rep["passed"])
+
+    def test_tracked_caps_label_fails(self):
+        rep = lint(snap(block("NOVO MÉTODO", 0.3, 0.30, 0.7, 0.32, font=36, caps=True, tracking_em=0.2)))
+        self.assertIn("C2", rules_hit(rep))
+
+    def test_counter_fails(self):
+        for text in ("02 / 05", "01 - THE WAIT", "Parte 3", "Step 2"):
+            with self.subTest(text=text):
+                rep = lint(snap(block(text, 0.4, 0.5, 0.6, 0.52, font=40)))
+                self.assertIn("C3", rules_hit(rep))
+
+    def test_twenty_four_seven_is_not_a_counter(self):
+        rep = lint(snap(block("24/7 suporte", 0.4, 0.5, 0.6, 0.52, font=40)))
+        self.assertNotIn("C3", rules_hit(rep))
+
+    def test_timecode_and_metadata_fail(self):
+        for text in ("00:00:12", "30 FPS", "1080x1920", "REC"):
+            with self.subTest(text=text):
+                rep = lint(snap(block(text, 0.4, 0.5, 0.6, 0.52, font=40)))
+                self.assertIn("C4", rules_hit(rep))
+
+    def test_progress_bar_growing_fails(self):
+        data = {"width": W, "height": H, "samples": [
+            {"t": t, "blocks": [], "shapes": [{"id": "bar", "kind": "bar", "box": [0, 10, w * W, 18]}]}
+            for t, w in ((1.0, 0.1), (2.0, 0.3), (3.0, 0.5))]}
+        rep = lint(data)
+        self.assertIn("P1", rules_hit(rep))
+
+    def test_header_bar_fails(self):
+        rep = lint(snap(shapes=[{"kind": "bar", "box": [0, 0, W, 0.06 * H], "filled": True}]))
+        self.assertIn("C6", rules_hit(rep))
+
+    def test_full_frame_background_is_not_a_bar(self):
+        rep = lint(snap(shapes=[{"kind": "bar", "box": [0, 0, W, H], "filled": True}]))
+        self.assertNotIn("C6", rules_hit(rep))
+
+    def test_kicker_over_headline_fails(self):
+        rep = lint(snap(block("o segredo", 0.1, 0.38, 0.4, 0.40, font=30),
+                        block("Pare de perder dinheiro", 0.1, 0.41, 0.9, 0.47, font=90)))
+        self.assertIn("C7", rules_hit(rep))
+
+    def test_left_headline_beside_right_media_fails(self):
+        rep = lint(snap(block("Seu app", 0.05, 0.40, 0.45, 0.46, font=90, align="left"),
+                        shapes=[{"kind": "media", "box": [0.55 * W, 0.30 * H, 0.95 * W, 0.70 * H]}]))
+        hits = [h for h in rep["hits"] if h["rule"] == "D1"]
+        self.assertTrue(hits)
+        self.assertEqual(hits[0]["sev"], "FAIL")
+
+    def test_left_headline_alone_only_warns(self):
+        rep = lint(snap(block("Seu app", 0.05, 0.40, 0.45, 0.46, font=90, align="left")))
+        hits = [h for h in rep["hits"] if h["rule"] == "D1"]
+        self.assertEqual([h["sev"] for h in hits], ["WARN"])
+        self.assertTrue(rep["passed"])
+
+
+class TestExemptions(unittest.TestCase):
+    def test_caption_and_legal_roles_are_not_chrome(self):
+        rep = lint(snap(block("PARTE 2", 0.4, 0.5, 0.6, 0.52, font=40, role="caption"),
+                        block("Resultados variam. CNPJ 00.000", 0.05, 0.95, 0.6, 0.97, font=24, role="legal")))
+        self.assertTrue(rep["passed"], rep["hits"])
+
+    def test_allow_list_from_a_measured_style(self):
+        data = {"width": W, "height": H, "samples": [
+            {"t": t, "blocks": [], "shapes": [{"id": "bar", "kind": "bar", "box": [0, 10, w * W, 18]}]}
+            for t, w in ((1.0, 0.1), (2.0, 0.3), (3.0, 0.5))]}
+        rep = lint(data, allow={"P1"})
+        self.assertTrue(rep["passed"])
+        self.assertEqual(rep["allowed"], ["P1"])
+
+    def test_text_in_flight_is_not_a_held_label(self):
+        # Same label at a different place 0.1 s later: it is moving through
+        # the corner, not parked there.
+        data = {"width": W, "height": H, "samples": [
+            {"t": 1.0, "blocks": [block("WIZZ", 0.05, 0.03, 0.15, 0.05, font=30)], "shapes": []},
+            {"t": 1.1, "blocks": [block("WIZZ", 0.25, 0.20, 0.35, 0.22, font=30)], "shapes": []}]}
+        self.assertNotIn("C1", rules_hit(lint(data)))
+
+
+class TestTimeline(unittest.TestCase):
+    def test_remotion_text_layers_are_linted(self):
+        tl = {"duration": 10.0, "elements": [
+            {"at": 0.0, "until": 10.0, "kind": "text", "text": "02/05",
+             "box": [900, 40, 1040, 80], "font_px": 32},
+            {"at": 0.6, "kind": "text"}]}   # an element without text is skipped
+        samples = CC.samples_from_timeline(tl, CFG.frame.width, CFG.frame.height, RULES)
+        rep = CC.lint(samples, RULES, set())
+        self.assertIn("C3", rules_hit(rep))
+        self.assertIn("C1", rules_hit(rep))
+
+    def test_timeline_progress_bar_from_box_end(self):
+        tl = {"duration": 10.0, "elements": [
+            {"at": 0.0, "until": 10.0, "kind": "bar", "box": [0, 1880, 100, 1890],
+             "box_end": [0, 1880, 1080, 1890]}]}
+        samples = CC.samples_from_timeline(tl, W, H, RULES)
+        self.assertIn("P1", rules_hit(CC.lint(samples, RULES, set())))
+
+    def test_flash_label_shorter_than_held_s_is_skipped(self):
+        tl = {"duration": 5.0, "elements": [
+            {"at": 1.0, "until": 1.1, "kind": "text", "text": "WIZZ",
+             "box": [40, 40, 200, 80], "font_px": 30}]}
+        samples = CC.samples_from_timeline(tl, W, H, RULES)
+        self.assertNotIn("C1", rules_hit(CC.lint(samples, RULES, set())))
+
+
+class TestCli(unittest.TestCase):
+    def _run(self, args):
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            code = CC.main(["--config", str(TEMPLATE), *args])
+        return code, buf.getvalue()
+
+    def test_snapshot_fail_exits_1(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            p = Path(tmp) / "layout.json"
+            p.write_text(json.dumps(snap(block("00:00:12", 0.4, 0.5, 0.6, 0.52, font=40))), encoding="utf-8")
+            code, out = self._run(["--snapshot", str(p)])
+        self.assertEqual(code, 1, out)
+        self.assertIn("C4", out)
+
+    def test_timeline_allow_key_is_read(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            p = Path(tmp) / "t.json"
+            p.write_text(json.dumps({"duration": 5.0, "chrome_allow": ["C3"], "elements": [
+                {"at": 0.0, "until": 5.0, "kind": "text", "text": "Dia 3",
+                 "box": [400, 900, 680, 960], "font_px": 40}]}), encoding="utf-8")
+            code, out = self._run(["--timeline", str(p)])
+        self.assertEqual(code, 0, out)
+
+    def test_missing_input_exits_2(self):
+        code, _ = self._run(["--snapshot", "/nonexistent.json"])
+        self.assertEqual(code, 2)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/src/skills-lib/wizz-video-effects/scripts/test_dead_frames.py

@@ -0,0 +1,171 @@
+# -*- coding: utf-8 -*-
+"""Tests of check_dead_frames.py: flat-field runs (blocks), frozen picture
+(warns), the motion note, and the config fallback to the template. The
+ffmpeg round trip is skipped when ffmpeg is absent."""
+import copy
+import io
+import json
+import random
+import shutil
+import subprocess
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+
+import check_dead_frames as DF
+from config import TEMPLATE, load
+
+CFG = load(TEMPLATE)
+RULES = DF.rules(CFG)[0]
+W, H = RULES.width, RULES.height
+SIZE = W * H
+
+
+def flat(v: int = 0) -> bytes:
+    return bytes([v]) * SIZE
+
+
+def textured(seed: int, amp: int = 60) -> bytes:
+    rnd = random.Random(seed)
+    return bytes(100 + rnd.randrange(amp) for _ in range(SIZE))
+
+
+def jitter(base: bytes, seed: int, amp: int = 3) -> bytes:
+    """The same picture plus small per-pixel noise: a talking head that
+    barely moves (sensor noise, breathing, compression)."""
+    rnd = random.Random(seed)
+    return bytes(max(0, min(255, b + rnd.randrange(-amp, amp + 1))) for b in base)
+
+
+class TestFrameMeasures(unittest.TestCase):
+    def test_uniform_frame_is_flat(self):
+        self.assertTrue(DF.is_flat(flat(0), RULES))
+        self.assertTrue(DF.is_flat(flat(200), RULES))
+
+    def test_textured_frame_is_not_flat(self):
+        self.assertFalse(DF.is_flat(textured(1), RULES))
+
+    def test_dark_frame_with_one_small_caption_is_not_flat(self):
+        # Range catches it even when std-dev is tiny: that frame belongs to
+        # the density gate, not to this one.
+        f = bytearray(flat(10))
+        f[SIZE // 2:SIZE // 2 + 6] = bytes([250]) * 6
+        self.assertFalse(DF.is_flat(bytes(f), RULES))
+
+    def test_mean_abs_diff(self):
+        self.assertEqual(DF.mean_abs_diff(flat(10), flat(10)), 0.0)
+        self.assertAlmostEqual(DF.mean_abs_diff(flat(10), flat(14)), 4.0)
+
+    def test_runs(self):
+        self.assertEqual(DF.runs([False, True, True, False, True]), [(1, 2), (4, 4)])
+        self.assertEqual(DF.runs([]), [])
+
+
+class TestAnalyze(unittest.TestCase):
+    FPS = 30.0
+
+    def _rep(self, frames):
+        return DF.analyze(frames, self.FPS, RULES)
+
+    def test_short_black_dip_inside_a_transition_passes(self):
+        frames = [textured(i) for i in range(20)] + [flat()] * RULES.flat_max_frames \
+            + [textured(100 + i) for i in range(20)]
+        rep = self._rep(frames)
+        self.assertTrue(rep["passed"], rep)
+        self.assertEqual(rep["flat_fail"], [])
+        self.assertEqual(len(rep["flat_ignored"]), 1)
+
+    def test_black_gap_longer_than_the_limit_fails(self):
+        frames = [textured(i) for i in range(20)] + [flat()] * (RULES.flat_max_frames + 2) \
+            + [textured(100 + i) for i in range(20)]
+        rep = self._rep(frames)
+        self.assertFalse(rep["passed"])
+        (s, e), = rep["flat_fail"]
+        self.assertEqual((s, e), (20, 20 + RULES.flat_max_frames + 1))
+
+    def test_frozen_picture_warns_but_does_not_block(self):
+        still = textured(7)
+        n = int(self.FPS * (RULES.frozen_warn_s + 1.0))
+        frames = [textured(i) for i in range(10)] + [still] * n + [textured(50 + i) for i in range(10)]
+        rep = self._rep(frames)
+        self.assertTrue(rep["passed"])
+        self.assertEqual(len(rep["frozen_warn"]), 1)
+
+    def test_talking_head_micro_motion_is_not_frozen(self):
+        base = textured(3)
+        frames = [jitter(base, i) for i in range(int(self.FPS * 4))]
+        rep = self._rep(frames)
+        self.assertEqual(rep["frozen_warn"], [])
+        self.assertTrue(rep["passed"])
+
+    def test_motion_note_is_reported(self):
+        frames = [textured(i) for i in range(5)]
+        rep = self._rep(frames)
+        self.assertGreater(rep["motion_mean"], 0.0)
+
+    def test_no_frame_is_an_error(self):
+        with self.assertRaises(DF.ReadError):
+            self._rep([])
+
+
+class TestConfigFallback(unittest.TestCase):
+    def test_config_without_block_uses_template(self):
+        raw = json.loads(TEMPLATE.read_text(encoding="utf-8"))
+        raw = {k: v for k, v in copy.deepcopy(raw).items() if k != "dead_frames"}
+        with tempfile.TemporaryDirectory() as tmp:
+            p = Path(tmp) / "effects.config.json"
+            p.write_text(json.dumps(raw), encoding="utf-8")
+            r, from_template = DF.rules(load(p))
+        self.assertTrue(from_template)
+        self.assertEqual(r.flat_max_frames, RULES.flat_max_frames)
+
+    def test_incoherent_block_is_refused(self):
+        raw = json.loads(TEMPLATE.read_text(encoding="utf-8"))
+        raw["dead_frames"]["flat_max_frames"] = -1
+        with tempfile.TemporaryDirectory() as tmp:
+            p = Path(tmp) / "effects.config.json"
+            p.write_text(json.dumps(raw), encoding="utf-8")
+            with self.assertRaises(DF.ConfigError):
+                DF.rules(load(p))
+
+
+class TestCli(unittest.TestCase):
+    def test_missing_video_exits_2(self):
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            code = DF.main(["--config", str(TEMPLATE), "/nonexistent/final.mp4"])
+        self.assertEqual(code, 2)
+
+
+@unittest.skipUnless(shutil.which("ffmpeg") and shutil.which("ffprobe"), "ffmpeg not installed")
+class TestOnRealFile(unittest.TestCase):
+    def _make(self, tmp: str, black_s: float) -> str:
+        out = str(Path(tmp) / "piece.mp4")
+        src = ("testsrc2=size=270x480:rate=30:duration=1[a];"
+               f"color=black:size=270x480:rate=30:duration={black_s}[b];"
+               "testsrc2=size=270x480:rate=30:duration=1[c];[a][b][c]concat=n=3:v=1:a=0")
+        subprocess.run(["ffmpeg", "-v", "error", "-y", "-filter_complex", src,
+                        "-pix_fmt", "yuv420p", out], check=True)
+        return out
+
+    def _run(self, video: str) -> tuple[int, str]:
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            code = DF.main(["--config", str(TEMPLATE), video])
+        return code, buf.getvalue()
+
+    def test_half_second_black_gap_fails(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            code, out = self._run(self._make(tmp, 0.5))
+        self.assertEqual(code, 1, out)
+        self.assertIn("FLAT", out)
+
+    def test_one_frame_black_dip_passes(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            code, out = self._run(self._make(tmp, 1 / 30))
+        self.assertEqual(code, 0, out)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/src/skills-lib/wizz-video-styles/SKILL.md

@@ -29,13 +29,14 @@ Scripts live in this skill's `scripts/`; run them from the project root (the his
    - B-roll or stock, a physical product, food, a place?
    - Niche, goal of the piece (follow, comment, save, click), duration.
    Never pick a style the material cannot feed. "Talking head" needs a person on camera; "motion editorial" needs nothing but a voice; "macro / ASMR" needs a physical product filmed close.
-2. **Pick the style** with [references/style-picker.md](references/style-picker.md): material decides which styles are possible, niche and goal rank them. Mixed is allowed and common: person on camera for the hook and the CTA, another style in the middle. Before deciding, run `node scripts/references.mjs history` in the project: if the last two pieces used the same style, do not pick it a third time unless the user wants a series; choose another style the material allows, or keep it only for the hook and CTA.
-3. **Open the style card** in `references/styles/` and follow it: rhythm, captions, palette, typography, motion, music, SFX, hook, CTA, and its "do not" list.
+2. **Pick the style** with [references/style-picker.md](references/style-picker.md): material decides which styles are possible, niche and goal rank them. Mixed is allowed and common: person on camera for the hook and the CTA, another style in the middle. Before deciding, run `node scripts/references.mjs history` in the project: if the last two pieces used the same style, do not pick it a third time unless the user wants a series; choose another style the material allows, or keep it only for the hook and CTA. Also run `node scripts/taste.mjs show`: what this user already approved or rejected in this project outranks the catalogue's ranking.
+3. **Open the style card** in `references/styles/` and follow it: rhythm, captions, palette, typography, motion, music, SFX, hook, CTA, and its "do not" list. Where the card is silent on how things move, use [references/motion-laws.md](references/motion-laws.md).
 4. **Get fresh references and watch two** before editing: `node scripts/references.mjs pick --style <key>` returns measured references plus, for styles generated in code, current viral videos from the awesome-opus5-5-videos list, skipping everything this project already used. Reading a card is not watching a video. For how those generated videos were briefed, see [references/generated-prompts.md](references/generated-prompts.md).
 5. **Audio:** music and SFX choices from [references/audio.md](references/audio.md); the redistributable kit is in `assets/audio/` (credits in `assets/audio/CREDITS.md`).
 6. **Hand over** to `wizz-video-effects` with the card's SFX ceiling and music level, then to Remotion.
 7. **Look at the final file**: extract frames and compare them side by side with a contact sheet of one reference.
 8. **Record the piece**: `node scripts/references.mjs record --style <key> --piece <slug> --refs <ids watched>`. It writes `_wizz-output/video-styles/historico.json`, which is what keeps the next piece from repeating the same references and look.
+9. **Record the user's verdict** after they review it (with two versions, offer `python3 scripts/blind_review.py prepare <dir> a.mp4 b.mp4` first), in their words: `node scripts/taste.mjs add --verdict approved|rejected --piece <slug> --style <key> --quote "..." --lesson "..."` (appends to `_wizz-output/video-styles/gosto.md`; the narrowest lesson the reaction supports).
 
 ## What the measurements say across every style
 
@@ -52,12 +53,15 @@ Details and the per-style table: [references/measured-patterns.md](references/me
 |---|---|
 | [references/style-picker.md](references/style-picker.md) | **start here.** Material and niche → which styles |
 | [references/styles/](references/styles/) | one card per style: recipe, references, do-not list |
+| [references/motion-laws.md](references/motion-laws.md) | how things move when the card is silent: easing, scale, cuts, fades, springs, word cadence (measured on horizontal brand films) |
 | [references/measured-patterns.md](references/measured-patterns.md) | the numbers behind the cards, per style and per niche |
 | [references/audio.md](references/audio.md) | music and SFX per style, the kit, libraries and licences |
 | [references/research-method.md](references/research-method.md) | how the catalogue was measured, its limits, how to add a niche or a style |
 | `data/references.json` | every measured short: link, channel, views, niche, style, metrics |
 | [references/generated-prompts.md](references/generated-prompts.md) | prompts of viral code-generated videos, grouped by style, and how they run here |
 | `scripts/analyze.sh` | measures one short (cuts, music bed, SFX heuristics, loudness, contact sheet) |
+| `scripts/blind_review.py` | blind side-by-side page for two or more versions, answer key hidden until the pick |
+| `scripts/taste.mjs` | the user's approved and rejected verdicts for this project, read before choosing and appended after review |
 | `scripts/references.mjs` | fresh references per style without repeats, and the project's history of styles used |
 | `scripts/beat_grid.py` | BPM, beats and downbeats of a song, so cuts snap to the music (lyric video, kinetic typography) |
 | `assets/remotion/editorial/` | Remotion template of the motion editorial style |

package/src/skills-lib/wizz-video-styles/references/motion-laws.md

@@ -0,0 +1,62 @@
+# Motion laws: how things move inside a style
+
+The style cards say **what** moves (captions, counters, cards, b-roll). This page says **how** it moves when the card is silent: durations, curves, scale, fades and word cadence.
+
+## Where these numbers come from (read first)
+
+Every number here is a measurement by [motionmaxxing](https://github.com/Tejashmakwana/motionmaxxing) (Apache-2.0, credited in `THIRD-PARTY-NOTICES.md`): about 4,300 moves sampled frame by frame from 53 professional moments, plus whole films ranked by one human rater. Two limits follow from that sample:
+
+- It is **horizontal** (16:9) **brand and product launch films**, mostly 3 to 7 s UI-forward moments. It is **not** vertical Reels, talking heads or captioned shorts. Nothing here was measured on the catalogue in `data/references.json`.
+- Frames are counted at 30 fps (`f`). 1 f = 0.033 s, 6 f = 0.2 s, 10 f = 0.33 s, 15 f = 0.5 s.
+
+So: **when a style card states a number, the card wins** (it was measured on vertical shorts). Use these laws for what the card leaves open, mostly in screens drawn in code (HyperFrames, the Remotion templates) and in motion graphics over footage.
+
+## The laws
+
+### 1. Land decelerates, leave accelerates
+
+- An element that arrives eases **out**: most of its travel happens in the first 4 to 8 f, then a long tail, no bounce. 58% of measured landings ease out.
+- An element that leaves eases **in** and exits at peak speed: 37% of leaving moves accelerate (42% of scale exits, 63% of blur exits). Not every exit: shrink-to-centre and moves swept by a camera may stay linear.
+- Median move: **10 f** (0.33 s). Translate and scale entries about 12 f, opacity 6 f, blur 7 f; p25 to p75 roughly 6 to 24 f. A film where everything takes 20 to 30 f is slower than the whole sample.
+
+### 2. Nothing grows from zero
+
+- An object with identity (logo, key word, card, cursor) **arrives from oversize and scales down** to rest: logos from about 3.5x, a cursor 2 to 5x, an opening word from about 0.39 of the frame height down to 0.09.
+- Growth from small is the content only in a few cases: tiles in a 1-frame cascade, an object that becomes the next scene, an identity object that starts no smaller than about 0.3 to 0.6x.
+- Spend scale once. Most type is small; the ending usually gets smaller. This is about arrival, not a licence for a giant cropped word in every beat.
+
+### 3. Cut on motion
+
+- A cut lands mid-move, at peak speed, never on a settled frame. The next shot opens already moving.
+- A piece ends in motion or on a designed stillness, not on a fade to black by default.
+- In this pipeline the **instant** of a cut comes from a speech breath (`wizz-video-effects`, `fill_breaths.py`). The law adds the picture side: at that instant something should still be moving, so the cut does not land on a held frame.
+
+### 4. Almost nothing fades
+
+- Elements arrive and leave by **moving** (offset, scale, blur decaying), by a hard 1-frame cut, or by unmasking. Measured: 3,392 transform entries against 584 opacity fades; exits 60% moves, 15% fades, 25% hard steps.
+- Opacity is a 4 to 6 f helper under a move, not the move. A UI row or a word that should read as a state change hard-cuts on.
+- Fades are for single objects, not between scenes; a slow fade is a calm-brand choice with a stated reason.
+
+### 5. One spring per film
+
+- Overshoot is rare and late: 8.8% of moves overshoot by more than 3%, and 88% of those peak after 35% of the move (a slow lean past the mark and back), not a fast bounce.
+- At most **one visible spring** per film, on the payoff that deserves a physical reward. A bounce on every pop is the most common generated-video tell.
+- The Remotion templates use `spring()` for entries; keep their damping high enough that only one element per piece visibly bounces.
+
+### 6. Words move at speech rhythm
+
+Whole words, never letters (letter-by-letter typing belongs only inside the product's own input field). Gaps between word onsets:
+
+| Situation | Gap |
+|---|---|
+| Fast hook, inside a phrase | 2 to 4 f (0.07 to 0.12 s) |
+| Standard headline | 4 to 6 f (0.12 to 0.20 s), tightening toward the end |
+| Voice-led, thoughtful | 8 to 12 f (0.25 to 0.40 s), irregular |
+| Before the payoff word | 1.5 to 2x the base gap, once |
+
+With narration, captions follow the `wizz-ctc-align` timestamps (the voice is the clock) and on-screen words land 0 to 2 f before they are heard. The table is for type without a voice, or for building a headline word by word.
+
+## Related
+
+- What breathes and what is dead on the final file: `wizz-video-effects`, `check_dead_frames.py` (no run of flat frames; frozen picture warns).
+- Corner labels, counters, progress bars and slide layouts: `wizz-video-effects`, `check_chrome.py`.

package/src/skills-lib/wizz-video-styles/references/styles/desafio-numero.md

@@ -27,6 +27,7 @@ Food, money, products, everyday economics. The highest single reach in the set (
 **Look**
 
 - A visible progress device fixed on screen: time icons (1 s / 1 min / 1 h) changing colour per stage, emoji checklist, price tags on each ingredient.
+  It is measured for this style, so the chrome lint of `wizz-video-effects` takes `chrome_allow: ["P1", "C3"]` in the timeline (progress and stage counter).
 - Close hands, real places (market, street), a reaction at the end.
 
 **Palette:** Warm natural colours; tags in bright yellow with black outline; red/green icons for stages.

package/src/skills-lib/wizz-video-styles/scripts/blind_review.py

@@ -0,0 +1,159 @@
+# -*- coding: utf-8 -*-
+"""Blind A/B review of two or more versions of a piece.
+
+    python3 blind_review.py prepare OUT_DIR a.mp4 b.mp4 [c.mp4 ...]
+    python3 blind_review.py reveal OUT_DIR
+
+prepare: links (or copies) each film to OUT_DIR/A.mp4, B.mp4 ... in a random
+order, writes OUT_DIR/index.html (the films side by side at phone size, one
+play button for all, sound per film) and the answer key in
+OUT_DIR/.answer-key.json (mode 600). Running it again on the same folder and
+films keeps the earlier shuffle, so a verdict already given stays valid.
+reveal: prints which letter is which file. Only after the user picked.
+
+Do not open the key or compare file sizes before judging: both give the
+films away. Judge the picture silent first, then each soundtrack alone. The
+user's pick goes to taste.mjs add.
+
+Idea from motionmaxxing's blind_review.py (Apache-2.0,
+github.com/Tejashmakwana/motionmaxxing); see THIRD-PARTY-NOTICES.md.
+
+Exit code: 0 ok, 2 bad usage (fewer than 2 films, missing file, no key).
+"""
+from __future__ import annotations
+
+import argparse
+import html
+import json
+import os
+import secrets
+import shutil
+import string
+import sys
+from pathlib import Path
+
+KEY_NAME = ".answer-key.json"
+
+PAGE = """<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Blind review</title>
+<style>
+:root {{ color-scheme: light dark; --bg: #f6f5f2; --ink: #1b1b1b; }}
+@media (prefers-color-scheme: dark) {{ :root {{ --bg: #141414; --ink: #ececec; }} }}
+body {{ margin: 0; padding: 16px; background: var(--bg); color: var(--ink); font: 16px/1.4 system-ui, sans-serif; }}
+.row {{ display: flex; gap: 16px; flex-wrap: wrap; justify-content: center; }}
+figure {{ margin: 0; text-align: center; }}
+video {{ width: min(42vw, 360px); aspect-ratio: 9 / 16; background: #000; }}
+button {{ font: inherit; padding: 6px 14px; margin: 4px; }}
+p {{ max-width: 720px; margin: 8px auto 16px; text-align: center; }}
+</style>
+</head>
+<body>
+<p>Watch silent first, then each sound alone. Pick before revealing anything.</p>
+<p><button id="play">Play all</button><button id="restart">Restart</button></p>
+<div class="row">
+{figures}
+</div>
+<script>
+const vids = [...document.querySelectorAll("video")];
+document.getElementById("play").onclick = () => {{
+  const go = vids[0].paused;
+  vids.forEach((v) => (go ? v.play() : v.pause()));
+}};
+document.getElementById("restart").onclick = () => vids.forEach((v) => {{ v.currentTime = 0; }});
+document.querySelectorAll("[data-solo]").forEach((b) => {{
+  b.onclick = () => vids.forEach((v) => {{ v.muted = v.id !== b.dataset.solo; }});
+}});
+</script>
+</body>
+</html>
+"""
+
+FIGURE = """<figure>
+<video id="{letter}" src="{letter}.mp4" muted playsinline preload="auto"></video>
+<figcaption><strong>{letter}</strong> <button data-solo="{letter}">Sound of {letter} only</button></figcaption>
+</figure>"""
+
+
+def assign(films: list[str]) -> dict[str, str]:
+    """Letter -> film, in a random order from the OS random source."""
+    pool = list(films)
+    order = []
+    while pool:
+        order.append(pool.pop(secrets.randbelow(len(pool))))
+    return dict(zip(string.ascii_uppercase, order))
+
+
+def _place(src: str, dst: Path) -> None:
+    if dst.exists():
+        dst.unlink()
+    try:
+        os.link(src, dst)
+    except OSError:
+        shutil.copyfile(src, dst)
+
+
+def prepare(out: Path, films: list[str]) -> int:
+    films = [os.path.abspath(f) for f in films]
+    if len(films) < 2 or len(set(films)) != len(films):
+        print("ERROR: give at least two different films")
+        return 2
+    missing = [f for f in films if not os.path.isfile(f)]
+    if missing:
+        print(f"ERROR: not found: {', '.join(missing)}")
+        return 2
+    if len(films) > len(string.ascii_uppercase):
+        print("ERROR: too many films")
+        return 2
+    out.mkdir(parents=True, exist_ok=True)
+    key_file = out / KEY_NAME
+    key = None
+    if key_file.exists():
+        old = json.loads(key_file.read_text(encoding="utf-8"))
+        if sorted(old.values()) == sorted(films):
+            key = old
+    key = key or assign(films)
+    for letter, film in key.items():
+        _place(film, out / f"{letter}.mp4")
+    key_file.write_text(json.dumps(key, indent=1) + "\n", encoding="utf-8")
+    os.chmod(key_file, 0o600)
+    figures = "\n".join(FIGURE.format(letter=html.escape(letter)) for letter in key)
+    (out / "index.html").write_text(PAGE.format(figures=figures), encoding="utf-8")
+    print(f"open {out / 'index.html'}  ({len(key)} films, letters {', '.join(key)})")
+    print(f"after the pick: python3 blind_review.py reveal {out}")
+    return 0
+
+
+def reveal(out: Path) -> int:
+    key_file = out / KEY_NAME
+    if not key_file.exists():
+        print(f"ERROR: no answer key in {out}")
+        return 2
+    for letter, film in json.loads(key_file.read_text(encoding="utf-8")).items():
+        print(f"{letter}: {film}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Blind A/B review page for versions of a piece.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    p = sub.add_parser("prepare")
+    p.add_argument("out")
+    p.add_argument("films", nargs="+")
+    r = sub.add_parser("reveal")
+    r.add_argument("out")
+    args = ap.parse_args(argv)
+    try:
+        if args.cmd == "prepare":
+            return prepare(Path(args.out), args.films)
+        return reveal(Path(args.out))
+    except (OSError, json.JSONDecodeError) as e:
+        print(f"ERROR: {e}")
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())