vidspotai-shared 1.0.95 → 1.0.96

package/lib/services/demo/demoRevisePrompt.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDemoReviseSystemPrompt = buildDemoReviseSystemPrompt;
+exports.buildDemoReviseUserText = buildDemoReviseUserText;
+const demoAuthorPrompt_1 = require("./demoAuthorPrompt");
+/**
+ * Prompt construction for the "request a change" spec reviser (plan §2.6 result
+ * step / Phase 9). The reviser is the structured re-edit path: instead of
+ * re-running the wizard from scratch, the user types a natural-language change
+ * ("make the intro punchier", "swap scene 3 for a pricing beat", "use a darker
+ * mood") and we mutate the EXISTING, already-rendered DemoSpec, then re-render.
+ *
+ * We reuse the author's system prompt verbatim — it carries the full scene
+ * vocabulary, the §2.6 style taxonomy, and the HARD RULES (never invent a
+ * screenshot URL, honor brand colors, honor wizard pins). A short REVISION MODE
+ * preamble reframes the task from "author from facts" to "apply this change to
+ * the given spec", and the user turn carries the current spec as JSON plus the
+ * change request. The same deterministic normalize pass then re-enforces every
+ * invariant, so a revision can never drift outside the contract the engine
+ * renders (real screenshot URLs, brand colors, duration budget, schema-validity).
+ */
+/** Preamble that turns the author prompt into a spec-editing prompt. */
+const REVISION_MODE = `REVISION MODE — you are EDITING an existing DemoSpec, not authoring from scratch.
+The user already has a rendered video from the current spec (provided below as JSON) and is requesting a specific change. Apply ONLY what the change asks for and keep everything else intact:
+- Preserve scene ids, order, copy, and durations that the change does not touch — a stable id lets narration + timing carry over.
+- Make the SMALLEST edit that satisfies the request. Do not re-theme, re-order, or rewrite scenes the user didn't ask you to.
+- If the change is impossible within the scene vocabulary or the HARD RULES (e.g. "use this screenshot" for a URL not in the available list), get as close as the rules allow rather than inventing anything.
+- Keep honoring the LOCKED wizard axes and brand colors exactly as in the current spec.
+- generatedAssets entries carrying status:"ready" + url are ALREADY PAID FOR — keep them (and the scene URLs that came from them) verbatim when their beats survive the change. Declare a NEW generatedAssets entry (cited as "gen://<id>") only when the change genuinely needs media that doesn't exist yet.
+Return the COMPLETE revised DemoSpec via the tool (not a diff) — every scene, including the untouched ones.`;
+/**
+ * Build the reviser system prompt: the full author prompt (vocabulary + rules +
+ * quality bar) plus the REVISION MODE preamble. `allowCustomScenes` threads the
+ * worker's `DEMO_CODEGEN_ENABLED` gate exactly as the author does, so a revision
+ * can only introduce a `custom` scene when the codegen agent that fills it is on.
+ */
+function buildDemoReviseSystemPrompt(opts = {}) {
+    return `${(0, demoAuthorPrompt_1.buildDemoAuthorSystemPrompt)(opts)}\n\n${REVISION_MODE}`;
+}
+/**
+ * The images the revised spec may cite — same verbatim-only rule as the author.
+ * `productUrls` are the project's persisted screenshots; `referenceUrls` are
+ * images the user attached to THIS change. Both are citable (copied verbatim onto
+ * screenshotUrl/screenshotUrls) and both are attached as vision, but references
+ * carry the extra meaning that the user is pointing at them for this edit — so
+ * the model should use them as the visual target (match this look/layout, or show
+ * this exact UI). If there are no images of either kind, deviceMockup is off.
+ */
+function citableSection(productUrls, referenceUrls) {
+    const hasProduct = !!productUrls?.length;
+    const hasRef = !!referenceUrls?.length;
+    if (!hasProduct && !hasRef) {
+        return `Available screenshots: NONE. Do not introduce deviceMockup; author any new product UI as fully synthetic featureShowcase surfaces.`;
+    }
+    const blocks = [];
+    if (hasProduct) {
+        const lines = productUrls.map((u, i) => `  [${i}] ${u}`).join("\n");
+        blocks.push(`Available product screenshots (${productUrls.length}) — URLs you may use, copied verbatim, on screenshotUrl/screenshotUrls:\n${lines}`);
+    }
+    if (hasRef) {
+        const lines = referenceUrls.map((u, i) => `  [R${i}] ${u}`).join("\n");
+        blocks.push(`REFERENCE IMAGES the user attached WITH THIS CHANGE (${referenceUrls.length}) — this is the look/layout/screenshot they are pointing at for the requested edit. Use them as the visual target: match the design, layout, or content they show. You MAY also cite these URLs verbatim on screenshotUrl/screenshotUrls (exactly like product screenshots) when the change asks to SHOW one of them:\n${lines}`);
+    }
+    blocks.push("All of the above images are attached to this message for you to see.");
+    return blocks.join("\n\n");
+}
+/**
+ * Build the reviser user turn: the current spec (as JSON) + the enumerated
+ * citable images (product screenshots + the user's per-edit reference images) +
+ * the user's natural-language change request. Images are attached separately as
+ * `imageUrls` (mirrors the author).
+ */
+function buildDemoReviseUserText(spec, instruction, productScreenshotUrls, referenceImageUrls) {
+    return [
+        "CURRENT DemoSpec (edit this — return the full revised spec):",
+        "```json",
+        JSON.stringify(spec, null, 2),
+        "```",
+        "",
+        citableSection(productScreenshotUrls, referenceImageUrls),
+        "",
+        "CHANGE REQUESTED by the user:",
+        instruction.trim(),
+    ].join("\n");
+}

