vidspotai-shared 1.0.82 → 1.0.83

package/lib/services/editor/planToProject.js

@@ -1,162 +1,40 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TRACK_ID = void 0;
-exports.buildOverlayClipsForScene = buildOverlayClipsForScene;
+exports.buildOverlayClipsForScene = exports.TRACK_ID = void 0;
 exports.planToProject = planToProject;
 const project_schema_1 = require("../../schemas/project.schema");
-// ─── track id constants ──────────────────────────────────────────────────
-exports.TRACK_ID = {
-    visual: "track-visual",
-    voiceover: "track-vo",
-    music: "track-music",
-    text: "track-text",
-    caption: "track-caption",
-};
-// ─── strategy → clip kind ────────────────────────────────────────────────
-const STILL_STRATEGIES = new Set([
-    "stock-image-ken-burns",
-    "ai-image-static",
-]);
-function isStillStrategy(s) {
-    return STILL_STRATEGIES.has(s);
-}
-/** A passable URL we can put in skeleton clips so ProjectSchema.url() passes. */
-const PLACEHOLDER_URL = "data:,placeholder";
-// ─── aspect → size defaults ──────────────────────────────────────────────
-function sizeForAspect(aspect) {
-    switch (aspect) {
-        case "9:16":
-            return { width: 1080, height: 1920 };
-        case "1:1":
-            return { width: 1080, height: 1080 };
-        case "4:5":
-            return { width: 1080, height: 1350 };
-        case "16:9":
-            return { width: 1920, height: 1080 };
-    }
-}
-// ─── transition kind → renderable subset ─────────────────────────────────
-const TRANSITION_KIND_MAP = {
-    none: null,
-    cut: null,
-    fade: "fade",
-    crossfade: "crossfade",
-    wipe: "wipe",
-    whipPan: "whipPan",
-    dipToBlack: "dipToBlack",
-    dipToWhite: "dipToWhite",
-};
-// ─── provenance builder ──────────────────────────────────────────────────
-function provenanceForScene(scene, outcome) {
-    const attempted = outcome?.attemptedProviders;
-    const source = (attempted && attempted.length > 0 ? attempted[0] : undefined) ??
-        scene.preferredProvider ??
-        scene.strategy;
-    return {
-        tier: scene.tier,
-        source,
-        modelKey: outcome?.modelKey ?? scene.preferredModel,
-        prompt: scene.prompt,
-        assetHash: outcome?.assetHash,
-        creditsSpent: outcome?.creditsSpent ?? scene.estimatedCredits,
-        generationId: outcome?.generationId,
-    };
-}
-// ─── overlay role → text styling defaults ────────────────────────────────
-function fontSizeForOverlay(o, frameHeight) {
-    // Explicit px wins.
-    if (typeof o.fontSize === "number")
-        return o.fontSize;
-    // sizePct (2–20% of frame height) → px. Resolution-independent.
-    if (typeof o.sizePct === "number") {
-        return Math.max(8, Math.round((o.sizePct / 100) * frameHeight));
-    }
-    switch (o.role) {
-        case "headline":
-            return 96;
-        case "cta":
-            return 72;
-        case "subheadline":
-        case "body":
-            return 48;
-        case "watermark":
-        case "disclaimer":
-        case "label":
-            return 28;
-    }
-}
-function fontWeightForOverlay(o) {
-    if (o.weight) {
-        return { regular: 400, medium: 500, bold: 700, black: 900 }[o.weight];
-    }
-    switch (o.role) {
-        case "headline":
-        case "cta":
-            return 900;
-        case "subheadline":
-            return 700;
-        case "watermark":
-        case "disclaimer":
-            return 400;
-        default:
-            return 700;
-    }
-}
+const planToProject_helpers_1 = require("./planToProject.helpers");
+// Re-export the public surface so `export * from "./editor/planToProject"`
+// (services/index.ts) keeps surfacing these for existing importers.
+var planToProject_helpers_2 = require("./planToProject.helpers");
+Object.defineProperty(exports, "TRACK_ID", { enumerable: true, get: function () { return planToProject_helpers_2.TRACK_ID; } });
+Object.defineProperty(exports, "buildOverlayClipsForScene", { enumerable: true, get: function () { return planToProject_helpers_2.buildOverlayClipsForScene; } });
 /**
- * Build the TextClip[] for a single scene's overlays at a known timeline
- * offset. Extracted from the planToProject loop so the regen handlers
- * (Stage 6 slice 4) can splice fresh overlays into projectJson without
- * duplicating the role → font/size/weight mapping. Pure / no I/O.
+ * planToProject — pure translator from an approved VideoPlan + per-scene
+ * executor outcomes into the canonical Project IR. The Project is what gets
+ * persisted to Firestore (videos/{id}.project) and consumed by both editor
+ * (via projectToDesign) and the headless stitcher.
+ *
+ * The translator is pure (no I/O, no Firestore, no provider calls). The
+ * caller resolves any base64 → URL uploads (e.g. voiceover MP3) before
+ * passing outcomes; this keeps the function testable and round-trippable.
  *
- * `offsetMs` is the scene's start on the master timeline (cumulative sum
- * of prior scene durations). `sceneDurationMs` clamps any overlay.endMs
- * that overshoots the scene.
+ * Skeleton mode: if outcomes is missing or a scene's visualUrl is absent,
+ * a placeholder data URL is emitted so the Project is schema-valid and the
+ * editor can render a grey placeholder pinned to the scene's intended
+ * duration. Worker fills in the real URL via Firestore update later.
+ *
+ * Input/outcome types live in ./planToProject.types; the pure clip-builder
+ * helpers (track ids, size/transition lookups, overlay styling) in
+ * ./planToProject.helpers.
  */
