@vibeframe/cli 0.105.1 → 0.105.2

package/dist/commands/_shared/scene-html-emit.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @module _shared/scene-html-emit
+ *
+ * Pure HTML emitters for `vibe scene add`. Each preset produces a self-contained
+ * Hyperframes-compatible scene composition: a `<template>`-wrapped `<div
+ * data-composition-id>` with scoped CSS, optional audio/image, and a paused
+ * GSAP timeline registered on `window.__timelines`.
+ *
+ * Also exposes helpers that mutate the root index.html:
+ * - `nextSceneStart()` — sum existing clip end-times to choose the new start
+ * - `insertClipIntoRoot()` — splice a `<div class="clip">` reference before the
+ *   root's closing div, preserving the user's hand-edited markup
+ * - `slugifySceneName()` — name → kebab-case scene id
+ *
+ * Pure functions only — no I/O. The orchestrating command (`scene add`) wires
+ * these to the filesystem.
+ */
+export type ScenePreset = "simple" | "announcement" | "explainer" | "kinetic-type" | "product-shot";
+export declare const SCENE_PRESETS: readonly ScenePreset[];
+/**
+ * One word from a Whisper word-level transcript. Mirrors
+ * {@link import("@vibeframe/ai-providers").TranscriptWord} but is duplicated
+ * here so this module stays pure (no provider package import).
+ */
+export interface SceneTranscriptWord {
+    text: string;
+    start: number;
+    end: number;
+}
+export interface EmitSceneInput {
+    /** Kebab-case scene id; appears in `data-composition-id` and template id. */
+    id: string;
+    preset: ScenePreset;
+    /** Canvas width in px (must match the root composition). */
+    width: number;
+    /** Canvas height in px (must match the root composition). */
+    height: number;
+    /** Visible composition duration in seconds. */
+    duration: number;
+    /** Headline text — required for non-simple presets; defaulted from id. */
+    headline?: string;
+    /** Secondary text (subhead/caption). Often the narration. */
+    subhead?: string;
+    /** Optional small label above the headline (explainer / product-shot). */
+    kicker?: string;
+    /** Project-relative image path (e.g. "assets/scene-intro.png"). */
+    imagePath?: string;
+    /** Project-relative narration audio path (e.g. "assets/narration-intro.mp3"). */
+    audioPath?: string;
+    /**
+     * Word-level timings (Whisper output) for narration sync. When supplied, the
+     * `simple`, `explainer`, and `kinetic-type` presets render each word as its
+     * own `<span class="word">` and animate them at their absolute audio start
+     * times via GSAP. `announcement` and `product-shot` ignore this field —
+     * their headlines are intentionally static.
+     */
+    transcript?: SceneTranscriptWord[];
+}
+/**
+ * Slugify a free-form scene name to a kebab-case id usable in HTML attributes
+ * and filenames. Strips diacritics, collapses whitespace, lowercases.
+ */
+export declare function slugifySceneName(name: string): string;
+/**
+ * Render a transcript as `<span class="word" data-i="N">…</span>` markup,
+ * separated by literal whitespace so kerning and wrapping behave naturally.
+ * Returns the empty string when there's nothing to render.
+ */
+export declare function renderTranscriptSpans(transcript: SceneTranscriptWord[]): string;
+/**
+ * Build absolute-timing GSAP tweens that fade each transcript word in at its
+ * narration `start` time. The `targetSelector` parametrises the scope so the
+ * same routine can drive `simple` (`.caption .word`), `explainer`
+ * (`#subtitle .word`), or `kinetic-type` (`.kinetic .word`).
+ *
+ * Each tween is `tl.fromTo(sel, {opacity:0,y:10}, {opacity:1,y:0,duration:0.18}, start)`
+ * — short enough to feel responsive at any speech rate, long enough to avoid
+ * popping at 30fps. Words clamp to non-negative starts.
+ */
+export declare function buildTranscriptTweens(transcript: SceneTranscriptWord[], targetSelector: string): string;
+/**
+ * Length of the scope opacity fade-in / fade-out applied at every scene's
+ * boundaries. When two adjacent clips overlap by this amount in the parent
+ * timeline (`scene.ts` and `segments-to-scenes.ts` lay them out that way),
+ * the outgoing scene's last `SCENE_OVERLAP_SECONDS` fades to opacity 0
+ * while the incoming scene's first `SCENE_OVERLAP_SECONDS` fades from 0,
+ * yielding a smooth crossfade instead of the hard cut the previous
+ * architecture produced.
+ *
+ * Tuned at 0.4 s — long enough that the eye perceives a soft transition,
+ * short enough that the text content of the next scene is fully present
+ * by the time the entrance animation finishes (entrance starts at 0.05 s).
+ */
+export declare const SCENE_OVERLAP_SECONDS = 0.4;
+/**
+ * Emit the full per-scene HTML. Returns a complete `<template>`-wrapped
+ * composition ready to write to `compositions/scene-<id>.html`.
+ */
+export declare function emitSceneHtml(input: EmitSceneInput): string;
+/**
+ * Sum existing `<div class="clip">` end-times to find where the next scene
+ * should start. Returns 0 for an empty root.
+ *
+ * `overlap` (default 0) is subtracted from the max end-time so callers can
+ * place the new clip to overlap with the previous one — used by the
+ * crossfade architecture (`vibe scene add` and `segments-to-scenes.ts`
+ * pass `SCENE_OVERLAP_SECONDS` here so each new scene's first
+ * `SCENE_OVERLAP_SECONDS` blend with the previous scene's last).
+ */
+export declare function nextSceneStart(rootHtml: string, overlap?: number): number;
+export interface ClipReferenceInput {
+    /** Scene id — used to derive the composition src path. */
+    id: string;
+    start: number;
+    duration: number;
+    trackIndex?: number;
+    /** Override the default `compositions/scene-<id>.html` src. */
+    src?: string;
+}
+/** Build the `<div class="clip" data-composition-id=... data-composition-src=...>` reference string. */
+export declare function buildClipReference(opts: ClipReferenceInput): string;
+/**
+ * Insert a clip reference inside the root composition's `#root` div, just
+ * before its closing `</div>`. Throws if the expected closing tag isn't
+ * found — callers should surface this as a structured error so users know
+ * to inspect a hand-edited root.
+ *
+ * Also grows the root's `data-duration` to fit the new clip's end-time.
+ */
+export declare function insertClipIntoRoot(rootHtml: string, clip: ClipReferenceInput): string;
+/**
+ * Read the root composition's canvas dims by parsing `data-width`/`data-height`
+ * on the `#root` div. Returns null if either is missing — caller should fall
+ * back to the project's aspect config.
+ */
+export declare function readRootDims(rootHtml: string): {
+    width: number;
+    height: number;
+} | null;

