visualfries 0.1.10115 → 0.3.2

package/dist/agent/runtimeSupport.js

@@ -0,0 +1,192 @@
+import { getComponentCapability } from './capabilities.js';
+const TWEEN_CONTROL_KEYS = new Set([
+    'from',
+    'duration',
+    'ease',
+    'delay',
+    'stagger',
+    'repeat',
+    'yoyo',
+    'repeatDelay',
+    'overwrite',
+    'onStart',
+    'onUpdate',
+    'onComplete',
+    'onRepeat',
+    'onReverseComplete'
+]);
+const KNOWN_TRANSFORMS = new Set([
+    'x',
+    'y',
+    'opacity',
+    'rotation',
+    'scale',
+    'scaleX',
+    'scaleY'
+]);
+function levelFor(mode) {
+    return mode === 'strict' ? 'error' : 'warning';
+}
+function issue(mode, component, layerId, data) {
+    return {
+        level: levelFor(mode),
+        type: 'runtime-support',
+        componentId: component.id,
+        layerId,
+        ...data
+    };
+}
+function selectorKind(target) {
+    if (typeof target !== 'string' || target === '' || target === 'container')
+        return 'container';
+    if (target === 'words' || target === 'lines' || target === 'chars')
+        return target;
+    return 'css';
+}
+function inspectTween(vars, path, capability, component, layerId, mode, issues) {
+    if (!vars)
+        return;
+    const states = [vars, typeof vars.from === 'object' && vars.from ? vars.from : undefined];
+    for (const [stateIndex, state] of states.entries()) {
+        if (!state)
+            continue;
+        for (const property of Object.keys(state)) {
+            if (TWEEN_CONTROL_KEYS.has(property))
+                continue;
+            if (!KNOWN_TRANSFORMS.has(property)) {
+                issues.push(issue(mode, component, layerId, {
+                    code: 'runtime-animation-property-unsupported',
+                    capabilityId: `component.${component.type}.animation.property.${property}`,
+                    path: `${path}${stateIndex === 1 ? '.from' : ''}.${property}`,
+                    message: `${component.type} does not guarantee animation property "${property}" at runtime.`
+                }));
+                continue;
+            }
+            if (!capability.animation.transforms.includes(property)) {
+                issues.push(issue(mode, component, layerId, {
+                    code: 'runtime-animation-property-unsupported',
+                    capabilityId: `component.${component.type}.animation.property.${property}`,
+                    path: `${path}${stateIndex === 1 ? '.from' : ''}.${property}`,
+                    message: `${component.type} accepts "${property}" in schema but does not evaluate it at runtime.`
+                }));
+            }
+        }
+    }
+}
+export function analyzeRuntimeSupport(scene, options = {}) {
+    const mode = options.mode ?? 'warn';
+    const issues = [];
+    for (const [layerIndex, layer] of (scene.layers ?? []).entries()) {
+        for (const [componentIndex, component] of (layer.components ?? []).entries()) {
+            const componentPath = `layers.${layerIndex}.components.${componentIndex}`;
+            const capability = getComponentCapability(component.type);
+            if (!capability)
+                continue;
+            if (capability.visual && capability.renderers.preview === 'none') {
+                issues.push(issue(mode, component, layer.id, {
+                    code: 'runtime-renderer-missing',
+                    capabilityId: `component.${component.type}.runtime.rendered`,
+                    path: componentPath,
+                    message: `${component.type} is accepted by schema but has no component render hook.`
+                }));
+            }
+            const animations = component.animations;
+            const enabledAnimations = animations?.enabled === false
+                ? []
+                : (animations?.list ?? []).filter((entry) => entry != null && entry.enabled !== false);
+            if (enabledAnimations.length > 0 && !capability.animation.attached) {
+                issues.push(issue(mode, component, layer.id, {
+                    code: 'runtime-animation-unsupported',
+                    capabilityId: `component.${component.type}.animation.attachment`,
+                    path: `${componentPath}.animations`,
+                    message: `${component.type} animation data validates but is not attached to a runtime animation target.`
+                }));
+            }
+            for (const [animationIndex, entry] of enabledAnimations.entries()) {
+                const basePath = `${componentPath}.animations.list.${animationIndex}`;
+                const animation = entry.animation;
+                if (typeof animation === 'string') {
+                    // System presets are resolved at construction time. Their concrete timeline is not
+                    // duplicated here; unresolved names are surfaced by the runtime explain path.
+                    continue;
+                }
+                const animationObject = animation;
+                const keyframe = animationObject.tween;
+                if (keyframe) {
+                    const target = selectorKind(animationObject.target);
+                    if (!capability.animation.selectors.includes(target)) {
+                        issues.push(issue(mode, component, layer.id, {
+                            code: 'runtime-animation-selector-unsupported',
+                            capabilityId: `component.${component.type}.animation.selector.${target}`,
+                            path: `${basePath}.target`,
+                            message: `${component.type} animation target "${String(animationObject.target)}" collapses to or misses the runtime target.`
+                        }));
+                    }
+                    inspectTween(keyframe.vars, `${basePath}.tween.vars`, capability, component, layer.id, mode, issues);
+                }
+                for (const [itemIndex, item] of (animationObject.timeline ?? []).entries()) {
+                    const sequence = item;
+                    const target = selectorKind(sequence.target);
+                    if (!capability.animation.selectors.includes(target)) {
+                        issues.push(issue(mode, component, layer.id, {
+                            code: 'runtime-animation-selector-unsupported',
+                            capabilityId: `component.${component.type}.animation.selector.${target}`,
+                            path: `${basePath}.timeline.${itemIndex}.target`,
+                            message: `${component.type} does not support animation selector "${String(sequence.target)}".`
+                        }));
+                    }
+                    for (const [tweenIndex, tween] of (sequence.tweens ?? []).entries()) {
+                        inspectTween(tween.vars, `${basePath}.timeline.${itemIndex}.tweens.${tweenIndex}.vars`, capability, component, layer.id, mode, issues);
+                    }
+                }
+            }
+            if (component.effects?.enabled !== false) {
+                for (const [effectId, effect] of Object.entries(component.effects?.map ?? {})) {
+                    const effectType = effect?.type;
+                    if (effectType && !capability.effects.supported.includes(effectType)) {
+                        issues.push(issue(mode, component, layer.id, {
+                            code: 'runtime-effect-unsupported',
+                            capabilityId: `component.${component.type}.effect.${effectType}`,
+                            path: `${componentPath}.effects.map.${effectId}`,
+                            message: `${effectType} is accepted for ${component.type} but is not in its runtime-supported effect set.`
+                        }));
+                    }
+                }
+            }
+            if (component.type === 'TEXT' || component.type === 'SUBTITLES') {
+                const text = component.appearance.text;
+                if (text.activeWord?.enabled && text.activeLine?.enabled) {
+                    issues.push(issue(mode, component, layer.id, {
+                        code: 'runtime-text-highlight-conflict',
+                        capabilityId: `component.${component.type}.text.activeHighlight.precedence`,
+                        path: `${componentPath}.appearance.text`,
+                        message: 'activeWord and activeLine target the same glyphs; activeWord takes deterministic precedence.'
+                    }));
+                }
+                if (text.highlightColors?.some((color) => typeof color !== 'string')) {
+                    issues.push(issue(mode, component, layer.id, {
+                        code: 'runtime-text-highlight-gradient-unsupported',
+                        capabilityId: `component.${component.type}.text.highlightColors.gradient`,
+                        path: `${componentPath}.appearance.text.highlightColors`,
+                        message: 'highlightColors currently cycles solid CSS colors only; gradient palette entries are not evaluated.'
+                    }));
+                }
+                const background = component.appearance.background;
+                if (background &&
+                    typeof background === 'object' &&
+                    'color' in background &&
+                    background.target === 'element' &&
+                    typeof background.color === 'object' &&
+                    typeof text.color === 'object') {
+                    issues.push(issue(mode, component, layer.id, {
+                        code: 'runtime-text-gradient-conflict',
+                        capabilityId: `component.${component.type}.text.compositing.elementGradientBackgroundWithGradientGlyph`,
+                        path: `${componentPath}.appearance`,
+                        message: 'Element-target gradient background and gradient glyph fill compete for CSS background-image. Use wrapper target.'
+                    }));
+                }
+            }
+        }
+    }
+    return { supported: issues.length === 0, issues };
+}

