vidspotai-shared 1.0.82-dev.0 → 1.0.83

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

@@ -1,4 +1,5 @@
-import type { Project } from "../../schemas/project.schema";
+import type { Clip, Project } from "../../schemas/project.schema";
+import type { RegenComponent } from "../credits/pricing";
 /**
  * planMutations — Stage 7-prep helper for the agent permission flow.
  *
@@ -43,4 +44,56 @@ export declare function findClipsNeedingPermission(currentProject: Project | nul
  * straight through.
  */
 export declare function requiresUserConfirmation(currentProject: Project | null | undefined): boolean;
+/**
+ * Stage 7 (lock enforcement) — the clips from `currentProject` that a
+ * regeneration must NOT overwrite: every protected clip (locked or
+ * user-placed) whose id the user did NOT explicitly approve to mutate.
+ *
+ * `allowedMutations` is the set of clip ids the user OK'd in the
+ * confirmation modal (echoed back through /execute-confirmed → the run
+ * doc → the job payload). A protected clip absent from that set is frozen:
+ * planToProject reuses it verbatim instead of rebuilding it from
+ * plan+outcome, because the user's edits (trim, volume, text, position)
+ * live only on the clip object — they're nowhere in the plan, so a rebuild
+ * would silently discard them.
+ *
+ * Returns `[]` when there's no prior project (first run on an empty canvas)
+ * or nothing is protected — the common path, a clean no-op.
+ */
+export declare function computePreservedClips(currentProject: Project | null | undefined, allowedMutations?: readonly string[]): Clip[];
+/** Per-scene sets of asset kinds whose generation can be skipped on regen. */
+export interface FrozenScenes {
+    /** Scene indices whose visual clip(s) are preserved — skip provider gen. */
+    visual: Set<number>;
+    /** Scene indices whose voiceover clip is preserved — skip TTS. */
+    voiceover: Set<number>;
+}
+/**
+ * Gap #1 follow-up (skip-generation) — derive, from the preserved clips, which
+ * scenes don't need their assets regenerated at all. A preserved visual means
+ * the user froze that scene's footage, so re-running the (expensive) provider
+ * gen just to discard the result is pure waste; same for a preserved VO and
+ * the TTS call. The executor consults these sets to short-circuit the tool
+ * dispatch, and planToProject uses `visual` to skip building a placeholder twin
+ * (the real preserved clip is injected verbatim instead).
+ *
+ * Keyed off the deterministic clip-id contract so it stays in lockstep with the
+ * ids planToProject emits (and the ids the preserve-override matches on).
+ */
+/**
+ * Gap #5 (diff-based bulk regen, lock-safety) — true if a regen target would
+ * overwrite a frozen (locked / user-edited) scene asset, so callers can drop it
+ * before charging or executing. The bulk diff (`diffPlans`) is plan-field based
+ * and lock-blind: a re-plan that rewrote a locked scene's prompt would emit a
+ * `visual` target for it, and running that would clobber the footage the user
+ * deliberately froze in the editor. Visual targets are gated by `frozen.visual`;
+ * voiceover AND captions by `frozen.voiceover` (captions are derived from the VO
+ * audio, so a locked VO keeps its captions too). Overlays/music aren't tracked
+ * by the frozen-scene model (they're separate clips), so they pass through.
+ */
+export declare function isRegenTargetFrozen(target: {
+    component: RegenComponent;
+    sceneIndex?: number;
+}, frozen: FrozenScenes): boolean;
+export declare function computeFrozenScenes(preserveClips: readonly Clip[]): FrozenScenes;
 //# sourceMappingURL=planMutations.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"planMutations.d.ts","sourceRoot":"","sources":["../../../src/services/agent/planMutations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAGlE;;;;;;;;;;;;;;;;GAgBG;AAEH,uFAAuF;AACvF,eAAO,MAAM,8BAA8B,EAAE,WAAW,CAAC,MAAM,CAG7D,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,aAAa,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,QAAQ,EAAE,QAAQ,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IAC5E,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,MAAM,EAAE,cAAc,CAAC;IACvB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAyDD;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GACzC,gBAAgB,EAAE,CAgBpB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GACzC,OAAO,CAET"}
