@vibeframe/cli 0.105.1 → 0.106.0

package/dist/commands/_shared/status-jobs.d.ts

@@ -0,0 +1,197 @@
+import type { BuildAssetKind } from "./build-cache.js";
+export type JobStatus = "queued" | "running" | "completed" | "failed" | "cancelled" | "unknown";
+export type JobType = "generate-video" | "generate-music";
+export type ProjectWorkflowStatus = "empty" | "ready" | "running" | "needs-author" | "failed" | "done" | "warn";
+export type ProjectCurrentStage = "init" | "assets" | "compose" | "sync" | "render" | "review" | "done";
+export interface JobRecord {
+    schemaVersion: "1";
+    id: string;
+    jobType: JobType;
+    status: JobStatus;
+    providerStatus?: string;
+    createdAt: string;
+    updatedAt: string;
+    projectDir: string;
+    workingDirectory: string;
+    command: string;
+    provider: string;
+    providerTaskId: string;
+    providerTaskType?: "text2video" | "image2video";
+    progress?: number;
+    resultUrl?: string;
+    beatId?: string;
+    outputPath?: string;
+    cachePath?: string;
+    assetKind?: BuildAssetKind;
+    assetCue?: string;
+    assetOptions?: Record<string, unknown>;
+    cacheKey?: string;
+    canonicalPath?: string;
+    metadataPath?: string;
+    error?: string;
+    promptPreview?: string;
+    retryWith: string[];
+}
+export interface CreateJobRecordOptions {
+    id?: string;
+    now?: Date;
+    jobType: JobType;
+    status?: JobStatus;
+    provider: string;
+    providerTaskId: string;
+    providerTaskType?: "text2video" | "image2video";
+    projectDir?: string;
+    workingDirectory?: string;
+    command: string;
+    prompt?: string;
+    progress?: number;
+    resultUrl?: string;
+    beatId?: string;
+    outputPath?: string;
+    cachePath?: string;
+    assetKind?: BuildAssetKind;
+    assetCue?: string;
+    assetOptions?: Record<string, unknown>;
+    cacheKey?: string;
+    canonicalPath?: string;
+    metadataPath?: string;
+    error?: string;
+}
+export interface RefreshJobOptions {
+    wait?: boolean;
+    output?: string;
+    workingDirectory?: string;
+    write?: boolean;
+}
+export interface JobStatusResult {
+    schemaVersion: "1";
+    kind: "job";
+    id: string;
+    jobType: JobType;
+    status: JobStatus;
+    provider: string;
+    providerTaskId: string;
+    providerTaskType?: "text2video" | "image2video";
+    createdAt: string;
+    updatedAt: string;
+    progress?: JobProgress;
+    result: JobResult | null;
+    job: JobRecord;
+    refreshed: boolean;
+    live: {
+        supported: boolean;
+        error?: string;
+    };
+    warnings: string[];
+    retryWith: string[];
+}
+export interface ProjectStatusResult {
+    schemaVersion: "1";
+    kind: "project";
+    project: string;
+    status: ProjectWorkflowStatus;
+    currentStage: ProjectCurrentStage;
+    beats: ProjectBeatReadiness;
+    build: BuildSummary | null;
+    review: ReviewSummary | null;
+    jobs: {
+        total: number;
+        active: number;
+        completed: number;
+        failed: number;
+        cancelled: number;
+        unknown: number;
+        latest: JobSummary[];
+    };
+    warnings: string[];
+    retryWith: string[];
+}
+export interface BuildSummary {
+    reportPath: string;
+    kind?: string;
+    success?: boolean;
+    phase?: string;
+    status?: string;
+    currentStage?: string;
+    selectedStage?: string;
+    outputPath?: string;
+    estimatedCostUsd?: number;
+    costUsd?: number;
+    beats?: ProjectBeatReadiness;
+    updatedAt?: string;
+    warnings: unknown[];
+    retryWith: string[];
+}
+export interface ReviewSummary {
+    reportPath: string;
+    kind?: string;
+    mode?: string;
+    status?: string;
+    score?: number;
+    issueCount: number;
+    errorCount: number;
+    warningCount: number;
+    infoCount: number;
+    fixOwners: {
+        vibe: number;
+        hostAgent: number;
+    };
+    sourceReports: string[];
+    updatedAt?: string;
+    retryWith: string[];
+}
+export interface JobSummary {
+    id: string;
+    jobType: JobType;
+    status: JobStatus;
+    provider: string;
+    providerTaskId: string;
+    providerTaskType?: string;
+    progress?: number;
+    resultUrl?: string;
+    beatId?: string;
+    outputPath?: string;
+    error?: string;
+    createdAt: string;
+    updatedAt: string;
+    retryWith: string[];
+}
+export interface JobProgress {
+    percent?: number;
+    phase: string;
+    providerStatus?: string;
+}
+export interface JobResult {
+    url?: string;
+    outputPath?: string;
+    cachePath?: string;
+    error?: string;
+}
+export interface ProjectBeatReadiness {
+    total: number;
+    assetsReady: number;
+    compositionsReady: number;
+    needsAuthor: string[];
+}
+export declare function findProjectRoot(start?: string): string;
+export declare function jobsDir(projectDir: string): string;
+export declare function normalizeJobStatus(status: unknown): JobStatus;
+export declare function createJobRecord(opts: CreateJobRecordOptions): JobRecord;
+export declare function createAndWriteJobRecord(opts: CreateJobRecordOptions): Promise<JobRecord>;
+export declare function writeJobRecord(record: JobRecord): Promise<void>;
+export declare function readJobRecord(jobId: string, projectDir?: string): Promise<JobRecord | null>;
+export declare function listJobRecords(projectDir: string): Promise<JobRecord[]>;
+export declare function refreshJobRecord(record: JobRecord, opts?: RefreshJobOptions): Promise<JobStatusResult>;
+export declare function inspectProjectStatus(projectDirArg: string, opts?: {
+    refresh?: boolean;
+}): Promise<ProjectStatusResult>;
+export declare function summarizeJob(record: JobRecord): JobSummary;
+export declare function retryWithForJob(record: JobRecord): string[];
+export declare function makeJobStatusResult(record: JobRecord, opts: {
+    refreshed: boolean;
+    live: {
+        supported: boolean;
+        error?: string;
+    };
+    warnings?: string[];
+}): JobStatusResult;

