visualfries 0.1.10120 → 0.3.2

package/dist/agent/capabilities.js

@@ -0,0 +1,246 @@
+export const VISUAL_COMPONENT_TYPES = [
+    'TEXT',
+    'SUBTITLES',
+    'IMAGE',
+    'VIDEO',
+    'GIF',
+    'SHAPE',
+    'COLOR',
+    'GRADIENT'
+];
+export const COMPONENT_TYPES = [...VISUAL_COMPONENT_TYPES, 'AUDIO'];
+const VISUAL_TRANSFORMS = [
+    'x',
+    'y',
+    'opacity',
+    'rotation',
+    'scale',
+    'scaleX',
+    'scaleY'
+];
+const GENERIC_VALIDATION_ONLY_EFFECTS = ['blur', 'colorAdjustment', 'rotationRandomizer'];
+export const COMPONENT_CAPABILITIES = {
+    TEXT: {
+        type: 'TEXT',
+        visual: true,
+        renderers: {
+            preview: 'html',
+            final: 'pixi',
+            parity: 'different-representation'
+        },
+        animation: {
+            attached: true,
+            target: 'html-element-or-wrapper',
+            transforms: [...VISUAL_TRANSFORMS],
+            selectors: ['container', 'words', 'lines', 'chars', 'css'],
+            coordinateSpace: 'css-transform',
+            transformOrigin: 'css-center-fixed',
+            seekDeterministic: true
+        },
+        effects: {
+            supported: ['textShadow', 'textOutline'],
+            validationOnly: [...GENERIC_VALIDATION_ONLY_EFFECTS]
+        },
+        backgrounds: ['solid-wrapper', 'gradient-wrapper', 'solid-element', 'gradient-element'],
+        textFeatures: [
+            'font',
+            'solid-color',
+            'gradient-color',
+            'alignment',
+            'transform',
+            'outline-solid',
+            'shadow',
+            'active-word-color-background',
+            'active-line-color-background',
+            'active-word-line-scale',
+            'solid-highlight-color-cycling',
+            'px-padding',
+            'split-words-lines-chars'
+        ],
+        caveats: [
+            'Preview uses HTML while final output rasterizes HTML into Pixi.',
+            'Element background padding defaults to 0.22em only when explicit padding is absent.',
+            'clipColor is not implemented; highlight color cycling supports solid colors only.'
+        ]
+    },
+    SUBTITLES: {
+        type: 'SUBTITLES',
+        visual: true,
+        renderers: { preview: 'html', final: 'pixi', parity: 'different-representation' },
+        animation: {
+            attached: true,
+            target: 'html-element-or-wrapper',
+            transforms: [...VISUAL_TRANSFORMS],
+            selectors: ['container', 'words', 'lines', 'chars', 'css'],
+            coordinateSpace: 'css-transform',
+            transformOrigin: 'css-center-fixed',
+            seekDeterministic: true
+        },
+        effects: {
+            supported: ['textShadow', 'textOutline'],
+            validationOnly: [...GENERIC_VALIDATION_ONLY_EFFECTS]
+        },
+        backgrounds: ['solid-wrapper', 'gradient-wrapper', 'solid-element', 'gradient-element'],
+        textFeatures: [
+            'font',
+            'solid-color',
+            'gradient-color',
+            'active-word-color-background',
+            'active-line-color-background',
+            'active-word-line-scale',
+            'solid-highlight-color-cycling',
+            'px-padding',
+            'timed-words'
+        ],
+        caveats: ['Advanced out anchors depend on cue/component duration and require frame QA.']
+    },
+    IMAGE: {
+        type: 'IMAGE',
+        visual: true,
+        renderers: { preview: 'pixi', final: 'pixi', parity: 'same-representation' },
+        animation: {
+            attached: true,
+            target: 'pixi-container',
+            transforms: [...VISUAL_TRANSFORMS],
+            selectors: ['container'],
+            coordinateSpace: 'component-relative-offset',
+            transformOrigin: 'component-center-fixed',
+            seekDeterministic: true
+        },
+        effects: {
+            supported: ['layoutSplit', 'fillBackgroundBlur'],
+            validationOnly: [...GENERIC_VALIDATION_ONLY_EFFECTS]
+        },
+        backgrounds: [],
+        textFeatures: [],
+        caveats: ['source.url is required by the image runtime even when assetId is present.']
+    },
+    VIDEO: {
+        type: 'VIDEO',
+        visual: true,
+        renderers: {
+            preview: 'native-media',
+            final: 'deterministic-media-pixi',
+            parity: 'media-predecoded'
+        },
+        animation: {
+            attached: true,
+            target: 'pixi-container',
+            transforms: [...VISUAL_TRANSFORMS],
+            selectors: ['container'],
+            coordinateSpace: 'component-relative-offset',
+            transformOrigin: 'component-center-fixed',
+            seekDeterministic: true
+        },
+        effects: {
+            supported: ['layoutSplit', 'fillBackgroundBlur'],
+            validationOnly: [...GENERIC_VALIDATION_ONLY_EFFECTS]
+        },
+        backgrounds: [],
+        textFeatures: [],
+        caveats: ['Final media frames are predecoded; browser media is preview-only.']
+    },
+    GIF: {
+        type: 'GIF',
+        visual: true,
+        renderers: {
+            preview: 'native-media',
+            final: 'deterministic-media-pixi',
+            parity: 'media-predecoded'
+        },
+        animation: {
+            attached: true,
+            target: 'pixi-container',
+            transforms: [...VISUAL_TRANSFORMS],
+            selectors: ['container'],
+            coordinateSpace: 'component-relative-offset',
+            transformOrigin: 'component-center-fixed',
+            seekDeterministic: true
+        },
+        effects: { supported: [], validationOnly: [...GENERIC_VALIDATION_ONLY_EFFECTS] },
+        backgrounds: [],
+        textFeatures: [],
+        caveats: ['Final GIF frames are predecoded; browser GIF playback is preview-only.']
+    },
+    SHAPE: {
+        type: 'SHAPE',
+        visual: true,
+        renderers: { preview: 'pixi', final: 'pixi', parity: 'same-representation' },
+        animation: {
+            attached: true,
+            target: 'pixi-container',
+            transforms: [...VISUAL_TRANSFORMS],
+            selectors: ['container'],
+            coordinateSpace: 'component-relative-offset',
+            transformOrigin: 'component-center-fixed',
+            seekDeterministic: true
+        },
+        effects: { supported: [], validationOnly: [...GENERIC_VALIDATION_ONLY_EFFECTS] },
+        backgrounds: ['solid-fill'],
+        textFeatures: [],
+        caveats: ['Rectangle cornerRadius and gradient fill are not production-proven.']
+    },
+    COLOR: {
+        type: 'COLOR',
+        visual: true,
+        renderers: { preview: 'pixi', final: 'pixi', parity: 'same-representation' },
+        animation: {
+            attached: true,
+            target: 'pixi-container',
+            transforms: [...VISUAL_TRANSFORMS],
+            selectors: ['container'],
+            coordinateSpace: 'component-relative-offset',
+            transformOrigin: 'component-center-fixed',
+            seekDeterministic: true
+        },
+        effects: { supported: [], validationOnly: [...GENERIC_VALIDATION_ONLY_EFFECTS] },
+        backgrounds: ['solid-canvas-fill'],
+        textFeatures: [],
+        caveats: []
+    },
+    GRADIENT: {
+        type: 'GRADIENT',
+        visual: true,
+        renderers: { preview: 'pixi', final: 'pixi', parity: 'same-representation' },
+        animation: {
+            attached: true,
+            target: 'pixi-container',
+            transforms: [...VISUAL_TRANSFORMS],
+            selectors: ['container'],
+            coordinateSpace: 'component-relative-offset',
+            transformOrigin: 'component-center-fixed',
+            seekDeterministic: true
+        },
+        effects: { supported: [], validationOnly: [...GENERIC_VALIDATION_ONLY_EFFECTS] },
+        backgrounds: ['linear-canvas-gradient', 'radial-canvas-gradient'],
+        textFeatures: [],
+        caveats: ['Radial shape/position fields currently use a centered max-radius fallback.']
+    },
+    AUDIO: {
+        type: 'AUDIO',
+        visual: false,
+        renderers: { preview: 'none', final: 'audio-mix', parity: 'not-applicable' },
+        animation: {
+            attached: false,
+            target: 'none',
+            transforms: [],
+            selectors: [],
+            coordinateSpace: 'none',
+            transformOrigin: 'none',
+            seekDeterministic: false
+        },
+        effects: { supported: [], validationOnly: [] },
+        backgrounds: [],
+        textFeatures: [],
+        caveats: ['AUDIO has no visual animation contract.']
+    }
+};
+export function getComponentCapability(type) {
+    return COMPONENT_CAPABILITIES[type];
+}
+export function getCapabilityCatalog() {
+    return COMPONENT_TYPES.map((type) => COMPONENT_CAPABILITIES[type]);
+}
+export function componentSupportsRuntimeAnimation(type) {
+    return getComponentCapability(type)?.animation.attached === true;
+}

