visualfries 0.1.10120 → 0.3.2

package/dist/agent/cueFiles.js

@@ -0,0 +1,219 @@
+import path from 'node:path';
+import { addAgentBrollSequence } from './broll.js';
+import { AGENT_BROLL_MOTIONS, AGENT_OVERLAY_STYLES, AGENT_TRANSITION_STYLES } from './catalog.js';
+import { addAgentTextOverlays } from './overlays.js';
+import { addAgentTransitions } from './transitions.js';
+import { SceneShape } from '../schemas/scene/index.js';
+export function mergeAgentCueFiles(...cueFiles) {
+    return cueFiles.reduce((merged, cues) => ({
+        ...merged,
+        ...cues,
+        broll: [...(merged.broll ?? []), ...(cues.broll ?? [])],
+        overlays: [...(merged.overlays ?? []), ...(cues.overlays ?? [])],
+        transitions: [...(merged.transitions ?? []), ...(cues.transitions ?? [])]
+    }), {});
+}
+function cueArray(cues, key) {
+    const value = cues[key];
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        throw new Error(`cues.${String(key)} must be an array.`);
+    }
+    return value;
+}
+function isPortableUrl(value) {
+    return /^[a-z]+:\/\//i.test(value) || value.startsWith('file://') || value.startsWith('data:');
+}
+export function normalizeAgentCueFile(cues, cueFilePath) {
+    const baseDir = cueFilePath ? path.dirname(path.resolve(cueFilePath)) : undefined;
+    const broll = cueArray(cues, 'broll').map((cue) => {
+        if (!baseDir || !cue.url || isPortableUrl(cue.url) || path.isAbsolute(cue.url))
+            return cue;
+        return {
+            ...cue,
+            url: path.join(baseDir, cue.url)
+        };
+    });
+    return {
+        ...cues,
+        broll,
+        overlays: cueArray(cues, 'overlays'),
+        transitions: cueArray(cues, 'transitions')
+    };
+}
+function isNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function checkRange(issues, path, start, end, duration) {
+    if (!isNumber(start)) {
+        issues.push({
+            level: 'error',
+            path: `${path}.start`,
+            message: 'start must be a finite number.'
+        });
+    }
+    if (!isNumber(end)) {
+        issues.push({ level: 'error', path: `${path}.end`, message: 'end must be a finite number.' });
+    }
+    if (isNumber(start) && isNumber(end) && end < start) {
+        issues.push({
+            level: 'error',
+            path: `${path}.end`,
+            message: 'end must be greater than or equal to start.'
+        });
+    }
+    if (duration !== undefined && isNumber(end) && end > duration) {
+        issues.push({
+            level: 'warning',
+            path: `${path}.end`,
+            message: `end is outside scene duration (${end}s > ${duration}s).`
+        });
+    }
+}
+export function validateAgentCueFile(input) {
+    const cues = normalizeAgentCueFile(input.cues, input.cueFilePath);
+    const broll = cues.broll ?? [];
+    const overlays = cues.overlays ?? [];
+    const transitions = cues.transitions ?? [];
+    const issues = [];
+    const durationIsValid = input.duration === undefined || (isNumber(input.duration) && input.duration > 0);
+    if (!durationIsValid) {
+        issues.push({
+            level: 'error',
+            path: 'duration',
+            message: 'duration must be a finite number greater than 0.'
+        });
+    }
+    for (const [index, cue] of broll.entries()) {
+        const pathPrefix = `broll[${index}]`;
+        if (!cue.url || typeof cue.url !== 'string') {
+            issues.push({ level: 'error', path: `${pathPrefix}.url`, message: 'url is required.' });
+        }
+        if (cue.motion &&
+            !AGENT_BROLL_MOTIONS.includes(cue.motion)) {
+            issues.push({
+                level: 'error',
+                path: `${pathPrefix}.motion`,
+                message: `Unknown b-roll motion "${cue.motion}".`
+            });
+        }
+        checkRange(issues, pathPrefix, cue.start, cue.end, input.duration);
+    }
+    for (const [index, cue] of overlays.entries()) {
+        const pathPrefix = `overlays[${index}]`;
+        if (!cue.text || typeof cue.text !== 'string') {
+            issues.push({ level: 'error', path: `${pathPrefix}.text`, message: 'text is required.' });
+        }
+        if (cue.style &&
+            !AGENT_OVERLAY_STYLES.includes(cue.style)) {
+            issues.push({
+                level: 'error',
+                path: `${pathPrefix}.style`,
+                message: `Unknown overlay style "${cue.style}".`
+            });
+        }
+        checkRange(issues, pathPrefix, cue.start, cue.end, input.duration);
+    }
+    for (const [index, cue] of transitions.entries()) {
+        const pathPrefix = `transitions[${index}]`;
+        if (!isNumber(cue.time)) {
+            issues.push({
+                level: 'error',
+                path: `${pathPrefix}.time`,
+                message: 'time must be a finite number.'
+            });
+        }
+        else if (cue.time < 0) {
+            issues.push({
+                level: 'error',
+                path: `${pathPrefix}.time`,
+                message: 'time must be greater than or equal to 0.'
+            });
+        }
+        if (cue.duration !== undefined && (!isNumber(cue.duration) || cue.duration <= 0)) {
+            issues.push({
+                level: 'error',
+                path: `${pathPrefix}.duration`,
+                message: 'duration must be a finite number greater than 0.'
+            });
+        }
+        if (cue.style &&
+            !AGENT_TRANSITION_STYLES.includes(cue.style)) {
+            issues.push({
+                level: 'error',
+                path: `${pathPrefix}.style`,
+                message: `Unknown transition style "${cue.style}".`
+            });
+        }
+        if (durationIsValid &&
+            input.duration !== undefined &&
+            isNumber(cue.time) &&
+            cue.time > input.duration) {
+            issues.push({
+                level: 'warning',
+                path: `${pathPrefix}.time`,
+                message: `time is outside scene duration (${cue.time}s > ${input.duration}s).`
+            });
+        }
+    }
+    return {
+        valid: !issues.some((issue) => issue.level === 'error'),
+        issues,
+        summary: {
+            broll: broll.length,
+            overlays: overlays.length,
+            transitions: transitions.length
+        }
+    };
+}
+export function applyAgentCueFile(input) {
+    const cues = normalizeAgentCueFile(input.cues, input.cueFilePath);
+    let scene = SceneShape.parse(input.scene);
+    const validation = validateAgentCueFile({
+        cues,
+        cueFilePath: input.cueFilePath,
+        duration: scene.settings.duration
+    });
+    if (!validation.valid) {
+        throw new Error(`Invalid cue file: ${JSON.stringify(validation.issues, null, 2)}`);
+    }
+    const broll = cues.broll ?? [];
+    const overlays = cues.overlays ?? [];
+    const transitions = cues.transitions ?? [];
+    if (broll.length > 0) {
+        scene = addAgentBrollSequence({
+            scene,
+            cues: broll,
+            layerId: cues.brollLayerId,
+            layerName: cues.brollLayerName,
+            layerOrder: cues.brollLayerOrder
+        });
+    }
+    if (overlays.length > 0) {
+        scene = addAgentTextOverlays({
+            scene,
+            overlays,
+            layerId: cues.overlayLayerId,
+            layerName: cues.overlayLayerName,
+            layerOrder: cues.overlayLayerOrder
+        });
+    }
+    if (transitions.length > 0) {
+        scene = addAgentTransitions({
+            scene,
+            transitions,
+            layerId: cues.transitionLayerId,
+            layerName: cues.transitionLayerName,
+            layerOrder: cues.transitionLayerOrder
+        });
+    }
+    return {
+        scene: SceneShape.parse(scene),
+        applied: {
+            broll: broll.length,
+            overlays: overlays.length,
+            transitions: transitions.length
+        }
+    };
+}

