vidspotai-shared 1.0.68 → 1.0.69-dev.0

package/lib/schemas/videoPlan.schema.js

@@ -0,0 +1,412 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VideoPlanSchema = exports.PlannerWarningSchema = exports.PlannedSceneSchema = exports.SceneLayoutSchema = exports.TextOverlaySchema = exports.TextBgStyleSchema = exports.TextAnimationSchema = exports.TextPositionSchema = exports.TextRoleSchema = exports.TransitionKindSchema = exports.SceneAssetStrategySchema = exports.AgentVisualBibleSchema = exports.BibleEntitySchema = void 0;
+const zod_1 = require("zod");
+const agentPersona_schema_1 = require("./agentPersona.schema");
+const project_schema_1 = require("./project.schema");
+/**
+ * VideoPlan — the planner LLM's structured output. Reviewed by the user as a
+ * storyboard BEFORE any generation spend. Once approved, the executor walks
+ * the scenes in order and runs the prescribed tools per scene.
+ *
+ * Validated against this Zod schema; if validation fails, the planner is
+ * retried up to N=2 with the validation errors fed back as correction context.
+ */
+/**
+ * AG-12 — Agent-side Visual Bible. The legacy non-agent flow has its own
+ * VisualBibleSchema in globals/types.ts; this is the agent-flavored variant
+ * that the planner threads through every scene prompt. Built by an LLM
+ * pre-pass (BibleBuilder) before plan(), persisted on the plan, and used to
+ * keep characters / objects / environment visually consistent across scenes.
+ *
+ * Entity IDs (CHAR_1, OBJ_1) are stable strings that scenes reference; the
+ * planner injects the full description verbatim whenever a scene's prompt
+ * mentions an id. AG-13 fills in optional `referenceImageUrl` for premium
+ * tier where we image-anchor identity (image-to-image / subject reference).
+ */
+exports.BibleEntitySchema = zod_1.z.object({
+    id: zod_1.z.string().regex(/^(CHAR|OBJ|ENV)_\d+$/, "id must be CHAR_<n>, OBJ_<n>, or ENV_<n>"),
+    name: zod_1.z.string().describe("Short label, e.g. 'Maya', 'amber dropper bottle'."),
+    description: zod_1.z
+        .string()
+        .describe("Verbatim visual description re-stated in every scene prompt referencing this entity. For characters: age, ethnicity, hair, build, wardrobe. For objects: shape, material, color, distinctive features. For environment: lighting, palette, era."),
+    /**
+     * AG-13 — pre-rendered reference image for this entity. Populated by the
+     * C2 pre-pass when consistencyTier >= "C2". Threaded as inputImageUrl /
+     * inputImageUrls on every scene's image-gen call where this id appears.
+     */
+    referenceImageUrl: zod_1.z.string().url().optional(),
+});
+exports.AgentVisualBibleSchema = zod_1.z.object({
+    /** Recurring people / mascots / spokes-characters. */
+    characters: zod_1.z.array(exports.BibleEntitySchema).default([]),
+    /** Recurring physical objects (product, key prop). */
+    objects: zod_1.z.array(exports.BibleEntitySchema).default([]),
+    /** Recurring environment (palette, lighting, location). Usually 0 or 1 entry. */
+    environments: zod_1.z.array(exports.BibleEntitySchema).default([]),
+    /** Tier signal: "C0" none, "C1" description-only, "C2" reference-image anchored. */
+    consistencyTier: zod_1.z.enum(["C0", "C1", "C2"]).default("C1"),
+});
+exports.SceneAssetStrategySchema = zod_1.z.enum([
+    "stock-video",
+    "stock-image-ken-burns",
+    "ai-image-static",
+    "ai-image-motion",
+    "ai-image-to-video",
+    "ai-text-to-video",
+    "user-asset",
+    "talking-head-avatar",
+]);
+exports.TransitionKindSchema = zod_1.z.enum([
+    "none",
+    "cut",
+    "fade",
+    "crossfade",
+    "wipe",
+    "whipPan",
+    "dipToBlack",
+    "dipToWhite",
+]);
+/**
+ * AG-40 — text overlay role. Each role has a default style (font, size, position,
+ * color, animation) defined in `agent/textOverlayStyles.ts`. The planner picks
+ * the role per overlay; the stitcher resolves the role → ffmpeg drawtext args.
+ *
+ * - headline:    big bold attention-grab line (top or center)
+ * - subheadline: secondary supporting line under a headline
+ * - body:        multi-line explainer / feature copy (lower-third)
+ * - cta:         call-to-action button-style text (bottom)
+ * - watermark:   persistent brand mark across all scenes (corner)
+ * - disclaimer:  fine-print legal / "results may vary" (bottom, small)
+ * - label:       in-frame label for an object or person (anchored to frame area)
+ */
+exports.TextRoleSchema = zod_1.z.enum([
+    "headline",
+    "subheadline",
+    "body",
+    "cta",
+    "watermark",
+    "disclaimer",
+    "label",
+]);
+exports.TextPositionSchema = zod_1.z.enum([
+    "top",
+    "top-left",
+    "top-right",
+    "top-banner", // top 15%, full-width strip
+    "center",
+    "left-rail", // left 33%, vertically centered (product shots)
+    "lower-third",
+    "bottom",
+    "bottom-left",
+    "bottom-right",
+    "caption-strip", // bottom-pinned word-by-word captions (TikTok feel)
+]);
+exports.TextAnimationSchema = zod_1.z.enum([
+    "none",
+    "fade",
+    "pop",
+    "type",
+    "slide-up",
+    "word-pop", // each word pops in sequentially
+    "highlight-current", // active word highlighted, others dim (VO-aligned)
+]);
+/**
+ * Background treatment for text legibility against any underlying frame.
+ * Distinct from `bgColor` (the actual color hex) — `bgStyle` is the shape /
+ * decoration the renderer draws. `pill` and `bar` both honor `bgColor`;
+ * `shadow` and `outline` ignore it.
+ */
+exports.TextBgStyleSchema = zod_1.z.enum([
+    "none",
+    "shadow", // drop shadow behind glyphs (no fill)
+    "pill", // rounded-rect fill hugging the text bbox
+    "bar", // full-width edge-to-edge horizontal bar
+    "outline", // glyph stroke (no fill)
+]);
+/**
+ * AG-40: Per-overlay spec. Multiple overlays can live on one scene (e.g. a
+ * persistent watermark + a headline + a CTA pill on the closing scene). The
+ * role drives sensible defaults from textOverlayStyles.ts; explicit overrides
+ * below win when present. Use `persistFromScene` to carry an overlay across
+ * subsequent scenes (e.g. watermark set on scene 0 with persistFromScene=0 is
+ * burned onto every scene until another overlay with the same role replaces it).
+ */
+exports.TextOverlaySchema = zod_1.z.object({
+    text: zod_1.z.string().min(1).max(140),
+    role: exports.TextRoleSchema,
+    position: exports.TextPositionSchema.optional(),
+    /** "primary" gets stronger styling (larger, stroked, animated); "secondary" subdued. */
+    emphasis: zod_1.z.enum(["primary", "secondary"]).optional(),
+    /** Per-overlay style overrides — usually unnecessary because role defaults are good. */
+    font: zod_1.z.string().optional(),
+    fontSize: zod_1.z.union([zod_1.z.literal("auto"), zod_1.z.number().int().positive()]).optional(),
+    /**
+     * Alternative to `fontSize` expressed as % of frame height (2–20). Resolution-
+     * independent, so the same plan renders proportionally on 9:16 phone vs
+     * 16:9 desktop. When both are set, `fontSize` (px) wins.
+     */
+    sizePct: zod_1.z.number().min(2).max(20).optional(),
+    weight: zod_1.z.enum(["regular", "medium", "bold", "black"]).optional(),
+    color: zod_1.z.string().optional(),
+    bgColor: zod_1.z.string().optional(),
+    /**
+     * Background decoration drawn behind the text for legibility. Distinct from
+     * `bgColor` (which is the fill hex used by `pill` / `bar`). Default driven by
+     * role + auto-contrast pass when omitted.
+     */
+    bgStyle: exports.TextBgStyleSchema.optional(),
+    animation: exports.TextAnimationSchema.optional(),
+    /** Start/end times in ms within the scene; default = whole scene. */
+    startMs: zod_1.z.number().nonnegative().optional(),
+    endMs: zod_1.z.number().nonnegative().optional(),
+    /** If set, this overlay carries forward to subsequent scenes until replaced. */
+    persistAcrossScenes: zod_1.z.boolean().optional(),
+});
+/**
+ * Per-scene composition decision. Drives how the scene's visual asset fills
+ * (or doesn't fill) the target aspect ratio. Critical when source aspect ≠
+ * target aspect — without this the renderer just stretches, which destroys
+ * intent on horizontal stock on a 9:16 target (or vice-versa).
+ *
+ * `composition` is required when SceneLayout is present; the others are
+ * progressive enhancements. Planner picks via the layout decision table
+ * (source aspect × target aspect × content type from the vision pass).
+ */
+exports.SceneLayoutSchema = zod_1.z.object({
+    composition: zod_1.z.enum([
+        "full-bleed", // asset fills frame, crop excess (uses focalPoint)
+        "letterbox", // asset native ratio centered, bars top/bottom
+        "blur-fill", // asset native ratio centered, blurred copy fills bars
+        "split-top", // asset top 60%, solid/gradient bottom 40% (text area)
+        "split-bottom", // asset bottom 60%, solid/gradient top 40%
+        "pip-bottom-right", // asset 35% size, bottom-right corner; bg fill
+    ]),
+    /**
+     * Asset's focal point — anchor when cropping (full-bleed) or composing
+     * (split / pip). Normalized 0–1 coords; (0.5, 0.5) = dead center. Driven
+     * by the vision pass on the scene's first frame; planner emits if known.
+     */
+    focalPoint: zod_1.z
+        .object({
+        x: zod_1.z.number().min(0).max(1),
+        y: zod_1.z.number().min(0).max(1),
+    })
+        .optional(),
+    /**
+     * Background fill for compositions that reveal dead space (letterbox /
+     * split / pip). Renderer interprets brand-* via persona/brandKit colors.
+     * `blur-extend` reuses the asset's own pixels blurred — usually safest.
+     */
+    backgroundFill: zod_1.z
+        .enum([
+        "black",
+        "white",
+        "brand-primary",
+        "brand-secondary",
+        "blur-extend",
+        "gradient",
+    ])
+        .optional(),
+});
+exports.PlannedSceneSchema = zod_1.z.object({
+    sceneIndex: zod_1.z.number().int().nonnegative(),
+    /** Plain-English description of what this scene shows. */
+    intent: zod_1.z.string(),
+    /** Asset acquisition strategy for this scene. */
+    strategy: exports.SceneAssetStrategySchema,
+    /** Tier the planner picked for this scene; usually <= brief.tierBudget. */
+    tier: project_schema_1.TierSchema,
+    /** Provider key the planner suggests; executor may swap on rate-limit. */
+    preferredProvider: zod_1.z.string().optional(),
+    /** Suggested model key, if applicable. */
+    preferredModel: zod_1.z.string().optional(),
+    /** Visual prompt (for AI generation strategies) or stock query terms. */
+    prompt: zod_1.z.string(),
+    // AG-25: was `.positive()` (exclusiveMinimum: 0). LLM kept emitting `0` on
+    // medium-pacing briefs across 3 retries — strict-JSON `>0` is a weak signal.
+    // 500ms is a practical sub-floor (real provider floor is 2000ms, enforced by
+    // the per-scene capability validator); this just keeps the model honest.
+    durationMs: zod_1.z.number().min(500),
+    voiceoverLine: zod_1.z.string().optional(),
+    /**
+     * AG-44: per-scene voice delivery override. Tone can shift across the arc
+     * (frustrated → curious → excited), so a single global voiceStyle is too
+     * coarse. When present, executor passes this instead of plan.voiceStyle for
+     * just this scene's TTS call. Examples: "frustrated", "calm", "excited",
+     * "whispered", "authoritative". Adjective only; the executor maps to
+     * ElevenLabs voice_settings.
+     */
+    voiceStyle: zod_1.z.string().optional(),
+    /**
+     * AG-40 legacy: a single bottom-center caption string. Kept for back-compat
+     * with traces / replay scripts. Prefer `overlays[]` for new plans — it lets
+     * you mix headline + watermark + CTA on the same scene with role-driven
+     * styling, animations, word-wrap, and persist-across-scenes.
+     */
+    onScreenText: zod_1.z.string().optional(),
+    /**
+     * AG-40: Structured text overlays. When present, the stitcher uses these
+     * instead of `onScreenText`. Each entry carries a role (headline/cta/etc.)
+     * that the renderer maps to font/size/position/animation defaults. Up to
+     * 4 overlays per scene — beyond that gets visually noisy.
+     */
+    overlays: zod_1.z.array(exports.TextOverlaySchema).max(4).optional(),
+    transitionIn: exports.TransitionKindSchema.default("cut"),
+    /** Up-front estimated credit cost for this scene. */
+    estimatedCredits: zod_1.z.number().nonnegative(),
+    /**
+     * Required only when strategy = "talking-head-avatar". URL of the presenter
+     * face still the avatar pipeline animates. Planner sources from
+     * brandKit.presenterFaceUrl; if absent, planner must NOT pick this strategy.
+     */
+    avatarFaceUrl: zod_1.z.string().url().optional(),
+    /**
+     * AG-11 — character anchoring across scenes. When the same person/mascot
+     * appears in multiple scenes, set this on the LATER scene to the sceneIndex
+     * of the first scene where that character appeared. The planner must also
+     * re-state the character's core identity descriptors verbatim in this
+     * scene's prompt (age, ethnicity, hair, build, wardrobe) so even text-only
+     * generation keeps the look. The executor will additionally pass the
+     * anchor scene's generated image as `inputImageUrl` once generate_image is
+     * re-enabled (image-to-image identity transfer).
+     */
+    characterAnchorSceneIndex: zod_1.z.number().int().nonnegative().optional(),
+    /**
+     * AG-12/13 — Bible entity ids this scene references (CHAR_1, OBJ_1, ENV_1).
+     * Used at two places: (a) planner injects each id's verbatim description
+     * into scene.prompt when the entity appears; (b) AG-13 executor pre-pass
+     * threads `referenceImageUrl` of each id as inputImageUrls on the scene's
+     * image-gen call to lock identity.
+     */
+    bibleEntityIds: zod_1.z.array(zod_1.z.string()).default([]),
+    /**
+     * User-set escape hatch for the trailing-silence warning. When true, the
+     * trailing-silence validator skips this scene — useful for visual-led
+     * moments (real-estate showcase, product close-up, cinematic beat) where
+     * the VO ends and the audience is meant to take in the visual.
+     */
+    allowTrailingSilence: zod_1.z.boolean().optional(),
+    /**
+     * Per-scene composition decision (text-layout v1). Optional for back-compat:
+     * when absent the renderer falls back to "stretch / cover" behavior. When
+     * present, the renderer honors composition / focalPoint / backgroundFill
+     * to fit the scene asset onto the target aspect intentionally rather than
+     * mechanically. Planner picks based on source aspect × target aspect × the
+     * vision pass's content classification (center / edges / face / broll).
+     */
+    layout: exports.SceneLayoutSchema.optional(),
+});
+/**
+ * Soft validator output. Unlike planner-rejection strings, warnings travel
+ * WITH an approved plan so the UI can flag risky scenes the user has chosen
+ * to ship. Two emitters today:
+ *  - `vo-clip`: even after the executor's 1.15× speedup the VO will overrun.
+ *  - `trailing-silence`: VO ends >threshold before the scene ends, no
+ *     allowTrailingSilence override set.
+ */
+exports.PlannerWarningSchema = zod_1.z.object({
+    sceneIndex: zod_1.z.number().int().nonnegative(),
+    kind: zod_1.z.enum(["vo-clip", "trailing-silence"]),
+    message: zod_1.z.string(),
+    /** Stage-1 sceneIndex-keyed signals; UI groups by scene. */
+    meta: zod_1.z
+        .object({
+        voEstimateMs: zod_1.z.number().nonnegative().optional(),
+        sceneDurationMs: zod_1.z.number().nonnegative().optional(),
+        silenceMs: zod_1.z.number().nonnegative().optional(),
+        overrunMs: zod_1.z.number().nonnegative().optional(),
+    })
+        .optional(),
+});
+exports.VideoPlanSchema = zod_1.z.object({
+    briefId: zod_1.z.string().optional(),
+    /** Persona the router selected (UGC ad / faceless YT / etc.). */
+    persona: agentPersona_schema_1.AgentPersonaSchema,
+    aspect: project_schema_1.AspectSchema,
+    totalDurationMs: zod_1.z.number().positive(),
+    totalEstimatedCredits: zod_1.z.number().nonnegative(),
+    /** Scene list, in render order. */
+    scenes: zod_1.z.array(exports.PlannedSceneSchema).min(1),
+    /** Music recommendation for the whole video. */
+    music: zod_1.z
+        .object({
+        strategy: zod_1.z.enum(["stock-track", "generated", "none"]),
+        query: zod_1.z.string().optional(),
+        moodTag: zod_1.z.string().optional(),
+        /**
+         * Beats-per-minute of the chosen / target track. Drives the beat-snap
+         * pass so scene cuts land on bar boundaries. Optional: when absent the
+         * snap pass falls back to a persona default (or no-ops for cinematic
+         * personas where free-form pacing reads better).
+         */
+        bpm: zod_1.z.number().int().positive().optional(),
+        /**
+         * URL of the chosen music track. Set by the post-planner music selection
+         * step (selectMusicForPlan) when strategy = "stock-track" / "generated"
+         * and a provider returns a hit.
+         */
+        url: zod_1.z.string().url().optional(),
+        /** Track length in seconds, when known. */
+        durationSec: zod_1.z.number().positive().optional(),
+        /** Source label for attribution / debugging ("curated", "jamendo", "mubert"). */
+        source: zod_1.z.string().optional(),
+        /** Best-effort attribution text; surface in UI when present. */
+        attribution: zod_1.z.string().optional(),
+        /**
+         * Onset timestamps (seconds) from essentia.js RhythmExtractor2013.
+         * When present, the snap pass aligns scene cuts to the nearest onset
+         * instead of the uniform BPM grid — cuts land on actual transients
+         * (kicks / snares / vocal entries) rather than mathematical bars.
+         */
+        onsets: zod_1.z.array(zod_1.z.number().nonnegative()).optional(),
+    })
+        .optional(),
+    /**
+     * Voice id to use across all VO scenes. ORCHESTRATOR-ONLY: the LLM must NOT
+     * fill this — leave undefined. The orchestrator injects the real ElevenLabs
+     * voice ID from brief.voice.voiceId post-parse. Descriptive labels like
+     * "female-young-adult-excited" are not valid ElevenLabs IDs and get stripped
+     * by the executor (AG-37). Use voiceStyle below to convey delivery instead.
+     */
+    voiceId: zod_1.z.string().optional(),
+    /**
+     * AG-31: voice delivery style — adjective forwarded from brief.voice.style.
+     * Executor maps it to ElevenLabs voice_settings (style/stability/speed).
+     * Kept as a string so the schema doesn't drag the VoiceStyleSchema enum
+     * into every consumer — executor validates at use-time.
+     */
+    voiceStyle: zod_1.z.string().optional(),
+    /** Free-form planner notes — e.g. why a particular tier mix was chosen. */
+    notes: zod_1.z.string().optional(),
+    /**
+     * AG-12 — Visual Bible built by the BibleBuilder pre-pass and threaded
+     * into every scene that references entity ids. Optional because legacy
+     * plans (built before AG-12) and dry-runs without a bible step are still
+     * valid. When present, executor consults it for reference-image threading
+     * (AG-13).
+     */
+    bible: exports.AgentVisualBibleSchema.optional(),
+    /**
+     * Soft validation warnings attached at planner finalize-time and refreshed
+     * by sceneEdit patches. Plan is still shippable; UI surfaces these so the
+     * user can fix or acknowledge.
+     */
+    warnings: zod_1.z.array(exports.PlannerWarningSchema).default([]),
+    /**
+     * Billing/provenance metadata stamped by the planner + plan controller so
+     * /execute can compute the right overhead charge. Optional for back-compat
+     * with plans built before the overhead-billing change — `estimatePlanOverheadCredits`
+     * treats all flags as false when absent.
+     */
+    meta: zod_1.z
+        .object({
+        /** True when the Anthropic web_search path actually ran (not just the heuristic). */
+        usedWebResearch: zod_1.z.boolean().optional(),
+        /** True when extended-thinking budget was attached (T3 premium briefs). */
+        usedThinking: zod_1.z.boolean().optional(),
+        /** True only when a fresh bible was built; cache hits stay false. */
+        bibleBuilt: zod_1.z.boolean().optional(),
+    })
+        .optional(),
+});

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

