motionrender 0.2.0 → 0.2.2

package/dist/types/packages/ai/src/agent.d.ts

@@ -0,0 +1,57 @@
+import type { AiProvider } from './providers.js';
+export type VideoFormat = 'reel' | 'landscape';
+export type BrandColor = {
+    primary: string;
+    secondary?: string;
+    accent?: string;
+    background?: string;
+    text?: string;
+};
+export type BrandFont = {
+    heading?: string;
+    body?: string;
+};
+export type BrandPack = {
+    colors?: BrandColor;
+    fonts?: BrandFont;
+    logo?: string;
+    name?: string;
+    style?: string;
+};
+export type AgentOptions = {
+    brief?: string;
+    url?: string;
+    dir?: string;
+    format?: VideoFormat;
+    durationSeconds?: number;
+    fps?: number;
+    render?: boolean;
+    outputMp4?: string;
+    onProgress?: (message: string) => void;
+    signal?: AbortSignal;
+    brand?: BrandPack;
+    visualCheck?: (videoPath: string, compositionPath: string) => Promise<{
+        passed: boolean;
+        report: string;
+        sheet?: Buffer;
+    }>;
+};
+export type AgentResult = {
+    dir: string;
+    videoPath: string;
+    compositionPath: string;
+    bundlePath: string;
+    mp4Path?: string;
+    previewPath?: string;
+    attempts: number;
+    code: string;
+};
+/**
+ * Returns true when the brief hints at a vertical reel format.
+ * Checks for social/vertical keywords case-insensitively.
+ */
+export declare function detectReelFormat(brief: string): boolean;
+/**
+ * Autonomous Video Agent that plans, codes, builds, and self-corrects React videos.
+ */
+export declare function runVideoAgent(provider: AiProvider, options: AgentOptions, buildHelper?: (source: string, output: string) => Promise<void>): Promise<AgentResult>;

package/dist/types/packages/ai/src/brand-scraper.d.ts

@@ -0,0 +1,35 @@
+import type { BrandPack } from './agent.js';
+import type { AiProvider } from './providers.js';
+export type ScrapedWebsite = {
+    url: string;
+    title?: string;
+    description?: string;
+    siteName?: string;
+    logo?: string;
+    themeColor?: string;
+    colors: string[];
+    headings: string[];
+    paragraphs: string[];
+    suggestedBrief?: string;
+};
+/**
+ * Normalizes a URL so that 'linear.app' becomes 'https://linear.app'.
+ */
+export declare function normalizeUrl(input: string): string;
+/**
+ * Fast, lightweight regex-based HTML metadata & brand asset extractor.
+ * Doesn't require heavy DOM dependencies; works seamlessly in Node 20+.
+ */
+export declare function parseWebsiteHtml(html: string, baseUrl: string): ScrapedWebsite;
+/**
+ * Fetches the website HTML and extracts brand assets, colors, and value proposition.
+ */
+export declare function scrapeWebsiteBrand(urlInput: string, timeoutMs?: number): Promise<ScrapedWebsite>;
+/**
+ * Distills raw scraped website metadata into a structured BrandPack using the AI provider,
+ * with a deterministic fallback if the AI request fails or provider is absent.
+ */
+export declare function distillBrandPack(scraped: ScrapedWebsite, provider?: AiProvider): Promise<{
+    brand: BrandPack;
+    suggestedBrief: string;
+}>;

package/dist/types/packages/ai/src/captions.d.ts

@@ -0,0 +1,11 @@
+export declare function captionsStyle(width: number, height: number): {
+    x: number;
+    y: number;
+    textAlign: "center";
+    maxWidth: number;
+    fontSize: number;
+    fontWeight: 700;
+    background: string;
+    padding: number;
+    radius: number;
+};

package/dist/types/packages/ai/src/compose.d.ts