package/lib/services/demo/demoReviser.d.ts

@@ -0,0 +1,63 @@
+import { DemoSpec } from "../../schemas/demoSpec.schema";
+import { LlmCaller } from "../agent/llmCaller";
+import { ModelChoice, ModelRouter } from "../agent/modelRouter";
+import { DemoAuthorInput } from "./demoAuthorPrompt";
+import { NormalizeResult } from "./demoAuthorNormalize";
+export interface DemoReviseDeps {
+    /**
+     * Normalize context — the SAME resolved inputs the spec was authored from
+     * (product name, resolved brand, the real screenshot URL set, wizard answers).
+     * The worker reconstructs this from the persisted project (no re-gather), so
+     * the normalize pass re-enforces exactly the invariants the original author
+     * had to (screenshot sanitation, brand-color forcing, wizard pins).
+     */
+    context: DemoAuthorInput;
+    /** LLM caller. Defaults to the host-wired dispatcher. */
+    llm?: LlmCaller;
+    /** Model router. Defaults to DEFAULT_MODEL_ROUTING. */
+    router?: ModelRouter;
+    /** Route the reviser to the premium tier (Opus) for higher-fidelity edits. */
+    premium?: boolean;
+    /** Sampling temperature. Lower than authoring — a revision should be conservative. */
+    temperature?: number;
+    /** Max output tokens — a full DemoSpec with rich scenes can be large. */
+    maxTokens?: number;
+    /**
+     * Allow the reviser to introduce Layer-B `custom` scenes. Threaded from the
+     * worker's `DEMO_CODEGEN_ENABLED` gate; default false so a revision never
+     * emits a `custom` scene the pipeline can't fill.
+     */
+    allowCustomScenes?: boolean;
+    /**
+     * Allow the revision to commission AI-generated media (`generatedAssets` +
+     * `gen://` refs). Default true; false only under DEMO_GEN_ASSETS_DISABLED.
+     */
+    allowGeneratedAssets?: boolean;
+    /**
+     * Reference images the user attached to THIS change (public URLs) — e.g. a
+     * screenshot of the look/layout they mean, or a UI they want shown. Distinct
+     * from the persisted product screenshots in `context`: they are the user's
+     * intent for this one edit, so they get first claim on the vision budget and
+     * are added to the citable whitelist (the model may match them or cite them
+     * verbatim), but they are NOT persisted into the project's screenshot set.
+     */
+    referenceImageUrls?: string[];
+}
+export interface DemoReviseResult extends NormalizeResult {
+    /** Model that produced the revised spec (primary or fallback). */
+    modelUsed: ModelChoice;
+    usedFallback?: boolean;
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+    };
+}
+/**
+ * Apply a natural-language change to an existing DemoSpec. Pure orchestration:
+ * build the reviser prompt (current spec as JSON + the change), re-attach the
+ * screenshots as vision, call `.structured(DemoSpec)`, then normalize. Throws if
+ * the caller is unconfigured or the model returns an unparseable / scene-less
+ * spec (the normalize pass is the last guard).
+ */
+export declare function reviseDemoSpec(currentSpec: DemoSpec, instruction: string, deps: DemoReviseDeps): Promise<DemoReviseResult>;
+//# sourceMappingURL=demoReviser.d.ts.map