+{"version":3,"file":"planMutations.d.ts","sourceRoot":"","sources":["../../../src/services/agent/planMutations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGzD;;;;;;;;;;;;;;;;GAgBG;AAEH,uFAAuF;AACvF,eAAO,MAAM,8BAA8B,EAAE,WAAW,CAAC,MAAM,CAG7D,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,aAAa,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,QAAQ,EAAE,QAAQ,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IAC5E,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,MAAM,EAAE,cAAc,CAAC;IACvB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAyDD;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GACzC,gBAAgB,EAAE,CAgBpB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GACzC,OAAO,CAET;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,EAC1C,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GACnC,IAAI,EAAE,CAMR;AAQD,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACpB,kEAAkE;IAClE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE;IAAE,SAAS,EAAE,cAAc,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,EAC1D,MAAM,EAAE,YAAY,GACnB,OAAO,CAOT;AAED,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,SAAS,IAAI,EAAE,GAAG,YAAY,CAahF"}

package/lib/services/agent/planMutations.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.USER_PLACED_PROVENANCE_SOURCES = void 0;
 exports.findClipsNeedingPermission = findClipsNeedingPermission;
 exports.requiresUserConfirmation = requiresUserConfirmation;
+exports.computePreservedClips = computePreservedClips;
+exports.isRegenTargetFrozen = isRegenTargetFrozen;
+exports.computeFrozenScenes = computeFrozenScenes;
 const planToProject_1 = require("../editor/planToProject");
 /**
  * planMutations — Stage 7-prep helper for the agent permission flow.
@@ -118,3 +121,78 @@ function findClipsNeedingPermission(currentProject) {
 function requiresUserConfirmation(currentProject) {
     return findClipsNeedingPermission(currentProject).length > 0;
 }
+/**
+ * Stage 7 (lock enforcement) — the clips from `currentProject` that a
+ * regeneration must NOT overwrite: every protected clip (locked or
+ * user-placed) whose id the user did NOT explicitly approve to mutate.
+ *
+ * `allowedMutations` is the set of clip ids the user OK'd in the
+ * confirmation modal (echoed back through /execute-confirmed → the run
+ * doc → the job payload). A protected clip absent from that set is frozen:
+ * planToProject reuses it verbatim instead of rebuilding it from
+ * plan+outcome, because the user's edits (trim, volume, text, position)
+ * live only on the clip object — they're nowhere in the plan, so a rebuild
+ * would silently discard them.
+ *
+ * Returns `[]` when there's no prior project (first run on an empty canvas)
+ * or nothing is protected — the common path, a clean no-op.
+ */
+function computePreservedClips(currentProject, allowedMutations) {
+    if (!currentProject)
+        return [];
+    const approved = new Set(allowedMutations ?? []);
+    return currentProject.clips.filter((clip) => isProtected(clip) !== null && !approved.has(clip.id));
+}
+// Deterministic clip-id shapes emitted by planToProject. A frozen visual can
+// be a single clip (`scene-3-visual`) or an extend-chain (`scene-3-visual-0`,
+// `-1`, …); both map back to the same scene. VO is always a single clip.
+const VISUAL_CLIP_ID_RE = /^scene-(\d+)-visual(?:-\d+)?$/;
+const VOICEOVER_CLIP_ID_RE = /^scene-(\d+)-vo$/;
+/**
+ * Gap #1 follow-up (skip-generation) — derive, from the preserved clips, which
+ * scenes don't need their assets regenerated at all. A preserved visual means
+ * the user froze that scene's footage, so re-running the (expensive) provider
+ * gen just to discard the result is pure waste; same for a preserved VO and
+ * the TTS call. The executor consults these sets to short-circuit the tool
+ * dispatch, and planToProject uses `visual` to skip building a placeholder twin
+ * (the real preserved clip is injected verbatim instead).
+ *
+ * Keyed off the deterministic clip-id contract so it stays in lockstep with the
+ * ids planToProject emits (and the ids the preserve-override matches on).
+ */
+/**
+ * Gap #5 (diff-based bulk regen, lock-safety) — true if a regen target would
+ * overwrite a frozen (locked / user-edited) scene asset, so callers can drop it
+ * before charging or executing. The bulk diff (`diffPlans`) is plan-field based
+ * and lock-blind: a re-plan that rewrote a locked scene's prompt would emit a
+ * `visual` target for it, and running that would clobber the footage the user
+ * deliberately froze in the editor. Visual targets are gated by `frozen.visual`;
+ * voiceover AND captions by `frozen.voiceover` (captions are derived from the VO
+ * audio, so a locked VO keeps its captions too). Overlays/music aren't tracked
+ * by the frozen-scene model (they're separate clips), so they pass through.
+ */
+function isRegenTargetFrozen(target, frozen) {
+    if (typeof target.sceneIndex !== "number")
+        return false;
+    if (target.component === "visual")
+        return frozen.visual.has(target.sceneIndex);
+    if (target.component === "voiceover" || target.component === "captions") {
+        return frozen.voiceover.has(target.sceneIndex);
+    }
+    return false;
+}
+function computeFrozenScenes(preserveClips) {
+    const visual = new Set();
+    const voiceover = new Set();
+    for (const clip of preserveClips) {
+        const v = VISUAL_CLIP_ID_RE.exec(clip.id);
+        if (v) {
+            visual.add(Number(v[1]));
+            continue;
+        }
+        const vo = VOICEOVER_CLIP_ID_RE.exec(clip.id);
+        if (vo)
+            voiceover.add(Number(vo[1]));
+    }
+    return { visual, voiceover };
+}

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

@@ -86,22 +86,5 @@ export declare class Planner {
         /** Free-form caller hint, e.g. "punchier CTA" or "drop the watermark". */
         instruction?: string;
     }): Promise<TextOverlay[]>;