package/dist/commands/_shared/scene-html-emit.test.d.ts

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

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

@@ -0,0 +1,56 @@
+import { type ReviewIssue, type ReviewSummary, type ReviewStatus } from "./review-report.js";
+export interface ProjectInspectOptions {
+    projectDir: string;
+    beatId?: string;
+    outputPath?: string;
+    writeReport?: boolean;
+}
+export interface ProjectInspectResult {
+    schemaVersion: "1";
+    kind: "project";
+    mode: "project";
+    project: string;
+    beat?: string;
+    status: ReviewStatus;
+    score: number;
+    issues: ReviewIssue[];
+    summary: ReviewSummary;
+    sourceReports: string[];
+    checks: {
+        files: Record<string, boolean>;
+        storyboard: {
+            ok: boolean;
+            beatCount: number;
+        };
+        compositions: {
+            expected: number;
+            found: number;
+            missing: string[];
+        };
+        lint: {
+            ok: boolean | null;
+            errorCount: number;
+            warningCount: number;
+            infoCount: number;
+        };
+        buildReport: {
+            exists: boolean;
+            outputPath?: string;
+        };
+        assets: {
+            checked: number;
+            missing: string[];
+            stale: string[];
+            unknownFreshness: string[];
+        };
+        rootSync: {
+            ok: boolean | null;
+            issueCount: number;
+            issues: string[];
+        };
+    };
+    retryWith: string[];
+    reportPath?: string;
+}
+export declare function inspectProject(opts: ProjectInspectOptions): Promise<ProjectInspectResult>;
+export declare function displayIssue(issue: ReviewIssue): string;