package/dist/agent/streamingEncoder.d.ts

@@ -0,0 +1,31 @@
+export type StreamEncoderFrameExtension = 'jpg' | 'png';
+export type PipeFrameEncoderOptions = {
+    fps: number;
+    inputExt: StreamEncoderFrameExtension;
+    outputPath: string;
+    crf?: number;
+    preset?: string;
+    debug?: boolean;
+};
+export declare function createFfmpegImagePipeArgs(options: PipeFrameEncoderOptions): string[];
+export declare function createMuxAudioArgs(input: {
+    videoPath: string;
+    audioPath: string;
+    outputPath: string;
+}): string[];
+export declare class PipeFrameEncoder {
+    #private;
+    constructor(options: PipeFrameEncoderOptions);
+    start(): void;
+    writeFrame(buffer: Buffer): Promise<void>;
+    finish(): Promise<{
+        elapsedMs: number;
+    }>;
+    abort(): void;
+}
+export declare function muxAudioWithVideo(input: {
+    videoPath: string;
+    audioPath: string;
+    outputPath: string;
+    debug?: boolean;
+}): Promise<void>;

package/dist/agent/streamingEncoder.js

@@ -0,0 +1,208 @@
+import { spawn } from 'node:child_process';
+export function createFfmpegImagePipeArgs(options) {
+    return [
+        '-y',
+        '-f',
+        'image2pipe',
+        '-framerate',
+        String(options.fps),
+        '-vcodec',
+        options.inputExt === 'png' ? 'png' : 'mjpeg',
+        '-i',
+        'pipe:0',
+        '-an',
+        '-c:v',
+        'libx264',
+        '-pix_fmt',
+        'yuv420p',
+        '-movflags',
+        '+faststart',
+        '-crf',
+        String(options.crf ?? 18),
+        '-preset',
+        options.preset ?? 'veryfast',
+        options.outputPath
+    ];
+}
+export function createMuxAudioArgs(input) {
+    return [
+        '-y',
+        '-i',
+        input.videoPath,
+        '-i',
+        input.audioPath,
+        '-map',
+        '0:v:0',
+        '-map',
+        '1:a:0?',
+        '-c:v',
+        'copy',
+        '-c:a',
+        'aac',
+        '-b:a',
+        '192k',
+        '-af',
+        'apad',
+        '-shortest',
+        '-movflags',
+        '+faststart',
+        input.outputPath
+    ];
+}
+export class PipeFrameEncoder {
+    #options;
+    #proc = null;
+    #exitPromise = null;
+    #stderrTail = '';
+    #startedAt = 0;
+    constructor(options) {
+        this.#options = options;
+    }
+    start() {
+        if (this.#proc)
+            return;
+        this.#startedAt = Date.now();
+        this.#proc = spawn(process.env.FFMPEG_PATH || 'ffmpeg', createFfmpegImagePipeArgs(this.#options), {
+            stdio: ['pipe', 'ignore', 'pipe']
+        });
+        this.#exitPromise = new Promise((resolve) => {
+            let settled = false;
+            const settle = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(result);
+            };
+            this.#proc?.once('error', (error) => {
+                settle({
+                    code: null,
+                    error: new Error(`PipeFrameEncoder failed to start ffmpeg: ${error.message}`)
+                });
+            });
+            this.#proc?.once('close', (code) => settle({ code }));
+        });
+        this.#proc.stderr?.on('data', (chunk) => {
+            const text = Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk);
+            if (this.#options.debug)
+                process.stderr.write(`[ffmpeg][visualfries-pipe] ${text}`);
+            this.#stderrTail = (this.#stderrTail + text).slice(-4000);
+        });
+    }
+    get #stdin() {
+        if (!this.#proc?.stdin) {
+            throw new Error('PipeFrameEncoder not started.');
+        }
+        return this.#proc.stdin;
+    }
+    async writeFrame(buffer) {
+        if (!this.#proc)
+            this.start();
+        let ok = false;
+        try {
+            ok = this.#stdin.write(buffer);
+        }
+        catch (error) {
+            const exitResult = await this.#exitPromise;
+            if (exitResult?.error)
+                throw exitResult.error;
+            throw error;
+        }
+        if (ok)
+            return;
+        const waitForDrain = new Promise((resolve, reject) => {
+            const cleanup = () => {
+                this.#stdin.off('drain', onDrain);
+                this.#stdin.off('error', onError);
+            };
+            const onDrain = () => {
+                cleanup();
+                resolve();
+            };
+            const onError = (error) => {
+                cleanup();
+                reject(error);
+            };
+            this.#stdin.on('drain', onDrain);
+            this.#stdin.on('error', onError);
+        });
+        const waitForExit = this.#exitPromise?.then((result) => {
+            if (result.error)
+                throw result.error;
+            if (result.code !== 0) {
+                throw new Error(`PipeFrameEncoder failed with exit code ${result.code}. ${this.#stderrTail}`);
+            }
+        });
+        await (waitForExit ? Promise.race([waitForDrain, waitForExit]) : waitForDrain);
+    }
+    async finish() {
+        if (!this.#proc)
+            return { elapsedMs: 0 };
+        const proc = this.#proc;
+        await new Promise((resolve, reject) => {
+            if (!proc.stdin || proc.stdin.destroyed) {
+                resolve();
+                return;
+            }
+            const onError = (error) => {
+                proc.stdin?.off('finish', onFinish);
+                reject(error);
+            };
+            const onFinish = () => {
+                proc.stdin?.off('error', onError);
+                resolve();
+            };
+            proc.stdin.once('error', onError);
+            proc.stdin.end(onFinish);
+        }).catch(async (error) => {
+            const exitResult = await this.#exitPromise;
+            if (exitResult?.error)
+                return;
+            throw error;
+        });
+        const result = await (this.#exitPromise ??
+            Promise.resolve({ code: null }));
+        this.#proc = null;
+        this.#exitPromise = null;
+        if (result.error) {
+            throw new Error(`${result.error.message}. ${this.#stderrTail}`.trim());
+        }
+        if (result.code !== 0) {
+            throw new Error(`PipeFrameEncoder failed with exit code ${result.code}. ${this.#stderrTail}`);
+        }
+        return { elapsedMs: Date.now() - this.#startedAt };
+    }
+    abort() {
+        if (!this.#proc)
+            return;
+        try {
+            this.#proc.kill('SIGKILL');
+        }
+        catch {
+            // Best effort cleanup.
+        }
+        this.#proc = null;
+    }
+}
+export async function muxAudioWithVideo(input) {
+    await new Promise((resolve, reject) => {
+        const proc = spawn(process.env.FFMPEG_PATH || 'ffmpeg', createMuxAudioArgs(input), {
+            stdio: ['ignore', 'ignore', 'pipe']
+        });
+        let stderrTail = '';
+        proc.stderr?.on('data', (chunk) => {
+            const text = Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk);
+            if (input.debug)
+                process.stderr.write(`[ffmpeg][visualfries-mux] ${text}`);
+            stderrTail = (stderrTail + text).slice(-4000);
+        });
+        proc.on('error', reject);
+        proc.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`Audio mux failed with exit code ${code}. ${stderrTail}`));
+            }
+        });
+    });
+}

