wizz-method 2.20.1 → 2.22.0

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

@@ -39,6 +39,7 @@ Requires Python 3 (stdlib only) and ffmpeg/ffprobe.
 
 ## Per piece
 
+0. **Taste.** Read `_wizz-output/video-styles/gosto.md` if it exists: what this user rejected is refused like an unknown event. After their review, append with `taste.mjs add` (`wizz-video-styles`).
 1. **Timeline.** Write the piece's timeline JSON ([references/data-contract.md](references/data-contract.md)): `words[]` from wizz-ctc-align, `scenes[]`, `elements[]`, and the safe-zone profile (`ad` or `organic`).
 2. **Events to sounds.** List what happens in the narration as semantic events with their times, from the words: a price appears, a verdict lands, a message arrives. Map them with `res = sound.map_requests([(5.4, "verdict"), (7.1, "element_in")], cfg)` from `scripts/sound.py`; it returns the shots (file and `vol` from the config) plus the refusals, with the reason. Write the accepted shots into `sfx[]` with their `event`. Events that trigger an effect (a `verdict` triggers `shake`): pass `sound.effect_candidates(res)` through `budget.select(...)` from `scripts/budget.py` and write the accepted ones into `shakes[]`; no other step writes them.
 3. **Effects on breaths.** `python3 scripts/fill_breaths.py TIMELINE --narration NARRATION.mp3 --visual LAYOUT_RENDER.mp4 --write` anchors punches and flashes on real speech breaths, runs every candidate through the budget, and sets scene transitions and cut sounds by speech pace. Without `--write` it only reports.
@@ -46,9 +47,9 @@ Requires Python 3 (stdlib only) and ffmpeg/ffprobe.
    - `--visual` must be a silent render **in the piece's final layout**. It decides punch vs flash by how close content sits to the safe-zone edge; measured on full-screen footage, every breath turns into a flash. Content inside a clipped card can take a punch.
    - Cut sounds are added here, after step 2: if the report lists sounds that would no longer be accepted together, map everything again. `check_excess.py` checks all sounds together and blocks on collisions.
 4. **Ducking.** `python3 scripts/sound.py duck TIMELINE --write` writes `ducking[]`; the Remotion volume callback is in the data contract.
-5. **Before rendering.** `python3 scripts/check_excess.py TIMELINE` (blocks) and `python3 scripts/check_rhythm.py TIMELINE` (warns).
+5. **Before rendering.** `python3 scripts/check_excess.py TIMELINE` (blocks), `python3 scripts/check_rhythm.py TIMELINE` (warns) and `python3 scripts/check_chrome.py --timeline TIMELINE` (blocks the slide look; for HyperFrames screens use `--snapshot` from `assets/chrome/collect_layout.js`).
 6. **Render** in Remotion from the timeline: SFX at their `vol`, narration with the ducking callback. `assets/remotion/` holds a reference `EffectsLayer.tsx` that consumes the timeline (copy it into the project). For the Remotion API itself, invoke `wizz-remotion-best-practices`.