package/dist/commands/_shared/scene-inspect.test.d.ts

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

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

@@ -0,0 +1,109 @@
+/**
+ * @module _shared/scene-lint
+ *
+ * In-process Hyperframes lint pipeline for VibeFrame scene projects. Wraps
+ * `runHyperframeLint` from `@hyperframes/producer` (its public lint entry
+ * point) and adapts the output to VibeFrame's two-tier file structure:
+ *
+ *   project/
+ *     index.html              # root composition  → linted as-is
+ *     compositions/*.html     # sub-compositions  → producer's lint emits two
+ *                                                   spurious findings here, so
+ *                                                   we filter them out.
+ *
+ * Two findings are filtered for sub-compositions because they encode the
+ * inverse rule (sub-comps SHOULD be wrapped in `<template>` and SHOULD NOT
+ * have an `<html>` wrapper):
+ *   - `standalone_composition_wrapped_in_template`
+ *   - `root_composition_missing_html_wrapper`
+ *
+ * Pure helpers are exported for unit testing; `runProjectLint` does the
+ * filesystem walk + lint orchestration. Mechanical `--fix` is intentionally
+ * conservative — only `timed_element_missing_clip_class` is auto-fixed in
+ * MVP 1.
+ */
+export type LintSeverity = "error" | "warning" | "info";
+export interface LintFinding {
+    code: string;
+    severity: LintSeverity;
+    message: string;
+    file?: string;
+    selector?: string;
+    elementId?: string;
+    fixHint?: string;
+    snippet?: string;
+}
+export interface FileLintResult {
+    /** Path relative to the project directory. */
+    file: string;
+    /** True for files under `compositions/` — used to filter false positives. */
+    isSubComposition: boolean;
+    findings: LintFinding[];
+}
+export interface FileFixResult {
+    file: string;
+    /** Codes that were mechanically fixed. */
+    codes: string[];
+}
+export interface ProjectLintResult {
+    ok: boolean;
+    errorCount: number;
+    warningCount: number;
+    infoCount: number;
+    files: FileLintResult[];
+    fixed: FileFixResult[];
+}
+/** Producer's two findings that are inverse-rules for sub-compositions. */
+export declare const SUB_COMP_FALSE_POSITIVES: ReadonlySet<string>;
+/**
+ * Discover scene files in a project. Returns the root composition (or null
+ * if missing) plus every `*.html` file under `compositions/` recursively.
+ *
+ * Paths returned are absolute. The caller derives project-relative paths via
+ * `relative(projectDir, path)`.
+ */
+export declare function discoverSceneFiles(opts: {
+    projectDir: string;
+    rootRel?: string;
+}): Promise<{
+    root: string | null;
+    subs: string[];
+}>;
+/**
+ * Drop findings that producer's lint emits as inverse-rules for sub-comp
+ * files. Other findings pass through unchanged.
+ */
+export declare function filterSubCompFalsePositives(findings: LintFinding[], isSubComposition: boolean): LintFinding[];
+/**
+ * Apply mechanical `--fix` rewrites for known-safe finding codes. Returns the
+ * (possibly unchanged) HTML and the list of codes that were fixed at least
+ * once.
+ *
+ * MVP 1 only auto-fixes `timed_element_missing_clip_class` — adding the
+ * `clip` class to elements that already carry timing attributes.
+ *
+ * Other "registration"/"paused" fixes are intentionally NOT mechanical —
+ * they require structural reasoning (where to insert the `window.__timelines`
+ * block, how to convert an unpaused timeline) that goes beyond a regex.
+ * The lint output still surfaces them with `fixHint` for the agent or human
+ * to apply.
+ */
+export declare function applyMechanicalFixes(html: string, findings: LintFinding[]): {
+    html: string;
+    fixedCodes: string[];
+};
+export interface RunProjectLintOptions {
+    projectDir: string;
+    rootRel?: string;
+    /** Apply mechanical fixes and write files back. */
+    fix?: boolean;
+}
+/**
+ * Walk the project, lint every HTML file, optionally apply mechanical fixes,
+ * and return aggregated counts. Throws only on FS errors; lint errors are
+ * surfaced as findings, not exceptions.
+ */
+export declare function runProjectLint(opts: RunProjectLintOptions): Promise<ProjectLintResult>;
+/** True if `root` exists and is a regular file. Used by callers that want to
+ *  pre-validate before invoking `runProjectLint`. */
+export declare function rootExists(projectDir: string, rootRel?: string): Promise<boolean>;

