vidspotai-shared 1.0.123 → 1.0.124

package/lib/schemas/brief.schema.d.ts

@@ -158,6 +158,39 @@ export declare const ReferenceLinkSchema: z.ZodObject<{
         transcriptExcerpt: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/**
+ * One Reference Library item the user @-mentioned in the composer (a built-in
+ * seed or one of their own refs), flattened across kinds by the frontend's
+ * `collectMentionedRefs` (wt-dev-frontend refs/tokens.ts — keep in sync).
+ *
+ * Unlike `references` (bare URLs), this carries what the item MEANS so the
+ * pipeline can honor it: characters / elements are pinned into the Visual
+ * Bible with their image (→ threaded as inputImageUrls on every scene they
+ * appear in, see mentionedRefs.ts), and style / effect / color / camera
+ * instructions are applied by the planner scene by scene.
+ */
+export declare const MentionedRefSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        element: "element";
+        motion: "motion";
+        color: "color";
+        style: "style";
+        character: "character";
+        effect: "effect";
+        camera: "camera";
+        voice: "voice";
+        model: "model";
+    }>;
+    slug: z.ZodString;
+    name: z.ZodString;
+    instruction: z.ZodOptional<z.ZodString>;
+    imageUrls: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    subkind: z.ZodOptional<z.ZodString>;
+    presetKey: z.ZodOptional<z.ZodString>;
+    swatches: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    voiceId: z.ZodOptional<z.ZodString>;
+    modelKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 export declare const VideoBriefSchema: z.ZodObject<{
     rawPrompt: z.ZodString;
     goal: z.ZodOptional<z.ZodString>;
@@ -278,6 +311,28 @@ export declare const VideoBriefSchema: z.ZodObject<{
             transcriptExcerpt: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
     }, z.core.$strip>>>;
+    mentionedRefs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            element: "element";
+            motion: "motion";
+            color: "color";
+            style: "style";
+            character: "character";
+            effect: "effect";
+            camera: "camera";
+            voice: "voice";
+            model: "model";
+        }>;
+        slug: z.ZodString;
+        name: z.ZodString;
+        instruction: z.ZodOptional<z.ZodString>;
+        imageUrls: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        subkind: z.ZodOptional<z.ZodString>;
+        presetKey: z.ZodOptional<z.ZodString>;
+        swatches: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        voiceId: z.ZodOptional<z.ZodString>;
+        modelKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     preferredModelKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
     tierBudget: z.ZodDefault<z.ZodEnum<{
         T0: "T0";
@@ -303,6 +358,7 @@ export type VoiceProfile = z.infer<typeof VoiceProfileSchema>;
 export type VoiceStyle = z.infer<typeof VoiceStyleSchema>;
 export type MusicProfile = z.infer<typeof MusicProfileSchema>;
 export type ReferenceLink = z.infer<typeof ReferenceLinkSchema>;
+export type MentionedRef = z.infer<typeof MentionedRefSchema>;
 export type VideoNiche = z.infer<typeof VideoNicheSchema>;
 export type Tone = z.infer<typeof ToneSchema>;
 export type HookStyle = z.infer<typeof HookStyleSchema>;

package/lib/schemas/brief.schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"brief.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/brief.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;EAc3B,CAAC;AAEH,eAAO,MAAM,UAAU;;;;;;;;;;EAUrB,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;EAQ1B,CAAC;AAEH,eAAO,MAAM,YAAY;;;;;EAAkD,CAAC;AAE5E;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,gBAAgB;;;;;;;EAA+C,CAAC;AAC7E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU,CASjE;AAKD,eAAO,MAAM,gBAAgB;;;;;;;;;;;EAW3B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkB7B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;iBAiB7B,CAAC;AAEH,eAAO,MAAM,YAAY;;;iBAKvB,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;iBAa9B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkG3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAC9C,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC"}
+{"version":3,"file":"brief.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/brief.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;EAc3B,CAAC;AAEH,eAAO,MAAM,UAAU;;;;;;;;;;EAUrB,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;EAQ1B,CAAC;AAEH,eAAO,MAAM,YAAY;;;;;EAAkD,CAAC;AAE5E;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,gBAAgB;;;;;;;EAA+C,CAAC;AAC7E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU,CASjE;AAKD,eAAO,MAAM,gBAAgB;;;;;;;;;;;EAW3B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkB7B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;iBAiB7B,CAAC;AAEH,eAAO,MAAM,YAAY;;;iBAKvB,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;iBAa9B,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;iBAe7B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwG3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAC9C,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC"}

package/lib/schemas/brief.schema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VideoBriefSchema = exports.ReferenceLinkSchema = exports.ClaimsSchema = exports.MusicProfileSchema = exports.VoiceProfileSchema = exports.VoiceStyleSchema = exports.LengthTierSchema = exports.PacingSchema = exports.HookStyleSchema = exports.ToneSchema = exports.VideoNicheSchema = void 0;
+exports.VideoBriefSchema = exports.MentionedRefSchema = exports.ReferenceLinkSchema = exports.ClaimsSchema = exports.MusicProfileSchema = exports.VoiceProfileSchema = exports.VoiceStyleSchema = exports.LengthTierSchema = exports.PacingSchema = exports.HookStyleSchema = exports.ToneSchema = exports.VideoNicheSchema = void 0;
 exports.deriveLengthTier = deriveLengthTier;
 const zod_1 = require("zod");
 const project_schema_1 = require("./project.schema");
