vidspotai-shared 1.0.94 → 1.0.96

package/lib/services/demo/demoAuthorPrompt.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DURATION_BUDGET = exports.DURATION_BUDGETS = void 0;
+exports.budgetForLength = budgetForLength;
+exports.buildDemoAuthorSystemPrompt = buildDemoAuthorSystemPrompt;
+exports.buildDemoAuthorUserText = buildDemoAuthorUserText;
+exports.DURATION_BUDGETS = {
+    // ~20–30s teaser — kinetic, few beats, one hero surface.
+    teaser: { min: 18000, target: 26000, max: 32000, sceneHint: "4–6 short scenes" },
+    // ~45–60s walkthrough — the default; intro → 2–3 features → CTA.
+    walkthrough: { min: 42000, target: 54000, max: 66000, sceneHint: "6–9 scenes" },
+    // ~90s detailed — full narrative, more feature surfaces.
+    detailed: { min: 78000, target: 92000, max: 108000, sceneHint: "9–13 scenes" },
+};
+/** Default when the user left targetLength on "decide for me". */
+exports.DEFAULT_DURATION_BUDGET = exports.DURATION_BUDGETS.walkthrough;
+function budgetForLength(targetLength) {
+    return targetLength ? exports.DURATION_BUDGETS[targetLength] : exports.DEFAULT_DURATION_BUDGET;
+}
+// ─── system prompt ───────────────────────────────────────────────────────────
+const SCENE_VOCABULARY = `
+SCENE TYPES (choose per beat; each is a Layer-A template that renders deterministically):
+- "logoReveal"      — brand sting to open/close. { tagline? }.
+- "bigStatement"    — large kinetic words, text-led value-prop. { lines[] (each line may mark ONE emphasized span with **double asterisks**), kicker? }. Best for kinetic/energetic openers + punchy value beats.
+- "problem"         — the pain, headline + scattered context chips. { headline, motifs[] (short pain phrases) }.
+- "featureShowcase" — a fake, brand-themed product screen (app chrome + sidebar + topbar) with an animated cursor operating it. { title, surface (one of: search|form|table|detail|chat|editor|analysis|marketplace|dashboard), cursorTypes? (text the cursor types), activeNav?, cards[]{title,subtitle?,badge?,badgeKind?,icon?}, screenshotUrl?, videoUrl? }. THE clean-ui-walkthrough centerpiece. Use when you can plausibly synthesize the UI OR embed a real screenshot/clip (videoUrl plays a real clip in the content region).
+- "splitFeature"    — bold headline on one side, an ISOLATED UI panel/screenshot on the other, numbered "STEP n —" eyebrow. { headline, body?, stepLabel?, side (left|right), screenshotUrl? OR videoUrl? OR cards[] }. The split-headline style; no app chrome, no cursor.
+- "deviceMockup"    — real screenshot(s) OR a real video clip composited into a 3D-perspective device frame with a camera move. { device (browser|laptop|phone|tablet), screenshotUrls[] (image assets), videoUrl? (a clip plays inside the frame — screenshots optional when set), motion (tilt|parallax|scroll|zoom-in|orbit), headline? }. REQUIRES real media — only use when screenshots OR a video asset are provided.
+- "mediaShot"       — ONE full-bleed image or clip fills the whole frame (cover-fit) under a slow camera move, with an optional SHORT headline over a readability scrim. { imageUrl? OR videoUrl?, headline?, motion (slow-zoom|drift|static), scrim (default true) }. The home for lifestyle/atmosphere/emotional media — a user photo/b-roll or a generated asset. Deliberately chrome-free: this is contextual imagery, NEVER a product-UI stand-in.
+- "chat"            — an AI-assistant conversation surface. { title, turns[]{role(user|assistant),text,chips?[]} }.
+- "dashboard"       — metrics + a simple chart. { title, stats[]{label,value?(number for count-up)|valueText?,suffix?,icon?}, chart[] (0..1 normalized bars) }.
+- "docAnalysis"     — a document being scanned, insight rows revealed. { title, insights[]{title,subtitle?,badge?,badgeKind?} }.
+- "cardGrid"        — a grid of feature cards. { title, cards[] (>=1) }.
+- "stats"           — a metric wall (count-up numbers). { headline?, stats[] (>=1) }.
+- "cta"             — closing call-to-action. { headline, buttonText, url?, stats[]? }.
+
+EVERY scene also takes: id (stable slug), durationMs (int), caption?{title,sub?} (VO-ready lower-third), narrationHint? (seed for the later script stage).`;
+/**
+ * Custom-scene guidance. Appended to the scene vocabulary only when the Layer-B
+ * codegen agent is enabled on the worker (`allowCustomScenes`). When it is off we
+ * emit the hard prohibition instead, so a spec never carries a `custom` scene the
+ * pipeline can't author — behavior is identical to before Phase 9 until the flag
+ * flips. When on, the planner may PROPOSE a custom scene by writing an `intent`
+ * brief; a specialist codegen agent (Layer B) authors the actual TSX afterward.
+ */
+const CUSTOM_SCENE_ALLOWED = `
+CUSTOM SCENES (choose on FIT, not as a last resort): The Layer-A templates above are the fast path, but they only cover common beats. QUALITY COMES FIRST — for each beat, pick the template that represents it WELL, and if the best-fit template would only APPROXIMATE it (forcing the concept into the wrong structure, dropping/misusing content, or reading as a generic panel), author a type:"custom" scene instead. Do NOT stretch a template to fit — a beat rendered in the wrong template is a worse outcome than the extra time/tokens a custom scene costs.
+
+Poor template fits that SHOULD usually be custom (illustrative, not exhaustive): a numbered step-by-step / how-it-works flow with connected steps; a side-by-side comparison ("us vs them", before/after); a bespoke data-visualization (timeline, funnel, map, graph beyond the dashboard's simple bars); a pricing/tier layout; an integrations/logo constellation; an unusual kinetic-typography composition; a novel arrangement of a product surface the templates don't model.
+
+For a custom scene set only: type:"custom", a stable id, durationMs, an optional caption/narrationHint, optional props, and — REQUIRED — a rich \`intent\`: a precise natural-language brief describing what the scene shows, how it animates across its duration (beats/motion over time), which Layer-0 primitives to lean on, and the on-brand look. Do NOT write any code; a specialist codegen agent authors the TSX from your intent.
+
+Budget: use as many custom scenes as the story genuinely needs — there is NO fixed cap — but each is authored individually, so choose deliberately (a typical video has 1–3). The opener/closer are well served by logoReveal/cta; keep those as templates unless the brand truly needs a bespoke sting.`;
+const CUSTOM_SCENE_DISALLOWED = `
+Do NOT emit type:"custom" — that path is authored by a different agent.`;
+/**
+ * Generated-media guidance. The planner may REQUEST AI-generated images/clips
+ * (declared in `generatedAssets`, cited as `gen://<id>`) and a deterministic
+ * pipeline stage materializes them before render. The PLANNING is the point:
+ * deciding when generation genuinely serves the product's story, what exactly
+ * to generate, and where it sits — most demos should request nothing.
+ * `DEMO_GEN_ASSETS_DISABLED` swaps in the prohibition as an emergency brake.
+ */
+const GENERATED_MEDIA_ALLOWED = `
+GENERATED MEDIA (you may commission AI-generated images/clips — decide like a creative director):
+Declare each request in top-level generatedAssets[]: { id (stable slug), kind ("image"|"video"), prompt (the full generation prompt), purpose (which beat it serves + why), aspect? (defaults to the video's), durationSec? (video, 2–8) }, then cite it from a scene media slot as the literal string "gen://<id>". A pipeline stage generates every request and swaps in the real URL; a failed generation simply degrades the scene, so never build a beat that is EMPTY without its asset.
+
+WHEN to commission (a decision ladder — real assets always outrank generated ones):
+- The product/service has no capturable UI (a physical product, a service, an API/CLI, a marketplace of physical goods) and the video needs a hero or in-context visual of it.
+- A beat's emotional register needs atmosphere the templates can't code — the problem's messy real world, the outcome's calm, the audience's environment (a kitchen, a job site, a clinic).
+- A cinematic/kinetic beat would be elevated by an abstract branded motion backdrop (video kind, cited from a mediaShot).
+DO NOT commission: fake product-UI "screenshots" (synthetic UI must be CODED featureShowcase/chat/dashboard surfaces — visibly designed, never photoreal fakes); anything a provided screenshot/asset already covers; generic decoration on beats a template already serves. MOST SaaS demos need ZERO generated assets — commission because THIS product's story demands it, not because the capability exists.
+
+WHERE "gen://<id>" may be cited: mediaShot.imageUrl / mediaShot.videoUrl (its primary home), splitFeature.screenshotUrl / splitFeature.videoUrl (the isolated side visual), and custom-scene props. NOT on deviceMockup or featureShowcase — those present media as the product's real screen.
+
+HOW to write the generation prompt (you are prompting a top image/video model):
+- Concrete subject + composition + lighting/mood + color grade, in one dense paragraph. Anchor it to the brand: name the palette hex codes as accent colors and match style.visual (cinematic → filmic shallow depth; minimal-calm → negative space, soft light; energetic-punchy → bold color, hard light).
+- ABSOLUTELY no readable text, words, letters, logos, or UI in the output — models render text badly and fake UI is banned; all text lives in overlays.
+- video: describe ONE continuous shot with explicit motion (what moves, how fast, camera behavior), no cuts, loop-friendly (ends near where it starts when possible).
+Caps: at most 4 images + 1 video per spec (requests beyond the cap are dropped in declaration order — declare the most important first).`;
+const GENERATED_MEDIA_DISALLOWED = `
+Do NOT declare generatedAssets and do NOT cite any "gen://" URL — asset generation is disabled; use only provided media.`;
+const STYLE_TAXONOMY = `
+STYLE (top-level, cross-cutting — re-skins EVERY scene; this is the anti-overfit axis):
+- visual: clean-ui-walkthrough | split-headline | kinetic-typography | cinematic | minimal-calm | energetic-punchy
+- pace: fast | medium | slow
+- colorMood: light | dark | brand-forward
+- audioIntent: captions | voiceover | music   (controls ON-SCREEN TEXT DENSITY: captions=headline-led, voiceover=sparse text, music=minimal text)
+- motion: subtle | balanced | dynamic
+
+narrative (drives scene ordering + tone): problem-solution | feature-showcase | day-in-the-life | hero-workflow | value-prop
+aspect: 16:9 | 9:16 | 1:1 | 4:5     fps: 30
+
+STYLE→SCENE affinity (guidance, not a straitjacket — pick what fits the product):
+- clean-ui-walkthrough → lean on featureShowcase (cursor operating the app) + chat/dashboard/docAnalysis; logoReveal open, cta close.
+- split-headline → splitFeature beats with STEP labels + isolated panels; minimal chrome.
+- kinetic-typography / energetic-punchy → bigStatement openers, deviceMockup (if screenshots) or featureShowcase, snappy short beats, stats, punchy cta.
+- cinematic / minimal-calm → slower bigStatement + one hero surface, lots of whitespace, glow/rings decor.`;
+function buildDemoAuthorSystemPrompt(opts = {}) {
+    const customGuidance = opts.allowCustomScenes
+        ? CUSTOM_SCENE_ALLOWED
+        : CUSTOM_SCENE_DISALLOWED;
+    const generatedMediaGuidance = opts.allowGeneratedAssets !== false
+        ? GENERATED_MEDIA_ALLOWED
+        : GENERATED_MEDIA_DISALLOWED;
+    return `You are the lead motion designer + creative director for VidSpotAI's autonomous SaaS product-demo generator. You author a single DemoSpec (returned via the provided tool) that a Remotion engine renders to a broadcast-quality MP4 with ZERO further human effort. Your bar is "better than a hand-made Product Hunt launch video."
+
+You are given a product's facts, its brand tokens, optional real product screenshots (as images you can SEE), and the user's answers to a style wizard. Produce a complete, ordered DemoSpec.
+
+${SCENE_VOCABULARY}
+${customGuidance}
+${generatedMediaGuidance}
+
+${STYLE_TAXONOMY}
+
+HARD RULES (violating these breaks the render or the brand):
+1. NEVER invent a media URL. Only use screenshot URLs from the "Available screenshots" list (on featureShowcase.screenshotUrl / splitFeature.screenshotUrl / deviceMockup.screenshotUrls) and video URLs from the "Featured media" list (on featureShowcase.videoUrl / splitFeature.videoUrl / deviceMockup.videoUrl), each copied VERBATIM. The ONE exception: "gen://<id>" refs to your OWN declared generatedAssets, where the GENERATED MEDIA rules allow them. If no screenshots are provided, do NOT emit a screenshot-only deviceMockup, and author featureShowcase surfaces as fully synthetic (coded) UI.
+5. FEATURED MEDIA the user attached (the "Featured media" list) MUST appear in the video — give each asset at least one scene: a video clip on a deviceMockup/splitFeature/featureShowcase videoUrl, an image on a screenshotUrl. Honor any placement note the user gave.
+2. Use the brand's colors as given — do not restyle them. Copy is yours; palette is theirs.
+3. The productName is overlay text; never bury it inside a screenshot description or expect the engine to draw it into a fake UI illegibly.
+4. Respect any wizard answer the user explicitly set (visual/pace/colorMood/audioIntent/narrative/aspect/features). Only choose freely for the axes they left unset ("decide for me").
+
+QUALITY BAR (observed in the reference demos — hit all of these):
+- Invent realistic, domain-specific data (names, rows, metrics, chat copy) — never lorem/placeholder.
+- Match on-screen text density to audioIntent (music → almost no text; captions → a headline per beat).
+- Give featureShowcase scenes a concrete cursorTypes string + a sensible activeNav so the walkthrough feels operated, not static.
+- Open with identity (logoReveal or a bigStatement value-prop), pay off with a cta. Order scenes to tell the chosen narrative.
+- Write a caption{title,sub?} for beats that carry a narration point (skip captions on pure kinetic/music beats). Seed narrationHint on feature beats for the later voiceover stage.
+- Prefer deviceMockup / splitFeature.screenshotUrl for authenticated apps you cannot convincingly fake; prefer coded featureShowcase when you want a cursor walkthrough and can plausibly synthesize the surface.
+
+DISTINCTIVENESS (every video must feel authored for THIS product, not filled into a house template):
+- Derive the arc from the product's actual story. "logoReveal → problem → bigStatement → features → stats → cta" is ONE possible skeleton, not the format — reorder, drop, or swap beats whenever the product suggests it: open on the product surface for a visually striking tool, lead with the workflow for hero-workflow, open on a bold claim for value-prop, skip the problem beat for a product whose value is self-evident.
+- Before returning, check your scene-type sequence: if it matches the generic skeleton out of inertia rather than choice, rework the weakest beat into a different type — or a custom scene.
+- When custom scenes are allowed, the product's ONE signature moment (its "aha" interaction or differentiator) is the first custom-scene candidate — bespoke motion pays off most there.
+- Numbers presented as the product's traction/social proof (user counts, ratings, "X% faster") must come from the provided facts (site copy, user input, screenshots). If none exist, do NOT fabricate adoption claims — build the stats beat from capability facts (languages supported, tools included, time-to-set-up) or skip it. Invented data belongs INSIDE synthetic UI surfaces, never in claims about the product itself.
+
+DURATION: size each scene's durationMs so the TOTAL lands near the target you are told, roughly 2–4s per beat (faster for kinetic/energetic, slower for cinematic/minimal-calm). Integer milliseconds.
+
+Return ONLY the DemoSpec via the tool. Author every field you can; the engine applies defaults for anything you omit.`;
+}
+// ─── user message ────────────────────────────────────────────────────────────
+/** Screenshots enumerated with their real URLs so the author can cite them verbatim. */
+function screenshotSection(urls) {
+    if (!urls?.length) {
+        return `Available screenshots: NONE. Do not emit deviceMockup; author any product UI as fully synthetic featureShowcase surfaces.`;
+    }
+    const lines = urls.map((u, i) => `  [${i}] ${u}`).join("\n");
+    return `Available screenshots (${urls.length}) — the ONLY URLs you may use, copied verbatim, on screenshotUrl/screenshotUrls:\n${lines}\nThe same images are attached to this message for you to see.`;
+}
+/** User-attached media that must be FEATURED in the video, with placement hints. */
+function mediaAssetSection(assets) {
+    if (!assets?.length)
+        return "";
+    const lines = assets.map((a, i) => {
+        const bits = [`  [${i}] ${a.kind.toUpperCase()} ${a.url}`];
+        if (a.label)
+            bits.push(`label: "${a.label}"`);
+        if (a.intent)
+            bits.push(`use: "${a.intent}"`);
+        if (a.kind === "video" && a.durationMs) {
+            bits.push(`~${Math.round(a.durationMs / 1000)}s`);
+        }
+        return bits.join(" · ");
+    });
+    return [
+        `Featured media (${assets.length}) — user-attached assets that MUST appear in the video, copied VERBATIM:`,
+        ...lines,
+        "Place each VIDEO url on a deviceMockup/splitFeature/featureShowcase videoUrl (a real clip playing inside the frame); place each IMAGE url on a screenshotUrl. Give every asset at least one scene, and honor any stated use.",
+    ].join("\n");
+}
+/** The agent's dynamic clarifying answers — authoritative steering the author must honor. */
+function clarifyAnswersSection(answers) {
+    const entries = Object.entries(answers ?? {});
+    if (entries.length === 0)
+        return "";
+    const lines = entries.map(([id, v]) => {
+        const val = Array.isArray(v) ? v.join(", ") : String(v);
+        return `  - ${id}: ${val}`;
+    });
+    return ["User clarifications (honor these — they answered them just now):", ...lines].join("\n");
+}
+/** Which wizard axes the user pinned vs left for you to decide. */
+function wizardSection(answers) {
+    const a = answers ?? {};
+    const pin = (label, v) => v === undefined || v === null || (Array.isArray(v) && v.length === 0)
+        ? `  ${label}: decide for me`
+        : `  ${label}: ${Array.isArray(v) ? v.join(", ") : String(v)} (LOCKED — must honor)`;
+    return [
+        "Wizard answers (LOCKED axes must be honored exactly; 'decide for me' is yours to choose):",
+        pin("visual style", a.visualStyle),
+        pin("pace", a.pace),
+        pin("target length", a.targetLength),
+        pin("narrative", a.narrative),
+        pin("aspect", a.aspect),
+        pin("color mood", a.colorMood),
+        pin("audio intent", a.audioIntent),
+        pin("features to highlight", a.features),
+    ].join("\n");
+}
+/** Build the user-turn text (images are attached separately as imageUrls). */
+function buildDemoAuthorUserText(input) {
+    const budget = budgetForLength(input.answers?.targetLength);
+    const brandColors = input.brand.colors ?? { palette: [] };
+    const identity = input.brand.identity ?? {};
+    const fonts = input.brand.fonts ?? {};
+    const facts = [
+        `Product name: ${input.productName}`,
+        input.tagline ? `Tagline: ${input.tagline}` : null,
+        input.description ? `Description: ${input.description}` : null,
+        input.features?.length ? `Features: ${input.features.join(", ")}` : null,
+        input.audience ? `Audience: ${input.audience}` : null,
+        input.websiteUrl ? `Website: ${input.websiteUrl}` : null,
+        input.pageSummary
+            ? `From the website (context, not verbatim): ${input.pageSummary}`
+            : null,
+        input.repoNotes ? `Notes from the author: ${input.repoNotes}` : null,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const brand = [
+        `Brand name: ${identity.brandName ?? input.productName}`,
+        identity.wordmark ? `Wordmark: ${identity.wordmark}` : null,
+        identity.logoUrl ? `Logo URL: ${identity.logoUrl}` : null,
+        `Primary color: ${brandColors.primary ?? "(unset — pick an on-brand default)"}`,
+        `Accent color: ${brandColors.accent ?? "(unset — pick a complementary accent)"}`,
+        brandColors.palette?.length ? `Palette: ${brandColors.palette.join(", ")}` : null,
+        fonts.heading ? `Heading font: ${fonts.heading}` : null,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    return [
+        `PRODUCT\n${facts}`,
+        `BRAND (use colors verbatim)\n${brand}`,
+        wizardSection(input.answers),
+        clarifyAnswersSection(input.clarifyAnswers),
+        screenshotSection(input.screenshotUrls),
+        mediaAssetSection(input.mediaAssets),
+        `TARGET DURATION: ~${Math.round(budget.target / 1000)}s total (stay within ${Math.round(budget.min / 1000)}–${Math.round(budget.max / 1000)}s), about ${budget.sceneHint}.`,
+        `Now author the DemoSpec. Set productName="${input.productName}". Fill brand.colors from the brand block above. Choose freely only for wizard axes marked "decide for me".`,
+    ]
+        .filter((s) => s && s.trim().length > 0)
+        .join("\n\n");
+}

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

@@ -0,0 +1,20 @@
+import { IDemoVideoWizardAnswers } from "../../models/demoVideoProject.model";
+export interface DemoCreditEstimate {
+    amountUsd: number;
+    amountCredits: number;
+    breakdown: Record<string, number>;
+    /** Total seconds of output the estimate assumed (from the target-length budget). */
+    assumedSeconds: number;
+}
+/**
+ * Estimate the credits to charge upfront for a demo-video job.
+ *
+ * `withVoiceover` toggles the Phase-5 script+TTS+final-render legs. Phase 4
+ * ships draft-only (silent) so the default is false — the draft IS the
+ * deliverable until the audio pipeline lands.
+ */
+export declare function estimateDemoVideoCredits(args: {
+    answers?: IDemoVideoWizardAnswers;
+    withVoiceover?: boolean;
+}): DemoCreditEstimate;
+//# sourceMappingURL=demoCredits.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"demoCredits.d.ts","sourceRoot":"","sources":["../../../src/services/demo/demoCredits.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AA4B9E,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,oFAAoF;IACpF,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,OAAO,CAAC,EAAE,uBAAuB,CAAC;IAClC,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,GAAG,kBAAkB,CAqBrB"}

package/lib/services/demo/demoCredits.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateDemoVideoCredits = estimateDemoVideoCredits;
+const creditUnit_1 = require("../../globals/creditUnit");
+const demoAuthorPrompt_1 = require("./demoAuthorPrompt");
+/**
+ * Cost model for the SaaS Demo Video generator (plan §8).
+ *
+ * Components: LLM planning (one structured+vision call) + server-side Remotion
+ * render compute (dominant, scales with output length) + — once Phase 5 lands —
+ * a script LLM pass + ElevenLabs TTS + a second (final) render.
+ *
+ * Rates are conservative upper bounds used to DEDUCT upfront (deduct-first, like
+ * image/video). The worker reconciles to actual at finalize (refunds the unused
+ * remainder). USD → credits via the single CREDITS_PER_USD source of truth.
+ */
+// One Claude structured-output call with a few screenshots as vision.
+const PLANNING_USD = 0.04;
+// Our Remotion render compute, per second of OUTPUT video. Draft = half-res
+// (cheaper); standard/final = full-res. Coarse — we own the box, but credits
+// must track the compute value delivered.
+const RENDER_USD_PER_SEC_DRAFT = 0.01;
+const RENDER_USD_PER_SEC_FINAL = 0.02;
+// Script LLM pass (Phase 5) — small structured call over the known timeline.
+const SCRIPT_USD = 0.02;
+// ElevenLabs TTS (Phase 5). ~14 chars/sec of speech is a safe upper bound.
+const TTS_USD_PER_1K_CHARS = 0.18;
+const TTS_CHARS_PER_SEC = 14;
+/**
+ * Estimate the credits to charge upfront for a demo-video job.
+ *
+ * `withVoiceover` toggles the Phase-5 script+TTS+final-render legs. Phase 4
+ * ships draft-only (silent) so the default is false — the draft IS the
+ * deliverable until the audio pipeline lands.
+ */
+function estimateDemoVideoCredits(args) {
+    const seconds = Math.round((0, demoAuthorPrompt_1.budgetForLength)(args.answers?.targetLength).target / 1000);
+    const withVo = args.withVoiceover ?? false;
+    const breakdown = {
+        planning: PLANNING_USD,
+        renderDraft: seconds * RENDER_USD_PER_SEC_DRAFT,
+    };
+    if (withVo) {
+        breakdown.script = SCRIPT_USD;
+        breakdown.voiceover = ((seconds * TTS_CHARS_PER_SEC) / 1000) * TTS_USD_PER_1K_CHARS;
+        breakdown.renderFinal = seconds * RENDER_USD_PER_SEC_FINAL;
+    }
+    const amountUsd = Object.values(breakdown).reduce((s, v) => s + v, 0);
+    const amountCredits = Math.max(creditUnit_1.MIN_CREDITS_PER_PAID_OP, Math.ceil(amountUsd * creditUnit_1.CREDITS_PER_USD));
+    return { amountUsd, amountCredits, breakdown, assumedSeconds: seconds };
+}

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

@@ -0,0 +1,43 @@
+import { DemoSpec } from "../../schemas/demoSpec.schema";
+export type DroppedMediaKind = "image" | "video";
+export interface DroppedMedia {
+    sceneId: string;
+    sceneType: string;
+    field: string;
+    url: string;
+    kind: DroppedMediaKind;
+    reason: string;
+}
+export interface MediaSanitizeResult {
+    /** A deep-cloned spec with all unreachable media fields removed. */
+    spec: DemoSpec;
+    /** Everything that was dropped, for observability/logging. */
+    dropped: DroppedMedia[];
+}
+export interface MediaGuardOptions {
+    /** Per-request timeout (ms). Default 8000. */
+    timeoutMs?: number;
+    /** Injectable fetch (tests). Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Preflight a single media URL: is it reachable AND does it look like the
+ * expected kind (image/video), i.e. NOT an HTML/XML error page and not the wrong
+ * media type. Exported so other stages (e.g. website logo extraction) reuse the
+ * exact same "is this a real image/video URL" test instead of re-implementing it
+ * — one source of truth for reachability. Non-http(s) URLs (data:/blob:) are
+ * trusted (`{ ok: true }`).
+ */
+export declare function checkMediaReachable(url: string, kind: DroppedMediaKind, options?: MediaGuardOptions): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Preflight every media URL in `spec` and return a cloned spec with the
+ * unreachable ones removed. Reachability of all URLs is checked concurrently;
+ * order of `dropped` follows scene/field order for stable logs.
+ */
+export declare function sanitizeDemoSpecMedia(spec: DemoSpec, options?: MediaGuardOptions): Promise<MediaSanitizeResult>;
+//# sourceMappingURL=demoMediaGuard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"demoMediaGuard.d.ts","sourceRoot":"","sources":["../../../src/services/demo/demoMediaGuard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AA+BpE,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,IAAI,EAAE,QAAQ,CAAC;IACf,8DAA8D;IAC9D,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AASD;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,gBAAgB,EACtB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAMvD;AAmDD;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,QAAQ,EACd,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,mBAAmB,CAAC,CAyG9B"}

package/lib/services/demo/demoMediaGuard.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkMediaReachable = checkMediaReachable;
+exports.sanitizeDemoSpecMedia = sanitizeDemoSpecMedia;
+/**
+ * Media reachability guard for the SaaS Demo Video pipeline.
+ *
+ * WHY THIS EXISTS — Remotion's `<Video>` (render path) loads a clip's duration
+ * behind a `delayRender()` handle that only clears on the media element's
+ * `loadedmetadata` event. A broken/expired/blocked video URL never fires that
+ * event, and an in-component `onError` re-render is NOT flushed while
+ * `renderStill`/`renderMedia` is blocked waiting on the handle — so the handle
+ * times out and the ENTIRE render fails (verified against remotion@4.0.236; the
+ * `deviceMockup-broken` / `splitFeature-broken` stress fixtures reproduce it).
+ * Unlike `<Img>` (whose `onError` degrades to a gradient), a 404 video cannot be
+ * salvaged inside the render — there is simply no frame to draw.
+ *
+ * The correct-by-construction fix is therefore UPSTREAM: preflight every media
+ * URL in a spec and DROP the ones that don't resolve to real media BEFORE the
+ * spec reaches the renderer. The templates already degrade a missing
+ * screenshot/video to their neutral coded surface, so a dropped URL renders
+ * cleanly instead of crashing. (The in-template `onError` paths remain as
+ * defense-in-depth — they cover the Player/preview and image assets.)
+ *
+ * Node-only (uses global `fetch`); called by the demo worker before render and
+ * by the template stress harness so both exercise the same sanitization.
+ */
+/** Per-scene media fields we validate, keyed by scene type at call sites. */
+const IMAGE_SINGLE_FIELDS = ["screenshotUrl", "imageUrl"];
+const IMAGE_ARRAY_FIELDS = ["screenshotUrls"];
+const VIDEO_FIELDS = ["videoUrl"];
+const DEFAULT_TIMEOUT_MS = 8000;
+/** Only http(s) URLs are network-checked; data:/blob:/empty are trusted as-is. */
+function isCheckableUrl(url) {
+    return typeof url === "string" && /^https?:\/\//i.test(url.trim());
+}
+/**
+ * Preflight a single media URL: is it reachable AND does it look like the
+ * expected kind (image/video), i.e. NOT an HTML/XML error page and not the wrong
+ * media type. Exported so other stages (e.g. website logo extraction) reuse the
+ * exact same "is this a real image/video URL" test instead of re-implementing it
+ * — one source of truth for reachability. Non-http(s) URLs (data:/blob:) are
+ * trusted (`{ ok: true }`).
+ */
+async function checkMediaReachable(url, kind, options = {}) {
+    if (!isCheckableUrl(url))
+        return { ok: true };
+    return reachable(url, kind, {
+        timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        fetchImpl: options.fetchImpl ?? fetch,
+    });
+}
+async function reachable(url, kind, opts) {
+    const { timeoutMs, fetchImpl } = opts;
+    const doFetch = async (method) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            return await fetchImpl(url, {
+                method,
+                signal: controller.signal,
+                // A 1-byte range keeps the GET fallback cheap (servers that reject HEAD).
+                ...(method === "GET" ? { headers: { Range: "bytes=0-0" } } : {}),
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    try {
+        let res = await doFetch("HEAD");
+        // Some hosts don't implement HEAD — retry with a tiny ranged GET.
+        if (res.status === 405 || res.status === 501)
+            res = await doFetch("GET");
+        if (res.status < 200 || res.status >= 300) {
+            return { ok: false, reason: `status ${res.status}` };
+        }
+        const contentType = (res.headers.get("content-type") ?? "").toLowerCase();
+        // Empty content-type (some CDNs on HEAD) is accepted — we only REJECT a
+        // positively-wrong type (e.g. an XML/HTML error page served as a screenshot,
+        // the exact 403-page-as-media defect we shipped).
+        if (contentType) {
+            const looksLikeError = /(text\/html|application\/xml|text\/xml)/.test(contentType);
+            if (looksLikeError)
+                return { ok: false, reason: `content-type ${contentType}` };
+            if (kind === "image" && contentType.startsWith("video/")) {
+                return { ok: false, reason: `content-type ${contentType} (expected image)` };
+            }
+            if (kind === "video" && contentType.startsWith("image/")) {
+                return { ok: false, reason: `content-type ${contentType} (expected video)` };
+            }
+        }
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, reason: e.message || "fetch failed" };
+    }
+}
+/**
+ * Preflight every media URL in `spec` and return a cloned spec with the
+ * unreachable ones removed. Reachability of all URLs is checked concurrently;
+ * order of `dropped` follows scene/field order for stable logs.
+ */
+async function sanitizeDemoSpecMedia(spec, options = {}) {
+    const opts = {
+        timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        fetchImpl: options.fetchImpl ?? fetch,
+    };
+    const refs = [];
+    for (const scene of spec.scenes) {
+        const s = scene;
+        for (const field of IMAGE_SINGLE_FIELDS) {
+            if (isCheckableUrl(s[field]))
+                refs.push({ scene, field, url: s[field], kind: "image" });
+        }
+        for (const field of VIDEO_FIELDS) {
+            if (isCheckableUrl(s[field]))
+                refs.push({ scene, field, url: s[field], kind: "video" });
+        }
+        for (const field of IMAGE_ARRAY_FIELDS) {
+            const arr = s[field];
+            if (Array.isArray(arr)) {
+                arr.forEach((u, index) => {
+                    if (isCheckableUrl(u))
+                        refs.push({ scene, field, url: u, index, kind: "image" });
+                });
+            }
+        }
+    }
+    // The brand logo (`brand.identity.logoUrl`) is rendered by <LogoRevealScene>'s
+    // <Img> — a bad one would fail that render exactly like a bad screenshot. It's
+    // not a scene field, so preflight it here too (any source: user/GitHub/website)
+    // and strip it from the cloned spec if it doesn't resolve to a real image.
+    const brandLogoUrl = spec.brand?.identity?.logoUrl;
+    const checkBrandLogo = isCheckableUrl(brandLogoUrl);
+    const [checks, brandLogoCheck] = await Promise.all([
+        Promise.all(refs.map((r) => reachable(r.url, r.kind, opts))),
+        checkBrandLogo
+            ? reachable(brandLogoUrl, "image", opts)
+            : Promise.resolve({ ok: true }),
+    ]);
+    // Build the set of (sceneId, field, index?) references to drop.
+    const dropped = [];
+    const dropBrandLogo = checkBrandLogo && !brandLogoCheck.ok;
+    if (dropBrandLogo && !brandLogoCheck.ok) {
+        dropped.push({
+            sceneId: "__brand__",
+            sceneType: "brand",
+            field: "identity.logoUrl",
+            url: brandLogoUrl,
+            kind: "image",
+            reason: brandLogoCheck.reason,
+        });
+    }
+    const dropSingle = new Set(); // key: `${sceneId}|${field}`
+    const dropArrayItem = new Set(); // key: `${sceneId}|${field}|${index}`
+    refs.forEach((r, i) => {
+        const check = checks[i];
+        if (check.ok)
+            return;
+        dropped.push({
+            sceneId: r.scene.id,
+            sceneType: r.scene.type,
+            field: r.field,
+            url: r.url,
+            kind: r.kind,
+            reason: check.reason,
+        });
+        if (r.index === undefined)
+            dropSingle.add(`${r.scene.id}|${r.field}`);
+        else
+            dropArrayItem.add(`${r.scene.id}|${r.field}|${r.index}`);
+    });
+    if (dropped.length === 0)
+        return { spec, dropped };
+    // Clone + strip. Structured deep clone keeps the spec immutable for the caller.
+    const cleanedScenes = spec.scenes.map((scene) => {
+        const clone = { ...scene };
+        for (const field of [...IMAGE_SINGLE_FIELDS, ...VIDEO_FIELDS]) {
+            if (dropSingle.has(`${scene.id}|${field}`))
+                delete clone[field];
+        }
+        for (const field of IMAGE_ARRAY_FIELDS) {
+            const arr = clone[field];
+            if (Array.isArray(arr)) {
+                clone[field] = arr.filter((_, index) => !dropArrayItem.has(`${scene.id}|${field}|${index}`));
+            }
+        }
+        return clone;
+    });
+    // Strip an unreachable brand logo so <LogoRevealScene> falls back to its
+    // wordmark instead of throwing on a dead <Img>.
+    const cleanedBrand = dropBrandLogo
+        ? {
+            ...spec.brand,
+            identity: (() => {
+                const id = { ...(spec.brand?.identity ?? {}) };
+                delete id.logoUrl;
+                return id;
+            })(),
+        }
+        : spec.brand;
+    return {
+        spec: { ...spec, brand: cleanedBrand, scenes: cleanedScenes },
+        dropped,
+    };
+}

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

@@ -0,0 +1,13 @@
+import { DemoSpec } from "../../schemas/demoSpec.schema";
+export interface DemoMusicSelection {
+    url: string;
+    attribution?: string;
+    mood?: string;
+    bpm?: number;
+}
+/**
+ * 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>;
+//# sourceMappingURL=demoMusic.d.ts.map

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

@@ -0,0 +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"}