vidspotai-shared 1.0.100 → 1.0.101-dev.0

package/lib/services/aiGen/providers/pixverse/pixverse.service.js

@@ -11,6 +11,7 @@ const aiModels_1 = require("../../../../globals/aiModels");
 const types_1 = require("../../../../globals/types");
 const firebase_1 = require("../../../../libs/firebase");
 const helpers_2 = require("../../../../utils/helpers");
+const mp4Duration_1 = require("../../../../utils/mp4Duration");
 const logger_1 = require("../../../../utils/logger");
 const errors_1 = require("../../../../utils/errors");
 const transientRetry_1 = require("../../transientRetry");
@@ -138,6 +139,13 @@ class PixVerseService extends baseAiGenProvider_service_1.BaseAiGenProviderServi
         // Extend a previously-generated PixVerse video. Takes the prior video_id;
         // returns a new task whose status is polled via the same /result/{id} endpoint.
         if (params.endpoint === "extend") {
+            // Backstop matching kling.service: reject rather than silently falling
+            // through to plain generation, which would return a brand-new clip while
+            // the caller believed their video had been continued.
+            if (!(0, aiModels_1.modelSupportsExtend)(params.modelKey)) {
+                throw new Error(`${params.modelKey} has no PixVerse video-extend endpoint. ` +
+                    `Extend-capable: ${[...aiModels_1.EXTEND_CAPABLE_MODELS].join(", ")}.`);
+            }
             if (!params.sourceTaskId) {
                 throw new Error("sourceTaskId (prior PixVerse video_id) is required for video extension");
             }
@@ -320,6 +328,12 @@ class PixVerseService extends baseAiGenProvider_service_1.BaseAiGenProviderServi
                     errorMessage: `Unknown PixVerse status: ${status}`,
                 };
         }
+        // NOTE: unlike Kling, PixVerse's /video/result payload carries NO clip
+        // length. Verified against the official docs 2026-07-24 — the whole Resp
+        // object is {create_time, id, modify_time, negative_prompt, outputHeight,
+        // outputWidth, prompt, resolution_ratio, seed, size, status, style, url},
+        // and `size` is bytes. So there is no field to read: the delivered length
+        // is measured from the downloaded file below (see readMp4DurationSec).
         const sourceVideoUrl = data?.Resp?.url;
         if (!sourceVideoUrl) {
             return {
@@ -333,6 +347,16 @@ class PixVerseService extends baseAiGenProvider_service_1.BaseAiGenProviderServi
             throw new Error(`Failed to download PixVerse video (${videoResp.status})`);
         }
         const buffer = Buffer.from(await videoResp.arrayBuffer());
+        // Measure the DELIVERED length off the bytes we already hold, since the
+        // API never reports it. Matters most for `endpoint:"extend"`, where the
+        // extend body deliberately sends no duration and PixVerse appends a fixed
+        // native increment — billing the requested duration there over-charges.
+        // Returns undefined for anything unreadable, in which case finalization
+        // keeps billing the requested duration exactly as before.
+        const durationSec = (0, mp4Duration_1.readMp4DurationSec)(buffer);
+        if (durationSec === undefined) {
+            logger_1.logger.warn("PixVerse: could not read delivered duration from the downloaded clip — billing will use the requested duration", { task, bytes: buffer.length });
+        }
         // ---- Upload to Firebase ----
         const filePath = `${outputFilePath}/${outputFilename}.mp4`;
         const bucket = (0, firebase_1.getBucket)();
@@ -353,6 +377,7 @@ class PixVerseService extends baseAiGenProvider_service_1.BaseAiGenProviderServi
         return {
             videoUrl: publicVideoUrl,
             status: types_1.EVideoSceneStatus.COMPLETED,
+            durationSec,
         };
     }
     // =========================================================

package/lib/services/aiGen/providers/types.d.ts

