@officexapp/vidfarm-devcli 0.21.27 → 0.21.29

package/dist/src/devcli/qa-check.js

@@ -0,0 +1,593 @@
+// Social-native QA check for the devcli — read a composition.html on disk and
+// flag "HTML slop": landing-page furniture that shows up everywhere on the web
+// and NEVER in a real TikTok/Reel/Short. Compositions are authored in HTML, so
+// an agent that reaches for its web-page instincts produces gradient CTA
+// capsules, benefit chip rows, and frosted cards floating over footage — the
+// single loudest tell that a video was machine-made.
+//
+// It also judges ONE frame on its own terms: t=0. That frame is the poster every
+// feed and share sheet freezes on, so a black open or a fade-up from black is a
+// real defect even though it's a single frame of ~30 in the first second.
+//
+// DESIGN CONTRACT (read before adding a rule):
+//   * BLOCKLIST, never allowlist. We name specific, well-known web-furniture
+//     patterns. Anything we haven't named is legal. A composition that does
+//     something weird, ugly, hand-made, or wildly stylized must PASS — the
+//     check exists to stop slop, not to homogenize style. If a rule would fire
+//     on a legitimately creative choice, the rule is wrong; loosen it.
+//   * FEEDBACK, never a gate. `vidfarm qa` exits 0 even with errors unless the
+//     caller opts into `--strict`. Nothing in the render path depends on it.
+//   * PRECISION over recall. Every `error` needs TWO independent signals (e.g.
+//     action copy AND a button shape). Single weak signals are `warn` at most.
+//     A false positive teaches agents to ignore the tool; a false negative just
+//     means we missed one.
+//
+// Pure DOM (linkedom) — no ffmpeg, no network, no Chrome. Local-only: this is a
+// devcli capability with no cloud/REST equivalent.
+import { parseHTML } from "linkedom";
+// ── The font regime ───────────────────────────────────────────────────────────
+// Mirrors CAPTION_FONT_REGIME in composition-edit.ts / COMPOSITION_FONT_IMPORT
+// in services/studio-project-adapter.ts. A family outside this set is not even
+// imported by the composition, so it silently falls back to a web-default sans
+// at render — which IS the slop look.
+const FONT_REGIME = ["tiktok sans", "montserrat", "abel", "source code pro", "yesteryear"];
+// Named separately so we can say "this is a website font" instead of the vaguer
+// "not imported" — the more actionable message when an agent typed it on purpose.
+const WEB_DEFAULT_FONTS = [
+    "inter", "roboto", "system-ui", "-apple-system", "arial", "helvetica", "helvetica neue",
+    "segoe ui", "times", "times new roman", "georgia", "verdana", "tahoma", "open sans", "lato", "nunito"
+];
+// Bootstrap / Tailwind / generic web-component class names. Matched as whole
+// tokens against class attributes, so `btn-primary` hits and `subtle` doesn't.
+const SLOP_CLASS_TOKENS = [
+    "btn", "button", "cta", "badge", "chip", "pill", "tag", "card", "panel", "navbar", "nav",
+    "hero", "jumbotron", "alert", "breadcrumb", "form-control", "input-group", "container",
+    "container-fluid", "row", "list-group", "well", "thumbnail", "media-object"
+];
+const SLOP_CLASS_PREFIXES = [
+    "col-", "rounded-full", "shadow-lg", "shadow-xl", "shadow-2xl", "backdrop-blur",
+    "bg-gradient-to-", "ring-", "btn-", "card-", "badge-", "nav-", "navbar-"
+];
+// Copy whose only job is to be clicked. Bare CTA words in a caption are FINE
+// ("buy now" is a legitimate social line) — this list only escalates a finding
+// when the text also sits inside a button shape.
+const ACTION_COPY = /\b(sign\s?up|get\s?started|learn\s?more|book\s+a\s+(call|demo)|start\s+(your\s+)?free\s+trial|free\s+trial|try\s+(it\s+)?free|click\s+here|subscribe\s+now|shop\s+now|order\s+now|contact\s+us|join\s+now|download\s+now|register\s+now|read\s+more|see\s+plans|view\s+pricing)\b/i;
+// The stock trust-badge phrases that show up in benefit chip rows.
+const BENEFIT_COPY = /(no\s+credit\s+card|money[-\s]?back|cancel\s+any\s?time|24\/7|free\s+shipping|verified|guarantee|no\s+commitment|risk[-\s]?free)/i;
+// Entrance transitions that leave frame 0 as a flat solid — the worst possible
+// thumbnail, because the frame carries no information at all.
+const BLANKING_INTROS = ["fade-black", "fade-white", "flash", "smoke"];
+function numAttrOf(node, name) {
+    const raw = node?.getAttribute?.(name);
+    const value = Number.parseFloat(String(raw ?? ""));
+    return Number.isFinite(value) ? value : NaN;
+}
+/** Does this clip paint pixels? Mirrors gapsFromClips in composition-edit.ts. */
+function isVisualClip(node) {
+    const kind = String(node?.getAttribute?.("data-layer-kind") ?? "").toLowerCase();
+    return node?.getAttribute?.("data-vf-timeline-proxy") === "video" || ["video", "image", "html", "shape"].includes(kind);
+}
+/** Is the clip on screen at t (seconds)? Layers with no duration are ignored. */
+function coversTime(node, t) {
+    const start = numAttrOf(node, "data-start");
+    const duration = numAttrOf(node, "data-duration");
+    if (!Number.isFinite(start) || !Number.isFinite(duration) || duration <= 0)
+        return false;
+    return start <= t + 0.001 && start + duration > t + 0.001;
+}
+function textOf(node) {
+    return String(node?.textContent ?? "").replace(/\s+/g, " ").trim();
+}
+function classTokens(node) {
+    return String(node?.getAttribute?.("class") ?? "").split(/\s+/).filter(Boolean);
+}
+function styleString(node) {
+    return String(node?.getAttribute?.("style") ?? "").toLowerCase();
+}
+/** Parse a CSS length in px from an inline style declaration. */
+function pxOf(style, prop) {
+    const match = style.match(new RegExp(`(?:^|;)\\s*${prop}\\s*:\\s*(-?[\\d.]+)px`));
+    return match ? Number(match[1]) : null;
+}
+function hasDecl(style, prop) {
+    return new RegExp(`(?:^|;)\\s*${prop}\\s*:`).test(style);
+}
+/** border-radius in px, treating any %/9999-style value as "fully rounded". */
+function radiusPx(style) {
+    const match = style.match(/(?:^|;)\s*border-radius\s*:\s*([^;]+)/);
+    if (!match)
+        return 0;
+    const raw = match[1].trim();
+    if (/%/.test(raw))
+        return 9999;
+    const num = Number((raw.match(/(-?[\d.]+)px/) ?? [])[1] ?? 0);
+    return Number.isFinite(num) ? num : 0;
+}
+function primaryFamily(raw) {
+    return String(raw).split(",")[0].replace(/['"]/g, "").trim().toLowerCase();
+}
+function label(node, fallback) {
+    const value = node?.getAttribute?.("data-label") ||
+        node?.getAttribute?.("data-slug") ||
+        node?.getAttribute?.("data-hf-id") ||
+        node?.getAttribute?.("id") ||
+        "";
+    const text = textOf(node).slice(0, 40);
+    const name = String(value).trim() || fallback;
+    return text ? `${name} — "${text}"` : name;
+}
+/**
+ * QA a composition's HTML. Pure: returns findings, mutates nothing. Safe on
+ * malformed input (returns a clean report rather than throwing) — a QA pass
+ * must never be the thing that breaks a render.
+ */
+export function qaCompositionHtml(html) {
+    const findings = [];
+    let root = null;
+    let document = null;
+    try {
+        ({ document } = parseHTML(html));
+        root = document.querySelector("[data-composition-id]") ?? document.body;
+    }
+    catch {
+        return {
+            ok: true,
+            verdict: "clean",
+            errors: [],
+            warnings: [],
+            checked: { layers: 0, text_layers: 0, canvas: null }
+        };
+    }
+    if (!root) {
+        return { ok: true, verdict: "clean", errors: [], warnings: [], checked: { layers: 0, text_layers: 0, canvas: null } };
+    }
+    const push = (f) => findings.push(f);
+    const all = Array.from(root.querySelectorAll("*"));
+    const layers = Array.from(root.querySelectorAll("[data-start]"));
+    // Only layers that actually SHOW WORDS get judged on typography and placement.
+    // A `data-layer-kind="text"` div is also how compositions carry scrims,
+    // gradient washes, and colour blocks — those legitimately span the full frame
+    // and have no font at all, so judging them would be pure noise.
+    const textLayers = Array.from(root.querySelectorAll('[data-layer-kind="caption"], [data-layer-kind="text"]')).filter((node) => textOf(node).length > 0);
+    const canvasW = Number(root.getAttribute?.("data-width") ?? 0) || null;
+    const canvasH = Number(root.getAttribute?.("data-height") ?? 0) || null;
+    // ── Rule: clickable elements ────────────────────────────────────────────────
+    // Nothing in a video is clickable. A <button>, a link, or a form control in a
+    // composition is web instinct leaking through, full stop.
+    for (const node of all) {
+        const tag = String(node.tagName ?? "").toLowerCase();
+        if (tag === "button" || tag === "form" || tag === "input" || tag === "select" || tag === "textarea") {
+            push({
+                rule: "clickable-element",
+                severity: "error",
+                message: `<${tag}> in a composition — nothing in a video is clickable.`,
+                where: label(node, `<${tag}>`),
+                fix: "Delete the control. If it carried a call to action, say it as a timed caption line on the footage (or in the voiceover)."
+            });
+        }
+        else if (tag === "a" && node.getAttribute?.("href")) {
+            push({
+                rule: "clickable-element",
+                severity: "warn",
+                message: "<a href> in a composition — links do nothing in a rendered MP4.",
+                where: label(node, "<a>"),
+                fix: "Keep the text if it's a real caption (a spoken URL reads fine); drop the anchor and any button styling around it."
+            });
+        }
+    }
+    // ── Rule: web-framework class names ────────────────────────────────────────
+    // Bootstrap/Tailwind furniture names. Two or more distinct hits is a strong
+    // signal someone built a landing page section; one is worth a nudge.
+    const frameworkHits = [];
+    for (const node of all) {
+        for (const token of classTokens(node)) {
+            const lower = token.toLowerCase();
+            if (SLOP_CLASS_TOKENS.includes(lower) || SLOP_CLASS_PREFIXES.some((p) => lower.startsWith(p))) {
+                frameworkHits.push({ node, token });
+                break;
+            }
+        }
+    }
+    if (frameworkHits.length) {
+        const tokens = [...new Set(frameworkHits.map((h) => h.token))].slice(0, 6).join(", ");
+        push({
+            rule: "web-framework-classes",
+            severity: frameworkHits.length >= 2 ? "error" : "warn",
+            message: `${frameworkHits.length} element(s) using web-page class names (${tokens}) — this is a landing page, not a video.`,
+            where: label(frameworkHits[0].node, "element"),
+            fix: "Rebuild as timed text on the footage. Text belongs ON the frame, not inside a container with padding and a shadow."
+        });
+    }
+    // Only CSS-FRAMEWORK stylesheets — a jsdelivr <script> for GSAP/anime.js is a
+    // normal, encouraged part of a local composition and must never trip this.
+    if (/bootstrap[^"']*\.css|cdn\.tailwindcss\.com|tailwind[^"']*\.css|fontawesome[^"']*\.css|bulma[^"']*\.css|foundation[^"']*\.css/i.test(html)) {
+        push({
+            rule: "web-framework-classes",
+            severity: "error",
+            message: "A CSS framework stylesheet (Bootstrap/Tailwind/FontAwesome/Bulma) is linked into the composition.",
+            where: "<head>",
+            fix: "Remove it. Its defaults ARE the look to avoid, and renders should be offline-deterministic. (A <script> CDN for GSAP/anime.js is fine — this is about CSS frameworks.)"
+        });
+    }
+    // ── Rule: CTA button ───────────────────────────────────────────────────────
+    // Two signals required: action copy AND a button shape (pill/rounded fill).
+    // "BUY NOW" as a bare caption is legitimate social copy and must not fire.
+    for (const node of all) {
+        const text = textOf(node);
+        if (!text || text.length > 60 || !ACTION_COPY.test(text))
+            continue;
+        const style = styleString(node);
+        const radius = radiusPx(style);
+        const filled = /background(?:-color|-image)?\s*:/.test(style) && !/background[^;]*:\s*(none|transparent)/.test(style);
+        const gradient = /linear-gradient|radial-gradient/.test(style);
+        const shadowed = hasDecl(style, "box-shadow");
+        const buttonShape = (radius >= 16 && filled) || (gradient && radius >= 8) || (filled && shadowed && radius >= 8);
+        if (buttonShape) {
+            push({
+                rule: "cta-button",
+                severity: "error",
+                message: `CTA button ("${text.slice(0, 40)}") — a filled, rounded capsule with action copy. Pure landing page.`,
+                where: label(node, "cta"),
+                fix: "Kill the capsule. Deliver the CTA as a plain caption line in the font regime, spoken in the voiceover, or as an arrow pointing at real on-screen UI."
+            });
+        }
+    }
+    // ── Rule: benefit chip / badge row ─────────────────────────────────────────
+    // "✓ No Credit Card Needed · ✓ 30-Min Trial" — a row of small rounded tags.
+    // Requires 2+ siblings that are each small, filled, and rounded.
+    const parents = new Map();
+    for (const node of all) {
+        const style = styleString(node);
+        const text = textOf(node);
+        if (!text || text.length > 45)
+            continue;
+        const filled = /background(?:-color|-image)?\s*:/.test(style) && !/background[^;]*:\s*(none|transparent)/.test(style);
+        const chipShape = radiusPx(style) >= 10 && filled;
+        const chipCopy = /^[✓✔✅•·]/.test(text) || BENEFIT_COPY.test(text);
+        if (!(chipShape && (chipCopy || text.split(" ").length <= 5)))
+            continue;
+        const parent = node.parentNode;
+        if (!parent)
+            continue;
+        const bucket = parents.get(parent) ?? [];
+        bucket.push(node);
+        parents.set(parent, bucket);
+    }
+    for (const [, bucket] of parents) {
+        if (bucket.length < 2)
+            continue;
+        push({
+            rule: "badge-chip-row",
+            severity: "error",
+            message: `A row of ${bucket.length} badge/chip pills (${bucket.slice(0, 3).map((n) => `"${textOf(n).slice(0, 22)}"`).join(", ")}) — trust badges are website furniture.`,
+            where: label(bucket[0], "chip"),
+            fix: "Say each benefit as its OWN timed caption line on the footage, one at a time, in the font regime. One idea per beat reads far better than a chip strip."
+        });
+    }
+    // ── Rule: card / panel / glassmorphism ─────────────────────────────────────
+    // A rounded box with a border, shadow, or frosted blur, holding more than one
+    // piece of content. A tight caption BAND is legal (small radius, one run) —
+    // this fires only once the band has become a container.
+    for (const node of all) {
+        const style = styleString(node);
+        if (!style)
+            continue;
+        const radius = radiusPx(style);
+        const frosted = /backdrop-filter\s*:\s*[^;]*blur/.test(style);
+        const bordered = /(?:^|;)\s*border\s*:\s*(?!0|none)/.test(style) || hasDecl(style, "border-width");
+        const shadowed = hasDecl(style, "box-shadow") && !/box-shadow\s*:\s*none/.test(style);
+        const childBoxes = Array.from(node.children ?? []).filter((c) => textOf(c)).length;
+        const filled = /background(?:-color|-image)?\s*:/.test(style) && !/background[^;]*:\s*(none|transparent)/.test(style);
+        if (frosted) {
+            push({
+                rule: "glass-card",
+                severity: "error",
+                message: "Glassmorphism (backdrop-filter blur) — a frosted web panel floating over the footage.",
+                where: label(node, "panel"),
+                fix: "Drop the panel. If the text needs legibility over busy footage, use a heavy outline (background_style outline) or a tight solid band that hugs the words."
+            });
+            continue;
+        }
+        if (radius >= 12 && (bordered || shadowed) && filled && childBoxes >= 2) {
+            push({
+                rule: "card-panel",
+                severity: "error",
+                message: `Card/panel: rounded ${Math.round(radius)}px box with ${bordered ? "a border" : "a drop shadow"} wrapping ${childBoxes} elements.`,
+                where: label(node, "card"),
+                fix: "Put the text directly on the frame. A legibility band is legal — radius ≤8px, no border, no shadow, hugging ONE text run — but a headline + subheading + URL inside one rounded box is a web card."
+            });
+        }
+    }
+    // ── Rule: gradient text fill ───────────────────────────────────────────────
+    if (/background-clip\s*:\s*text|-webkit-background-clip\s*:\s*text/i.test(html)) {
+        push({
+            rule: "gradient-text",
+            severity: "error",
+            message: "Gradient-filled text (background-clip:text) — a SaaS hero headline treatment.",
+            where: "composition styles",
+            fix: "Use a solid fill. If you want emphasis, pop a SINGLE word in an accent color, or go heavier weight / ALL-CAPS."
+        });
+    }
+    // ── Rule: page structure elements ──────────────────────────────────────────
+    for (const node of all) {
+        const tag = String(node.tagName ?? "").toLowerCase();
+        if (tag === "table" || tag === "nav" || tag === "header" || tag === "footer") {
+            push({
+                rule: "page-structure",
+                severity: tag === "table" ? "warn" : "error",
+                message: `<${tag}> element — page chrome has no place in a video frame.`,
+                where: label(node, `<${tag}>`),
+                fix: tag === "table"
+                    ? "If it's real data, build it as an animated stat/number reveal instead of a static grid of cells."
+                    : "Delete it and re-time its content as captions on the footage."
+            });
+        }
+        if (tag === "ul" || tag === "ol") {
+            const style = styleString(node);
+            // A list with markers switched OFF is just a layout container — fine.
+            if (!/list-style(?:-type)?\s*:\s*none/.test(style)) {
+                push({
+                    rule: "bullet-list",
+                    severity: "warn",
+                    message: `<${tag}> with visible bullet markers — a slide/webpage list, not a social beat.`,
+                    where: label(node, `<${tag}>`),
+                    fix: "Reveal the points ONE AT A TIME as timed caption lines. If you want the list look, set list-style:none and animate each row in."
+                });
+            }
+        }
+    }
+    // ── Rule: font regime ──────────────────────────────────────────────────────
+    for (const node of textLayers) {
+        const attr = String(node.getAttribute?.("data-font-family") ?? "").trim();
+        const style = styleString(node);
+        const cssMatch = style.match(/(?:^|;)\s*font-family\s*:\s*([^;]+)/);
+        const family = primaryFamily(attr || (cssMatch ? cssMatch[1] : ""));
+        if (family && !FONT_REGIME.includes(family)) {
+            const isWebDefault = WEB_DEFAULT_FONTS.includes(family) || family === "sans-serif" || family === "serif";
+            push({
+                rule: "font-regime",
+                severity: isWebDefault ? "error" : "warn",
+                message: isWebDefault
+                    ? `Text layer in "${family}" — a website body font. This alone makes a frame read as a screenshot of a web page.`
+                    : `Text layer in "${family}", outside the composition's imported font regime — it will silently fall back at render.`,
+                where: label(node, "text layer"),
+                fix: `Use an imported display family: Montserrat (default), TikTok Sans, Abel, Source Code Pro, or Yesteryear — e.g. \`vidfarm set-style <dir> --layer <key> --font-family Montserrat\`. Local renders auto-coerce this, but the editor preview will not match until you fix it.`
+            });
+        }
+        // Weight: the TikTok caption look is heavy. Light weights are a legitimate
+        // creative choice for a title card, so this is only ever a nudge.
+        const weightRaw = node.getAttribute?.("data-font-weight") ?? (style.match(/(?:^|;)\s*font-weight\s*:\s*(\d{3})/) ?? [])[1];
+        const weight = Number(weightRaw);
+        if (Number.isFinite(weight) && weight > 0 && weight < 600) {
+            push({
+                rule: "font-weight",
+                severity: "warn",
+                message: `Caption weight ${weight} — social captions read at 700–900; anything lighter dissolves on a phone over moving footage.`,
+                where: label(node, "text layer"),
+                fix: "Bump to 700–900 unless the light weight is a deliberate title-card look."
+            });
+        }
+        // Size: 0 is invisible (a real bug we have shipped before); tiny text is
+        // unreadable at phone scale. Only judged when we know the canvas width.
+        const sizePx = pxOf(style, "font-size") ?? Number(node.getAttribute?.("data-font-size") ?? NaN);
+        if (Number.isFinite(sizePx)) {
+            if (sizePx === 0) {
+                push({
+                    rule: "font-size",
+                    severity: "error",
+                    message: "font-size:0 — this text renders invisibly.",
+                    where: label(node, "text layer"),
+                    fix: "Set a real size: ~36–64px on a 1080-wide frame."
+                });
+            }
+            else if (canvasW && sizePx > 0 && sizePx < canvasW * 0.026) {
+                push({
+                    rule: "font-size",
+                    severity: "warn",
+                    message: `font-size ${Math.round(sizePx)}px on a ${canvasW}px-wide canvas — too small to read on a phone.`,
+                    where: label(node, "text layer"),
+                    fix: `Aim for ~${Math.round(canvasW * 0.033)}–${Math.round(canvasW * 0.06)}px.`
+                });
+            }
+        }
+    }
+    // ── Rule: caption safe zone ────────────────────────────────────────────────
+    // Local renders auto-normalize this, but the editor preview and cloud render
+    // do not — so flag it as a warning rather than silently relying on the fixer.
+    // PORTRAIT ONLY: the dead zones are phone-feed chrome (status bar, action rail,
+    // username block). A 16:9 or square composition has no such constraint.
+    if (canvasH && canvasW && canvasH > canvasW) {
+        for (const node of textLayers) {
+            const style = styleString(node);
+            const top = Number((style.match(/(?:^|;)\s*top\s*:\s*(-?[\d.]+)%/) ?? [])[1]);
+            const height = Number((style.match(/(?:^|;)\s*height\s*:\s*(-?[\d.]+)%/) ?? [])[1]);
+            if (!Number.isFinite(top))
+                continue;
+            const bottom = top + (Number.isFinite(height) ? height : 0);
+            if (top < 8 || bottom > 85) {
+                push({
+                    rule: "caption-safe-zone",
+                    severity: "warn",
+                    message: `Text at ${top.toFixed(0)}%–${bottom.toFixed(0)}% spills into the phone-UI dead zone (safe band is 8%–85%).`,
+                    where: label(node, "text layer"),
+                    fix: "Pull it inside 8%–85% keeping its top-vs-bottom anchoring. `vidfarm render --target local` clamps this automatically; the editor preview and cloud render do not."
+                });
+            }
+        }
+    }
+    // ── Rule: the first frame IS the thumbnail ─────────────────────────────────
+    // Frame 0 is one frame of ~30 in the first second, but every feed, share
+    // sheet, and player poster freezes on it — so it is seen by everyone who
+    // scrolls past and never presses play. A black open, a fade-up from black, or
+    // an empty frame waiting for the hook line throws away the only frame that
+    // has to sell the video. Judged at t=0 exactly, since that is the frame the
+    // poster is grabbed from.
+    const visualClips = layers.filter(isVisualClip);
+    const openingVisuals = visualClips.filter((node) => coversTime(node, 0));
+    if (visualClips.length && !openingVisuals.length) {
+        const earliest = visualClips
+            .map((node) => numAttrOf(node, "data-start"))
+            .filter((value) => Number.isFinite(value))
+            .sort((a, b) => a - b)[0];
+        push({
+            rule: "thumbnail-blank-open",
+            severity: "error",
+            message: Number.isFinite(earliest)
+                ? `Nothing is on screen at t=0 — the first visual starts at ${earliest.toFixed(2)}s, so the thumbnail is a black frame.`
+                : "Nothing is on screen at t=0 — the thumbnail is a black frame.",
+            where: "timeline t=0",
+            fix: "Pull the opening clip back to start:0 (`vidfarm retime <dir> --layer <key> --start 0`), or place a deliberate hook frame there. The first frame is the poster every scroller judges the video by."
+        });
+    }
+    for (const node of openingVisuals) {
+        const intro = String(node.getAttribute?.("data-transition") ?? "").trim().toLowerCase();
+        if (!intro || intro === "none")
+            continue;
+        const blanking = BLANKING_INTROS.includes(intro);
+        push({
+            rule: "thumbnail-fade-in",
+            severity: blanking ? "error" : "warn",
+            message: blanking
+                ? `The opening clip has a "${intro}" entrance — frame 0 is a flat ${intro === "fade-white" ? "white" : intro === "flash" ? "blown-out" : "black"} frame, so that becomes the thumbnail.`
+                : `The opening clip has a "${intro}" entrance — frame 0 is caught mid-animation (offset, blurred, or scaled), which is what the thumbnail freezes on.`,
+            where: label(node, "opening clip"),
+            fix: `Drop the entrance on the FIRST clip — it's an intro, not a junction (\`vidfarm transitions set <dir> --layer <key> --in none\`). Junction transitions between later clips are unaffected. If you truly want to open from black, add a held hook frame before it so the poster still shows something.`
+        });
+    }
+    // The strongest thumbnails carry the hook in words. Only a nudge: opening on a
+    // clean face or product shot is a legitimate call.
+    if (textLayers.length && !textLayers.some((node) => coversTime(node, 0))) {
+        const earliest = textLayers
+            .map((node) => numAttrOf(node, "data-start"))
+            .filter((value) => Number.isFinite(value))
+            .sort((a, b) => a - b)[0];
+        push({
+            rule: "thumbnail-no-hook-text",
+            severity: "warn",
+            message: Number.isFinite(earliest)
+                ? `No on-screen text at t=0 (the first text lands at ${earliest.toFixed(2)}s) — the thumbnail carries no hook words.`
+                : "No on-screen text at t=0 — the thumbnail carries no hook words.",
+            where: "timeline t=0",
+            fix: "Start the hook line at 0 so the poster frame states the promise. Ignore this if the video deliberately opens on a clean face/product shot."
+        });
+    }
+    const errors = findings.filter((f) => f.severity === "error");
+    const warnings = findings.filter((f) => f.severity === "warn");
+    return {
+        ok: errors.length === 0,
+        verdict: errors.length ? "slop" : warnings.length ? "warnings" : "clean",
+        errors,
+        warnings,
+        checked: {
+            layers: layers.length,
+            text_layers: textLayers.length,
+            canvas: canvasW && canvasH ? `${canvasW}×${canvasH}` : null
+        }
+    };
+}
+function aspectLabel(width, height) {
+    if (!width || !height)
+        return null;
+    const gcd = (a, b) => (b ? gcd(b, a % b) : a);
+    const divisor = gcd(width, height) || 1;
+    return `${width / divisor}:${height / divisor}`;
+}
+/**
+ * Derive the facts a QA_REGIME.md can assert against. Pure, tolerant of
+ * malformed input (returns empty facts rather than throwing) — same contract as
+ * qaCompositionHtml, because a regime run must never break a render either.
+ */
+export function extractCompositionFacts(html) {
+    const empty = {
+        duration_sec: null,
+        canvas: { width: null, height: null, aspect: null },
+        visual_clips: [],
+        text_runs: [],
+        card_runs: [],
+        audio_layers: 0,
+        caption_layers: 0,
+        first_frame_visual: false,
+        first_frame_text: null,
+        first_text_at_sec: null,
+        max_simultaneous_text: 0,
+        off_regime_fonts: [],
+        all_text: ""
+    };
+    let root = null;
+    try {
+        const { document } = parseHTML(html);
+        root = document.querySelector("[data-composition-id]") ?? document.body;
+    }
+    catch {
+        return empty;
+    }
+    if (!root)
+        return empty;
+    const layers = Array.from(root.querySelectorAll("[data-start]"));
+    const width = Number(root.getAttribute?.("data-width") ?? 0) || null;
+    const height = Number(root.getAttribute?.("data-height") ?? 0) || null;
+    const duration = Number.parseFloat(String(root.getAttribute?.("data-duration") ?? ""));
+    const visualClips = layers.filter(isVisualClip).map((node) => ({
+        key: String(node.getAttribute?.("data-hf-id") || node.getAttribute?.("id") || ""),
+        kind: String(node.getAttribute?.("data-layer-kind") ?? "video").toLowerCase(),
+        start: numAttrOf(node, "data-start") || 0,
+        duration: numAttrOf(node, "data-duration") || 0
+    }));
+    const textRuns = [];
+    for (const node of Array.from(root.querySelectorAll('[data-layer-kind="caption"], [data-layer-kind="text"]'))) {
+        const text = textOf(node);
+        if (!text)
+            continue;
+        const style = styleString(node);
+        const cssFamily = (style.match(/(?:^|;)\s*font-family\s*:\s*([^;]+)/) ?? [])[1] ?? "";
+        const family = primaryFamily(String(node.getAttribute?.("data-font-family") ?? "") || cssFamily);
+        textRuns.push({
+            key: String(node.getAttribute?.("data-hf-id") || node.getAttribute?.("id") || ""),
+            kind: String(node.getAttribute?.("data-layer-kind") ?? "text").toLowerCase(),
+            text,
+            start: numAttrOf(node, "data-start") || 0,
+            duration: numAttrOf(node, "data-duration") || 0,
+            font: family || null
+        });
+    }
+    // Max text runs sharing the screen — swept at every run's start, which is the
+    // only instant the count can rise.
+    let maxSimultaneous = 0;
+    for (const probe of textRuns) {
+        const at = probe.start;
+        const overlapping = textRuns.filter((run) => run.start <= at + 0.001 && run.start + run.duration > at + 0.001).length;
+        if (overlapping > maxSimultaneous)
+            maxSimultaneous = overlapping;
+    }
+    const openingText = textRuns.filter((run) => run.start <= 0.001 && run.start + run.duration > 0.001);
+    const sortedStarts = textRuns.map((run) => run.start).sort((a, b) => a - b);
+    return {
+        duration_sec: Number.isFinite(duration) ? duration : null,
+        canvas: { width, height, aspect: aspectLabel(width, height) },
+        visual_clips: visualClips,
+        text_runs: textRuns,
+        card_runs: textRuns.filter((run) => run.kind === "text"),
+        audio_layers: layers.filter((node) => String(node.getAttribute?.("data-layer-kind") ?? "").toLowerCase() === "audio").length,
+        caption_layers: textRuns.filter((run) => run.kind === "caption").length,
+        first_frame_visual: visualClips.some((clip) => clip.start <= 0.001 && clip.start + clip.duration > 0.001),
+        first_frame_text: openingText.length ? openingText.map((run) => run.text).join(" ").trim() : null,
+        first_text_at_sec: sortedStarts.length ? sortedStarts[0] : null,
+        max_simultaneous_text: maxSimultaneous,
+        off_regime_fonts: [...new Set(textRuns.map((run) => run.font).filter((font) => Boolean(font) && !FONT_REGIME.includes(font)))],
+        all_text: textRuns.map((run) => run.text).join(" \n ")
+    };
+}
+/** Human-readable report body (no trailing summary line — the CLI adds that). */
+export function formatQaReport(report, colors) {
+    const { red, yellow, dim, reset } = colors;
+    const lines = [];
+    for (const finding of [...report.errors, ...report.warnings]) {
+        const isError = finding.severity === "error";
+        const mark = isError ? `${red}✗ SLOP${reset}` : `${yellow}! warn${reset}`;
+        lines.push(`${mark} ${dim}[${finding.rule}]${reset} ${finding.message}`);
+        lines.push(`       ${dim}at${reset} ${finding.where}`);
+        lines.push(`       ${dim}→${reset} ${finding.fix}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=qa-check.js.map