package/dist/commands/_shared/scene-lint.test.d.ts

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

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

@@ -0,0 +1,147 @@
+/**
+ * @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
+ * project (via `hyperframes.json` + `meta.json` + `index.html`). Either
+ * toolchain can be run inside the directory.
+ *
+ * Pure functions; no I/O beyond `scaffoldSceneProject()` which orchestrates
+ * file writes. Everything else returns strings or JSON-serializable objects
+ * so it can be unit-tested without touching the filesystem.
+ */
+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";
+export declare function aspectToDims(aspect: SceneAspect): {
+    width: number;
+    height: number;
+};
+/** Shape of the Hyperframes project config file. */
+export interface HyperframesConfig {
+    $schema?: string;
+    registry?: string;
+    paths?: {
+        blocks?: string;
+        components?: string;
+        assets?: string;
+    };
+    [key: string]: unknown;
+}
+/** Shape of the Hyperframes meta file. */
+export interface HyperframesMeta {
+    id: string;
+    name: string;
+    createdAt: string;
+    [key: string]: unknown;
+}
+/** Shape of the new VibeFrame-specific project config. */
+export interface VibeProjectConfig {
+    name: string;
+    aspect: SceneAspect;
+    /** Default scene duration in seconds when none is inferred from narration. */
+    defaultSceneDuration: number;
+    /** Default providers per capability. `null` means "auto-resolve from env". */
+    providers: {
+        image: "openai" | "gemini" | "grok" | null;
+        tts: "elevenlabs" | "kokoro" | null;
+        transcribe: "whisper" | null;
+    };
+    /** Cost ceiling for `vibe remix` runs in this project. 0 disables. */
+    budget: {
+        maxUsd: number;
+    };
+    /** Scene composition renderer boundary. Hyperframes is the only supported engine today. */
+    composition: {
+        engine: "hyperframes";
+        entry: string;
+    };
+}
+/** Defaults for a fresh scene project. */
+export declare function defaultVibeProjectConfig(name: string): VibeProjectConfig;
+/** The Hyperframes config we write on init. Matches the format at
+ *  hyperframe-learn/my-first-video/hyperframes.json.
+ */
+export declare function buildHyperframesConfig(): HyperframesConfig;
+export declare function buildHyperframesMeta(name: string, now?: Date): HyperframesMeta;
+/**
+ * Merge an existing Hyperframes config with our defaults, preserving any
+ * user-authored keys and nested values. `vibe scene init` is idempotent:
+ * running it on a directory that already has `hyperframes.json` must never
+ * lose user config.
+ */
+export declare function mergeHyperframesConfig(existing: HyperframesConfig, defaults: HyperframesConfig): HyperframesConfig;
+/**
+ * Minimal valid Hyperframes root composition — empty (no sub-compositions
+ * yet). A later `vibe scene add` inserts `<div class="clip" ...>` children.
+ */
+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;
+/** 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. */
+export declare function buildProjectAgentsMd(name: string): string;
+/** Claude Code wrapper. Keeps scene guidance single-sourced in AGENTS.md. */
+export declare function buildProjectClaudeMd(name: string): string;
+/** Minimal .gitignore for a scene project. */
+export declare function buildSceneGitignore(): string;
+export interface ScaffoldOptions {
+    dir: string;
+    name?: string;
+    aspect?: SceneAspect;
+    duration?: number;
+    now?: Date;
+    /**
+     * Optional named visual style (e.g. "Swiss Pulse"). When provided,
+     * `DESIGN.md` is seeded with the style's palette / typography / motion
+     * rules instead of placeholders. Resolved via `getVisualStyle()`.
+     */
+    visualStyle?: VisualStyle;
+    /** Scaffold shape. Defaults to "full" for backward-compatible programmatic use. */
+    profile?: SceneScaffoldProfile;
+}
+export interface ScaffoldResult {
+    /** Files written (absolute paths). */
+    created: string[];
+    /** Files that already existed and were NOT overwritten. */
+    skipped: string[];
+    /** Files that were merge-updated (currently only hyperframes.json). */
+    merged: string[];
+    /** Files grouped by product purpose for human and JSON output. */
+    groups: SceneScaffoldGroups;
+}
+export interface SceneScaffoldGroups {
+    authoring: string[];
+    render: string[];
+    agent: string[];
+}
+export declare function isSceneScaffoldProfile(value: string): value is SceneScaffoldProfile;
+export declare function describeSceneScaffold(opts: {
+    dir: string;
+    profile?: SceneScaffoldProfile;
+}): SceneScaffoldGroups;
+/**
+ * Scaffold (or update) a scene project at `dir`. Idempotent: running twice is
+ * a no-op; running on an existing Hyperframes project merges `hyperframes.json`
+ * instead of overwriting.
+ */
+export declare function scaffoldSceneProject(opts: ScaffoldOptions): Promise<ScaffoldResult>;

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

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

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

