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