package/dist/agent/cuePresets.d.ts

@@ -0,0 +1,7 @@
+import type { AgentCueFile } from './cueFiles.js';
+export type AgentCuePresetName = 'hidden-engine-dynamic' | 'captioned-clean';
+export type CreateAgentCuePresetInput = {
+    preset?: AgentCuePresetName;
+    duration: number;
+};
+export declare function createAgentCuePreset(input: CreateAgentCuePresetInput): AgentCueFile;

package/dist/agent/cuePresets.js

@@ -0,0 +1,50 @@
+function clampTime(value, duration) {
+    return Number(Math.min(Math.max(value, 0), duration).toFixed(3));
+}
+function timed(start, length, duration) {
+    const safeStart = clampTime(start, duration);
+    return {
+        start: safeStart,
+        end: clampTime(Math.max(safeStart + 0.1, start + length), duration)
+    };
+}
+function transitionTimes(duration) {
+    const count = Math.max(0, Math.min(8, Math.floor(duration / 5)));
+    return Array.from({ length: count }, (_, index) => clampTime((index + 1) * (duration / (count + 1)), duration));
+}
+export function createAgentCuePreset(input) {
+    const preset = input.preset ?? 'hidden-engine-dynamic';
+    const duration = Math.max(0.5, input.duration);
+    if (preset === 'captioned-clean') {
+        return {
+            overlays: [],
+            broll: [],
+            transitions: transitionTimes(duration).map((time) => ({
+                time,
+                style: 'dip-to-black',
+                duration: 0.18
+            }))
+        };
+    }
+    const hook = timed(0.35, 0.9, duration);
+    const proof = timed(Math.min(8, duration * 0.22), 1.2, duration);
+    const mechanism = timed(Math.min(16, duration * 0.42), 1.15, duration);
+    const choice = timed(Math.max(0.4, duration - 7), 1.1, duration);
+    const cta = timed(Math.max(0.5, duration - 3.2), 1.4, duration);
+    return {
+        overlays: [
+            { text: 'HOOK', ...hook, style: 'hook-punch' },
+            { text: 'PROOF', ...proof, style: 'proof-pill' },
+            { text: 'THE MACHINE', ...mechanism, style: 'metric-badge' },
+            { text: 'CHOOSE', ...choice, style: 'shock-word' },
+            { text: 'your move', ...cta, style: 'cta-card' }
+        ],
+        broll: [],
+        transitions: transitionTimes(duration).map((time, index) => ({
+            time,
+            style: index % 3 === 0 ? 'swipe-left' : 'dip-to-black',
+            color: index % 3 === 0 ? '#04483D' : undefined,
+            duration: index % 3 === 0 ? 0.24 : 0.2
+        }))
+    };
+}