@@ -6,6 +6,8 @@ export type ComposeOptions = PromptOptions & {
     maxAttempts?: number;
     /** Run `ove review`-style checks between attempts and feed design errors back. Slow; off by default. */
     review?: boolean;
+    /** Plan beats and look first (Claude-style motion graphics), then write the composition. */
+    plan?: boolean;
     baseDir?: string;
     signal?: AbortSignal;
     onProgress?: (message: string) => void;

package/dist/types/packages/ai/src/edit.d.ts

@@ -0,0 +1,69 @@
+import type { Composition } from '../../core/src/index.js';
+import type { AiProvider, Transcript, TranscriptWord } from './providers.js';
+export type CutSegment = {
+    from: number;
+    to: number;
+};
+export type CutPlan = {
+    /** The kept stretches of the source, in seconds, in order. */
+    segments: CutSegment[];
+    /** The kept words with their times remapped onto the edited timeline (what the captions show). */
+    words: TranscriptWord[];
+    /** Seconds removed between the first and last kept word. */
+    cut: number;
+    /** Filler and repeated words cut (um, uh, "the the"). */
+    fillers: number;
+};
+export type PlanCutsOptions = {
+    /** A pause longer than this, in seconds, is cut (default 0.5). */
+    maxSilence?: number;
+    /** Keep filler words in the video instead of cutting them. */
+    keepFillers?: boolean;
+    /** Breathing room kept before the first and after the last word, in seconds (default 0.3). */
+    padding?: number;
+};
+/** Turns word timings into a cut list: speech runs join across pauses up to maxSilence, longer pauses become cuts. */
+export declare function planCuts(transcript: Transcript, options?: PlanCutsOptions): CutPlan;
+export type EditCompositionOptions = {
+    fps: number;
+    width: number;
+    height: number;
+    /** The clip, as an asset id or a path relative to the composition. */
+    src: string;
+    plan: CutPlan;
+    /** Composition-relative path to a captions file (word timings); left out, the reel has no captions. */
+    captionsSrc?: string;
+};
+/** Builds the edited composition: one video layer per kept stretch (hard jump cuts between them), captions over all of it. */
+export declare function editComposition(options: EditCompositionOptions): Composition;
+export type EditOptions = {
+    /** Path to the raw clip (any file FFmpeg reads). */
+    clip: string;
+    /** Project directory to write: composition.json, composition.schema.json, assets/. */
+    outDir: string;
+    width?: number;
+    height?: number;
+    fps?: number;
+    maxSilence?: number;
+    keepFillers?: boolean;
+    padding?: number;
+    captions?: boolean;
+    language?: string;
+    /** Write into a directory that already has files. */
+    force?: boolean;
+    signal?: AbortSignal;
+    onProgress?: (message: string) => void;
+};
+export type EditResult = {
+    dir: string;
+    composition: string;
+    captions?: string;
+    durationSeconds: number;
+    sourceSeconds: number;
+    segments: number;
+    cut: number;
+    fillers: number;
+    words: number;
+};
+/** Transcribes a raw clip, cuts its fillers and silences, and writes the edited reel as a project. */
+export declare function editVideo(provider: AiProvider, options: EditOptions): Promise<EditResult>;

package/dist/types/packages/ai/src/index.d.ts

@@ -6,8 +6,15 @@ export * from './template.js';
 export { applyFixes, isFixReply, type Fix } from './patch.js';
 export * from './narrate.js';
 export * from './voiceover.js';
+export * from './edit.js';
+export * from './shorts.js';
+export * from './retime.js';
 export * from './image.js';
 export * from './batch.js';
 export * from './project.js';
+export * from './agent.js';
+export * from './brand-scraper.js';
+export * from './registry.js';
+export * from './plan.js';
 export { extractJson, sanitizeCompositionJson } from './json.js';
-export { systemPrompt, userPrompt, refineUserPrompt, refineOutlinePrompt, compositionOutline, refineOutlineChars, ratioName, type PromptOptions } from './prompt.js';
+export { systemPrompt, userPrompt, planSystemPrompt, planUserPrompt, isMotionPlan, refineUserPrompt, refineOutlinePrompt, compositionOutline, refineOutlineChars, ratioName, type PromptOptions, type MotionPlan, type MotionBeat } from './prompt.js';

package/dist/types/packages/ai/src/plan.d.ts

@@ -0,0 +1,42 @@
+import type { AiProvider } from './providers.js';
+import type { MotionBeat } from './prompt.js';
+import { type GenerationPath, type Registry } from './registry.js';
+export type BuildPlan = {
+    path: GenerationPath;
+    template?: string;
+    theme?: string;
+    idea?: string;
+    beats: MotionBeat[];
+    reasons: string[];
+};
+export type PlanOptions = {
+    brief: string;
+    width: number;
+    height: number;
+    fps: number;
+    durationSeconds: number;
+    kind?: string;
+    registry: Registry;
+    /** Which routes the caller will actually act on (default: all; react additionally needs allowReact). */
+    paths?: GenerationPath[];
+    /** Full JSON compositions and React code can use sounds and clips; templates cannot. */
+    assets?: {
+        id: string;
+        type: string;
+        src: string;
+    }[];
+    allowReact?: boolean;
+    maxAttempts?: number;
+    signal?: AbortSignal;
+    onProgress?: (message: string) => void;
+};
+/** Parses and validates one reply against the registry. Returns the plan, or the problems to send back to the model. */
+export declare function readBuildPlan(reply: unknown, options: PlanOptions): {
+    plan?: BuildPlan;
+    problems: string[];
+};
+/**
+ * Plans the video. Returns a validated plan, or undefined when the planner cannot be trusted (no reply within the attempt
+ * budget or non-plan-shaped output), so callers fall back to the routing that always worked.
+ */
+export declare function planBuild(provider: AiProvider, options: PlanOptions): Promise<BuildPlan | undefined>;

package/dist/types/packages/ai/src/prompt.d.ts

@@ -17,8 +17,26 @@ export type PromptOptions = {
     }[];
     includeSchema?: boolean;
     narration?: boolean;
+    /** Beats and look from the planning pass; the composition must follow them. */
+    motionPlan?: MotionPlan;
 };
