vidspotai-shared 1.0.94 → 1.0.96

package/lib/services/demo/demoAuthorNormalize.js

@@ -0,0 +1,327 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEMO_GEN_ASSET_MAX_VIDEOS = exports.DEMO_GEN_ASSET_MAX_IMAGES = void 0;
+exports.isGenAssetRef = isGenAssetRef;
+exports.genAssetIdFromRef = genAssetIdFromRef;
+exports.collectGenAssetRefs = collectGenAssetRefs;
+exports.normalizeDemoSpec = normalizeDemoSpec;
+exports.specTotalMs = specTotalMs;
+const demoSpec_schema_1 = require("../../schemas/demoSpec.schema");
+const demoAuthorPrompt_1 = require("./demoAuthorPrompt");
+// ─── 1. wizard pins ──────────────────────────────────────────────────────────
+/** Overwrite style/narrative/aspect axes the user explicitly locked. */
+function applyWizardPins(spec, answers, notes) {
+    if (!answers)
+        return spec;
+    const style = { ...spec.style };
+    let narrative = spec.narrative;
+    let aspect = spec.aspect;
+    if (answers.visualStyle && style.visual !== answers.visualStyle) {
+        notes.push(`visual: ${style.visual} → ${answers.visualStyle} (wizard pin)`);
+        style.visual = answers.visualStyle;
+    }
+    if (answers.pace && style.pace !== answers.pace) {
+        notes.push(`pace: ${style.pace} → ${answers.pace} (wizard pin)`);
+        style.pace = answers.pace;
+    }
+    if (answers.colorMood && style.colorMood !== answers.colorMood) {
+        notes.push(`colorMood: ${style.colorMood} → ${answers.colorMood} (wizard pin)`);
+        style.colorMood = answers.colorMood;
+    }
+    if (answers.audioIntent && style.audioIntent !== answers.audioIntent) {
+        notes.push(`audioIntent: ${style.audioIntent} → ${answers.audioIntent} (wizard pin)`);
+        style.audioIntent = answers.audioIntent;
+    }
+    if (answers.narrative && narrative !== answers.narrative) {
+        notes.push(`narrative: ${narrative} → ${answers.narrative} (wizard pin)`);
+        narrative = answers.narrative;
+    }
+    if (answers.aspect && aspect !== answers.aspect) {
+        notes.push(`aspect: ${aspect} → ${answers.aspect} (wizard pin)`);
+        aspect = answers.aspect;
+    }
+    return { ...spec, style, narrative, aspect };
+}
+// ─── 1.5 generated-asset requests (caps + reference accounting) ──────────────
+/** Hard caps on planner-requested AI media per spec (cost + wall-clock bound). */
+exports.DEMO_GEN_ASSET_MAX_IMAGES = 4;
+exports.DEMO_GEN_ASSET_MAX_VIDEOS = 1;
+/** Is this URL-slot value a reference to a declared generated asset? */
+function isGenAssetRef(url) {
+    return !!url && url.startsWith(demoSpec_schema_1.GEN_ASSET_URI_PREFIX);
+}
+/** `gen://hero-shot` → `hero-shot` (undefined when not a gen ref). */
+function genAssetIdFromRef(url) {
+    return url.slice(demoSpec_schema_1.GEN_ASSET_URI_PREFIX.length);
+}
+/** Every `gen://` ref AND every raw media string cited anywhere in a scene list
+ *  (typed media slots + custom-scene prop bags, walked deeply so codegen props
+ *  count as usage). */
+function collectGenAssetRefs(scenes) {
+    const ids = new Set();
+    const urls = new Set();
+    const visit = (value, depth) => {
+        if (depth > 6 || value == null)
+            return;
+        if (typeof value === "string") {
+            if (isGenAssetRef(value))
+                ids.add(genAssetIdFromRef(value));
+            else if (value)
+                urls.add(value);
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const v of value)
+                visit(v, depth + 1);
+            return;
+        }
+        if (typeof value === "object") {
+            for (const v of Object.values(value)) {
+                visit(v, depth + 1);
+            }
+        }
+    };
+    for (const scene of scenes) {
+        switch (scene.type) {
+            case "deviceMockup":
+                scene.screenshotUrls.forEach((u) => visit(u, 0));
+                visit(scene.videoUrl, 0);
+                break;
+            case "featureShowcase":
+            case "splitFeature":
+                visit(scene.screenshotUrl, 0);
+                visit(scene.videoUrl, 0);
+                break;
+            case "mediaShot":
+                visit(scene.imageUrl, 0);
+                visit(scene.videoUrl, 0);
+                break;
+            case "custom":
+                visit(scene.props, 0);
+                break;
+            default:
+                break;
+        }
+    }
+    return { ids, urls };
+}
+/** Dedupe ids (first declaration wins) + enforce the per-kind caps. READY
+ *  assets (already generated + paid for on a prior pass/revise) take cap
+ *  priority over pending requests; within each group, declaration order wins —
+ *  the planner is told to list by importance. Original order is preserved. */
+function capGeneratedAssets(assets, notes) {
+    const seen = new Set();
+    const deduped = [];
+    for (const asset of assets) {
+        if (seen.has(asset.id)) {
+            notes.push(`generatedAssets — dropped duplicate id "${asset.id}"`);
+            continue;
+        }
+        seen.add(asset.id);
+        deduped.push(asset);
+    }
+    const kept = new Set();
+    const counts = { image: 0, video: 0 };
+    const caps = { image: exports.DEMO_GEN_ASSET_MAX_IMAGES, video: exports.DEMO_GEN_ASSET_MAX_VIDEOS };
+    const isReady = (a) => a.status === "ready" && !!a.url;
+    for (const asset of [...deduped.filter(isReady), ...deduped.filter((a) => !isReady(a))]) {
+        if (counts[asset.kind] >= caps[asset.kind]) {
+            notes.push(`generatedAssets — dropped ${asset.kind} "${asset.id}" (cap ${caps[asset.kind]})`);
+            continue;
+        }
+        counts[asset.kind]++;
+        kept.add(asset.id);
+    }
+    return deduped.filter((a) => kept.has(a.id));
+}
+function sanitizeScreenshots(scenes, allowed, notes) {
+    // Placement policy: deviceMockup + featureShowcase present media AS the
+    // product's real screen, so they accept REAL media only — a generated image
+    // there would fabricate product UI. splitFeature side visuals and mediaShot
+    // full-bleed moments may cite generated assets (that's what they're for).
+    const images = allowed.realImages;
+    const videos = allowed.realVideos;
+    const anyImages = new Set([...allowed.realImages, ...allowed.genImages]);
+    const anyVideos = new Set([...allowed.realVideos, ...allowed.genVideos]);
+    const isImage = (u) => !!u && images.has(u);
+    const isVideo = (u) => !!u && videos.has(u);
+    const isAnyImage = (u) => !!u && anyImages.has(u);
+    const isAnyVideo = (u) => !!u && anyVideos.has(u);
+    const out = [];
+    for (const scene of scenes) {
+        switch (scene.type) {
+            case "deviceMockup": {
+                const valid = scene.screenshotUrls.filter((u) => images.has(u));
+                const validVideo = isVideo(scene.videoUrl) ? scene.videoUrl : undefined;
+                if (valid.length === 0 && !validVideo) {
+                    notes.push(`dropped deviceMockup "${scene.id}" — no valid media URLs`);
+                    continue; // drop the scene entirely
+                }
+                if (valid.length !== scene.screenshotUrls.length) {
+                    notes.push(`deviceMockup "${scene.id}" — removed ${scene.screenshotUrls.length - valid.length} invalid screenshot URL(s)`);
+                }
+                if (scene.videoUrl && !validVideo) {
+                    notes.push(`deviceMockup "${scene.id}" — stripped invented videoUrl`);
+                }
+                out.push({
+                    ...scene,
+                    screenshotUrls: valid,
+                    ...(validVideo ? { videoUrl: validVideo } : { videoUrl: undefined }),
+                });
+                break;
+            }
+            case "featureShowcase":
+            case "splitFeature": {
+                // splitFeature side visuals may cite generated assets; featureShowcase
+                // (media inside the fake-app surface = "the product's screen") may not.
+                const okImage = scene.type === "splitFeature" ? isAnyImage : isImage;
+                const okVideo = scene.type === "splitFeature" ? isAnyVideo : isVideo;
+                let next = scene;
+                if (scene.screenshotUrl && !okImage(scene.screenshotUrl)) {
+                    notes.push(`${scene.type} "${scene.id}" — stripped invented screenshotUrl (falls back to coded surface)`);
+                    const { screenshotUrl: _drop, ...rest } = next;
+                    next = rest;
+                }
+                if (scene.videoUrl && !okVideo(scene.videoUrl)) {
+                    notes.push(`${scene.type} "${scene.id}" — stripped invented videoUrl`);
+                    const { videoUrl: _dropV, ...rest } = next;
+                    next = rest;
+                }
+                out.push(next);
+                break;
+            }
+            case "mediaShot": {
+                // The full-bleed media home: real uploads AND generated assets both fine.
+                const validImage = isAnyImage(scene.imageUrl) ? scene.imageUrl : undefined;
+                const validVideo = isAnyVideo(scene.videoUrl) ? scene.videoUrl : undefined;
+                if (!validImage && !validVideo) {
+                    notes.push(`dropped mediaShot "${scene.id}" — no valid media URLs`);
+                    continue;
+                }
+                if (scene.imageUrl && !validImage) {
+                    notes.push(`mediaShot "${scene.id}" — stripped invented imageUrl`);
+                }
+                if (scene.videoUrl && !validVideo) {
+                    notes.push(`mediaShot "${scene.id}" — stripped invented videoUrl`);
+                }
+                out.push({ ...scene, imageUrl: validImage, videoUrl: validVideo });
+                break;
+            }
+            default:
+                out.push(scene);
+        }
+    }
+    return out;
+}
+// ─── 3. brand colors ─────────────────────────────────────────────────────────
+/** Force the user's brand tokens back onto the spec (the model authors copy, not palette). */
+function forceBrandColors(spec, input, notes) {
+    const given = input.brand.colors;
+    if (!given)
+        return spec;
+    const colors = { ...spec.brand.colors };
+    let changed = false;
+    if (given.primary && colors.primary !== given.primary) {
+        colors.primary = given.primary;
+        changed = true;
+    }
+    if (given.accent && colors.accent !== given.accent) {
+        colors.accent = given.accent;
+        changed = true;
+    }
+    if (given.palette?.length) {
+        colors.palette = given.palette;
+    }
+    if (changed)
+        notes.push(`brand colors forced to user tokens`);
+    return { ...spec, brand: { ...spec.brand, colors } };
+}
+// ─── 4. duration budget ──────────────────────────────────────────────────────
+/**
+ * Scale every scene's duration by a single factor so the total lands inside the
+ * budget window. Proportional scaling preserves the author's intended pacing
+ * (a 4s hero beat stays ~2× a 2s cut). Only scales when the total is outside
+ * [min,max]; snaps to `target` when it does. Enforces a per-scene floor.
+ */
+const MIN_SCENE_MS = 700;
+function fitDuration(scenes, budget, notes) {
+    const total = scenes.reduce((acc, s) => acc + s.durationMs, 0);
+    if (total >= budget.min && total <= budget.max)
+        return scenes;
+    const factor = budget.target / Math.max(total, 1);
+    notes.push(`total duration ${Math.round(total / 1000)}s outside ${Math.round(budget.min / 1000)}–${Math.round(budget.max / 1000)}s → scaled ×${factor.toFixed(2)} to ~${Math.round(budget.target / 1000)}s`);
+    return scenes.map((s) => ({
+        ...s,
+        durationMs: Math.max(MIN_SCENE_MS, Math.round(s.durationMs * factor)),
+    }));
+}
+// ─── orchestration ───────────────────────────────────────────────────────────
+/**
+ * Run the full deterministic normalize pipeline on a raw authored spec and
+ * return a schema-valid, render-ready DemoSpec plus the list of adjustments.
+ * Throws only if the model produced something with zero scenes (unrecoverable).
+ */
+function normalizeDemoSpec(raw, input) {
+    const notes = [];
+    const budget = (0, demoAuthorPrompt_1.budgetForLength)(input.answers?.targetLength);
+    // productName is authoritative from the caller, never the model.
+    let spec = { ...raw, productName: input.productName };
+    spec = applyWizardPins(spec, input.answers, notes);
+    spec = forceBrandColors(spec, input, notes);
+    // Planner-requested AI media: dedupe + cap FIRST so refs to dropped requests
+    // are treated as invented URLs by the sanitizer below.
+    const generatedAssets = capGeneratedAssets(spec.generatedAssets ?? [], notes);
+    // Allowed media sets: images = uploaded/captured screenshots + image assets;
+    // videos = the user's video assets. Only these URLs may survive on scene props.
+    // `gen://<id>` refs are allowed iff they point at a surviving declared asset of
+    // the matching kind — the asset-generation stage resolves them to real URLs.
+    // Which slots accept gen refs is decided per scene type in sanitizeScreenshots.
+    const imageAssetUrls = (input.mediaAssets ?? [])
+        .filter((a) => a.kind === "image")
+        .map((a) => a.url);
+    // Ready assets' RESOLVED urls are also allowed (in the gen sets, so placement
+    // policy still holds): on revise, the incoming spec's scenes already carry the
+    // substituted GCS URLs, and stripping them as "invented" would throw away
+    // media we already paid for.
+    const readyGenUrls = (kind) => generatedAssets
+        .filter((a) => a.kind === kind && a.status === "ready" && !!a.url)
+        .map((a) => a.url);
+    const genRef = (a) => `${demoSpec_schema_1.GEN_ASSET_URI_PREFIX}${a.id}`;
+    const allowed = {
+        realImages: new Set([...(input.screenshotUrls ?? []), ...imageAssetUrls]),
+        realVideos: new Set((input.mediaAssets ?? []).filter((a) => a.kind === "video").map((a) => a.url)),
+        genImages: new Set([
+            ...generatedAssets.filter((a) => a.kind === "image").map(genRef),
+            ...readyGenUrls("image"),
+        ]),
+        genVideos: new Set([
+            ...generatedAssets.filter((a) => a.kind === "video").map(genRef),
+            ...readyGenUrls("video"),
+        ]),
+    };
+    let scenes = sanitizeScreenshots(spec.scenes, allowed, notes);
+    if (scenes.length === 0) {
+        throw new Error("normalizeDemoSpec: authored spec has no renderable scenes after media sanitation");
+    }
+    scenes = fitDuration(scenes, budget, notes);
+    // Drop asset requests nothing cites anymore (refs may have been stripped or
+    // their scene dropped) — an unreferenced request is pure provider spend. A
+    // ready asset cited by its RESOLVED url (post-materialization spec) counts.
+    const cited = collectGenAssetRefs(scenes);
+    const referencedAssets = generatedAssets.filter((a) => {
+        if (cited.ids.has(a.id))
+            return true;
+        if (a.status === "ready" && a.url && cited.urls.has(a.url))
+            return true;
+        notes.push(`generatedAssets — dropped unreferenced "${a.id}"`);
+        return false;
+    });
+    spec = { ...spec, scenes, generatedAssets: referencedAssets };
+    // Final schema pass applies all defaults + guarantees a valid contract.
+    const parsed = demoSpec_schema_1.DemoSpecSchema.parse(spec);
+    return { spec: parsed, adjustments: notes };
+}
+/** Convenience — total timeline of a normalized spec (ms). */
+function specTotalMs(spec) {
+    return (0, demoSpec_schema_1.demoSpecDurationMs)(spec);
+}

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