package/dist/agent/deterministicMedia.d.ts

@@ -0,0 +1,61 @@
+import { type Scene } from '../schemas/scene/index.js';
+export type LocalDeterministicMediaStrategy = 'predecoded-image-sequence';
+export type LocalDeterministicFrameExtension = 'jpg' | 'png';
+export type LocalDeterministicMediaComponent = {
+    component: Scene['layers'][number]['components'][number];
+    id: string;
+    type: 'VIDEO' | 'GIF';
+    sourceUrl: string;
+    sourceStartAt: number;
+    sourceEndAt?: number;
+    timelineStartAt: number;
+    timelineEndAt: number;
+};
+export type LocalDeterministicActiveWindow = {
+    activeStartFrame: number;
+    activeEndFrame: number;
+    activeStartSec: number;
+    activeEndSec: number;
+    sourceStartSec: number;
+};
+export type LocalPredecodedExtractionPlan = {
+    sourceStartSec: number;
+    extractFrameCount: number;
+    outputFrameCount: number;
+    sourceEndLimited: boolean;
+};
+export type LocalDeterministicFrameManifest = Record<string, Record<string, string>>;
+export type PrepareLocalDeterministicMediaInput = {
+    scene: unknown;
+    workDir: string;
+    fromFrame: number;
+    toFrame: number;
+    publicBasePath?: string;
+    frameExtension?: LocalDeterministicFrameExtension;
+    jpegQualityScale?: number;
+    strict?: boolean;
+    diagnostics?: boolean;
+};
+export type PrepareLocalDeterministicMediaResult = {
+    preparedScene: Scene;
+    payload: {
+        strategy: 'visualfries-provider-predecoded';
+        frameManifest: LocalDeterministicFrameManifest;
+        diagnosticsEnabled: boolean;
+        mediaDeterministicStrict: boolean;
+    };
+    media: Array<{
+        componentId: string;
+        type: 'VIDEO' | 'GIF';
+        sourceUrl: string;
+        framesPrepared: number;
+    }>;
+    assetsRoot: string;
+    strategyUsed: LocalDeterministicMediaStrategy;
+};
+export declare const normalizeDeterministicPublicBasePath: (value: string) => string;
+export declare function collectLocalDeterministicMediaComponents(input: unknown): LocalDeterministicMediaComponent[];
+export declare function resolveLocalDeterministicActiveWindow(component: LocalDeterministicMediaComponent, fromFrame: number, toFrame: number, fps: number): LocalDeterministicActiveWindow | null;
+export declare function toLocalDeterministicFrameIndex(component: LocalDeterministicMediaComponent, sceneFrameIndex: number, fps: number): number;
+export declare function resolveLocalPredecodedExtractionPlan(sourceStartSec: number, sourceEndSec: number | undefined, expectedFrameCount: number, fps: number): LocalPredecodedExtractionPlan;
+export declare function prepareLocalDeterministicMedia(input: PrepareLocalDeterministicMediaInput): Promise<PrepareLocalDeterministicMediaResult>;