@@ -0,0 +1,10 @@
+import { VideoPlan } from "../../schemas/videoPlan.schema";
+export interface SnapOptions {
+    /** Used only when neither plan.music.bpm nor the persona default exists. */
+    fallbackBpm?: number;
+    /** Override beats-per-bar (default 4 — cut on whole bars, not individual beats). */
+    beatsPerBar?: number;
+}
+export declare function resolveBpm(plan: VideoPlan, opts?: SnapOptions): number | undefined;
+export declare function snapPlanToBeats(plan: VideoPlan, opts?: SnapOptions): VideoPlan;
+//# sourceMappingURL=beatSnap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"beatSnap.d.ts","sourceRoot":"","sources":["../../../src/services/agent/beatSnap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,SAAS,EAAE,MAAM,gCAAgC,CAAC;AA+BzE,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,GAAE,WAAgB,GAAG,MAAM,GAAG,SAAS,CAKtF;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,GAAE,WAAgB,GAAG,SAAS,CAMlF"}

package/lib/services/agent/beatSnap.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBpm = resolveBpm;
+exports.snapPlanToBeats = snapPlanToBeats;
+const personas_1 = require("./personas");
+/**
+ * Beat-snap pass — adjusts each scene's durationMs so cuts land on bar
+ * boundaries of the chosen music. Cuts that land on bars feel produced;
+ * arbitrary durations feel like a slideshow with music laid over the top.
+ *
+ * Two modes, picked automatically:
+ *
+ *   1. ONSET MODE (preferred). When plan.music.onsets is populated by
+ *      detectOnsets() (essentia.js), each scene's cumulative end time snaps
+ *      to the nearest detected onset — cuts land on actual transients
+ *      (kicks / snares / vocal entries), not a uniform grid. This is what
+ *      a human editor does.
+ *
+ *   2. BPM MODE (fallback). When no onsets are available we fall back to
+ *      uniform bar math at the resolved BPM:
+ *        - plan.music.bpm  → PERSONA_PACKS[plan.persona].defaultBpm
+ *          → opts.fallbackBpm → no-op
+ *      Each scene rounds to the nearest barMs (4 beats by default).
+ *
+ * Both modes:
+ *   - never go below 1 bar of duration
+ *   - never go shorter than the voiceover line needs (~3 wps), rounded up
+ *   - recompute plan.totalDurationMs from the snapped sum
+ */
+const BEATS_PER_BAR = 4;
+const ESTIMATED_WORDS_PER_SECOND = 3;
+function resolveBpm(plan, opts = {}) {
+    if (plan.music?.bpm)
+        return plan.music.bpm;
+    const personaDefault = personas_1.PERSONA_PACKS[plan.persona]?.defaultBpm;
+    if (personaDefault)
+        return personaDefault;
+    return opts.fallbackBpm;
+}
+function snapPlanToBeats(plan, opts = {}) {
+    const onsets = plan.music?.onsets;
+    if (onsets && onsets.length >= plan.scenes.length) {
+        return snapToOnsets(plan, onsets);
+    }
+    return snapToBpmGrid(plan, opts);
+}
+function snapToOnsets(plan, onsets) {
+    // Build cumulative target end-times then snap each to the nearest onset.
+    // Scenes flow sequentially, so the second scene's start = first scene's end.
+    const sortedOnsets = [...onsets].sort((a, b) => a - b);
+    const snappedScenes = [];
+    let cumulativeMs = 0;
+    for (const scene of plan.scenes) {
+        const minDurMs = sceneMinMs(scene);
+        const targetEndMs = cumulativeMs + Math.max(scene.durationMs, minDurMs);
+        const snappedEndMs = Math.max(cumulativeMs + minDurMs, nearestOnsetMs(targetEndMs, sortedOnsets, cumulativeMs + minDurMs));
+        const newDurationMs = snappedEndMs - cumulativeMs;
+        snappedScenes.push(newDurationMs === scene.durationMs ? scene : { ...scene, durationMs: newDurationMs });
+        cumulativeMs = snappedEndMs;
+    }
+    return {
+        ...plan,
+        scenes: snappedScenes,
+        totalDurationMs: cumulativeMs,
+    };
+}
+function snapToBpmGrid(plan, opts) {
+    const bpm = resolveBpm(plan, opts);
+    if (!bpm)
+        return plan;
+    const beatsPerBar = opts.beatsPerBar ?? BEATS_PER_BAR;
+    const barMs = (60000 / bpm) * beatsPerBar;
+    const snappedScenes = plan.scenes.map((scene) => snapScene(scene, barMs));
+    const totalDurationMs = snappedScenes.reduce((sum, s) => sum + s.durationMs, 0);
+    return {
+        ...plan,
+        music: {
+            strategy: plan.music?.strategy ?? "stock-track",
+            ...plan.music,
+            bpm,
+        },
+        scenes: snappedScenes,
+        totalDurationMs,
+    };
+}
+function snapScene(scene, barMs) {
+    const minMs = Math.max(barMs, ceilToBar(sceneMinMs(scene), barMs));
+    const snapped = Math.max(minMs, roundToBar(scene.durationMs, barMs));
+    return snapped === scene.durationMs ? scene : { ...scene, durationMs: snapped };
+}
+function sceneMinMs(scene) {
+    return scene.voiceoverLine ? estimateVoMs(scene.voiceoverLine) : 0;
+}
+function nearestOnsetMs(targetMs, onsetsSec, minMs) {
+    // Binary search would be faster but onsets list is short (1 per beat for a
+    // 3-min track at 120bpm = ~360 entries) and snap runs once per plan.
+    let bestMs = targetMs;
+    let bestDiff = Infinity;
+    for (const sec of onsetsSec) {
+        const ms = sec * 1000;
+        if (ms < minMs)
+            continue;
+        const diff = Math.abs(ms - targetMs);
+        if (diff < bestDiff) {
+            bestDiff = diff;
+            bestMs = ms;
+        }
+        else if (ms > targetMs && diff > bestDiff) {
+            // Past the target — onsets are sorted, so no closer match ahead.
+            break;
+        }
+    }
+    return bestMs;
+}
+function roundToBar(ms, barMs) {
+    return Math.max(barMs, Math.round(ms / barMs) * barMs);
+}
+function ceilToBar(ms, barMs) {
+    if (ms <= 0)
+        return 0;
+    return Math.ceil(ms / barMs) * barMs;
+}
+function estimateVoMs(line) {
+    const words = line.trim().split(/\s+/).filter(Boolean).length;
+    if (words === 0)
+        return 0;
+    return Math.ceil((words / ESTIMATED_WORDS_PER_SECOND) * 1000);
+}

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