package/dist/commands/_shared/status-jobs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/_shared/storyboard-draft.d.ts

@@ -0,0 +1,13 @@
+import type { VisualStyle } from "./visual-styles.js";
+export interface StoryboardDraft {
+    storyboardMd: string;
+    designMd: string;
+    warnings: string[];
+}
+export declare function draftStoryboardFromBrief(opts: {
+    name: string;
+    brief: string;
+    durationSec?: number;
+    aspect?: string;
+    visualStyle?: VisualStyle;
+}): StoryboardDraft;

package/dist/commands/_shared/storyboard-draft.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/_shared/storyboard-edit.d.ts

@@ -0,0 +1,26 @@
+import { type Beat } from "./storyboard-parse.js";
+export declare const STORYBOARD_CUE_KEYS: readonly ["duration", "narration", "backdrop", "video", "motion", "voice", "music", "asset"];
+export type StoryboardCueKey = (typeof STORYBOARD_CUE_KEYS)[number];
+export interface StoryboardValidationIssue {
+    severity: "error" | "warning";
+    code: string;
+    message: string;
+    beatId?: string;
+}
+export interface StoryboardValidationResult {
+    ok: boolean;
+    beats: Beat[];
+    issues: StoryboardValidationIssue[];
+}
+export declare function validateStoryboardMarkdown(markdown: string): StoryboardValidationResult;
+export declare function getStoryboardBeat(markdown: string, beatId: string): Beat | null;
+export declare function setStoryboardCue(markdown: string, opts: {
+    beatId: string;
+    key: string;
+    value?: unknown;
+    unset?: boolean;
+}): string;
+export declare function moveStoryboardBeat(markdown: string, opts: {
+    beatId: string;
+    afterBeatId: string;
+}): string;