@@ -102,6 +102,26 @@ export interface VideoStatusResult {
     status: EVideoSceneStatus;
     videoUrl?: string;
     errorMessage?: string;
+    /**
+     * ACTUAL length of the delivered clip, in seconds, when the provider reports
+     * it. Billing must prefer this over the REQUESTED duration: the two diverge
+     * whenever a provider ignores or clamps the requested value.
+     *
+     * The motivating case is video-extend. `buildExtendBody()` (Kling) and the
+     * Pixverse `/extend/generate` body deliberately send no `duration` — both
+     * providers append a fixed native increment (~5s / ~5-8s) — yet every billing
+     * site priced from the requested duration, so `endpoint:"extend"` with
+     * `duration:10` charged for 10s of generation and delivered ~5s. On
+     * kling-v2-master that is 28 credits for a 14-credit clip.
+     *
+     * Kling already returns this (`task_result.videos[].duration`, seconds as a
+     * string); it was parsed for `.url` only and discarded. Providers that don't
+     * report a length leave this undefined and billing falls back to the
+     * requested duration, exactly as before.
+     *
+     * See notes/UTILITY_TOOLS_LAUNCH_PLAN.md §1.5.1.
+     */
+    durationSec?: number;
 }
 export interface VideoStatusParams {
     task: TVideoJobTask;

package/lib/services/aiGen/providers/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/services/aiGen/providers/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/services/aiGen/providers/types.ts"],"names":[],"mappings":"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"}

package/lib/services/avatarGen/avatarProviderFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"avatarProviderFactory.d.ts","sourceRoot":"","sources":["../../../src/services/avatarGen/avatarProviderFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AA4ClF,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAEhE;AAED,kFAAkF;AAClF,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,eAAe,GACxB,kBAAkB,GAAG,SAAS,CAEhC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAEtE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,eAAe,GACxB,oBAAoB,CAMtB"}
+{"version":3,"file":"avatarProviderFactory.d.ts","sourceRoot":"","sources":["../../../src/services/avatarGen/avatarProviderFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAgDlF,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAEhE;AAED,kFAAkF;AAClF,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,eAAe,GACxB,kBAAkB,GAAG,SAAS,CAEhC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAEtE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,eAAe,GACxB,oBAAoB,CAMtB"}

package/lib/services/avatarGen/avatarProviderFactory.js

@@ -7,11 +7,13 @@ exports.getAvatarVideoProvider = getAvatarVideoProvider;
 const aiModels_1 = require("../../globals/aiModels");
 const heygenAvatarProvider_1 = require("./providers/heygenAvatarProvider");
 const klingAvatarProvider_1 = require("./providers/klingAvatarProvider");
+const synthesiaAvatarProvider_1 = require("./providers/synthesiaAvatarProvider");
 const tavusAvatarProvider_1 = require("./providers/tavusAvatarProvider");
 const avatarProviderMap = {
     [aiModels_1.EVideoGenModels.KLING_AVATAR]: (modelKey) => new klingAvatarProvider_1.KlingAvatarProvider(modelKey),
     [aiModels_1.EVideoGenModels.HEYGEN_AVATAR]: (modelKey) => new heygenAvatarProvider_1.HeyGenAvatarProvider(modelKey),
     [aiModels_1.EVideoGenModels.TAVUS_AVATAR]: (modelKey) => new tavusAvatarProvider_1.TavusAvatarProvider(modelKey),
+    [aiModels_1.EVideoGenModels.SYNTHESIA_AVATAR]: (modelKey) => new synthesiaAvatarProvider_1.SynthesiaAvatarProvider(modelKey),
 };
 /**
  * Static capability lookup, keyed off each provider's `CAPABILITIES` constant —
@@ -24,6 +26,7 @@ const avatarCapabilityMap = {
     [aiModels_1.EVideoGenModels.KLING_AVATAR]: klingAvatarProvider_1.KlingAvatarProvider.CAPABILITIES,
     [aiModels_1.EVideoGenModels.HEYGEN_AVATAR]: heygenAvatarProvider_1.HeyGenAvatarProvider.CAPABILITIES,
     [aiModels_1.EVideoGenModels.TAVUS_AVATAR]: tavusAvatarProvider_1.TavusAvatarProvider.CAPABILITIES,
+    [aiModels_1.EVideoGenModels.SYNTHESIA_AVATAR]: synthesiaAvatarProvider_1.SynthesiaAvatarProvider.CAPABILITIES,
 };
 /** True if `modelKey` is an avatar model handled by a dedicated avatar provider. */
 function isAvatarModel(modelKey) {

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

@@ -3,4 +3,5 @@ export * from "./avatarProviderFactory";
 export * from "./providers/klingAvatarProvider";
 export * from "./providers/heygenAvatarProvider";
 export * from "./providers/tavusAvatarProvider";
+export * from "./providers/synthesiaAvatarProvider";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/avatarGen/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,iCAAiC,CAAC;AAChD,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/avatarGen/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,iCAAiC,CAAC;AAChD,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,qCAAqC,CAAC"}

package/lib/services/avatarGen/index.js

@@ -19,3 +19,4 @@ __exportStar(require("./avatarProviderFactory"), exports);
 __exportStar(require("./providers/klingAvatarProvider"), exports);
 __exportStar(require("./providers/heygenAvatarProvider"), exports);
 __exportStar(require("./providers/tavusAvatarProvider"), exports);
+__exportStar(require("./providers/synthesiaAvatarProvider"), exports);

package/lib/services/avatarGen/providers/synthesiaAvatarProvider.d.ts

@@ -0,0 +1,53 @@
+import { EVideoGenModels } from "../../../globals/aiModels";
+import { AvatarCapabilities, AvatarGenerateRequest, AvatarStatusQuery, AvatarStatusResult, AvatarSubmitResult, EAvatarEngine, IAvatarVideoProvider } from "../IAvatarVideoProvider";
+/**
+ * Synthesia avatar engine — a HOSTED engine (the caller picks a Synthesia stock
+ * or personal avatar + voice and supplies a script; Synthesia does its own TTS +
+ * lipsync in one render). Positioned as the enterprise/compliance tier: studio
+ * presenters across 140+ languages for regulated buyers.
+ *
+ * Contract (Synthesia API v2, verified 2026-07-19 against docs.synthesia.io):
+ *   • submit : POST /v2/videos
+ *              { test, title, visibility, aspectRatio,
+ *                input: [{ avatar, background, scriptText,
+ *                          avatarSettings: { voice? } }] }        → { id, status }
+ *   • status : GET  /v2/videos/{id}
+ *              → { status, download, duration, thumbnail, ... }
+ *              status enum: in_progress | approved | complete | error |
+ *                           rejected | deleted   (`download` set when complete)
+ *   • auth   : Authorization: Bearer <key>  (header-based)
+ *
+ * NO ISupportsHostedCatalog: Synthesia exposes stock avatars/voices as static
+ * reference tables (IDs are copied from the web app), not a stable list REST
+ * endpoint — so the catalog capability is DEFERRED (per the Reach plan §2.4,
+ * "Catalog (defer to Phase 4+)"). Selection is by known avatar/voice id today.
+ *
+ * Standalone class — Synthesia has no place in the generic video factory; avatar
+ * gen is its own concern (see IAvatarVideoProvider). Transport (auth + timeout +
+ * retry) is owned here, mirroring HeyGen/Tavus.
+ *
+ * Runtime is gated on SYNTHESIA_API_KEY (enterprise plan). Until that key is in
+ * the env stores the constructor throws — the intended "wired but not enabled"
+ * state for the enterprise tier.
+ */
+export declare class SynthesiaAvatarProvider implements IAvatarVideoProvider {
+    private readonly modelKey;
+    /** Static so callers can branch on capability without constructing (which
+     *  would require SYNTHESIA_API_KEY just to read the input mode). */
+    static readonly CAPABILITIES: AvatarCapabilities;
+    readonly engine = EAvatarEngine.SYNTHESIA;
+    readonly capabilities: AvatarCapabilities;
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly submitTimeout;
+    private readonly statusTimeout;
+    /** Synthesia requires a named background; "off_white" is a built-in studio bg. */
+    private readonly defaultBackground;
+    constructor(modelKey?: EVideoGenModels);
+    generate(req: AvatarGenerateRequest): Promise<AvatarSubmitResult>;
+    checkStatus(query: AvatarStatusQuery): Promise<AvatarStatusResult>;
+    private request;
+    /** Retries transient network/timeout/429 failures with a small backoff. */
+    private requestWithRetry;
+}
+//# sourceMappingURL=synthesiaAvatarProvider.d.ts.map

package/lib/services/avatarGen/providers/synthesiaAvatarProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesiaAvatarProvider.d.ts","sourceRoot":"","sources":["../../../../src/services/avatarGen/providers/synthesiaAvatarProvider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACrB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,uBAAwB,YAAW,oBAAoB;IAqBhE,OAAO,CAAC,QAAQ,CAAC,QAAQ;IApB3B;wEACoE;IACpE,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAI9C;IAEF,QAAQ,CAAC,MAAM,2BAA2B;IAC1C,QAAQ,CAAC,YAAY,qBAAwC;IAE7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAW;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IAExC,kFAAkF;IAClF,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAe;gBAG9B,QAAQ,GAAE,eAAkD;IAQzE,QAAQ,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA6CjE,WAAW,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;YAoC1D,OAAO;IA0BrB,2EAA2E;YAC7D,gBAAgB;CAsD/B"}

package/lib/services/avatarGen/providers/synthesiaAvatarProvider.js

@@ -0,0 +1,176 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SynthesiaAvatarProvider = void 0;
+const axios_1 = __importDefault(require("axios"));
+const aiModels_1 = require("../../../globals/aiModels");
+const types_1 = require("../../../globals/types");
+const logger_1 = require("../../../utils/logger");
+const IAvatarVideoProvider_1 = require("../IAvatarVideoProvider");
+/**
+ * Synthesia avatar engine — a HOSTED engine (the caller picks a Synthesia stock
+ * or personal avatar + voice and supplies a script; Synthesia does its own TTS +
+ * lipsync in one render). Positioned as the enterprise/compliance tier: studio
+ * presenters across 140+ languages for regulated buyers.
+ *
+ * Contract (Synthesia API v2, verified 2026-07-19 against docs.synthesia.io):
+ *   • submit : POST /v2/videos
+ *              { test, title, visibility, aspectRatio,
+ *                input: [{ avatar, background, scriptText,
+ *                          avatarSettings: { voice? } }] }        → { id, status }
+ *   • status : GET  /v2/videos/{id}
+ *              → { status, download, duration, thumbnail, ... }
+ *              status enum: in_progress | approved | complete | error |
+ *                           rejected | deleted   (`download` set when complete)
+ *   • auth   : Authorization: Bearer <key>  (header-based)
+ *
+ * NO ISupportsHostedCatalog: Synthesia exposes stock avatars/voices as static
+ * reference tables (IDs are copied from the web app), not a stable list REST
+ * endpoint — so the catalog capability is DEFERRED (per the Reach plan §2.4,
+ * "Catalog (defer to Phase 4+)"). Selection is by known avatar/voice id today.
+ *
+ * Standalone class — Synthesia has no place in the generic video factory; avatar
+ * gen is its own concern (see IAvatarVideoProvider). Transport (auth + timeout +
+ * retry) is owned here, mirroring HeyGen/Tavus.
+ *
+ * Runtime is gated on SYNTHESIA_API_KEY (enterprise plan). Until that key is in
+ * the env stores the constructor throws — the intended "wired but not enabled"
+ * state for the enterprise tier.
+ */
+class SynthesiaAvatarProvider {
+    constructor(modelKey = aiModels_1.EVideoGenModels.SYNTHESIA_AVATAR) {
+        this.modelKey = modelKey;
+        this.engine = IAvatarVideoProvider_1.EAvatarEngine.SYNTHESIA;
+        this.capabilities = SynthesiaAvatarProvider.CAPABILITIES;
+        this.baseUrl = "https://api.synthesia.io";
+        this.submitTimeout = 120000; // 2 min — submit can be slow under load
+        this.statusTimeout = 60000; // 1 min — status should be fast
+        /** Synthesia requires a named background; "off_white" is a built-in studio bg. */
+        this.defaultBackground = "off_white";
+        if (!process.env.SYNTHESIA_API_KEY) {
+            throw new Error("Missing SYNTHESIA_API_KEY in environment variables");
+        }
+        this.apiKey = process.env.SYNTHESIA_API_KEY;
+    }
+    async generate(req) {
+        if (req.mode !== "hosted") {
+            throw new Error(`SynthesiaAvatarProvider only supports hosted requests (got "${req.mode}")`);
+        }
+        // Synthesia's clip carries the avatar + script; the voice is set on
+        // avatarSettings.voice (optional — omit to use the avatar's default voice).
+        const avatarSettings = {
+            style: "rectangular",
+        };
+        if (req.hostedVoiceId) {
+            avatarSettings.voice = req.hostedVoiceId;
+        }
+        const body = {
+            test: false,
+            visibility: "private",
+            title: `vidspot-${req.hostedAvatarId}-${req.script.slice(0, 24)}`,
+            input: [
+                {
+                    avatar: req.hostedAvatarId,
+                    background: this.defaultBackground,
+                    scriptText: req.script,
+                    avatarSettings,
+                },
+            ],
+        };
+        const data = await this.request("/v2/videos", "POST", body, this.submitTimeout);
+        const videoId = data?.id;
+        if (!videoId) {
+            throw new Error(`Synthesia submit returned no id: ${JSON.stringify(data?.message ?? data)}`);
+        }
+        return { providerTaskId: videoId };
+    }
+    async checkStatus(query) {
+        const data = await this.requestWithRetry(`/v2/videos/${encodeURIComponent(query.providerTaskId)}`, "GET", undefined, this.statusTimeout);
+        // Synthesia status enum: in_progress | approved | complete | error |
+        // rejected | deleted. Only `complete` (with a download URL) is terminal-ok;
+        // `approved` is a moderation-passed intermediate that still renders.
+        if (data?.status === "complete" && data.download) {
+            return {
+                status: types_1.EVideoSceneStatus.COMPLETED,
+                videoUrl: data.download,
+            };
+        }
+        if (data?.status === "error" ||
+            data?.status === "rejected" ||
+            data?.status === "deleted") {
+            return {
+                status: types_1.EVideoSceneStatus.FAILED,
+                errorMessage: `Synthesia render ${data.status}`,
+            };
+        }
+        return { status: types_1.EVideoSceneStatus.PENDING };
+    }
+    // ─── Transport ────────────────────────────────────────────────────────────
+    async request(endpoint, method, body, timeout = this.submitTimeout) {
+        const config = {
+            method,
+            url: `${this.baseUrl}${endpoint}`,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json",
+            },
+            timeout,
+            data: body,
+        };
+        const response = await axios_1.default.request(config);
+        if (response.status < 200 || response.status >= 300) {
+            throw new Error(`Synthesia API Error: ${response.status} ${response.statusText} — ${JSON.stringify(response.data)}`);
+        }
+        return response.data;
+    }
+    /** Retries transient network/timeout/429 failures with a small backoff. */
+    async requestWithRetry(endpoint, method, body, timeout = this.statusTimeout, maxAttempts = 4) {
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                return await this.request(endpoint, method, body, timeout);
+            }
+            catch (err) {
+                const e = err;
+                const httpStatus = e.response?.status;
+                const isTimeout = e.code === "ECONNABORTED" || (e.message?.includes("timeout") ?? false);
+                const isNetworkError = e.code === "ECONNRESET" ||
+                    e.code === "ECONNREFUSED" ||
+                    e.code === "ENOTFOUND" ||
+                    e.code === "ERR_NETWORK";
+                const isRateLimit = httpStatus === 429;
+                const isRetryable = isTimeout || isNetworkError || isRateLimit;
+                if (!isRetryable || attempt === maxAttempts) {
+                    logger_1.logger.error("Synthesia request failed (non-retryable or max attempts)", {
+                        endpoint,
+                        attempt,
+                        maxAttempts,
+                        httpStatus,
+                        errorCode: e.code,
+                        errorMessage: e.message,
+                    });
+                    throw err;
+                }
+                const backoffMs = isRateLimit ? 10000 : 1000;
+                logger_1.logger.warn("Synthesia request failed — retrying", {
+                    endpoint,
+                    attempt,
+                    maxAttempts,
+                    httpStatus,
+                    backoffMs,
+                });
+                await new Promise((r) => setTimeout(r, backoffMs));
+            }
+        }
+        throw new Error("Unreachable");
+    }
+}
+exports.SynthesiaAvatarProvider = SynthesiaAvatarProvider;
+/** Static so callers can branch on capability without constructing (which
+ *  would require SYNTHESIA_API_KEY just to read the input mode). */
+SynthesiaAvatarProvider.CAPABILITIES = {
+    inputMode: "hosted",
+    nativeTts: true,
+    multiSceneSplit: false,
+};

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

