vidspotai-shared 1.0.67 → 1.0.69-dev.0

package/lib/services/agent/modelQualityNotes.js

@@ -0,0 +1,248 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getModelCapabilityScore = getModelCapabilityScore;
+exports.renderModelQualityHintsForSystemPrompt = renderModelQualityHintsForSystemPrompt;
+exports.recordCriticEvidence = recordCriticEvidence;
+exports._dumpStore = _dumpStore;
+exports._resetCacheForTests = _resetCacheForTests;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const logger_1 = require("../../utils/logger");
+const STORAGE_PATH = path.resolve(__dirname, "..", "..", "..", "data", "model-quality-notes.json");
+// Hand-seeded baseline. Anything not listed is treated as "unknown" (no
+// hint emitted, no decay applied). Seed conservatively — better to leave a
+// capability unrated than to over-claim.
+const SEED = [
+    {
+        modelKey: "bytedance-seedance-1.0-pro-fast",
+        lastUpdated: "2026-05-17",
+        capabilities: {
+            textRendering: {
+                score: 2,
+                seedNote: "Test 1 (2026-05-17): mangled 'HydraPure' label across all 5 I2V outputs from a clean reference image. Use only for scenes without on-bottle / on-package text.",
+                evidence: [],
+            },
+            fastMotion: { score: 5, seedNote: "Fast variant — strong at action/whip-pans.", evidence: [] },
+            characterContinuity: { score: 4, seedNote: "Holds same face well over short scenes.", evidence: [] },
+            photoreal: { score: 4, evidence: [] },
+        },
+    },
+    {
+        modelKey: "bytedance-seedance-1.0-pro",
+        lastUpdated: "2026-05-17",
+        capabilities: {
+            textRendering: { score: 3, seedNote: "Pro variant — better than fast but still untested at scale on brand text.", evidence: [] },
+            photoreal: { score: 5, evidence: [] },
+            cinematic: { score: 5, evidence: [] },
+        },
+    },
+    {
+        modelKey: "runway-gen4.5",
+        lastUpdated: "2026-05-17",
+        capabilities: {
+            textRendering: { score: 4, seedNote: "Runway Gen-4 is known to preserve source-image text faithfully when given a clean reference.", evidence: [] },
+            cinematic: { score: 5, evidence: [] },
+            productFidelity: { score: 4, evidence: [] },
+        },
+    },
+    {
+        modelKey: "kling-v3.0",
+        lastUpdated: "2026-05-17",
+        capabilities: {
+            textRendering: { score: 3, evidence: [] },
+            photoreal: { score: 4, evidence: [] },
+            characterContinuity: { score: 4, evidence: [] },
+        },
+    },
+    {
+        modelKey: "pixverse-v6",
+        lastUpdated: "2026-05-17",
+        capabilities: {
+            textRendering: { score: 3, seedNote: "Untested for brand text — used as default low-cost during early dev.", evidence: [] },
+        },
+    },
+];
+const WINDOW = 10;
+const FAIL_COUNT_THRESHOLD = 3;
+const FAIL_RATE_THRESHOLD = 0.3;
+let cache;
+function readStore() {
+    if (cache)
+        return cache;
+    try {
+        if (fs.existsSync(STORAGE_PATH)) {
+            cache = JSON.parse(fs.readFileSync(STORAGE_PATH, "utf8"));
+            return cache;
+        }
+    }
+    catch (e) {
+        logger_1.logger.warn("modelQualityNotes: store read failed; using seed", {
+            err: e instanceof Error ? e.message : String(e),
+        });
+    }
+    cache = JSON.parse(JSON.stringify(SEED));
+    return cache;
+}
+function writeStore(entries) {
+    try {
+        fs.mkdirSync(path.dirname(STORAGE_PATH), { recursive: true });
+        fs.writeFileSync(STORAGE_PATH, JSON.stringify(entries, null, 2));
+        cache = entries;
+    }
+    catch (e) {
+        logger_1.logger.warn("modelQualityNotes: store write failed", {
+            err: e instanceof Error ? e.message : String(e),
+        });
+    }
+}
+function getModelCapabilityScore(modelKey, capability) {
+    const entry = readStore().find((e) => e.modelKey === modelKey);
+    return entry?.capabilities[capability]?.score;
+}
+/**
+ * Return a short paragraph the planner system prompt can paste in,
+ * listing models to AVOID per capability. Only emits hints for
+ * capabilities we have rated AND that the brief signals are relevant
+ * (so the planner isn't drowned in noise).
+ */
+function renderModelQualityHintsForSystemPrompt(opts) {
+    const lines = [];
+    const store = readStore();
+    const collect = (cap, threshold, label) => {
+        const bad = [];
+        for (const e of store) {
+            const s = e.capabilities[cap]?.score;
+            if (s !== undefined && s < threshold)
+                bad.push({ modelKey: e.modelKey, score: s });
+        }
+        if (bad.length) {
+            const list = bad.map((b) => `${b.modelKey} (score ${b.score})`).join(", ");
+            lines.push(`  - ${label}: AVOID ${list}`);
+        }
+    };
+    if (opts.needsBrandText)
+        collect("textRendering", 3, "Scene has BRAND TEXT / product labels");
+    if (opts.needsCharacterContinuity)
+        collect("characterContinuity", 3, "Scene needs SAME CHARACTER across cuts");
+    if (opts.needsFastMotion)
+        collect("fastMotion", 3, "Scene has FAST MOTION / action");
+    if (opts.needsCinematic)
+        collect("cinematic", 3, "Scene needs CINEMATIC camera moves");
+    if (lines.length === 0)
+        return "";
+    return [
+        "",
+        "Model quality evidence (from past critic runs — respect these):",
+        ...lines,
+    ].join("\n");
+}
+/**
+ * Critic feedback hook: called after every stitched-video critic run
+ * with the structured findings. We map each finding's `dimension` to a
+ * `Capability`, record evidence under the model that rendered the scene,
+ * and decay the score iff the recent-window thresholds are met.
+ */
+function recordCriticEvidence(input) {
+    const dimensionToCapability = {
+        brandTextLegibility: "textRendering",
+        characterContinuity: "characterContinuity",
+        pacingFit: undefined,
+        cutRhythm: undefined,
+        voiceoverClarity: undefined,
+        voiceoverEmotionMatch: undefined,
+        voiceoverPacing: undefined,
+        audioMixBalance: undefined,
+        musicPresence: undefined,
+        hookStrength: undefined,
+        ctaPresence: undefined,
+        overallImpression: undefined,
+    };
+    const store = readStore();
+    const decays = [];
+    for (const f of input.findings) {
+        const cap = dimensionToCapability[f.dimension];
+        if (!cap)
+            continue;
+        const sceneIdx = f.sceneIndexHint;
+        // If finding has no scene hint, it's a video-wide judgement — apply to
+        // every model used in the run so single-scene evidence doesn't get lost.
+        const targets = sceneIdx !== undefined
+            ? [input.sceneModels.get(sceneIdx)].filter((x) => !!x)
+            : [...new Set(input.sceneModels.values())];
+        for (const modelKey of targets) {
+            let entry = store.find((e) => e.modelKey === modelKey);
+            if (!entry) {
+                entry = { modelKey, lastUpdated: new Date().toISOString().slice(0, 10), capabilities: {} };
+                store.push(entry);
+            }
+            const capEntry = entry.capabilities[cap] ?? { score: 3, evidence: [] };
+            capEntry.evidence.push({
+                at: new Date().toISOString(),
+                verdict: f.severity,
+                message: f.message,
+                runId: input.runId,
+                sceneIndex: sceneIdx,
+            });
+            if (capEntry.evidence.length > WINDOW) {
+                capEntry.evidence = capEntry.evidence.slice(-WINDOW);
+            }
+            const fails = capEntry.evidence.filter((e) => e.verdict === "fail").length;
+            const rate = fails / capEntry.evidence.length;
+            if (fails >= FAIL_COUNT_THRESHOLD && rate >= FAIL_RATE_THRESHOLD && capEntry.score > 1) {
+                const from = capEntry.score;
+                capEntry.score = Math.max(1, capEntry.score - 1);
+                decays.push({ modelKey, capability: cap, from, to: capEntry.score });
+                // Reset evidence window after a decay so we don't double-penalise.
+                capEntry.evidence = [];
+            }
+            entry.capabilities[cap] = capEntry;
+            entry.lastUpdated = new Date().toISOString().slice(0, 10);
+        }
+    }
+    writeStore(store);
+    if (decays.length) {
+        logger_1.logger.info("modelQualityNotes: score decays applied", { decays });
+    }
+    return { decays };
+}
+/** For tests + manual inspection. */
+function _dumpStore() {
+    return JSON.parse(JSON.stringify(readStore()));
+}
+/** For tests — reset to seed (does NOT touch disk). */
+function _resetCacheForTests() {
+    cache = JSON.parse(JSON.stringify(SEED));
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Model router — picks the right LLM per agent role.
+ *
+ * Roles split because their cost/quality profiles differ wildly:
+ *   - router     : single classification call, pick persona from first message
+ *   - planner    : structured-output, must produce valid VideoPlan
+ *   - executor   : narrow tool-routing loop, mostly mechanical
+ *   - critic     : vision QA across scenes, rubric-following
+ *   - reference  : ingest a TikTok/Reel URL, extract structure
+ *
+ * The actual LLM call is delegated to an injected LlmCaller (wired to
+ * Vercel AI Gateway / OpenRouter at the host layer) — this keeps the
+ * agent code provider-agnostic and easy to A/B test against the eval set.
+ */
+export type AgentRole = "router" | "planner" | "executor" | "critic" | "reference";
+export interface ModelChoice {
+    /** Logical model id, e.g. "claude-sonnet-4.6", "claude-haiku-4.5", "gpt-5". */
+    modelId: string;
+    /** Provider key for the LLM gateway, e.g. "anthropic", "openai", "google". */
+    provider: string;
+    /** Vision input supported. */
+    vision?: boolean;
+}
+export interface ModelRoutingPolicy {
+    /** Default per-role model. */
+    primary: Record<AgentRole, ModelChoice>;
+    /** Fallback if primary is unavailable / rate-limited. Optional per-role. */
+    fallback?: Partial<Record<AgentRole, ModelChoice>>;
+    /** Premium tier upgrade — Premium-budget briefs route planner to this model. */
+    premiumPlanner?: ModelChoice;
+}
+export declare const DEFAULT_MODEL_ROUTING: ModelRoutingPolicy;
+export declare class ModelRouter {
+    private readonly policy;
+    constructor(policy?: ModelRoutingPolicy);
+    pickFor(role: AgentRole, opts?: {
+        premium?: boolean;
+    }): ModelChoice;
+    fallbackFor(role: AgentRole): ModelChoice | undefined;
+}
+//# sourceMappingURL=modelRouter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"modelRouter.d.ts","sourceRoot":"","sources":["../../../src/services/agent/modelRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,SAAS,GACT,UAAU,GACV,QAAQ,GACR,WAAW,CAAC;AAEhB,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACxC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IACnD,gFAAgF;IAChF,cAAc,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED,eAAO,MAAM,qBAAqB,EAAE,kBAgCnC,CAAC;AAEF,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,GAAE,kBAA0C;IAE/E,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,WAAW;IAOnE,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS;CAGtD"}

package/lib/services/agent/modelRouter.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Model router — picks the right LLM per agent role.
+ *
+ * Roles split because their cost/quality profiles differ wildly:
+ *   - router     : single classification call, pick persona from first message
+ *   - planner    : structured-output, must produce valid VideoPlan
+ *   - executor   : narrow tool-routing loop, mostly mechanical
+ *   - critic     : vision QA across scenes, rubric-following
+ *   - reference  : ingest a TikTok/Reel URL, extract structure
+ *
+ * The actual LLM call is delegated to an injected LlmCaller (wired to
+ * Vercel AI Gateway / OpenRouter at the host layer) — this keeps the
+ * agent code provider-agnostic and easy to A/B test against the eval set.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModelRouter = exports.DEFAULT_MODEL_ROUTING = void 0;
+exports.DEFAULT_MODEL_ROUTING = {
+    primary: {
+        router: { modelId: "claude-haiku-4-5", provider: "anthropic" },
+        planner: { modelId: "claude-sonnet-4-6", provider: "anthropic" },
+        executor: { modelId: "claude-haiku-4-5", provider: "anthropic" },
+        // Critic rubrics today (continuity / consistency / voSync / costVsTier)
+        // are pure perception + structured-output tasks — Gemini 2.5 Flash
+        // handles them at ~$0.002/call vs ~$0.04/call on Sonnet (20× cheaper)
+        // without measurable quality loss on perception axes. The brand-safety
+        // rubric is parked for now; when it returns, route only that axis to
+        // Sonnet (it's the policy-reasoning slice where Sonnet wins).
+        critic: {
+            modelId: "gemini-2.5-flash",
+            provider: "google",
+            vision: true,
+        },
+        reference: {
+            modelId: "gemini-2.5-pro",
+            provider: "google",
+            vision: true,
+        },
+    },
+    fallback: {
+        router: { modelId: "gpt-5-mini", provider: "openai" },
+        planner: { modelId: "gpt-5", provider: "openai" },
+        executor: { modelId: "deepseek-chat", provider: "deepseek" },
+        // Sonnet is the Critic fallback — it costs more but is the safest
+        // bet when Flash refuses or returns malformed structured output.
+        critic: { modelId: "claude-sonnet-4-6", provider: "anthropic", vision: true },
+        reference: { modelId: "claude-sonnet-4-6", provider: "anthropic" },
+    },
+    premiumPlanner: { modelId: "claude-opus-4-7", provider: "anthropic" },
+};
+class ModelRouter {
+    constructor(policy = exports.DEFAULT_MODEL_ROUTING) {
+        this.policy = policy;
+    }
+    pickFor(role, opts) {
+        if (role === "planner" && opts?.premium && this.policy.premiumPlanner) {
+            return this.policy.premiumPlanner;
+        }
+        return this.policy.primary[role];
+    }
+    fallbackFor(role) {
+        return this.policy.fallback?.[role];
+    }
+}
+exports.ModelRouter = ModelRouter;

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

@@ -0,0 +1,23 @@
+import { VideoPlan } from "../../schemas/videoPlan.schema";
+/**
+ * selectMusicForPlan — runs once after the planner returns and before the
+ * beat-snap pass, attaching a real track URL + bpm to plan.music.
+ *
+ * Why post-planner instead of letting the planner call search_music itself:
+ * the planner is a single structured-output call, not a tool-using agent.
+ * Adding a tool-call cycle here would double LLM latency and cost for a
+ * step that is fully mechanical — query string → provider → URL.
+ *
+ * No-ops when:
+ *   - plan.music.strategy === "none"
+ *   - plan.music.url is already set (user / brand kit pre-selected a track)
+ *   - all music providers are unconfigured (curated catalog should always
+ *     be available, so this branch should be rare in practice).
+ *
+ * On failure (no provider returns a hit) we leave plan.music.url unset and
+ * the snap pass falls back to BPM math; the editor can still attach music
+ * downstream. Not surfacing this as an error — music is enhancement, not
+ * a blocker.
+ */
+export declare function selectMusicForPlan(plan: VideoPlan): Promise<VideoPlan>;
+//# sourceMappingURL=musicSelect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"musicSelect.d.ts","sourceRoot":"","sources":["../../../src/services/agent/musicSelect.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAyC3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAkD5E"}

package/lib/services/agent/musicSelect.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectMusicForPlan = selectMusicForPlan;
+const audioAnalysis_1 = require("../audioAnalysis");
+const musicGen_1 = require("../musicGen");
+const logger_1 = require("../../utils/logger");
+const beatSnap_1 = require("./beatSnap");
+const personas_1 = require("./personas");
+/**
+ * AG-27: HEAD-probe a track URL to confirm it's actually fetchable before we
+ * commit it to the plan. The curated catalog points at a GCS bucket
+ * (`vidspot-public-music`) that doesn't exist in every environment — picking
+ * a dead URL meant the final video had no music with no warning. We walk the
+ * results in priority order and return the first track whose URL is alive.
+ *
+ * 5s timeout per probe — slow enough to absorb cold CDN edges, fast enough
+ * that a 5-track search adds at most 25s to plan-time in the worst case.
+ */
+async function pickFirstReachable(tracks) {
+    for (const t of tracks) {
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 5000);
+            const r = await fetch(t.url, { method: "HEAD", signal: controller.signal });
+            clearTimeout(timeout);
+            if (r.ok)
+                return t;
+            logger_1.logger.warn("music url HEAD non-2xx, skipping", {
+                url: t.url,
+                status: r.status,
+                source: t.source,
+            });
+        }
+        catch (e) {
+            logger_1.logger.warn("music url HEAD failed, skipping", {
+                url: t.url,
+                source: t.source,
+                err: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
+    return undefined;
+}
+/**
+ * selectMusicForPlan — runs once after the planner returns and before the
+ * beat-snap pass, attaching a real track URL + bpm to plan.music.
+ *
+ * Why post-planner instead of letting the planner call search_music itself:
+ * the planner is a single structured-output call, not a tool-using agent.
+ * Adding a tool-call cycle here would double LLM latency and cost for a
+ * step that is fully mechanical — query string → provider → URL.
+ *
+ * No-ops when:
+ *   - plan.music.strategy === "none"
+ *   - plan.music.url is already set (user / brand kit pre-selected a track)
+ *   - all music providers are unconfigured (curated catalog should always
+ *     be available, so this branch should be rare in practice).
+ *
+ * On failure (no provider returns a hit) we leave plan.music.url unset and
+ * the snap pass falls back to BPM math; the editor can still attach music
+ * downstream. Not surfacing this as an error — music is enhancement, not
+ * a blocker.
+ */
+async function selectMusicForPlan(plan) {
+    if (!plan.music || plan.music.strategy === "none" || plan.music.url)
+        return plan;
+    const personaDefaultBpm = personas_1.PERSONA_PACKS[plan.persona]?.defaultBpm;
+    const bpmTarget = plan.music.bpm ?? personaDefaultBpm;
+    const totalSec = Math.ceil(plan.totalDurationMs / 1000);
+    const result = await (0, musicGen_1.searchAllMusicSources)({
+        query: plan.music.query,
+        mood: plan.music.moodTag,
+        bpmTarget,
+        durationSecMin: totalSec,
+        limit: 5,
+    });
+    // AG-27: walk the result list, returning the first URL that responds 2xx
+    // to a HEAD probe. Guards against curated tracks whose GCS bucket is dead
+    // in this environment.
+    const track = await pickFirstReachable(result.tracks);
+    if (!track) {
+        logger_1.logger.warn("selectMusicForPlan: no reachable track in result list", {
+            candidateCount: result.tracks.length,
+            query: plan.music.query,
+        });
+        return plan;
+    }
+    // Onset detection runs best-effort: timeout / disabled / WASM error all
+    // resolve to undefined and the snap pass falls back to BPM math. When it
+    // succeeds we get both a corrected BPM (essentia is more accurate than
+    // the provider's metadata) and a list of transient timestamps.
+    const onsetAnalysis = await (0, audioAnalysis_1.detectOnsets)(track.url);
+    return {
+        ...plan,
+        music: {
+            ...plan.music,
+            url: track.url,
+            bpm: onsetAnalysis?.bpm
+                ?? track.bpm
+                ?? plan.music.bpm
+                ?? (0, beatSnap_1.resolveBpm)(plan)
+                ?? personaDefaultBpm,
+            durationSec: track.durationSec,
+            source: track.source,
+            attribution: track.attribution,
+            onsets: onsetAnalysis?.onsets,
+        },
+    };
+}

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

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ */
+import type { TextOverlay } from "../../schemas/videoPlan.schema";
+import { type ResolvedTextStyle } from "./textOverlayStyles";
+export interface RenderContext {
+    /** Output video frame width in px (typically 1080 for 9:16). */
+    frameWidth: number;
+    /** Output video frame height in px (typically 1920 for 9:16). */
+    frameHeight: number;
+    /** Scene duration in seconds — used for animation timing. */
+    sceneDurationSec: number;
+    /** Absolute path to a TTF/OTC ffmpeg drawtext can load. */
+    fontFile: string;
+}
+export interface RenderedOverlay {
+    /** Ready-to-paste ffmpeg drawtext expression (no input/output labels). */
+    drawtextExpr: string;
+    /** Original overlay for trace/debug. */
+    source: TextOverlay;
+    /** Resolved style after merging role defaults + overrides. */
+    resolved: ResolvedTextStyle;
+    /** Final font size in px after auto-shrink. */
+    finalFontSizePx: number;
+    /** Final wrapped text (multi-line with literal "\n"). */
+    finalText: string;
+    /** Number of lines after wrap. */
+    lineCount: number;
+}
+/**
+ * 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).
+ */
+export declare function renderOverlay(overlay: TextOverlay, ctx: RenderContext): RenderedOverlay;
+/**
+ * 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.
+ */
+export declare function renderOverlayChain(overlays: TextOverlay[], ctx: RenderContext): {
+    vfilter: string;
+    rendered: RenderedOverlay[];
+};
+/**
+ * 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.
+ */
+export declare function expandPersistentOverlays(perScene: Array<TextOverlay[] | undefined>): TextOverlay[][];
+//# sourceMappingURL=overlayRenderer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overlayRenderer.d.ts","sourceRoot":"","sources":["../../../src/services/agent/overlayRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAuB,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAElF,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,gBAAgB,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,MAAM,EAAE,WAAW,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,+CAA+C;IAC/C,eAAe,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;CACnB;AAsHD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,aAAa,GACjB,eAAe,CA6EjB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,WAAW,EAAE,EACvB,GAAG,EAAE,aAAa,GACjB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,eAAe,EAAE,CAAA;CAAE,CAMlD;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,KAAK,CAAC,WAAW,EAAE,GAAG,SAAS,CAAC,GACzC,WAAW,EAAE,EAAE,CAyBjB"}