vidspotai-shared 1.0.99 → 1.0.101-dev.0

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

@@ -0,0 +1,69 @@
+import { IDemoCaptionTrack, IDemoCaptionWord } from "../../models/demoVideoProject.model";
+import { DemoSpec } from "../../schemas/demoSpec.schema";
+/**
+ * Caption track construction for the SaaS Demo Video pipeline (audit finding G3).
+ *
+ * Social feeds autoplay MUTED, so a demo whose whole argument lives in the
+ * voiceover says nothing there. This module turns the synthesized narration into
+ * readable, word-timed cues that the render burns in, plus an `.srt` sidecar for
+ * platforms that accept an upload.
+ *
+ * The interesting problem is not timing, it's LINE LENGTH: a narration segment is
+ * per-scene and can be 30+ words. Drawn as one line that's an unreadable wall, so
+ * segments are split into cues sized to what a viewer takes in at a glance,
+ * breaking on sentence boundaries wherever the text offers one.
+ */
+/**
+ * A segment of narration with its words already timed on the VIDEO timeline —
+ * i.e. the voicing stage has applied any `atempo` correction and added the
+ * segment's `startMs`. This module never sees provider-relative time.
+ */
+export interface DemoNarrationTiming {
+    /** Scene this narration belongs to (matches DemoScene.id). */
+    sceneId: string;
+    /** The spoken copy, verbatim — this is what gets displayed. */
+    text: string;
+    /** Absolute start on the video timeline, ms. */
+    startMs: number;
+    /** Absolute end on the video timeline, ms (post-compression, slot-clamped). */
+    endMs: number;
+    /**
+     * Absolute-timed words from the provider's character alignment. Empty when the
+     * provider returned none — this module then falls back to proportional timing.
+     */
+    words: IDemoCaptionWord[];
+}
+/**
+ * Should this video burn captions into the picture?
+ *
+ * Portrait and square ALWAYS: those aspects exist for social feeds, which autoplay
+ * muted, so an un-captioned vertical cut ships with its argument inaudible. That is
+ * exactly the G2/G3 "social does not ship" verdict.
+ *
+ * Landscape only when the style asked for a captions-led read (`audioIntent`).
+ * A 16:9 landing-page or YC cut is watched with sound, and permanent burned-in
+ * text there competes with the on-screen lower-thirds the planner already wrote.
+ *
+ * Pure by design — the `DEMO_CAPTIONS_DISABLED` kill switch is applied by the
+ * worker, so this stays trivially testable.
+ */
+export declare function shouldBurnCaptions(spec: Pick<DemoSpec, "aspect" | "style">): boolean;
+/**
+ * Split timed narration into readable cues.
+ *
+ * `fromAlignment` records whether the times came from real provider alignment or
+ * from proportional estimation, so the QA/report layer can tell an honest
+ * karaoke-synced track from a best-effort one.
+ */
+export declare function buildCaptionTrack(segments: DemoNarrationTiming[]): IDemoCaptionTrack;
+/**
+ * Serialize a caption track as SubRip (`.srt`) — the format YouTube, LinkedIn and
+ * Vimeo all accept as an uploaded subtitle file. Shipping this alongside the
+ * burned-in captions also makes the narration searchable/indexable, which
+ * burned-in pixels never are.
+ *
+ * A zero-length cue is emitted with a minimum 1ms span rather than dropped: some
+ * parsers reject `start == end`, and losing a line is worse than a rounding nudge.
+ */
+export declare function captionTrackToSrt(track: IDemoCaptionTrack): string;
+//# sourceMappingURL=demoCaptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"demoCaptions.d.ts","sourceRoot":"","sources":["../../../src/services/demo/demoCaptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAEzD;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AAsBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,OAAO,CAGpF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,mBAAmB,EAAE,GAAG,iBAAiB,CAuBpF;AAsED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAOlE"}