package/dist/agent/deterministicMedia.js

@@ -0,0 +1,303 @@
+import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SceneShape } from '../schemas/scene/index.js';
+const cloneScene = (scene) => JSON.parse(JSON.stringify(scene));
+const normalizeUrl = (value) => {
+    try {
+        const parsed = new URL(value);
+        parsed.search = '';
+        parsed.hash = '';
+        return parsed.toString();
+    }
+    catch {
+        return value;
+    }
+};
+const safeFilePart = (value) => value.replace(/[^a-zA-Z0-9._-]/g, '_');
+export const normalizeDeterministicPublicBasePath = (value) => {
+    const normalized = value.replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+$/, '');
+    const segments = normalized.split('/').filter(Boolean);
+    if (segments.length === 0 || segments.some((segment) => segment === '.' || segment === '..')) {
+        throw new Error('publicBasePath must be a relative URL path without "." or ".." segments.');
+    }
+    return `/${segments.join('/')}`;
+};
+const resolveSafeAssetRoot = (workDir, publicBasePath) => {
+    const root = path.resolve(workDir);
+    const target = path.resolve(root, publicBasePath.slice(1));
+    const relative = path.relative(root, target);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error('publicBasePath must resolve inside workDir.');
+    }
+    return target;
+};
+const toInputPath = (sourceUrl) => {
+    if (sourceUrl.startsWith('file://'))
+        return fileURLToPath(sourceUrl);
+    return sourceUrl;
+};
+const sourceForComponent = (scene, component) => {
+    if (!('source' in component))
+        return undefined;
+    const directUrl = component.source?.url ?? component.source?.streamUrl;
+    if (directUrl)
+        return directUrl;
+    const assetId = component.source?.assetId;
+    return assetId ? scene.assets.find((asset) => asset.id === assetId)?.url : undefined;
+};
+export function collectLocalDeterministicMediaComponents(input) {
+    const scene = SceneShape.parse(input);
+    const media = [];
+    for (const layer of scene.layers ?? []) {
+        if (!layer || layer.muted)
+            continue;
+        for (const component of layer.components ?? []) {
+            if (!component || component.visible === false)
+                continue;
+            if (component.type !== 'VIDEO' && component.type !== 'GIF')
+                continue;
+            const sourceUrl = sourceForComponent(scene, component);
+            if (!sourceUrl)
+                continue;
+            media.push({
+                component,
+                id: component.id || crypto.randomUUID(),
+                type: component.type,
+                sourceUrl,
+                sourceStartAt: 'source' in component ? (component.source?.startAt ?? 0) : 0,
+                sourceEndAt: 'source' in component && typeof component.source?.endAt === 'number'
+                    ? component.source.endAt
+                    : undefined,
+                timelineStartAt: component.timeline?.startAt ?? 0,
+                timelineEndAt: component.timeline?.endAt ?? scene.settings.duration
+            });
+        }
+    }
+    return media;
+}
+export function resolveLocalDeterministicActiveWindow(component, fromFrame, toFrame, fps) {
+    const frameBoundaryEpsilon = 1e-6;
+    const chunkStartSec = fromFrame / fps;
+    const chunkEndSec = toFrame / fps;
+    const activeStartSec = Math.max(chunkStartSec, component.timelineStartAt);
+    const activeEndSec = Math.min(chunkEndSec, component.timelineEndAt);
+    if (activeEndSec <= activeStartSec)
+        return null;
+    const activeStartFrame = Math.max(fromFrame, Math.ceil(activeStartSec * fps - frameBoundaryEpsilon));
+    const activeEndFrame = Math.min(toFrame, Math.ceil(activeEndSec * fps - frameBoundaryEpsilon));
+    if (activeEndFrame <= activeStartFrame)
+        return null;
+    return {
+        activeStartSec,
+        activeEndSec,
+        activeStartFrame,
+        activeEndFrame,
+        sourceStartSec: component.sourceStartAt + (activeStartFrame / fps - component.timelineStartAt)
+    };
+}
+export function toLocalDeterministicFrameIndex(component, sceneFrameIndex, fps) {
+    const timelineStartInFrames = component.timelineStartAt * fps;
+    const sourceStartInFrames = component.sourceStartAt * fps;
+    return Math.max(0, Math.round(sourceStartInFrames + sceneFrameIndex - timelineStartInFrames));
+}
+export function resolveLocalPredecodedExtractionPlan(sourceStartSec, sourceEndSec, expectedFrameCount, fps) {
+    const outputFrameCount = Math.max(0, Math.floor(expectedFrameCount));
+    if (outputFrameCount <= 0) {
+        return { sourceStartSec, extractFrameCount: 0, outputFrameCount: 0, sourceEndLimited: false };
+    }
+    if (typeof sourceEndSec !== 'number' ||
+        !Number.isFinite(sourceEndSec) ||
+        sourceEndSec <= sourceStartSec) {
+        if (typeof sourceEndSec === 'number' && sourceEndSec <= sourceStartSec) {
+            return {
+                sourceStartSec: Math.max(0, sourceEndSec - 1 / fps),
+                extractFrameCount: 1,
+                outputFrameCount,
+                sourceEndLimited: true
+            };
+        }
+        return {
+            sourceStartSec,
+            extractFrameCount: outputFrameCount,
+            outputFrameCount,
+            sourceEndLimited: false
+        };
+    }
+    const availableFrames = Math.max(1, Math.ceil((sourceEndSec - sourceStartSec) * fps - 1e-6));
+    return {
+        sourceStartSec,
+        extractFrameCount: Math.min(outputFrameCount, availableFrames),
+        outputFrameCount,
+        sourceEndLimited: availableFrames < outputFrameCount
+    };
+}
+const runFfmpeg = async (args, label) => {
+    const ffmpegPath = process.env.FFMPEG_PATH || 'ffmpeg';
+    await new Promise((resolve, reject) => {
+        const child = spawn(ffmpegPath, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => {
+            stderr = (stderr + String(chunk)).slice(-4000);
+        });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`[visualfries deterministic media][${label}] ffmpeg exited ${code}. ${stderr}`));
+            }
+        });
+    });
+};
+const listFrameFiles = async (dir, extension) => {
+    const files = (await fs.readdir(dir))
+        .filter((file) => file.toLowerCase().endsWith(`.${extension}`))
+        .sort((a, b) => Number(path.basename(a, `.${extension}`)) - Number(path.basename(b, `.${extension}`)))
+        .map((file) => path.join(dir, file));
+    return files;
+};
+const extractFrameSequence = async (options) => {
+    await fs.mkdir(options.outputDir, { recursive: true });
+    const outputPattern = path.join(options.outputDir, `%d.${options.extension}`);
+    const seekMode = options.seekMode ?? 'fast';
+    const paddedDurationSec = options.expectedFrameCount / options.fps + 0.5 / options.fps;
+    const args = ['-y'];
+    if (seekMode === 'fast') {
+        args.push('-ss', options.sourceStartSec.toFixed(6));
+    }
+    args.push('-i', options.inputPath);
+    if (seekMode === 'accurate') {
+        args.push('-ss', options.sourceStartSec.toFixed(6));
+    }
+    args.push('-t', paddedDurationSec.toFixed(6), '-vf', `fps=${options.fps}:round=near:start_time=0`, '-frames:v', String(options.expectedFrameCount), '-vsync', 'cfr', '-start_number', '1');
+    if (options.extension === 'jpg') {
+        args.push('-q:v', String(options.jpegQualityScale), '-pix_fmt', 'yuvj420p');
+    }
+    else {
+        args.push('-compression_level', '3');
+    }
+    args.push(outputPattern);
+    await runFfmpeg(args, options.label ?? 'extract-frame-sequence');
+    return listFrameFiles(options.outputDir, options.extension);
+};
+const padTrailingFrames = async (outputDir, extension, frames, expectedFrameCount) => {
+    if (frames.length === expectedFrameCount ||
+        frames.length === 0 ||
+        frames.length > expectedFrameCount) {
+        return frames;
+    }
+    const lastFrame = frames[frames.length - 1];
+    for (let index = frames.length + 1; index <= expectedFrameCount; index += 1) {
+        await fs.copyFile(lastFrame, path.join(outputDir, `${index}.${extension}`));
+    }
+    return listFrameFiles(outputDir, extension);
+};
+const assignBoundaryFrames = (manifest, componentId, frameIndex, frameUrl, radius = 2) => {
+    manifest[componentId] = manifest[componentId] ?? {};
+    for (let index = Math.max(0, frameIndex - radius); index <= frameIndex + radius; index += 1) {
+        manifest[componentId][String(index)] ??= frameUrl;
+    }
+};
+export async function prepareLocalDeterministicMedia(input) {
+    const scene = cloneScene(SceneShape.parse(input.scene));
+    const fps = scene.settings.fps || 30;
+    const publicBasePath = normalizeDeterministicPublicBasePath(input.publicBasePath ?? '/deterministic-media');
+    const frameExtension = input.frameExtension ?? 'jpg';
+    const jpegQualityScale = Math.max(1, Math.min(31, Math.floor(input.jpegQualityScale ?? 2)));
+    const assetsRoot = resolveSafeAssetRoot(input.workDir, publicBasePath);
+    const predecodedRoot = path.join(assetsRoot, 'predecoded');
+    await fs.mkdir(predecodedRoot, { recursive: true });
+    const mediaComponents = collectLocalDeterministicMediaComponents(scene);
+    const frameManifest = {};
+    const preparedMedia = [];
+    for (const media of mediaComponents) {
+        const activeWindow = resolveLocalDeterministicActiveWindow(media, input.fromFrame, input.toFrame, fps);
+        if (!activeWindow)
+            continue;
+        const componentDirName = safeFilePart(media.id);
+        const componentOutputDir = path.join(predecodedRoot, componentDirName);
+        await fs.rm(componentOutputDir, { recursive: true, force: true });
+        await fs.mkdir(componentOutputDir, { recursive: true });
+        const activeStartFrame = activeWindow.activeStartFrame;
+        const expectedFrameCount = activeWindow.activeEndFrame - activeWindow.activeStartFrame;
+        if (expectedFrameCount <= 0)
+            continue;
+        const extractionPlan = resolveLocalPredecodedExtractionPlan(activeWindow.sourceStartSec, media.sourceEndAt, expectedFrameCount, fps);
+        if (extractionPlan.extractFrameCount <= 0)
+            continue;
+        const sourceInput = toInputPath(media.sourceUrl);
+        if (!/^https?:\/\//.test(sourceInput) && !existsSync(sourceInput)) {
+            throw new Error(`VisualFries deterministic media source does not exist: ${media.sourceUrl}`);
+        }
+        let frames = await extractFrameSequence({
+            inputPath: sourceInput,
+            outputDir: componentOutputDir,
+            sourceStartSec: extractionPlan.sourceStartSec,
+            expectedFrameCount: extractionPlan.extractFrameCount,
+            fps,
+            extension: frameExtension,
+            jpegQualityScale,
+            seekMode: 'fast',
+            label: `${media.id}:fast`
+        });
+        if (frames.length < extractionPlan.extractFrameCount) {
+            for (const framePath of frames)
+                await fs.rm(framePath, { force: true });
+            frames = await extractFrameSequence({
+                inputPath: sourceInput,
+                outputDir: componentOutputDir,
+                sourceStartSec: extractionPlan.sourceStartSec,
+                expectedFrameCount: extractionPlan.extractFrameCount,
+                fps,
+                extension: frameExtension,
+                jpegQualityScale,
+                seekMode: 'accurate',
+                label: `${media.id}:accurate-retry`
+            });
+        }
+        frames = await padTrailingFrames(componentOutputDir, frameExtension, frames, expectedFrameCount);
+        if (frames.length < expectedFrameCount) {
+            throw new Error(`VisualFries deterministic media missing frames for ${media.id}: expected ${expectedFrameCount}, got ${frames.length}`);
+        }
+        const firstDeterministicFrameIndex = activeWindow
+            ? toLocalDeterministicFrameIndex(media, activeStartFrame, fps)
+            : Math.round(media.sourceStartAt * fps);
+        const firstFrameUrl = `${publicBasePath}/predecoded/${componentDirName}/1.${frameExtension}`;
+        assignBoundaryFrames(frameManifest, media.id, Math.round(media.sourceStartAt * fps), firstFrameUrl);
+        for (let index = 0; index < expectedFrameCount; index += 1) {
+            const fileName = `${index + 1}.${frameExtension}`;
+            const fullPath = path.join(componentOutputDir, fileName);
+            if (!existsSync(fullPath)) {
+                throw new Error(`VisualFries deterministic media frame missing: ${fullPath}`);
+            }
+            frameManifest[media.id] = frameManifest[media.id] ?? {};
+            frameManifest[media.id][String(firstDeterministicFrameIndex + index)] =
+                `${publicBasePath}/predecoded/${componentDirName}/${fileName}`;
+        }
+        const lastFrameUrl = `${publicBasePath}/predecoded/${componentDirName}/${expectedFrameCount}.${frameExtension}`;
+        assignBoundaryFrames(frameManifest, media.id, firstDeterministicFrameIndex + expectedFrameCount - 1, lastFrameUrl);
+        preparedMedia.push({
+            componentId: media.id,
+            type: media.type,
+            sourceUrl: normalizeUrl(media.sourceUrl),
+            framesPrepared: expectedFrameCount
+        });
+    }
+    return {
+        preparedScene: scene,
+        payload: {
+            strategy: 'visualfries-provider-predecoded',
+            frameManifest,
+            diagnosticsEnabled: input.diagnostics ?? false,
+            mediaDeterministicStrict: input.strict ?? true
+        },
+        media: preparedMedia,
+        assetsRoot,
+        strategyUsed: 'predecoded-image-sequence'
+    };
+}