package/dist/commands/_shared/storyboard-edit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/_shared/storyboard-parse.d.ts

@@ -0,0 +1,159 @@
+/**
+ * @module _shared/storyboard-parse
+ *
+ * Parses a STORYBOARD.md document into the shape `compose-scenes-with-skills`
+ * (v0.59+) needs: a `global` direction block (everything before the first
+ * `## Beat …` heading) plus an array of `beats`.
+ *
+ * The format follows Hyperframes' step-4-storyboard.md convention, but stays
+ * forgiving on small variations (em-dash vs hyphen vs colon between "Beat N"
+ * and the title; explicit "Beat" prefix optional).
+ *
+ * v0.60 adds optional YAML cue extraction so a `vibe scene build` driver can
+ * dispatch TTS / image-gen / duration without separate flags:
+ *   - **Project frontmatter** — `---\n…yaml…\n---` at the top of the file
+ *     (standard markdown frontmatter). Holds project-wide defaults like
+ *     providers, voice, default duration. Stripped from `global`.
+ *   - **Per-beat cues** — the FIRST ```yaml fenced block inside a beat body,
+ *     parsed into `Beat.cues`. Stripped from `body` so the LLM prompt
+ *     stays free of machine-only metadata.
+ * Both are back-compat: storyboards without frontmatter or yaml blocks
+ * parse exactly as before.
+ *
+ * Pure function. No I/O.
+ */
+export interface ParsedStoryboard {
+    /**
+     * Markdown content before the first `## …` heading. Holds project-wide
+     * direction (format, audio, style basis). Trimmed; may be empty.
+     * **Project frontmatter (`---\n…\n---`) is stripped from this field.**
+     */
+    global: string;
+    /** One entry per `## …` heading. Order matches the document. */
+    beats: Beat[];
+    /**
+     * Project-level YAML frontmatter parsed from the top of the document, if
+     * present. Holds defaults the `vibe scene build` driver applies to every
+     * beat unless overridden by a per-beat cue. Undefined when no frontmatter
+     * was present.
+     */
+    frontmatter?: ProjectFrontmatter;
+}
+/**
+ * Project-level cues from the document's top frontmatter. All fields are
+ * optional — the driver (or user) supplies CLI-flag fallbacks.
+ *
+ * Index signature stays open so projects can stash custom keys (e.g. brand
+ * colour palette overrides) without TypeScript pushback.
+ */
+export interface ProjectFrontmatter {
+    /** Slug for the project — informational, not used by the parser. */
+    project?: string;
+    /**
+     * Per-primitive provider preferences. Keys match the CLI's `--tts`,
+     * `--image-provider`, `--music-provider` flags.
+     */
+    providers?: {
+        tts?: string;
+        image?: string;
+        video?: string;
+        music?: string;
+    };
+    /** Default voice id for TTS (provider-specific — see `--voice` flag). */
+    voice?: string;
+    /** Default beat duration in seconds when a beat omits both cue and `### Beat duration`. */
+    defaultDuration?: number;
+    /** Visual identity preset hint (informational; e.g. "Swiss Pulse"). */
+    style?: string;
+    [key: string]: unknown;
+}
+/**
+ * Per-beat cues extracted from the first ```yaml fenced block inside a beat
+ * body. The driver passes these to TTS / image / compose calls so the
+ * storyboard alone is enough source for `vibe scene build`.
+ */
+export interface BeatCues {
+    /** Narration text for this beat (drives TTS + scene `<audio>` element). */
+    narration?: string;
+    /** Image prompt for the backdrop generation (drives T2I). */
+    backdrop?: string;
+    /** Beat duration in seconds — overrides `### Beat duration` subsection if both present. */
+    duration?: number;
+    /** Voice override for this beat (overrides project frontmatter `voice`). */
+    voice?: string;
+    [key: string]: unknown;
+}
+export interface Beat {
+    /**
+     * Stable id for the beat. Derivation order:
+     *   1. `## Beat <ID> [— or - or :] [Title]` → "<ID>" (lowercased, slugified
+     *      if non-alphanumeric — e.g. "1", "hook", "scene-2").
+     *   2. `## <Title>` (no Beat prefix) → slug(<Title>).
+     * Always non-empty, kebab-case-or-numeric.
+     */
+    id: string;
+    /** The full original heading line (without the leading `## `). */
+    heading: string;
+    /**
+     * Markdown body of the beat, including any nested `### …` subsections.
+     * Trimmed. Excludes the `## …` line itself. **The leading ```yaml cue
+     * block (if present) is stripped** so this field stays clean for LLM
+     * prompts.
+     */
+    body: string;
+    /**
+     * Beat duration in seconds, derived from (in priority order):
+     *   1. `cues.duration` (per-beat YAML)
+     *   2. `### Beat duration` subsection
+     * Undefined when neither is present.
+     */
+    duration?: number;
+    /**
+     * Per-beat cues parsed from the first ```yaml block inside the body.
+     * Undefined when no yaml block was present.
+     */
+    cues?: BeatCues;
+}
+/**
+ * Parse a STORYBOARD.md document into structured beats.
+ *
+ * Empty input → `{ global: "", beats: [] }`.
+ * Input with no `##` headings → `{ global: <whole doc>, beats: [] }`.
+ */
+export declare function parseStoryboard(md: string): ParsedStoryboard;
+/**
+ * Strip a leading `---\n…\n---` YAML frontmatter block and return the parsed
+ * value. Returns `{ frontmatter: undefined, remaining: input }` when there's
+ * no frontmatter, when the YAML doesn't parse, or when the parsed root isn't
+ * an object — graceful degradation, since the downstream caller can always
+ * fall back on CLI flags.
+ */
+export declare function extractProjectFrontmatter(md: string): {
+    frontmatter: ProjectFrontmatter | undefined;
+    remaining: string;
+};
+/**
+ * Pull a leading ```yaml cue block off a beat body and return both the parsed
+ * cues and the remaining body (cues stripped). Mirrors
+ * `extractProjectFrontmatter`'s "swallow only when valid" behaviour.
+ */
+export declare function extractBeatCues(body: string): {
+    cues: BeatCues | undefined;
+    body: string;
+};
+/**
+ * Derive a stable id from a `## …` heading line (the part after `## `).
+ *
+ * Examples:
+ *   "Beat 1 — Hook"       → "1"
+ *   "Beat hook : Intro"   → "hook"
+ *   "Beat 2 - Core"       → "2"
+ *   "Hook"                → "hook"
+ *   "Hook (3 seconds)"    → "hook"
+ */
+export declare function deriveBeatId(headingLine: string): string;
+/**
+ * Look for a `### Beat duration` subsection inside a beat body and parse
+ * the first number. Returns undefined when absent or unparseable.
+ */
+export declare function parseBeatDuration(body: string): number | undefined;