package/dist/agent/transcripts.d.ts

@@ -0,0 +1,29 @@
+import type { Subtitle } from '../schemas/scene/subtitles.js';
+export type TranscriptWordInput = {
+    text?: string;
+    word?: string;
+    start?: number;
+    end?: number;
+    start_at?: number;
+    end_at?: number;
+};
+export type TranscriptSegmentInput = {
+    id?: string;
+    text?: string;
+    start?: number;
+    end?: number;
+    start_at?: number;
+    end_at?: number;
+    words?: TranscriptWordInput[];
+};
+export type TranscriptInput = TranscriptSegmentInput[] | {
+    language?: string;
+    language_code?: string;
+    subtitles?: TranscriptSegmentInput[];
+    segments?: TranscriptSegmentInput[];
+    words?: TranscriptWordInput[];
+};
+export type TranscriptTextFormat = 'srt' | 'vtt' | 'auto';
+export declare function normalizeTranscript(input: TranscriptInput): Subtitle[];
+export declare function inferTranscriptDuration(subtitles: Subtitle[]): number;
+export declare function parseSubtitleText(input: string, format?: TranscriptTextFormat): TranscriptInput;

package/dist/agent/transcripts.js

@@ -0,0 +1,146 @@
+function toNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim()) {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function normalizeWord(word) {
+    const text = String(word.text ?? word.word ?? '').trim();
+    const start = toNumber(word.start_at ?? word.start);
+    const end = toNumber(word.end_at ?? word.end);
+    if (!text || start === undefined || end === undefined)
+        return undefined;
+    return [text, start, Math.max(start, end)];
+}
+function segmentText(segment) {
+    const explicit = String(segment.text ?? '').trim();
+    if (explicit)
+        return explicit;
+    return (segment.words ?? [])
+        .map((word) => String(word.text ?? word.word ?? '').trim())
+        .filter(Boolean)
+        .join(' ');
+}
+function segmentTiming(segment) {
+    const start = toNumber(segment.start_at ?? segment.start);
+    const end = toNumber(segment.end_at ?? segment.end);
+    if (start !== undefined && end !== undefined) {
+        return { start, end: Math.max(start, end) };
+    }
+    const words = (segment.words ?? []).map(normalizeWord).filter(Boolean);
+    if (!words.length)
+        return undefined;
+    return {
+        start: words[0][1],
+        end: words[words.length - 1][2]
+    };
+}
+function wordsToSegments(words, maxWordsPerSegment = 7) {
+    const normalized = words.map(normalizeWord).filter(Boolean);
+    const segments = [];
+    for (let index = 0; index < normalized.length; index += maxWordsPerSegment) {
+        const chunk = normalized.slice(index, index + maxWordsPerSegment);
+        segments.push({
+            id: `subtitle-${segments.length + 1}`,
+            text: chunk.map((word) => word[0]).join(' '),
+            start_at: chunk[0][1],
+            end_at: chunk[chunk.length - 1][2],
+            words: chunk.map((word) => ({
+                text: word[0],
+                start_at: word[1],
+                end_at: word[2]
+            }))
+        });
+    }
+    return segments;
+}
+export function normalizeTranscript(input) {
+    const rawSegments = Array.isArray(input)
+        ? input
+        : input.subtitles && input.subtitles.length > 0
+            ? input.subtitles
+            : input.segments && input.segments.length > 0
+                ? input.segments
+                : input.words
+                    ? wordsToSegments(input.words)
+                    : [];
+    return rawSegments
+        .map((segment, index) => {
+        const timing = segmentTiming(segment);
+        const text = segmentText(segment);
+        if (!timing || !text)
+            return undefined;
+        const words = (segment.words ?? []).map(normalizeWord).filter(Boolean);
+        return {
+            id: segment.id ?? `subtitle-${index + 1}`,
+            start_at: timing.start,
+            end_at: timing.end,
+            text,
+            words: words.length ? words : undefined
+        };
+    })
+        .filter(Boolean);
+}
+export function inferTranscriptDuration(subtitles) {
+    return subtitles.reduce((duration, subtitle) => Math.max(duration, subtitle.end_at), 0);
+}
+function parseTimestamp(value) {
+    const normalized = value.trim().replace(',', '.');
+    const parts = normalized.split(':');
+    if (parts.length < 2 || parts.length > 3)
+        return undefined;
+    const seconds = Number(parts.at(-1));
+    const minutes = Number(parts.at(-2));
+    const hours = parts.length === 3 ? Number(parts[0]) : 0;
+    if (![seconds, minutes, hours].every(Number.isFinite))
+        return undefined;
+    return hours * 3600 + minutes * 60 + seconds;
+}
+function stripVttCueSetting(value) {
+    return value.trim().split(/\s+/, 1)[0] ?? value.trim();
+}
+function parseCueBlock(block, index) {
+    const lines = block
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (!lines.length)
+        return undefined;
+    const timingIndex = lines.findIndex((line) => line.includes('-->'));
+    if (timingIndex === -1)
+        return undefined;
+    const [rawStart, rawEnd] = lines[timingIndex].split('-->', 2);
+    const start = parseTimestamp(rawStart ?? '');
+    const end = parseTimestamp(stripVttCueSetting(rawEnd ?? ''));
+    if (start === undefined || end === undefined)
+        return undefined;
+    const text = lines
+        .slice(timingIndex + 1)
+        .join(' ')
+        .replace(/<[^>]+>/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!text)
+        return undefined;
+    return {
+        id: `subtitle-${index + 1}`,
+        text,
+        start_at: start,
+        end_at: Math.max(start, end)
+    };
+}
+export function parseSubtitleText(input, format = 'auto') {
+    const text = input.replace(/^\uFEFF/, '').trim();
+    const withoutHeader = format === 'vtt' || (format === 'auto' && /^WEBVTT(?:\s|$)/i.test(text))
+        ? text
+            .replace(/^WEBVTT[^\n\r]*(?:\r?\n)+/i, '')
+            .replace(/^(NOTE|STYLE|REGION)[\s\S]*?(?:\r?\n){2}/gim, '')
+        : text;
+    return withoutHeader
+        .split(/\r?\n\s*\r?\n/)
+        .map(parseCueBlock)
+        .filter(Boolean);
+}

package/dist/agent/transitions.d.ts

@@ -0,0 +1,20 @@
+import { type ComponentInput, type Scene, type SceneInput } from '../schemas/scene/index.js';
+export type AgentTransitionStyle = 'dip-to-black' | 'flash' | 'swipe-left' | 'swipe-up' | 'focus-pull';
+export type AgentTransitionCue = {
+    id?: string;
+    time: number;
+    duration?: number;
+    style?: AgentTransitionStyle;
+    color?: string;
+    layerOrder?: number;
+    animated?: boolean;
+};
+export type AddAgentTransitionsInput = {
+    scene: Scene | SceneInput;
+    transitions: AgentTransitionCue[];
+    layerId?: string;
+    layerName?: string;
+    layerOrder?: number;
+};
+export declare function createAgentTransitionComponent(cue: AgentTransitionCue, scene: Scene | SceneInput, index?: number): ComponentInput;
+export declare function addAgentTransitions(input: AddAgentTransitionsInput): Scene;