package/dist/agent/captionScene.d.ts

@@ -0,0 +1,23 @@
+import { type Scene } from '../schemas/scene/index.js';
+import { type TranscriptInput } from './transcripts.js';
+export type CaptionScenePreset = 'reels-center' | 'reels-lower' | 'podcast-clean' | 'hidden-engine-center';
+export type CaptionSceneInput = {
+    id?: string;
+    video: {
+        url: string;
+        assetId?: string;
+        width?: number;
+        height?: number;
+        duration?: number;
+        hasAudio?: boolean;
+    };
+    transcript: TranscriptInput;
+    preset?: CaptionScenePreset;
+    language?: string;
+    width?: number;
+    height?: number;
+    fps?: number;
+    duration?: number;
+    backgroundColor?: string;
+};
+export declare function createCaptionScene(input: CaptionSceneInput): Scene;

package/dist/agent/captionScene.js

@@ -0,0 +1,204 @@
+import { SceneShape } from '../schemas/scene/index.js';
+import { inferTranscriptDuration, normalizeTranscript } from './transcripts.js';
+function captionPreset(preset, width, height) {
+    const safeWidth = Math.round(width * 0.86);
+    const x = Math.round((width - safeWidth) / 2);
+    if (preset === 'reels-lower') {
+        return {
+            x,
+            y: Math.round(height * 0.68),
+            width: safeWidth,
+            height: Math.round(height * 0.18),
+            fontSize: Math.round(width * 0.065),
+            fontFamily: 'Montserrat',
+            fontWeight: '900',
+            color: '#FFFFFF',
+            activeColor: '#FFDD55',
+            activeBackgroundColor: '#083F36',
+            backgroundColor: 'rgba(0, 0, 0, 0.42)',
+            backgroundAlwaysVisible: false,
+            textTransform: 'uppercase',
+            shadowBlur: 12
+        };
+    }
+    if (preset === 'podcast-clean') {
+        return {
+            x,
+            y: Math.round(height * 0.7),
+            width: safeWidth,
+            height: Math.round(height * 0.16),
+            fontSize: Math.round(width * 0.054),
+            fontFamily: 'Inter',
+            fontWeight: '800',
+            color: '#FFFFFF',
+            activeColor: '#FFFFFF',
+            activeBackgroundColor: '#0D5C4A',
+            backgroundColor: 'rgba(0, 0, 0, 0.34)',
+            backgroundAlwaysVisible: false,
+            textTransform: 'none',
+            shadowBlur: 8
+        };
+    }
+    if (preset === 'hidden-engine-center') {
+        return {
+            x,
+            y: Math.round(height * 0.44),
+            width: safeWidth,
+            height: Math.round(height * 0.2),
+            fontSize: Math.round(width * 0.066),
+            fontFamily: 'Montserrat',
+            fontWeight: '900',
+            color: '#F7F7F2',
+            activeColor: '#FFDF5A',
+            activeBackgroundColor: '#06483D',
+            backgroundColor: 'rgba(0, 0, 0, 0.28)',
+            backgroundAlwaysVisible: false,
+            textTransform: 'uppercase',
+            shadowBlur: 10
+        };
+    }
+    return {
+        x,
+        y: Math.round(height * 0.48),
+        width: safeWidth,
+        height: Math.round(height * 0.2),
+        fontSize: Math.round(width * 0.064),
+        fontFamily: 'Montserrat',
+        fontWeight: '900',
+        color: '#FFFFFF',
+        activeColor: '#FFD84D',
+        activeBackgroundColor: '#054D42',
+        backgroundColor: 'rgba(0, 0, 0, 0.3)',
+        backgroundAlwaysVisible: false,
+        textTransform: 'uppercase',
+        shadowBlur: 10
+    };
+}
+export function createCaptionScene(input) {
+    const width = input.width ?? 1080;
+    const height = input.height ?? 1920;
+    const fps = input.fps ?? 30;
+    const language = input.language ?? 'en';
+    const assetId = input.video.assetId ?? 'main-video';
+    const subtitles = normalizeTranscript(input.transcript);
+    const duration = input.duration ?? input.video.duration ?? inferTranscriptDuration(subtitles);
+    const sceneDuration = Math.max(0.1, duration);
+    const videoUrl = input.video.url;
+    const preset = captionPreset(input.preset ?? 'reels-center', width, height);
+    const videoAsset = {
+        id: assetId,
+        type: 'VIDEO',
+        url: videoUrl,
+        metadata: {
+            width: input.video.width ?? width,
+            height: input.video.height ?? height,
+            duration: sceneDuration,
+            hasAudio: input.video.hasAudio ?? true
+        }
+    };
+    const video = {
+        id: 'video-main',
+        type: 'VIDEO',
+        name: 'Main video',
+        timeline: { startAt: 0, endAt: sceneDuration },
+        source: { url: videoUrl, assetId, metadata: videoAsset.metadata },
+        appearance: { x: 0, y: 0, width, height },
+        volume: 1,
+        muted: false,
+        playback: { autoplay: true, loop: false, playbackRate: 1 },
+        crop: { x: 0, y: 0, width: 1, height: 1 },
+        order: 0
+    };
+    const captions = {
+        id: 'subtitles-main',
+        type: 'SUBTITLES',
+        name: 'Captions',
+        timeline: { startAt: 0, endAt: sceneDuration },
+        source: { assetId, languageCode: language },
+        timingAnchor: {
+            mode: 'ASSET_USAGE',
+            assetId,
+            offset: 0
+        },
+        appearance: {
+            x: preset.x,
+            y: preset.y,
+            width: preset.width,
+            height: preset.height,
+            horizontalAlign: 'center',
+            verticalAlign: 'center',
+            ...(preset.backgroundColor
+                ? {
+                    background: {
+                        enabled: true,
+                        color: preset.backgroundColor,
+                        target: 'wrapper',
+                        radius: 18
+                    }
+                }
+                : {}),
+            backgroundAlwaysVisible: preset.backgroundAlwaysVisible,
+            text: {
+                fontFamily: preset.fontFamily,
+                fontSize: { value: preset.fontSize, unit: 'px' },
+                fontWeight: preset.fontWeight,
+                color: preset.color,
+                textAlign: 'center',
+                textTransform: preset.textTransform,
+                lineHeight: { value: 1.05, unit: 'em' },
+                shadow: {
+                    enabled: true,
+                    color: '#000000',
+                    blur: preset.shadowBlur,
+                    offsetX: 0,
+                    offsetY: 3
+                },
+                activeWord: {
+                    enabled: true,
+                    color: preset.activeColor,
+                    backgroundColor: preset.activeBackgroundColor,
+                    scale: 1.08,
+                    backgroundPaddingX: 14,
+                    backgroundPaddingY: 6,
+                    backgroundBorderRadius: 10
+                }
+            }
+        },
+        order: 10
+    };
+    const mediaLayer = {
+        id: 'layer-media',
+        name: 'Media',
+        order: 0,
+        components: [video]
+    };
+    const captionLayer = {
+        id: 'layer-captions',
+        name: 'Captions',
+        order: 10,
+        components: [captions]
+    };
+    const scene = {
+        id: input.id ?? 'visualfries-caption-scene',
+        name: 'Agent Caption Scene',
+        settings: {
+            width,
+            height,
+            duration: sceneDuration,
+            fps,
+            backgroundColor: input.backgroundColor ?? '#000000',
+            subtitles: {
+                punctuation: true,
+                mergeGap: 0.2,
+                data: {
+                    [assetId]: {
+                        [language]: subtitles
+                    }
+                }
+            }
+        },
+        assets: [videoAsset],
+        layers: [mediaLayer, captionLayer]
+    };
+    return SceneShape.parse(scene);
+}

