vidspotai-shared 1.0.67 → 1.0.69-dev.0

package/lib/services/agent/planner/overlaySanity.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isStyleLeakText = isStyleLeakText;
+exports.checkOverlayContentSanity = checkOverlayContentSanity;
+/**
+ * Overlay-content sanity. The planner sometimes leaks the prompt's typography
+ * instructions into overlay.text — emitting strings like "Bold white sans-serif
+ * subtitle text with a soft drop-shadow, centered in the lower third of a 9:16
+ * frame" as the literal on-screen text. The renderer then burns that styling
+ * description onto the screen instead of the intended copy.
+ *
+ * This validator rejects overlays whose text reads like a typography / layout /
+ * color directive rather than actual copy. Detection is conservative: each
+ * single signal alone (e.g. the word "bold") is fine ("Bold moves win"), but
+ * combining a font/weight token with a position or color token in the same
+ * string is a near-certain leak.
+ */
+const FONT_WEIGHT_PATTERN = /\b(sans-?serif|serif|monospace|font-?(?:family|weight|size)|typeface|italics?|regular weight|bold(?:face)?|semi-?bold|extra-?bold|light weight|medium weight|heavy weight)\b/i;
+const POSITION_PATTERN = /\b(lower\s+third|upper\s+third|centered\s+(?:horizontally|vertically)|9\s*[:x/]\s*16(?:\s+(?:frame|aspect|ratio))?|16\s*[:x/]\s*9(?:\s+(?:frame|aspect|ratio))?|top-aligned|bottom-aligned|left-aligned|right-aligned|center-aligned|safe area)\b/i;
+const COLOR_PATTERN = /\b(white|black|gray|grey|red|blue|green|yellow|orange|purple|magenta|cyan|drop[- ]shadow|stroke|outline|#[0-9a-f]{3,8})\b/i;
+const TEXT_NOUN_PATTERN = /\b(text|font|caption|subtitle|overlay|copy|type|glyph|letters?)\b/i;
+function isStyleLeakText(text) {
+    const reasons = [];
+    const hasFontWeight = FONT_WEIGHT_PATTERN.test(text);
+    const hasPosition = POSITION_PATTERN.test(text);
+    const hasColor = COLOR_PATTERN.test(text);
+    const hasTextNoun = TEXT_NOUN_PATTERN.test(text);
+    // Position phrases (e.g. "lower third", "9:16 frame") are essentially never
+    // valid on-screen copy — flag on their own.
+    if (hasPosition)
+        reasons.push("technical position/aspect phrase");
+    // Font-family/weight + a text noun = the model is describing typography of
+    // the overlay rather than writing copy. ("Bold moves win" → no text noun,
+    // passes. "Bold sans-serif text" → font + text noun, fails.)
+    if (hasFontWeight && hasTextNoun)
+        reasons.push("font-family/weight + text noun");
+    // Color + text/font in the same string = describing how the text looks.
+    if (hasColor && hasTextNoun)
+        reasons.push("color + text/font noun");
+    return { leak: reasons.length > 0, reasons };
+}
+function checkOverlayContentSanity(plan) {
+    const offenders = [];
+    for (const s of plan.scenes) {
+        if (!s.overlays?.length)
+            continue;
+        for (const o of s.overlays) {
+            const text = (o.text ?? "").trim();
+            if (!text)
+                continue;
+            const { leak, reasons } = isStyleLeakText(text);
+            if (leak) {
+                offenders.push({
+                    sceneIndex: s.sceneIndex,
+                    role: o.role,
+                    text,
+                    reasons,
+                });
+            }
+        }
+    }
+    if (offenders.length === 0)
+        return null;
+    const roleHint = (role) => {
+        switch (role) {
+            case "headline":
+                return "max 6 words, the hook phrase";
+            case "subheadline":
+                return "max 8 words, the supporting phrase";
+            case "body":
+                return "a 6-12 word supporting line";
+            case "cta":
+                return "max 5 words combining brand + verb (e.g. 'Get HydraPure Today')";
+            case "watermark":
+                return "max 2 words, just the brand name";
+            case "disclaimer":
+                return "tiny legal copy";
+            case "label":
+                return "max 3 words naming the in-frame object/person";
+            default:
+                return "actual on-screen copy";
+        }
+    };
+    const messages = offenders.map((o) => `Overlay text for scene ${o.sceneIndex} role=${o.role} is a styling description, not actual on-screen content (matched: ${o.reasons.join("; ")}). The text field is what users will read; styling is applied automatically. Replace with the actual short phrase (for role=${o.role}: ${roleHint(o.role)}). NEVER describe fonts/colors/positions in the text field. Offending value: ${JSON.stringify(o.text)}`);
+    return messages.join("\n");
+}

package/lib/services/agent/planner/promptSections.d.ts

@@ -0,0 +1,25 @@
+import { VideoBrief } from "../../../schemas/brief.schema";
+import { AgentVisualBible } from "../../../schemas/videoPlan.schema";
+import { IBrandKitModel, IStyleMemoryModel } from "../../../models/agent.model";
+export declare function briefMentionsBrandText(brief: VideoBrief): boolean;
+/**
+ * Render the per-brief video-strategy bias into a planner-readable rule.
+ * "indirect" is the new default — ai-image-to-video is usually cheaper AND
+ * higher quality than ai-text-to-video because we can iterate on the image
+ * cheap (~$0.03/re-roll) and let the I2V model preserve that composition.
+ * "direct" is the escape hatch for shots that genuinely need T2V (continuous
+ * camera motion an image can't seed). "auto" keeps the legacy free-choice.
+ */
+export declare function buildVideoStrategySection(strategy: "direct" | "indirect" | "auto" | undefined): string;
+export declare function buildModelCatalogSection(): string;
+export declare function buildBrandKitSection(brandKit: IBrandKitModel | null): string;
+/**
+ * AG-12 — render the Visual Bible into the planner system prompt. When a
+ * bible is present, the planner MUST tag scene.bibleEntityIds with the ids
+ * of any entity appearing in the scene AND re-state each tagged entity's
+ * verbatim description in scene.prompt. This is what keeps the SAME character
+ * looking like the same character across cuts.
+ */
+export declare function buildBibleSection(bible: AgentVisualBible | null): string;
+export declare function buildStyleMemorySection(memory: IStyleMemoryModel | null): string;
+//# sourceMappingURL=promptSections.d.ts.map

package/lib/services/agent/planner/promptSections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptSections.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/promptSections.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAQhF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAGjE;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,GACnD,MAAM,CAkCR;AAED,wBAAgB,wBAAwB,IAAI,MAAM,CAWjD;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,GAAG,MAAM,CAgC5E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,MAAM,CAqCxE;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,GAAG,MAAM,CAsBhF"}

package/lib/services/agent/planner/promptSections.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.briefMentionsBrandText = briefMentionsBrandText;
+exports.buildVideoStrategySection = buildVideoStrategySection;
+exports.buildModelCatalogSection = buildModelCatalogSection;
+exports.buildBrandKitSection = buildBrandKitSection;
+exports.buildBibleSection = buildBibleSection;
+exports.buildStyleMemorySection = buildStyleMemorySection;
+const tierHelpers_1 = require("../../../globals/aiModels/tierHelpers");
+// AG-39: heuristic — does the brief signal that the planner should care
+// about on-screen brand text (so scenes get steered away from models
+// known to mangle text)? Looks at brief.brandName, brief.productName,
+// and any string field that mentions "label", "logo", "brand", "CTA",
+// "watermark", or "product name".
+function briefMentionsBrandText(brief) {
+    const blob = JSON.stringify(brief).toLowerCase();
+    return /(brand\s*name|product\s*name|brand\s*kit|logo|label|watermark|cta|on[- ]screen text|on[- ]product text)/.test(blob);
+}
+/**
+ * Render the per-brief video-strategy bias into a planner-readable rule.
+ * "indirect" is the new default — ai-image-to-video is usually cheaper AND
+ * higher quality than ai-text-to-video because we can iterate on the image
+ * cheap (~$0.03/re-roll) and let the I2V model preserve that composition.
+ * "direct" is the escape hatch for shots that genuinely need T2V (continuous
+ * camera motion an image can't seed). "auto" keeps the legacy free-choice.
+ */
+function buildVideoStrategySection(strategy) {
+    switch (strategy) {
+        case "direct":
+            return [
+                "Video-strategy bias: DIRECT (text-to-video).",
+                "  - Default video scenes to strategy=ai-text-to-video (T3).",
+                "  - Use ai-image-to-video (T2) only when the chosen T2V model lacks the",
+                "    capability needed (e.g. an aspect ratio it doesn't support).",
+            ].join("\n");
+        case "auto":
+            return [
+                "Video-strategy bias: AUTO.",
+                "  - Pick ai-text-to-video vs ai-image-to-video per scene based on cost,",
+                "    quality, and motion needs — no enforced default.",
+            ].join("\n");
+        case "indirect":
+        default:
+            return [
+                "Video-strategy bias: INDIRECT (image-to-video) — DEFAULT.",
+                "  - Default every video scene to strategy=ai-image-to-video (T2).",
+                "    Generate a still first, then animate it. Cheaper AND usually higher",
+                "    quality than direct text-to-video because:",
+                "      (a) iteration is ~$0.03 per re-rolled image vs ~$0.65 per re-rolled",
+                "          text-to-video clip, so we can vet composition before paying for",
+                "          motion.",
+                "      (b) image-to-video models preserve identity / framing / brand subject",
+                "          we already approved, instead of letting a text-to-video model",
+                "          drift mid-shot.",
+                "  - Use ai-text-to-video (T3) ONLY when the scene demands camera motion",
+                "    a static image can't seed — continuous orbit / parallax dolly /",
+                "    dynamic crowd action / something the I2V model can't synthesise from",
+                "    one keyframe. Flag this in scene.intent so reviewers know why.",
+            ].join("\n");
+    }
+}
+function buildModelCatalogSection() {
+    // Today the agent ships text-to-video and image-to-video providers; both
+    // share the same per-tier shape, and t2v is the most common executor path.
+    // Image-gen models live under a separate tool (generate_image) so they
+    // don't belong in this catalog.
+    const t2v = (0, tierHelpers_1.summarizeModelsForPlanner)("text-to-video");
+    const i2v = (0, tierHelpers_1.summarizeModelsForPlanner)("image-to-video");
+    const sections = [];
+    if (t2v)
+        sections.push("", "Text-to-video models by tier (cheapest first):", t2v);
+    if (i2v)
+        sections.push("", "Image-to-video models by tier (cheapest first):", i2v);
+    return sections.join("\n");
+}
+function buildBrandKitSection(brandKit) {
+    if (!brandKit)
+        return "";
+    const lines = [];
+    if (brandKit.brandName)
+        lines.push(`  Brand: ${brandKit.brandName}`);
+    if (brandKit.primaryColorHex || brandKit.secondaryColorHex) {
+        const palette = [brandKit.primaryColorHex, brandKit.secondaryColorHex]
+            .filter(Boolean)
+            .join(" / ");
+        lines.push(`  Palette: ${palette}`);
+    }
+    if (brandKit.fontFamily)
+        lines.push(`  Font: ${brandKit.fontFamily}`);
+    if (brandKit.voiceId)
+        lines.push(`  Preferred TTS voice id: ${brandKit.voiceId}`);
+    if (brandKit.presenterFaceUrl) {
+        lines.push(`  Presenter face URL (use as scene.avatarFaceUrl on talking-head-avatar scenes): ${brandKit.presenterFaceUrl}`);
+    }
+    if (brandKit.musicMoods?.length) {
+        lines.push(`  Music moods: ${brandKit.musicMoods.join(", ")}`);
+    }
+    if (brandKit.preferredClaims?.length) {
+        lines.push(`  Preferred phrasing: ${brandKit.preferredClaims.join("; ")}`);
+    }
+    if (brandKit.bannedClaims?.length) {
+        lines.push(`  NEVER produce these phrases: ${brandKit.bannedClaims.join("; ")}`);
+    }
+    if (!lines.length)
+        return "";
+    return [
+        "",
+        "Brand kit (set once by the user — apply on every scene):",
+        ...lines,
+    ].join("\n");
+}
+/**
+ * AG-12 — render the Visual Bible into the planner system prompt. When a
+ * bible is present, the planner MUST tag scene.bibleEntityIds with the ids
+ * of any entity appearing in the scene AND re-state each tagged entity's
+ * verbatim description in scene.prompt. This is what keeps the SAME character
+ * looking like the same character across cuts.
+ */
+function buildBibleSection(bible) {
+    if (!bible)
+        return "";
+    const characters = bible.characters ?? [];
+    const objects = bible.objects ?? [];
+    const environments = bible.environments ?? [];
+    if (!characters.length && !objects.length && !environments.length)
+        return "";
+    const formatEntity = (e) => `    ${e.id} — ${e.name}: ${e.description}`;
+    const lines = [
+        "",
+        `Visual Bible (consistency tier ${bible.consistencyTier}) — recurring entities you MUST keep visually constant across scenes:`,
+    ];
+    if (characters.length) {
+        lines.push("  Characters:");
+        characters.forEach((c) => lines.push(formatEntity(c)));
+    }
+    if (objects.length) {
+        lines.push("  Objects:");
+        objects.forEach((o) => lines.push(formatEntity(o)));
+    }
+    if (environments.length) {
+        lines.push("  Environments:");
+        environments.forEach((e) => lines.push(formatEntity(e)));
+    }
+    lines.push("", "Bible usage contract (hard rule):", "  - For every scene, set scene.bibleEntityIds to the list of entity ids that appear in that scene (e.g. [\"CHAR_1\", \"OBJ_1\"]).", "  - For every entity in scene.bibleEntityIds, re-state its description verbatim in scene.prompt. Do NOT paraphrase — copy the exact words from the bible. Different scenes referencing the same entity must use IDENTICAL description text.", "  - characterAnchorSceneIndex (AG-11) is still useful as a backup signal but the bible is primary. If both are set, both should agree.", bible.consistencyTier === "C2"
+        ? "  - C2 note: entities will additionally get pre-rendered reference images (executor threads them as inputImageUrls on image-gen calls). Your descriptions seed those reference images, so be visually specific."
+        : "  - C1 note: descriptions are the ONLY consistency signal — no reference images. Be as visually specific as possible.");
+    return lines.join("\n");
+}
+function buildStyleMemorySection(memory) {
+    if (!memory)
+        return "";
+    const accepted = (memory.acceptedScenes ?? []).slice(-3);
+    const rejected = (memory.rejectedScenes ?? []).slice(-3);
+    if (!accepted.length && !rejected.length)
+        return "";
+    const fmt = (entry) => {
+        try {
+            return JSON.stringify(entry.scene);
+        }
+        catch {
+            return "[unserializable scene]";
+        }
+    };
+    const sections = ["", "Style memory (recent decisions by this user):"];
+    if (accepted.length) {
+        sections.push("  Bias toward shapes like these (accepted):");
+        accepted.forEach((s) => sections.push(`    - ${fmt(s)}`));
+    }
+    if (rejected.length) {
+        sections.push("  Avoid shapes like these (rejected):");
+        rejected.forEach((s) => sections.push(`    - ${fmt(s)}`));
+    }
+    return sections.join("\n");
+}

package/lib/services/agent/planner/repair.d.ts

@@ -0,0 +1,16 @@
+import { VideoPlan } from "../../../schemas/videoPlan.schema";
+/**
+ * AG-33: mechanical preferredModel auto-correct. If a scene picks a model that
+ * structurally cannot serve its duration, swap to the cheapest model in the
+ * same tier whose allowed-durations list includes the scene's duration. Runs
+ * BEFORE checkSceneDurationCapability so the validator only fires for genuinely
+ * unfixable cases. Test 1 hit a 3-retry crash because the planner kept picking
+ * runway-gen4-turbo (5/8/10s only) for 2s scenes despite the system prompt
+ * + retry directive — auto-correct cuts that loop short.
+ *
+ * Selection order for a sub-5s scene: bytedance-seedance-1.0-pro-fast (T2,
+ * 2-12s, cheap) → bytedance-seedance-1.0-pro (T2) → runway-gen4.5 (T3, 2-10s)
+ * → kling-v3.0 (T3, 3-15s). Returns the count of swaps so the trace can log.
+ */
+export declare function autoCorrectPreferredModels(plan: VideoPlan): number;
+//# sourceMappingURL=repair.d.ts.map

package/lib/services/agent/planner/repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/repair.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAG9D;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CA6BlE"}

package/lib/services/agent/planner/repair.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.autoCorrectPreferredModels = autoCorrectPreferredModels;
+const tierHelpers_1 = require("../../../globals/aiModels/tierHelpers");
+/**
+ * AG-33: mechanical preferredModel auto-correct. If a scene picks a model that
+ * structurally cannot serve its duration, swap to the cheapest model in the
+ * same tier whose allowed-durations list includes the scene's duration. Runs
+ * BEFORE checkSceneDurationCapability so the validator only fires for genuinely
+ * unfixable cases. Test 1 hit a 3-retry crash because the planner kept picking
+ * runway-gen4-turbo (5/8/10s only) for 2s scenes despite the system prompt
+ * + retry directive — auto-correct cuts that loop short.
+ *
+ * Selection order for a sub-5s scene: bytedance-seedance-1.0-pro-fast (T2,
+ * 2-12s, cheap) → bytedance-seedance-1.0-pro (T2) → runway-gen4.5 (T3, 2-10s)
+ * → kling-v3.0 (T3, 3-15s). Returns the count of swaps so the trace can log.
+ */
+function autoCorrectPreferredModels(plan) {
+    // Short-duration capable models in priority order (cheap+fast first).
+    const SHORT_DURATION_FALLBACKS = [
+        "bytedance-seedance-1.0-pro-fast",
+        "bytedance-seedance-1.0-pro",
+        "runway-gen4.5",
+        "kling-v3.0",
+    ];
+    const aiVideoStrategies = new Set(["ai-image-to-video", "ai-text-to-video"]);
+    let swaps = 0;
+    for (const s of plan.scenes) {
+        if (!aiVideoStrategies.has(s.strategy))
+            continue;
+        if (!s.preferredModel)
+            continue;
+        const allowed = (0, tierHelpers_1.getModelAllowedDurations)(s.preferredModel);
+        if (!allowed)
+            continue;
+        const seconds = s.durationMs / 1000;
+        const matches = allowed.some((v) => Math.abs(v - seconds) < 0.25);
+        if (matches)
+            continue;
+        // Find the first fallback whose allowed durations include `seconds`.
+        const swapTo = SHORT_DURATION_FALLBACKS.find((m) => {
+            const a = (0, tierHelpers_1.getModelAllowedDurations)(m);
+            return a?.some((v) => Math.abs(v - seconds) < 0.25);
+        });
+        if (swapTo) {
+            s.preferredModel = swapTo;
+            swaps++;
+        }
+    }
+    return swaps;
+}

package/lib/services/agent/planner/structuralRules.d.ts

@@ -0,0 +1,10 @@
+import { VideoBrief } from "../../../schemas/brief.schema";
+/**
+ * Strict structural rules surfaced by Phase 1 dry-run (AG-8/9/10). These three
+ * gaps consistently capped UGC eval scores at 0.887 — pacing ignored, duration
+ * under-delivered, CTA caption order wrong. Spelled out as hard contracts in
+ * the planner prompt rather than soft hints, plus AG-9 also has a post-plan
+ * validator (checkDurationContract) so the planner can't silently miss it.
+ */
+export declare function buildStructuralRulesSection(brief: VideoBrief): string;
+//# sourceMappingURL=structuralRules.d.ts.map

package/lib/services/agent/planner/structuralRules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structuralRules.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/structuralRules.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAE3D;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAkJrE"}

package/lib/services/agent/planner/structuralRules.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildStructuralRulesSection = buildStructuralRulesSection;
+/**
+ * Strict structural rules surfaced by Phase 1 dry-run (AG-8/9/10). These three
+ * gaps consistently capped UGC eval scores at 0.887 — pacing ignored, duration
+ * under-delivered, CTA caption order wrong. Spelled out as hard contracts in
+ * the planner prompt rather than soft hints, plus AG-9 also has a post-plan
+ * validator (checkDurationContract) so the planner can't silently miss it.
+ */
+function buildStructuralRulesSection(brief) {
+    const lines = ["", "Strict structural rules (hard contracts):"];
+    const targetMs = brief.durationSec ? Math.round(brief.durationSec * 1000) : null;
+    if (targetMs) {
+        const minMs = Math.round(targetMs * 0.95);
+        const maxMs = Math.round(targetMs * 1.05);
+        lines.push(`  - Duration: sum of scene.durationMs MUST be within [${minMs}, ${maxMs}] ms (target ${targetMs} ms, ±5%). If short, add a B-roll scene or extend filler scenes — do NOT under-deliver on the brief's requested duration.`);
+    }
+    // Pacing → per-scene duration band. ALL pacing modes get an explicit band
+    // (not just fast-cut), because without one the planner defaults to its own
+    // bias and ships 15×2s scenes for a 30s "medium pacing / informational"
+    // brief. The band is derived from pacing, then clamped against the 2000ms
+    // provider floor. Scene count is derived from totalDurationMs / avg band.
+    //
+    //   very-fast → 2.0-3.0s   (TikTok / Reels listicle, beat-cut energy)
+    //   fast      → 3.0-4.0s   (UGC ad, social recap)
+    //   medium    → 4.0-6.0s   (narration-driven explainers, faceless-YT)
+    //   slow      → 6.0-10.0s  (cinematic / ambient)
+    //
+    // Hook (sceneIndex 0) may run up to the upper band of the next-faster mode
+    // to set up the problem statement. Provider floor 2000ms always wins.
+    const PACING_BANDS_MS = {
+        "very-fast": { minMs: 2000, maxMs: 3000 },
+        fast: { minMs: 3000, maxMs: 4000 },
+        medium: { minMs: 4000, maxMs: 6000 },
+        slow: { minMs: 6000, maxMs: 10000 },
+    };
+    // faceless-yt removed from fastCutNiches: it covers calm educational
+    // explainers (1-2 sentences per cut on 4-6s scenes) as often as listicles.
+    // Brief.pacing="fast"/"very-fast" is the listicle signal now.
+    const fastCutNiches = ["ugc-ad", "social-recap", "fitness"];
+    const effectivePacing = brief.pacing ??
+        ((brief.niche && fastCutNiches.includes(brief.niche)) ? "fast" : "medium");
+    const band = PACING_BANDS_MS[effectivePacing];
+    const minMsScene = Math.max(band.minMs, 2000); // provider floor wins
+    const maxMsScene = Math.max(band.maxMs, minMsScene);
+    // Hook gets a little extra headroom (one band step faster) so the opener
+    // can set up the topic without forcing the rest of the video to match.
+    const hookMaxMs = Math.max(maxMsScene, 3000);
+    const flooredNote = minMsScene > band.minMs
+        ? ` (provider floor 2000ms overrides pacing min ${band.minMs}ms — no model accepts sub-2s clips)`
+        : "";
+    lines.push(`  - Pacing: brief.pacing="${effectivePacing}" → per-scene durationMs in [${minMsScene}, ${maxMsScene}]${flooredNote}. The hook (sceneIndex 0) may run up to ${hookMaxMs}ms.`);
+    if (targetMs) {
+        // Derive scene count from target duration / avg band (round to nearest).
+        const avgMs = Math.round((minMsScene + maxMsScene) / 2);
+        const idealCount = Math.max(1, Math.round(targetMs / avgMs));
+        const minCount = Math.max(1, Math.floor(targetMs / maxMsScene));
+        const maxCount = Math.max(minCount, Math.floor(targetMs / minMsScene));
+        lines.push(`  - Scene count: with target ${targetMs}ms and per-scene band [${minMsScene}, ${maxMsScene}]ms, plan ${minCount}-${maxCount} scenes (target ~${idealCount} scenes of ~${avgMs}ms each). For pacing="${effectivePacing}" do NOT ship more than ${maxCount} scenes — telegraphic micro-cuts are the wrong feel. Pick scene durations from the preferredModel's allowed-durations list (e.g. seedance-1.0-pro-fast supports any integer 2-12s; pixverse supports [5,8,10]).`);
+    }
+    // AG-15: provider duration capability. Every AI-video scene's durationMs/1000
+    // MUST be in the picked model's allowed durations. Hard floor: 2s — no model
+    // in the catalog accepts sub-2s clips. If pacing wants tighter cuts, REDUCE
+    // scene count (combine two micro-cuts into one ≥2s clip) rather than
+    // shipping a scene the executor can't render. Short-duration capable models:
+    //   • 2s floor: bytedance-seedance-1.0-pro / -pro-fast (T2), runway-gen4.5 (T3)
+    //   • 3s floor: kling-v3.0 (T3)
+    //   • 4s floor: google-veo-3.1 / -fast / -lite, bytedance-seedance-1.5-pro,
+    //     bytedance-seedance-2.0 / -2.0-fast
+    //   • 5s floor: kling 2.x family, pixverse all, alibaba-wan, runway-gen4-turbo
+    //   • 6s floor: minimax-hailuo-02 / 2.3 / 2.3-fast  ← do NOT pick for <6s scenes.
+    // The catalog above lists each model's "dur:..." constraint — match scene
+    // durations to it. Pacing target can still be honoured by varying scene COUNT
+    // (e.g. a 10s UGC at fast pacing = 2 scenes × 5s on pixverse, NOT 6 × 1.7s).
+    lines.push("  - Provider duration floor: every scene with strategy=ai-image-to-video or ai-text-to-video MUST have durationMs/1000 in its preferredModel's allowed durations (shown as `dur:` in the catalog). Hard universal floor is 2s — no provider accepts sub-2s clips. If a desired scene is shorter than the floor, MERGE it with the next scene instead of generating a too-short clip. For sub-5s scenes, pick from: bytedance-seedance-1.0-pro / -pro-fast (2-12s), runway-gen4.5 (2-10s), kling-v3.0 (3-15s), google-veo-3.1* (4-8s). Picking minimax-hailuo for a <6s scene is a HARD ERROR.");
+    // AG-28: voiceover-vs-scene duration budget. Without this, the planner
+    // picks scene.durationMs based on visual pacing and the TTS that comes
+    // out is consistently 1-2s longer per scene → voice clipped mid-sentence.
+    lines.push("  - Voiceover budget: every scene.voiceoverLine MUST fit inside scene.durationMs at TTS speed ~150 wpm. Rule of thumb: max words ≈ (durationMs - 250) / 400. Examples: 2000ms → ≤4 words; 2500ms → ≤5 words; 3000ms → ≤7 words; 4000ms → ≤9 words. Commas/em-dashes add ~150ms each. If your line is longer than the scene can carry, either (a) shorten the line, (b) merge with adjacent scene + extend duration, or (c) leave voiceoverLine undefined and let onScreenText carry the message. Do NOT write a 12-word line for a 2000ms scene — the stitcher will clip it.");
+    // AG-10 + AG-40: text overlay structure. Each scene gets `overlays[]` (preferred
+    // over the legacy single `onScreenText` string). Each overlay has a role that
+    // drives styling. The closing scene must include a role:'cta' overlay that
+    // combines brand + verb so the viewer leaves with both pieces of information.
+    lines.push("  - Text overlays: prefer `scene.overlays[]` (array of TextOverlay) over `onScreenText` (single string, legacy). Each overlay = { text, role, position?, animation?, bgStyle?, sizePct?, persistAcrossScenes? }. CRITICAL: `text` is the LITERAL COPY USERS WILL READ on screen — the exact words rendered. It is NOT a description of how the overlay should look. Styling is applied automatically from the role; do NOT describe it. GOOD: text:\"Your eyes lie to you\". BAD: text:\"Bold white sans-serif subtitle text in the lower third of a 9:16 frame\" (that is a styling description and will be REJECTED). Roles available: 'headline' (top, big-bold, max 6 words, the hook), 'subheadline' (lower-third, medium, max 8 words), 'body' (lower-third, small, max 14 words — a supporting line of actual copy), 'cta' (bottom, bold pill, max 5 words, MUST be on LAST scene, MUST combine brand + verb like 'Get HydraPure Today'), 'watermark' (bottom-right tiny — emit ONCE on scene 0 with persistAcrossScenes:true, just the brand name, max 2 words; the renderer auto-carries it across every subsequent scene), 'disclaimer' (tiny bottom legal), 'label' (in-frame object/person label, max 3 words). Max 4 overlays per scene. Don't put two headlines on the same scene. Don't repeat a watermark scene-by-scene — emit once and it persists. Emojis OK.");
+    // text-layout v1 — extended position vocabulary + animation/bgStyle/sizePct
+    // recommendations. Planner picks per-scene based on scene.intent / role.
+    lines.push("  - Overlay position vocabulary (set `position` explicitly to override role default): 'top', 'top-banner' (full-width strip across the top — good for category labels / counter chips), 'top-left' / 'top-right' (corner badges), 'center' (single-line emphasis), 'left-rail' (vertically-centered left 33% — product-shot copy beside the asset), 'lower-third' (default for subheadline/body), 'bottom', 'bottom-left' / 'bottom-right', 'caption-strip' (bottom-pinned word-by-word captions — TikTok-style on voiceover-driven scenes). Pick the position that matches the scene intent: hook → 'center' or 'top-banner'; product-reveal → 'left-rail' or 'lower-third'; voiceover-narration → 'caption-strip'; cta → 'lower-third' or bottom band.");
+    lines.push("  - Overlay animation (set `animation` to override role default): 'fade' (default neutral), 'slide-up' (cta / lower-third — feels intentional), 'pop' (headline / label — punchy), 'type' (typewriter — sparingly, on hook moments only), 'word-pop' (each word pops in sequentially — for hooks where you want to land the message word by word), 'highlight-current' (for caption-strip — active word brightens while others dim, mimics karaoke captions; ONLY use with position='caption-strip'). Default to 'fade' if unsure. Don't stack 'word-pop' on every scene — once or twice per video.");
+    lines.push("  - Overlay bgStyle (background decoration for legibility — set `bgStyle` to override the auto-default): 'none' (text only, no chrome), 'shadow' (drop shadow — safe default on any background), 'pill' (rounded-rect fill hugging the text — great for cta / counter chips), 'bar' (full-width edge-to-edge band — pairs with 'top-banner' or 'caption-strip'), 'outline' (glyph stroke for high contrast on busy footage). The renderer applies a smart default when omitted, so only set this when you specifically want a different treatment.");
+    lines.push("  - Overlay sizePct (optional alternative to fontSize, expressed as % of frame height, range 2–20): use for resolution-independent sizing. Typical: hook headline ~10–14, subheadline ~6–8, body ~4–6, caption-strip ~5–7, watermark ~2–3. The role default is fine 90% of the time; only set sizePct when you want emphasis bigger or smaller than the role suggests.");
+    lines.push("  - Overlay font (optional, picks from the curated pack): one of 'Inter', 'Anton', 'Bebas Neue', 'Playfair Display', 'Caveat', 'Permanent Marker', 'IBM Plex Sans', 'Space Grotesk', 'Archivo Black', 'Outfit', 'Fraunces', 'DM Serif Display'. Persona-driven pick: friendly/casual → Caveat or Outfit; bold/urgent (sales hook) → Anton, Archivo Black, or Bebas Neue; editorial/premium → Playfair Display, Fraunces, or DM Serif Display; tech/modern → Inter, Space Grotesk, or IBM Plex Sans; handmade/artisanal → Permanent Marker or Caveat. Omit `font` to use the role default (Poppins) when no persona signal is strong.");
+    // AG-37: voiceId must come from brief (real ElevenLabs ID), never invented
+    // by the LLM. Earlier runs saw the planner hallucinating descriptive labels
+    // like "female-young-adult-excited" which then got stripped by the executor.
+    lines.push("  - voiceId: leave UNDEFINED at BOTH plan level AND every scene. ElevenLabs voice IDs are 20-char opaque strings (e.g. 'EXAVITQu4vr4xnSDxMaL'). You do NOT know any of them and MUST NOT invent them. Descriptive labels like 'female-young-adult-excited' are invalid and get stripped. The orchestrator overwrites plan.voiceId post-parse from the brief; per-scene voiceId is a hallucination — never emit it. Use voiceStyle (adjective like 'excited', 'calm', 'authoritative') to convey delivery; that's what the executor maps to voice settings.");
+    // AG-44: per-scene voiceStyle. A single global tone is too coarse for an
+    // emotional arc (e.g. UGC ads that open frustrated and close excited).
+    lines.push("  - Per-scene voiceStyle: set scene.voiceStyle (adjective: 'frustrated', 'curious', 'excited', 'whispered', 'authoritative', 'calm') when the emotional beat of that scene differs from the global tone. Common pattern for UGC: scene 0 frustrated/skeptical (the problem), middle scenes curious/intrigued (the reveal), final scene excited/confident (the CTA). If a scene has no special emotional shift, omit voiceStyle and the executor uses plan.voiceStyle.");
+    // AG-11: character consistency across scenes. When the same person appears
+    // in multiple scenes, the planner must (a) describe identity verbatim each
+    // time, (b) set characterAnchorSceneIndex on later scenes pointing to the
+    // first scene the character appeared in.
+    lines.push("  - Character consistency: when the SAME person (presenter, customer, mascot) appears in multiple scenes, you MUST: (1) in the FIRST scene the character appears, write a complete identity description in scene.prompt — age range, ethnicity, hair color/length/style, build, distinctive features, exact wardrobe (color + garment type). (2) in every LATER scene with the same character, RE-STATE those identity descriptors verbatim AND set scene.characterAnchorSceneIndex to the sceneIndex of the first appearance. Do NOT write generic phrases like \"a woman doing X\" in later scenes — that produces a different face every time. If the brief implies recurring presenter (UGC ads, talking-head), assume ONE character throughout unless explicitly multi-cast.");
+    // text-layout v1 — per-scene composition decision. Optional but strongly
+    // recommended when source aspect ≠ target aspect (i.e. most stock video
+    // and avatar shots on 9:16 vertical, or vertical UGC on 16:9 horizontal).
+    // Driven by source aspect × target aspect × what's in the asset.
+    lines.push(`  - Per-scene layout: set scene.layout = { composition, focalPoint?, backgroundFill? } when the scene asset's native aspect differs from the target (${brief.aspect ?? "9:16"}), or when the scene needs a deliberate compositional choice. composition options: 'full-bleed' (asset fills frame, crop excess — use when subject is center-framed and crop won't lose it), 'letterbox' (asset native ratio centered, solid bars top/bottom — preserves composition but feels static), 'blur-fill' (asset native ratio centered with blurred copy filling the bars — modern social default, usually the right call), 'split-top' (asset top 60%, solid area bottom 40% — text panel below), 'split-bottom' (asset bottom 60%, solid area top 40% — header panel above), 'pip-bottom-right' (asset 35% size in the corner, bg fills — use when the asset's aspect can't fit cleanly, e.g. vertical clip on 16:9 target). focalPoint = { x, y } normalized 0–1 anchors the crop or composition center (defaults to {0.5, 0.5} = center). backgroundFill applies to letterbox/split/pip ('blur-extend' = blurred asset copy, 'black'/'white', 'brand-primary'/'brand-secondary', 'gradient'). Decision rule: 16:9 source on 9:16 target → 'blur-fill' if the subject sits anywhere off-center, 'full-bleed' only if center-framed; 9:16 source on 16:9 target → 'pip-bottom-right'; matching aspects → omit layout (default full-bleed).`);
+    return lines.length > 1 ? lines.join("\n") : "";
+}

package/lib/services/agent/planner/validators.d.ts

@@ -0,0 +1,65 @@
+import { VideoBrief } from "../../../schemas/brief.schema";
+import { PlannerWarning, VideoPlan } from "../../../schemas/videoPlan.schema";
+/**
+ * AG-9: hard duration contract. Returns null if the plan honours the brief's
+ * requested duration within 10%, otherwise returns a correction message to
+ * feed back to the planner on retry.
+ */
+export declare function checkDurationContract(plan: VideoPlan, brief: VideoBrief): string | null;
+/**
+ * Captions contract. Faceless-YT explainers / TikTok shorts / any brief that
+ * mentions "captions" or "subtitles" MUST ship with at least one overlay per
+ * scene (the audience is sound-off by default). Returns a correction directive
+ * when the contract is broken; null when satisfied or N/A.
+ *
+ * Talking-head-avatar scenes are exempt — the avatar IS the on-screen text
+ * substitute and burned-in captions on top of a presenter feel cluttered.
+ */
+export declare function checkCaptionsContract(plan: VideoPlan, brief: VideoBrief): string | null;
+/**
+ * Narration-density contract. When a plan is narration-driven (>50% of scenes
+ * carry a voiceoverLine) AND brief.pacing is "medium" or "slow", every scene
+ * MUST be >= 3500ms. Sub-3.5s narration scenes produce telegraphic 3-4 word
+ * lines that read like a TikTok listicle instead of an informational explainer
+ * — the failure mode the user hit with 15×2s scenes for a 30s faceless-yt
+ * brief at medium pacing. Returns null when the plan satisfies the contract
+ * or the contract doesn't apply (fast/very-fast pacing, or VO-light plans).
+ */
+export declare function checkNarrationDensityContract(plan: VideoPlan, brief: VideoBrief): string | null;
+/**
+ * AG-28: per-scene voiceover-budget validator. Estimates TTS duration from the
+ * VO line's word count + punctuation. If the estimate exceeds the scene's
+ * durationMs by >10%, return a correction directive listing the offending
+ * scenes + the max word count that would fit. The planner can either shorten
+ * the line or merge with the next scene on retry.
+ */
+export declare function checkSceneTtsBudget(plan: VideoPlan): string | null;
+/**
+ * AG-15: per-scene duration-capability validator. For each scene using an AI
+ * video provider (ai-image-to-video / ai-text-to-video), confirm that
+ * scene.durationMs/1000 is in the preferredModel's allowed-durations list. On
+ * mismatch, build a directive correction the planner can act on: name the
+ * offending scenes + suggest a model whose `dur:` range actually accepts the
+ * requested duration. Root cause for Test-1 burning $0 of useful work: planner
+ * picked minimax-hailuo-02 (6s / 10s only) for 1.7s scenes — fallback chain
+ * exhausted because every fallback was also a ≥6s model.
+ */
+export declare function checkSceneDurationCapability(plan: VideoPlan): string | null;
+/**
+ * Warning-channel siblings of the rejection validators above. These run on
+ * an already-approved plan (or after a sceneEdit patch) and produce
+ * PlannerWarning entries the UI can surface — never rejection strings.
+ */
+/** Demote vo-clip rejections to warnings after the planner has exhausted retries. */
+export declare function collectSceneVoClipWarnings(plan: VideoPlan): PlannerWarning[];
+/**
+ * Warn when a scene's VO ends notably before the scene itself ends — that
+ * extra time renders as silence over a continuing visual, which reads as
+ * dead air on most formats. Suppressed when `scene.allowTrailingSilence`
+ * is set (visual-led moments). Scenes without VO are exempt (silence by
+ * design — handled by music / ambience tracks).
+ */
+export declare function collectSceneTrailingSilenceWarnings(plan: VideoPlan): PlannerWarning[];
+/** One-shot helper: returns the full warning set for a plan + scene overrides. */
+export declare function collectPlanWarnings(plan: VideoPlan): PlannerWarning[];
+//# sourceMappingURL=validators.d.ts.map

package/lib/services/agent/planner/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/validators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAe9E;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CA4BvF;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CA6BvF;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,UAAU,GAChB,MAAM,GAAG,IAAI,CAuBf;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAgClE;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAyC3E;AAED;;;;GAIG;AAEH,qFAAqF;AACrF,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,SAAS,GAAG,cAAc,EAAE,CA2B5E;AAED;;;;;;GAMG;AACH,wBAAgB,mCAAmC,CACjD,IAAI,EAAE,SAAS,GACd,cAAc,EAAE,CAyBlB;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,cAAc,EAAE,CAKrE"}