/**
 * @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>;