package/dist/agent/catalog.d.ts

@@ -0,0 +1,24 @@
+import { type CapabilityComponentType } from './capabilities.js';
+export declare const AGENT_CAPTION_PRESETS: readonly ["reels-center", "reels-lower", "podcast-clean", "hidden-engine-center"];
+export declare const AGENT_CUE_PRESETS: readonly ["hidden-engine-dynamic", "captioned-clean"];
+export declare const AGENT_OVERLAY_STYLES: readonly ["pop-label", "shock-word", "soft-card", "hook-punch", "proof-pill", "danger-crossout", "metric-badge", "cta-card"];
+export declare const AGENT_BROLL_MOTIONS: readonly ["none", "slow-zoom-in", "slow-zoom-out", "drift-up"];
+export declare const AGENT_TRANSITION_STYLES: readonly ["dip-to-black", "flash", "swipe-left", "swipe-up"];
+export declare const AGENT_TRANSCRIPT_FORMATS: readonly ["json", "srt", "vtt"];
+export declare const AGENT_CLI_COMMANDS: readonly ["doctor", "catalog", "validate", "init", "caption-scene", "preset-cues", "apply-cues", "validate-cues", "qa", "inspect", "explain", "parity", "render", "compose", "produce"];
+export declare function getAgentCatalog(options?: {
+    component?: CapabilityComponentType;
+}): {
+    captionPresets: ("reels-center" | "reels-lower" | "podcast-clean" | "hidden-engine-center")[];
+    cuePresets: ("hidden-engine-dynamic" | "captioned-clean")[];
+    overlayStyles: ("pop-label" | "shock-word" | "soft-card" | "hook-punch" | "proof-pill" | "danger-crossout" | "metric-badge" | "cta-card")[];
+    brollMotions: ("none" | "slow-zoom-in" | "slow-zoom-out" | "drift-up")[];
+    transitionStyles: ("dip-to-black" | "flash" | "swipe-left" | "swipe-up")[];
+    transcriptFormats: ("srt" | "vtt" | "json")[];
+    cliCommands: ("render" | "doctor" | "catalog" | "validate" | "init" | "caption-scene" | "preset-cues" | "apply-cues" | "validate-cues" | "qa" | "inspect" | "explain" | "parity" | "compose" | "produce")[];
+    capabilities: import("./capabilities.js").ComponentCapability[];
+    recommendedWorkflow: {
+        routine: string;
+        debug: string[];
+    };
+};