-    private buildMessages;
 }
-/**
- * Heuristic — does the brief mention real-world entities that benefit from
- * web grounding? A planner without research will happily invent fake app
- * names, fabricate statistics, and miss real-world brand details. Triggers
- * when the brief contains:
- *   - explicit "top N / best / popular / list of" framings
- *   - proper-noun-heavy briefs (≥2 capitalized non-sentence-start words)
- *   - listicle/comparison/news/review keywords
- *   - explicit time markers ("2026", "latest", "this year", "recent")
- *   - statistics signals ("statistics", "data", "percent", "study")
- *
- * Deliberately conservative — false negatives are fine (we just skip the
- * search), false positives waste $0.01 per planner call. Override via
- * `useWebResearch: true|false` when the caller knows better.
- */
-export declare function briefNeedsWebResearch(brief: VideoBrief): boolean;
 //# sourceMappingURL=Planner.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Planner.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/Planner.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,WAAW,EAEX,SAAS,EAEV,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAwB7C;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,OAAO;IAIN,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAEP,IAAI,EAAE,cAAc;IAK3C,IAAI,CACR,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;QACJ,OAAO,CAAC,EAAE,YAAY,CAAC;QACvB,QAAQ,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;QACjC,WAAW,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;QACvC,KAAK,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;QAChC;;;;;;WAMG;QACH,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;KAC9B,GACL,OAAO,CAAC,SAAS,CAAC;IAmOrB;;;;;;;;;;;OAWG;IACH,UAAU,CACR,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;QACJ,OAAO,CAAC,EAAE,YAAY,CAAC;QACvB,QAAQ,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;QACjC,WAAW,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;QACvC,KAAK,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;KAC5B,GACL;QAAE,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAA;KAAE;IAqDhE;;;;;;;;;;;;;;;;OAgBG;IACG,0BAA0B,CAC9B,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;QACJ,OAAO,CAAC,EAAE,YAAY,CAAC;QACvB,QAAQ,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;QACjC,KAAK,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;QAChC,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,0EAA0E;QAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;KACjB,GACL,OAAO,CAAC,WAAW,EAAE,CAAC;IA0IzB,OAAO,CAAC,aAAa;CAuItB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAiChE"}
+{"version":3,"file":"Planner.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/Planner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAoB,MAAM,+BAA+B,CAAC;AAC7E,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,SAAS,EAEV,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAkB7C;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,OAAO;IAIN,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAEP,IAAI,EAAE,cAAc;IAK3C,IAAI,CACR,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;QACJ,OAAO,CAAC,EAAE,YAAY,CAAC;QACvB,QAAQ,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;QACjC,WAAW,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;QACvC,KAAK,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;QAChC;;;;;;WAMG;QACH,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;KAC9B,GACL,OAAO,CAAC,SAAS,CAAC;IAyQrB;;;;;;;;;;;OAWG;IACH,UAAU,CACR,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;QACJ,OAAO,CAAC,EAAE,YAAY,CAAC;QACvB,QAAQ,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;QACjC,WAAW,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;QACvC,KAAK,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;KAC5B,GACL;QAAE,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAA;KAAE;IAqEhE;;;;;;;;;;;;;;;;OAgBG;IACG,0BAA0B,CAC9B,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;QACJ,OAAO,CAAC,EAAE,YAAY,CAAC;QACvB,QAAQ,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;QACjC,KAAK,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;QAChC,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,0EAA0E;QAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;KACjB,GACL,OAAO,CAAC,WAAW,EAAE,CAAC;CAQ1B"}

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

@@ -1,20 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Planner = void 0;
-exports.briefNeedsWebResearch = briefNeedsWebResearch;
-const zod_1 = require("zod");
+const brief_schema_1 = require("../../../schemas/brief.schema");
 const videoPlan_schema_1 = require("../../../schemas/videoPlan.schema");
 const llmCallerAnthropic_1 = require("../llmCallerAnthropic");
 const llmCallerRegistry_1 = require("../llmCallerRegistry");
 const modelRouter_1 = require("../modelRouter");