+export type MotionBeat = {
+    name: string;
+    takeaway?: string;
+    onScreen?: string;
+    seconds?: number;
+    motion?: string;
+};
+export type MotionPlan = {
+    idea?: string;
+    look?: Record<string, string>;
+    beats: MotionBeat[];
+    transition?: string;
+};
+export declare function isMotionPlan(raw: unknown): raw is MotionPlan;
 export declare function systemPrompt(options?: Partial<PromptOptions>): string;
+export declare function planSystemPrompt(): string;
+export declare function planUserPrompt(brief: string, options: PromptOptions): string;
 export declare function userPrompt(brief: string, options: PromptOptions): string;
 export declare function refineUserPrompt(composition: any, instruction: string): string;
 /** Compositions longer than this many characters are shown to the model as an outline, not in full (about 4000 tokens). */

package/dist/types/packages/ai/src/providers.d.ts

@@ -1,13 +1,16 @@
 export type ChatRole = 'system' | 'user' | 'assistant';
 export type ChatMessage = {
     role: ChatRole;
-    content: string;
+    content: string | any[];
 };
+export type ChatTask = 'compose' | 'template' | 'heal' | 'brand' | 'batch' | 'vision' | 'fast';
 export type ChatOptions = {
     json?: boolean;
     temperature?: number;
     maxTokens?: number;
     signal?: AbortSignal;
+    task?: ChatTask;
+    model?: string;
 };
 export type ImageOptions = {
     size?: string;
@@ -53,7 +56,7 @@ export type AiProvider = {
         signal?: AbortSignal;
     }): Promise<Transcript>;
 };
-export type ProviderId = 'groq' | 'mock';
+export type ProviderId = 'anthropic' | 'claude' | 'groq' | 'nvidia' | 'nim' | 'freellmapi' | 'openai' | 'mock';
 export type ProviderConfig = {
     provider?: string;
     model?: string;
@@ -98,6 +101,36 @@ export declare class GroqProvider implements AiProvider {
         signal?: AbortSignal;
     }): Promise<Transcript>;
 }