package/lib/services/demo/demoReviser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demoReviser.d.ts","sourceRoot":"","sources":["../../../src/services/demo/demoReviser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAkB,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAKrD,OAAO,EAAE,eAAe,EAAqB,MAAM,uBAAuB,CAAC;AAoB3E,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,OAAO,EAAE,eAAe,CAAC;IACzB,yDAAyD;IACzD,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,uDAAuD;IACvD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,kEAAkE;IAClE,SAAS,EAAE,WAAW,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9D;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,QAAQ,EACrB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,gBAAgB,CAAC,CA+D3B"}

package/lib/services/demo/demoReviser.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reviseDemoSpec = reviseDemoSpec;
+const demoSpec_schema_1 = require("../../schemas/demoSpec.schema");
+const llmCallerRegistry_1 = require("../agent/llmCallerRegistry");
+const modelRouter_1 = require("../agent/modelRouter");
+const demoRevisePrompt_1 = require("./demoRevisePrompt");
+const demoAuthorNormalize_1 = require("./demoAuthorNormalize");
+/**
+ * DemoSpec reviser — the "request a change" re-edit path (plan §2.6 / Phase 9).
+ *
+ * ONE Claude `.structured<DemoSpec>()` call takes the CURRENT (already-rendered)
+ * spec + a natural-language change request and returns the full revised spec,
+ * which the same deterministic normalize pass re-hardens (real screenshot URLs,
+ * brand colors, duration budget, schema-validity). Structurally identical to
+ * `authorDemoSpec` — provider-agnostic (injected `LlmCaller`), model-routed —
+ * but seeded with the existing spec instead of authoring from raw facts, so a
+ * change costs one LLM call + a re-render rather than a wizard restart.
+ *
+ * The worker calls this at a REVISING stage when `pendingRevision` is set on the
+ * project doc, persists the returned spec, and re-renders from it.
+ */
+/** Cap screenshots re-attached as vision (mirrors the author's MAX_VISION_SCREENSHOTS). */
+const MAX_VISION_SCREENSHOTS = 6;
+/**
+ * Apply a natural-language change to an existing DemoSpec. Pure orchestration:
+ * build the reviser prompt (current spec as JSON + the change), re-attach the
+ * screenshots as vision, call `.structured(DemoSpec)`, then normalize. Throws if
+ * the caller is unconfigured or the model returns an unparseable / scene-less
+ * spec (the normalize pass is the last guard).
+ */
+async function reviseDemoSpec(currentSpec, instruction, deps) {
+    const llm = deps.llm ?? (0, llmCallerRegistry_1.getLlmCaller)();
+    const router = deps.router ?? new modelRouter_1.ModelRouter();
+    const model = router.pickFor("planner", { premium: deps.premium });
+    const fallbackModel = router.fallbackFor("planner");
+    // Same cap-before-prompt discipline as the author: only advertise (and attach)
+    // the images the model can actually see, so the citable set matches. The user's
+    // per-edit reference images get FIRST claim on the vision budget (they are the
+    // explicit intent for this change); product screenshots fill the remainder.
+    const refShots = [...new Set(deps.referenceImageUrls ?? [])].slice(0, MAX_VISION_SCREENSHOTS);
+    const productShots = [...new Set(deps.context.screenshotUrls ?? [])]
+        .filter((u) => !refShots.includes(u))
+        .slice(0, Math.max(0, MAX_VISION_SCREENSHOTS - refShots.length));
+    // Everything the model may SEE and CITE this edit (product + references).
+    const visionImageUrls = [...productShots, ...refShots];
+    const cappedContext = {
+        ...deps.context,
+        screenshotUrls: visionImageUrls.length ? visionImageUrls : undefined,
+    };
+    const system = (0, demoRevisePrompt_1.buildDemoReviseSystemPrompt)({
+        allowCustomScenes: deps.allowCustomScenes,
+        allowGeneratedAssets: deps.allowGeneratedAssets,
+    });
+    const userText = (0, demoRevisePrompt_1.buildDemoReviseUserText)(currentSpec, instruction, productShots, refShots);
+    const result = await llm.structured({
+        model,
+        fallbackModel,
+        messages: [
+            { role: "system", content: system },
+            {
+                role: "user",
+                content: userText,
+                imageUrls: visionImageUrls.length ? visionImageUrls : undefined,
+            },
+        ],
+        schema: demoSpec_schema_1.DemoSpecSchema,
+        schemaName: "DemoSpec",
+        // Conservative: a revision should change what was asked and little else.
+        temperature: deps.temperature ?? 0.3,
+        maxTokens: deps.maxTokens ?? 8000,
+    });
+    const raw = demoSpec_schema_1.DemoSpecSchema.parse(result.data);
+    const normalized = (0, demoAuthorNormalize_1.normalizeDemoSpec)(raw, cappedContext);
+    return {
+        ...normalized,
+        modelUsed: result.usedFallback && fallbackModel ? fallbackModel : model,
+        usedFallback: result.usedFallback,
+        usage: result.usage,
+    };
+}