package/dist/commands/_shared/storyboard-parse.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/_shared/storyboard-revise.d.ts

@@ -0,0 +1,32 @@
+import type { AgentMessage } from "../../agent/types.js";
+import { type ComposerProvider } from "./composer-resolve.js";
+import { type StoryboardValidationResult } from "./storyboard-edit.js";
+export type StoryboardRevisionChat = (messages: AgentMessage[]) => Promise<string>;
+export interface StoryboardRevisionOptions {
+    projectDir: string;
+    request: string;
+    durationSec?: number;
+    composer?: ComposerProvider;
+    dryRun?: boolean;
+    chat?: StoryboardRevisionChat;
+}
+export interface StoryboardRevisionResult {
+    schemaVersion: "1";
+    kind: "storyboard-revision";
+    success: boolean;
+    projectDir: string;
+    storyboardPath: string;
+    provider?: ComposerProvider;
+    summary: string;
+    changedBeats: string[];
+    validation: StoryboardValidationResult;
+    warnings: string[];
+    wrote: boolean;
+    retryWith: string[];
+    storyboard?: string;
+    code?: string;
+    message?: string;
+    suggestion?: string;
+    recoverable?: boolean;
+}
+export declare function executeStoryboardRevision(opts: StoryboardRevisionOptions): Promise<StoryboardRevisionResult>;