package/lib/services/demo/demoCaptions.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldBurnCaptions = shouldBurnCaptions;
+exports.buildCaptionTrack = buildCaptionTrack;
+exports.captionTrackToSrt = captionTrackToSrt;
+/**
+ * Cue sizing. Tuned for a phone-held-vertically read: ~5–8 words is one glance,
+ * and a line that sits longer than ~2.8s feels stalled even when the speech
+ * behind it is still going.
+ */
+const MAX_CUE_WORDS = 8;
+const MAX_CUE_MS = 2800;
+/**
+ * Don't honour a punctuation break below this many words, or "Yes. Really." emits
+ * two one-word flashes.
+ */
+const MIN_CUE_WORDS = 3;
+/** A comma is a weaker break than a full stop — only take it once the line has body. */
+const MIN_COMMA_BREAK_WORDS = 5;
+/** Ends a sentence — the strongest place to cut a caption line. */
+const SENTENCE_END = /[.!?:]["')\]]?$/;
+/** A softer clause boundary. */
+const CLAUSE_END = /[,;—–]["')\]]?$/;
+/**
+ * Should this video burn captions into the picture?
+ *
+ * Portrait and square ALWAYS: those aspects exist for social feeds, which autoplay
+ * muted, so an un-captioned vertical cut ships with its argument inaudible. That is
+ * exactly the G2/G3 "social does not ship" verdict.
+ *
+ * Landscape only when the style asked for a captions-led read (`audioIntent`).
+ * A 16:9 landing-page or YC cut is watched with sound, and permanent burned-in
+ * text there competes with the on-screen lower-thirds the planner already wrote.
+ *
+ * Pure by design — the `DEMO_CAPTIONS_DISABLED` kill switch is applied by the
+ * worker, so this stays trivially testable.
+ */
+function shouldBurnCaptions(spec) {
+    if (spec.style.audioIntent === "music")
+        return false;
+    return spec.aspect === "16:9" ? spec.style.audioIntent === "captions" : true;
+}
+/**
+ * Split timed narration into readable cues.
+ *
+ * `fromAlignment` records whether the times came from real provider alignment or
+ * from proportional estimation, so the QA/report layer can tell an honest
+ * karaoke-synced track from a best-effort one.
+ */
+function buildCaptionTrack(segments) {
+    const cues = [];
+    let anyAlignment = false;
+    let allAlignment = segments.length > 0;
+    for (const seg of segments) {
+        const words = seg.words.length ? seg.words : estimateWords(seg);
+        if (seg.words.length)
+            anyAlignment = true;
+        else
+            allAlignment = false;
+        if (!words.length)
+            continue;
+        cues.push(...cuesFromWords(seg, words, seg.words.length > 0));
+    }
+    // Never let a cue outlive the next one's start: a slot-clamped segment can end
+    // after the following segment begins, and two captions on screen at once reads
+    // as a bug even when the audio underneath is correct.
+    for (let i = 0; i < cues.length - 1; i++) {
+        const cur = cues[i];
+        const next = cues[i + 1];
+        if (cur.endMs > next.startMs)
+            cur.endMs = Math.max(cur.startMs, next.startMs);
+    }
+    return { cues, fromAlignment: anyAlignment && allAlignment };
+}
+/**
+ * Space a segment's words evenly across its spoken window. The honest fallback
+ * when a provider returned no alignment: line breaks and cue timing stay right
+ * (they're driven by the segment window, which we measured with ffprobe), only
+ * the within-line word emphasis becomes approximate.
+ */
+function estimateWords(seg) {
+    const tokens = seg.text.trim().split(/\s+/).filter(Boolean);
+    if (!tokens.length)
+        return [];
+    const span = Math.max(0, seg.endMs - seg.startMs);
+    const per = span / tokens.length;
+    return tokens.map((word, i) => ({
+        word,
+        startMs: Math.round(seg.startMs + per * i),
+        endMs: Math.round(seg.startMs + per * (i + 1)),
+    }));
+}
+/** Greedy line-breaker: fill a cue until a good break appears or the bounds hit. */
+function cuesFromWords(seg, words, real) {
+    const out = [];
+    let cur = [];
+    const flush = () => {
+        if (!cur.length)
+            return;
+        const first = cur[0];
+        const last = cur[cur.length - 1];
+        out.push({
+            sceneId: seg.sceneId,
+            text: cur.map((w) => w.word).join(" "),
+            startMs: first.startMs,
+            endMs: Math.max(last.endMs, first.startMs + 1),
+            // Only publish per-word timings we actually measured. Estimated words would
+            // drive the karaoke fill off the real speech, which looks worse than the
+            // renderer's own even spacing — and the renderer already does that for [].
+            words: real ? cur.map((w) => ({ ...w })) : [],
+        });
+        cur = [];
+    };
+    for (const w of words) {
+        cur.push(w);
+        const spanMs = w.endMs - cur[0].startMs;
+        const hitBound = cur.length >= MAX_CUE_WORDS || spanMs >= MAX_CUE_MS;
+        const sentence = cur.length >= MIN_CUE_WORDS && SENTENCE_END.test(w.word);
+        const clause = cur.length >= MIN_COMMA_BREAK_WORDS && CLAUSE_END.test(w.word);
+        if (hitBound || sentence || clause)
+            flush();
+    }
+    flush();
+    return out;
+}
+/** `1234` → `00:00:01,234` (SRT timecode). */
+function srtTime(ms) {
+    const total = Math.max(0, Math.round(ms));
+    const h = Math.floor(total / 3600000);
+    const m = Math.floor((total % 3600000) / 60000);
+    const s = Math.floor((total % 60000) / 1000);
+    const milli = total % 1000;
+    const pad = (n, w = 2) => String(n).padStart(w, "0");
+    return `${pad(h)}:${pad(m)}:${pad(s)},${pad(milli, 3)}`;
+}
+/**
+ * Serialize a caption track as SubRip (`.srt`) — the format YouTube, LinkedIn and
+ * Vimeo all accept as an uploaded subtitle file. Shipping this alongside the
+ * burned-in captions also makes the narration searchable/indexable, which
+ * burned-in pixels never are.
+ *
+ * A zero-length cue is emitted with a minimum 1ms span rather than dropped: some
+ * parsers reject `start == end`, and losing a line is worse than a rounding nudge.
+ */
+function captionTrackToSrt(track) {
+    return track.cues
+        .map((cue, i) => {
+        const end = Math.max(cue.endMs, cue.startMs + 1);
+        return `${i + 1}\n${srtTime(cue.startMs)} --> ${srtTime(end)}\n${cue.text}\n`;
+    })
+        .join("\n");
+}

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

@@ -9,5 +9,12 @@ export interface DemoMusicSelection {
  * Pick a reachable background-music bed for a demo. Returns null (never throws)
  * when nothing is reachable — the caller ships the video without a bed.
  */
-export declare function selectDemoMusic(spec: DemoSpec): Promise<DemoMusicSelection | null>;
+export declare function selectDemoMusic(spec: DemoSpec, opts?: {
+    /**
+     * A user-uploaded music bed (from the "have a track?" asset ask). When set
+     * and reachable it WINS over the curated catalog — the user's own track,
+     * ducked under any voiceover in the mux exactly like a curated bed.
+     */
+    preferredUrl?: string;
+}): Promise<DemoMusicSelection | null>;
 //# sourceMappingURL=demoMusic.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"demoMusic.d.ts","sourceRoot":"","sources":["../../../src/services/demo/demoMusic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAsBzD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAmDD;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAmBxF"}
+{"version":3,"file":"demoMusic.d.ts","sourceRoot":"","sources":["../../../src/services/demo/demoMusic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAsBzD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAyDD;;;GAGG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,QAAQ,EACd,IAAI,CAAC,EAAE;IACL;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GACA,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CA6BpC"}

package/lib/services/demo/demoMusic.js

@@ -46,23 +46,29 @@ function moodForStyle(spec) {
  * a dead CDN edge silently ships no music rather than 404-crashing the mux.
  * (Same guard shape as `selectMusicForPlan`'s `pickFirstReachable`.)
  */
+async function urlReachable(url) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+        const r = await fetch(url, { method: "HEAD", signal: controller.signal });
+        clearTimeout(timeout);
+        if (r.ok)
+            return true;
+        logger_1.logger.warn(`${TAG} track HEAD non-2xx, skipping`, { url, status: r.status });
+        return false;
+    }
+    catch (e) {
+        logger_1.logger.warn(`${TAG} track HEAD failed, skipping`, {
+            url,
+            err: e instanceof Error ? e.message : String(e),
+        });
+        return false;
+    }
+}
 async function firstReachable(tracks) {
     for (const t of tracks) {
-        try {
-            const controller = new AbortController();
-            const timeout = setTimeout(() => controller.abort(), 5000);
-            const r = await fetch(t.url, { method: "HEAD", signal: controller.signal });
-            clearTimeout(timeout);
-            if (r.ok)
-                return t;
-            logger_1.logger.warn(`${TAG} track HEAD non-2xx, skipping`, { url: t.url, status: r.status });
-        }
-        catch (e) {
-            logger_1.logger.warn(`${TAG} track HEAD failed, skipping`, {
-                url: t.url,
-                err: e instanceof Error ? e.message : String(e),
-            });
-        }
+        if (await urlReachable(t.url))
+            return t;
     }
     return undefined;
 }
@@ -70,7 +76,17 @@ async function firstReachable(tracks) {
  * Pick a reachable background-music bed for a demo. Returns null (never throws)
  * when nothing is reachable — the caller ships the video without a bed.
  */
-async function selectDemoMusic(spec) {
+async function selectDemoMusic(spec, opts) {
+    // User-provided track wins when reachable (still fail-soft to the catalog).
+    if (opts?.preferredUrl && (await urlReachable(opts.preferredUrl))) {
+        logger_1.logger.info(`${TAG} using user-provided bed`, { url: opts.preferredUrl });
+        return { url: opts.preferredUrl, attribution: "User-provided" };
+    }
+    if (opts?.preferredUrl) {
+        logger_1.logger.warn(`${TAG} user bed unreachable — falling back to catalog`, {
+            url: opts.preferredUrl,
+        });
+    }
     const { mood, query, bpmTarget } = moodForStyle(spec);
     try {
         // Don't pass durationSecMin — every curated track is looped to the video

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

@@ -36,7 +36,8 @@ export declare function wordCount(text: string): number;
  *   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.
+ *   3. drop any dangling function-word tail so the line ends on a content word;
+ *   4. always end on terminal punctuation.
  * Never lengthens. Returns the (possibly) trimmed text + whether it changed.
  */
 export declare function fitNarrationToBudget(text: string, budget: number): {

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

@@ -1 +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"}
+{"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;AA0DD;;;;;;;;;;;;;;GAcG;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

@@ -72,6 +72,32 @@ function splitSentences(text) {
         out.push(text.slice(last).trim());
     return out.filter(Boolean);
 }
+/**
+ * Words that must never END a trimmed line: cutting here yields a dangling
+ * fragment ("…describe what you want and.") that reads as broken copy and sounds
+ * worse spoken than a shorter, complete phrase. Conjunctions, prepositions,
+ * articles, and auxiliaries all imply a continuation that was cut away.
+ */
+const DANGLING_TAIL_WORDS = new Set([
+    "a", "an", "and", "as", "at", "but", "by", "for", "from", "if", "in", "into",
+    "is", "it", "its", "of", "on", "or", "so", "than", "that", "the", "then",
+    "to", "up", "was", "were", "when", "which", "while", "with", "you", "your",
+]);
+/**
+ * Drop trailing function words so a capped span ends on a content word. Bounded:
+ * never strips below half the words it was given, so a line made entirely of
+ * function words degrades to the plain cap rather than to nothing.
+ */
+function trimDanglingTail(text) {
+    const words = text.trim().split(/\s+/).filter(Boolean);
+    const floor = Math.ceil(words.length / 2);
+    let end = words.length;
+    while (end > floor &&
+        DANGLING_TAIL_WORDS.has(words[end - 1].toLowerCase().replace(/[^\p{L}']/gu, ""))) {
+        end--;
+    }
+    return words.slice(0, end).join(" ");
+}
 /**
  * Deterministically fit narration to a spoken-word `budget` so the synthesized
  * speech lands INSIDE its scene window — instead of overrunning and either
@@ -83,7 +109,8 @@ function splitSentences(text) {
  *   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.
+ *   3. drop any dangling function-word tail so the line ends on a content word;
+ *   4. always end on terminal punctuation.
  * Never lengthens. Returns the (possibly) trimmed text + whether it changed.
  */
 function fitNarrationToBudget(text, budget) {
@@ -110,7 +137,7 @@ function fitNarrationToBudget(text, budget) {
     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 };
+    return { text: ensureTerminalPunctuation(trimDanglingTail(out)), trimmed: true };
 }
 /** Pull the salient on-screen copy from a scene so narration can complement it. */
 function sceneCopyDigest(scene) {

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

@@ -0,0 +1,29 @@
+/**
+ * Stock-asset resolution for the SaaS Demo Video pipeline — the "real library"
+ * half of the planner's `generatedAssets` (see DemoGeneratedAssetSchema, where
+ * `source:"stock"` requests a real photo/clip instead of an AI generation).
+ *
+ * Free, instant, and REAL: for generic real-world subjects (a laptop on a desk,
+ * a city street, a coffee shop) a licensed stock shot beats a synthesized one —
+ * so the planner can prefer it and skip the generation cost. Resolution reuses
+ * the same provider cascade the agent flow uses (Pexels → Pixabay → Unsplash for
+ * images; Pexels → Pixabay for video), gated on env keys. Fail-soft: returns
+ * null when nothing is reachable/available, and the caller marks the asset failed
+ * and strips its `gen://` ref so the scene degrades to its coded surface.
+ *
+ * Kept in `shared` (next to demoMusic) so it can import the provider services via
+ * relative paths — they are not part of the package's public surface. Deliberately
+ * cache-free: demo runs are infrequent and each stock ref resolves once per spec.
+ */
+import type { DemoGeneratedAsset, DemoSpec } from "../../schemas/demoSpec.schema";
+/** Whether any stock provider is configured — the prompt only offers stock when true. */
+export declare function stockAssetsAvailable(): boolean;
+/**
+ * Resolve one `source:"stock"` asset to a real media URL, trying each configured
+ * provider in turn. Returns null (never throws) when no provider yields a hit.
+ */
+export declare function resolveStockAsset(request: DemoGeneratedAsset, spec: DemoSpec): Promise<{
+    url: string;
+    attribution?: string;
+} | null>;
+//# sourceMappingURL=demoStockAssets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"demoStockAssets.d.ts","sourceRoot":"","sources":["../../../src/services/demo/demoStockAssets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAYlF,yFAAyF;AACzF,wBAAgB,oBAAoB,IAAI,OAAO,CAM9C;AAkDD;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CA+CvD"}

package/lib/services/demo/demoStockAssets.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stockAssetsAvailable = stockAssetsAvailable;
+exports.resolveStockAsset = resolveStockAsset;
+const pexels_service_1 = require("../aiGen/providers/pexels/pexels.service");
+const pixabay_service_1 = require("../aiGen/providers/pixabay/pixabay.service");
+const unsplash_service_1 = require("../aiGen/providers/unsplash/unsplash.service");
+const logger_1 = require("../../utils/logger");
+const TAG = "[DemoStockAssets]";
+/** Whether any stock provider is configured — the prompt only offers stock when true. */
+function stockAssetsAvailable() {
+    return Boolean(process.env.PEXELS_API_KEY ||
+        process.env.PIXABAY_API_KEY ||
+        process.env.UNSPLASH_ACCESS_KEY);
+}
+/** Provider cascade — same order/precedence as the agent's search_stock tool. */
+function buildChain(kind) {
+    const pexels = new pexels_service_1.PexelsProviderService();
+    const pixabay = new pixabay_service_1.PixabayProviderService();
+    const unsplash = new unsplash_service_1.UnsplashProviderService();
+    const chain = [
+        {
+            name: "pexels",
+            available: () => Boolean(process.env.PEXELS_API_KEY),
+            supports: () => true,
+            search: (p) => pexels.searchStock(p),
+        },
+        {
+            name: "pixabay",
+            available: () => Boolean(process.env.PIXABAY_API_KEY),
+            supports: () => true,
+            search: (p) => pixabay.searchStock(p),
+        },
+        {
+            name: "unsplash",
+            available: () => Boolean(process.env.UNSPLASH_ACCESS_KEY),
+            supports: (k) => k === "image",
+            search: (p) => unsplash.searchStock(p),
+        },
+    ];
+    return chain.filter((l) => l.supports(kind) && l.available());
+}
+/** Plain search terms from the request (`query` wins; else the prompt's first words). */
+function searchQuery(request) {
+    const q = request.query?.trim();
+    if (q)
+        return q;
+    // Fallback: first ~6 words of the generation prompt, stripped of punctuation.
+    return request.prompt
+        .replace(/[^\p{L}\p{N}\s]/gu, " ")
+        .split(/\s+/)
+        .filter(Boolean)
+        .slice(0, 6)
+        .join(" ");
+}
+/**
+ * Resolve one `source:"stock"` asset to a real media URL, trying each configured
+ * provider in turn. Returns null (never throws) when no provider yields a hit.
+ */
+async function resolveStockAsset(request, spec) {
+    const kind = request.kind; // "image" | "video"
+    const chain = buildChain(kind);
+    if (chain.length === 0) {
+        logger_1.logger.warn(`${TAG} no stock provider configured — cannot resolve`, {
+            id: request.id,
+            kind,
+        });
+        return null;
+    }
+    const params = {
+        query: searchQuery(request),
+        kind,
+        aspectRatio: request.aspect ?? spec.aspect,
+        perPage: 5,
+        ...(kind === "video"
+            ? { minDurationSec: 2, maxDurationSec: request.durationSec ?? 15 }
+            : {}),
+    };
+    for (const link of chain) {
+        try {
+            const result = await link.search(params);
+            const asset = result.assets?.[0];
+            if (asset?.url) {
+                logger_1.logger.info(`${TAG} resolved ${kind} "${request.id}" via ${link.name}`, {
+                    query: params.query,
+                });
+                return {
+                    url: asset.url,
+                    ...(asset.attribution?.name
+                        ? { attribution: `${asset.attribution.name} (${asset.source})` }
+                        : {}),
+                };
+            }
+            logger_1.logger.warn(`${TAG} ${link.name} returned no results`, {
+                id: request.id,
+                query: params.query,
+            });
+        }
+        catch (err) {
+            logger_1.logger.warn(`${TAG} ${link.name} search failed — trying next`, {
+                id: request.id,
+                err: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return null;
+}

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

@@ -13,7 +13,9 @@ export * from "./demoAuthor";
 export * from "./demoCredits";
 export * from "./demoScriptPrompt";
 export * from "./demoScriptWriter";
+export * from "./demoCaptions";
 export * from "./demoMusic";
+export * from "./demoStockAssets";
 export * from "./demoMediaGuard";
 export * from "./demoRevisePrompt";
 export * from "./demoReviser";
@@ -21,4 +23,5 @@ export * from "./demoPrefill";
 export * from "./demoTriage";
 export * from "./githubOAuth";
 export * from "./githubOAuthState";
+export * from "./productConnection.service";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/demo/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/demo/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,6BAA6B,CAAC"}

package/lib/services/demo/index.js

@@ -29,7 +29,9 @@ __exportStar(require("./demoAuthor"), exports);
 __exportStar(require("./demoCredits"), exports);
 __exportStar(require("./demoScriptPrompt"), exports);
 __exportStar(require("./demoScriptWriter"), exports);
+__exportStar(require("./demoCaptions"), exports);
 __exportStar(require("./demoMusic"), exports);
+__exportStar(require("./demoStockAssets"), exports);
 __exportStar(require("./demoMediaGuard"), exports);
 __exportStar(require("./demoRevisePrompt"), exports);
 __exportStar(require("./demoReviser"), exports);
@@ -37,3 +39,4 @@ __exportStar(require("./demoPrefill"), exports);
 __exportStar(require("./demoTriage"), exports);
 __exportStar(require("./githubOAuth"), exports);
 __exportStar(require("./githubOAuthState"), exports);
+__exportStar(require("./productConnection.service"), exports);

package/lib/services/demo/productConnection.service.d.ts

@@ -0,0 +1,78 @@
+import { IProductConnectionModel } from "../../models/productConnection.model";
+/**
+ * Product sign-in connection store (Tier 2 product-footage-capture —
+ * notes/PRODUCT_FOOTAGE_CAPTURE_PLAN.md). Owns the encrypt-at-write /
+ * decrypt-at-read of a user's captured browser sign-in session so both the
+ * live-session capture endpoint AND the worker's authed replay go through one
+ * place. Mirrors the githubConnection token flow (AES-256-GCM via the shared
+ * vault, `SOCIAL_TOKEN_ENC_KEY`) — plaintext state never touches Firestore.
+ */
+/**
+ * A Playwright-compatible browser storage snapshot — the RESULT of a sign-in
+ * (never credentials). Shape matches Playwright's `storageState()` so the worker
+ * can seed cookies + localStorage before navigating past the auth wall.
+ */
+export interface ProductStorageState {
+    cookies: Array<{
+        name: string;
+        value: string;
+        domain: string;
+        path: string;
+        /** Unix seconds; -1 / absent for session cookies. */
+        expires?: number;
+        httpOnly?: boolean;
+        secure?: boolean;
+        sameSite?: "Strict" | "Lax" | "None";
+    }>;
+    origins: Array<{
+        origin: string;
+        localStorage: Array<{
+            name: string;
+            value: string;
+        }>;
+    }>;
+}
+/** Public-safe view of a connection — everything EXCEPT the encrypted state. */
+export interface ProductConnectionSummary {
+    host: string;
+    productUrl: string;
+    origins: string[];
+    label?: string;
+    status: IProductConnectionModel["status"];
+    expiresHint?: number;
+}
+/** Origin host of a URL, lowercased, or null if unparseable. */
+export declare function hostOf(url: string): string | null;
+/** True when the vault is configured — connections are unusable without it. */
+export declare function isProductConnectionEnabled(): boolean;
+/**
+ * Upsert a captured sign-in session (encrypted). Idempotent per (user, host):
+ * re-connecting the same product replaces the expired snapshot. Returns the
+ * host used as the connection key.
+ */
+export declare function saveProductConnection(args: {
+    userId: string;
+    productUrl: string;
+    storageState: ProductStorageState;
+    label?: string;
+}): Promise<{
+    host: string;
+}>;
+/**
+ * Read + decrypt a user's connection for a host. Returns the storageState +
+ * metadata, or null when there's no ACTIVE connection / the vault can't decrypt
+ * (best-effort — the caller treats null as "not connected" and asks the user).
+ */
+export declare function getProductConnection(userId: string, host: string): Promise<{
+    state: ProductStorageState;
+    conn: IProductConnectionModel;
+} | null>;
+/** List a user's connections as public-safe summaries (no encrypted state). */
+export declare function listProductConnections(userId: string): Promise<ProductConnectionSummary[]>;
+/** Delete (revoke) a user's connection for a host. */
+export declare function deleteProductConnection(userId: string, host: string): Promise<void>;
+/** Flag a connection expired after a replay found the session no longer authenticates. */
+export declare function markProductConnectionExpired(userId: string, host: string): Promise<void>;
+/** Stamp lastUsedAt after a successful replay (observability; best-effort). */
+export declare function touchProductConnection(userId: string, host: string): Promise<void>;
+//# sourceMappingURL=productConnection.service.d.ts.map

package/lib/services/demo/productConnection.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"productConnection.service.d.ts","sourceRoot":"","sources":["../../../src/services/demo/productConnection.service.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,uBAAuB,EAExB,MAAM,sCAAsC,CAAC;AAG9C;;;;;;;GAOG;AAEH;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,qDAAqD;QACrD,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;KACtC,CAAC,CAAC;IACH,OAAO,EAAE,KAAK,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACtD,CAAC,CAAC;CACJ;AAED,gFAAgF;AAChF,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,gEAAgE;AAChE,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMjD;AAWD,+EAA+E;AAC/E,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,mBAAmB,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAgC5B;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,KAAK,EAAE,mBAAmB,CAAC;IAAC,IAAI,EAAE,uBAAuB,CAAA;CAAE,GAAG,IAAI,CAAC,CAY/E;AAED,+EAA+E;AAC/E,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,wBAAwB,EAAE,CAAC,CAerC;AAED,sDAAsD;AACtD,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,0FAA0F;AAC1F,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,+EAA+E;AAC/E,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAQf"}