package/lib/services/demo/demoScriptPrompt.d.ts

@@ -0,0 +1,63 @@
+import { DemoScene, DemoSpec } from "../../schemas/demoSpec.schema";
+/**
+ * Prompt construction for the SaaS Demo Video narration writer
+ * (plan Phase 5 / §4 stage 4 / §6).
+ *
+ * Unlike the reference workflow (visual-first → Gemini analyses the recording →
+ * script matched to timestamps), WE OWN the timeline: the DemoSpec's scene
+ * durations are already exact, so the narration is authored already aligned to
+ * scene start/end frames — no recording round-trip. This module turns each scene
+ * into a compact brief (id, type, duration, on-screen copy, the author's
+ * `narrationHint`) and asks Claude for one concise spoken line per scene, sized
+ * to that scene's spoken-time budget so the TTS lands inside the scene window.
+ *
+ * The prompt only DESCRIBES intent; `demoScriptWriter.ts` enforces the hard
+ * guarantees a prompt can only request (valid sceneIds, one segment per scene,
+ * timeline offsets) via a deterministic normalize pass.
+ */
+/**
+ * Natural narration rate — ~150 wpm. Matches `elevenlabsConfig.wordsPerSecond`
+ * (the TTS provider's nominal rate) so the word budget we hand the author and the
+ * spoken duration the voice stage estimates agree.
+ */
+export declare const SCRIPT_WORDS_PER_SECOND = 2.5;
+/** Spoken-word budget for a scene of `durationMs`, given the fill factor. */
+export declare function scriptWordBudget(durationMs: number): number;
+/** Rough spoken-word count (whitespace tokens). */
+export declare function wordCount(text: string): number;
+/**
+ * Deterministically fit narration to a spoken-word `budget` so the synthesized
+ * speech lands INSIDE its scene window — instead of overrunning and either
+ * overlapping the next scene's voice or being clipped/rushed by the voice stage.
+ * This is the hard enforcement behind the prompt's soft "respect the wordBudget"
+ * ask (the model has been observed to overshoot ~2×).
+ *
+ * Strategy, preferring to end on a natural boundary:
+ *   1. keep as many WHOLE sentences as fit within budget;
+ *   2. if even the first sentence is over budget, cap at `budget` words and back
+ *      off to the last clause boundary (comma/semicolon/dash) in that span;
+ *   3. always end on terminal punctuation.
+ * Never lengthens. Returns the (possibly) trimmed text + whether it changed.
+ */
+export declare function fitNarrationToBudget(text: string, budget: number): {
+    text: string;
+    trimmed: boolean;
+};
+/** A compact, model-facing view of one scene for the narration writer. */
+export interface DemoScriptSceneBrief {
+    sceneId: string;
+    index: number;
+    type: DemoScene["type"];
+    durationMs: number;
+    /** Suggested spoken-word ceiling so the line fits the scene window. */
+    wordBudget: number;
+    /** Salient on-screen copy the narration should complement (not read verbatim). */
+    onScreen: string;
+    /** The author's optional per-scene narration intent. */
+    narrationHint?: string;
+}
+/** Build the per-scene briefs the writer reasons over, in timeline order. */
+export declare function buildDemoScriptBriefs(spec: DemoSpec): DemoScriptSceneBrief[];
+export declare function buildDemoScriptSystemPrompt(): string;
+export declare function buildDemoScriptUserText(spec: DemoSpec, briefs: DemoScriptSceneBrief[]): string;
+//# sourceMappingURL=demoScriptPrompt.d.ts.map