package/dist/commands/_shared/storyboard-revise.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/_shared/timeline-project.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @module _shared/timeline-project
+ *
+ * Shared action logic for `vibe timeline create/info/set` (and the
+ * deprecated `vibe project create/info/set` alias). Extracted so both
+ * surfaces call the same code path — the only difference is which
+ * default filename `create` writes to:
+ *
+ * - `vibe timeline create` → `timeline.json` (canonical)
+ * - `vibe project create`  → `project.vibe.json` (legacy, deprecated)
+ *
+ * Read-side commands (`info`, `set`) use `resolveTimelineFile` which
+ * accepts both filenames. Existing `*.vibe.json` files keep working
+ * forever; only the on-disk filename for *new* creates differs.
+ */
+import { TIMELINE_FILENAME, LEGACY_TIMELINE_FILENAME } from "../../utils/project-resolver.js";
+export { TIMELINE_FILENAME, LEGACY_TIMELINE_FILENAME };
+export interface TimelineCreateOptions {
+    output?: string;
+    ratio?: string;
+    fps?: string;
+    dryRun?: boolean;
+}
+export interface TimelineSetOptions {
+    name?: string;
+    ratio?: string;
+    fps?: string;
+    dryRun?: boolean;
+}
+export declare function executeTimelineCreate(name: string, options: TimelineCreateOptions, commandName: string, startedAt: number, defaultFilename?: string, createDirectoryByDefault?: boolean): Promise<void>;
+export declare function executeTimelineInfo(file: string, commandName: string, startedAt: number): Promise<void>;
+export declare function executeTimelineSet(file: string, options: TimelineSetOptions, commandName: string, startedAt: number): Promise<void>;