+export declare class AnthropicProvider implements AiProvider {
+    id: string;
+    model: string;
+    baseUrl: string;
+    apiKey: string;
+    constructor(config?: ProviderConfig);
+    chat(messages: ChatMessage[], options?: ChatOptions): Promise<string>;
+}
+export declare class NvidiaProvider implements AiProvider {
+    id: string;
+    model: string;
+    baseUrl: string;
+    apiKey: string;
+    constructor(config?: ProviderConfig);
+    private headers;
+    chat(messages: ChatMessage[], options?: ChatOptions): Promise<string>;
+}
+export declare const TASK_MODEL_PREFERENCES: Record<ChatTask, string[]>;
+export declare function getAvailableFreeLlmModels(baseUrl: string, headers: Record<string, string>, signal?: AbortSignal): Promise<Set<string>>;
+export declare function inferChatTask(messages: ChatMessage[], options?: ChatOptions): ChatTask;
+export declare class FreeLlmApiProvider implements AiProvider {
+    id: string;
+    model: string;
+    baseUrl: string;
+    apiKey: string;
+    constructor(config?: ProviderConfig);
+    private headers;
+    resolveModel(task: ChatTask, explicitModel?: string, signal?: AbortSignal): Promise<string>;
+    chat(messages: ChatMessage[], options?: ChatOptions): Promise<string>;
+}
 export declare class MockProvider implements AiProvider {
     id: string;
     model: string;

package/dist/types/packages/ai/src/registry.d.ts

@@ -0,0 +1,81 @@
+export type GenerationPath = 'template' | 'json' | 'react';
+export type CapabilityKind = 'template' | 'theme' | 'block' | 'component' | 'effect' | 'sound';
+export type Param = {
+    name: string;
+    type: string;
+    description?: string;
+};
+export type Capability = {
+    id: string;
+    kind: CapabilityKind;
+    name: string;
+    description: string;
+    /** Which generation paths can use this capability. */
+    paths: GenerationPath[];
+    version: string;
+    /** What the user (or the model filling a template) must supply. */
+    params: Param[];
+    /** Compatibility text, such as an aspect ratio, the wanted length, or "takes a theme". */
+    fit?: string;
+    example?: string;
+    width?: number;
+    height?: number;
+    durationSeconds?: number;
+    takesTheme?: boolean;
+};
+export type Registry = {
+    version: string;
+    capabilities: Capability[];
+    select(kind: CapabilityKind): Capability[];
+    find(kind: CapabilityKind, id: string): Capability | undefined;
+    counts(): Record<CapabilityKind, number>;
+};
+/** Entries the calling package knows: its own template, theme and block catalogues. Metadata only; no source JSON. */
+export type TemplateEntry = {
+    id: string;
+    name: string;
+    description: string;
+    width: number;
+    height: number;
+    durationSeconds: number;
+    themed?: boolean;
+    variables: {
+        name: string;
+        type: string;
+        description?: string;
+    }[];
+};
+export type ThemeEntry = {
+    id: string;
+    name: string;
+    description: string;
+};
+export type BlockEntry = {
+    id: string;
+    name: string;
+    description: string;
+    category: string;
+    kind: 'scene' | 'overlay';
+    durationFrames: number;
+};
+export type RegistryInput = {
+    templates?: TemplateEntry[];
+    themes?: ThemeEntry[];
+    blocks?: BlockEntry[];
+};
+export declare const registryVersion = "1";
+export declare function buildRegistry(input?: RegistryInput): Registry;
+/** The same aspect ratio, within 2%: a 1080x1080 template fits a 1078x1085 canvas. */
+export declare function sameShape(a: {
+    width?: number;
+    height?: number;
+}, b: {
+    width: number;
+    height: number;
+}): boolean;
+/** The registry as compact text for the planner prompt, grouped by kind. */
+export declare function describeCapabilities(registry: Registry, fit: {
+    width: number;
+    height: number;
+    allowReact?: boolean;
+}): string;

package/dist/types/packages/ai/src/retime.d.ts

@@ -0,0 +1,7 @@
+import type { Composition } from '../../core/src/index.js';
+/**
+ * Stretches or trims a composition to the requested length in seconds. Scenes keep their relative lengths and
+ * everything inside them scales by the same factor; the composition is returned unchanged when it already has
+ * the requested length.
+ */
+export declare function retimeComposition(composition: Composition, targetSeconds: number): Composition;

package/dist/types/packages/ai/src/shorts.d.ts

@@ -0,0 +1,75 @@
+import type { AiProvider, Transcript, TranscriptWord } from './providers.js';
+import { type CutPlan } from './edit.js';
+export type ShortCandidate = {
+    /** Seconds into the source where the short starts and ends. */
+    from: number;
+    to: number;
+    /** The rubric total; see planShorts for the parts. */
+    score: number;
+    breakdown: {
+        endsClean: number;
+        hook: number;
+        density: number;
+        lengthFit: number;
+    };
+    /** The words in the short, in source time. */
+    words: TranscriptWord[];
+    /** The words as one line — the first sentence is the hook a viewer sees first. */
+    text: string;
+};
+export type PlanShortsOptions = {
+    /** How many shorts to pick (default 3). */
+    count?: number;
+    /** Shortest candidate, in seconds (default 15). */
+    minSeconds?: number;
+    /** Longest candidate, in seconds (default 60). */
+    maxSeconds?: number;
+    /** A pause longer than this, in seconds, ends a sentence even without punctuation (default 0.8). */
+    maxSilence?: number;
+};
+/**
+ * Scores windows of whole sentences as candidate shorts. Every candidate starts at a sentence boundary (a cut
+ * there never looks accidental); the rubric rewards a clean ending (2), a hook in the first sentence (2), dense
+ * speech (0–1), and a length near the 25–45 s sweet spot (0–1). The best `count` non-overlapping windows win.
+ */
+export declare function planShorts(transcript: Transcript, options?: PlanShortsOptions): ShortCandidate[];
+/** The cut plan for one candidate: tightened like `ove ai edit`, or one continuous stretch with `cut: false`. */
+export declare function shortsCandidatePlan(candidate: ShortCandidate, cut: boolean, maxSilence: number, keepFillers: boolean): CutPlan;
+export type ShortsOptions = {
+    /** Path to the long recording (any file FFmpeg reads). */
+    clip: string;
+    /** Directory to write the projects into: `<outDir>/short-01/`, `<outDir>/short-02/`, … */
+    outDir: string;
+    count?: number;
+    minSeconds?: number;
+    maxSeconds?: number;
+    width?: number;
+    height?: number;
+    fps?: number;
+    /** Tighten silences and fillers inside each short (default true); false keeps each short one continuous stretch. */
+    cut?: boolean;
+    maxSilence?: number;
+    keepFillers?: boolean;
+    captions?: boolean;
+    language?: string;
+    signal?: AbortSignal;
+    onProgress?: (message: string) => void;
+};
+export type ShortResult = {
+    dir: string;
+    composition: string;
+    index: number;
+    from: number;
+    to: number;
+    score: number;
+    text: string;
+    durationSeconds: number;
+    words: number;
+};
+export type ShortsResult = {
+    dir: string;
+    sourceSeconds: number;
+    shorts: ShortResult[];
+};
+/** Transcribes a long recording once and writes the best `count` shorts as projects. */
+export declare function shortsFrom(provider: AiProvider, options: ShortsOptions): Promise<ShortsResult>;

package/dist/types/packages/cli/src/agent-cli.d.ts

@@ -0,0 +1,15 @@
+import { type VideoFormat } from '../../ai/src/agent.js';
+/** The agent's settings parsed from the checked arguments index.ts passes ([command, ...args]). */
+export declare function agentArgs(argv: string[]): {
+    brief: string | undefined;
+    dir: string | undefined;
+    url: string | undefined;
+    format: VideoFormat;
+    durationSeconds: number;
+    fps: number;
+    shouldRender: boolean;
+    noPlan: boolean;
+    providerName: string | undefined;
+    model: string | undefined;
+};
+export declare function runAgentCli(argv: string[]): Promise<number>;