vidspotai-shared 1.0.82-dev.0 → 1.0.83

package/lib/services/agent/covers/covers.schema.d.ts

@@ -0,0 +1,158 @@
+import { z } from "zod";
+/**
+ * X8 Social Suite · Phase 6 · E2 — "AI covers + A/B" schemas.
+ *
+ * One source video → an LLM picks the strongest still MOMENTS to grab as cover
+ * frames AND writes the thumbnail copy (a punchy headline + optional subtext)
+ * for each, deliberately spread across distinct A/B ANGLES (curiosity vs.
+ * benefit vs. bold-claim …). Each candidate frame is then extracted, cropped to
+ * the cover aspect, and re-scored by a VISION model so the picks reflect what
+ * the frame actually looks like (sharp / well-framed / a face), not just what
+ * the transcript said. The output is a set of ranked, ready-to-A/B-test covers.
+ *
+ * Deliberately a sibling of E3 (auto-repurpose), not a fork: E3 cuts VIDEO
+ * spans, E2 grabs STILL frames. They share the ffmpeg primitives (download /
+ * probe / a new single-frame extract), the ASR transcript shape, and the
+ * reframe geometry — but the brain and output shape differ, so E2 gets its own
+ * pure planner (coverPlanner.ts) and its own worker, leaving E3 untouched.
+ *
+ * As elsewhere on the agent surface, the PURE logic (frame selection, copy,
+ * vision re-scoring, clamping, credit math) lives in `shared` so it is
+ * unit-/eval-able; the IO-heavy stages (download → ASR → ffmpeg frame extract →
+ * upload) run in the node-express worker where ffmpeg already is.
+ */
+export declare const CoverRequestSchema: z.ZodObject<{
+    sourceVideoUrl: z.ZodString;
+    sourceDurationSec: z.ZodNumber;
+    maxCovers: z.ZodOptional<z.ZodNumber>;
+    aspect: z.ZodOptional<z.ZodEnum<{
+        "9:16": "9:16";
+        "1:1": "1:1";
+        "4:5": "4:5";
+        "16:9": "16:9";
+    }>>;
+    language: z.ZodOptional<z.ZodString>;
+    instructions: z.ZodOptional<z.ZodString>;
+    tone: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type CoverRequest = z.infer<typeof CoverRequestSchema>;
+export declare const COVER_HEADLINE_MAX = 80;
+export declare const COVER_SUBTEXT_MAX = 120;
+export declare const COVER_ANGLE_MAX = 40;
+export declare const COVER_REASON_MAX = 400;
+/** The recognised A/B angles. Free strings are allowed but the planner is steered to these. */
+export declare const COVER_ANGLES: readonly ["curiosity", "benefit", "bold-claim", "question", "how-to", "emotional", "contrarian", "listicle"];
+/**
+ * One cover candidate: a single still MOMENT of the source plus the thumbnail
+ * copy to overlay on it. The overlay text is returned as DATA (not baked into
+ * the pixels) so the UI can render every A/B variant live and the user can pick
+ * the winner before exporting — keeps v1 flexible and avoids font/placement
+ * guesswork in ffmpeg.
+ */
+export declare const CoverCandidateSchema: z.ZodObject<{
+    atMs: z.ZodNumber;
+    headline: z.ZodString;
+    subtext: z.ZodOptional<z.ZodString>;
+    angle: z.ZodString;
+    reason: z.ZodString;
+    score: z.ZodNumber;
+}, z.core.$strict>;
+export type CoverCandidate = z.infer<typeof CoverCandidateSchema>;
+export declare const CoverPlanSchema: z.ZodObject<{
+    covers: z.ZodArray<z.ZodObject<{
+        atMs: z.ZodNumber;
+        headline: z.ZodString;
+        subtext: z.ZodOptional<z.ZodString>;
+        angle: z.ZodString;
+        reason: z.ZodString;
+        score: z.ZodNumber;
+    }, z.core.$strict>>;
+    summary: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type CoverPlan = z.infer<typeof CoverPlanSchema>;
+/**
+ * Per-frame verdict from the vision pass. The planner chose the moment from
+ * TEXT; the vision model now actually LOOKS at the extracted frame and reports
+ * whether it works as a still (sharp, well-composed, a clear subject/face) and
+ * a 0–100 visual score. `index` ties back to the candidate it judged.
+ */
+export declare const CoverVisionVerdictSchema: z.ZodObject<{
+    index: z.ZodNumber;
+    visualScore: z.ZodNumber;
+    isPoor: z.ZodBoolean;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type CoverVisionVerdict = z.infer<typeof CoverVisionVerdictSchema>;
+export declare const CoverVisionReportSchema: z.ZodObject<{
+    verdicts: z.ZodArray<z.ZodObject<{
+        index: z.ZodNumber;
+        visualScore: z.ZodNumber;
+        isPoor: z.ZodBoolean;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CoverVisionReport = z.infer<typeof CoverVisionReportSchema>;
+/**
+ * Tiny job envelope — same design rule as RepurposeJobPayload: the full request
+ * lives on `agentProjects/{projectId}.coverRequest`, the worker reads it at job
+ * start. Keeps the Redis stream light.
+ */
+export declare const CoverJobPayloadSchema: z.ZodObject<{
+    runId: z.ZodString;
+    projectId: z.ZodString;
+    userId: z.ZodString;
+    enqueuedAt: z.ZodNumber;
+}, z.core.$strict>;
+export type CoverJobPayload = z.infer<typeof CoverJobPayloadSchema>;
+/**
+ * A finished cover on `agentProjects/{projectId}.covers[]`. Carries the
+ * extracted/cropped still URL + the overlay copy + the source timestamp it was
+ * grabbed from, plus the blended final score (planner + vision). Sorted by
+ * `score` desc in the UI so the strongest A/B variant leads.
+ */
+export interface ProducedCover {
+    index: number;
+    /** Source timestamp the still was grabbed from, ms. */
+    atMs: number;
+    /** Overlay copy (rendered live over the image by the UI; not baked in). */
+    headline: string;
+    subtext?: string;
+    /** The A/B angle this variant tests. */
+    angle: string;
+    reason: string;
+    /** Blended final score 0–100 (planner click-through × vision frame quality). */
+    score: number;
+    /** Planner's pre-vision click-through prediction (kept for transparency). */
+    plannerScore: number;
+    /** Vision frame-quality score 0–100 when the vision pass ran (else absent). */
+    visualScore?: number;
+    /** Output aspect (the requested target, e.g. "9:16"). */
+    aspect: string;
+    /** Long-lived signed URL of the extracted, aspect-cropped still (JPG). */
+    imageUrl: string;
+    width: number;
+    height: number;
+}
+/**
+ * Flat USD overheads beyond the per-second ASR cost:
+ *   - the cover-planner LLM call (one structured text pass over the transcript),
+ *   - the vision re-score LLM call (one structured vision pass over the frames),
+ *   - our ffmpeg compute per cover (a single-frame extract + crop + upload —
+ *     cheap, but priced so the op isn't free).
+ */
+export declare const COVER_PLANNER_LLM_USD = 0.04;
+export declare const COVER_VISION_LLM_USD = 0.02;
+export declare const COVER_COMPUTE_PER_USD = 0.005;
+/** Default covers assumed for the upfront estimate when maxCovers is omitted. */
+export declare const DEFAULT_MAX_COVERS = 4;
+/**
+ * Pure upfront credit estimate for a covers job. The controller deducts this
+ * before enqueue; the worker reconciles against the REAL ASR duration and the
+ * actual number of covers produced, refunding any overcharge. 1 credit = $0.10.
+ */
+export declare function estimateCoverCredits(args: {
+    sourceDurationSec: number;
+    maxCovers?: number;
+}): number;
+//# sourceMappingURL=covers.schema.d.ts.map

package/lib/services/agent/covers/covers.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"covers.schema.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/covers/covers.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;kBAuBpB,CAAC;AACZ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,iBAAiB,MAAM,CAAC;AACrC,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,+FAA+F;AAC/F,eAAO,MAAM,YAAY,8GASf,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;;;;;;;kBAetB,CAAC;AACZ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,eAAe;;;;;;;;;;kBAMjB,CAAC;AACZ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAIxD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;kBAU1B,CAAC;AACZ,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,eAAO,MAAM,uBAAuB;;;;;;;kBAIzB,CAAC;AACZ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAIxE;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;kBAOvB,CAAC;AACZ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAIpE;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAID;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAC1C,eAAO,MAAM,oBAAoB,OAAO,CAAC;AACzC,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAG3C,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,CAST"}

package/lib/services/agent/covers/covers.schema.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_COVERS = exports.COVER_COMPUTE_PER_USD = exports.COVER_VISION_LLM_USD = exports.COVER_PLANNER_LLM_USD = exports.CoverJobPayloadSchema = exports.CoverVisionReportSchema = exports.CoverVisionVerdictSchema = exports.CoverPlanSchema = exports.CoverCandidateSchema = exports.COVER_ANGLES = exports.COVER_REASON_MAX = exports.COVER_ANGLE_MAX = exports.COVER_SUBTEXT_MAX = exports.COVER_HEADLINE_MAX = exports.CoverRequestSchema = void 0;
+exports.estimateCoverCredits = estimateCoverCredits;
+const zod_1 = require("zod");
+const project_schema_1 = require("../../../schemas/project.schema");
+const helpers_1 = require("../../../utils/helpers");
+/**
+ * X8 Social Suite · Phase 6 · E2 — "AI covers + A/B" schemas.
+ *
+ * One source video → an LLM picks the strongest still MOMENTS to grab as cover
+ * frames AND writes the thumbnail copy (a punchy headline + optional subtext)
+ * for each, deliberately spread across distinct A/B ANGLES (curiosity vs.
+ * benefit vs. bold-claim …). Each candidate frame is then extracted, cropped to
+ * the cover aspect, and re-scored by a VISION model so the picks reflect what
+ * the frame actually looks like (sharp / well-framed / a face), not just what
+ * the transcript said. The output is a set of ranked, ready-to-A/B-test covers.
+ *
+ * Deliberately a sibling of E3 (auto-repurpose), not a fork: E3 cuts VIDEO
+ * spans, E2 grabs STILL frames. They share the ffmpeg primitives (download /
+ * probe / a new single-frame extract), the ASR transcript shape, and the
+ * reframe geometry — but the brain and output shape differ, so E2 gets its own
+ * pure planner (coverPlanner.ts) and its own worker, leaving E3 untouched.
+ *
+ * As elsewhere on the agent surface, the PURE logic (frame selection, copy,
+ * vision re-scoring, clamping, credit math) lives in `shared` so it is
+ * unit-/eval-able; the IO-heavy stages (download → ASR → ffmpeg frame extract →
+ * upload) run in the node-express worker where ffmpeg already is.
+ */
+// ─── request (the controller body) ───────────────────────────────────────────
+exports.CoverRequestSchema = zod_1.z
+    .object({
+    /** Publicly-fetchable URL of the source video (Firebase Storage / signed). */
+    sourceVideoUrl: zod_1.z.string().url(),
+    /**
+     * Source duration in seconds — needed for the UPFRONT ASR credit estimate
+     * (ASR is billed per second). The worker reconciles against the real ASR
+     * `audioDuration` after transcription.
+     */
+    sourceDurationSec: zod_1.z.number().positive(),
+    /** Hard cap on how many cover variants to produce. Planner default is 4. */
+    maxCovers: zod_1.z.number().int().positive().max(12).optional(),
+    /** Output aspect for the cover image. Default 9:16 (Reels/Shorts/TikTok). */
+    aspect: project_schema_1.AspectSchema.optional(),
+    /** ASR language hint (e.g. "en", "es"). Omitted → AssemblyAI autodetect. */
+    language: zod_1.z.string().min(2).max(10).optional(),
+    /** Free-form steering for the planner ("lean into the price reveal", etc.). */
+    instructions: zod_1.z.string().max(2000).optional(),
+    /** Tone hint for the headlines ("punchy", "professional"). */
+    tone: zod_1.z.string().max(200).optional(),
+    /** Display title for the produced cover set / project. */
+    title: zod_1.z.string().max(200).optional(),
+})
+    .strict();
+// ─── cover candidates (LLM output) ───────────────────────────────────────────
+exports.COVER_HEADLINE_MAX = 80;
+exports.COVER_SUBTEXT_MAX = 120;
+exports.COVER_ANGLE_MAX = 40;
+exports.COVER_REASON_MAX = 400;
+/** The recognised A/B angles. Free strings are allowed but the planner is steered to these. */
+exports.COVER_ANGLES = [
+    "curiosity",
+    "benefit",
+    "bold-claim",
+    "question",
+    "how-to",
+    "emotional",
+    "contrarian",
+    "listicle",
+];
+/**
+ * One cover candidate: a single still MOMENT of the source plus the thumbnail
+ * copy to overlay on it. The overlay text is returned as DATA (not baked into
+ * the pixels) so the UI can render every A/B variant live and the user can pick
+ * the winner before exporting — keeps v1 flexible and avoids font/placement
+ * guesswork in ffmpeg.
+ */
+exports.CoverCandidateSchema = zod_1.z
+    .object({
+    /** Timestamp in the SOURCE timeline to grab the still from, ms. */
+    atMs: zod_1.z.number().nonnegative(),
+    /** The big, scroll-stopping overlay headline (the thumbnail's main text). */
+    headline: zod_1.z.string().max(exports.COVER_HEADLINE_MAX),
+    /** Optional smaller supporting line under the headline. */
+    subtext: zod_1.z.string().max(exports.COVER_SUBTEXT_MAX).optional(),
+    /** The A/B angle this variant tests (see COVER_ANGLES; free string allowed). */
+    angle: zod_1.z.string().max(exports.COVER_ANGLE_MAX),
+    /** Why this frame + copy makes a strong cover — surfaced in the UI + eval. */
+    reason: zod_1.z.string().max(exports.COVER_REASON_MAX),
+    /** Planner's predicted click-through 0–100 (refined by the vision pass). */
+    score: zod_1.z.number().min(0).max(100),
+})
+    .strict();
+exports.CoverPlanSchema = zod_1.z
+    .object({
+    covers: zod_1.z.array(exports.CoverCandidateSchema).min(1),
+    /** One-line description of the cover set (optional; shown in UI). */
+    summary: zod_1.z.string().max(500).optional(),
+})
+    .strict();
+// ─── vision re-score (LLM output, pass 2) ────────────────────────────────────
+/**
+ * Per-frame verdict from the vision pass. The planner chose the moment from
+ * TEXT; the vision model now actually LOOKS at the extracted frame and reports
+ * whether it works as a still (sharp, well-composed, a clear subject/face) and
+ * a 0–100 visual score. `index` ties back to the candidate it judged.
+ */
+exports.CoverVisionVerdictSchema = zod_1.z
+    .object({
+    index: zod_1.z.number().int().nonnegative(),
+    /** 0–100 — purely how good the FRAME looks as a thumbnail still. */
+    visualScore: zod_1.z.number().min(0).max(100),
+    /** True if the frame is blurry / mid-blink / a transition smear / blank. */
+    isPoor: zod_1.z.boolean(),
+    /** Short note on the frame ("clear face, good contrast" / "motion blur"). */
+    note: zod_1.z.string().max(200).optional(),
+})
+    .strict();
+exports.CoverVisionReportSchema = zod_1.z
+    .object({
+    verdicts: zod_1.z.array(exports.CoverVisionVerdictSchema),
+})
+    .strict();
+// ─── BullMQ envelope ─────────────────────────────────────────────────────────
+/**
+ * Tiny job envelope — same design rule as RepurposeJobPayload: the full request
+ * lives on `agentProjects/{projectId}.coverRequest`, the worker reads it at job
+ * start. Keeps the Redis stream light.
+ */
+exports.CoverJobPayloadSchema = zod_1.z
+    .object({
+    runId: zod_1.z.string().min(1),
+    projectId: zod_1.z.string().min(1),
+    userId: zod_1.z.string().min(1),
+    enqueuedAt: zod_1.z.number().int().nonnegative(),
+})
+    .strict();
+// ─── cost ────────────────────────────────────────────────────────────────────
+/**
+ * Flat USD overheads beyond the per-second ASR cost:
+ *   - the cover-planner LLM call (one structured text pass over the transcript),
+ *   - the vision re-score LLM call (one structured vision pass over the frames),
+ *   - our ffmpeg compute per cover (a single-frame extract + crop + upload —
+ *     cheap, but priced so the op isn't free).
+ */
+exports.COVER_PLANNER_LLM_USD = 0.04;
+exports.COVER_VISION_LLM_USD = 0.02;
+exports.COVER_COMPUTE_PER_USD = 0.005;
+/** AssemblyAI Universal-2 base rate, $/hr (mirrors AssemblyAIService / E3). */
+const ASR_USD_PER_HOUR = 0.15;
+/** Default covers assumed for the upfront estimate when maxCovers is omitted. */
+exports.DEFAULT_MAX_COVERS = 4;
+/**
+ * Pure upfront credit estimate for a covers job. The controller deducts this
+ * before enqueue; the worker reconciles against the REAL ASR duration and the
+ * actual number of covers produced, refunding any overcharge. 1 credit = $0.10.
+ */
+function estimateCoverCredits(args) {
+    const covers = args.maxCovers ?? exports.DEFAULT_MAX_COVERS;
+    const asrUsd = (ASR_USD_PER_HOUR / 3600) * Math.max(0, args.sourceDurationSec);
+    const totalUsd = asrUsd +
+        exports.COVER_PLANNER_LLM_USD +
+        exports.COVER_VISION_LLM_USD +
+        exports.COVER_COMPUTE_PER_USD * Math.max(1, covers);
+    return (0, helpers_1.getCreditsFromCost)(totalUsd);
+}

package/lib/services/agent/covers/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./covers.schema";
+export * from "./coverPlanner";
+//# sourceMappingURL=index.d.ts.map

package/lib/services/agent/covers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/covers/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC"}

package/lib/services/agent/covers/index.js

@@ -0,0 +1,18 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./covers.schema"), exports);
+__exportStar(require("./coverPlanner"), exports);

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

@@ -40,6 +40,7 @@ export declare const CriticFindingSchema: z.ZodObject<{
         pass: "pass";
     }>;
     clipId: z.ZodOptional<z.ZodString>;
+    sceneIndex: z.ZodOptional<z.ZodNumber>;
     message: z.ZodString;
     suggestedAction: z.ZodOptional<z.ZodObject<{
         kind: z.ZodEnum<{
@@ -72,6 +73,7 @@ export declare const CriticReportSchema: z.ZodObject<{
             pass: "pass";
         }>;
         clipId: z.ZodOptional<z.ZodString>;
+        sceneIndex: z.ZodOptional<z.ZodNumber>;
         message: z.ZodString;
         suggestedAction: z.ZodOptional<z.ZodObject<{
             kind: z.ZodEnum<{
@@ -85,6 +87,14 @@ export declare const CriticReportSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type CriticReport = z.infer<typeof CriticReportSchema>;
+/**
+ * OD-6 — derive a scene index from a clip id. The executor and regen core mint
+ * clip ids as `scene-<n>-visual` / `scene-<n>-vo` / `scene-<n>-caption` and
+ * `clip-<n>` (and the cost-preflight uses bare `scene-<n>`). Matching the
+ * leading `scene-`/`clip-` token avoids accidentally picking up a trailing
+ * number elsewhere in the id. Returns undefined when no scene token is present.
+ */
+export declare function sceneIndexFromClipId(clipId: string | undefined): number | undefined;
 export interface CriticOptions {
     llm: LlmCaller;
     router?: ModelRouter;

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

@@ -1 +1 @@
-{"version":3,"file":"critic.d.ts","sourceRoot":"","sources":["../../../src/services/agent/critic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,oBAAoB;;;;EAAmC,CAAC;AACrE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;iBAmB9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAG7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,qBAAa,MAAM;IAGL,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAER,IAAI,EAAE,aAAa;IAI1C,MAAM,CACV,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,YAAY,CAAC;QAAC,IAAI,CAAC,EAAE,SAAS,CAAA;KAAO,GACtD,OAAO,CAAC,YAAY,CAAC;IAwExB,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,aAAa;CAKtB"}
+{"version":3,"file":"critic.d.ts","sourceRoot":"","sources":["../../../src/services/agent/critic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,oBAAoB;;;;EAAmC,CAAC;AACrE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;iBA4B9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAG7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAMnF;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,qBAAa,MAAM;IAGL,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAER,IAAI,EAAE,aAAa;IAI1C,MAAM,CACV,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,YAAY,CAAC;QAAC,IAAI,CAAC,EAAE,SAAS,CAAA;KAAO,GACtD,OAAO,CAAC,YAAY,CAAC;IAkFxB,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,aAAa;CAKtB"}

package/lib/services/agent/critic.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Critic = exports.CriticReportSchema = exports.CriticFindingSchema = exports.CriticSeveritySchema = void 0;
+exports.sceneIndexFromClipId = sceneIndexFromClipId;
 const zod_1 = require("zod");
 const modelRouter_1 = require("./modelRouter");
 const personas_1 = require("./personas");
@@ -31,6 +32,15 @@ exports.CriticFindingSchema = zod_1.z.object({
     severity: exports.CriticSeveritySchema,
     /** Which clip / scene the finding refers to, if any. */
     clipId: zod_1.z.string().optional(),
+    /**
+     * OD-6 — the scene this finding targets, derived deterministically from
+     * `clipId` after the LLM returns (see `sceneIndexFromClipId`). Lets both the
+     * inline panel and the full-page review match a finding to a storyboard tile
+     * by exact index instead of the fragile `clipId.includes(String(idx))` test
+     * (which mismatched "scene-3" against "scene-13"). Absent when the finding is
+     * project-wide (e.g. a `costVsTier` budget finding with no clip).
+     */
+    sceneIndex: zod_1.z.number().int().nonnegative().optional(),
     message: zod_1.z.string(),
     /** Optional self-heal hint the executor can act on. */
     suggestedAction: zod_1.z
@@ -44,6 +54,22 @@ exports.CriticReportSchema = zod_1.z.object({
     overall: exports.CriticSeveritySchema,
     findings: zod_1.z.array(exports.CriticFindingSchema),
 });
+/**
+ * OD-6 — derive a scene index from a clip id. The executor and regen core mint
+ * clip ids as `scene-<n>-visual` / `scene-<n>-vo` / `scene-<n>-caption` and
+ * `clip-<n>` (and the cost-preflight uses bare `scene-<n>`). Matching the
+ * leading `scene-`/`clip-` token avoids accidentally picking up a trailing
+ * number elsewhere in the id. Returns undefined when no scene token is present.
+ */
+function sceneIndexFromClipId(clipId) {
+    if (!clipId)
+        return undefined;
+    const m = /^(?:scene|clip)-(\d+)/.exec(clipId);
+    if (!m)
+        return undefined;
+    const n = Number.parseInt(m[1], 10);
+    return Number.isInteger(n) && n >= 0 ? n : undefined;
+}
 class Critic {
     constructor(opts) {
         this.opts = opts;
@@ -114,7 +140,17 @@ class Critic {
                 },
             ],
         });
-        return result.data;
+        // OD-6 — stamp each finding with a deterministic sceneIndex parsed from its
+        // clipId so the UI matches findings to scenes by exact index. The LLM is
+        // not asked to emit sceneIndex (it reliably references clipId), so we derive
+        // it here rather than trust a second model-supplied field.
+        return {
+            ...result.data,
+            findings: result.data.findings.map((f) => ({
+                ...f,
+                sceneIndex: f.sceneIndex ?? sceneIndexFromClipId(f.clipId),
+            })),
+        };
     }
     formatEmphasis(persona) {
         const emphasis = personas_1.PERSONA_PACKS[persona].criticEmphasis;

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

@@ -69,8 +69,8 @@ export declare const TextEditSchema: z.ZodObject<{
         fontSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodNumber]>>;
         sizePct: z.ZodOptional<z.ZodNumber>;
         weight: z.ZodOptional<z.ZodEnum<{
-            bold: "bold";
             regular: "regular";
+            bold: "bold";
             black: "black";
             medium: "medium";
         }>>;
@@ -164,8 +164,8 @@ export declare const EditRequestSchema: z.ZodObject<{
             fontSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodNumber]>>;
             sizePct: z.ZodOptional<z.ZodNumber>;
             weight: z.ZodOptional<z.ZodEnum<{
-                bold: "bold";
                 regular: "regular";
+                bold: "bold";
                 black: "black";
                 medium: "medium";
             }>>;
@@ -248,8 +248,8 @@ export declare function classifyCriticFindingsToEdit(args: {
     userIntentScope?: number[];
 }): EditRequest | null;
 /**
- * LLM-classifier prompt builder. The caller wires this through any LLMCaller
- * with structured-output support (Gateway / OpenAI / Gemini).
+ * LLM-classifier prompt builder. The caller wires this through any LlmCaller
+ * with structured-output support (Anthropic / OpenAI / Gemini).
  *
  * NOTE: we don't ship a default LLM caller here so the module stays
  * dependency-light — same pattern as planner / bibleBuilder. Tests can mock.

package/lib/services/agent/editClassifier.js

@@ -154,8 +154,8 @@ function classifyCriticFindingsToEdit(args) {
     };
 }
 /**
- * LLM-classifier prompt builder. The caller wires this through any LLMCaller
- * with structured-output support (Gateway / OpenAI / Gemini).
+ * LLM-classifier prompt builder. The caller wires this through any LlmCaller
+ * with structured-output support (Anthropic / OpenAI / Gemini).
  *
  * NOTE: we don't ship a default LLM caller here so the module stays
  * dependency-light — same pattern as planner / bibleBuilder. Tests can mock.

package/lib/services/agent/editExisting/editAssembler.d.ts

@@ -0,0 +1,78 @@
+import { Project } from "../../../schemas/project.schema";
+import { HighlightSegment } from "./editExisting.schema";
+/**
+ * Stream L · L-5 — pure assembly helpers for the edit-existing pipeline.
+ *
+ * Everything here is deterministic + IO-free so it can be unit/eval-tested
+ * without spend: segment clamping/ordering, caption-word remapping onto the
+ * cut timeline, and building the editable Project JSON (a single video track
+ * of source-trim clips, the same primitive the extend-chain layout uses).
+ */
+/** Drop kept spans shorter than this (sub-half-second slivers aren't usable cuts). */
+export declare const MIN_SEGMENT_MS = 400;
+/** A caption word on the OUTPUT (cut) timeline, ms from the highlight region start. */
+export interface RemappedCaptionWord {
+    word: string;
+    start: number;
+    end: number;
+}
+/** Word-level ASR input for caption remapping. */
+interface TimedWord {
+    text: string;
+    start: number;
+    end: number;
+}
+/** Total kept duration across segments, ms. */
+export declare function totalSegmentMs(segments: HighlightSegment[]): number;
+/**
+ * Clamp segments into [0, sourceDurationMs], sort chronologically, remove
+ * overlaps (a later segment that starts before the previous one ended is
+ * pushed forward; if that collapses it, it's dropped), and drop slivers below
+ * MIN_SEGMENT_MS. Idempotent — safe to run on already-clean input.
+ */
+export declare function clampSegments(segments: HighlightSegment[], sourceDurationMs: number): HighlightSegment[];
+/**
+ * Remap word timings from the SOURCE timeline onto the concatenated cut
+ * timeline (0-based at the start of the first kept segment). Only words that
+ * fall inside a kept segment survive; each is clamped to its segment and
+ * shifted by the cumulative offset of that segment in the output.
+ */
+export declare function remapCaptionWords(words: TimedWord[], segments: HighlightSegment[]): RemappedCaptionWord[];
+/** Width/height of the output frame (probed from the source by the worker). */
+export interface OutputSize {
+    width: number;
+    height: number;
+}
+/** An optional bumper clip (intro/outro) with its probed duration. */
+export interface BumperClip {
+    url: string;
+    durationMs: number;
+}
+export interface BuildEditProjectArgs {
+    projectId: string;
+    agentRunId: string;
+    name: string;
+    sourceVideoUrl: string;
+    /** Already clamped/ordered (run clampSegments first). */
+    segments: HighlightSegment[];
+    size: OutputSize;
+    aspect: "9:16" | "1:1" | "4:5" | "16:9";
+    fps?: number;
+    /** Caption words ALREADY remapped to the highlight region (0-based). */
+    captionWords?: RemappedCaptionWord[];
+    captionLanguage?: string;
+    intro?: BumperClip;
+    outro?: BumperClip;
+    /** ISO timestamp; injected so the function stays pure/testable. */
+    now: string;
+}
+/**
+ * Build an editable Project JSON for the re-edit. The highlight clips reference
+ * the ORIGINAL source URL with trims (lossless — the user can re-extend a cut
+ * in the editor), intro/outro reference their own URLs, and captions (if any)
+ * land on a dedicated track over the highlight region. Validated against
+ * ProjectSchema before returning, so the editor + renderer accept it as-is.
+ */
+export declare function buildEditProject(args: BuildEditProjectArgs): Project;
+export {};
+//# sourceMappingURL=editAssembler.d.ts.map

package/lib/services/agent/editExisting/editAssembler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editAssembler.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/editExisting/editAssembler.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EAGR,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;;;;;;GAOG;AAEH,sFAAsF;AACtF,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,uFAAuF;AACvF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,kDAAkD;AAClD,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,+CAA+C;AAC/C,wBAAgB,cAAc,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,MAAM,CAEnE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,gBAAgB,EAAE,EAC5B,gBAAgB,EAAE,MAAM,GACvB,gBAAgB,EAAE,CAmBpB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,EAAE,EAClB,QAAQ,EAAE,gBAAgB,EAAE,GAC3B,mBAAmB,EAAE,CAgBvB;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,YAAY,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACrC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;CACb;AAKD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAiGpE"}