wizz-method 2.22.0 → 2.23.0

package/src/skills-lib/wizz-video-effects/references/data-contract.md

@@ -42,6 +42,7 @@ Only `start` and `end` are required. Breaths are the gaps between words at least
 
 - `transition`: `cut`, `whip`, `zoom` or any name the renderer knows. Anything other than `""` or `cut` counts as a `transition` event in the budget. `fill_breaths.py` only fills scenes without a real transition (absent, `""` or `cut`); a transition the author declared is kept, and its `sfx` too when already set.
 - `sfx` (optional): the cut sound, played at `start`. Same shape as an `sfx[]` entry without `at`.
+- `carry` (optional, required on a one-take piece): one line saying what on screen survives the passage into this scene and what it becomes. Read by `check_one_take.py` ([one-take.md](one-take.md)).
 
 ### `sfx[]`
 
@@ -165,6 +166,7 @@ Written by `assets/chrome/collect_layout.js` from the opened HTML composition (i
 | --- | --- | --- | --- |
 | `fill_breaths.py TIMELINE [--narration F@OFF] [--visual MP4] [--write\|--out P]` | `words`, `scenes`, effects, `sfx`, `duration` | `scenes[].transition`, `scenes[].sfx`, `punches`, `flashes`, `sfx` | 0, 2 |
 | `sound.py duck TIMELINE [--write]` | `sfx`, `scenes[].sfx`, `words`, `fps` | `ducking` | 0, 2 |
+| `check_one_take.py FINAL.mp4 [--timeline T]` | `scenes[].carry`, `scenes[].transition` | nothing | 0 pass, 1 fail, 2 error |
 | `check_excess.py TIMELINE... [--warn]` | effects, `scenes`, `duration` | nothing | 0 pass, 1 fail, 2 error |
 | `check_rhythm.py TIMELINE...` | `scenes`, effects, `elements`, `duration` | nothing | always 0 (warn only) |
 | `check_chrome.py --timeline T \| --snapshot LAYOUT [--allow R]` | `elements[]` text layers and bars, `chrome_allow` (or the snapshot) | nothing | 0, 1, 2 |

package/src/skills-lib/wizz-video-effects/references/gates.md

@@ -17,6 +17,7 @@ Thresholds are cited by config key. Every script exits `0` pass, `1` fail, `2` i
 | `check_safe_zone.py` | **final MP4** | per row, local contrast (std-dev, `safe_zone_gate.dp_min`) on every frame; the highest and lowest content rows must sit inside the piece's profile (`safe_zones.<profile>` top and bottom) | yes | whether what invades is text, a card or background glow; left and right edges. Full-screen footage fails by construction: frame it inside the zone. On a fail, extract the frame and look |
 | `measure_density.py` | **final MP4** | how many of `density.n_bands` bands across the active safe zone have content (`density.dp_min`), sampled every `density.step_s`; fails under `density.min_filled` | yes | whether the content makes sense there: a band full of noise counts like a band full of information |
 | `check_dead_frames.py` | **final MP4**, every frame | runs of flat frames (one uniform field: `dead_frames.flat_std` and `dead_frames.flat_range` on a small luma copy); more than `dead_frames.flat_max_frames` in a row fails. Frozen picture (frame difference under `dead_frames.frozen_diff`) longer than `dead_frames.frozen_warn_s` only warns. Prints the mean motion against `dead_frames.motion_band_reference` as a question | yes for flat runs; frozen is a warning | a talking head is never flat and almost never frozen (noise, breathing, compression), so a dead shot on camera passes; grain or a looping background keeps a dead slide "moving"; a dark frame with one small line of text is not flat (that is density). Thresholds come from horizontal launch films (motionmaxxing G2), not from vertical Reels |
+| `check_one_take.py` | timeline JSON (`--timeline`) + **final MP4**, every frame | only on a piece meant as one take: every scene after the first declares `carry` and is not a plain `cut`; a frame whose change is above `one_take.cut_min_diff` and `one_take.cut_ratio` times the median of its `one_take.neighbour_frames` neighbours is a hard cut ([one-take.md](one-take.md)) | yes | a dissolve between unrelated scenes (no spike); whether the declared carry is really on screen; a cut hidden under a flash or a blur. Thresholds are a house rule, not measured on real one-take pieces |
 | `check_loudness.py` | **final MP4 or audio** | integrated loudness and true peak (ffmpeg `loudnorm`) against `loudness.*`; prints the two-pass fix and warns when the fix will switch loudnorm to dynamic compression | yes | the balance inside the mix (voice vs SFX); that is the level contract and the ear |
 
 Order that matches the pipeline: config and coverage once per project; excess, rhythm and chrome on the timeline before the expensive render; safe zone, density, dead frames and loudness on the final file.

package/src/skills-lib/wizz-video-effects/references/one-take.md

@@ -0,0 +1,41 @@
+# One take: a piece with no change of scene
+
+A one-take piece is one continuous shot. Nothing replaces anything: every beat grows out of something already on screen, and a single camera carries the viewer from the hook to the CTA. It fits pieces drawn in code (HyperFrames): a product film, a UI walkthrough, an explainer. It does not fit footage that was shot in separate takes. Idea seen in onetake (github.com/feitangyuan/onetake, PolyForm Noncommercial); nothing here is copied from it. The onetake skill itself is installable as the optional CLI `onetake` (designer area), free only for personal or noncommercial work; client work or content that sells needs onetake Pro. This technique needs neither.
+
+## The rule
+
+**No passage is only a change of scene.** At every boundary, something on screen survives and becomes the next beat. Write it in the timeline as the scene's `carry` ([data-contract.md](data-contract.md)), in one line: what it is and what it turns into. If that line cannot be written, the passage is a cut, and the piece is not one take.
+
+## Ways to carry
+
+- **Grow into:** an element of this beat becomes the frame of the next one (a price chip opens into the checkout card; a search bar opens into the app window).
+- **Push through:** the camera flies into an element (a card, a phone screen, a letter of the headline) until its inside is the next scene.
+- **Pull back:** the camera opens from a detail to reveal it was part of a bigger picture (one cell of a table, one post in a feed).
+- **Travel:** a line, a dot or a cursor leaves this beat and becomes the first stroke of the next one.
+- **Gather:** the closing lockup collects the pieces seen along the way.
+
+## Camera
+
+- Lead the subject: the camera arrives where the next element will land a moment before it lands.
+- Rest between moves. A hold of about a beat after each move is what makes the move read; a camera that never stops reads as a screensaver.
+- Vary the length of the moves; equal lengths read as a template.
+- Fast moves get motion blur; a sharp whip looks like a glitch.
+- Build every move as a function of time (seek(t)), so every frame renders the same.
+
+## Passages to build first (agency Reels)
+
+From the pauta of effect names collected on 2026-10-25, the ones that are carries and serve agency Reels:
+
+| Passage | Carry |
+|---|---|
+| Zoom Through Cut | push through an element into the next scene |
+| Pullback Reveal | pull back from a detail to the whole |
+| Phone Mockup | the screen of a phone grows out of the frame or the frame flies into it |
+| Chart Grow | a number on screen becomes the bar or line of a chart |
+| Headline Wall | a headline pulls back to reveal a wall of headlines |
+
+Still only names, no recipe yet: Orbit, Couch Wall, UI World, Frame Break, Digital Zoom, Checklist, Greenscreen, Paper Cut, Doodle Boy, Vertigo, Cover Story, Glass Type.
+
+## Gate
+
+`scripts/check_one_take.py FINAL.mp4 --timeline TIMELINE` blocks a scene without `carry`, a `transition` that is a plain cut, and any hard cut measured in the file (`one_take.*` in the config). A dissolve between unrelated scenes passes the measurement: the `carry` line and the eye are what catch it. Extract the frames around each passage and look.

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

@@ -0,0 +1,159 @@
+# -*- coding: utf-8 -*-
+"""ONE-TAKE gate: no passage is only a change of scene.
+
+For a piece meant as one continuous shot (a camera that flies from one beat
+into the next, an element that becomes the next screen). Two checks:
+
+    CARRY (blocks, timeline). Every scene after the first declares in
+        `carry` what on screen survives the passage and becomes the next beat
+        ("the price chip grows into the checkout card"). A scene without it,
+        or whose `transition` is a plain `cut`, is a swap, not a passage.
+    CUTS (blocks, final MP4). On a small luma copy of every frame
+        (one_take.analysis_width x one_take.analysis_height), a frame whose
+        mean absolute difference to the previous one is above
+        one_take.cut_min_diff AND one_take.cut_ratio times the median of its
+        neighbours (one_take.neighbour_frames on each side) is a hard cut. A
+        whip or a fast push changes many frames in a row, so it is not an
+        isolated spike; a cut is one.
+
+What it cannot see:
+    - A dissolve between two unrelated scenes has no spike: it passes CUTS.
+      Only the `carry` line and the eye catch it.
+    - Whether the declared carry is really on screen. Extract the frames
+      around each passage and look.
+    - A cut hidden under a flash or a whip blur spreads its change over
+      several frames and passes.
+
+Exit code: 0 pass, 1 fail, 2 file or config unreadable.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import statistics
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import Iterable
+
+from check_dead_frames import mean_abs_diff
+from check_safe_zone import ReadError, all_frames, video_fps
+from config import Config, ConfigError, add_config_arg, load, optional_block
+from timeline import TimelineError, load as load_timeline
+
+BLOCK = "one_take"
+
+
+@dataclass(frozen=True)
+class OneTakeRules:
+    width: int
+    height: int
+    cut_min_diff: float
+    cut_ratio: float
+    neighbour_frames: int
+
+
+def rules(cfg: Config) -> tuple[OneTakeRules, bool]:
+    """(rules, from_template). Refuses an incoherent block."""
+    b, from_template = optional_block(cfg, BLOCK)
+    try:
+        r = OneTakeRules(
+            width=int(b["analysis_width"]), height=int(b["analysis_height"]),
+            cut_min_diff=float(b["cut_min_diff"]), cut_ratio=float(b["cut_ratio"]),
+            neighbour_frames=int(b["neighbour_frames"]))
+    except (KeyError, TypeError, ValueError) as e:
+        raise ConfigError(f"{BLOCK}: missing or invalid key ({e})") from e
+    if r.width <= 0 or r.height <= 0:
+        raise ConfigError(f"{BLOCK}.analysis_width and analysis_height must be > 0")
+    if r.cut_min_diff <= 0 or r.cut_ratio <= 1:
+        raise ConfigError(f"{BLOCK}.cut_min_diff must be > 0 and cut_ratio > 1")
+    if r.neighbour_frames < 1:
+        raise ConfigError(f"{BLOCK}.neighbour_frames must be >= 1")
+    return r, from_template
+
+
+def missing_carry(scenes) -> list[tuple[int, float, str]]:
+    """(index, start, reason) of every scene after the first that is a swap."""
+    out = []
+    for i, sc in enumerate(scenes or []):
+        if i == 0:
+            continue
+        start = float(sc.get("start", 0.0))
+        if not str(sc.get("carry") or "").strip():
+            out.append((i, start, "no `carry`"))
+        elif sc.get("transition") == "cut":
+            out.append((i, start, "`transition` is a plain cut"))
+    return out
+
+
+def diffs(frames: Iterable[bytes]) -> list[float]:
+    """diffs[i] = change from frame i to frame i + 1."""
+    out, prev = [], None
+    for fr in frames:
+        if prev is not None:
+            out.append(mean_abs_diff(fr, prev))
+        prev = fr
+    return out
+
+
+def cut_frames(d: list[float], r: OneTakeRules) -> list[int]:
+    """Frame index (the first frame after the jump) of every isolated spike."""
+    out = []
+    k = r.neighbour_frames
+    for i, v in enumerate(d):
+        if v <= r.cut_min_diff:
+            continue
+        around = d[max(0, i - k):i] + d[i + 1:i + 1 + k]
+        base = statistics.median(around) if around else 0.0
+        if v > r.cut_ratio * base:
+            out.append(i + 1)
+    return out
+
+
+def report(name: str, cuts: list[int], fps: float, swaps, r: OneTakeRules,
+           from_template: bool) -> int:
+    print(f"{name}: one-take gate")
+    if from_template:
+        print(f"  note: no '{BLOCK}' block in the project config; using the template's")
+    if swaps is None:
+        print("  note: no --timeline; the `carry` of each passage was not checked")
+    elif swaps:
+        print(f"  SWAP: {len(swaps)} passage(s) with nothing carried into the next beat:")
+        for i, start, why in swaps[:10]:
+            print(f"     scene {i} at {start:6.2f}s: {why}")
+    else:
+        print("  ok: every passage declares what it carries")
+    if cuts:
+        print(f"  CUT: {len(cuts)} hard cut(s) (frame change above one_take.cut_min_diff="
+              f"{r.cut_min_diff} and {r.cut_ratio}x its neighbours):")
+        for f in cuts[:10]:
+            print(f"     {f / fps:6.2f}s (frame {f})")
+    else:
+        print("  ok: no hard cut in the file")
+    return 1 if cuts or swaps else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="One-take gate: every passage carries something (timeline) and the final MP4 has no hard cut.")
+    add_config_arg(ap)
+    ap.add_argument("video", help="final MP4")
+    ap.add_argument("--timeline", help="timeline JSON; checks the `carry` of every scene")
+    args = ap.parse_args(argv)
+    try:
+        cfg = load(args.config)
+        r, from_template = rules(cfg)
+        swaps = missing_carry(load_timeline(args.timeline).get("scenes")) if args.timeline else None
+        if not os.path.exists(args.video):
+            raise ReadError(f"video not found: {args.video}")
+        d = diffs(f for _, f in all_frames(args.video, r.width, r.height))
+        if not d:
+            raise ReadError("fewer than two frames decoded")
+        return report(os.path.basename(args.video), cut_frames(d, r), video_fps(args.video),
+                      swaps, r, from_template)
+    except (ConfigError, ReadError, TimelineError, subprocess.SubprocessError, OSError) as e:
+        print(f"ERROR: {e}")
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,126 @@
+# -*- coding: utf-8 -*-
+"""Tests of check_one_take.py: the `carry` of every passage (timeline), hard
+cuts as isolated spikes of frame change (a whip is not one), and the config
+fallback to the template. The ffmpeg round trip is skipped when ffmpeg is
+absent."""
+import io
+import json
+import shutil
+import subprocess
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+
+import check_one_take as OT
+from config import TEMPLATE, load
+
+CFG = load(TEMPLATE)
+RULES = OT.rules(CFG)[0]
+W, H = RULES.width, RULES.height
+SIZE = W * H
+
+
+def gradient(offset: int) -> bytes:
+    """A horizontal ramp shifted by `offset` columns: a camera that pans."""
+    return bytes(((x + offset) * 4) % 256 for _ in range(H) for x in range(W))
+
+
+def flat(v: int) -> bytes:
+    return bytes([v]) * SIZE
+
+
+class TestCarry(unittest.TestCase):
+    def test_every_passage_with_carry_passes(self):
+        scenes = [{"start": 0.0}, {"start": 3.0, "transition": "push", "carry": "price chip grows into the card"}]
+        self.assertEqual(OT.missing_carry(scenes), [])
+
+    def test_scene_without_carry_is_a_swap(self):
+        scenes = [{"start": 0.0}, {"start": 3.0, "transition": "push"}, {"start": 6.0, "carry": "  "}]
+        self.assertEqual([i for i, _, _ in OT.missing_carry(scenes)], [1, 2])
+
+    def test_plain_cut_with_carry_is_still_a_swap(self):
+        scenes = [{"start": 0.0}, {"start": 3.0, "transition": "cut", "carry": "the logo"}]
+        self.assertEqual(OT.missing_carry(scenes)[0][2], "`transition` is a plain cut")
+
+    def test_first_scene_needs_nothing(self):
+        self.assertEqual(OT.missing_carry([{"start": 0.0}]), [])
+        self.assertEqual(OT.missing_carry(None), [])
+
+
+class TestCuts(unittest.TestCase):
+    def test_slow_pan_has_no_cut(self):
+        d = OT.diffs(gradient(i) for i in range(40))
+        self.assertEqual(OT.cut_frames(d, RULES), [])
+
+    def test_hard_cut_is_found_on_the_first_frame_after_it(self):
+        frames = [gradient(i) for i in range(20)] + [flat(240 - i) for i in range(20)]
+        d = OT.diffs(frames)
+        self.assertEqual(OT.cut_frames(d, RULES), [20])
+
+    def test_fast_whip_over_several_frames_is_not_a_cut(self):
+        # Large change on every frame for a while: a move, not a cut.
+        frames = [gradient(0)] * 10 + [gradient(i * 9) for i in range(1, 9)] + [gradient(72)] * 10
+        d = OT.diffs(frames)
+        self.assertGreater(max(d), RULES.cut_min_diff)
+        self.assertEqual(OT.cut_frames(d, RULES), [])
+
+    def test_small_jump_under_the_floor_is_ignored(self):
+        frames = [flat(100)] * 10 + [flat(100 + int(RULES.cut_min_diff) - 2)] * 10
+        self.assertEqual(OT.cut_frames(OT.diffs(frames), RULES), [])
+
+
+class TestRules(unittest.TestCase):
+    def test_template_block_is_coherent(self):
+        r, _ = OT.rules(CFG)
+        self.assertGreater(r.cut_ratio, 1)
+
+    def test_project_config_without_block_falls_back_to_template(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            data = json.loads(Path(TEMPLATE).read_text(encoding="utf-8"))
+            data.pop(OT.BLOCK)
+            p = Path(tmp) / "effects.config.json"
+            p.write_text(json.dumps(data), encoding="utf-8")
+            _, from_template = OT.rules(load(str(p)))
+            self.assertTrue(from_template)
+
+
+@unittest.skipUnless(shutil.which("ffmpeg") and shutil.which("ffprobe"), "ffmpeg not installed")
+class TestRoundTrip(unittest.TestCase):
+    def _render(self, tmp: str, filters: str) -> str:
+        out = str(Path(tmp) / "piece.mp4")
+        subprocess.run(["ffmpeg", "-v", "error", "-y", "-f", "lavfi", "-i", filters,
+                        "-pix_fmt", "yuv420p", out], check=True)
+        return out
+
+    def _run(self, *args) -> tuple[int, str]:
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            code = OT.main(["--config", str(TEMPLATE), *args])
+        return code, buf.getvalue()
+
+    def test_two_colours_spliced_fail_and_a_timeline_without_carry_too(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            video = self._render(tmp, "color=c=0x202020:s=270x480:d=1:r=24,format=gray[a];"
+                                      "color=c=0xe0e0e0:s=270x480:d=1:r=24,format=gray[b];"
+                                      "[a][b]concat=n=2:v=1")
+            tl = Path(tmp) / "t.json"
+            tl.write_text(json.dumps({"scenes": [{"start": 0}, {"start": 1, "transition": "cut"}]}))
+            code, out = self._run(video, "--timeline", str(tl))
+            self.assertEqual(code, 1, out)
+            self.assertIn("CUT", out)
+            self.assertIn("SWAP", out)
+
+    def test_continuous_gradient_passes(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            video = self._render(tmp, "gradients=s=270x480:d=2:r=24:speed=0.02")
+            code, out = self._run(video)
+            self.assertEqual(code, 0, out)
+
+    def test_missing_video_is_an_input_error(self):
+        code, _ = self._run("/nonexistent.mp4")
+        self.assertEqual(code, 2)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/src/skills-lib/wizz-video-styles/LICENSE-lemo-opuscar.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LemoLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -30,13 +30,14 @@ Scripts live in this skill's `scripts/`; run them from the project root (the his
    - 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. 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).
+3. **Open the style card** in `references/styles/` (or, for an art-directed film rather than a reach format, a film style from [references/film-styles.md](references/film-styles.md)) 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).
+5. **Pieces drawn in code** (no footage): run the story, look and storyboard check-ins of [references/check-ins.md](references/check-ins.md) before building, with the panels timed on `scripts/beat_grid.py`.
+6. **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`).
+7. **Hand over** to `wizz-video-effects` with the card's SFX ceiling and music level, then to Remotion.
+8. **Look at the final file**: extract frames and compare them side by side with a contact sheet of one reference.
+9. **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.
+10. **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
 
@@ -58,13 +59,17 @@ Details and the per-style table: [references/measured-patterns.md](references/me
 | [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/film-styles.md](references/film-styles.md) | 59 art-directed film styles drawn in code (lemo-opuscar, not measured): index, how to build them in HyperFrames for 9:16, what the test renders taught |
+| [references/insert-recipes.md](references/insert-recipes.md) | b-roll treatments cut into a style (collage b-roll), drawn in code, not measured |
 | [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) |
+| [references/check-ins.md](references/check-ins.md) | story, look and storyboard approvals before building a piece drawn in code, plus the beat map |
+| `scripts/beat_grid.py` | BPM, beats, downbeats, loudest hits and drops of a song, so cuts and the payoff snap to the music |
 | `assets/remotion/editorial/` | Remotion template of the motion editorial style |
+| `assets/film-styles/` | three film styles rebuilt as 9:16 HyperFrames compositions (swiss-motion, risograph, dark-keynote), plus the risograph as a Remotion component, all gated |
 | `assets/audio/` | licensed music beds and SFX that may ship with a project |
 
 ## Out of scope

package/src/skills-lib/wizz-video-styles/assets/film-styles/dark-keynote.html

@@ -0,0 +1,78 @@
+<!doctype html>
+<html lang="pt-BR">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=1080, height=1920" />
+<title>dark-keynote · 9:16 example</title>
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<style>
+  body { margin: 0; background: #07090D; }
+  #root { position: relative; width: 1080px; height: 1920px; overflow: hidden; font-family: "Inter", "Helvetica Neue", sans-serif; color: #E8ECF2; }
+  .stage { position: absolute; inset: 0;
+    background: radial-gradient(ellipse 80% 40% at 50% 8%, #151A24 0%, transparent 70%),
+                radial-gradient(circle at 78% 62%, rgba(110,140,255,0.07) 0%, transparent 45%),
+                radial-gradient(ellipse at 50% 50%, transparent 50%, rgba(0,0,0,0.55) 100%), #07090D; }
+  .grid { position: absolute; inset: 0;
+    background-image: linear-gradient(rgba(255,255,255,0.03) 1px, transparent 1px), linear-gradient(90deg, rgba(255,255,255,0.03) 1px, transparent 1px);
+    background-size: 48px 48px; }
+  .card { position: absolute; width: 560px; height: 116px; border-radius: 22px; background: #141922;
+    border: 1px solid rgba(255,255,255,0.08); box-shadow: inset 0 1px 0 rgba(255,255,255,0.06), 0 20px 40px rgba(0,0,0,0.45); }
+  .card .ico { position: absolute; left: 24px; top: 28px; width: 60px; height: 60px; border-radius: 14px; background: #1E2531; }
+  .card .l1 { position: absolute; left: 104px; top: 30px; width: 300px; height: 18px; border-radius: 9px; background: #3A4352; }
+  .card .l2 { position: absolute; left: 104px; top: 64px; width: 200px; height: 14px; border-radius: 7px; background: #262D39; }
+  .card .badge { position: absolute; right: 22px; top: 22px; width: 40px; height: 40px; border-radius: 20px; background: #E5484D;
+    font: 600 20px/40px "JetBrains Mono", Menlo, monospace; text-align: center; color: #fff; }
+  #btn { position: absolute; left: 340px; top: 1180px; width: 400px; height: 120px; border-radius: 60px; background: #1A2029;
+    border: 1px solid rgba(255,255,255,0.1); font: 600 40px/120px Inter, "Helvetica Neue", sans-serif; text-align: center; color: #9AA4B2; }
+  #cursor { position: absolute; left: 0; top: 0; width: 44px; height: 56px; }
+  #big { position: absolute; left: 0; top: 560px; width: 1080px; text-align: center; font: 700 520px/1 "Inter Tight", "Helvetica Neue", sans-serif;
+    letter-spacing: -0.045em; color: #B7F34A; text-shadow: 0 0 80px rgba(183,243,74,0.35); }
+  #label { position: absolute; left: 0; top: 1120px; width: 1080px; text-align: center; font: 500 30px "JetBrains Mono", Menlo, monospace; letter-spacing: 0.18em; color: #8A94A3; }
+  #toast { position: absolute; left: 240px; top: 1400px; width: 600px; height: 92px; border-radius: 46px; background: rgba(20,25,34,0.9);
+    border: 1px solid rgba(255,255,255,0.12); font: 500 38px/92px Inter, "Helvetica Neue", sans-serif; text-align: center; }
+  #toast i { display: inline-block; width: 14px; height: 14px; border-radius: 7px; background: #B7F34A; margin-right: 16px; vertical-align: middle; }
+</style>
+</head>
+<body>
+<div id="root" data-composition-id="main" data-width="1080" data-height="1920" data-duration="6" data-fps="24">
+  <section id="scene" class="clip" data-start="0" data-duration="6" data-track-index="1" style="position:absolute;inset:0">
+    <div class="stage"></div><div class="grid"></div>
+    <div id="cards"></div>
+    <div id="btn">unificar</div>
+    <div id="big">1</div>
+    <div id="label">PAINEL · NO LUGAR DE 9 ABAS</div>
+    <div id="toast"><i></i>tudo num lugar só</div>
+    <svg id="cursor" viewBox="0 0 22 28"><path d="M1 1 L1 22 L7 16.5 L11 26 L14.5 24.5 L10.5 15 L18 15 Z" fill="#fff" stroke="#000" stroke-width="1.2"/></svg>
+  </section>
+</div>
+<script>
+  // 9 cards on the 48 px grid, fixed positions (no random)
+  const pos = [[96,288],[432,416],[144,544],[480,672],[96,800],[432,928],[192,1056],[480,1184],[96,1312]];
+  const holder = document.getElementById("cards");
+  pos.forEach(([x, y], i) => {
+    const c = document.createElement("div"); c.className = "card"; c.style.left = x + "px"; c.style.top = y + "px";
+    c.innerHTML = '<div class="ico"></div><div class="l1"></div><div class="l2"></div><div class="badge">' + (i + 2) + '</div>';
+    holder.appendChild(c);
+  });
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+  const beat = 0.5;
+  // spawns: drop + small overshoot, one per half beat (problem state, red badges)
+  tl.from(".card", { y: -60, opacity: 0, duration: 0.25, ease: "back.out(1.3)", stagger: beat / 2 }, 0.1);
+  tl.to(".card", { x: (i) => (i % 2 ? 4 : -4), duration: 0.05, ease: "none", repeat: 5, yoyo: true }, 2.4); // tremble
+  tl.from("#btn", { scale: 0.6, opacity: 0, duration: 0.25, ease: "back.out(1.3)" }, 2.5);
+  // cursor flies on a curve to the button, lands on the beat at 3.0
+  tl.fromTo("#cursor", { x: 900, y: 1480 }, { x: 560, y: 1250, duration: 0.5, ease: "power3.out" }, 2.5);
+  tl.to("#cursor", { scale: 0.85, duration: 0.06, ease: "none", yoyo: true, repeat: 1 }, 3.0);
+  tl.to("#btn", { backgroundColor: "#B7F34A", color: "#0A0D10", duration: 0.08, ease: "none" }, 3.0);
+  // turn: cards retract into the button, one per eighth note
+  tl.to(".card", { x: (i) => 540 - 280 - pos[i][0], y: (i) => 1240 - 58 - pos[i][1], scale: 0.2, opacity: 0, duration: 0.3, ease: "power3.in", stagger: 0.06 }, 3.15);
+  tl.to(["#btn", "#cursor"], { scaleY: 0.02, scaleX: 0.4, opacity: 0, duration: 0.2, ease: "power3.in" }, 3.85);
+  // the number gets its own screen, no caption over it
+  tl.from("#big", { scale: 0.7, opacity: 0, duration: 0.3, ease: "back.out(1.3)" }, 3.9);
+  tl.from("#label", { y: 20, opacity: 0, duration: 0.2, ease: "power2.out" }, 4.0);
+  tl.from("#toast", { y: 24, opacity: 0, duration: 0.16, ease: "power2.out" }, 4.25);
+  window.__timelines["main"] = tl;
+</script>
+</body>
+</html>

package/src/skills-lib/wizz-video-styles/assets/film-styles/remotion/Riso.tsx

@@ -0,0 +1,63 @@
+import React from "react";
+import { AbsoluteFill, Easing, interpolate, useCurrentFrame, useVideoConfig } from "remotion";
+
+// Risograph Print (lemo-opuscar card), rebuilt for Remotion: each plate is one ink
+// printed with multiply; tints are a dotted mask; registration is fixed per shot,
+// with one kick on the accent and a drift that snaps back on the downbeat.
+const PAPER = "#F4EEE2";
+const TEAL = "#00838A";
+const ORANGE = "#FF7477";
+const clamp = { extrapolateLeft: "clamp", extrapolateRight: "clamp" } as const;
+
+const Tint: React.FC<{ ink: string; dot: number; style: React.CSSProperties }> = ({ ink, dot, style }) => {
+  const mask = `radial-gradient(circle, #000 ${dot}px, transparent ${dot + 0.6}px)`;
+  return <div style={{ position: "absolute", background: ink, WebkitMaskImage: mask, maskImage: mask, WebkitMaskSize: "7px 7px", maskSize: "7px 7px", ...style }} />;
+};
+
+const Title: React.FC<{ ink: string; style?: React.CSSProperties }> = ({ ink, style }) => (
+  <div style={{ position: "absolute", left: 110, top: 310, width: 900, fontFamily: "Futura, 'Avenir Next', sans-serif", fontWeight: 800, fontSize: 150, lineHeight: 0.92, letterSpacing: "-0.02em", color: ink, ...style }}>
+    <div>anúncio</div>
+    <div>que vende</div>
+  </div>
+);
+
+export const Riso: React.FC = () => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const t = frame / fps;
+
+  const hillY = interpolate(t, [0, 0.6], [100, 0], { ...clamp, easing: Easing.out(Easing.cubic) });
+  const titleClip = interpolate(t, [0.25, 0.75], [100, 0], { ...clamp, easing: Easing.out(Easing.quad) });
+  const roller = interpolate(t, [1, 2], [0, 1], clamp);
+  // sun rises on twos: 18 steps over 1.5 s
+  const sunStep = Math.floor(interpolate(t, [1.4, 2.9], [0, 18], clamp));
+  const sunY = 320 - (320 * sunStep) / 18;
+  // kick on the accent at 3.0, ringing back
+  const kick = t < 3 ? 0 : t < 3.04 ? 1 : interpolate(t, [3.04, 3.34], [1, 0], { ...clamp, easing: Easing.out(Easing.elastic(1.5)) });
+  const p2x = -2 - 12 * kick;
+  const p2y = 2 + 8 * kick;
+  // drift through the hold, snap back on the downbeat
+  const p1x = t < 3.4 ? 2 : t < 4.6 ? interpolate(t, [3.4, 4.6], [2, 22]) : 2;
+  const p2on = t < 5;
+
+  const plate: React.CSSProperties = { position: "absolute", inset: -40, mixBlendMode: "multiply" };
+  return (
+    <AbsoluteFill style={{ background: PAPER }}>
+      <div style={{ ...plate, transform: `translate(${p1x}px, -1px)` }}>
+        <Tint ink={TEAL} dot={2.2} style={{ left: 0, top: 290, width: 1160, height: 570 }} />
+        <div style={{ position: "absolute", left: -100, top: 1180, width: 1400, height: 900, borderRadius: "50% 50% 0 0", background: TEAL, transform: `translateY(${hillY}px)` }} />
+        <Title ink={TEAL} style={{ clipPath: `inset(0 0 ${titleClip}% 0)` }} />
+      </div>
+      {p2on && (
+        <div style={{ ...plate, transform: `translate(${p2x}px, ${p2y}px)`, clipPath: `inset(0 0 ${100 - roller * 100}% 0)` }}>
+          <div style={{ position: "absolute", left: 380, top: 820, width: 520, height: 520, borderRadius: "50%", background: ORANGE, transform: `translateY(${sunY}px)` }} />
+          <Title ink={ORANGE} style={{ transform: "translate(9px, 7px)", opacity: 0.9 }} />
+          <Tint ink={ORANGE} dot={2} style={{ left: 0, top: 1350, width: 1160, height: 250 }} />
+        </div>
+      )}
+      {roller > 0 && roller < 1 && (
+        <div style={{ position: "absolute", left: 0, top: -40 + roller * 2000, width: 1080, height: 30, background: "rgba(255,116,119,0.35)", mixBlendMode: "multiply" }} />
+      )}
+    </AbsoluteFill>
+  );
+};

package/src/skills-lib/wizz-video-styles/assets/film-styles/risograph.html

@@ -0,0 +1,69 @@
+<!doctype html>
+<html lang="pt-BR">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=1080, height=1920" />
+<title>risograph · 9:16 example</title>
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<style>
+  body { margin: 0; background: #F4EEE2; }
+  #root { position: relative; width: 1080px; height: 1920px; overflow: hidden; font-family: "Futura", "Avenir Next", sans-serif; }
+  .paper { position: absolute; inset: 0; background: #F4EEE2; }
+  /* each plate is one ink, printed with multiply so overlaps mix */
+  .plate { position: absolute; inset: -40px; mix-blend-mode: multiply; }
+  .teal { --ink: #00838A; }
+  .orange { --ink: #FF7477; }
+  .solid { position: absolute; background: var(--ink); }
+  .tint { position: absolute; background: var(--ink);
+    -webkit-mask-image: radial-gradient(circle, #000 var(--dot), transparent calc(var(--dot) + 0.6px));
+    -webkit-mask-size: 7px 7px; mask-image: radial-gradient(circle, #000 var(--dot), transparent calc(var(--dot) + 0.6px)); mask-size: 7px 7px; }
+  .title { position: absolute; left: 110px; width: 900px; font-weight: 800; font-size: 150px; line-height: 0.92; letter-spacing: -0.02em; color: var(--ink); }
+  .grain { position: absolute; inset: 0; mix-blend-mode: multiply; opacity: 0.35; }
+  #roller { position: absolute; left: 0; width: 1080px; height: 30px; background: rgba(255,116,119,0.35); mix-blend-mode: multiply; }
+</style>
+</head>
+<body>
+<div id="root" data-composition-id="main" data-width="1080" data-height="1920" data-duration="6" data-fps="24">
+  <section id="scene" class="clip" data-start="0" data-duration="6" data-track-index="1" style="position:absolute;inset:0">
+    <div class="paper"></div>
+    <!-- plate 1: teal, offset +2px/-1px -->
+    <div id="p1" class="plate teal">
+      <div class="tint" style="--dot:2.2px; left:0; top:290px; width:1160px; height:570px"></div>
+      <div id="hill" class="solid" style="left:-100px; top:1180px; width:1400px; height:900px; border-radius:50% 50% 0 0"></div>
+      <div id="t1" class="title" style="top:310px"><span style="display:block">anúncio</span><span style="display:block">que vende</span></div>
+          </div>
+    <!-- plate 2: orange, offset -2px/+2px, arrives by roller sweep -->
+    <div id="p2" class="plate orange">
+      <div id="sun" class="solid" style="left:380px; top:820px; width:520px; height:520px; border-radius:50%"></div>
+      <div id="t2" class="title" style="top:310px; transform: translate(9px,7px); opacity:0.9"><span style="display:block">anúncio</span><span style="display:block">que vende</span></div>
+      <div class="tint" style="--dot:2px; left:0; top:1350px; width:1160px; height:250px"></div>
+    </div>
+    <svg class="grain" width="1080" height="1920"><filter id="n"><feTurbulence type="fractalNoise" baseFrequency="0.9" numOctaves="2" seed="7"/><feColorMatrix values="0 0 0 0 1  0 0 0 0 1  0 0 0 0 1  0 0 0 -1.2 1.1"/></filter><rect width="1080" height="1920" filter="url(#n)"/></svg>
+    <div id="roller"></div>
+  </section>
+</div>
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+  tl.set("#p1", { x: 2, y: -1 }, 0);
+  tl.set("#p2", { x: -2, y: 2 }, 0);
+  // one-plate version first: teal alone is a complete frame
+  tl.from("#t1", { clipPath: "inset(0 0 100% 0)", duration: 0.5, ease: "power2.out" }, 0.25);
+  tl.from("#hill", { y: 100, duration: 0.6, ease: "power3.out" }, 0.0);
+  // roller sweep prints the orange plate top to bottom (1.0 - 2.0)
+  tl.fromTo("#p2", { clipPath: "inset(0 0 100% 0)" }, { clipPath: "inset(0 0 0% 0)", duration: 1.0, ease: "none" }, 1.0);
+  tl.fromTo("#roller", { y: -40 }, { y: 1960, duration: 1.0, ease: "none" }, 1.0);
+  // sun rises on twos (12 fps steps)
+  tl.fromTo("#sun", { y: 320 }, { y: 0, duration: 1.5, ease: "steps(18)" }, 1.4);
+  // kick: registration jumps on the accent at 3.0 and rings back
+  tl.to("#p2", { x: -14, y: 10, duration: 0.04, ease: "none" }, 3.0);
+  tl.to("#p2", { x: -2, y: 2, duration: 0.3, ease: "elastic.out(1, 0.35)" }, 3.04);
+  // drift through the hold, snap back on the downbeat
+  tl.to("#p1", { x: 22, duration: 1.2, ease: "none" }, 3.4);
+  tl.to("#p1", { x: 2, duration: 0.05, ease: "none" }, 4.6);
+  // ending: one ink left (the orange plate lifts away)
+  tl.to("#p2", { opacity: 0, duration: 0.05, ease: "none" }, 5.0);
+  window.__timelines["main"] = tl;
+</script>
+</body>
+</html>