-const personas_1 = require("../personas");
-const modelQualityNotes_1 = require("../modelQualityNotes");
-const promptSections_1 = require("./promptSections");
-const structuralRules_1 = require("./structuralRules");
+const scriptFirstPlanner_1 = require("./scriptFirstPlanner");
 const repair_1 = require("./repair");
 const overlaySanity_1 = require("./overlaySanity");
 const costPreflight_1 = require("../costPreflight");
 const validators_1 = require("./validators");
+const plannerMessages_1 = require("./plannerMessages");
+const overlayRegen_1 = require("./overlayRegen");
 class Planner {
     constructor(opts) {
         this.opts = opts;
@@ -22,16 +20,27 @@ class Planner {
         this.maxRetries = opts.maxRetries ?? 2;
     }
     async plan(brief, opts = {}) {
+        // Stream L (L-3): long-form (L1/L2) uses script-first authoring (full
+        // narration → chapters → B-roll scenes) rather than the single-call
+        // scene-first planner below, which drifts on multi-minute videos. The
+        // assembled plan satisfies the L-2 chapter contract by construction.
+        const lengthTier = brief.lengthTier ?? (0, brief_schema_1.deriveLengthTier)(brief.durationSec);
+        if (lengthTier === "L1" || lengthTier === "L2") {
+            return (0, scriptFirstPlanner_1.planScriptFirst)({ llm: this.opts.llm }, brief, {
+                persona: opts.persona,
+                bible: opts.bible ?? null,
+            });
+        }
         const model = this.router.pickFor("planner", {
             premium: brief.tierBudget === "T3",
         });
         const fallbackModel = this.router.fallbackFor("planner");
         // Resolve research flag. We only use research when the Anthropic caller
         // is wired AND the brief implies real-world subjects — otherwise the
-        // gateway path (provider-portable) is preferred.
+        // normal dispatcher path (no server-side web_search) is used.
         const anthropic = (0, llmCallerRegistry_1.getAnthropicCaller)();
         const wantsResearch = opts.useWebResearch === true ||
-            (opts.useWebResearch !== false && briefNeedsWebResearch(brief));
+            (opts.useWebResearch !== false && (0, plannerMessages_1.briefNeedsWebResearch)(brief));
         let useResearchCall = wantsResearch &&
             anthropic !== null &&
             typeof anthropic.structuredWithTools === "function" &&
@@ -45,7 +54,7 @@ class Planner {
         const thinkingBudget = premium ? 4096 : undefined;
         let lastErrors;
         for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
-            const messages = this.buildMessages(brief, opts.persona, opts.brandKit ?? null, opts.styleMemory ?? null, opts.bible ?? null, lastErrors, useResearchCall);
+            const messages = (0, plannerMessages_1.buildPlannerMessages)(brief, opts.persona, opts.brandKit ?? null, opts.styleMemory ?? null, opts.bible ?? null, lastErrors, useResearchCall);
             let result;
             try {
                 if (useResearchCall && anthropic?.structuredWithTools) {
@@ -54,9 +63,10 @@ class Planner {
                     // - `cachePrompt`: 90% discount on cache hits — every retry within
                     //   5 minutes pays ~10% of the system + tools tokens.
                     // - `thinking`: enabled on T3 premium briefs only.
-                    // - Transient Anthropic errors fall through to the gateway path
-                    //   below via the catch — better to ship a non-researched plan
-                    //   than to 500 the whole /plan endpoint on an outage.
+                    // - Transient Anthropic errors fall through to the non-research
+                    //   dispatcher path below via the catch — better to ship a
+                    //   non-researched plan than to 500 the whole /plan endpoint on an
+                    //   outage.
                     try {
                         result = await anthropic.structuredWithTools({
                             model,
@@ -77,7 +87,7 @@ class Planner {
                             // subsequent attempts. The plan we produce won't be grounded,
                             // but it'll exist — and the warning flag tells the UI.
                             useResearchCall = false;
-                            const fallbackMessages = this.buildMessages(brief, opts.persona, opts.brandKit ?? null, opts.styleMemory ?? null, opts.bible ?? null, lastErrors, false);
+                            const fallbackMessages = (0, plannerMessages_1.buildPlannerMessages)(brief, opts.persona, opts.brandKit ?? null, opts.styleMemory ?? null, opts.bible ?? null, lastErrors, false);
                             result = await this.opts.llm.structured({
                                 model,
                                 fallbackModel,
@@ -104,8 +114,8 @@ class Planner {
                 }
             }
             catch (e) {
-                // AG-25: the gateway throws on schema-validation failures. Without this
-                // catch the planner's correction-retry loop never fires — a single
+                // AG-25: the LlmCaller throws on schema-validation failures. Without
+                // this catch the planner's correction-retry loop never fires — a single
                 // sub-1ms scene duration from the LLM would crash the whole agent.
                 // Capture the error as correction context and let the loop retry.
                 const msg = e instanceof Error ? e.message : String(e);
@@ -183,6 +193,31 @@ class Planner {
                     lastErrors = narrationGap;
                     continue;
                 }
+                // Stream L (L-2): chapter contract for L1/L2 long-form plans — chapters
+                // MUST partition the scene list exactly. Downgrade-on-last-attempt
+                // (like ttsGap): chapters aren't render-breaking (the schema field is
+                // optional and the render path ignores it for now), so ship without
+                // them rather than throw away an otherwise-valid long-form plan.
+                const chapterGap = (0, validators_1.checkChapterContract)(reparsed.data, brief);
+                if (chapterGap && attempt < this.maxRetries) {
+                    lastErrors = chapterGap;
+                    continue;
+                }
+                // Stream L (L-6): hard spend cap. If brief.maxSpendUSD is set and the
+                // plan's estimated generation cost is over it, re-prompt for cheaper
+                // tiers / stock / fewer scenes. Hard-reject (no downgrade) — shipping
+                // an over-budget plan would spend past the user's explicit cap.
+                const budgetGap = (0, validators_1.checkBudgetContract)(reparsed.data, brief);
+                if (budgetGap) {
+                    lastErrors = budgetGap;
+                    continue;
+                }
+                // Stream L (L-1): stamp the effective length tier so downstream
+                // consumers (cost guardrails L-6, editor chapter UI) don't re-derive
+                // it. Trust brief.lengthTier when set; otherwise derive from duration.
+                // Don't trust the LLM to fill it — overlay deterministically.
+                reparsed.data.lengthTier =
+                    brief.lengthTier ?? (0, brief_schema_1.deriveLengthTier)(brief.durationSec);
                 // Persist the bible on the plan so downstream (executor / AG-13)
                 // has it without a second read. Planner doesn't author the bible.
                 if (opts.bible)
@@ -239,10 +274,25 @@ class Planner {
      * who already painted partial JSON for the first attempt.
      */
     planStream(brief, opts = {}) {
+        // Stream L (L-3): long-form is a multi-pass pipeline (script → chapters →
+        // scenes) that can't stream a single structured payload cleanly. Run the
+        // non-streaming script-first path and emit the finished plan as one chunk,
+        // mirroring the no-structuredStream fallback below.
+        const lengthTier = brief.lengthTier ?? (0, brief_schema_1.deriveLengthTier)(brief.durationSec);
+        if (lengthTier === "L1" || lengthTier === "L2") {
+            const result = this.plan(brief, opts);
+            const tokens = {
+                async *[Symbol.asyncIterator]() {
+                    const plan = await result;
+                    yield JSON.stringify(plan);
+                },
+            };
+            return { tokens, result };
+        }
         const model = this.router.pickFor("planner", {
             premium: brief.tierBudget === "T3",
         });
-        const messages = this.buildMessages(brief, opts.persona, opts.brandKit ?? null, opts.styleMemory ?? null, opts.bible ?? null);
+        const messages = (0, plannerMessages_1.buildPlannerMessages)(brief, opts.persona, opts.brandKit ?? null, opts.styleMemory ?? null, opts.bible ?? null);
         if (!this.opts.llm.structuredStream) {
             // Fallback path — emit the whole plan as one chunk after non-streaming call.
             const result = this.plan(brief, opts);
@@ -299,293 +349,7 @@ class Planner {
      * beyond the LLM call.
      */
     async regenerateOverlaysForScene(scene, brief, opts = {}) {
-        const model = this.router.pickFor("planner", {
-            premium: brief.tierBudget === "T3",
-        });
-        const fallbackModel = this.router.fallbackFor("planner");
-        const FocusedOverlaySchema = zod_1.z.object({
-            overlays: zod_1.z.array(videoPlan_schema_1.TextOverlaySchema).max(4),
-        });
-        const personaPack = opts.persona ? personas_1.PERSONA_PACKS[opts.persona] : null;
-        const brandKitSection = (0, promptSections_1.buildBrandKitSection)(opts.brandKit ?? null);
-        const bibleSection = (0, promptSections_1.buildBibleSection)(opts.bible ?? null);
-        const closingHint = opts.isClosingScene
-            ? "  - This IS the CLOSING scene — you MUST include role='cta' (max 5 words, brand + verb, e.g. 'Get HydraPure Today')."
-            : "  - This is NOT the closing scene — do NOT emit role='cta' (CTA belongs only on the final scene).";
-        const watermarkHint = scene.sceneIndex === 0
-            ? "  - This IS scene 0 — you MAY include exactly one role='watermark' overlay with persistAcrossScenes:true (max 2 words, brand name)."
-            : "  - This is NOT scene 0 — do NOT emit role='watermark' (watermark is emitted once on scene 0 and auto-carries forward).";
-        const overlayContract = [
-            "Emit ONLY this scene's overlays (array of TextOverlay, max 4 entries).",
-            "Each overlay = { text, role, position?, persistAcrossScenes?, emphasis?, animation?, startMs?, endMs? }.",
-            "CRITICAL: `text` is the LITERAL on-screen copy users will read — NOT a description of how it should look. Styling (font, color, position, drop-shadow) is applied automatically from the role.",
-            "  GOOD: text:\"Your eyes lie to you\"",
-            "  BAD:  text:\"Bold white sans-serif subtitle in the lower third of a 9:16 frame\"  (REJECTED as styling description)",
-            "Roles + word limits:",
-            "  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 pill, bold, max 5 words, MUST combine brand + verb.",
-            "  watermark   — bottom-right tiny, max 2 words, just the brand name.",
-            "  disclaimer  — tiny bottom legal copy.",
-            "  label       — in-frame object/person label, max 3 words.",
-            "Max 4 overlays per scene. Don't emit two headlines on the same scene.",
-            "Emojis are OK — the renderer supports color glyphs natively.",
-            closingHint,
-            watermarkHint,
-        ].join("\n");
-        const personaLine = personaPack
-            ? `Persona: ${opts.persona} — ${personaPack.plannerPrompt.split("\n")[0]}`
-            : "";
-        const system = [
-            "You are a video-overlay copywriter.",
-            "Given ONE scene from a VideoPlan, emit a fresh `overlays[]` for that scene.",
-            "The rest of the plan (other scenes, VO, visuals, music) is fixed — do not comment on it, do not return it.",
-            "",
-            overlayContract,
-            personaLine,
-            brandKitSection,
-            bibleSection,
-        ]
-            .filter(Boolean)
-            .join("\n");
-        const sceneContext = {
-            sceneIndex: scene.sceneIndex,
-            intent: scene.intent,
-            prompt: scene.prompt,
-            voiceoverLine: scene.voiceoverLine,
-            onScreenText: scene.onScreenText,
-            durationMs: scene.durationMs,
-            currentOverlays: scene.overlays ?? [],
-        };
-        const userParts = [
-            `Brief context:\n${JSON.stringify({
-                rawPrompt: brief.rawPrompt,
-                tone: brief.tone,
-                niche: brief.niche,
-            }, null, 2)}`,
-            `Scene:\n${JSON.stringify(sceneContext, null, 2)}`,
-        ];
-        if (opts.instruction?.trim()) {
-            userParts.push(`Caller instruction: ${opts.instruction.trim()}`);
-        }
-        else {
-            userParts.push("No specific instruction — produce a fresh, on-brand overlay set that fits the scene's intent and voiceoverLine.");
-        }
-        const user = userParts.join("\n\n");
-        let lastErrors;
-        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
-            const messages = [
-                { role: "system", content: system },
-                {
-                    role: "user",
-                    content: lastErrors
-                        ? `${user}\n\nPrevious attempt failed validation: ${lastErrors}\nFix and try again.`
-                        : user,
-                },
-            ];
-            try {
-                const result = await this.opts.llm.structured({
-                    model,
-                    fallbackModel,
-                    messages,
-                    schema: FocusedOverlaySchema,
-                    schemaName: "SceneOverlays",
-                    temperature: attempt === 0 ? 0.6 : 0.3,
-                });
-                const overlays = result.data.overlays;
-                // Re-use the same style-leak validator the full-plan path uses by
-                // wrapping the overlays in a single-scene VideoPlan-shaped object.
-                // Cheaper than re-implementing the regex set here.
-                const probe = {
-                    scenes: [{ ...scene, overlays }],
-                };
-                const leak = (0, overlaySanity_1.checkOverlayContentSanity)(probe);
-                if (leak) {
-                    lastErrors = leak;
-                    continue;
-                }
-                return overlays;
-            }
-            catch (e) {
-                const msg = e instanceof Error ? e.message : String(e);
-                if (/schema validation failed|non-JSON|empty response/i.test(msg)) {
-                    lastErrors = `Previous attempt failed validation: ${msg.slice(0, 400)}.`;
-                    continue;
-                }
-                throw e;
-            }
-        }
-        throw new Error(`Planner failed to produce valid overlays for scene ${scene.sceneIndex} after ${this.maxRetries + 1} attempts. Last errors: ${lastErrors}`);
-    }
-    buildMessages(brief, persona, brandKit, styleMemory, bible, lastErrors, useResearchCall = false) {
-        const structuralRulesSection = (0, structuralRules_1.buildStructuralRulesSection)(brief);
-        const personaSection = persona
-            ? [
-                "",
-                `Selected persona: ${persona}.`,
-                `Set plan.persona to "${persona}" in the output.`,
-                "Persona-specific structural rules (apply on top of the global tier rules):",
-                personas_1.PERSONA_PACKS[persona].plannerPrompt,
-            ].join("\n")
-            : "";
-        const brandKitSection = (0, promptSections_1.buildBrandKitSection)(brandKit);
-        const styleMemorySection = (0, promptSections_1.buildStyleMemorySection)(styleMemory);
-        const bibleSection = (0, promptSections_1.buildBibleSection)(bible);
-        const modelCatalogSection = (0, promptSections_1.buildModelCatalogSection)();
-        const videoStrategySection = (0, promptSections_1.buildVideoStrategySection)(brief.videoStrategy);
-        // AG-39: warn the planner away from models with known capability gaps for
-        // dimensions this brief signals it cares about (brand text on product
-        // labels is the immediate driver). Empty string when nothing rated.
-        const modelQualitySection = (0, modelQualityNotes_1.renderModelQualityHintsForSystemPrompt)({
-            needsBrandText: (0, promptSections_1.briefMentionsBrandText)(brief),
-            needsCharacterContinuity: persona === "ugc-ad" || persona === "talking-head",
-            needsFastMotion: brief.tone?.toLowerCase()?.includes("energetic") || brief.tone?.toLowerCase()?.includes("action"),
-            needsCinematic: brief.tone?.toLowerCase()?.includes("cinematic"),
-        });
-        const researchSection = useResearchCall
-            ? [
-                "",
-                "RESEARCH MODE — `web_search` is enabled. The brief mentions real-world",
-                "subjects (products, companies, people, places, events, or statistics).",
-                "Before planning, run targeted `web_search` calls (max 5) to ground the",
-                "plan in real facts: real product names, real feature lists, real logos,",
-                "real statistics, real quotes. Use the results to populate scene prompts,",
-                "voiceover lines, and overlay copy — NEVER fabricate company names,",
-                "product specs, or numbers. Cite findings implicitly via accurate copy;",
-                "do not embed raw URLs in the plan. When done researching, call the",
-                "`submit_VideoPlan` tool with the final plan.",
-                "",
-            ].join("\n")
-            : "";
-        const system = [
-            "You are a video-production planner.",
-            "Given a VideoBrief, produce a VideoPlan: an ordered list of scenes",
-            "with per-scene asset strategy, tier, prompt, duration, and voiceover.",
-            researchSection,
-            "",
-            "Tier rules — respect brief.tierBudget as the maximum tier:",
-            "  T0: stock footage / image with Ken-Burns motion.",
-            "  T1: AI-generated still + camera motion.",
-            "  T2: AI image-to-video on key frames only.",
-            "  T3: full text-to-video (most expensive — use sparingly).",
-            "",
-            "Stock strategy bias — when budget is T0 and the scene depicts something",
-            "with natural motion (skies, light, water, traffic, hands at work,",
-            "animals, machinery, weather, crowds), prefer strategy='stock-video' over",
-            "'stock-image-ken-burns'. Static images with synthesized zoom feel like",
-            "a slideshow when chained for >3 cuts; real stock clips give the same",
-            "T0 cost with genuine motion. Only fall back to stock-image-ken-burns",
-            "when the subject is inherently still (diagrams, infographics, single",
-            "objects on a table, frozen moments) OR when the brief explicitly asks",
-            "for a poster/title-card feel.",
-            "",
-            videoStrategySection,
-            "",
-            "talking-head-avatar is wired and runs the kling-avatar pipeline (face",
-            "still + TTS lipsync). Pick it ONLY when the brand kit exposes a",
-            "presenterFaceUrl — set scene.avatarFaceUrl to that URL on every avatar",
-            "scene. If no presenter face is available, fall back to ai-image-to-video",
-            "or stock-video of a presenter instead.",
-            "",
-            "user-asset is wired and reuses the requesting user's existing library",
-            "(their previously generated images / videos / audio) instead of spending",
-            "credits to make a new asset. Pick user-asset when the brief mentions a",
-            "recurring brand subject (their product photo, spokesperson, b-roll) —",
-            "the executor falls back to stock-video if no library match scores high",
-            "enough, so picking it is safe.",
-            "",
-            "Keep total estimated credits as low as possible while honoring the",
-            "brief. Mix tiers within a single video where it helps cost without",
-            "harming quality (e.g. T2 hero shot + T0 b-roll between).",
-            "",
-            "Smart model routing — set preferredModel per scene from the catalog:",
-            "  - Hero / opening-hook / product-reveal scenes: pick the highest-",
-            "    quality model in the chosen tier (most expensive in that tier).",
-            "  - B-roll / filler / transition scenes: pick the cheapest model in",
-            "    the chosen tier — the audience won't notice the difference and",
-            "    cost drops 3–5x.",
-            "  - When in doubt for a non-hero scene, pick the median-cost model.",
-            "  - preferredModel must match a key from the catalog below; the",
-            "    executor will swap on rate-limit, so picking is best-effort, not",
-            "    a hard contract.",
-            modelCatalogSection,
-            modelQualitySection,
-            // AG-14 fix: persona section moved above structuralRulesSection and
-            // bibleSection. The bible block has multiple "MUST" rules that were
-            // crowding out persona.hookStyle when persona was the last item before
-            // brandKit; on `seed-ugc-skincare` this regressed hookStrength to 0.4
-            // (planner picked a generic "Wait…" opener instead of the brief's
-            // problem-statement hook). Order is now: persona (voice + hookStyle) →
-            // structural rules → bible (entity verbatim re-statement).
-            personaSection,
-            structuralRulesSection,
-            bibleSection,
-            brandKitSection,
-            styleMemorySection,
-        ]
-            .filter(Boolean)
-            .join("\n");
-        const user = [
-            `Brief:\n${JSON.stringify(brief, null, 2)}`,
-            lastErrors
-                ? `\nYour previous attempt failed validation: ${lastErrors}\nFix the structure and try again.`
-                : "",
-        ]
-            .filter(Boolean)
-            .join("\n");
-        return [
-            { role: "system", content: system },
-            { role: "user", content: user },
-        ];
+        return (0, overlayRegen_1.regenerateOverlaysForScene)({ llm: this.opts.llm, router: this.router, maxRetries: this.maxRetries }, scene, brief, opts);
     }
 }
 exports.Planner = Planner;
-/**
- * Heuristic — does the brief mention real-world entities that benefit from
- * web grounding? A planner without research will happily invent fake app
- * names, fabricate statistics, and miss real-world brand details. Triggers
- * when the brief contains:
- *   - explicit "top N / best / popular / list of" framings
- *   - proper-noun-heavy briefs (≥2 capitalized non-sentence-start words)
- *   - listicle/comparison/news/review keywords
- *   - explicit time markers ("2026", "latest", "this year", "recent")
- *   - statistics signals ("statistics", "data", "percent", "study")
- *
- * Deliberately conservative — false negatives are fine (we just skip the
- * search), false positives waste $0.01 per planner call. Override via
- * `useWebResearch: true|false` when the caller knows better.
- */
-function briefNeedsWebResearch(brief) {
-    const text = [
-        brief.rawPrompt ?? "",
-        brief.tone ?? "",
-        brief.niche ?? "",
-    ]
-        .filter(Boolean)
-        .join(" ");
-    if (!text.trim())
-        return false;
-    const lower = text.toLowerCase();
-    const listicleSignals = /\b(top\s+\d+|best\s+\d*\s*\w+|popular|list\s+of|review|comparison|vs\.?|versus|trending|latest|recent|news|breaking|study|statistics?|data|percent|%|million|billion|industry|market|report)\b/;
-    if (listicleSignals.test(lower))
-        return true;
-    const yearMarker = /\b(20\d{2}|this\s+year|last\s+year)\b/;
-    if (yearMarker.test(lower))
-        return true;
-    // Count proper nouns that aren't sentence-starters — heuristic for
-    // "specific brands / people / places".
-    const words = text.split(/\s+/);
-    let properNouns = 0;
-    for (let i = 0; i < words.length; i++) {
-        const w = words[i] ?? "";
-        const prev = i > 0 ? words[i - 1] ?? "" : "";
-        const isSentenceStart = i === 0 || /[.!?]$/.test(prev);
-        if (!isSentenceStart && /^[A-Z][a-zA-Z0-9]{2,}/.test(w)) {
-            properNouns++;
-            if (properNouns >= 2)
-                return true;
-        }
-    }
-    return false;
-}