@@ -0,0 +1,109 @@
+/**
+ * @module _shared/scene-render
+ *
+ * Render a VibeFrame scene project to MP4/WebM/MOV using the Hyperframes
+ * producer directly. Unlike the FFmpeg-bridge backend in
+ * `pipeline/renderers/hyperframes.ts` which has to convert a `TimelineState`
+ * into a temp Hyperframes project, scene projects already ARE Hyperframes
+ * projects — so we hand the producer the user's project dir and entry file
+ * verbatim.
+ *
+ * `executeSceneRender()` is decoupled from CLI flags so that the C6 agent
+ * tool and the C5 `--format scenes` pipeline can call it the same way. It
+ * returns a structured result instead of throwing or exiting.
+ */
+import { type RenderConfig } from "@hyperframes/producer";
+import { type SceneAspect } from "./scene-project.js";
+export type RenderFps = 24 | 30 | 60;
+export type RenderQuality = "draft" | "standard" | "high";
+export type RenderFormat = "mp4" | "webm" | "mov";
+export interface SceneRenderOptions {
+    /** Project directory (defaults to cwd). */
+    projectDir?: string;
+    /** Root composition file relative to projectDir (default: "index.html"). */
+    root?: string;
+    /** Render only one storyboard beat by synthesizing a temporary root. */
+    beatId?: string;
+    /** Output file. When relative, resolved against projectDir. Default:
+     *  `renders/<projectName>-<isoStamp>.<format>`. */
+    output?: string;
+    fps?: RenderFps;
+    quality?: RenderQuality;
+    format?: RenderFormat;
+    /** Hyperframes capture worker count. Default 1 (the existing backend's
+     *  default — auto-worker mode times out on small comps). */
+    workers?: number;
+    signal?: AbortSignal;
+    onProgress?: (pct: number, stage: string) => void;
+}
+export interface SceneRenderResult {
+    success: boolean;
+    kind?: "render";
+    beat?: string | null;
+    root?: string;
+    outputPath?: string;
+    durationMs?: number;
+    framesRendered?: number;
+    totalFrames?: number;
+    fps?: RenderFps;
+    quality?: RenderQuality;
+    format?: RenderFormat;
+    /** Number of `<audio>` elements muxed into the final file. 0 = silent project. */
+    audioCount?: number;
+    /** True when ffmpeg was invoked to overlay audio on the producer's video. */
+    audioMuxApplied?: boolean;
+    /** Non-fatal warning from the audio mux pass — caller may surface to the user. */
+    audioMuxWarning?: string;
+    reportPath?: string;
+    code?: string;
+    error?: string;
+    retryWith?: string[];
+}
+/** Map a quality preset to an x264 CRF (lower = higher quality). */
+export declare function qualityToCrf(quality?: RenderQuality): number;
+/**
+ * Compute the default output path for a render. Pure — does no I/O. Returns
+ * an absolute path under `<projectDir>/renders/`.
+ *
+ * `now` is injectable so tests get deterministic output.
+ */
+export declare function defaultOutputPath(opts: {
+    projectDir: string;
+    projectName?: string;
+    format?: RenderFormat;
+    beatId?: string;
+    now?: Date;
+}): string;
+/**
+ * Build the producer's `RenderConfig` from caller options. Pure — useful for
+ * unit tests that want to assert defaults without touching Chrome.
+ */
+export declare function buildRenderConfig(opts: {
+    fps?: RenderFps;
+    quality?: RenderQuality;
+    format?: RenderFormat;
+    workers?: number;
+    entryFile?: string;
+}): RenderConfig;
+/**
+ * Render a scene project. Mirrors the contract of the existing Hyperframes
+ * backend (preflight → execute → structured result), but skips the
+ * `TimelineState` → temp project conversion because the user's project is
+ * already a valid Hyperframes project.
+ */
+export declare function executeSceneRender(opts?: SceneRenderOptions): Promise<SceneRenderResult>;
+export interface BeatRenderRootResult {
+    success: boolean;
+    root: string;
+    durationSec?: number;
+    compositionPath?: string;
+    narrationPath?: string;
+    code?: "BEAT_NOT_FOUND" | "BEAT_RENDER_NOT_READY";
+    error?: string;
+    retryWith?: string[];
+}
+export declare function prepareBeatRenderRoot(opts: {
+    projectDir: string;
+    beatId: string;
+    aspect: SceneAspect;
+}): Promise<BeatRenderRootResult>;

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

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

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

@@ -0,0 +1,22 @@
+import { type FileFixResult, type FileLintResult } from "./scene-lint.js";
+import { type ReviewIssue, type ReviewStatus } from "./review-report.js";
+export interface SceneRepairOptions {
+    projectDir: string;
+    rootRel?: string;
+    dryRun?: boolean;
+    includeRoot?: boolean;
+}
+export interface SceneRepairResult {
+    schemaVersion: "1";
+    kind: "scene-repair";
+    project: string;
+    dryRun: boolean;
+    status: ReviewStatus;
+    score: number;
+    fixed: FileFixResult[];
+    wouldFix: FileFixResult[];
+    remainingIssues: ReviewIssue[];
+    files: FileLintResult[];
+    retryWith: string[];
+}
+export declare function executeSceneRepair(opts: SceneRepairOptions): Promise<SceneRepairResult>;

package/dist/commands/_shared/scene-repair.test.d.ts

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