/**
 * @module _shared/compose-prompts
 *
 * Phase H2 — agentic compose primitive. Reads `STORYBOARD.md` + `DESIGN.md`
 * from a scene project and emits a structured plan for the host agent
 * (Claude Code, Cursor, Codex, Aider) to author per-beat HTML files
 * itself. **No LLM call from inside the CLI** — that's the point. The
 * CLI is the deterministic toolbelt; the host agent is the sole reasoner.
 *
 * Output shape:
 *
 *   {
 *     "projectDir": "<abs>",
 *     "designReference":     "DESIGN.md",
 *     "storyboardReference": "STORYBOARD.md",
 *     "skillReference":      "SKILL.md",        // present after `scene install-skill`
 *     "compositionsDir":     "compositions",
 *     "beats": [
 *       { "id": "hook", "outputPath": "compositions/scene-hook.html",
 *         "userPrompt": "...", "body": "...", "cues": {...}, "exists": false }
 *     ],
 *     "instructions": [...]
 *   }
 *
 * Pairs with H1 (`vibe scene install-skill`) — the host agent reads
 * `SKILL.md` for framework rules, `DESIGN.md` for visual identity, then
 * writes each `compositions/scene-<id>.html`. After authoring, runs
 * `vibe scene lint --fix` to verify and `vibe render` to produce MP4.
 *
 * The internal-LLM path (`vibe scene build`, PR #176) still works — it's
 * the batch / non-agent fallback. H3 will add mode dispatch so a single
 * entry point picks between agentic and batch depending on context.
 */
export interface ComposePromptsBeat {
    /** Stable beat id from `parseStoryboard().deriveBeatId()`. */
    id: string;
    /** Original `## …` heading line (without the `## ` prefix). */
    heading: string;
    /** Path the agent should write the composition to (relative to projectDir). */
    outputPath: string;
    /** Storyboard beat duration in seconds (the MINIMUM — see finalDurationSec). */
    duration?: number;
    /**
     * Narration-synced FINAL beat duration in seconds — the storyboard duration
     * stretched to cover generated narration audio. Use THIS for
     * `data-duration` and timeline anchors when present; using the storyboard
     * `duration` produces scenes that end early and render black tails.
     */
    finalDurationSec?: number;
    /** Per-beat YAML cues parsed from the leading code block of the body. */
    cues?: Record<string, unknown>;
    /** Beat body markdown (with the leading `\`\`\`yaml` cue block stripped). */
    body: string;
    /**
     * Pre-built user prompt — the same shape `composeBeatHtml` would send to
     * Claude / OpenAI / Gemini. The host agent consumes this directly so the
     * agentic and batch paths produce equivalent HTML.
     */
    userPrompt: string;
    /** True when `compositions/scene-<id>.html` already exists on disk. */
    exists: boolean;
}
export interface ComposePromptsResult {
    success: boolean;
    /** Absolute project directory. */
    projectDir: string;
    /** Project-root-relative path to DESIGN.md (always "DESIGN.md"). */
    designReference: string;
    /** Project-root-relative path to STORYBOARD.md (always "STORYBOARD.md"). */
    storyboardReference: string;
    /**
     * Project-root-relative path to the universal Hyperframes SKILL.md.
     * `null` when the skill hasn't been installed — the
     * `warnings` field then carries an actionable hint.
     */
    skillReference: string | null;
    /** Project-root-relative compositions directory (always "compositions"). */
    compositionsDir: string;
    /** Per-beat plan, ordered by source document position. */
    beats: ComposePromptsBeat[];
    /** Step-by-step instructions for the host agent. */
    instructions: string[];
    /** Hyperframes bundle version — informational; ties cache keys back to the internal-LLM path. */
    bundleVersion: string;
    /** Non-fatal hints surfaced to the agent (e.g. missing SKILL.md). */
    warnings: string[];
    /** Set when {@link success} is false. */
    error?: string;
}
export interface ComposePromptsOptions {
    /** Project directory containing STORYBOARD.md / DESIGN.md. */
    projectDir: string;
    /**
     * Restrict output to a single beat id. When unset, every beat in the
     * storyboard is emitted.
     */
    beatId?: string;
}
/**
 * Build the agent compose plan from a scene project on disk. Pure I/O —
 * no network, no LLM, no mutation. Caller (CLI handler / manifest tool /
 * MCP surface) decides how to surface the result.
 */
export declare function getComposePrompts(opts: ComposePromptsOptions): Promise<ComposePromptsResult>;