@@ -25,6 +25,13 @@ export interface DemoAuthorDeps {
      * DEMO_GEN_ASSETS_DISABLED kill-switch.
      */
     allowGeneratedAssets?: boolean;
+    /**
+     * Allow the planner to resolve real STOCK-library assets (`source:"stock"`).
+     * Defaults to whether a stock provider is configured (`stockAssetsAvailable()`),
+     * so stock lights up automatically once a PEXELS/PIXABAY/UNSPLASH key is set —
+     * no separate flag. Pass explicitly to override.
+     */
+    allowStockAssets?: boolean;
 }
 export interface DemoAuthorResult extends NormalizeResult {
     /** Model that produced the spec (primary or fallback). */

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

@@ -1 +1 @@
-{"version":3,"file":"demoAuthor.d.ts","sourceRoot":"","sources":["../../../src/services/demo/demoAuthor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EACL,eAAe,EAGhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAqB,MAAM,uBAAuB,CAAC;AAqB3E,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,uDAAuD;IACvD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kFAAkF;IAClF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,0DAA0D;IAC1D,SAAS,EAAE,WAAW,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9D;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,eAAe,EACtB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,gBAAgB,CAAC,CAgD3B"}
+{"version":3,"file":"demoAuthor.d.ts","sourceRoot":"","sources":["../../../src/services/demo/demoAuthor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EACL,eAAe,EAGhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAqB,MAAM,uBAAuB,CAAC;AAsB3E,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,uDAAuD;IACvD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kFAAkF;IAClF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,0DAA0D;IAC1D,SAAS,EAAE,WAAW,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9D;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,eAAe,EACtB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,gBAAgB,CAAC,CAiD3B"}

package/lib/services/demo/demoAuthor.js

@@ -6,6 +6,7 @@ const llmCallerRegistry_1 = require("../agent/llmCallerRegistry");
 const modelRouter_1 = require("../agent/modelRouter");
 const demoAuthorPrompt_1 = require("./demoAuthorPrompt");
 const demoAuthorNormalize_1 = require("./demoAuthorNormalize");
+const demoStockAssets_1 = require("./demoStockAssets");
 /**
  * DemoSpec author — the "plan" stage of the SaaS Demo Video pipeline (plan
  * Phase 3 / §4 stage 2).
@@ -44,6 +45,7 @@ async function authorDemoSpec(input, deps = {}) {
     const system = (0, demoAuthorPrompt_1.buildDemoAuthorSystemPrompt)({
         allowCustomScenes: deps.allowCustomScenes,
         allowGeneratedAssets: deps.allowGeneratedAssets,
+        allowStockAssets: deps.allowStockAssets ?? (0, demoStockAssets_1.stockAssetsAvailable)(),
     });
     const userText = (0, demoAuthorPrompt_1.buildDemoAuthorUserText)(cappedInput);
     const result = await llm.structured({

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

@@ -95,6 +95,12 @@ export interface DemoAuthorPromptOpts {
      * worker passes false only under the DEMO_GEN_ASSETS_DISABLED kill-switch.
      */
     allowGeneratedAssets?: boolean;
+    /**
+     * Allow the planner to resolve real STOCK-library assets (`source:"stock"`).
+     * The worker passes true only when a stock provider is configured
+     * (`stockAssetsAvailable()`); ignored when generation is disabled entirely.
+     */
+    allowStockAssets?: boolean;
 }
 export declare function buildDemoAuthorSystemPrompt(opts?: DemoAuthorPromptOpts): string;
 /** Build the user-turn text (images are attached separately as imageUrls). */

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

@@ -1 +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"}
+{"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;AAqGD;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,2BAA2B,CAAC,IAAI,GAAE,oBAAyB,GAAG,MAAM,CAmDnF;AAmED,8EAA8E;AAC9E,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CA+CtE"}

package/lib/services/demo/demoAuthorPrompt.js

@@ -80,6 +80,18 @@ HOW to write the generation prompt (you are prompting a top image/video model):
 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.`;
+/**
+ * Stock-library addendum — appended only when a stock provider is configured
+ * (see stockAssetsAvailable()). Lets the planner resolve a real photo/clip from a
+ * licensed library instead of paying a generative model, for generic real-world
+ * subjects where a stock shot is as good or better. Same declaration + gen://
+ * citation mechanism, distinguished by source:"stock" + a search query.
+ */
+const STOCK_MEDIA_ALLOWED = `
+STOCK MEDIA (a real, free, licensed library is available — prefer it over generation for GENERIC real-world subjects):
+- To use a stock asset, declare it in generatedAssets[] with source:"stock", a kind ("image"|"video"), and query (2–5 plain search words — the subject only, NO brand names, NO UI text; e.g. "founder laptop cafe", "city street night"). Omit/ignore the generation prompt for stock (a short prompt is fine as a description but query drives the search). Cite it exactly like a generated asset: "gen://<id>".
+- PREFER source:"stock" over source:"generated" when the subject is a common real-world thing (people working, places, objects, nature, devices) — it's instant, free, and photoreal. RESERVE source:"generated" for subjects a library won't have: your product's specific look, surreal/branded compositions, exact palette-matched abstract motion backdrops.
+- A stock miss degrades exactly like a failed generation (ref stripped, beat falls back to its coded surface) — so still never author a beat that is EMPTY without the asset.`;
 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
@@ -100,8 +112,9 @@ function buildDemoAuthorSystemPrompt(opts = {}) {
     const customGuidance = opts.allowCustomScenes
         ? CUSTOM_SCENE_ALLOWED
         : CUSTOM_SCENE_DISALLOWED;
-    const generatedMediaGuidance = opts.allowGeneratedAssets !== false
-        ? GENERATED_MEDIA_ALLOWED
+    const genAllowed = opts.allowGeneratedAssets !== false;
+    const generatedMediaGuidance = genAllowed
+        ? GENERATED_MEDIA_ALLOWED + (opts.allowStockAssets ? `\n${STOCK_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."
 
@@ -128,6 +141,15 @@ QUALITY BAR (observed in the reference demos — hit all of these):
 - 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.
 
+CONTENTFUL SURFACES — every coded product UI must look POPULATED, never hollow (hard quality gate; empty UI reads as broken and sinks the whole video):
+- Fill it or omit it. Every surface/region you invoke (featureShowcase surfaces, chat turns, dashboard tiles, editor rows, analysis findings, table rows, card grids) MUST be filled with real, specific, domain-accurate content. NEVER emit a featureShowcase/cardGrid/surface with an empty or near-empty cards array — an unpopulated surface renders as blank chrome. If you can't supply genuine content for a region, don't include that region (e.g. don't ask for a sidebar/panel/stat you can't fill).
+- Right shape, at least 3 items where the surface is a list: search → 3–5 results, each title + subtitle + badge; dashboard → 3–4 stats, each a value (+ an icon, and a delta only if truthful); editor → labelled property rows (label + value, e.g. Caption / Trim / Music / Brand); analysis or scene-plan → findings each a label (+ optional sub + a timecode badge); chat → alternating user/assistant turns with real copy. Give search/editor/dashboard cards an \`icon\` so tiles/rows carry a glyph.
+- NO EMPTY ASSET SLOTS. Never leave a blank avatar, poster, logo, or thumbnail hole. The engine auto-fills these — a person → initials from userName, a video/result tile → brand-gradient poster + play glyph, the product chrome → brand fills — but ONLY when you provide the underlying content (a userName, card titles, subtitles). Supply that content; do not describe an empty frame.
+
+ASSETS (images / video / music / voiceover) — prefer REAL, ask FIRST, improvise LAST, never leave a hole:
+- Order of preference for any asset that would materially raise quality (hero screenshot, presenter photo, B-roll, logo): (a) a user-attached asset (Featured media / screenshots), else (b) commission it via generatedAssets where GENERATED MEDIA rules allow, else (c) a stock/library asset if the pipeline exposes one, else (d) a synthetic coded surface. Only fall to a coded surface once real imagery is genuinely unavailable — never fabricate an empty placeholder to stand in for a missing asset.
+- Don't FORCE an asset where it adds nothing. A clean coded surface beats a gratuitous stock photo; use imagery only where it earns its place.
+
 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.

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"}