package/dist/agent/index.d.ts

@@ -0,0 +1,18 @@
+export * from './audioMixer.js';
+export * from './broll.js';
+export * from './catalog.js';
+export * from './capabilities.js';
+export * from './captionScene.js';
+export * from './cueFiles.js';
+export * from './cuePresets.js';
+export * from './deterministicMedia.js';
+export * from './inspectScene.js';
+export * from './localRender.js';
+export * from './overlays.js';
+export * from './productionPlan.js';
+export * from './runtimeSupport.js';
+export * from './renderPlan.js';
+export * from './renderRanges.js';
+export * from './streamingEncoder.js';
+export * from './transcripts.js';
+export * from './transitions.js';

package/dist/agent/index.js

@@ -0,0 +1,18 @@
+export * from './audioMixer.js';
+export * from './broll.js';
+export * from './catalog.js';
+export * from './capabilities.js';
+export * from './captionScene.js';
+export * from './cueFiles.js';
+export * from './cuePresets.js';
+export * from './deterministicMedia.js';
+export * from './inspectScene.js';
+export * from './localRender.js';
+export * from './overlays.js';
+export * from './productionPlan.js';
+export * from './runtimeSupport.js';
+export * from './renderPlan.js';
+export * from './renderRanges.js';
+export * from './streamingEncoder.js';
+export * from './transcripts.js';
+export * from './transitions.js';