@officexapp/vidfarm-devcli 0.21.27 → 0.21.28

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

@@ -0,0 +1,420 @@
+// 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.
+//
+// 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;
+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."
+                });
+            }
+        }
+    }
+    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
+        }
+    };
+}
+/** 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@officexapp/vidfarm-devcli",
-  "version": "0.21.27",
+  "version": "0.21.28",
   "description": "Local bridge for the Vidfarm Trackpad Editor. `vidfarm serve <template_id>` boots the FULL editor on localhost (disk-backed records/storage, free in-process render); edit composition.html on disk (Claude Code, Codex, etc.) and the browser live-morphs it.",
   "type": "module",
   "bin": {
@@ -24,6 +24,7 @@
     "dist/src/devcli/local-render.js",
     "dist/src/devcli/port-utils.js",
     "dist/src/devcli/process-scan.js",
+    "dist/src/devcli/qa-check.js",
     "dist/src/devcli/sequence.js",
     "dist/src/devcli/skills.js",
     "dist/src/devcli/speech.js",
@@ -86,6 +87,7 @@
     "start": "node --import ./dist/src/instrument.js --enable-source-maps dist/src/index.js",
     "check": "tsc -p tsconfig.json --noEmit && npm run check:skills",
     "test:clips": "node --import tsx --test test/clip-curation.test.ts",
+    "test:qa": "node --import tsx --test test/qa-check.test.ts",
     "check:skills": "node scripts/build-director-skill-rollup.mjs --check && node scripts/check-skill-routes.mjs",
     "benchmark:editor-chat": "node --import tsx scripts/benchmark-editor-chat-harness.mjs",
     "cdk:deploy:prod-serverless": "npm run build && dotenv -e .env.production -- npx aws-cdk deploy --app 'node dist/infra/cdk/bin/vidfarm-prod.js'",