@@ -163,6 +163,33 @@ exports.ReferenceLinkSchema = zod_1.z.object({
     })
         .optional(),
 });
+/**
+ * One Reference Library item the user @-mentioned in the composer (a built-in
+ * seed or one of their own refs), flattened across kinds by the frontend's
+ * `collectMentionedRefs` (wt-dev-frontend refs/tokens.ts — keep in sync).
+ *
+ * Unlike `references` (bare URLs), this carries what the item MEANS so the
+ * pipeline can honor it: characters / elements are pinned into the Visual
+ * Bible with their image (→ threaded as inputImageUrls on every scene they
+ * appear in, see mentionedRefs.ts), and style / effect / color / camera
+ * instructions are applied by the planner scene by scene.
+ */
+exports.MentionedRefSchema = zod_1.z.object({
+    kind: zod_1.z.enum(["character", "style", "color", "element", "effect", "camera", "motion", "voice", "model"]),
+    slug: zod_1.z.string().max(120),
+    name: zod_1.z.string().max(120),
+    /** The look / recipe / direction this ref stands for. */
+    instruction: zod_1.z.string().max(2000).optional(),
+    /** Absolute reference image URLs (character / style / element). */
+    imageUrls: zod_1.z.array(zod_1.z.string().url()).max(4).optional(),
+    /** Element sub-kind — "location" pins as an environment, else an object. */
+    subkind: zod_1.z.string().max(40).optional(),
+    /** Canonical model camera-control preset (camera / motion refs). */
+    presetKey: zod_1.z.string().max(60).optional(),
+    swatches: zod_1.z.array(zod_1.z.string().max(20)).max(12).optional(),
+    voiceId: zod_1.z.string().max(120).optional(),
+    modelKey: zod_1.z.string().max(120).optional(),
+});
 exports.VideoBriefSchema = zod_1.z.object({
     /** Free-text user request, kept verbatim. */
     rawPrompt: zod_1.z.string(),
@@ -199,6 +226,11 @@ exports.VideoBriefSchema = zod_1.z.object({
     cta: zod_1.z.string().optional(),
     claims: exports.ClaimsSchema.default({ allow: [], block: [] }),
     references: zod_1.z.array(exports.ReferenceLinkSchema).default([]),
+    /**
+     * Reference Library items the user @-mentioned (see MentionedRefSchema).
+     * Optional (not defaulted) so existing briefs and eval seeds are unchanged.
+     */
+    mentionedRefs: zod_1.z.array(exports.MentionedRefSchema).max(24).optional(),
     /**
      * Soft generation-model preference supplied by the user (via the composer's
      * "@Models" mention category). These are real catalog keys (e.g.

package/lib/services/agent/eval/types.d.ts

@@ -143,6 +143,28 @@ export declare const EvalBriefSchema: z.ZodObject<{
                 transcriptExcerpt: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
         }, z.core.$strip>>>;
+        mentionedRefs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                element: "element";
+                motion: "motion";
+                color: "color";
+                style: "style";
+                character: "character";
+                effect: "effect";
+                camera: "camera";
+                voice: "voice";
+                model: "model";
+            }>;
+            slug: z.ZodString;
+            name: z.ZodString;
+            instruction: z.ZodOptional<z.ZodString>;
+            imageUrls: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            subkind: z.ZodOptional<z.ZodString>;
+            presetKey: z.ZodOptional<z.ZodString>;
+            swatches: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            voiceId: z.ZodOptional<z.ZodString>;
+            modelKey: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
         preferredModelKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
         tierBudget: z.ZodDefault<z.ZodEnum<{
             T0: "T0";

package/lib/services/agent/eval/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/eval/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;GAUG;AAEH,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB;;;;;;;iBAQ3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAM1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;iBAY9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB;;;;iBAI5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;iBAQ1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/eval/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;GAUG;AAEH,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB;;;;;;;iBAQ3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAM1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;iBAY9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB;;;;iBAI5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;iBAQ1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

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

@@ -0,0 +1,20 @@
+import { VideoBrief } from "../../schemas/brief.schema";
+import { AgentVisualBible } from "../../schemas/videoPlan.schema";
+/**
+ * Pin every mentioned character / element into the bible. When the bible
+ * builder already made an entity for it (matched by name — the brief text
+ * names the ref, since tokens resolve to names), that entity keeps its id and
+ * gains the ref's image + description; otherwise a new entity is appended.
+ *
+ * Creates a bible when there is none (C0 briefs skip the builder, and the
+ * builder soft-fails to undefined) — a user who picked a character expects
+ * that face even on the cheapest tier, and the bible is how it gets there.
+ * Returns the input untouched when nothing is pinnable.
+ */
+export declare function pinMentionedRefsIntoBible(bible: AgentVisualBible | undefined, brief: VideoBrief): AgentVisualBible | undefined;
+/**
+ * Planner system-prompt section for the user's @-mentioned refs. Empty string
+ * when there are none (the common path adds zero tokens).
+ */
+export declare function buildMentionedRefsSection(brief: VideoBrief, bible: AgentVisualBible | null): string;
+//# sourceMappingURL=mentionedRefs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mentionedRefs.d.ts","sourceRoot":"","sources":["../../../src/services/agent/mentionedRefs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAe,MAAM,gCAAgC,CAAC;AAgD/E;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,gBAAgB,GAAG,SAAS,EACnC,KAAK,EAAE,UAAU,GAChB,gBAAgB,GAAG,SAAS,CAwC9B;AAID;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAC7B,MAAM,CAmER"}

package/lib/services/agent/mentionedRefs.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pinMentionedRefsIntoBible = pinMentionedRefsIntoBible;
+exports.buildMentionedRefsSection = buildMentionedRefsSection;
+const ID_PREFIX = {
+    characters: "CHAR",
+    objects: "OBJ",
+    environments: "ENV",
+};
+function entityKindFor(ref) {
+    if (ref.kind === "character")
+        return "characters";
+    if (ref.kind === "element")
+        return ref.subkind === "location" ? "environments" : "objects";
+    return null;
+}
+function nextId(entities, prefix) {
+    const max = entities.reduce((m, e) => {
+        const n = Number(e.id.split("_")[1]);
+        return Number.isFinite(n) && n > m ? n : m;
+    }, 0);
+    return `${prefix}_${max + 1}`;
+}
+const norm = (s) => s.trim().toLowerCase();
+/**
+ * Pin every mentioned character / element into the bible. When the bible
+ * builder already made an entity for it (matched by name — the brief text
+ * names the ref, since tokens resolve to names), that entity keeps its id and
+ * gains the ref's image + description; otherwise a new entity is appended.
+ *
+ * Creates a bible when there is none (C0 briefs skip the builder, and the
+ * builder soft-fails to undefined) — a user who picked a character expects
+ * that face even on the cheapest tier, and the bible is how it gets there.
+ * Returns the input untouched when nothing is pinnable.
+ */
+function pinMentionedRefsIntoBible(bible, brief) {
+    const pinnable = (brief.mentionedRefs ?? []).filter((r) => entityKindFor(r));
+    if (pinnable.length === 0)
+        return bible;
+    const tier = brief.consistencyTier ?? "C1";
+    const out = {
+        characters: [...(bible?.characters ?? [])],
+        objects: [...(bible?.objects ?? [])],
+        environments: [...(bible?.environments ?? [])],
+        consistencyTier: bible?.consistencyTier ?? (tier === "C0" ? "C1" : tier),
+    };
+    for (const ref of pinnable) {
+        const kind = entityKindFor(ref);
+        const list = out[kind];
+        const imageUrl = ref.imageUrls?.[0];
+        const description = ref.instruction?.trim() || ref.name;
+        const idx = list.findIndex((e) => norm(e.name) === norm(ref.name) || norm(e.name).includes(norm(ref.name)));
+        const existing = idx >= 0 ? list[idx] : undefined;
+        if (existing) {
+            list[idx] = {
+                ...existing,
+                name: ref.name,
+                // The ref's description matches its image; the builder's was
+                // inferred from the brief text alone.
+                description: imageUrl ? description : existing.description,
+                ...(imageUrl ? { referenceImageUrl: imageUrl } : {}),
+            };
+        }
+        else {
+            list.push({
+                id: nextId(list, ID_PREFIX[kind]),
+                name: ref.name,
+                description,
+                ...(imageUrl ? { referenceImageUrl: imageUrl } : {}),
+            });
+        }
+    }
+    return out;
+}
+const DIRECTION_KINDS = ["style", "effect", "color", "camera", "motion"];
+/**
+ * Planner system-prompt section for the user's @-mentioned refs. Empty string
+ * when there are none (the common path adds zero tokens).
+ */
+function buildMentionedRefsSection(brief, bible) {
+    const refs = brief.mentionedRefs ?? [];
+    if (refs.length === 0)
+        return "";
+    const allEntities = bible
+        ? [...bible.characters, ...bible.objects, ...bible.environments]
+        : [];
+    const pinned = refs
+        .filter((r) => entityKindFor(r))
+        .map((r) => ({ ref: r, entity: allEntities.find((e) => norm(e.name) === norm(r.name)) }))
+        .filter((p) => p.entity);
+    const by = (k) => refs.filter((r) => r.kind === k && (r.instruction || r.swatches?.length));
+    const lines = [
+        "",
+        "USER-SELECTED REFERENCES — the user explicitly picked these from their Reference Library by",
+        "@-mentioning them in the brief. They are requirements, not suggestions; the brief text names",
+        "each one where the user wants it.",
+    ];
+    if (pinned.length) {
+        lines.push("  Pinned subjects (each carries a reference image the generator receives):");
+        pinned.forEach(({ ref, entity }) => lines.push(`    ${entity.id} — ${ref.name} (${ref.kind === "character" ? "character" : ref.subkind ?? "element"})`));
+        lines.push("  Every scene that shows one of these MUST list its id in scene.bibleEntityIds — that is how", "  the reference image reaches the generator. A scene that omits the id renders a stranger.", "  Scenes showing a pinned subject must use an AI-generated strategy (not stock / user-asset).");
+    }
+    const styles = by("style");
+    if (styles.length) {
+        lines.push("  Visual style — apply to EVERY scene prompt, verbatim:");
+        styles.forEach((r) => lines.push(`    ${r.name}: ${r.instruction}`));
+    }
+    const colors = by("color");
+    if (colors.length) {
+        lines.push("  Color palette — grade every scene toward these colors:");
+        colors.forEach((r) => lines.push(`    ${r.name}: ${r.swatches?.join(", ") ?? r.instruction}`));
+    }
+    const effects = by("effect");
+    if (effects.length) {
+        lines.push("  Effects — add to every scene prompt unless the brief ties one to a specific moment:");
+        effects.forEach((r) => lines.push(`    ${r.name}: ${r.instruction}`));
+    }
+    const angles = by("camera");
+    if (angles.length) {
+        lines.push("  Camera angles / framing — use on the scene(s) the brief ties them to; if the brief doesn't say", "  where, use it on the opening scene. Put the framing text in scene.prompt:");
+        angles.forEach((r) => lines.push(`    ${r.name}: ${r.instruction}`));
+    }
+    const moves = by("motion");
+    if (moves.length) {
+        lines.push("  Camera moves — same placement rule as angles. Copy the direction into scene.prompt verbatim.", "  A still can't carry a camera move, so those scenes must use ai-image-to-video or", "  ai-text-to-video (never ai-image-static / stock-image-ken-burns):");
+        moves.forEach((r) => lines.push(`    ${r.name}: ${r.instruction}`));
+    }
+    return lines.join("\n");
+}

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

@@ -1 +1 @@
-{"version":3,"file":"plannerMessages.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/plannerMessages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAehF;;;;;GAKG;AAEH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,YAAY,GAAG,SAAS,EACjC,QAAQ,EAAE,cAAc,GAAG,IAAI,EAC/B,WAAW,EAAE,iBAAiB,GAAG,IAAI,EACrC,KAAK,EAAE,gBAAgB,GAAG,IAAI,EAC9B,UAAU,CAAC,EAAE,MAAM,EACnB,eAAe,UAAQ;;;;;;KA0JxB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAiChE"}
+{"version":3,"file":"plannerMessages.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/plannerMessages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAgBhF;;;;;GAKG;AAEH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,YAAY,GAAG,SAAS,EACjC,QAAQ,EAAE,cAAc,GAAG,IAAI,EAC/B,WAAW,EAAE,iBAAiB,GAAG,IAAI,EACrC,KAAK,EAAE,gBAAgB,GAAG,IAAI,EAC9B,UAAU,CAAC,EAAE,MAAM,EACnB,eAAe,UAAQ;;;;;;KA4JxB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAiChE"}

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

@@ -7,6 +7,7 @@ const modelQualityNotes_1 = require("../modelQualityNotes");
 const outputLanguage_1 = require("../../translation/outputLanguage");
 const promptSections_1 = require("./promptSections");
 const structuralRules_1 = require("./structuralRules");
+const mentionedRefs_1 = require("../mentionedRefs");
 /**
  * Planner prompt assembly + the web-research heuristic. Pure functions (no LLM
  * call, no class state) so the Planner class stays focused on the
@@ -32,6 +33,7 @@ function buildPlannerMessages(brief, persona, brandKit, styleMemory, bible, last
     const brandKitSection = (0, promptSections_1.buildBrandKitSection)(brandKit);
     const styleMemorySection = (0, promptSections_1.buildStyleMemorySection)(styleMemory);
     const bibleSection = (0, promptSections_1.buildBibleSection)(bible);
+    const mentionedRefsSection = (0, mentionedRefs_1.buildMentionedRefsSection)(brief, bible);
     const modelCatalogSection = (0, promptSections_1.buildModelCatalogSection)();
     const preferredModelsSection = (0, promptSections_1.buildPreferredModelsSection)(brief.preferredModelKeys);
     const videoStrategySection = (0, promptSections_1.buildVideoStrategySection)(brief.videoStrategy);
@@ -127,6 +129,7 @@ function buildPlannerMessages(brief, persona, brandKit, styleMemory, bible, last
         personaSection,
         structuralRulesSection,
         bibleSection,
+        mentionedRefsSection,
         brandKitSection,
         styleMemorySection,
         "",

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

@@ -1 +1 @@
-{"version":3,"file":"promptSections.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/promptSections.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAShF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAGjE;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,GACnD,MAAM,CAkCR;AAED,wBAAgB,wBAAwB,IAAI,MAAM,CAWjD;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,kBAAkB,EAAE,MAAM,EAAE,GAAG,SAAS,GACvC,MAAM,CAmCR;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,GAAG,MAAM,CAgC5E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,MAAM,CAqCxE;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,GAAG,MAAM,CAsBhF"}
+{"version":3,"file":"promptSections.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/promptSections.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAShF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAGjE;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,GACnD,MAAM,CAkCR;AAED,wBAAgB,wBAAwB,IAAI,MAAM,CAWjD;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,kBAAkB,EAAE,MAAM,EAAE,GAAG,SAAS,GACvC,MAAM,CAmCR;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,GAAG,MAAM,CAgC5E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,MAAM,CA6CxE;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,GAAG,MAAM,CAsBhF"}

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

@@ -181,6 +181,11 @@ function buildBibleSection(bible) {
     const environments = bible.environments ?? [];
     if (!characters.length && !objects.length && !environments.length)
         return "";
+    // Entities pinned from the user's @-mentioned refs arrive with an image even
+    // below C2 (see mentionedRefs.ts).
+    const withImages = [...characters, ...objects, ...environments]
+        .filter((e) => e.referenceImageUrl)
+        .map((e) => e.id);
     const formatEntity = (e) => `    ${e.id} — ${e.name}: ${e.description}`;
     const lines = [
         "",
@@ -200,7 +205,9 @@ function buildBibleSection(bible) {
     }
     lines.push("", "Bible usage contract (hard rule):", "  - For every scene, set scene.bibleEntityIds to the list of entity ids that appear in that scene (e.g. [\"CHAR_1\", \"OBJ_1\"]).", "  - For every entity in scene.bibleEntityIds, re-state its description verbatim in scene.prompt. Do NOT paraphrase — copy the exact words from the bible. Different scenes referencing the same entity must use IDENTICAL description text.", "  - characterAnchorSceneIndex (AG-11) is still useful as a backup signal but the bible is primary. If both are set, both should agree.", bible.consistencyTier === "C2"
         ? "  - C2 note: entities will additionally get pre-rendered reference images (executor threads them as inputImageUrls on image-gen calls). Your descriptions seed those reference images, so be visually specific."
-        : "  - C1 note: descriptions are the ONLY consistency signal — no reference images. Be as visually specific as possible.");
+        : withImages.length
+            ? `  - C1 note: ${withImages.join(", ")} carry user-supplied reference images (threaded as inputImageUrls on every scene that lists them); for the rest, descriptions are the only consistency signal — be as visually specific as possible.`
+            : "  - C1 note: descriptions are the ONLY consistency signal — no reference images. Be as visually specific as possible.");
     return lines.join("\n");
 }
 function buildStyleMemorySection(memory) {

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

@@ -1 +1 @@
-{"version":3,"file":"runPlanning.d.ts","sourceRoot":"","sources":["../../../src/services/agent/runPlanning.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAoB,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,SAAS,EACV,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAwBnD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,cAAc,GAAG,IAAI,GAC9B,MAAM,CAUR;AAiED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC;IAClC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,GAAG,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CACtC,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAoBhF;AAED,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IAC7D,OAAO,EAAE,gBAAgB,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;CACjB,GAAG,IAAI,CAkCP;AAED,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,IAAI,EAAE,SAAS,CAAC;IAChB,6EAA6E;IAC7E,KAAK,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACpC,wGAAwG;IACxG,UAAU,EAAE,OAAO,CAAC;IACpB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,8CAA8C;IAC9C,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACtC,qEAAqE;IACrE,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAClC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CACtC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAuD7B"}
+{"version":3,"file":"runPlanning.d.ts","sourceRoot":"","sources":["../../../src/services/agent/runPlanning.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAoB,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,SAAS,EACV,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAyBnD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,cAAc,GAAG,IAAI,GAC9B,MAAM,CAaR;AAiED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC;IAClC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,GAAG,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CACtC,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAuBhF;AAED,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IAC7D,OAAO,EAAE,gBAAgB,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;CACjB,GAAG,IAAI,CAkCP;AAED,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,IAAI,EAAE,SAAS,CAAC;IAChB,6EAA6E;IAC7E,KAAK,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACpC,wGAAwG;IACxG,UAAU,EAAE,OAAO,CAAC;IACpB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,8CAA8C;IAC9C,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACtC,qEAAqE;IACrE,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAClC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CACtC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAuD7B"}

package/lib/services/agent/runPlanning.js

@@ -11,6 +11,7 @@ const brief_schema_1 = require("../../schemas/brief.schema");
 const llmCallerRegistry_1 = require("./llmCallerRegistry");
 const bibleBuilder_1 = require("./bibleBuilder");
 const bibleImageVision_1 = require("./bibleImageVision");
+const mentionedRefs_1 = require("./mentionedRefs");
 const planner_1 = require("./planner");
 const musicSelect_1 = require("./musicSelect");
 const beatSnap_1 = require("./beatSnap");
@@ -37,7 +38,10 @@ const isoNow = () => new Date().toISOString();
  * we never cache nothing as something.
  */
 function computeBibleCacheKey(brief, brandKit) {
-    if ((brief.consistencyTier ?? "C1") === "C0")
+    // C0 builds no bible — unless the user @-mentioned a character/element,
+    // which gets pinned into one (see pinMentionedRefsIntoBible).
+    const pins = (brief.mentionedRefs ?? []).some((r) => r.kind === "character" || r.kind === "element");
+    if ((brief.consistencyTier ?? "C1") === "C0" && !pins)
         return "";
     return (0, crypto_1.createHash)("sha256")
         .update(JSON.stringify({
@@ -125,8 +129,11 @@ async function getBibleWithCache(args) {
         persona: args.persona,
         brandKit: args.brandKit,
     });
+    // Pin @-mentioned characters/elements (with their reference images) before
+    // the vision pass, so their descriptions get re-read from the image too.
+    const pinned = (0, mentionedRefs_1.pinMentionedRefsIntoBible)(built, args.brief);
     args.onStage?.("aligning_bible_with_images");
-    const bible = await safeBibleImageVision(built);
+    const bible = await safeBibleImageVision(pinned);
     return { bible, fresh: true, key };
 }
 /**

package/lib/services/agent/tools/generateScript.tool.d.ts

@@ -140,6 +140,28 @@ declare const InputSchema: z.ZodObject<{
                 transcriptExcerpt: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
         }, z.core.$strip>>>;
+        mentionedRefs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                element: "element";
+                motion: "motion";
+                color: "color";
+                style: "style";
+                character: "character";
+                effect: "effect";
+                camera: "camera";
+                voice: "voice";
+                model: "model";
+            }>;
+            slug: z.ZodString;
+            name: z.ZodString;
+            instruction: z.ZodOptional<z.ZodString>;
+            imageUrls: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            subkind: z.ZodOptional<z.ZodString>;
+            presetKey: z.ZodOptional<z.ZodString>;
+            swatches: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            voiceId: z.ZodOptional<z.ZodString>;
+            modelKey: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
         preferredModelKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
         tierBudget: z.ZodDefault<z.ZodEnum<{
             T0: "T0";

package/lib/services/agent/tools/generateScript.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateScript.tool.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/tools/generateScript.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAoB,MAAM,+BAA+B,CAAC;AAC7E,OAAO,EAAE,MAAM,EAAgB,MAAM,mCAAmC,CAAC;AACzE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAIzC,OAAO,EAAgB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAG/D;;;;;;;;;;;;;;;GAeG;AAEH,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAUf,CAAC;AAeH,QAAA,MAAM,YAAY;;;;;;;;iBAGhB,CAAC;AAEH;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,UAAU,EACjB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAoEtD;AAED,eAAO,MAAM,kBAAkB,EAAE,cAAc,CAC7C,OAAO,WAAW,EAClB,OAAO,YAAY,CAcpB,CAAC"}
+{"version":3,"file":"generateScript.tool.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/tools/generateScript.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAoB,MAAM,+BAA+B,CAAC;AAC7E,OAAO,EAAE,MAAM,EAAgB,MAAM,mCAAmC,CAAC;AACzE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAIzC,OAAO,EAAgB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAG/D;;;;;;;;;;;;;;;GAeG;AAEH,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAUf,CAAC;AAeH,QAAA,MAAM,YAAY;;;;;;;;iBAGhB,CAAC;AAEH;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,UAAU,EACjB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAoEtD;AAED,eAAO,MAAM,kBAAkB,EAAE,cAAc,CAC7C,OAAO,WAAW,EAClB,OAAO,YAAY,CAcpB,CAAC"}

package/lib/services/agent/tools/planVideo.tool.d.ts

@@ -123,6 +123,28 @@ declare const InputSchema: z.ZodObject<{
                 transcriptExcerpt: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
         }, z.core.$strip>>>;
+        mentionedRefs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                element: "element";
+                motion: "motion";
+                color: "color";
+                style: "style";
+                character: "character";
+                effect: "effect";
+                camera: "camera";
+                voice: "voice";
+                model: "model";
+            }>;
+            slug: z.ZodString;
+            name: z.ZodString;
+            instruction: z.ZodOptional<z.ZodString>;
+            imageUrls: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            subkind: z.ZodOptional<z.ZodString>;
+            presetKey: z.ZodOptional<z.ZodString>;
+            swatches: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            voiceId: z.ZodOptional<z.ZodString>;
+            modelKey: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
         preferredModelKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
         tierBudget: z.ZodDefault<z.ZodEnum<{
             T0: "T0";

package/lib/services/agent/tools/planVideo.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"planVideo.tool.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/tools/planVideo.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAgB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAQ/D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAExD;AAED,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAIf,CAAC;AAEH,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAEhB,CAAC;AAEH,eAAO,MAAM,aAAa,EAAE,cAAc,CACxC,OAAO,WAAW,EAClB,OAAO,YAAY,CAuBpB,CAAC"}
+{"version":3,"file":"planVideo.tool.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/tools/planVideo.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAgB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAQ/D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAExD;AAED,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAIf,CAAC;AAEH,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAEhB,CAAC;AAEH,eAAO,MAAM,aAAa,EAAE,cAAc,CACxC,OAAO,WAAW,EAClB,OAAO,YAAY,CAuBpB,CAAC"}

package/lib/services/translation/translation.service.d.ts

@@ -28,9 +28,17 @@ import { ELANGUAGE_CODE, IDetectLang } from "../../globals/types";
  */
 export declare const TRANSLATION_FAILED = "TRANSLATION_FAILED";
 /**
- * Translate `text` from → to (default English). Primary CF first (with a couple
- * of quick retries), then a cheap LLM. Throws Error(TRANSLATION_FAILED) only if
- * BOTH layers fail; `.cause` carries the last error.
+ * Split `text` into pieces of at most `max` chars whose concatenation is
+ * exactly `text`. Breaks at sentence / line ends where possible; a single
+ * over-long sentence is hard-split at the last whitespace before `max`.
+ */
+export declare function splitForTranslation(text: string, max?: number): string[];
+/**
+ * Translate `text` from → to (default English). Long text is split into
+ * chunks translated in parallel (see CHUNK_MAX_CHARS); each chunk goes
+ * primary CF first (with a quick retry), then a cheap LLM. Throws
+ * Error(TRANSLATION_FAILED) only if BOTH layers fail for some chunk; `.cause`
+ * carries the last error.
  */
 declare function translate(text: string, from: ELANGUAGE_CODE, to?: ELANGUAGE_CODE, version?: "v1" | "v2"): Promise<string>;
 /**

package/lib/services/translation/translation.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"translation.service.d.ts","sourceRoot":"","sources":["../../../src/services/translation/translation.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGlE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAmJvD;;;;GAIG;AACH,iBAAe,SAAS,CACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,cAAc,EACpB,EAAE,GAAE,cAAkC,EACtC,OAAO,GAAE,IAAI,GAAG,IAAW,GAC1B,OAAO,CAAC,MAAM,CAAC,CAsCjB;AAqDD;;;;;;;;;;;;;;GAcG;AACH,iBAAe,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA8ChE;AAOD,eAAO,MAAM,kBAAkB;;;CAG9B,CAAC;AAGF,qDAAqD;AACrD,eAAO,MAAM,qBAAqB,kBAAY,CAAC;AAC/C,0DAA0D;AAC1D,eAAO,MAAM,UAAU,uBAAiB,CAAC"}
+{"version":3,"file":"translation.service.d.ts","sourceRoot":"","sources":["../../../src/services/translation/translation.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGlE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAiDvD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAkB,GAAG,MAAM,EAAE,CA8BjF;AA4ID;;;;;;GAMG;AACH,iBAAe,SAAS,CACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,cAAc,EACpB,EAAE,GAAE,cAAkC,EACtC,OAAO,GAAE,IAAI,GAAG,IAAW,GAC1B,OAAO,CAAC,MAAM,CAAC,CAiBjB;AAiGD;;;;;;;;;;;;;;GAcG;AACH,iBAAe,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA8ChE;AAOD,eAAO,MAAM,kBAAkB;;;CAG9B,CAAC;AAGF,qDAAqD;AACrD,eAAO,MAAM,qBAAqB,kBAAY,CAAC;AAC/C,0DAA0D;AAC1D,eAAO,MAAM,UAAU,uBAAiB,CAAC"}

package/lib/services/translation/translation.service.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectLang = exports.getTranslationWrapper = exports.translationService = exports.TRANSLATION_FAILED = void 0;
+exports.splitForTranslation = splitForTranslation;
 const axios_1 = __importDefault(require("axios"));
 const enums_1 = require("../../globals/aiModels/enums");
 const types_1 = require("../../globals/types");
@@ -90,6 +91,76 @@ const PRIMARY_MAX_ATTEMPTS = 2;
 // handshake) gets a second, fresh try instead of being fatal.
 const FALLBACK_ATTEMPT_TIMEOUT_MS = 8000;
 const FALLBACK_MAX_ATTEMPTS = 2;
+// 2026-09-28 ROOT CAUSE of the recurring "BOTH primary and LLM fallback"
+// Slack alerts: fixed timeouts vs. LONG prompts. 14 days of prod logs: every
+// sampled both-layer failure was a 483–2523-word prompt; every fast success
+// was ≤~100 words. Neither upstream was down — a healthy gpt-4o-mini call on
+// a real failed 726-word `id` prompt took 17s (1141 output tokens), so an 8s
+// attempt could never win, and retrying just repeated the doomed call.
+//
+// Fix: split long text on paragraph/sentence boundaries into ≤CHUNK_MAX_CHARS
+// pieces and translate them IN PARALLEL, so wall time tracks one chunk rather
+// than the whole prompt. Per-attempt timeouts also scale with chunk length
+// (base + per-char) so a max-size chunk has real headroom.
+const CHUNK_MAX_CHARS = 1200;
+const CHUNK_CONCURRENCY = 6;
+const PRIMARY_TIMEOUT_PER_CHAR_MS = 2;
+const FALLBACK_TIMEOUT_PER_CHAR_MS = 5;
+function primaryTimeoutFor(text) {
+    return PRIMARY_TIMEOUT_MS + text.length * PRIMARY_TIMEOUT_PER_CHAR_MS;
+}
+function fallbackTimeoutFor(text) {
+    return FALLBACK_ATTEMPT_TIMEOUT_MS + text.length * FALLBACK_TIMEOUT_PER_CHAR_MS;
+}
+/**
+ * Split `text` into pieces of at most `max` chars whose concatenation is
+ * exactly `text`. Breaks at sentence / line ends where possible; a single
+ * over-long sentence is hard-split at the last whitespace before `max`.
+ */
+function splitForTranslation(text, max = CHUNK_MAX_CHARS) {
+    if (text.length <= max)
+        return [text];
+    // Sentence-ish units, each carrying its trailing whitespace/newlines.
+    const units = text.match(/[^.!?。！？\n]*(?:[.!?。！？]+["'”’)\]]*|\n|$)\s*/g) ?? [text];
+    const pieces = [];
+    for (const unit of units) {
+        if (!unit)
+            continue;
+        let rest = unit;
+        while (rest.length > max) {
+            const cut = rest.lastIndexOf(" ", max);
+            const at = cut > max / 2 ? cut + 1 : max;
+            pieces.push(rest.slice(0, at));
+            rest = rest.slice(at);
+        }
+        if (rest)
+            pieces.push(rest);
+    }
+    const chunks = [];
+    let cur = "";
+    for (const p of pieces) {
+        if (cur && cur.length + p.length > max) {
+            chunks.push(cur);
+            cur = "";
+        }
+        cur += p;
+    }
+    if (cur)
+        chunks.push(cur);
+    return chunks;
+}
+/** Runs `fn` over `items` with at most `limit` in flight; preserves order. */
+async function mapWithConcurrency(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        for (let i = next++; i < items.length; i = next++) {
+            out[i] = await fn(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return out;
+}
 // gpt-4o-mini: cheap (~$0.15/1M in, $0.60/1M out → fractions of a cent per
 // prompt), reliable, and independent of the Google video quota. Swap here if a
 // cheaper effective model becomes available.
@@ -105,7 +176,7 @@ function languageLabel(code) {
 async function callPrimaryTranslate(text, from, to, version) {
     const res = await axios_1.default.post(`${PRIMARY_BASE}/translate`, { text, from, to, version }, {
         headers: { "internal-key": process.env.TRANSLATION_SERVICE_KEY || "" },
-        timeout: PRIMARY_TIMEOUT_MS,
+        timeout: primaryTimeoutFor(text),
     });
     const translated = res.data?.translated;
     if (typeof translated !== "string" || !translated.length) {
@@ -171,7 +242,7 @@ async function callLlmTranslate(text, from, to) {
     let lastErr;
     for (let attempt = 1; attempt <= FALLBACK_MAX_ATTEMPTS; attempt++) {
         try {
-            return await withTimeout(callLlmTranslateOnce(text, from, to), FALLBACK_ATTEMPT_TIMEOUT_MS, "LLM fallback");
+            return await withTimeout(callLlmTranslateOnce(text, from, to), fallbackTimeoutFor(text), "LLM fallback");
         }
         catch (err) {
             lastErr = err;
@@ -180,13 +251,33 @@ async function callLlmTranslate(text, from, to) {
     throw lastErr;
 }
 /**
- * Translate `text` from → to (default English). Primary CF first (with a couple
- * of quick retries), then a cheap LLM. Throws Error(TRANSLATION_FAILED) only if
- * BOTH layers fail; `.cause` carries the last error.
+ * Translate `text` from → to (default English). Long text is split into
+ * chunks translated in parallel (see CHUNK_MAX_CHARS); each chunk goes
+ * primary CF first (with a quick retry), then a cheap LLM. Throws
+ * Error(TRANSLATION_FAILED) only if BOTH layers fail for some chunk; `.cause`
+ * carries the last error.
  */
 async function translate(text, from, to = types_1.ELANGUAGE_CODE.en, version = "v2") {
     if (!text || !text.trim())
         return text;
+    const chunks = splitForTranslation(text);
+    if (chunks.length === 1)
+        return translateChunk(text, from, to, version);
+    const translated = await mapWithConcurrency(chunks, CHUNK_CONCURRENCY, async (chunk) => {
+        // Translate the trimmed core and re-attach the chunk's own boundary
+        // whitespace — both layers trim, which would otherwise glue sentences
+        // together or drop paragraph breaks at chunk seams.
+        const lead = chunk.match(/^\s*/)?.[0] ?? "";
+        const trail = chunk.match(/\s*$/)?.[0] ?? "";
+        const core = chunk.trim();
+        if (!core)
+            return chunk;
+        return lead + (await translateChunk(core, from, to, version)).trim() + trail;
+    });
+    return translated.join("");
+}
+/** One chunk through primary → LLM fallback. */
+async function translateChunk(text, from, to, version) {
     // ── Layer 1: primary Cloud Function ──────────────────────────────────────
     let primaryErr;
     for (let attempt = 1; attempt <= PRIMARY_MAX_ATTEMPTS; attempt++) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vidspotai-shared",
-  "version": "1.0.123",
+  "version": "1.0.124",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "exports": {