-7. **Gate the final MP4.** Footage (an actor take, b-roll) edge to edge fails the safe zone by construction: the gate measures contrast, not text. Put footage in a frame inside the zone over a plain or darkened background. `check_safe_zone.py FINAL.mp4 --timeline TIMELINE` (the piece's profile; run with `--profile` for the other one if the piece also runs there), `measure_density.py FINAL.mp4 --timeline TIMELINE`, `check_loudness.py FINAL.mp4` (prints the ffmpeg command that fixes it when it fails, and warns when that fix will compress; a quiet narration is better raised before the render).
+7. **Gate the final MP4.** Footage (an actor take, b-roll) edge to edge fails the safe zone by construction: the gate measures contrast, not text. Put footage in a frame inside the zone over a plain or darkened background. `check_safe_zone.py FINAL.mp4 --timeline TIMELINE` (the piece's profile; run with `--profile` for the other one if the piece also runs there), `measure_density.py FINAL.mp4 --timeline TIMELINE`, `check_dead_frames.py FINAL.mp4`, `check_loudness.py FINAL.mp4` (prints the ffmpeg command that fixes it when it fails, and warns when that fix will compress; a quiet narration is better raised before the render).
 8. **Look.** Extract frames of the final file, including one of the CTA block, and read them.
 
 Every script takes `--config PATH`; without it, `VIDEO_EFFECTS_CONFIG`, then `./effects.config.json`.
@@ -60,7 +61,9 @@ Every script takes `--config PATH`; without it, `VIDEO_EFFECTS_CONFIG`, then `./
 | `check_excess.py` | yes (unless `--warn`) | an effect that always happens stops marking anything |
 | `check_safe_zone.py` | yes | text under the platform UI is text nobody reads |
 | `measure_density.py` | yes | an empty frame loses the scroll |
+| `check_dead_frames.py` | yes on blank runs, warns on frozen picture | a blank gap reads as a broken video |
 | `check_loudness.py` | yes | platforms normalise to about -14 LUFS; louder only distorts |
+| `check_chrome.py` | yes | a corner label or a counter makes an ad read as a slide |
 | `check_rhythm.py` | **warns only** | its numbers come from weak sources |
 
 Full table, what each gate cannot see, and escape hatches: [references/gates.md](references/gates.md).

package/src/skills-lib/wizz-video-effects/assets/chrome/collect_layout.js

@@ -0,0 +1,113 @@
+// collect_layout.js: layout snapshot of an HTML composition for check_chrome.py.
+//
+// Paste the whole file as the expression of a browser eval on the opened
+// composition (HyperFrames preview, a plain HTML film, or Remotion Studio on
+// the composition), e.g. with agent-browser:
+//   agent-browser open file:///.../index.html
+//   agent-browser eval "$(cat collect_layout.js)" > layout.json
+// It seeks each sample time, waits two frames, and returns
+// {width, height, samples: [{t, blocks, shapes}]} as JSON text.
+//
+// Times: window.__chromeTimes if set (array of seconds), else 12 evenly
+// spaced plus each one again 0.1 s later (the pair tells a parked label from
+// one flying through). Seek: window.__seek(t), else the paused GSAP
+// timelines in window.__timelines (HyperFrames), else gsap.globalTimeline.
+// Remotion Studio has none of these: set window.__seek yourself, or take one
+// snapshot per frame with ?frame=N and merge.
+//
+// Roles: an element (or ancestor) with data-role="caption|legal|ui" is
+// written with that role, so the lint skips it. Text in <canvas>, <img>,
+// <video> or WebGL is invisible here.
+//
+// Rules ported from motionmaxxing (Apache-2.0); see THIRD-PARTY-NOTICES.md.
+(async () => {
+  const root = document.querySelector('[data-composition-id="main"]') || document.body;
+  const rect = root.getBoundingClientRect();
+  const W = Number(root.dataset?.width) || rect.width || window.innerWidth;
+  const H = Number(root.dataset?.height) || rect.height || window.innerHeight;
+  const sx = W / (rect.width || W);
+  const sy = H / (rect.height || H);
+  const tls = window.__timelines && typeof window.__timelines === 'object' ? Object.values(window.__timelines) : [];
+  const duration =
+    Number(root.dataset?.duration) ||
+    (tls[0] && typeof tls[0].duration === 'function' ? tls[0].duration() : 0) ||
+    (window.gsap ? window.gsap.globalTimeline.duration() : 0);
+
+  const seek = async (t) => {
+    if (typeof window.__seek === 'function') await window.__seek(t);
+    else if (tls.length > 0) for (const tl of tls) tl.seek(t, false);
+    else if (window.gsap) window.gsap.globalTimeline.seek(t, false);
+    await new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+  };
+
+  const box = (r) => [
+    Math.round((r.left - rect.left) * sx),
+    Math.round((r.top - rect.top) * sy),
+    Math.round((r.right - rect.left) * sx),
+    Math.round((r.bottom - rect.top) * sy),
+  ];
+  const opacity = (el) => {
+    let o = 1;
+    for (let e = el; e && e !== document.documentElement; e = e.parentElement) o *= Number(getComputedStyle(e).opacity);
+    return o;
+  };
+  const roleOf = (el) => el.closest('[data-role]')?.dataset.role || '';
+  const visible = (el, r) => r.width >= 1 && r.height >= 1 && getComputedStyle(el).visibility !== 'hidden' && opacity(el) >= 0.05;
+
+  const textBlocks = () => {
+    const out = [];
+    for (const el of root.querySelectorAll('*')) {
+      const own = [...el.childNodes].filter((n) => n.nodeType === 3 && n.textContent.trim());
+      if (own.length === 0) continue;
+      const range = document.createRange();
+      range.selectNodeContents(el);
+      const r = range.getBoundingClientRect();
+      if (!visible(el, r)) continue;
+      const cs = getComputedStyle(el);
+      const fontPx = Number.parseFloat(cs.fontSize) * sy;
+      const spacing = cs.letterSpacing === 'normal' ? 0 : Number.parseFloat(cs.letterSpacing) / Number.parseFloat(cs.fontSize);
+      const lineH = Number.parseFloat(cs.lineHeight) || Number.parseFloat(cs.fontSize) * 1.2;
+      out.push({
+        text: el.textContent.trim().replaceAll(/\s+/g, ' ').slice(0, 120),
+        box: box(r),
+        font_px: Math.round(fontPx),
+        caps: cs.textTransform === 'uppercase',
+        tracking_em: Math.round(spacing * 100) / 100,
+        align: cs.textAlign,
+        lines: Math.max(1, Math.round(r.height / lineH)),
+        role: roleOf(el),
+      });
+    }
+    return out;
+  };
+
+  const shapes = () => {
+    const out = [];
+    let i = 0;
+    for (const el of root.querySelectorAll('*')) {
+      i += 1;
+      const r = el.getBoundingClientRect();
+      if (!visible(el, r)) continue;
+      const tag = el.tagName.toLowerCase();
+      const cs = getComputedStyle(el);
+      const media = /^(img|video|canvas|svg|picture)$/.test(tag) || /url\(/.test(cs.backgroundImage);
+      const filled = !/rgba\(0, 0, 0, 0\)|transparent/.test(cs.backgroundColor);
+      const border = Number.parseFloat(cs.borderTopWidth) >= 1 || Number.parseFloat(cs.borderBottomWidth) >= 1;
+      if (!media && !filled && !border) continue;
+      const kind = media ? 'media' : roleOf(el) === 'ui' ? 'surface' : 'bar';
+      out.push({ id: el.id || `${tag}-${i}`, kind, box: box(r) });
+    }
+    return out;
+  };
+
+  const base = Array.isArray(window.__chromeTimes)
+    ? window.__chromeTimes
+    : Array.from({ length: 12 }, (_, k) => (duration * (k + 0.5)) / 12);
+  const times = Array.isArray(window.__chromeTimes) ? base : base.flatMap((t) => [t, t + 0.1]);
+  const samples = [];
+  for (const t of times) {
+    await seek(t);
+    samples.push({ t: Math.round(t * 1000) / 1000, blocks: textBlocks(), shapes: shapes() });
+  }
+  return JSON.stringify({ width: W, height: H, duration, samples });
+})();

package/src/skills-lib/wizz-video-effects/assets/effects.config.template.json

@@ -57,6 +57,41 @@
     "_source": "min_filled 3 of 7 is a house rule of the source project, not an external benchmark."
   },
 
+  "dead_frames": {
+    "analysis_width": 54,
+    "analysis_height": 96,
+    "flat_std": 1.5,
+    "flat_range": 8,
+    "flat_max_frames": 3,
+    "frozen_diff": 0.35,
+    "frozen_warn_s": 1.5,
+    "motion_band_reference": [4.4, 6.8, 9.8],
+    "_note": "check_dead_frames.py on the FINAL MP4. A flat frame is one uniform field (luma std-dev under flat_std AND range under flat_range on the analysis frame); a run of more than flat_max_frames blocks. A frozen frame differs from the previous one by less than frozen_diff (mean absolute luma, 0-255); a frozen run longer than frozen_warn_s only warns.",
+    "_source": "flat_std, flat_range and flat_max_frames are gate G2 of motionmaxxing (Apache-2.0, github.com/Tejashmakwana/motionmaxxing), measured on horizontal pro launch films at 96x54; the analysis frame here keeps the same pixel count in 9:16. frozen_diff is their hold epsilon; frozen_warn_s is the top of their 'designed breath' (0.6-1.5 s). motion_band_reference is their Q1, median and Q3 of mean frame-to-frame luma change over human-made horizontal brand films: printed as a question, never a gate, and never measured on vertical Reels."
+  },
+
+  "chrome_lint": {
+    "small_text": 0.04,
+    "corner_x": 0.2,
+    "corner_y": 0.14,
+    "edge_band": 0.07,
+    "caps_tracking_em": 0.05,
+    "caps_max_size": 0.045,
+    "counter_max_size": 0.06,
+    "headline_min_size": 0.05,
+    "kicker_ratio": 2.0,
+    "kicker_gap": 0.06,
+    "deck_left_x": 0.2,
+    "bar_min_width": 0.6,
+    "bar_max_height": 0.14,
+    "bar_band": 0.12,
+    "progress_min_growth": 0.08,
+    "held_s": 0.3,
+    "exempt_roles": ["caption", "legal", "ui"],
+    "_note": "check_chrome.py. Positions are fractions of the frame (0-1). Text sizes (font size) are fractions of the SHORT side of the frame (1080 px in 9:16), so they keep the pixel size of the horizontal source. held_s: a timeline text layer shorter than this is in flight, not a held label.",
+    "_source": "Rules C1-C4, C6, C7, D1 and P1 of motionmaxxing's lint.mjs (gate G5, Apache-2.0, github.com/Tejashmakwana/motionmaxxing), built from one user's verdicts on horizontal launch films. exempt_roles is a house decision: captions, legally required ad text and product UI are not chrome."
+  },
+
   "budget": {
     "_readme": "The anti-excess engine. An effect only enters if its curve section still has budget, it respects the minimum distance and it does not repeat too much. When two candidates collide, the higher narrative strength wins.",
     "gap_min_global": 2.0,

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

@@ -18,7 +18,7 @@ Numbers that decide anything (gaps, ceilings, depths) are never in the timeline:
 | `shakes[]` | list | same | planner | short shakes (`budget.per_effect.shake.max_dur_s`) |
 | `flashes[]` | list | same | planner, `fill_breaths.py` | opacity flashes |
 | `interrupts[]` | list | same | planner | pattern interrupts |
-| `elements[]` | list | `check_rhythm.py` | planner | element entries (cards, labels) that count as visual change |
+| `elements[]` | list | `check_rhythm.py`, `check_chrome.py` | planner | element entries (cards, labels) that count as visual change |
 | `ducking[]` | list | renderer | `sound.py duck --write` | narration duck windows |
 
 ### `words[]` (ctc-align output, unchanged)
@@ -64,6 +64,20 @@ Each item is a number (the instant) or an object with `at`:
 "elements": [{ "at": 0.6, "kind": "text" }]
 ```
 
+Text layers and bars that `check_chrome.py` should read carry their geometry (pixels of the final frame) and stay on screen until `until` (default: the end):
+
+```json
+"elements": [
+  { "at": 0.6, "until": 4.0, "kind": "text", "text": "Pare de perder dinheiro", "box": [100, 760, 980, 860], "font_px": 96, "align": "center" },
+  { "at": 1.0, "until": 3.0, "kind": "text", "text": "custa", "box": [400, 1300, 680, 1380], "font_px": 72, "role": "caption" },
+  { "at": 0.0, "kind": "bar", "box": [0, 1880, 100, 1890], "box_end": [0, 1880, 1080, 1890] }
+]
+```
+
+- `role`: `caption`, `legal` or `ui` (`chrome_lint.exempt_roles`) is not chrome. Optional `caps`, `tracking_em` (letter-spacing in em), `lines`.
+- `box_end`: the bar's box at `until`; wider than `box` means a growing bar.
+- Top-level `chrome_allow`: rules the chosen style measured on real videos (e.g. `["P1"]`), printed as allowed.
+
 ### `ducking[]`
 
 Written by `python3 scripts/sound.py duck TIMELINE --write`. One window per group of SFX that sound over the **start of a spoken word**; nothing else ducks.
@@ -132,6 +146,19 @@ export const narrationVolume = (ducking: Duck[], fps: number, startFrame = 0) =>
 }
 ```
 
+## Layout snapshot (`check_chrome.py --snapshot`)
+
+Written by `assets/chrome/collect_layout.js` from the opened HTML composition (instructions at the top of that file); not part of the timeline:
+
+```json
+{ "width": 1080, "height": 1920, "samples": [
+  { "t": 1.0,
+    "blocks": [{ "text": "02 / 05", "box": [948, 40, 1040, 75], "font_px": 30, "caps": false, "tracking_em": 0, "align": "start", "lines": 1, "role": "" }],
+    "shapes": [{ "id": "bar", "kind": "bar", "box": [0, 1880, 1080, 1888] }] } ] }
+```
+
+`kind` is `bar` (any filled or bordered box), `media` (img, video, canvas, svg) or `surface` (inside `data-role="ui"`). Samples come in pairs 0.1 s apart, so a label flying through a corner is not taken for a parked one.
+
 ## Which script touches what
 
 | Script | Reads | Writes | Exit codes |
@@ -140,6 +167,8 @@ export const narrationVolume = (ducking: Duck[], fps: number, startFrame = 0) =>
 | `sound.py duck TIMELINE [--write]` | `sfx`, `scenes[].sfx`, `words`, `fps` | `ducking` | 0, 2 |
 | `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 |
 | `check_safe_zone.py MP4 [--timeline T]` | `safe_zone_profile` | nothing | 0, 1, 2 |
 | `measure_density.py MP4 [--timeline T]` | `safe_zone_profile` | nothing | 0, 1, 2 |
+| `check_dead_frames.py MP4` | the final file only | nothing | 0, 1, 2 |
 | `check_loudness.py MP4` | the final file only | nothing | 0, 1, 2 |

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

@@ -13,11 +13,13 @@ Thresholds are cited by config key. Every script exits `0` pass, `1` fail, `2` i
 | `normalize_audio.py --check` | SFX folder | every file at `sound.reference_level_db`, peak under `sound.max_peak_db` | yes | silent tails: it measures the whole file, so trim first |
 | `check_excess.py` | timeline JSON | every sound together (`sfx[]` and scene cut sounds) against the three refusals: unknown event, collision, same sound in a row; per effect kind: ceiling per minute, smallest gap, longest run in a row (`budget.per_effect.*`); dominant effects of different kinds closer than `budget.gap_min_global`; always reports the densest 10 s cluster | yes (`--warn` only while calibrating) | effects drawn inside the screens themselves (HyperFrames timelines); only what the timeline declares |
 | `check_rhythm.py` | timeline JSON | longest stretch with no visual change (`rhythm.max_static_s`), cut cadence in the hook (`rhythm.hook_s`, `rhythm.hook_cut_every_s`) and body (`rhythm.body_cut_every_s`), CTA tail excluded (`rhythm.cta_tail_s`). SFX never count as change | **no, warns only** | motion inside a screen; its numbers come from weak sources ([editing-patterns.md](editing-patterns.md)) |
+| `check_chrome.py` | timeline text layers (`--timeline`) or a DOM snapshot of the screens (`--snapshot`, from `assets/chrome/collect_layout.js`) | page chrome and slide look, thresholds in `chrome_lint.*`: C1 small label parked in a corner or edge band, C2 small tracked caps, C3 counter ("02 / 05", "Parte 3"), C4 timecode or metadata, C6 wide bar or hairline in the top or bottom band, C7 kicker right above a headline, D1 left headline block with media on the right, a sub-line or 2+ lines (alone: warn), P1 thin bar that grows. Roles in `chrome_lint.exempt_roles` (caption, legal, ui) are skipped; a rule the style measured goes in `chrome_allow` or `--allow` and is printed | yes | text in canvas, images, video or burned into footage; Remotion text not declared in `elements[]`; whether the flagged thing is still the right call. Rules come from one user's verdicts on horizontal launch films (motionmaxxing G5) |
 | `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_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 and rhythm on the timeline before the expensive render; safe zone, density and loudness on the final file.
+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.
 
 ## Two profiles, measured separately
 

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

@@ -0,0 +1,376 @@
+# -*- coding: utf-8 -*-
+"""PAGE-CHROME gate: does the piece look like a slide or a HUD?
+
+Reads what text and shapes are on screen, never the pixels, from one of two
+sources:
+
+    --snapshot LAYOUT.json  a layout snapshot of an HTML composition
+        (HyperFrames, or Remotion Studio, which is also a DOM), written by
+        assets/chrome/collect_layout.js at a few seek times.
+    --timeline TIMELINE     the Remotion timeline: the text layers declared in
+        elements[] (`text`, `box`, `font_px`, `role`, `until`).
+
+Rules (thresholds in the config block chrome_lint):
+    C1 corner/edge label     small text parked in a corner or an edge band      FAIL
+    C2 tracked-caps label    small uppercase text with wide letter-spacing      FAIL
+    C3 counter               "02 / 05", "01 - THE WAIT", "Parte 3", bare "01"    FAIL
+    C4 production metadata   timecode, FPS, BPM, resolution, REC, version       FAIL
+    C6 header/footer bar     a wide bar or hairline in the top or bottom band   FAIL
+    C7 kicker over headline  a small line right above a headline 2x its size   FAIL
+    D1 deck layout           left-anchored headline with media on the right,
+                             a sub-line or 2+ lines: FAIL; alone: WARN
+    P1 progress bar          a thin bar that grows over time                    FAIL
+
+Not chrome: text whose `role` is in chrome_lint.exempt_roles (captions,
+legally required ad text, product UI). A rule the chosen style measured on
+real videos (the progress device of `desafio-numero`) is allowed with
+`--allow P1` or `chrome_allow: ["P1"]` in the timeline; allowed rules are
+printed, never silent.
+
+What it cannot see: text drawn into a <canvas>, an image, a video or burned
+into footage; text a Remotion component draws without declaring it in the
+timeline; whether a flagged element is still the right call. A PASS is not
+taste: look at the frames.
+
+Rules ported from gate G5 of motionmaxxing's lint.mjs (Apache-2.0,
+github.com/Tejashmakwana/motionmaxxing), rewritten for 9:16; see
+THIRD-PARTY-NOTICES.md.
+
+Exit code: 0 pass (warnings allowed), 1 fail, 2 input or config unreadable.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+import timeline as tl
+from config import Config, ConfigError, add_config_arg, load, optional_block
+
+BLOCK = "chrome_lint"
+SEVERITY = {"C1": "FAIL", "C2": "FAIL", "C3": "FAIL", "C4": "FAIL", "C6": "FAIL",
+            "C7": "FAIL", "D1": "FAIL", "P1": "FAIL"}
+NAMES = {"C1": "corner/edge label", "C2": "tracked-caps label", "C3": "counter",
+         "C4": "production metadata", "C6": "header/footer bar", "C7": "kicker over headline",
+         "D1": "deck layout (left headline block)", "P1": "progress bar"}
+
+RX_COUNTER_NUM = re.compile(r"^\s*0?\d{1,2}\s*(?:[/·|]|-(?=\s*[A-Za-z]{3,}))\s*(?:0?\d{1,2}\b|[A-Za-zÀ-ú]{3,})")
+RX_COUNTER_WORD = re.compile(
+    r"\b(chapter|scene|act|step|part|episode|shot|take|beat|"
+    r"cap[ií]tulo|cena|ato|passo|parte|etapa|epis[oó]dio)\s*0?\d", re.I)
+RX_COUNTER_BARE = re.compile(r"^\s*0\d\s*$")
+RX_META = re.compile(
+    r"\bBPM\b|\bFPS\b|\bFRAME\s*\d|\b(?:1920|3840|1280|1080|720)\s*[x×]\s*(?:1080|2160|720|1920|1280)\b"
+    r"|\bT\s*\+\s*\d|\bTC\b|\b\d{1,2}:\d{2}:\d{2}(?:[.:]\d+)?\b|\b\d{1,2}:\d{2}\.\d{1,3}\b|\bREC\b")
+RX_VERSION = re.compile(r"\bv\d+\.\d+(?:\.\d+)?\b|©", re.I)
+RX_24_7 = re.compile(r"^\s*24\s*/\s*7\b")
+
+
+@dataclass(frozen=True)
+class ChromeRules:
+    small_text: float
+    corner_x: float
+    corner_y: float
+    edge_band: float
+    caps_tracking_em: float
+    caps_max_size: float
+    counter_max_size: float
+    headline_min_size: float
+    kicker_ratio: float
+    kicker_gap: float
+    deck_left_x: float
+    bar_min_width: float
+    bar_max_height: float
+    bar_band: float
+    progress_min_growth: float
+    held_s: float
+    exempt_roles: frozenset
+
+
+def rules(cfg: Config) -> tuple[ChromeRules, bool]:
+    b, from_template = optional_block(cfg, BLOCK)
+    try:
+        nums = {k: float(b[k]) for k in ChromeRules.__dataclass_fields__ if k != "exempt_roles"}
+        r = ChromeRules(**nums, exempt_roles=frozenset(str(x) for x in b["exempt_roles"]))
+    except (KeyError, TypeError, ValueError) as e:
+        raise ConfigError(f"{BLOCK}: missing or invalid key ({e})") from e
+    bad = [k for k, v in nums.items() if v <= 0]
+    if bad:
+        raise ConfigError(f"{BLOCK}: must be > 0: {', '.join(bad)}")
+    return r, from_template
+
+
+# ------------------------------------------------------------------ inputs
+
+@dataclass(frozen=True)
+class Block:
+    text: str
+    x0: float
+    y0: float
+    x1: float
+    y1: float
+    size: float          # font size / short side of the frame
+    caps: bool
+    tracking: float      # letter-spacing in em
+    role: str
+    align: str
+    lines: int
+
+    @property
+    def cx(self) -> float:
+        return (self.x0 + self.x1) / 2
+
+    @property
+    def cy(self) -> float:
+        return (self.y0 + self.y1) / 2
+
+
+@dataclass(frozen=True)
+class Shape:
+    sid: str
+    kind: str            # bar | rule | media | surface
+    x0: float
+    y0: float
+    x1: float
+    y1: float
+
+
+def _norm_box(box, w: float, h: float) -> tuple[float, float, float, float]:
+    x0, y0, x1, y1 = (float(v) for v in box)
+    return x0 / w, y0 / h, x1 / w, y1 / h
+
+
+def _block(d: dict, w: float, h: float) -> Block | None:
+    text = str(d.get("text") or "").strip()
+    if not text or "box" not in d:
+        return None
+    x0, y0, x1, y1 = _norm_box(d["box"], w, h)
+    caps = bool(d.get("caps")) or (text.upper() == text and any(c.isalpha() for c in text))
+    return Block(text, x0, y0, x1, y1, float(d.get("font_px", 0)) / min(w, h), caps,
+                 float(d.get("tracking_em", 0.0)), str(d.get("role") or ""),
+                 str(d.get("align") or ""), int(d.get("lines", 1)))
+
+
+def _shape(d: dict, i: int, w: float, h: float) -> Shape:
+    x0, y0, x1, y1 = _norm_box(d["box"], w, h)
+    return Shape(str(d.get("id", i)), str(d.get("kind", "bar")), x0, y0, x1, y1)
+
+
+def samples_from_snapshot(data: dict) -> list[dict]:
+    """[{t, blocks: [Block], shapes: [Shape]}] from a collect_layout.js file."""
+    w, h = float(data["width"]), float(data["height"])
+    out = []
+    for s in data.get("samples") or []:
+        blocks = [b for b in (_block(x, w, h) for x in s.get("blocks") or []) if b]
+        shapes = [_shape(x, i, w, h) for i, x in enumerate(s.get("shapes") or []) if "box" in x]
+        out.append({"t": float(s["t"]), "blocks": blocks, "shapes": shapes})
+    return sorted(out, key=lambda s: s["t"])
+
+
+def samples_from_timeline(data: dict, w: int, h: int, r: ChromeRules) -> list[dict]:
+    """One sample per layer start, with every declared layer visible then.
+    A layer shorter than held_s is in flight and is skipped; a bar with a
+    `box_end` wider than its `box` is a growing bar (P1)."""
+    total, _ = tl.duration(data)
+    layers = []
+    for i, e in enumerate(data.get("elements") or []):
+        if not isinstance(e, dict) or "box" not in e:
+            continue
+        start = float(e.get("at", 0.0))
+        end = float(e.get("until", total))
+        if end - start < r.held_s:
+            continue
+        layers.append((start, end, i, e))
+    out = []
+    for t in sorted({start for start, _, _, _ in layers}):
+        blocks, shapes = [], []
+        for start, end, i, e in layers:
+            if not start <= t < end:
+                continue
+            if e.get("text"):
+                b = _block(e, w, h)
+                if b:
+                    blocks.append(b)
+            elif e.get("kind") in ("bar", "rule", "media", "surface"):
+                shapes.append(_shape(e, i, w, h))
+                if e.get("box_end"):
+                    shapes.append(_shape({**e, "box": e["box_end"]}, i, w, h))
+        out.append({"t": t, "blocks": blocks, "shapes": shapes, "timeline": True})
+    return out
+
+
+# ------------------------------------------------------------------- rules
+
+def _held(b: Block, t: float, samples: list[dict], r: ChromeRules) -> bool:
+    """Parked, not flying through: the same text at the same place in the
+    neighbouring samples within held_s. No neighbour at all: held."""
+    near = [s for s in samples if s["t"] != t and abs(s["t"] - t) <= r.held_s]
+    if not near:
+        return True
+    return any(c.text == b.text and abs(c.x0 - b.x0) < 0.006 and abs(c.y0 - b.y0) < 0.006
+               for s in near for c in s["blocks"])
+
+
+def _text_rules(b: Block, r: ChromeRules) -> list[str]:
+    hits = []
+    small = b.size <= r.small_text
+    corner = (b.cx < r.corner_x or b.cx > 1 - r.corner_x) and (b.cy < r.corner_y or b.cy > 1 - r.corner_y)
+    edge = b.y1 < r.edge_band or b.y0 > 1 - r.edge_band or b.x1 < r.edge_band / 2 or b.x0 > 1 - r.edge_band / 2
+    if small and (corner or edge):
+        hits.append("C1")
+    letters = sum(1 for c in b.text if c.isalpha())
+    if b.caps and b.tracking >= r.caps_tracking_em and b.size <= r.caps_max_size and letters >= 2:
+        hits.append("C2")
+    counter = RX_COUNTER_NUM.search(b.text) or RX_COUNTER_WORD.search(b.text) or RX_COUNTER_BARE.search(b.text)
+    if b.size <= r.counter_max_size and counter and not RX_24_7.search(b.text):
+        hits.append("C3")
+    if (RX_META.search(b.text) and b.size <= r.counter_max_size) or (RX_VERSION.search(b.text) and small):
+        hits.append("C4")
+    return hits
+
+
+def _kickers(free: list[Block], r: ChromeRules) -> dict[int, Block]:
+    out = {}
+    for a in free:
+        for i, b in enumerate(free):
+            if a is b or a.size > r.small_text or b.size < max(a.size * r.kicker_ratio, r.headline_min_size):
+                continue
+            gap = b.y0 - a.y1
+            aligned = abs(a.x0 - b.x0) < 0.02 or abs(a.cx - b.cx) < 0.02
+            if -0.01 < gap < r.kicker_gap and aligned:
+                out[i] = a
+    return out
+
+
+def _deck(free: list[Block], shapes: list[Shape], kickers: dict[int, Block], r: ChromeRules):
+    biggest = max((b.size for b in free), default=0.0)
+    for i, b in enumerate(free):
+        left = 0.02 <= b.x0 < r.deck_left_x and b.x1 < 0.78
+        if not (b.size >= r.headline_min_size and b.size >= 0.85 * biggest and left
+                and b.align != "center" and abs(b.cx - 0.5) > 0.06):
+            continue
+        why = []
+        if any(c is not b and 0.02 <= c.size <= 0.6 * b.size and -0.005 < c.y0 - b.y1 < 0.08
+               and abs(c.x0 - b.x0) < 0.03 for c in free):
+            why.append("sub-line")
+        if i in kickers:
+            why.append("kicker")
+        if any(s.kind in ("media", "surface") and 0.04 <= (s.x1 - s.x0) * (s.y1 - s.y0) <= 0.7
+               and (s.x0 + s.x1) / 2 > 0.5 and s.x0 > b.x1 - 0.05 and s.y1 > b.y0 and s.y0 < b.y1 + 0.2
+               for s in shapes):
+            why.append("media on the right")
+        if b.lines >= 2:
+            why.append(f"{b.lines} lines")
+        yield b, why
+
+
+def _bars(shapes: list[Shape], r: ChromeRules) -> list[Shape]:
+    out = []
+    for s in shapes:
+        if s.kind in ("media", "surface"):
+            continue
+        w, h, cy = s.x1 - s.x0, s.y1 - s.y0, (s.y0 + s.y1) / 2
+        if w >= r.bar_min_width and h <= r.bar_max_height and (cy < r.bar_band or cy > 1 - r.bar_band):
+            out.append(s)
+    return out
+
+
+def _progress(samples: list[dict], r: ChromeRules) -> list[tuple[str, float, float]]:
+    """(id, first width, last width) of thin bars that grow over time."""
+    widths: dict[str, list[float]] = {}
+    for s in samples:
+        for sh in s["shapes"]:
+            if sh.kind not in ("media", "surface") and sh.y1 - sh.y0 <= 0.02:
+                widths.setdefault(sh.sid, []).append(sh.x1 - sh.x0)
+    out = []
+    for sid, ws in widths.items():
+        steps = [b - a for a, b in zip(ws, ws[1:])]
+        grows = ws[-1] - ws[0] >= r.progress_min_growth and all(d >= -0.005 for d in steps)
+        if len(ws) >= 2 and grows:
+            out.append((sid, ws[0], ws[-1]))
+    return out
+
+
+def lint(samples: list[dict], r: ChromeRules, allow: set[str]) -> dict:
+    hits: dict[tuple, dict] = {}
+
+    def add(rule: str, t: float, what: str, sev: str | None = None):
+        key = (rule, what)
+        h = hits.setdefault(key, {"rule": rule, "what": what, "times": [], "sev": sev or SEVERITY[rule]})
+        if t not in h["times"]:
+            h["times"].append(t)
+
+    for s in samples:
+        t = s["t"]
+        free = [b for b in s["blocks"] if b.role not in r.exempt_roles and _held(b, t, samples, r)]
+        for b in free:
+            for rule in _text_rules(b, r):
+                add(rule, t, b.text)
+        kickers = _kickers(free, r)
+        for i, a in kickers.items():
+            add("C7", t, f"{a.text!r} over {free[i].text!r}")
+        for b, why in _deck(free, s["shapes"], kickers, r):
+            add("D1", t, f"{b.text!r}" + (f" with {', '.join(why)}" if why else " alone"),
+                "FAIL" if why else "WARN")
+        for sh in _bars(s["shapes"], r):
+            add("C6", t, f"{sh.kind} {sh.sid} at y={sh.y0:.2f}-{sh.y1:.2f}")
+    for sid, w0, w1 in _progress(samples, r):
+        add("P1", samples[0]["t"], f"bar {sid} grows {w0:.2f} -> {w1:.2f} of the width")
+    used = sorted({h["rule"] for h in hits.values()} & allow)
+    kept = [h for h in hits.values() if h["rule"] not in allow]
+    kept.sort(key=lambda h: (h["rule"], h["times"][0]))
+    return {"hits": kept, "allowed": used, "passed": not any(h["sev"] == "FAIL" for h in kept)}
+
+
+# --------------------------------------------------------------------- CLI
+
+def report(rep: dict, source: str, n_samples: int, from_template: bool) -> int:
+    print(f"{source}: {n_samples} sample(s)")
+    if from_template:
+        print(f"  note: no '{BLOCK}' block in the project config; using the template's")
+    for h in rep["hits"]:
+        times = ", ".join(f"{t:.2f}s" for t in sorted(h["times"])[:6])
+        print(f"  {h['sev']:4} {h['rule']} {NAMES[h['rule']]}: {h['what']}  [{times}]")
+    for rule in rep["allowed"]:
+        print(f"  allowed {rule} {NAMES[rule]} (the style measured it)")
+    print(f"GATE chrome: {'PASS' if rep['passed'] else 'FAIL'}")
+    return 0 if rep["passed"] else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Page-chrome / slide-look lint on a layout snapshot or a timeline.")
+    add_config_arg(ap)
+    src = ap.add_mutually_exclusive_group(required=True)
+    src.add_argument("--snapshot", help="layout JSON written by assets/chrome/collect_layout.js")
+    src.add_argument("--timeline", help="timeline JSON with text layers in elements[]")
+    ap.add_argument("--allow", default="", help="comma-separated rules the chosen style measured (e.g. P1)")
+    args = ap.parse_args(argv)
+    try:
+        cfg = load(args.config)
+        r, from_template = rules(cfg)
+        allow = {a.strip() for a in args.allow.split(",") if a.strip()}
+        if args.snapshot:
+            p = Path(args.snapshot)
+            if not p.exists():
+                raise tl.TimelineError(f"snapshot not found: {p}")
+            samples = samples_from_snapshot(json.loads(p.read_text(encoding="utf-8")))
+            source = p.name
+        else:
+            data = tl.load(args.timeline)
+            allow |= set(data.get("chrome_allow") or [])
+            samples = samples_from_timeline(data, cfg.frame.width, cfg.frame.height, r)
+            source = Path(args.timeline).name
+        unknown = allow - set(SEVERITY)
+        if unknown:
+            raise ConfigError(f"unknown rule(s) in allow: {', '.join(sorted(unknown))}")
+        return report(lint(samples, r, allow), source, len(samples), from_template)
+    except (ConfigError, tl.TimelineError, json.JSONDecodeError, KeyError, ValueError, OSError) as e:
+        print(f"ERROR: {e}")
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())