@@ -0,0 +1,43 @@
+/**
+ * BibleBuilder — AG-12 pre-pass that builds an AgentVisualBible from a brief
+ * BEFORE the planner runs. The bible captures recurring characters / objects /
+ * environment with verbatim descriptions; the planner injects each entity's
+ * description whenever a scene references it, and AG-13 image-anchors them.
+ *
+ * Runs as a single LLM structured-output call (~$0.01). Skippable: if the
+ * brief is too short or describes a one-off scene (no recurring entities),
+ * the bible comes back with empty arrays and the agent degrades to AG-11's
+ * per-scene-prompt re-state. Either way the planner gets a defined shape.
+ *
+ * Tier behavior:
+ *   - C0: builder is skipped entirely by the caller (fastest, no consistency).
+ *   - C1 (default for paid): bible is built with descriptions only.
+ *   - C2 (premium): builder runs same as C1; the C2 pre-pass (renderReferenceImages
+ *     in a separate module) then fills referenceImageUrl on each entity.
+ */
+import { z } from "zod";
+import { AgentPersona } from "../../schemas/agentPersona.schema";
+import { VideoBrief } from "../../schemas/brief.schema";
+import { AgentVisualBible } from "../../schemas/videoPlan.schema";
+import { IBrandKitModel } from "../../models/agent.model";
+import { LlmCaller } from "./llmCaller";
+import { ModelRouter } from "./modelRouter";
+export interface BibleBuilderOptions {
+    llm: LlmCaller;
+    router?: ModelRouter;
+}
+export interface BuildBibleArgs {
+    brief: VideoBrief;
+    persona?: AgentPersona;
+    brandKit?: IBrandKitModel | null;
+    /** "C1" (description-only) or "C2" (description + ref-image placeholder slots). */
+    consistencyTier?: "C1" | "C2";
+}
+export declare class BibleBuilder {
+    private readonly opts;
+    private readonly router;
+    constructor(opts: BibleBuilderOptions);
+    build({ brief, persona, brandKit, consistencyTier, }: BuildBibleArgs): Promise<AgentVisualBible>;
+}
+export type { z };
+//# sourceMappingURL=bibleBuilder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bibleBuilder.d.ts","sourceRoot":"","sources":["../../../src/services/agent/bibleBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EACL,gBAAgB,EAEjB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,QAAQ,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACjC,mFAAmF;IACnF,eAAe,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CAC/B;AAED,qBAAa,YAAY;IAGX,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAER,IAAI,EAAE,mBAAmB;IAIhD,KAAK,CAAC,EACV,KAAK,EACL,OAAO,EACP,QAAQ,EACR,eAAsB,GACvB,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;CA+F9C;AAGD,YAAY,EAAE,CAAC,EAAE,CAAC"}