package/dist/commands/_shared/tts-resolve.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @module _shared/tts-resolve
+ *
+ * One-stop factory for picking a TTS provider at runtime. Used by every
+ * scene-authoring path that turns text into narration audio (currently
+ * `executeSceneAdd`; `script-to-video --format scenes` follows in C5+).
+ *
+ * Routes between:
+ *   - **ElevenLabs** — cloud, API-key gated, paid (~$0.02/scene). Default
+ *     when `ELEVENLABS_API_KEY` is set.
+ *   - **Kokoro** — local Apache 2.0 model, free, ~330MB first-call download.
+ *     The fallback for key-less users.
+ *
+ * The router exposes a uniform `TtsCallable` shape so call sites don't have
+ * to branch on provider id. Both providers already return the same
+ * `{ success, audioBuffer, error?, characterCount? }` result.
+ */
+import type { KokoroLoadEvent } from "@vibeframe/ai-providers";
+/** TTS providers VibeFrame can route to. `"auto"` picks based on key availability. */
+export type TtsProviderName = "auto" | "elevenlabs" | "kokoro";
+/** Concrete provider id surfaced in result metadata. Never `"auto"`. */
+export type ResolvedTtsProvider = "elevenlabs" | "kokoro";
+/** Options accepted by every {@link TtsCallable}. Subset of provider-specific options. */
+export interface TtsCallOptions {
+    /**
+     * Provider-specific voice id. ElevenLabs takes voice names/ids
+     * (`"rachel"`, `"21m00Tcm..."`); Kokoro takes voice ids (`"af_heart"`,
+     * `"am_michael"`). The router does not map between the two.
+     */
+    voice?: string;
+    /** Speaking speed multiplier (Kokoro: 0.5–2; ElevenLabs: 0.7–1.2). */
+    speed?: number;
+    /** Cold-start progress callback (Kokoro only — fires on first ~330MB load). */
+    onProgress?: (event: KokoroLoadEvent) => void;
+}
+/** Result of a TTS call. Same shape both providers already return. */
+export interface TtsCallResult {
+    success: boolean;
+    audioBuffer?: Buffer;
+    error?: string;
+    characterCount?: number;
+}
+/** Synthesise speech from text. Provider-specific implementation lives behind this. */
+export type TtsCallable = (text: string, options?: TtsCallOptions) => Promise<TtsCallResult>;
+export interface TtsResolution {
+    /** Concrete provider chosen. */
+    provider: ResolvedTtsProvider;
+    /** Output container — drives the narration filename extension. */
+    audioExtension: "mp3" | "wav";
+    /** Synthesise text → audio buffer. */
+    call: TtsCallable;
+}
+/**
+ * Resolve a TTS provider preference into a callable + metadata.
+ *
+ * Resolution policy:
+ *   - `"elevenlabs"`: requires `ELEVENLABS_API_KEY`. Throws an `ApiKeyError`-style
+ *     error via {@link getApiKey} (consumed by `requireApiKey`/`exitWithError`).
+ *   - `"kokoro"`: always available (local). No key check.
+ *   - `"auto"` (or `undefined`): if an ElevenLabs key is configured in
+ *     project/user config.yaml, .env, or process env, picks ElevenLabs;
+ *     otherwise falls back to Kokoro.
+ */
+export declare function resolveTtsProvider(preferred?: TtsProviderName): Promise<TtsResolution>;
+/**
+ * Thrown when the caller asked for a specific provider whose key/runtime is
+ * unavailable. Carries the provider id so the caller can format a clean
+ * `usageError`/`exitWithError`.
+ */
+export declare class TtsKeyMissingError extends Error {
+    readonly provider: ResolvedTtsProvider;
+    constructor(provider: ResolvedTtsProvider);
+}
+/** Validate a free-form `--tts <value>` against {@link TtsProviderName}. */
+export declare function parseTtsProviderName(value: string | undefined): TtsProviderName;

package/dist/commands/_shared/tts-resolve.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for the TTS router. The actual provider classes are mocked at
+ * the module level so we can drive resolution outcomes deterministically.
+ */
+export {};

package/dist/commands/_shared/video-providers.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @module _shared/video-providers
+ * @description Per-provider `generateVideoWithRetry*` helpers used by the
+ * script-to-video pipeline. Each wraps a single AI provider's video
+ * generation API in a retry loop with onProgress callbacks. Split out of
+ * `ai-script-pipeline.ts` in v0.69 (Plan G Phase 4).
+ */
+import type { GeminiProvider, GrokProvider, KlingProvider, RunwayProvider } from "@vibeframe/ai-providers";
+import { type StoryboardSegment } from "./video-utils.js";
+/** Generate video with retry logic for Grok provider. */
+export declare function generateVideoWithRetryGrok(grok: GrokProvider, segment: StoryboardSegment, options: {
+    duration: number;
+    aspectRatio: "16:9" | "9:16" | "1:1";
+    referenceImage?: string;
+}, maxRetries: number, onProgress?: (message: string) => void): Promise<{
+    requestId: string;
+} | null>;
+/**
+ * Generate video with retry logic for Kling provider.
+ * Supports image-to-video with URL (v2.5/v2.6 models).
+ */
+export declare function generateVideoWithRetryKling(kling: KlingProvider, segment: StoryboardSegment, options: {
+    duration: 5 | 10;
+    aspectRatio: "16:9" | "9:16" | "1:1";
+    referenceImage?: string;
+}, maxRetries: number, onProgress?: (message: string) => void): Promise<{
+    taskId: string;
+    type: "text2video" | "image2video";
+} | null>;
+/** Generate video with retry logic for Runway provider. */
+export declare function generateVideoWithRetryRunway(runway: RunwayProvider, segment: StoryboardSegment, referenceImage: string, options: {
+    duration: 5 | 10;
+    aspectRatio: "16:9" | "9:16";
+}, maxRetries: number, onProgress?: (message: string) => void): Promise<{
+    taskId: string;
+} | null>;
+/** Generate video with retry logic for Veo (Gemini) provider. */
+export declare function generateVideoWithRetryVeo(gemini: GeminiProvider, segment: StoryboardSegment, options: {
+    duration: 4 | 6 | 8;
+    aspectRatio: "16:9" | "9:16" | "1:1";
+    referenceImage?: string;
+}, maxRetries: number, onProgress?: (message: string) => void): Promise<{
+    operationName: string;
+} | null>;

