@vibeframe/cli 0.113.10 → 0.113.24

package/dist/commands/_shared/scene-build.d.ts

@@ -64,6 +64,19 @@ export type SceneBuildProgressEvent = {
     type: "narration-skipped";
     beatId: string;
     reason: string;
+} | {
+    type: "transcript-generated";
+    beatId: string;
+    path: string;
+    wordCount: number;
+} | {
+    type: "transcript-cached";
+    beatId: string;
+    path: string;
+} | {
+    type: "transcript-skipped";
+    beatId: string;
+    reason: string;
 } | {
     type: "backdrop-cached";
     beatId: string;
@@ -234,7 +247,7 @@ export interface SceneBuildOptions {
      * based on env keys (claude > gemini > openai). Pass an explicit value
      * to require that provider's key.
      */
-    composer?: ComposerProvider;
+    composer?: ComposerProvider | "template";
     skipNarration?: boolean;
     skipBackdrop?: boolean;
     skipRender?: boolean;
@@ -254,6 +267,13 @@ export interface SceneBuildOptions {
     skipKeyframe?: boolean;
     /** Skip music generation even when beats declare music cues. */
     skipMusic?: boolean;
+    /**
+     * Skip Whisper word-level transcription of generated narration. Default is
+     * to transcribe whenever narration exists and an OpenAI key is configured,
+     * writing `assets/transcript-<beat>.json` so the composer can sync caption /
+     * kinetic-type reveals to speech. Pass true to opt out (no transcribe cost).
+     */
+    skipTranscript?: boolean;
     /** OpenAI image quality — see `vibe generate image --quality`. */
     imageQuality?: "standard" | "hd";
     /** OpenAI image size. Default 1536x1024 for cinematic 16:9-ish framing. */
@@ -282,9 +302,9 @@ export interface SceneBuildOptions {
  *   - `failed` — primitives, compose, or render errored. {@link error}
  *     carries the message; {@link beats} reflects partial state.
  */
-export type SceneBuildPhase = "done" | "assets-only" | "pending-jobs" | "compose-only" | "sync-only" | "render-only" | "needs-author" | "failed";
+export type SceneBuildPhase = "done" | "assets-only" | "transcript-only" | "pending-jobs" | "compose-only" | "sync-only" | "render-only" | "needs-author" | "failed";
 export type BuildWorkflowStatus = "done" | "running" | "needs-author" | "failed" | "ready";
-export type BuildCurrentStage = "assets" | "compose" | "sync" | "render" | "done";
+export type BuildCurrentStage = "assets" | "transcript" | "compose" | "sync" | "render" | "done";
 export interface BuildBeatSummary {
     total: number;
     assetsReady: number;
@@ -333,6 +353,7 @@ export interface SceneBuildResult {
     composePrompts?: {
         skillReference: string | null;
         designReference: string;
+        compositionReference: string | null;
         storyboardReference: string;
         compositionsDir: string;
         instructions: string[];
@@ -346,7 +367,7 @@ export interface SceneBuildResult {
     beatSummary?: BuildBeatSummary;
     estimatedCostUsd?: number;
     costUsd?: number;
-    stageReports?: Record<"assets" | "compose" | "sync" | "render", StageReport>;
+    stageReports?: Record<"assets" | "transcript" | "compose" | "sync" | "render", StageReport>;
     sceneRepair?: BuildSceneRepairSummary;
     jobs?: JobRecord[];
     warnings?: string[];
@@ -479,7 +500,7 @@ declare function toBuildReport(projectDir: string, result: SceneBuildResult): {
     }[];
     outputPath: string | undefined;
     sceneRepair: BuildSceneRepairSummary;
-    stageReports: Record<"assets" | "compose" | "sync" | "render", StageReport> | undefined;
+    stageReports: Record<"assets" | "compose" | "sync" | "render" | "transcript", StageReport> | undefined;
     warnings: string[];
     retryWith: string[];
     totalLatencyMs: number;

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

@@ -2,7 +2,7 @@
  * @module _shared/scene-project
  *
  * Helpers for scaffolding a "scene project" — a directory that works as both
- * a VibeFrame project (via `vibe.project.yaml`) AND a HeyGen Hyperframes
+ * a VibeFrame project (via `vibe.config.json`) AND a HeyGen Hyperframes
  * project (via `hyperframes.json` + `meta.json` + `index.html`). Either
  * toolchain can be run inside the directory.
  *
@@ -14,6 +14,37 @@ import type { VisualStyle } from "./visual-styles.js";
 /** Supported aspect ratios for scene projects (maps to CSS canvas dims). */
 export type SceneAspect = "16:9" | "9:16" | "1:1" | "4:5";
 export type SceneScaffoldProfile = "minimal" | "agent" | "full";
+/**
+ * Project KIND — orthogonal to {@link SceneScaffoldProfile} (which decides which
+ * files exist). Kind decides which pipeline STAGES run and which composer is the
+ * default:
+ * - `cinema` / `story` — directed, character-driven; keyframe→i2v, LLM composer.
+ * - `aivideo` — character + i2v, the deterministic `template` composer.
+ * - `product` — backdrop/asset-centric (no i2v keyframes).
+ * - `motion` — pure HTML/CSS/GSAP graphics (no AI image/video assets).
+ */
+export type SceneKind = "cinema" | "product" | "aivideo" | "story" | "motion";
+export declare const VALID_SCENE_KINDS: readonly SceneKind[];
+/** Default kind preserves today's behavior (LLM composer, cue-driven assets). */
+export declare const DEFAULT_SCENE_KIND: SceneKind;
+export declare function isSceneKind(value: string): value is SceneKind;
+/**
+ * Per-kind default asset skips, OR'd with the explicit `--skip-*` flags. Returns
+ * only the skips a kind forces; `cinema`/`story`/`aivideo` add none (assets run
+ * from their cues).
+ */
+export declare function kindAssetPolicy(kind: SceneKind): {
+    skipKeyframe?: boolean;
+    skipVideo?: boolean;
+    skipBackdrop?: boolean;
+};
+/** The composer a kind defaults to when `--composer` is not given. */
+export declare function composerDefaultForKind(kind: SceneKind): "template" | undefined;
+/**
+ * Whether a kind has a recurring cast worth a `CHARACTERS.md` bible. Character-
+ * driven kinds (cinema/story/aivideo) do; product/motion do not.
+ */
+export declare function kindHasCast(kind: SceneKind): boolean;
 export declare function aspectToDims(aspect: SceneAspect): {
     width: number;
     height: number;
@@ -80,22 +111,22 @@ export declare function buildEmptyRootHtml(opts: {
     aspect: SceneAspect;
     duration: number;
 }): string;
-/**
- * Project-local `DESIGN.md` template — the visual-identity hard-gate.
- *
- * Hyperframes' `hyperframes` skill teaches: "no scene HTML before DESIGN.md is
- * authored." This template seeds that contract so the project never opens
- * with a blank slate. When `style` is provided, the rules are pre-filled
- * from the vendored named-style data (`visual-styles.ts`); otherwise the
- * user (or agent) fills the placeholders.
- *
- * The agent-driven craft path expects this file as input — see
- * `.claude/skills/vibe-scene/SKILL.md`.
- */
 export declare function buildDesignMd(opts: {
     name: string;
     style?: VisualStyle;
 }): string;
+/**
+ * Always-on `SCRIPT.md` — the narrative spine authored before the beat-level
+ * STORYBOARD.md. Kind tailors the guidance (a `motion`/`product` script is a
+ * shot/asset list; a `story`/`cinema` script is a scene-by-scene narrative).
+ */
+export declare function buildScriptMd(name: string, kind?: SceneKind): string;
+/**
+ * Kind-gated `CHARACTERS.md` — the cast bible. Promotes today's STORYBOARD
+ * \`characters:\` frontmatter into first-class identity blocks (reference sheet
+ * path + an identity-lock description used to keep keyframes/i2v on-model).
+ */
+export declare function buildCharactersMd(name: string): string;
 /** Starter `STORYBOARD.md` for the one-shot `vibe build` flow. */
 export declare function buildStoryboardMd(name: string, duration?: number): string;
 /** Project-local AGENTS.md that orients every agent host to both toolchains. */
@@ -118,6 +149,8 @@ export interface ScaffoldOptions {
     visualStyle?: VisualStyle;
     /** Scaffold shape. Defaults to "full" for backward-compatible programmatic use. */
     profile?: SceneScaffoldProfile;
+    /** Project kind — drives which pipeline stages run + the default composer. */
+    kind?: SceneKind;
 }
 export interface ScaffoldResult {
     /** Files written (absolute paths). */
@@ -138,6 +171,7 @@ export declare function isSceneScaffoldProfile(value: string): value is SceneSca
 export declare function describeSceneScaffold(opts: {
     dir: string;
     profile?: SceneScaffoldProfile;
+    kind?: SceneKind;
 }): SceneScaffoldGroups;
 /**
  * Scaffold (or update) a scene project at `dir`. Idempotent: running twice is

package/dist/commands/_shared/scene-render.d.ts

@@ -38,6 +38,12 @@ export interface SceneRenderOptions {
     openAfterRender?: boolean;
     /** Reveal the rendered media in Finder/file manager after a successful render. */
     revealInFinder?: boolean;
+    /**
+     * Skip the audio-mux pass and emit silent video. The audio is added later by
+     * the `assemble` stage (`executeSceneAssemble` / `vibe assemble`). Default
+     * `vibe render` keeps the render+assemble single-shot behavior.
+     */
+    silent?: boolean;
     signal?: AbortSignal;
     onProgress?: (pct: number, stage: string) => void;
 }

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

@@ -1,5 +1,5 @@
 import { type Beat } from "./storyboard-parse.js";
-export declare const STORYBOARD_CUE_KEYS: readonly ["duration", "narration", "backdrop", "video", "keyframe", "motion", "voice", "music", "asset", "characters"];
+export declare const STORYBOARD_CUE_KEYS: readonly ["duration", "narration", "backdrop", "video", "keyframe", "motion", "voice", "music", "asset", "characters", "eyebrow", "title", "caption", "kicker", "sub"];
 export type StoryboardCueKey = (typeof STORYBOARD_CUE_KEYS)[number];
 export interface StoryboardValidationIssue {
     severity: "error" | "warning";

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

@@ -120,6 +120,12 @@ export interface BeatCues {
      * if present, supplies the motion prompt; otherwise this text is used.
      */
     keyframe?: string;
+    /** Lower-third overlay eyebrow/kicker (read by the deterministic composer). */
+    eyebrow?: string;
+    /** Lower-third headline; falls back to the beat heading when absent. */
+    title?: string;
+    /** Lower-third sub-line / caption. */
+    caption?: string;
     [key: string]: unknown;
 }
 /** Normalize a beat's `characters` cue to a clean string[] (single or list). */

package/dist/commands/_shared/transcribe-narration.d.ts

@@ -0,0 +1,23 @@
+import type { SceneTranscriptWord } from "./scene-html-emit.js";
+export interface TranscribeNarrationOptions {
+    /** OpenAI API key for Whisper. */
+    apiKey: string;
+    /** Optional BCP-47 language hint passed to Whisper (auto-detect when unset). */
+    language?: string;
+}
+/**
+ * Transcribe a narration audio file to word-level timings. Returns an empty
+ * array on ANY failure (no words, API error, bad audio) so callers can treat
+ * the absence of timings as "no word-sync available" rather than abort.
+ */
+export declare function transcribeNarrationWords(audioAbsPath: string, opts: TranscribeNarrationOptions): Promise<SceneTranscriptWord[]>;
+/** Canonical per-beat transcript path, relative to the project root. */
+export declare function beatTranscriptRelPath(beatId: string): string;
+/**
+ * Read a previously generated `assets/transcript-<beatId>.json` from disk.
+ * Returns `undefined` when the file is missing or malformed — compose then
+ * proceeds without word timings (identical to a project that never
+ * transcribed). Validates each entry's shape so a hand-edited or partial file
+ * can't inject `NaN`/`undefined` timings into the prompt.
+ */
+export declare function readBeatTranscript(projectDir: string, beatId: string): Promise<SceneTranscriptWord[] | undefined>;

package/dist/commands/_shared/transcribe-narration.test.d.ts

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

package/dist/commands/assemble.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const assembleCommand: Command;

package/dist/commands/design.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const designCommand: Command;

package/dist/commands/export.d.ts

@@ -1,4 +1,3 @@
-import { Command } from "commander";
 /**
  * Get the duration of a media file using ffprobe
  * For images, returns a default duration since they have no inherent time
@@ -50,7 +49,6 @@ export declare function validateOverrides(overrides: CustomOverrides): string |
  * Reusable export function for programmatic usage
  */
 export declare function runExport(projectPath: string, outputPath: string, options?: ExportOptions): Promise<ExportResult>;
-export declare const exportCommand: Command;
 export interface PresetSettings {
     resolution: string;
     videoBitrate: string;

package/dist/commands/init.d.ts

@@ -7,7 +7,7 @@
  * machine-wide config (`~/.vibeframe/config.yaml`), init writes
  * project-local files: `AGENTS.md` (cross-tool), `CLAUDE.md` (Claude
  * Code, imports `@AGENTS.md`), `.env.example`, `.gitignore` additions,
- * and an optional `vibe.project.yaml`.
+ * and `vibe.config.json` (the canonical project contract).
  *
  * Scaffolding decision tree:
  *   - Always: `.gitignore` additions, `.env.example`

package/dist/commands/preview.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const previewCommand: Command;

package/dist/commands/preview.test.d.ts

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