-function buildOverlayClipsForScene(sceneIndex, offsetMs, sceneDurationMs, overlays, frameHeight) {
-    const clips = [];
-    for (const [oi, overlay] of overlays.entries()) {
-        const overlayFrom = offsetMs + Math.max(0, overlay.startMs ?? 0);
-        const overlayTo = offsetMs + Math.min(sceneDurationMs, overlay.endMs ?? sceneDurationMs);
-        if (overlayTo <= overlayFrom)
-            continue;
-        clips.push({
-            id: `scene-${sceneIndex}-overlay-${oi}`,
-            trackId: exports.TRACK_ID.text,
-            type: "text",
-            display: { from: overlayFrom, to: overlayTo },
-            name: overlay.role,
-            text: overlay.text,
-            fontFamily: overlay.font ?? "Poppins",
-            fontSize: fontSizeForOverlay(overlay, frameHeight),
-            fontWeight: fontWeightForOverlay(overlay),
-            color: overlay.color ?? "#ffffff",
-            align: "center",
-            backgroundColor: overlay.bgColor,
-            effects: [],
-            transform: { x: 0, y: 0, scaleX: 1, scaleY: 1, rotation: 0, opacity: 1 },
-            locked: false,
-            metadata: {
-                sceneIndex,
-                role: overlay.role,
-                position: overlay.position,
-                emphasis: overlay.emphasis,
-                animation: overlay.animation,
-                bgStyle: overlay.bgStyle,
-                sizePct: overlay.sizePct,
-                persistAcrossScenes: overlay.persistAcrossScenes ?? false,
-            },
-        });
-    }
-    return clips;
-}
-// ─── main ────────────────────────────────────────────────────────────────
 function planToProject(input) {
     const { plan, projectId, name, agentRunId, musicUrl, musicDurationMs } = input;
     const outcomes = input.outcomes ?? {};
     const now = new Date().toISOString();
     const createdAt = input.createdAt ?? now;
     const updatedAt = input.updatedAt ?? now;
-    const size = sizeForAspect(plan.aspect);
+    const size = (0, planToProject_helpers_1.sizeForAspect)(plan.aspect);
     // Walk scenes in order; build clips per kind and accumulate offset.
     const clips = [];
     const transitions = [];
@@ -165,6 +43,7 @@ function planToProject(input) {
     let hasVoiceover = false;
     let hasOverlays = false;
     let hasCaptions = false;
+    let hasBroll = false;
     const sortedScenes = [...plan.scenes].sort((a, b) => a.sceneIndex - b.sceneIndex);
     for (const scene of sortedScenes) {
         const outcome = outcomes[scene.sceneIndex];
@@ -181,12 +60,34 @@ function planToProject(input) {
         const sceneDurationMs = Math.max(plannedSceneDurationMs, voDurationMs);
         const display = { from: offsetMs, to: offsetMs + sceneDurationMs };
         const visualClipId = `scene-${scene.sceneIndex}-visual`;
-        const visualUrl = outcome?.visualUrl || PLACEHOLDER_URL;
-        const provenance = provenanceForScene(scene, outcome);
-        if (isStillStrategy(scene.strategy)) {
+        const visualUrl = outcome?.visualUrl || planToProject_helpers_1.PLACEHOLDER_URL;
+        const provenance = (0, planToProject_helpers_1.provenanceForScene)(scene, outcome);
+        // AG-2 / L-4: an extend chain resolves to ≥2 sub-clips for one scene. They
+        // render as adjacent video clips across the scene window. Track the first
+        // sub-clip (transition target) and last sub-clip (next scene's transition
+        // source) so cross-scene transitions still anchor correctly.
+        const chainClips = outcome?.clips;
+        let firstVisualClipId = visualClipId;
+        let lastVisualClipId = visualClipId;
+        // Gap #1 follow-up (skip-generation). Visual was preserved verbatim and the
+        // executor skipped its gen, so there's no real URL to build from. Don't emit
+        // a placeholder twin — the preserve-override below injects the real clip(s).
+        // We still anchor this scene's transitions on the preserved visual ids (the
+        // chain's first/last) so cross-scene transitions reference clips that exist.
+        const visualFrozen = input.frozenVisualScenes?.has(scene.sceneIndex) ?? false;
+        if (visualFrozen) {
+            const sceneVisuals = (input.preserveClips ?? [])
+                .filter((c) => c.id === visualClipId || c.id.startsWith(`${visualClipId}-`))
+                .sort((a, b) => a.display.from - b.display.from);
+            if (sceneVisuals.length > 0) {
+                firstVisualClipId = sceneVisuals[0].id;
+                lastVisualClipId = sceneVisuals[sceneVisuals.length - 1].id;
+            }
+        }
+        else if ((0, planToProject_helpers_1.isStillStrategy)(scene.strategy)) {
             const imageClip = {
                 id: visualClipId,
-                trackId: exports.TRACK_ID.visual,
+                trackId: planToProject_helpers_1.TRACK_ID.visual,
                 type: "image",
                 display,
                 name: `Scene ${scene.sceneIndex + 1}`,
@@ -206,10 +107,51 @@ function planToProject(input) {
             };
             clips.push(imageClip);
         }
+        else if (chainClips && chainClips.length >= 2) {
+            // Multi-clip scene (extend chain): split the scene window proportionally
+            // to each sub-clip's nominal seconds; the last absorbs rounding so the
+            // sub-clips tile the window with no gaps. No intra-scene transitions —
+            // the extensions are a single continuous shot (hard cut/none between).
+            const totalSec = chainClips.reduce((s, c) => s + Math.max(0.001, c.durationSec), 0);
+            let subFrom = offsetMs;
+            chainClips.forEach((c, k) => {
+                const isLast = k === chainClips.length - 1;
+                const subTo = isLast
+                    ? offsetMs + sceneDurationMs
+                    : subFrom + Math.round(sceneDurationMs * (c.durationSec / totalSec));
+                const subId = `${visualClipId}-${k}`;
+                const subClip = {
+                    id: subId,
+                    trackId: planToProject_helpers_1.TRACK_ID.visual,
+                    type: "video",
+                    display: { from: subFrom, to: subTo },
+                    name: k === 0 ? `Scene ${scene.sceneIndex + 1}` : `Scene ${scene.sceneIndex + 1} (cont. ${k})`,
+                    src: c.visualUrl || planToProject_helpers_1.PLACEHOLDER_URL,
+                    volume: scene.voiceoverLine ? 0 : 1,
+                    playbackRate: 1,
+                    provenance,
+                    effects: [],
+                    transform: { x: 0, y: 0, scaleX: 1, scaleY: 1, rotation: 0, opacity: 1 },
+                    locked: false,
+                    metadata: {
+                        sceneIndex: scene.sceneIndex,
+                        strategy: scene.strategy,
+                        layout: scene.layout,
+                        extendClipIndex: k,
+                        extendSourceTaskId: c.taskId,
+                    },
+                };
+                clips.push(subClip);
+                if (k === 0)
+                    firstVisualClipId = subId;
+                lastVisualClipId = subId;
+                subFrom = subTo;
+            });
+        }
         else {
             const videoClip = {
                 id: visualClipId,
-                trackId: exports.TRACK_ID.visual,
+                trackId: planToProject_helpers_1.TRACK_ID.visual,
                 type: "video",
                 display,
                 name: `Scene ${scene.sceneIndex + 1}`,
@@ -228,20 +170,22 @@ function planToProject(input) {
             };
             clips.push(videoClip);
         }
-        // Transition between previous scene's visual and this one.
+        // Transition between previous scene's visual and this one. For a multi-clip
+        // scene the transition lands on the FIRST sub-clip; the next scene's
+        // transition will source from this scene's LAST sub-clip.
         if (prevVisualClipId && scene.transitionIn) {
-            const kind = TRANSITION_KIND_MAP[scene.transitionIn];
+            const kind = planToProject_helpers_1.TRANSITION_KIND_MAP[scene.transitionIn];
             if (kind) {
                 transitions.push({
                     id: `transition-${scene.sceneIndex}`,
                     fromClipId: prevVisualClipId,
-                    toClipId: visualClipId,
+                    toClipId: firstVisualClipId,
                     kind,
                     durationMs: 400,
                 });
             }
         }
-        prevVisualClipId = visualClipId;
+        prevVisualClipId = lastVisualClipId;
         // Voiceover clip.
         if (scene.voiceoverLine && outcome?.voiceoverUrl) {
             hasVoiceover = true;
@@ -255,7 +199,7 @@ function planToProject(input) {
                 : sceneDurationMs;
             const voClip = {
                 id: `scene-${scene.sceneIndex}-vo`,
-                trackId: exports.TRACK_ID.voiceover,
+                trackId: planToProject_helpers_1.TRACK_ID.voiceover,
                 type: "audio",
                 display: { from: offsetMs, to: offsetMs + voClipDurationMs },
                 name: `VO ${scene.sceneIndex + 1}`,
@@ -277,7 +221,7 @@ function planToProject(input) {
             clips.push(voClip);
         }
         // Overlay text clips.
-        const overlayClips = buildOverlayClipsForScene(scene.sceneIndex, offsetMs, sceneDurationMs, scene.overlays ?? [], size.height);
+        const overlayClips = (0, planToProject_helpers_1.buildOverlayClipsForScene)(scene.sceneIndex, offsetMs, sceneDurationMs, scene.overlays ?? [], size.height);
         if (overlayClips.length > 0)
             hasOverlays = true;
         for (const clip of overlayClips)
@@ -286,17 +230,25 @@ function planToProject(input) {
         if (outcome?.captionWords && outcome.captionWords.length > 0) {
             hasCaptions = true;
             const text = outcome.captionWords.map((w) => w.word).join(" ");
+            // CH-8 — apply persisted caption styling (set by the chat
+            // change_caption_style tool): per-scene override wins over the
+            // plan-level style, which wins over the renderer defaults, per field.
+            const cs = { ...plan.captionStyle, ...scene.captionStyle };
             const captionClip = {
                 id: `scene-${scene.sceneIndex}-caption`,
-                trackId: exports.TRACK_ID.caption,
+                trackId: planToProject_helpers_1.TRACK_ID.caption,
                 type: "caption",
                 display,
                 name: `Captions ${scene.sceneIndex + 1}`,
                 text,
                 words: outcome.captionWords,
-                fontFamily: "Poppins",
-                fontSize: 48,
-                color: "#ffffff",
+                fontFamily: cs?.fontFamily ?? "Poppins",
+                fontSize: cs?.fontSize ?? 48,
+                // CH-1 — weight is optional; leave it unset so the renderer applies
+                // its default bold (800) unless the style explicitly overrides it.
+                ...(cs?.fontWeight !== undefined ? { fontWeight: cs.fontWeight } : {}),
+                color: cs?.color ?? "#ffffff",
+                ...(cs?.highlightColor ? { highlightColor: cs.highlightColor } : {}),
                 language: "en",
                 effects: [],
                 transform: { x: 0, y: 0, scaleX: 1, scaleY: 1, rotation: 0, opacity: 1 },
@@ -305,6 +257,34 @@ function planToProject(input) {
             };
             clips.push(captionClip);
         }
+        // CH-6 — B-roll overlays: each renders on the second video lane (above the
+        // main visual) within this scene's window. assetUrl points at an existing
+        // asset (no generation here); volume 0 so the overlay is silent by default.
+        if (scene.broll?.length) {
+            scene.broll.forEach((b, k) => {
+                const start = display.from + Math.max(0, Math.min(sceneDurationMs - 1, b.startMs ?? 0));
+                const maxTo = display.from + sceneDurationMs;
+                const to = b.durationMs ? Math.min(start + b.durationMs, maxTo) : maxTo;
+                const brollId = `scene-${scene.sceneIndex}-broll-${k}`;
+                const common = {
+                    id: brollId,
+                    trackId: planToProject_helpers_1.TRACK_ID.broll,
+                    display: { from: start, to },
+                    name: `B-roll ${scene.sceneIndex + 1}.${k + 1}`,
+                    src: b.assetUrl,
+                    provenance: (0, planToProject_helpers_1.provenanceForScene)(scene, outcome),
+                    effects: [],
+                    transform: { x: 0, y: 0, scaleX: 1, scaleY: 1, rotation: 0, opacity: 1 },
+                    locked: false,
+                    metadata: { sceneIndex: scene.sceneIndex, broll: true },
+                };
+                const brollClip = b.kind === "image"
+                    ? { ...common, type: "image" }
+                    : { ...common, type: "video", volume: 0, playbackRate: 1 };
+                clips.push(brollClip);
+                hasBroll = true;
+            });
+        }
         offsetMs += sceneDurationMs;
     }
     // Music: one clip spanning the full duration on the music track.
@@ -316,14 +296,14 @@ function planToProject(input) {
             (plan.music?.durationSec ? plan.music.durationSec * 1000 : offsetMs);
         const musicClip = {
             id: "music",
-            trackId: exports.TRACK_ID.music,
+            trackId: planToProject_helpers_1.TRACK_ID.music,
             type: "audio",
             display: { from: 0, to: offsetMs },
             name: "Music",
             src: resolvedMusicUrl,
             volume: 0.4,
             trim: musicMs > offsetMs ? { from: 0, to: offsetMs } : undefined,
-            duckAgainstTrackId: hasVoiceover ? exports.TRACK_ID.voiceover : undefined,
+            duckAgainstTrackId: hasVoiceover ? planToProject_helpers_1.TRACK_ID.voiceover : undefined,
             fadeInMs: 1500,
             fadeOutMs: 1000,
             provenance: {
@@ -342,19 +322,68 @@ function planToProject(input) {
         };
         clips.push(musicClip);
     }
+    // Stage 7 (lock enforcement) — overlay preserved clips verbatim. Runs after
+    // ALL clips (incl. music) are built so a preserved clip cleanly displaces
+    // its freshly-rebuilt twin by id (ids are deterministic: scene-N-visual /
+    // -vo / -caption / -overlay-K / -broll-K, plus "music"). A preserved clip
+    // with no rebuilt twin (e.g. a user-added clip not tied to any plan scene)
+    // is appended so it survives the rebuild. We keep the prior clip object
+    // as-is: it carries the user's edits, which exist nowhere in plan+outcome.
+    //
+    // Known v0 limitation: a preserved clip keeps its prior display.from/to, so
+    // if neighbouring (regenerated) scenes change duration the frozen clip can
+    // drift out of alignment. Full timeline reconciliation is the diff engine's
+    // job; preserving verbatim (the user locked position too) is the safe read,
+    // and matches the coarse over-preserve contract in planMutations.
+    if (input.preserveClips?.length) {
+        const preservedById = new Map(input.preserveClips.map((c) => [c.id, c]));
+        for (let i = 0; i < clips.length; i++) {
+            const replacement = preservedById.get(clips[i].id);
+            if (replacement) {
+                clips[i] = replacement;
+                preservedById.delete(replacement.id);
+            }
+        }
+        for (const leftover of preservedById.values()) {
+            clips.push(leftover);
+            // Make sure the leftover's track gets declared below.
+            switch (leftover.trackId) {
+                case planToProject_helpers_1.TRACK_ID.broll:
+                    hasBroll = true;
+                    break;
+                case planToProject_helpers_1.TRACK_ID.voiceover:
+                    hasVoiceover = true;
+                    break;
+                case planToProject_helpers_1.TRACK_ID.music:
+                    hasMusic = true;
+                    break;
+                case planToProject_helpers_1.TRACK_ID.text:
+                    hasOverlays = true;
+                    break;
+                case planToProject_helpers_1.TRACK_ID.caption:
+                    hasCaptions = true;
+                    break;
+                default: break; // visual track is always declared
+            }
+        }
+    }
     // Build tracks list (only declare tracks that actually have clips).
     const tracks = [];
     let trackIndex = 0;
     // Stacking: visual at 0, captions/text above, audio below in order.
-    tracks.push(makeTrack(exports.TRACK_ID.visual, "video", trackIndex++, "Video"));
+    tracks.push((0, planToProject_helpers_1.makeTrack)(planToProject_helpers_1.TRACK_ID.visual, "video", trackIndex++, "Video"));
+    // CH-6 — B-roll lane sits directly above the main video (higher index =
+    // painted on top) so overlays show over the scene's primary visual.
+    if (hasBroll)
+        tracks.push((0, planToProject_helpers_1.makeTrack)(planToProject_helpers_1.TRACK_ID.broll, "video", trackIndex++, "B-roll"));
     if (hasVoiceover)
-        tracks.push(makeTrack(exports.TRACK_ID.voiceover, "audio", trackIndex++, "Voiceover"));
+        tracks.push((0, planToProject_helpers_1.makeTrack)(planToProject_helpers_1.TRACK_ID.voiceover, "audio", trackIndex++, "Voiceover"));
     if (hasMusic)
-        tracks.push(makeTrack(exports.TRACK_ID.music, "audio", trackIndex++, "Music"));
+        tracks.push((0, planToProject_helpers_1.makeTrack)(planToProject_helpers_1.TRACK_ID.music, "audio", trackIndex++, "Music"));
     if (hasOverlays)
-        tracks.push(makeTrack(exports.TRACK_ID.text, "text", trackIndex++, "Text"));
+        tracks.push((0, planToProject_helpers_1.makeTrack)(planToProject_helpers_1.TRACK_ID.text, "text", trackIndex++, "Text"));
     if (hasCaptions)
-        tracks.push(makeTrack(exports.TRACK_ID.caption, "caption", trackIndex++, "Captions"));
+        tracks.push((0, planToProject_helpers_1.makeTrack)(planToProject_helpers_1.TRACK_ID.caption, "caption", trackIndex++, "Captions"));
     const durationMs = Math.max(1, offsetMs);
     return {
         schemaVersion: project_schema_1.PROJECT_SCHEMA_VERSION,
@@ -381,15 +410,3 @@ function planToProject(input) {
         updatedAt,
     };
 }
-function makeTrack(id, kind, index, name) {
-    return {
-        id,
-        kind,
-        name,
-        index,
-        muted: false,
-        hidden: false,
-        locked: false,
-        gainDb: 0,
-    };
-}

package/lib/services/editor/planToProject.types.d.ts

@@ -0,0 +1,94 @@
+import type { Clip } from "../../schemas/project.schema";
+import type { VideoPlan } from "../../schemas/videoPlan.schema";
+/**
+ * Input/outcome types for planToProject. Kept separate from the translator so
+ * callers (executor host, regen handlers) can import the shapes without pulling
+ * the full builder.
+ */
+export interface SceneRenderOutcome {
+    /** Resolved URL for the scene's visual asset (image or video). */
+    visualUrl?: string;
+    /**
+     * AG-2 / L-4 extend chain. When a scene's visual was built as a source clip +
+     * N native extensions (too-long scene on an extend-capable model), the host's
+     * resolveExtendChain fills this with the sub-clips in render order. When
+     * present (length ≥ 2) planToProject lays them out as adjacent video clips
+     * spanning the scene's time window, which the renderer concatenates. A single
+     * resolved clip falls back to the `visualUrl` path.
+     */
+    clips?: Array<{
+        visualUrl: string;
+        durationSec: number;
+        taskId?: string;
+    }>;
+    /** Resolved URL for the scene's voiceover. */
+    voiceoverUrl?: string;
+    /**
+     * VO duration in ms used by planToProject to size the clip's display
+     * window. When set from a probed actual mp3 (preferred), reflects real
+     * playback length; when set from the wpm estimator it can undershoot
+     * emotive/punctuated lines by 400–900ms and the editor's Remotion Audio
+     * truncates at endAt. Caller should set the actual when available.
+     */
+    voiceoverDurationMs?: number;
+    /** Resolved URL for an external captions file (.vtt/.srt) if any. */
+    captionsUrl?: string;
+    /** Word-level caption timing (start/end ms within scene). */
+    captionWords?: Array<{
+        word: string;
+        start: number;
+        end: number;
+    }>;
+    /** Final model key the executor landed on (may differ from preferredModel). */
+    modelKey?: string;
+    /** Provider chain walked, primary first; recorded in provenance. */
+    attemptedProviders?: string[];
+    /** P-UNS-2: stock attribution to record in clip provenance (Unsplash credit). */
+    attribution?: {
+        name: string;
+        url?: string;
+    };
+    /** Provider idempotency key (used for reuse on regen). */
+    generationId?: string;
+    /** Credits actually spent on this scene. */
+    creditsSpent?: number;
+    /** Content hash of the visual asset, when computed. */
+    assetHash?: string;
+}
+export interface PlanToProjectInput {
+    plan: VideoPlan;
+    outcomes?: Record<number, SceneRenderOutcome | undefined>;
+    projectId: string;
+    name?: string;
+    agentRunId?: string;
+    /** When set, overrides plan.music.url (caller can swap to CDN-hosted version). */
+    musicUrl?: string;
+    /** Music duration in ms; falls back to plan.music.durationSec*1000 if unset. */
+    musicDurationMs?: number;
+    /** Project createdAt; defaults to now. */
+    createdAt?: string;
+    /** Project updatedAt; defaults to now. */
+    updatedAt?: string;
+    /**
+     * Stage 7 (lock enforcement) — clips from the prior project that must be
+     * reproduced verbatim, displacing any freshly-built clip with the same id.
+     * Supply the output of `computePreservedClips(priorProject, allowedMutations)`.
+     * A locked/user-placed clip carries edits (trim, volume, text, position)
+     * that exist nowhere in the plan, so it cannot be rebuilt — only kept as-is.
+     * Empty / unset on a first run or when nothing is protected (a no-op).
+     */
+    preserveClips?: Clip[];
+    /**
+     * Gap #1 follow-up (skip-generation). Scene indices whose visual is frozen
+     * (preserved verbatim — see `preserveClips`). For these we DON'T build a
+     * placeholder visual clip from plan+outcome: the executor skipped generation
+     * so there's no real URL, and a placeholder twin would either be redundantly
+     * overridden (single-clip ids match) or — worse — leak a stray PLACEHOLDER
+     * clip when the preserved visual is an extend-chain (ids `-0`/`-1` don't
+     * match the rebuilt single `scene-N-visual`). Instead we skip the build and
+     * let the preserve-override inject the real clip(s), anchoring transitions on
+     * the preserved ids. Derive via `computeFrozenScenes(preserveClips).visual`.
+     */
+    frozenVisualScenes?: ReadonlySet<number>;
+}
+//# sourceMappingURL=planToProject.types.d.ts.map

package/lib/services/editor/planToProject.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planToProject.types.d.ts","sourceRoot":"","sources":["../../../src/services/editor/planToProject.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAEhE;;;;GAIG;AAEH,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3E,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnE,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,iFAAiF;IACjF,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,CAAC,CAAC;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,IAAI,EAAE,CAAC;IACvB;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC1C"}

package/lib/services/editor/planToProject.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/services/firestore.service.d.ts

@@ -8,6 +8,7 @@ import { IImageJobModel } from "../models/image.model";
 import { INotificationModel } from "../models/notification.model";
 import { IRefModel } from "../models/ref.model";
 import { IMediaUploadModel } from "../models/mediaUpload.model";
+import { ISocialAccountModel, ISocialAnalyticsModel, ISocialInboxItemModel, ISocialPostModel } from "../models/social.model";
 import { IShareModel } from "../models/share.model";
 import { IUserModel } from "../models/user.model";
 import { IVideoJobModel } from "../models/video.model";
@@ -50,6 +51,10 @@ export declare class FirestoreService {
     static agentRunsCol: CollectionReference<IAgentRunModel, DocumentData>;
     static sharesCol: CollectionReference<IShareModel, DocumentData>;
     static mediaUploadsCol: CollectionReference<IMediaUploadModel, DocumentData>;
+    static socialAccountsCol: CollectionReference<ISocialAccountModel, DocumentData>;
+    static socialPostsCol: CollectionReference<ISocialPostModel, DocumentData>;
+    static socialAnalyticsCol: CollectionReference<ISocialAnalyticsModel, DocumentData>;
+    static socialInboxCol: CollectionReference<ISocialInboxItemModel, DocumentData>;
     /** Add new document with generated ID */
     static appendNewRecord<T>(collectionRef: CollectionReference<T>, data: T): Promise<DocumentReference<T>>;
     /** Add or overwrite a document with a specific ID */

package/lib/services/firestore.service.d.ts.map

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

package/lib/services/firestore.service.js

@@ -156,3 +156,16 @@ FirestoreService.sharesCol = firebase_1.firestore
 FirestoreService.mediaUploadsCol = firebase_1.firestore
     .collection("mediaUploads")
     .withConverter(collectionConverter());
+// 🔹 X8 Social Suite — see notes/SOCIAL_SUITE_PLAN.md
+FirestoreService.socialAccountsCol = firebase_1.firestore
+    .collection("socialAccounts")
+    .withConverter(collectionConverter());
+FirestoreService.socialPostsCol = firebase_1.firestore
+    .collection("socialPosts")
+    .withConverter(collectionConverter());
+FirestoreService.socialAnalyticsCol = firebase_1.firestore
+    .collection("socialAnalytics")
+    .withConverter(collectionConverter());
+FirestoreService.socialInboxCol = firebase_1.firestore
+    .collection("socialInbox")
+    .withConverter(collectionConverter());