package/dist/agent/catalog.js

@@ -0,0 +1,67 @@
+import { getCapabilityCatalog, getComponentCapability } from './capabilities.js';
+export const AGENT_CAPTION_PRESETS = [
+    'reels-center',
+    'reels-lower',
+    'podcast-clean',
+    'hidden-engine-center'
+];
+export const AGENT_CUE_PRESETS = ['hidden-engine-dynamic', 'captioned-clean'];
+export const AGENT_OVERLAY_STYLES = [
+    'pop-label',
+    'shock-word',
+    'soft-card',
+    'hook-punch',
+    'proof-pill',
+    'danger-crossout',
+    'metric-badge',
+    'cta-card'
+];
+export const AGENT_BROLL_MOTIONS = ['none', 'slow-zoom-in', 'slow-zoom-out', 'drift-up'];
+export const AGENT_TRANSITION_STYLES = ['dip-to-black', 'flash', 'swipe-left', 'swipe-up'];
+export const AGENT_TRANSCRIPT_FORMATS = ['json', 'srt', 'vtt'];
+export const AGENT_CLI_COMMANDS = [
+    'doctor',
+    'catalog',
+    'validate',
+    'init',
+    'caption-scene',
+    'preset-cues',
+    'apply-cues',
+    'validate-cues',
+    'qa',
+    'inspect',
+    'explain',
+    'parity',
+    'render',
+    'compose',
+    'produce'
+];
+export function getAgentCatalog(options = {}) {
+    const componentCapability = options.component
+        ? getComponentCapability(options.component)
+        : undefined;
+    if (options.component && !componentCapability) {
+        throw new Error(`Unknown VisualFries component type: ${options.component}`);
+    }
+    return {
+        captionPresets: [...AGENT_CAPTION_PRESETS],
+        cuePresets: [...AGENT_CUE_PRESETS],
+        overlayStyles: [...AGENT_OVERLAY_STYLES],
+        brollMotions: [...AGENT_BROLL_MOTIONS],
+        transitionStyles: [...AGENT_TRANSITION_STYLES],
+        transcriptFormats: [...AGENT_TRANSCRIPT_FORMATS],
+        cliCommands: [...AGENT_CLI_COMMANDS],
+        capabilities: componentCapability ? [componentCapability] : getCapabilityCatalog(),
+        recommendedWorkflow: {
+            routine: 'visualfries compose --video ./input.mp4 --transcript ./captions.srt --cue-preset hidden-engine-dynamic --cues ./cues.json --scene-output ./scene.json --qa-output ./qa/frames --render-mode preview --output ./preview.mp4',
+            debug: [
+                'visualfries doctor --json',
+                'visualfries caption-scene --video ./input.mp4 --transcript ./captions.srt --preset hidden-engine-center --output ./scene.json',
+                'visualfries preset-cues --duration 45 --preset hidden-engine-dynamic --output ./cues.json',
+                'visualfries apply-cues ./scene.json --cues ./cues.json --output ./scene.with-cues.json',
+                'visualfries inspect ./scene.with-cues.json --screenshots --samples 3 --output ./qa/frames --json',
+                'visualfries render ./scene.with-cues.json --render-mode preview --output ./preview.mp4'
+            ]
+        }
+    };
+}

