vidspotai-shared 1.0.67 → 1.0.69-dev.0

package/lib/services/agent/overlayRenderer.js

@@ -0,0 +1,253 @@
+"use strict";
+/**
+ * AG-40 — overlay renderer. Turns a `TextOverlay[]` into a list of ffmpeg
+ * `drawtext` filter expressions ready to chain in a `-filter_complex` graph.
+ *
+ * Word-wrap policy:
+ *   - Each role has a `maxWidthFraction` (e.g. 0.88 of frame width).
+ *   - We estimate text width as `chars * fontSize * 0.55` (Arial-ish ratio).
+ *   - If a line exceeds the max width, greedy word-wrap into multiple lines.
+ *   - If a single word exceeds max width even alone, we shrink fontSize stepwise.
+ *
+ * Anti-emoji guard:
+ *   drawtext can't render colour glyphs without libass — strip surrogate-pair
+ *   emoji upfront. Was the cause of "the H is cut off" mishap in Test 1: the
+ *   "🌊" wasn't rendered but its width was counted toward layout.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderOverlay = renderOverlay;
+exports.renderOverlayChain = renderOverlayChain;
+exports.expandPersistentOverlays = expandPersistentOverlays;
+const textOverlayStyles_1 = require("./textOverlayStyles");
+/**
+ * Strip emojis + chars drawtext can't render. Emojis are stripped because
+ * the colour-glyph rendering needs libass, not drawtext. Other control chars
+ * get cleaned out for the same reason.
+ */
+function stripEmoji(s) {
+    return s
+        .replace(/[\u{1F300}-\u{1FAFF}\u{2600}-\u{27BF}\u{FE0F}\u{200D}]/gu, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/**
+ * Greedy word-wrap. Given a max char count per line, returns the text split
+ * into lines. If a single word exceeds the budget, the line gets that word
+ * alone — caller handles font shrink in that case.
+ */
+function wrapWords(text, maxCharsPerLine) {
+    if (maxCharsPerLine <= 0)
+        return [text];
+    const words = text.split(/\s+/).filter(Boolean);
+    const lines = [];
+    let current = "";
+    for (const w of words) {
+        if (!current) {
+            current = w;
+            continue;
+        }
+        if ((current + " " + w).length <= maxCharsPerLine) {
+            current += " " + w;
+        }
+        else {
+            lines.push(current);
+            current = w;
+        }
+    }
+    if (current)
+        lines.push(current);
+    return lines;
+}
+/**
+ * Approximate char width relative to font size. 0.55 is a decent fit for
+ * Arial-family sans-serif at mixed case. Bolder weights are slightly wider —
+ * we bump to 0.6 for bold/black to be safe.
+ */
+function avgCharWidth(fontSizePx, weight) {
+    const ratio = weight === "bold" || weight === "black" ? 0.6 : 0.55;
+    return fontSizePx * ratio;
+}
+/**
+ * Escape a literal text string for ffmpeg drawtext filter syntax. Special chars
+ * that need escaping inside single-quoted drawtext text=: backslash, single
+ * quote, colon. Newlines stay literal "\n" in the text expression — drawtext
+ * with `text_align=center` and `\n` produces multi-line output (modern ffmpeg)
+ * or we pre-render each line as a separate drawtext with y offsets (compat).
+ */
+function escapeDrawtext(s) {
+    return s
+        .replace(/\\/g, "\\\\")
+        .replace(/:/g, "\\:")
+        .replace(/'/g, "\\'")
+        .replace(/%/g, "\\%");
+}
+/**
+ * Compute x/y ffmpeg expressions for a given position. ffmpeg drawtext
+ * accepts `x` / `y` as expressions referencing `w` (frame W), `h`, `text_w`,
+ * `text_h`.
+ */
+function positionExprs(position, edgePadPx) {
+    switch (position) {
+        case "top":
+            return { x: "(w-text_w)/2", y: `${edgePadPx}` };
+        case "top-left":
+            return { x: `${edgePadPx}`, y: `${edgePadPx}` };
+        case "top-right":
+            return { x: `w-text_w-${edgePadPx}`, y: `${edgePadPx}` };
+        case "center":
+            return { x: "(w-text_w)/2", y: "(h-text_h)/2" };
+        case "lower-third":
+            return { x: "(w-text_w)/2", y: "h*0.66" };
+        case "bottom":
+            return { x: "(w-text_w)/2", y: `h-text_h-${edgePadPx}` };
+        case "bottom-left":
+            return { x: `${edgePadPx}`, y: `h-text_h-${edgePadPx}` };
+        case "bottom-right":
+            return { x: `w-text_w-${edgePadPx}`, y: `h-text_h-${edgePadPx}` };
+        default:
+            return { x: "(w-text_w)/2", y: `h-text_h-${edgePadPx}` };
+    }
+}
+/**
+ * Convert animation kind + scene timing into ffmpeg drawtext `enable` and
+ * `alpha` expressions. Best-effort: fade and pop are supported; type/slide-up
+ * fall back to plain (drawtext can't do per-glyph typewriter without -filter_complex
+ * gymnastics).
+ */
+function animationExprs(_animation, startSec, endSec) {
+    // ffmpeg filter graph parser treats commas as filter separators even inside
+    // single-quoted option values when used with -vf. Multi-term expressions like
+    // `min(1,max(0,...))` were being split into "filters" by ffmpeg, producing
+    // `No such filter: '0.000'`. Quoted commas inside drawtext's `between(...)`
+    // also fail unless explicitly escaped. Escape commas with `\,` per ffmpeg
+    // filter-graph quoting rules. We keep things simple: only emit the `enable`
+    // gate (no alpha) — short overlays don't need a fade-out to look acceptable.
+    const enable = `between(t\\,${startSec.toFixed(3)}\\,${endSec.toFixed(3)})`;
+    return { enable };
+}
+/**
+ * Build one drawtext expression for a single overlay. Returns the expression
+ * plus debug metadata. Caller chains many of these with `,` (or splits per
+ * scene depending on its mux structure).
+ */
+function renderOverlay(overlay, ctx) {
+    const resolved = (0, textOverlayStyles_1.resolveOverlayStyle)(overlay);
+    // 1. Compute initial font size from frame height + max width budget in px.
+    let fontSizePx = typeof overlay.fontSize === "number"
+        ? overlay.fontSize
+        : Math.round(ctx.frameHeight * resolved.fontSizeFraction);
+    const maxWidthPx = ctx.frameWidth * resolved.maxWidthFraction;
+    const edgePadPx = Math.round(Math.min(ctx.frameWidth, ctx.frameHeight) * resolved.edgePaddingFraction);
+    // 2. Clean text (strip emoji) — same content the user sees.
+    const cleanText = stripEmoji(overlay.text);
+    // 3. Wrap by char budget, auto-shrinking until widest line fits the width
+    //    budget. Cap at 6 shrink passes (each -10%) so we don't infinite-loop
+    //    on an absurd single word.
+    let lines = [cleanText];
+    for (let pass = 0; pass < 6; pass++) {
+        const charW = avgCharWidth(fontSizePx, resolved.weight);
+        const maxCharsPerLine = Math.max(1, Math.floor(maxWidthPx / charW));
+        lines = wrapWords(cleanText, maxCharsPerLine);
+        // Check that no single line is over-wide (an unwrappable long word).
+        const widestPx = Math.max(...lines.map((l) => l.length * charW));
+        if (widestPx <= maxWidthPx)
+            break;
+        // Shrink ~10% and retry.
+        fontSizePx = Math.max(12, Math.round(fontSizePx * 0.9));
+    }
+    // Multi-line text in drawtext requires either a real newline (which breaks
+    // -vf parsing) or a doubly-escaped backslash that survives filter-graph
+    // unescape and reaches drawtext as `\n`. The single-escape form ("\\n",
+    // 2 chars: backslash+n) gets stripped by the filter parser and drawtext
+    // renders a literal "n" glyph — that's what produced "yournwatertasten"
+    // in the Test 1 repair. Use a 4-char source escape so drawtext sees `\n`.
+    const wrapped = lines.map(escapeDrawtext).join("\\\\n");
+    const startSec = (overlay.startMs ?? 0) / 1000;
+    const endSec = (overlay.endMs ?? overlay.startMs ?? ctx.sceneDurationSec * 1000) / 1000;
+    // Default end = scene end when no endMs given.
+    const effectiveEnd = overlay.endMs !== undefined ? endSec : ctx.sceneDurationSec;
+    const effectiveStart = startSec;
+    const { x, y } = positionExprs(resolved.position, edgePadPx);
+    const anim = animationExprs(resolved.animation, effectiveStart, effectiveEnd);
+    // Compose drawtext expression. Order: fontfile, text, fontsize, fontcolor,
+    // box (if bgColor), borderw + bordercolor (stroke), x, y, enable, alpha.
+    const parts = [];
+    parts.push(`fontfile='${ctx.fontFile.replace(/'/g, "\\'")}'`);
+    // Wrap the multi-line text in single quotes for the filter; we already
+    // escaped colons + quotes + backslashes inside.
+    parts.push(`text='${wrapped}'`);
+    parts.push(`fontsize=${fontSizePx}`);
+    parts.push(`fontcolor=${resolved.color}`);
+    if (resolved.bgColor) {
+        parts.push("box=1");
+        parts.push(`boxcolor=${resolved.bgColor}@${(resolved.bgAlpha ?? 0.85).toFixed(2)}`);
+        parts.push("boxborderw=18");
+    }
+    if (resolved.strokeWidth > 0) {
+        parts.push(`borderw=${resolved.strokeWidth}`);
+        parts.push(`bordercolor=${resolved.strokeColor}`);
+    }
+    parts.push("line_spacing=12");
+    parts.push("text_align=C");
+    parts.push(`x=${x}`);
+    parts.push(`y=${y}`);
+    parts.push(`enable='${anim.enable}'`);
+    if (anim.alpha)
+        parts.push(`alpha='${anim.alpha}'`);
+    return {
+        drawtextExpr: `drawtext=${parts.join(":")}`,
+        source: overlay,
+        resolved,
+        finalFontSizePx: fontSizePx,
+        finalText: wrapped,
+        lineCount: lines.length,
+    };
+}
+/**
+ * Render many overlays into a single chained filter expression, joined by
+ * commas. Caller pipes it through `-vf` (single video stream) or wraps in
+ * `-filter_complex` if mixing with other filters.
+ */
+function renderOverlayChain(overlays, ctx) {
+    const rendered = overlays.map((o) => renderOverlay(o, ctx));
+    return {
+        vfilter: rendered.map((r) => r.drawtextExpr).join(","),
+        rendered,
+    };
+}
+/**
+ * AG-40: persist-across-scenes resolver. Given the per-scene overlay arrays
+ * in playback order, append any overlay flagged `persistAcrossScenes` (or with
+ * a role whose default-persist is true, like watermark) onto every subsequent
+ * scene that doesn't already have an overlay of the same role.
+ *
+ * This is what lets the planner emit a watermark exactly once (on scene 0) and
+ * have it appear on every scene — no need to repeat it scene-by-scene.
+ */
+function expandPersistentOverlays(perScene) {
+    const sticky = [];
+    const out = [];
+    for (const sceneOverlays of perScene) {
+        const own = sceneOverlays ?? [];
+        // Inject sticky overlays at the front, but skip any whose role this scene
+        // already has explicitly (per-scene override wins).
+        const ownRoles = new Set(own.map((o) => o.role));
+        const carried = sticky.filter((o) => !ownRoles.has(o.role));
+        const final = [...carried, ...own];
+        out.push(final);
+        // Update sticky stack with this scene's persistent overlays.
+        for (const o of own) {
+            const persist = o.persistAcrossScenes ??
+                ((0, textOverlayStyles_1.resolveOverlayStyle)(o).persistAcrossScenesDefault ?? false);
+            if (persist) {
+                // Replace existing sticky of same role with the newer instance.
+                const idx = sticky.findIndex((s) => s.role === o.role);
+                if (idx >= 0)
+                    sticky[idx] = o;
+                else
+                    sticky.push(o);
+            }
+        }
+    }
+    return out;
+}

package/lib/services/agent/perSceneCritic.d.ts

@@ -0,0 +1,90 @@
+/**
+ * AG-43: per-scene critic. Runs a lightweight Gemini Flash pass on each scene's
+ * raw MP4 *before* stitch, focused on the failure modes that show up in a
+ * single clip (action plausibility, character drift across the clip's own
+ * frames, brand label legibility, prompt adherence). The full stitched critic
+ * (stitchedVideoCritic.ts) still grades the assembled result — this is an
+ * earlier safety net so we can flag broken scenes and queue targeted re-gens
+ * via AG-41 instead of paying for a stitch + critic over already-broken assets.
+ *
+ * Cost: ~$0.0001 per scene (Gemini Flash, ~3s clip ≈ 800 input tokens). For a
+ * 5-scene plan that's ~$0.0005 total — negligible vs the $0.20-0.50 we save
+ * by re-generating one scene instead of the whole thing.
+ */
+import { z } from "zod";
+export declare const PerSceneFindingSchema: z.ZodObject<{
+    severity: z.ZodEnum<{
+        fail: "fail";
+        warn: "warn";
+        pass: "pass";
+    }>;
+    dimension: z.ZodEnum<{
+        brandTextLegibility: "brandTextLegibility";
+        actionPlausibility: "actionPlausibility";
+        promptAdherence: "promptAdherence";
+        characterDrift: "characterDrift";
+        compositionQuality: "compositionQuality";
+        motionQuality: "motionQuality";
+    }>;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type PerSceneFinding = z.infer<typeof PerSceneFindingSchema>;
+export declare const PerSceneReviewSchema: z.ZodObject<{
+    sceneIndex: z.ZodNumber;
+    score: z.ZodNumber;
+    shippable: z.ZodBoolean;
+    summary: z.ZodString;
+    findings: z.ZodArray<z.ZodObject<{
+        severity: z.ZodEnum<{
+            fail: "fail";
+            warn: "warn";
+            pass: "pass";
+        }>;
+        dimension: z.ZodEnum<{
+            brandTextLegibility: "brandTextLegibility";
+            actionPlausibility: "actionPlausibility";
+            promptAdherence: "promptAdherence";
+            characterDrift: "characterDrift";
+            compositionQuality: "compositionQuality";
+            motionQuality: "motionQuality";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+    recommendRegenerate: z.ZodBoolean;
+}, z.core.$strip>;
+export type PerSceneReview = z.infer<typeof PerSceneReviewSchema>;
+export interface PerSceneCriticInput {
+    sceneIndex: number;
+    videoUrl: string;
+    /** Original visual prompt the model was given. */
+    prompt: string;
+    /** Optional spoken line for context (don't grade audio — there is none yet). */
+    voiceoverLine?: string;
+    /** Optional on-screen text that overlays will burn later. */
+    onScreenText?: string;
+    /** Bible entities so we know what objects/characters should be present. */
+    expectedEntities?: Array<{
+        name: string;
+        kind: "character" | "object" | "environment";
+    }>;
+}
+export declare function buildPerSceneCriticPrompt(input: PerSceneCriticInput): string;
+/**
+ * Run the per-scene critic. Caller passes the same Gemini invoker the stitched
+ * critic uses; only difference is the prompt + smaller response schema.
+ */
+export declare function runPerSceneCritic(input: PerSceneCriticInput, invokeGemini: (args: {
+    prompt: string;
+    videoUrl: string;
+    responseSchema: z.ZodType<PerSceneReview>;
+}) => Promise<PerSceneReview>): Promise<PerSceneReview>;
+/**
+ * Convenience: run the per-scene critic over many scenes in parallel (capped
+ * concurrency to keep Gemini quota safe).
+ */
+export declare function runPerSceneCriticBatch(scenes: PerSceneCriticInput[], invokeGemini: (args: {
+    prompt: string;
+    videoUrl: string;
+    responseSchema: z.ZodType<PerSceneReview>;
+}) => Promise<PerSceneReview>, concurrency?: number): Promise<PerSceneReview[]>;
+//# sourceMappingURL=perSceneCritic.d.ts.map

package/lib/services/agent/perSceneCritic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perSceneCritic.d.ts","sourceRoot":"","sources":["../../../src/services/agent/perSceneCritic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;iBAWhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;iBAY/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,WAAW,GAAG,QAAQ,GAAG,aAAa,CAAA;KAAE,CAAC,CAAC;CAC1F;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAgC5E;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,mBAAmB,EAC1B,YAAY,EAAE,CAAC,IAAI,EAAE;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;CAC3C,KAAK,OAAO,CAAC,cAAc,CAAC,GAC5B,OAAO,CAAC,cAAc,CAAC,CAuBzB;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,mBAAmB,EAAE,EAC7B,YAAY,EAAE,CAAC,IAAI,EAAE;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;CAC3C,KAAK,OAAO,CAAC,cAAc,CAAC,EAC7B,WAAW,SAAI,GACd,OAAO,CAAC,cAAc,EAAE,CAAC,CAY3B"}

package/lib/services/agent/perSceneCritic.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * AG-43: per-scene critic. Runs a lightweight Gemini Flash pass on each scene's
+ * raw MP4 *before* stitch, focused on the failure modes that show up in a
+ * single clip (action plausibility, character drift across the clip's own
+ * frames, brand label legibility, prompt adherence). The full stitched critic
+ * (stitchedVideoCritic.ts) still grades the assembled result — this is an
+ * earlier safety net so we can flag broken scenes and queue targeted re-gens
+ * via AG-41 instead of paying for a stitch + critic over already-broken assets.
+ *
+ * Cost: ~$0.0001 per scene (Gemini Flash, ~3s clip ≈ 800 input tokens). For a
+ * 5-scene plan that's ~$0.0005 total — negligible vs the $0.20-0.50 we save
+ * by re-generating one scene instead of the whole thing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PerSceneReviewSchema = exports.PerSceneFindingSchema = void 0;
+exports.buildPerSceneCriticPrompt = buildPerSceneCriticPrompt;
+exports.runPerSceneCritic = runPerSceneCritic;
+exports.runPerSceneCriticBatch = runPerSceneCriticBatch;
+const zod_1 = require("zod");
+const logger_1 = require("../../utils/logger");
+exports.PerSceneFindingSchema = zod_1.z.object({
+    severity: zod_1.z.enum(["pass", "warn", "fail"]),
+    dimension: zod_1.z.enum([
+        "actionPlausibility",
+        "promptAdherence",
+        "brandTextLegibility",
+        "characterDrift",
+        "compositionQuality",
+        "motionQuality",
+    ]),
+    message: zod_1.z.string().min(4),
+});
+exports.PerSceneReviewSchema = zod_1.z.object({
+    sceneIndex: zod_1.z.number().int().nonnegative(),
+    score: zod_1.z.number().min(0).max(10),
+    shippable: zod_1.z.boolean(),
+    summary: zod_1.z.string().min(8).max(400),
+    findings: zod_1.z.array(exports.PerSceneFindingSchema),
+    /**
+     * Critic recommends regenerating this scene if true — usually because at
+     * least one FAIL finding fired. AG-41 edit-classifier reads this to decide
+     * whether to surface a `modify-scene-visual` edit suggestion.
+     */
+    recommendRegenerate: zod_1.z.boolean(),
+});
+function buildPerSceneCriticPrompt(input) {
+    const entities = input.expectedEntities?.length
+        ? input.expectedEntities.map((e) => `  - ${e.kind}: ${e.name}`).join("\n")
+        : "  (none specified)";
+    return [
+        "You are a per-scene QC reviewer for AI-generated short ad clips.",
+        "WATCH the attached video (silent, no audio yet — judge VISUALS only).",
+        "Grade against the spec and rubric below. Be strict — this is the pre-stitch",
+        "safety net that catches breakage worth a re-generation.",
+        "",
+        `Scene index: ${input.sceneIndex}`,
+        `Visual prompt the model was given:`,
+        `  """${input.prompt}"""`,
+        input.voiceoverLine ? `Spoken line (for context — will be added later):\n  """${input.voiceoverLine}"""` : "",
+        input.onScreenText ? `Planned on-screen text (will be overlaid later):\n  """${input.onScreenText}"""` : "",
+        "Expected entities in the frame (from the visual bible):",
+        entities,
+        "",
+        "Rubric — score each dimension pass / warn / fail:",
+        "  - actionPlausibility  : every visible action must be physically possible given the state of the objects on screen. MUST flag FAIL: drinking from a sealed/capped bottle, pouring from a closed container, using a phone with a dark screen, walking through a closed door, etc. Pay attention to caps, lids, seals, buttons, doors, switches.",
+        "  - promptAdherence     : does the scene actually depict what the prompt asked for, or did the model drift?",
+        "  - brandTextLegibility : if a product label is visible, is the brand name spelled correctly and readable?",
+        "  - characterDrift      : within this single scene, does the person stay the same throughout (no morphing mid-clip)?",
+        "  - compositionQuality  : framing, lighting, focus all professional — not amateur / blurry / mis-composed?",
+        "  - motionQuality       : motion feels natural — no warping limbs, melting faces, teleporting objects?",
+        "",
+        "Set recommendRegenerate=true if ANY dimension is FAIL. The orchestrator will queue a targeted re-generation",
+        "(keeping all other scenes + voice + music intact) when this is true, so be honest — a generous PASS",
+        "when you should have said FAIL costs more than a strict FAIL when you should have said WARN.",
+        "",
+        "Output JSON exactly matching the response schema.",
+    ].filter(Boolean).join("\n");
+}
+/**
+ * Run the per-scene critic. Caller passes the same Gemini invoker the stitched
+ * critic uses; only difference is the prompt + smaller response schema.
+ */
+async function runPerSceneCritic(input, invokeGemini) {
+    try {
+        const prompt = buildPerSceneCriticPrompt(input);
+        const review = await invokeGemini({
+            prompt,
+            videoUrl: input.videoUrl,
+            responseSchema: exports.PerSceneReviewSchema,
+        });
+        return { ...review, sceneIndex: input.sceneIndex };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        logger_1.logger.warn("perSceneCritic failed; soft-fail review", { sceneIndex: input.sceneIndex, err: msg });
+        return {
+            sceneIndex: input.sceneIndex,
+            score: 0,
+            shippable: false,
+            summary: `Per-scene critic failed: ${msg}. Manual review required.`,
+            findings: [
+                { severity: "warn", dimension: "compositionQuality", message: `Critic call failed: ${msg}` },
+            ],
+            recommendRegenerate: false,
+        };
+    }
+}
+/**
+ * Convenience: run the per-scene critic over many scenes in parallel (capped
+ * concurrency to keep Gemini quota safe).
+ */
+async function runPerSceneCriticBatch(scenes, invokeGemini, concurrency = 3) {
+    const out = [];
+    let i = 0;
+    async function worker() {
+        while (i < scenes.length) {
+            const idx = i++;
+            const scene = scenes[idx];
+            out[idx] = await runPerSceneCritic(scene, invokeGemini);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, scenes.length) }, worker));
+    return out;
+}

package/lib/services/agent/personas.d.ts

@@ -0,0 +1,78 @@
+import { AgentPersona, AgentPersonaSchema } from "../../schemas/agentPersona.schema";
+import { LlmCaller } from "./llmCaller";
+import { ModelRouter } from "./modelRouter";
+export type { AgentPersona };
+export { AgentPersonaSchema };
+/**
+ * Vertical agent personas. Each persona = curated planner system prompt
+ * + recommended tier mix + critic rubric. Router LLM picks the persona
+ * from the user's first message (single classification call, Haiku-tier).
+ *
+ * Why personas: vertical specialisation is what makes a small model and
+ * a small team feel like a domain expert. invideo / Captions both win
+ * on this. v1 ships 5; v2 adds general + niche personas.
+ */
+export interface PersonaPack {
+    id: AgentPersona;
+    /** Short user-facing label. */
+    label: string;
+    /** Single-sentence pitch shown in persona picker. */
+    blurb: string;
+    /** Default brief axes the persona pre-fills (used when LLM confidence is low). */
+    defaults: {
+        aspect: "16:9" | "9:16" | "1:1";
+        durationSec: number;
+        tone: string;
+        pacing: "slow" | "medium" | "fast" | "very-fast";
+        hookStyle: string;
+        tierBudget: "T0" | "T1" | "T2" | "T3";
+    };
+    /** Planner system-prompt addendum: niche-specific structural priors. */
+    plannerPrompt: string;
+    /**
+     * Default BPM for the beat-snap pass when neither the user nor the planner
+     * specifies one. Personas where steady BPM cuts feel right (recap, UGC) set
+     * a value; cinematic / educational personas leave it undefined so cuts stay
+     * free-form.
+     */
+    defaultBpm?: number;
+    /** Critic rubric weights (override the global judge). */
+    criticEmphasis: Partial<{
+        hookStrength: number;
+        voVisualSync: number;
+        pacingFit: number;
+        brandSafety: number;
+        costVsTier: number;
+        intentMatch: number;
+    }>;
+    /**
+     * AG-30: recommended consistency tier for this persona. Used as the default
+     * when the brief leaves `consistencyTier` undefined. Character-driven
+     * personas (UGC, talking-head, product-demo with presenter) need C2 — text
+     * descriptions alone do not anchor faces tightly enough across scenes, so
+     * we end up with a different actor in every cut. Stock-driven personas
+     * (recipe B-roll, travel) stay on C1 since there's no recurring face.
+     */
+    recommendedConsistencyTier?: "C0" | "C1" | "C2";
+}
+export declare const PERSONA_PACKS: Record<AgentPersona, PersonaPack>;
+/**
+ * AG-30: resolve the consistency tier for an agent run. Brief wins when set
+ * explicitly; otherwise fall back to the persona's recommendation; otherwise
+ * the safe global default of C1. UGC / talking-head / product-demo
+ * recommend C2 because the same presenter/product needs to look identical
+ * across cuts — text descriptions alone produce a different actor every
+ * scene (Test 1 had 5 different women in 5 scenes on C1).
+ */
+export declare function resolveConsistencyTier(persona: AgentPersona | undefined, briefTier: "C0" | "C1" | "C2" | undefined): "C0" | "C1" | "C2";
+export declare class PersonaRouter {
+    private readonly llm;
+    private readonly router;
+    constructor(llm: LlmCaller, router?: ModelRouter);
+    route(rawPrompt: string): Promise<{
+        persona: AgentPersona;
+        confidence: number;
+        reason: string;
+    }>;
+}
+//# sourceMappingURL=personas.d.ts.map

package/lib/services/agent/personas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"personas.d.ts","sourceRoot":"","sources":["../../../src/services/agent/personas.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EACZ,kBAAkB,EACnB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,YAAY,EAAE,YAAY,EAAE,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAE9B;;;;;;;;GAQG;AAEH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,YAAY,CAAC;IACjB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,QAAQ,EAAE;QACR,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;QAChC,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;QACjD,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;KACvC,CAAC;IACF,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,cAAc,EAAE,OAAO,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IACH;;;;;;;OAOG;IACH,0BAA0B,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;CACjD;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,YAAY,EAAE,WAAW,CAmH3D,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,YAAY,GAAG,SAAS,EACjC,SAAS,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,GACxC,IAAI,GAAG,IAAI,GAAG,IAAI,CAIpB;AAQD,qBAAa,aAAa;IAEtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,GAAG,EAAE,SAAS,EACd,MAAM,GAAE,WAA+B;IAGpD,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QACtC,OAAO,EAAE,YAAY,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CA4BH"}