@@ -0,0 +1,102 @@
+import { DemoBrand } from "../../schemas/demoSpec.schema";
+import { IDemoClarifyAnswerValue, IDemoMediaAsset, IDemoVideoWizardAnswers } from "../../models/demoVideoProject.model";
+/**
+ * Prompt construction for the SaaS Demo Video author (plan Phase 3 / §4 stage 2).
+ *
+ * The author is a single Claude `.structured<DemoSpec>()` call: it turns the
+ * user's product facts + brand tokens + product screenshots (as vision) + the
+ * clarifying-wizard answers into a valid, render-ready `DemoSpec` that the
+ * Layer-A scene-template engine renders to MP4 with zero manual effort.
+ *
+ * Kept separate from `demoAuthor.ts` because the system prompt is the largest,
+ * most-iterated surface — it encodes the scene vocabulary, the §2.6 style
+ * taxonomy, the anti-overfit rule, and the screenshot-vs-coded-chrome guidance.
+ * The prompt only DESCRIBES the contract; the zod schema is what actually
+ * constrains the output (passed as the tool `input_schema`), and a
+ * deterministic normalize pass (demoAuthor.ts) enforces the invariants a prompt
+ * can only request (wizard pins, real screenshot URLs, duration budget).
+ */
+export interface DurationBudget {
+    min: number;
+    target: number;
+    max: number;
+    /** Rough scene-count guidance handed to the author for pacing. */
+    sceneHint: string;
+}
+export declare const DURATION_BUDGETS: Record<NonNullable<IDemoVideoWizardAnswers["targetLength"]>, DurationBudget>;
+/** Default when the user left targetLength on "decide for me". */
+export declare const DEFAULT_DURATION_BUDGET: DurationBudget;
+export declare function budgetForLength(targetLength: IDemoVideoWizardAnswers["targetLength"] | undefined): DurationBudget;
+/**
+ * Everything the author needs to write a DemoSpec. Product facts + resolved
+ * brand + the raw inputs (screenshots/website) + wizard answers. Brand colors
+ * are honored verbatim (never re-invented); copy + scene structure are authored.
+ */
+export interface DemoAuthorInput {
+    /** Product display name — overlay text only, never AI-rendered into pixels. */
+    productName: string;
+    /** One-line value proposition, if the user gave one. */
+    tagline?: string;
+    /** Short product description / what it does. */
+    description?: string;
+    /** Feature labels to highlight (from the wizard "which features" multi-select). */
+    features?: string[];
+    /** Target-audience hint for script tone. */
+    audience?: string;
+    /** Resolved brand tokens (colors/fonts/identity). Colors are used as-is. */
+    brand: DemoBrand;
+    /** Real product screenshot URLs (GCS). Fed as vision AND the ONLY image URLs the author may cite. */
+    screenshotUrls?: string[];
+    /**
+     * Media the user wants FEATURED in the video (images + video clips). Unlike
+     * screenshots (reference the author MAY use), these SHOULD appear on the
+     * timeline. Video clips are placed via *.videoUrl scene props; image assets are
+     * merged into the screenshot set upstream. The author is told they exist + must
+     * surface them. See [[IDemoMediaAsset]].
+     */
+    mediaAssets?: IDemoMediaAsset[];
+    /** Product website, for context. The worker's gather stage fetches it (see `pageSummary`). */
+    websiteUrl?: string;
+    /**
+     * A compact, LLM-free summary of the product page's copy (title/description +
+     * visible-text lead), extracted by the worker during gather even when the user
+     * never clicked "Autofill". Steering context for the script — NOT rendered
+     * verbatim on screen. See [[gatherPageSignals]].
+     */
+    pageSummary?: string;
+    /** User's free-text notes about the repo/product — steering context, not rendered verbatim. */
+    repoNotes?: string;
+    /** Clarifying-wizard answers. Omitted fields === "decide for me" (author picks). */
+    answers?: IDemoVideoWizardAnswers;
+    /**
+     * Answers to the agent's DYNAMIC clarifying questions (triage/mid-run loop),
+     * keyed by question id. Authoritative steering context — the author should honor
+     * them. See [[DemoQuestion]].
+     */
+    clarifyAnswers?: Record<string, IDemoClarifyAnswerValue>;
+}
+/**
+ * The system prompt. Deliberately opinionated about quality (invented realistic
+ * domain data, cursor-synced walkthroughs, staggered reveals, on-brand color)
+ * and about the two hard reliability rules a prompt CAN enforce by instruction:
+ * never invent screenshot URLs, never render the product name as pixels.
+ */
+export interface DemoAuthorPromptOpts {
+    /**
+     * Allow the planner to PROPOSE `custom` scenes (with an `intent` brief the
+     * Layer-B codegen agent later authors). Mirrors the worker's
+     * `DEMO_CODEGEN_ENABLED` gate — default false, so the prompt keeps the hard
+     * "no custom scenes" rule and behavior is unchanged until the flag is on.
+     */
+    allowCustomScenes?: boolean;
+    /**
+     * Allow the planner to COMMISSION AI-generated media (`generatedAssets` +
+     * `gen://` refs). Default true — the deterministic caps bound the cost; the
+     * worker passes false only under the DEMO_GEN_ASSETS_DISABLED kill-switch.
+     */
+    allowGeneratedAssets?: boolean;
+}
+export declare function buildDemoAuthorSystemPrompt(opts?: DemoAuthorPromptOpts): string;
+/** Build the user-turn text (images are attached separately as imageUrls). */
+export declare function buildDemoAuthorUserText(input: DemoAuthorInput): string;
+//# sourceMappingURL=demoAuthorPrompt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"demoAuthorPrompt.d.ts","sourceRoot":"","sources":["../../../src/services/demo/demoAuthorPrompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC1D,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,uBAAuB,EACxB,MAAM,qCAAqC,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AAMH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,WAAW,CAAC,uBAAuB,CAAC,cAAc,CAAC,CAAC,EACpD,cAAc,CAQf,CAAC;AAEF,kEAAkE;AAClE,eAAO,MAAM,uBAAuB,EAAE,cAA6C,CAAC;AAEpF,wBAAgB,eAAe,CAC7B,YAAY,EAAE,uBAAuB,CAAC,cAAc,CAAC,GAAG,SAAS,GAChE,cAAc,CAEhB;AAID;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,KAAK,EAAE,SAAS,CAAC;IACjB,qGAAqG;IACrG,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,8FAA8F;IAC9F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,OAAO,CAAC,EAAE,uBAAuB,CAAC;IAClC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;CAC1D;AAwFD;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,wBAAgB,2BAA2B,CAAC,IAAI,GAAE,oBAAyB,GAAG,MAAM,CA0CnF;AAmED,8EAA8E;AAC9E,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CA+CtE"}