package/dist/agent/cueFiles.d.ts

@@ -0,0 +1,54 @@
+import { type AgentBrollCue } from './broll.js';
+import { type AgentTextOverlayCue } from './overlays.js';
+import { type AgentTransitionCue } from './transitions.js';
+import { type Scene, type SceneInput } from '../schemas/scene/index.js';
+export type AgentCueFile = {
+    broll?: AgentBrollCue[];
+    overlays?: AgentTextOverlayCue[];
+    transitions?: AgentTransitionCue[];
+    brollLayerId?: string;
+    brollLayerName?: string;
+    brollLayerOrder?: number;
+    overlayLayerId?: string;
+    overlayLayerName?: string;
+    overlayLayerOrder?: number;
+    transitionLayerId?: string;
+    transitionLayerName?: string;
+    transitionLayerOrder?: number;
+};
+export type ApplyAgentCueFileInput = {
+    scene: Scene | SceneInput;
+    cues: AgentCueFile;
+    cueFilePath?: string;
+};
+export type ApplyAgentCueFileResult = {
+    scene: Scene;
+    applied: {
+        broll: number;
+        overlays: number;
+        transitions: number;
+    };
+};
+export type AgentCueValidationIssue = {
+    level: 'error' | 'warning';
+    path: string;
+    message: string;
+};
+export type ValidateAgentCueFileInput = {
+    cues: AgentCueFile;
+    duration?: number;
+    cueFilePath?: string;
+};
+export type AgentCueValidationReport = {
+    valid: boolean;
+    issues: AgentCueValidationIssue[];
+    summary: {
+        broll: number;
+        overlays: number;
+        transitions: number;
+    };
+};
+export declare function mergeAgentCueFiles(...cueFiles: AgentCueFile[]): AgentCueFile;
+export declare function normalizeAgentCueFile(cues: AgentCueFile, cueFilePath?: string): AgentCueFile;
+export declare function validateAgentCueFile(input: ValidateAgentCueFileInput): AgentCueValidationReport;
+export declare function applyAgentCueFile(input: ApplyAgentCueFileInput): ApplyAgentCueFileResult;