package/lib/services/demo/demoScriptPrompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demoScriptPrompt.d.ts","sourceRoot":"","sources":["../../../src/services/demo/demoScriptPrompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAEpE;;;;;;;;;;;;;;;GAeG;AAEH;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAY3C,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAM3D;AAED,mDAAmD;AACnD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AA4BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CA6BpC;AAED,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAuED,6EAA6E;AAC7E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,oBAAoB,EAAE,CAU5E;AAED,wBAAgB,2BAA2B,IAAI,MAAM,CAkBpD;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,oBAAoB,EAAE,GAC7B,MAAM,CAuBR"}

package/lib/services/demo/demoScriptPrompt.js

@@ -0,0 +1,234 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCRIPT_WORDS_PER_SECOND = void 0;
+exports.scriptWordBudget = scriptWordBudget;
+exports.wordCount = wordCount;
+exports.fitNarrationToBudget = fitNarrationToBudget;
+exports.buildDemoScriptBriefs = buildDemoScriptBriefs;
+exports.buildDemoScriptSystemPrompt = buildDemoScriptSystemPrompt;
+exports.buildDemoScriptUserText = buildDemoScriptUserText;
+/**
+ * Prompt construction for the SaaS Demo Video narration writer
+ * (plan Phase 5 / §4 stage 4 / §6).
+ *
+ * Unlike the reference workflow (visual-first → Gemini analyses the recording →
+ * script matched to timestamps), WE OWN the timeline: the DemoSpec's scene
+ * durations are already exact, so the narration is authored already aligned to
+ * scene start/end frames — no recording round-trip. This module turns each scene
+ * into a compact brief (id, type, duration, on-screen copy, the author's
+ * `narrationHint`) and asks Claude for one concise spoken line per scene, sized
+ * to that scene's spoken-time budget so the TTS lands inside the scene window.
+ *
+ * The prompt only DESCRIBES intent; `demoScriptWriter.ts` enforces the hard
+ * guarantees a prompt can only request (valid sceneIds, one segment per scene,
+ * timeline offsets) via a deterministic normalize pass.
+ */
+/**
+ * Natural narration rate — ~150 wpm. Matches `elevenlabsConfig.wordsPerSecond`
+ * (the TTS provider's nominal rate) so the word budget we hand the author and the
+ * spoken duration the voice stage estimates agree.
+ */
+exports.SCRIPT_WORDS_PER_SECOND = 2.5;
+/**
+ * Fraction of a scene we let narration fill. < 1 leaves breathing room (natural
+ * pauses, and short logo/CTA beats that shouldn't be wall-to-wall speech). The
+ * voice stage applies a mild speed-up (≤1.2×) for any segment that still overruns.
+ */
+const SCRIPT_FILL_FACTOR = 0.85;
+/** Never ask for fewer than this — a 1s beat still gets a 2–3 word line. */
+const MIN_SCRIPT_WORDS = 2;
+/** Spoken-word budget for a scene of `durationMs`, given the fill factor. */
+function scriptWordBudget(durationMs) {
+    const seconds = durationMs / 1000;
+    return Math.max(MIN_SCRIPT_WORDS, Math.round(seconds * exports.SCRIPT_WORDS_PER_SECOND * SCRIPT_FILL_FACTOR));
+}
+/** Rough spoken-word count (whitespace tokens). */
+function wordCount(text) {
+    return text.trim().split(/\s+/).filter(Boolean).length;
+}
+function ensureTerminalPunctuation(s) {
+    const trimmed = s.replace(/[\s,;:—–-]+$/, "").trim();
+    return /[.!?]$/.test(trimmed) ? trimmed : `${trimmed}.`;
+}
+/**
+ * Split into sentences on REAL boundaries only: a `.`/`!`/`?` that is followed by
+ * whitespace + an uppercase letter, or by end-of-string. This deliberately does
+ * NOT break on the `.` inside decimals ("4.9") or domains ("vidspotai.com"), which
+ * a naive `/[.!?]/` split mangles.
+ */
+function splitSentences(text) {
+    const out = [];
+    const re = /[.!?]+(?=\s+\p{Lu}|\s*$)/gu;
+    let last = 0;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        const end = m.index + m[0].length;
+        out.push(text.slice(last, end).trim());
+        last = end;
+        if (re.lastIndex === m.index)
+            re.lastIndex++; // guard against zero-width loops
+    }
+    if (last < text.length)
+        out.push(text.slice(last).trim());
+    return out.filter(Boolean);
+}
+/**
+ * Deterministically fit narration to a spoken-word `budget` so the synthesized
+ * speech lands INSIDE its scene window — instead of overrunning and either
+ * overlapping the next scene's voice or being clipped/rushed by the voice stage.
+ * This is the hard enforcement behind the prompt's soft "respect the wordBudget"
+ * ask (the model has been observed to overshoot ~2×).
+ *
+ * Strategy, preferring to end on a natural boundary:
+ *   1. keep as many WHOLE sentences as fit within budget;
+ *   2. if even the first sentence is over budget, cap at `budget` words and back
+ *      off to the last clause boundary (comma/semicolon/dash) in that span;
+ *   3. always end on terminal punctuation.
+ * Never lengthens. Returns the (possibly) trimmed text + whether it changed.
+ */
+function fitNarrationToBudget(text, budget) {
+    const clean = text.trim().replace(/\s+/g, " ");
+    if (!clean)
+        return { text: clean, trimmed: false };
+    if (wordCount(clean) <= budget)
+        return { text: clean, trimmed: false };
+    // 1) whole sentences up to budget
+    const sentences = splitSentences(clean);
+    let acc = "";
+    for (const s of sentences) {
+        const candidate = acc ? `${acc} ${s}` : s;
+        if (wordCount(candidate) > budget)
+            break;
+        acc = candidate;
+    }
+    if (acc)
+        return { text: ensureTerminalPunctuation(acc), trimmed: true };
+    // 2) first sentence already over budget → cap at budget words, back off to the
+    //    last clause boundary in the capped span (only if it keeps ≥ half the budget)
+    const capped = clean.split(" ").slice(0, Math.max(1, budget)).join(" ");
+    const clauseIdx = Math.max(capped.lastIndexOf(","), capped.lastIndexOf(";"), capped.lastIndexOf("—"), capped.lastIndexOf("–"));
+    const out = clauseIdx > 0 && wordCount(capped.slice(0, clauseIdx)) >= Math.ceil(budget * 0.5)
+        ? capped.slice(0, clauseIdx)
+        : capped;
+    return { text: ensureTerminalPunctuation(out), trimmed: true };
+}
+/** Pull the salient on-screen copy from a scene so narration can complement it. */
+function sceneCopyDigest(scene) {
+    const parts = [];
+    const push = (v) => {
+        if (v && v.trim())
+            parts.push(v.trim());
+    };
+    if (scene.caption) {
+        push(scene.caption.title);
+        push(scene.caption.sub);
+    }
+    switch (scene.type) {
+        case "problem":
+            push(scene.headline);
+            break;
+        case "logoReveal":
+            push(scene.tagline);
+            break;
+        case "featureShowcase":
+            push(scene.title);
+            push(scene.cursorTypes);
+            scene.cards.forEach((c) => push(c.title));
+            break;
+        case "splitFeature":
+            push(scene.stepLabel);
+            push(scene.headline);
+            push(scene.body);
+            break;
+        case "bigStatement":
+            push(scene.kicker);
+            scene.lines.forEach((l) => push(l.replace(/\*\*/g, "")));
+            break;
+        case "deviceMockup":
+            push(scene.headline);
+            break;
+        case "mediaShot":
+            push(scene.headline?.replace(/\*\*/g, ""));
+            break;
+        case "chat":
+            push(scene.title);
+            scene.turns.forEach((t) => push(`${t.role}: ${t.text}`));
+            break;
+        case "dashboard":
+            push(scene.title);
+            scene.stats.forEach((s) => push(s.label));
+            break;
+        case "docAnalysis":
+            push(scene.title);
+            scene.insights.forEach((i) => push(i.title));
+            break;
+        case "cardGrid":
+            push(scene.title);
+            scene.cards.forEach((c) => push(c.title));
+            break;
+        case "stats":
+            push(scene.headline);
+            scene.stats.forEach((s) => push(`${s.valueText ?? s.value ?? ""} ${s.label}`.trim()));
+            break;
+        case "cta":
+            push(scene.headline);
+            push(scene.buttonText);
+            break;
+        case "custom":
+            // Path B (Phase 8) — no structured copy to digest.
+            break;
+    }
+    // Keep the digest bounded — long chat/card lists would bloat the prompt.
+    return parts.slice(0, 8).join(" · ").slice(0, 400);
+}
+/** Build the per-scene briefs the writer reasons over, in timeline order. */
+function buildDemoScriptBriefs(spec) {
+    return spec.scenes.map((scene, index) => ({
+        sceneId: scene.id,
+        index,
+        type: scene.type,
+        durationMs: scene.durationMs,
+        wordBudget: scriptWordBudget(scene.durationMs),
+        onScreen: sceneCopyDigest(scene),
+        ...(scene.narrationHint ? { narrationHint: scene.narrationHint } : {}),
+    }));
+}
+function buildDemoScriptSystemPrompt() {
+    return [
+        "You are the narration writer for an autonomous SaaS product-demo video.",
+        "The video's scenes and exact durations are ALREADY fixed — you write the voiceover that plays over them.",
+        "",
+        "Write a single, natural spoken line for each scene that deserves narration.",
+        "Rules:",
+        '- One segment per scene, addressed by its exact `sceneId` — the quoted value shown as sceneId=\"…\". Copy it verbatim. It is NOT the scene type in parentheses; never return the type, and never invent a sceneId.',
+        "- You MAY omit a scene (return no segment for it) when narration would be redundant — e.g. a bare logo sting or a wordless transition. Prefer omission over filler.",
+        "- HARD LIMIT: never exceed a scene's `wordBudget`. It is the number of words that actually FIT in that scene's spoken time. A line over budget is deterministically TRIMMED to fit (your later words are dropped), and overrunning also causes the voice to overlap the next scene. So lead with the essential point and stay at or below the budget — write SHORTER, not longer.",
+        "- COMPLEMENT the on-screen copy — don't read captions/headlines back verbatim. Add the value, the 'why it matters', the connective tissue.",
+        "- Natural, confident, conversational brand voice. No hype clichés ('revolutionary', 'game-changing'), no reading of UI chrome, no stage directions, no emoji.",
+        "- One continuous through-line across scenes: problem → product → payoff → call to action. Each line should follow from the last when read in order.",
+        "- Plain spoken sentences only (this is fed to text-to-speech). No markdown, no bullet points, no SSML.",
+        "- Match the audience and narrative tone provided.",
+        "",
+        "Return segments in timeline order, each { sceneId, text }. `text` is exactly what will be spoken (empty/omit to skip a scene).",
+    ].join("\n");
+}
+function buildDemoScriptUserText(spec, briefs) {
+    const totalSec = Math.round(briefs.reduce((acc, b) => acc + b.durationMs, 0) / 1000);
+    const lines = [
+        `Product: ${spec.productName}`,
+        ...(spec.tagline ? [`Tagline: ${spec.tagline}`] : []),
+        ...(spec.audience ? [`Audience: ${spec.audience}`] : []),
+        `Narrative arc: ${spec.narrative}`,
+        `Audio intent: ${spec.style.audioIntent} (captions = sparse VO, on-screen text leads · voiceover = VO leads, carry the story · music = keep VO minimal or omit)`,
+        `Total runtime: ~${totalSec}s across ${briefs.length} scenes.`,
+        "",
+        "Scenes (timeline order):",
+    ];
+    for (const b of briefs) {
+        const secs = (b.durationMs / 1000).toFixed(1);
+        const hint = b.narrationHint ? ` | hint: ${b.narrationHint}` : "";
+        const onScreen = b.onScreen ? ` | on-screen: ${b.onScreen}` : "";
+        lines.push(`- sceneId="${b.sceneId}" (${b.type} scene, ${secs}s, ≤${b.wordBudget} words)${onScreen}${hint}`);
+    }
+    return lines.join("\n");
+}