package/dist/commands/_shared/video-utils.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @module _shared/video-utils
+ * @description Shared helpers for the script-to-video pipeline:
+ * StoryboardSegment type, retry constants, ImgBB upload, FFmpeg/Kling
+ * video extension, error logging, and the generic wait-for-completion
+ * loop. Split out of `ai-script-pipeline.ts` in v0.69 (Plan G Phase 4).
+ */
+import type { KlingProvider, RunwayProvider } from "@vibeframe/ai-providers";
+/** A single scene segment from the Claude-generated storyboard. */
+export interface StoryboardSegment {
+    /** 1-based scene index (assigned during generation) */
+    index?: number;
+    /** Narrative description of the scene */
+    description: string;
+    /** Visual prompt for image/video generation */
+    visuals: string;
+    /** Art style directive (e.g. "cinematic", "anime") */
+    visualStyle?: string;
+    /** Character appearance description for consistency */
+    characterDescription?: string;
+    /** Reference to previous scene for continuity */
+    previousSceneLink?: string;
+    /** Voiceover narration text */
+    narration?: string;
+    /** Audio direction (e.g. "upbeat music") */
+    audio?: string;
+    /** Text lines to overlay on the video */
+    textOverlays?: string[];
+    /** Scene duration in seconds (updated to match narration) */
+    duration: number;
+    /** Cumulative start time in seconds */
+    startTime: number;
+}
+/** Default retry count for video generation API calls. */
+export declare const DEFAULT_VIDEO_RETRIES = 2;
+/** Delay between retries in milliseconds. */
+export declare const RETRY_DELAY_MS = 5000;
+/** Sleep helper. */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Upload image to ImgBB and return the URL.
+ * Used for Kling v2.5/v2.6 image-to-video which requires URL (not base64).
+ */
+export declare function uploadToImgbb(imageBuffer: Buffer, apiKey: string): Promise<{
+    success: boolean;
+    url?: string;
+    error?: string;
+}>;
+/**
+ * Extend a video to target duration using Kling extend API when possible,
+ * with fallback to FFmpeg-based extendVideoNaturally.
+ *
+ * When the extension ratio > 1.4 and a Kling provider + videoId are available,
+ * uses the Kling video-extend API for natural continuation instead of freeze frames.
+ */
+export declare function extendVideoToTarget(videoPath: string, targetDuration: number, outputDir: string, sceneLabel: string, options?: {
+    kling?: KlingProvider;
+    videoId?: string;
+    onProgress?: (message: string) => void;
+}): Promise<void>;
+/**
+ * Log a provider failure to stderr. Centralizes the "what went wrong" output
+ * so call sites stop silently dropping provider errors into failedScenes.
+ */
+export declare function logSceneFailure(provider: string, sceneLabel: string, err: unknown): void;
+/**
+ * Wait for video completion with retry logic.
+ */
+export declare function waitForVideoWithRetry(provider: KlingProvider | RunwayProvider, taskId: string, providerType: "kling" | "runway", maxRetries: number, onProgress?: (message: string) => void, timeout?: number): Promise<{
+    videoUrl: string;
+} | null>;