package/lib/services/demo/demoScriptWriter.d.ts

@@ -0,0 +1,65 @@
+import { DemoSpec } from "../../schemas/demoSpec.schema";
+import { IDemoVideoScriptSegment } from "../../models/demoVideoProject.model";
+import { LlmCaller } from "../agent/llmCaller";
+import { ModelChoice, ModelRouter } from "../agent/modelRouter";
+export interface DemoScriptDeps {
+    /** LLM caller. Defaults to the host-wired dispatcher. */
+    llm?: LlmCaller;
+    /** Model router. Defaults to DEFAULT_MODEL_ROUTING. */
+    router?: ModelRouter;
+    /** Route to the premium tier (Opus) for higher-fidelity copy. */
+    premium?: boolean;
+    /** Sampling temperature. Slightly creative but on-brand. */
+    temperature?: number;
+    /** Max output tokens — a script is small (a few lines per scene). */
+    maxTokens?: number;
+}
+export interface DemoScriptResult {
+    /** Timeline-synced narration, one entry per narrated scene (timeline order). */
+    segments: IDemoVideoScriptSegment[];
+    /** Deterministic corrections the normalize pass applied (for observability). */
+    adjustments: string[];
+    modelUsed: ModelChoice;
+    usedFallback?: boolean;
+    /** True when the writer whiffed and we synthesized the script from narrationHints. */
+    usedHintFallback?: boolean;
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+    };
+}
+/**
+ * Write a timeline-synced narration script for a rendered DemoSpec. Pure
+ * orchestration: build the per-scene briefs, call `.structured()`, then normalize
+ * to concrete `IDemoVideoScriptSegment[]` (compute offsets, drop unknown/empty
+ * scenes, dedupe, order). Returns an empty `segments` list (not a throw) when the
+ * model narrates nothing — the caller decides whether that means "silent final".
+ */
+export declare function writeDemoScript(spec: DemoSpec, deps?: DemoScriptDeps): Promise<DemoScriptResult>;
+/**
+ * Deterministic guarantees the prompt can only request:
+ *  - resolve each segment to a REAL scene (drop truly unknown sceneIds),
+ *  - one segment per scene (keep the first; drop later duplicates),
+ *  - drop blank narration,
+ *  - stamp `startMs` (cumulative scene offset) + `durationMs` (the scene window;
+ *    the voice stage overwrites `durationMs` with the actual spoken length),
+ *  - emit in timeline order.
+ *
+ * `sceneId` resolution is tolerant by design. The script LLM is a separate call
+ * from the planner and has been observed to echo the scene *type* (`logoReveal`,
+ * `problem`, …) or a punctuation-drifted slug instead of the planner's exact
+ * `scene.id`. Rather than drop every segment (which silently ships a captionless,
+ * voiceover-less video), we resolve a raw id in three tiers: exact id → id with
+ * spelling drift normalized → the scene *type* when that type occurs exactly once
+ * in the timeline (so the mapping is unambiguous). Only a raw id that matches
+ * none of these is dropped. Each non-exact resolution is recorded as an
+ * adjustment for observability.
+ */
+export declare function normalizeDemoScript(spec: DemoSpec, rawSegments: Array<{
+    sceneId: string;
+    text: string;
+}>): {
+    segments: IDemoVideoScriptSegment[];
+    adjustments: string[];
+};
+//# sourceMappingURL=demoScriptWriter.d.ts.map

package/lib/services/demo/demoScriptWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demoScriptWriter.d.ts","sourceRoot":"","sources":["../../../src/services/demo/demoScriptWriter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AACzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAyChE,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,uDAAuD;IACvD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,QAAQ,EAAE,uBAAuB,EAAE,CAAC;IACpC,gFAAgF;IAChF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,WAAW,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,KAAK,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9D;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,QAAQ,EACd,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,gBAAgB,CAAC,CA0D3B;AAOD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,QAAQ,EACd,WAAW,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GACpD;IAAE,QAAQ,EAAE,uBAAuB,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAE,CAkGhE"}