video-editing 1.3.1 → 3.0.0

package/dist/index.d.ts

@@ -1,462 +1,5 @@
 import { z } from 'zod';
 
-type TokenType = "word" | "spacing" | "audio_event";
-/** A single ElevenLabs Scribe token (word-level, verbatim). */
-interface ScribeWord {
-    type?: TokenType;
-    text?: string;
-    start: number | null;
-    end: number | null;
-    speaker_id?: string | null;
-    [extra: string]: unknown;
-}
-interface ScribeTranscript {
-    language_code?: string;
-    text?: string;
-    words: ScribeWord[];
-    [extra: string]: unknown;
-}
-/** One KEEP segment in SOURCE seconds. Gaps between ranges are the cuts. */
-interface EdlRange {
-    source: string;
-    start: number;
-    end: number;
-    beat?: string;
-    quote?: string;
-    reason?: string;
-    /** Optional per-range grade override (preset name | raw ffmpeg filter | "auto"). */
-    grade?: string;
-}
-interface EdlOverlay {
-    [k: string]: unknown;
-}
-interface Edl {
-    version: number;
-    sources: Record<string, string>;
-    /** "none" | preset name | raw ffmpeg filter | "auto" */
-    grade: string;
-    ranges: EdlRange[];
-    overlays: EdlOverlay[];
-    total_duration_s: number;
-    /** Optional explicit subtitle path. */
-    subtitles?: string;
-    /** Set once the amplitude silence-trim pass has rewritten the ranges. */
-    desilenced?: boolean;
-}
-interface SourceJson {
-    created: string;
-    source: string;
-    stem: string;
-    job_dir: string;
-    duration_s: number;
-    stored_width: number;
-    stored_height: number;
-    display_width: number;
-    display_height: number;
-    rotation: number;
-    probe: FfprobeResult;
-}
-interface FfprobeStream {
-    index?: number;
-    codec_type?: string;
-    codec_name?: string;
-    width?: number;
-    height?: number;
-    r_frame_rate?: string;
-    avg_frame_rate?: string;
-    duration?: string;
-    color_transfer?: string;
-    side_data_list?: Array<Record<string, unknown>>;
-    tags?: Record<string, string>;
-    [extra: string]: unknown;
-}
-interface FfprobeResult {
-    streams?: FfprobeStream[];
-    format?: {
-        duration?: string;
-        size?: string;
-        format_name?: string;
-        [k: string]: unknown;
-    };
-    [extra: string]: unknown;
-}
-interface CutBoundary {
-    index: number;
-    output_time_s: number;
-    removed_source_gap_s: number;
-    source_before: number;
-    source_after: number;
-}
-type RenderMode = "preview" | "draft" | "final";
-interface ReviewIssue {
-    where?: string;
-    range_index?: number | null;
-    severity?: "error" | "warning" | "info";
-    problem?: string;
-    fix?: string;
-}
-interface ReviewJson {
-    verdict?: "clean" | "needs-fixes";
-    issues?: ReviewIssue[];
-    confidence?: string;
-}
-interface Warning {
-    id: string;
-    severity: string;
-    output_time_s: number;
-    range_index: number | null | undefined;
-    problem: string;
-    fix: string;
-}
-interface VerifyJoinFinding {
-    index: number;
-    output_time_s: number;
-    duplicated_phrase?: string;
-    gap_s?: number;
-    severity: "error" | "warning" | "info";
-    detail: string;
-}
-interface VerifyResult {
-    verdict: "clean" | "needs-fixes";
-    mode: "full" | "joins";
-    joins: VerifyJoinFinding[];
-    confidence: string;
-}
-
-interface RunResult {
-    code: number;
-    stdout: string;
-    stderr: string;
-}
-interface RunOptions {
-    /** Capture stdout/stderr into strings (default: inherit to the terminal). */
-    capture?: boolean;
-    /** Write merged stdout+stderr to this file path. */
-    stdoutPath?: string;
-    cwd?: string;
-    /** Throw on non-zero exit (default true). */
-    check?: boolean;
-    /** Echo the command (default true) — mirrors the Python "+ <cmd>" trace. */
-    echo?: boolean;
-}
-declare function shown(cmd: string[]): string;
-declare class CommandError extends Error {
-    code: number;
-    result: RunResult;
-    constructor(message: string, code: number, result: RunResult);
-}
-/** Run a command, streaming or capturing output. Async. */
-declare function run(cmd: string[], opts?: RunOptions): Promise<RunResult>;
-/** Synchronous run (used by a few hot paths / parity tooling). */
-declare function runSync(cmd: string[], opts?: {
-    check?: boolean;
-    echo?: boolean;
-}): RunResult;
-/** ffprobe -of json, parsed. Mirrors cli.py ffprobe(). */
-declare function ffprobe(path: string): Promise<FfprobeResult>;
-declare function videoStream(probe: FfprobeResult): FfprobeStream;
-declare function mediaDuration(path: string): Promise<number>;
-/** Assert ffmpeg + ffprobe are on PATH. */
-declare function requireFfmpeg(): void;
-
-declare function configDir(): string;
-declare function configEnvPath(): string;
-interface KeyOptions {
-    /** explicit --api-key value (highest precedence after env var miss) */
-    apiKey?: string;
-    /** extra .env path to check (e.g. for tests) */
-    envPath?: string;
-}
-/** Resolve the ElevenLabs API key or throw with a clear message. */
-declare function loadApiKey(opts?: KeyOptions): string;
-
-declare function slugify(value: string): string;
-declare function isoNow(): string;
-/** Round to `ndigits` using round-half-to-even (Python's round()). */
-declare function pyRound(x: number, ndigits?: number): number;
-/** Format like Python f"{x:.<prec>f}" (fixed-point, round-half-even-ish). */
-declare function pyFixed(x: number, prec: number): string;
-/** Python f"{x:0<width>.<prec>f}" — zero-padded fixed width incl. sign/dot. */
-declare function pyFixedPad(x: number, width: number, prec: number): string;
-/** Python f"{x:<width>.<prec>f}" — space-padded (right-aligned). */
-declare function pySpacePad(x: number, width: number, prec: number): string;
-
-declare function rotationDegrees(stream: FfprobeStream): number;
-/** Returns [displayWidth, displayHeight, rotation] accounting for rotation flags. */
-declare function displayedDimensions(stream: FfprobeStream): [number, number, number];
-
-declare const DEFAULT_EDIT_ROOT: string;
-declare const VIDEO_EXTS: Set<string>;
-declare function defaultJobDir(source: string): string;
-declare function transcriptPath(jobDir: string, stem: string): string;
-declare function initJob(source: string, jobDir: string | null, opts?: {
-    force?: boolean;
-}): Promise<string>;
-declare function loadJob(jobDir: string): SourceJson;
-declare function sourceFromJob(jobDir: string): string;
-interface ResolvedJob {
-    jobDir: string;
-    source: string;
-    stem: string;
-}
-/** Resolve a job from a --source or --job-dir argument. */
-declare function resolveJob(args: {
-    source?: string;
-    jobDir?: string;
-}, opts?: {
-    forceJob?: boolean;
-}): Promise<ResolvedJob>;
-
-declare function ensureVerticalMaster(jobDir: string, source: string, opts?: {
-    force?: boolean;
-}): Promise<string>;
-
-interface TranscribeOptions {
-    editDir: string;
-    language?: string;
-    numSpeakers?: number;
-    noHeal?: boolean;
-    force?: boolean;
-    apiKey?: string;
-    verbose?: boolean;
-}
-/**
- * Transcribe a single video. Returns the path to the transcript JSON.
- * Cached: returns the existing path immediately if the transcript already
- * exists (unless `force`). Mirrors transcribe_one().
- */
-declare function transcribeOne(video: string, opts: TranscribeOptions): Promise<string>;
-
-interface BatchOptions {
-    workers?: number;
-    language?: string;
-    numSpeakers?: number;
-    editDir?: string;
-    apiKey?: string;
-}
-interface BatchResult {
-    videos: string[];
-    cached: string[];
-    transcribed: string[];
-    errors: Array<{
-        video: string;
-        message: string;
-    }>;
-}
-/**
- * Batch transcription. Returns a summary of which files were cached,
- * transcribed, and which failed. Mirrors transcribe_batch.main().
- */
-declare function transcribeBatch(videosDir: string, opts?: BatchOptions): Promise<BatchResult>;
-
-/**
- * Screen a single transcript and return the report text exactly as
- * flag_takes.py prints it to stdout (this is what gets written to flags.txt).
- */
-declare function screenTakes(transcriptPath: string, opts?: {
-    offset?: number;
-    longToken?: number;
-    gap?: number;
-}): string;
-
-interface PackTranscriptsOptions {
-    silenceThreshold?: number;
-    output?: string;
-}
-declare function packTranscripts(editDir: string, opts?: PackTranscriptsOptions): {
-    path: string;
-    content: string;
-};
-
-declare const PRESETS: Record<string, string>;
-/** Return the ffmpeg filter string for a preset name. Empty string for 'none'.
- *  Throws (like Python's KeyError) for unknown presets. */
-declare function getPreset(name: string): string;
-interface GradeStats {
-    y_mean: number;
-    y_range: number;
-    sat_mean: number;
-}
-/** Pure decision logic — mirrors auto_grade_for_clip's decision rules exactly.
- *  Bounded to ±8% on any axis, NO color shift. Unit-testable without ffmpeg. */
-declare function decideGradeFilter(stats: GradeStats): string;
-/** Analyze a clip and return the computed auto-grade `eq=...` filter string
- *  (or "" for passthrough). Bounded to ±8% on any axis, NO color shift.
- *
- *  Probes the clip duration via ffprobe (matching Python's default behavior),
- *  samples frames via ffmpeg signalstats, then applies the bounded decision
- *  rules. Equivalent to Python's auto_grade_for_clip(video)[0]. */
-declare function autoGradeForClip(input: string): Promise<string>;
-
-interface RenderOptions {
-    preview?: boolean;
-    draft?: boolean;
-    buildSubtitles?: boolean;
-    noSubtitles?: boolean;
-    noLoudnorm?: boolean;
-}
-/** Render a video from an EDL. Mirrors render.py main(). */
-declare function render(edlPath: string, output: string, opts?: RenderOptions): Promise<void>;
-
-/**
- * Compute a windowed-RMS envelope of length `samples` from raw Int16 PCM.
- *
- * Pure port of the math in Python's compute_envelope() (after WAV parsing):
- *   - convert to float32 / 32768
- *   - window = max(1, floor(n / samples))
- *   - reshape to (-1, window) over the usable prefix, RMS per window
- *   - pad with zeros / truncate to `samples`
- *   - normalize by max so values land in [0, 1]
- *
- * Returns all-zeros of length `samples` for empty input.
- */
-declare function computeEnvelope(pcm: Int16Array, samples: number): number[];
-interface TimelineViewOptions {
-    /** Number of frames in the filmstrip (default 10). */
-    nFrames?: number;
-    /** Path to a transcript.json for word labels + silence shading. */
-    transcript?: string;
-}
-/**
- * Render a filmstrip + waveform composite PNG for [start, end] of `video` to
- * `output`. Faithful port of render_timeline() in timeline_view.py.
- *
- * The caller must pass `end < duration`; we clamp `end` to the media duration
- * internally (same defensive behavior as the Python EOF guard) to avoid the
- * end-window-at-EOF failure.
- */
-declare function timelineView(video: string, start: number, end: number, output: string, opts?: TimelineViewOptions): Promise<void>;
-
-interface VerifyOptions {
-    full?: boolean;
-    windowS?: number;
-    gapThresholdS?: number;
-    apiKey?: string;
-}
-interface TimedWord {
-    text: string;
-    norm: string;
-    start: number;
-    end: number;
-}
-interface DupSpan {
-    /** The full matched text (abandoned take + keeper). */
-    text: string;
-    /** The repeated n-gram length in tokens. 2 = a bare two-word repeat (often
-     *  emphasis / a spelled acronym like "WW" → "דבל יו דבל יו" / a spoken number),
-     *  >= 3 = a restarted clause (the strong retake fingerprint). */
-    n: number;
-}
-/**
- * ALL near-adjacent repeated phrases (the retake fingerprint), left to right.
- * Reports the longest match at each position and skips past it, so a stumbly
- * source with several within-window stutters surfaces every one (not just the
- * first). Intentional rhetorical repeats ("X? Y X?") also match — the editor
- * adjudicates those. Each span carries its n-gram length so callers can weight
- * a 3+-word clause restart (almost always a real retake) above a bare 2-word
- * repeat (frequently a spelled acronym / number / emphasis, not a retake).
- */
-declare function duplicatedSpans(words: TimedWord[]): DupSpan[];
-/** ALL near-adjacent repeated phrases as plain text (back-compat). */
-declare function duplicatedPhrases(words: TimedWord[]): string[];
-/** First near-adjacent duplicate (back-compat helper). */
-declare function duplicatedPhrase(words: TimedWord[]): string | null;
-/** Largest inter-word gap that straddles `joinOffset` (window-relative seconds). */
-declare function straddlingGap(words: TimedWord[], joinOffset: number): number;
-declare function verify(jobDir: string, opts?: VerifyOptions): Promise<VerifyResult>;
-
-interface SilenceInterval {
-    start: number;
-    end: number;
-}
-interface DesilenceOptions {
-    /** Silence threshold in dB (ffmpeg silencedetect `noise`). Default -39. */
-    noiseDb: number;
-    /** Minimum silence length (s) to act on — also silencedetect `d`. Default 0.30. */
-    minSilence: number;
-    /** Total air (s) to leave where an internal silence is cut. Default 0.13. */
-    targetGap: number;
-    /** Air kept BEFORE speech resumes at a cut / leading edge. Default 0.05. */
-    leadKeep: number;
-    /** Air kept AFTER speech ends at a cut / trailing edge. Default 0.08. */
-    trailKeep: number;
-    /** Drop any resulting sub-range shorter than this (s). Default 0.10. */
-    minSegment: number;
-}
-declare const DEFAULT_DESILENCE: DesilenceOptions;
-/** ffmpeg argv for an amplitude silence scan. No video, null muxer; the report
- *  lands on stderr. Pure (no execution). */
-declare function silenceDetectArgs(source: string, noiseDb: number, minSilenceS: number): string[];
-/** Parse `silence_start:` / `silence_end:` pairs out of ffmpeg stderr.
- *  A dangling silence_start (silence runs to EOF) is closed at `sourceDurationS`
- *  when provided (>0), otherwise dropped. */
-declare function parseSilenceDetect(stderr: string, sourceDurationS?: number): SilenceInterval[];
-/** Tighten ONE keep-range against the detected silences: excise internal
- *  silences >= minSilence (leaving trailKeep + leadKeep of air) and trim silent
- *  leading/trailing edges. Returns 1..N sub-ranges, all inside [start,end],
- *  inheriting source/grade/beat/quote. Pure. */
-declare function tightenRange(range: EdlRange, silences: SilenceInterval[], opts?: DesilenceOptions, words?: SilenceInterval[]): EdlRange[];
-/** Tighten every range against per-source silence maps, protecting intra-word
- *  splits with per-source word tokens. Pure. */
-declare function tightenRanges(ranges: EdlRange[], silencesBySource: Record<string, SilenceInterval[]>, opts?: DesilenceOptions, wordsBySource?: Record<string, SilenceInterval[]>): EdlRange[];
-/** Load word-token spans per EDL source from the job's transcripts/ dir. Tries
- *  transcripts/<sourceName>.json, then falls back to the lone transcript when a
- *  single-source job names its transcript by stem (the common case). */
-declare function loadWordsBySource(edl: Edl, editDir: string): Record<string, SilenceInterval[]>;
-/** Run silencedetect on a source and return the silence intervals. */
-declare function detectSilences(source: string, noiseDb: number, minSilenceS: number, sourceDurationS: number): Promise<SilenceInterval[]>;
-interface DesilenceStats {
-    rangesBefore: number;
-    rangesAfter: number;
-    durationBefore: number;
-    durationAfter: number;
-    removedS: number;
-}
-/** Detect silences for every source referenced by the EDL, tighten all ranges,
- *  and return a new EDL (with updated total_duration_s + a `desilenced` marker)
- *  plus stats. Does NOT write anything. */
-declare function desilenceEdl(edl: Edl, editDir: string, opts?: DesilenceOptions): Promise<{
-    edl: Edl;
-    stats: DesilenceStats;
-}>;
-
-declare function loadWords(tpath: string, opts?: {
-    includeEvents?: boolean;
-}): ScribeWord[];
-declare function writeWordDump(tpath: string, outPath: string, gapThreshold?: number): void;
-declare function writeCoverage(jobDir: string, source: string, tpath: string): Promise<string>;
-declare function writeTranscriptArtifacts(jobDir: string, source: string, tpath: string): Promise<void>;
-declare function ensureTranscribed(jobDir: string, source: string, stem: string, opts?: {
-    language?: string;
-    numSpeakers?: number;
-    noHeal?: boolean;
-    force?: boolean;
-    apiKey?: string;
-}): Promise<string>;
-declare function edlPath(jobDir: string): string;
-declare function readEdl(jobDir: string): Edl | null;
-declare function cutBoundaries(ranges: Edl["ranges"]): CutBoundary[];
-declare function writeBoundaries(jobDir: string): string | null;
-declare function generateQcImages(jobDir: string, opts?: {
-    preview?: string;
-    maxImages?: number;
-}): Promise<string | null>;
-declare function writeWarningsFromReview(jobDir: string): string;
-declare function artifactPaths(jobDir: string, stem: string): Record<string, string>;
-declare function writeAgentManifest(jobDir: string, source: string, stem: string, mode: string): string;
-declare function statusPayload(jobDir: string): Promise<Record<string, unknown>>;
-
-declare function learnedEditingGuardrails(jobDir: string, stem: string): string;
-declare function agentizePrompt(text: string, jobDir: string, stem: string): string;
-declare function writeVideoEditingPrompt(jobDir: string, stem: string, templateName: string, outName: string): string;
-interface SilencePromptOptions {
-    minGap: number;
-    targetGap: number;
-    leadPad: number;
-    trailPad: number;
-}
-declare function writeSilencePrompt(jobDir: string, stem: string, opts: SilencePromptOptions): string;
-
 /** Who put an item into the timeline, and in which authoring round. Required on
  *  every item; defaults to {round:null, changeId:null, actor:"agent"}. */
 declare const provenanceSchema: z.ZodDefault<z.ZodObject<{
@@ -523,14 +66,14 @@ declare const sourceAnchorSchema: z.ZodObject<{
     end: z.ZodNumber;
 }, "strict", z.ZodTypeAny, {
     type: "source";
+    source: string;
     start: number;
     end: number;
-    source: string;
 }, {
     type: "source";
+    source: string;
     start: number;
     end: number;
-    source: string;
 }>;
 /** Symbolic OUTPUT-time anchor. Numeric output seconds are deliberately not
  *  representable: output time shifts under desilence/re-cuts, so authored docs
@@ -604,14 +147,14 @@ declare const anchorSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     end: z.ZodNumber;
 }, "strict", z.ZodTypeAny, {
     type: "source";
+    source: string;
     start: number;
     end: number;
-    source: string;
 }, {
     type: "source";
+    source: string;
     start: number;
     end: number;
-    source: string;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"output">;
     at: z.ZodUnion<[z.ZodEnum<["start", "end", "full"]>, z.ZodObject<{
@@ -655,6 +198,19 @@ declare const timelineSourceSchema: z.ZodObject<{
     durationS?: number | undefined;
     transcriptHash?: string | undefined;
 }>;
+/** Declarative color grade for the composition render path: a named preset
+ *  with an optional 0..1 intensity. (Distinct from the legacy ffmpeg grade
+ *  string, which settings.grade also still accepts.) */
+declare const gradeSettingSchema: z.ZodObject<{
+    preset: z.ZodString;
+    intensity: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    preset: string;
+    intensity?: number | undefined;
+}, {
+    preset: string;
+    intensity?: number | undefined;
+}>;
 declare const settingsSchema: z.ZodDefault<z.ZodObject<{
     canvas: z.ZodDefault<z.ZodObject<{
         w: z.ZodNumber;
@@ -763,9 +319,9 @@ declare const cutRangeSchema: z.ZodObject<{
         actor?: "agent" | "user" | undefined;
     }>>;
 }, "strict", z.ZodTypeAny, {
+    source: string;
     start: number;
     end: number;
-    source: string;
     id: string;
     provenance: {
         round: number | null;
@@ -777,9 +333,9 @@ declare const cutRangeSchema: z.ZodObject<{
     quote?: string | undefined;
     reason?: string | undefined;
 }, {
+    source: string;
     start: number;
     end: number;
-    source: string;
     id: string;
     grade?: string | undefined;
     beat?: string | undefined;
@@ -853,6 +409,12 @@ declare const captionOverrideSchema: z.ZodObject<{
         actor?: "agent" | "user" | undefined;
     }>>;
 }, "strict", z.ZodTypeAny, {
+    id: string;
+    provenance: {
+        round: number | null;
+        changeId: string | null;
+        actor: "agent" | "user";
+    };
     anchor: {
         type: "words";
         source: string;
@@ -864,17 +426,12 @@ declare const captionOverrideSchema: z.ZodObject<{
         } | undefined;
         edge?: "start" | "end" | undefined;
     };
-    id: string;
-    provenance: {
-        round: number | null;
-        changeId: string | null;
-        actor: "agent" | "user";
-    };
     op: "replace-text" | "hide" | "break-line" | "style";
     text?: string | undefined;
     color?: string | undefined;
     emphasis?: "pop" | "highlight" | undefined;
 }, {
+    id: string;
     anchor: {
         type: "words";
         source: string;
@@ -886,17 +443,76 @@ declare const captionOverrideSchema: z.ZodObject<{
         } | undefined;
         edge?: "start" | "end" | undefined;
     };
-    id: string;
     op: "replace-text" | "hide" | "break-line" | "style";
-    text?: string | undefined;
     provenance?: {
         round?: number | null | undefined;
         changeId?: string | null | undefined;
         actor?: "agent" | "user" | undefined;
     } | undefined;
+    text?: string | undefined;
     color?: string | undefined;
     emphasis?: "pop" | "highlight" | undefined;
 }>;
+/** Caption presets:
+ *  - "grouped" (default): phrases bounded by long inter-word gaps
+ *    (style.gapBreakS), cut joins and sentence-ending punctuation, packed
+ *    into balanced cues of up to style.maxWords words (5 words → 3+2, never
+ *    4+1; see deriveCaptionCues in compile.ts).
+ *  - "opus-karaoke": word-by-word (one cue per word), explicit opt-in. */
+declare const captionPresetSchema: z.ZodEnum<["grouped", "opus-karaoke"]>;
+/** Timing/grouping knobs. Renderer-specific style keys pass through untouched;
+ *  defaults are applied at compile (see CAPTION_STYLE_DEFAULTS) so authored
+ *  timeline.json files stay minimal. */
+declare const captionStyleSchema: z.ZodObject<{
+    /** Max words per grouped cue (preset "grouped" only). */
+    maxWords: z.ZodOptional<z.ZodNumber>;
+    /** Inter-word gap (seconds) that ends a phrase — a hard cue boundary
+     *  (preset "grouped" only). */
+    gapBreakS: z.ZodOptional<z.ZodNumber>;
+    /** Seconds each cue's display start is shifted EARLIER (clamped to the
+     *  previous cue's end / the segment's outStart). */
+    leadS: z.ZodOptional<z.ZodNumber>;
+    /** Max seconds a cue is held past its last word to bridge the gap to the
+     *  next cue (never past the segment's outEnd). */
+    holdS: z.ZodOptional<z.ZodNumber>;
+    /** Per-word highlight sweep within grouped cues (karaoke-style). */
+    karaoke: z.ZodOptional<z.ZodBoolean>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    /** Max words per grouped cue (preset "grouped" only). */
+    maxWords: z.ZodOptional<z.ZodNumber>;
+    /** Inter-word gap (seconds) that ends a phrase — a hard cue boundary
+     *  (preset "grouped" only). */
+    gapBreakS: z.ZodOptional<z.ZodNumber>;
+    /** Seconds each cue's display start is shifted EARLIER (clamped to the
+     *  previous cue's end / the segment's outStart). */
+    leadS: z.ZodOptional<z.ZodNumber>;
+    /** Max seconds a cue is held past its last word to bridge the gap to the
+     *  next cue (never past the segment's outEnd). */
+    holdS: z.ZodOptional<z.ZodNumber>;
+    /** Per-word highlight sweep within grouped cues (karaoke-style). */
+    karaoke: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    /** Max words per grouped cue (preset "grouped" only). */
+    maxWords: z.ZodOptional<z.ZodNumber>;
+    /** Inter-word gap (seconds) that ends a phrase — a hard cue boundary
+     *  (preset "grouped" only). */
+    gapBreakS: z.ZodOptional<z.ZodNumber>;
+    /** Seconds each cue's display start is shifted EARLIER (clamped to the
+     *  previous cue's end / the segment's outStart). */
+    leadS: z.ZodOptional<z.ZodNumber>;
+    /** Max seconds a cue is held past its last word to bridge the gap to the
+     *  next cue (never past the segment's outEnd). */
+    holdS: z.ZodOptional<z.ZodNumber>;
+    /** Per-word highlight sweep within grouped cues (karaoke-style). */
+    karaoke: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">>;
+/** Compile-time defaults for the caption style knobs. */
+declare const CAPTION_STYLE_DEFAULTS: {
+    readonly maxWords: 4;
+    readonly gapBreakS: 0.6;
+    readonly leadS: 0.08;
+    readonly holdS: 0.9;
+};
 declare const zoomSchema: z.ZodObject<{
     id: z.ZodString;
     anchor: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
@@ -945,14 +561,14 @@ declare const zoomSchema: z.ZodObject<{
         end: z.ZodNumber;
     }, "strict", z.ZodTypeAny, {
         type: "source";
+        source: string;
         start: number;
         end: number;
-        source: string;
     }, {
         type: "source";
+        source: string;
         start: number;
         end: number;
-        source: string;
     }>, z.ZodObject<{
         type: z.ZodLiteral<"output">;
         at: z.ZodUnion<[z.ZodEnum<["start", "end", "full"]>, z.ZodObject<{
@@ -1055,6 +671,12 @@ declare const zoomSchema: z.ZodObject<{
         actor?: "agent" | "user" | undefined;
     }>>;
 }, "strict", z.ZodTypeAny, {
+    id: string;
+    provenance: {
+        round: number | null;
+        changeId: string | null;
+        actor: "agent" | "user";
+    };
     anchor: {
         type: "words";
         source: string;
@@ -1067,9 +689,9 @@ declare const zoomSchema: z.ZodObject<{
         edge?: "start" | "end" | undefined;
     } | {
         type: "source";
+        source: string;
         start: number;
         end: number;
-        source: string;
     } | {
         type: "output";
         at: "start" | "end" | "full" | {
@@ -1077,13 +699,7 @@ declare const zoomSchema: z.ZodObject<{
         };
         durationS?: number | undefined;
     };
-    id: string;
-    provenance: {
-        round: number | null;
-        changeId: string | null;
-        actor: "agent" | "user";
-    };
-    onCut: "error" | "drop" | "clip";
+    onCut: "clip" | "drop" | "error";
     rect: {
         w: number;
         h: number;
@@ -1105,6 +721,7 @@ declare const zoomSchema: z.ZodObject<{
         scale?: number | undefined;
     } | undefined;
 }, {
+    id: string;
     anchor: {
         type: "words";
         source: string;
@@ -1117,9 +734,9 @@ declare const zoomSchema: z.ZodObject<{
         edge?: "start" | "end" | undefined;
     } | {
         type: "source";
+        source: string;
         start: number;
         end: number;
-        source: string;
     } | {
         type: "output";
         at: "start" | "end" | "full" | {
@@ -1127,7 +744,6 @@ declare const zoomSchema: z.ZodObject<{
         };
         durationS?: number | undefined;
     };
-    id: string;
     rect: {
         w: number;
         h: number;
@@ -1140,7 +756,7 @@ declare const zoomSchema: z.ZodObject<{
         changeId?: string | null | undefined;
         actor?: "agent" | "user" | undefined;
     } | undefined;
-    onCut?: "error" | "drop" | "clip" | undefined;
+    onCut?: "clip" | "drop" | "error" | undefined;
     to?: {
         rect?: {
             w: number;
@@ -1161,11 +777,11 @@ declare const overlayFxSchema: z.ZodObject<{
     preset: z.ZodEnum<["fade", "pop", "slide-up", "slide-down", "scale-in"]>;
     durationS: z.ZodNumber;
 }, "strict", z.ZodTypeAny, {
-    preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
     durationS: number;
-}, {
     preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
+}, {
     durationS: number;
+    preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
 }>;
 declare const overlaySchema: z.ZodObject<{
     id: z.ZodString;
@@ -1216,14 +832,14 @@ declare const overlaySchema: z.ZodObject<{
         end: z.ZodNumber;
     }, "strict", z.ZodTypeAny, {
         type: "source";
+        source: string;
         start: number;
         end: number;
-        source: string;
     }, {
         type: "source";
+        source: string;
         start: number;
         end: number;
-        source: string;
     }>, z.ZodObject<{
         type: z.ZodLiteral<"output">;
         at: z.ZodUnion<[z.ZodEnum<["start", "end", "full"]>, z.ZodObject<{
@@ -1256,12 +872,12 @@ declare const overlaySchema: z.ZodObject<{
     }, "strict", z.ZodTypeAny, {
         x: number;
         y: number;
-        align: "center" | "left" | "right";
+        align: "left" | "center" | "right";
         safeArea: boolean;
     }, {
         x?: number | undefined;
         y?: number | undefined;
-        align?: "center" | "left" | "right" | undefined;
+        align?: "left" | "center" | "right" | undefined;
         safeArea?: boolean | undefined;
     }>>;
     text: z.ZodOptional<z.ZodString>;
@@ -1285,21 +901,21 @@ declare const overlaySchema: z.ZodObject<{
         preset: z.ZodEnum<["fade", "pop", "slide-up", "slide-down", "scale-in"]>;
         durationS: z.ZodNumber;
     }, "strict", z.ZodTypeAny, {
-        preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
         durationS: number;
-    }, {
         preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
+    }, {
         durationS: number;
+        preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
     }>>;
     exit: z.ZodOptional<z.ZodObject<{
         preset: z.ZodEnum<["fade", "pop", "slide-up", "slide-down", "scale-in"]>;
         durationS: z.ZodNumber;
     }, "strict", z.ZodTypeAny, {
-        preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
         durationS: number;
-    }, {
         preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
+    }, {
         durationS: number;
+        preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
     }>>;
     /** Size as canvas fractions (w of canvas width, h of canvas height). */
     size: z.ZodOptional<z.ZodObject<{
@@ -1328,6 +944,12 @@ declare const overlaySchema: z.ZodObject<{
         actor?: "agent" | "user" | undefined;
     }>>;
 }, "strict", z.ZodTypeAny, {
+    id: string;
+    provenance: {
+        round: number | null;
+        changeId: string | null;
+        actor: "agent" | "user";
+    };
     anchor: {
         type: "words";
         source: string;
@@ -1340,9 +962,9 @@ declare const overlaySchema: z.ZodObject<{
         edge?: "start" | "end" | undefined;
     } | {
         type: "source";
+        source: string;
         start: number;
         end: number;
-        source: string;
     } | {
         type: "output";
         at: "start" | "end" | "full" | {
@@ -1350,44 +972,39 @@ declare const overlaySchema: z.ZodObject<{
         };
         durationS?: number | undefined;
     };
-    kind: "text" | "title-card" | "image" | "sticker";
-    id: string;
-    provenance: {
-        round: number | null;
-        changeId: string | null;
-        actor: "agent" | "user";
-    };
     style: {
         preset?: string | undefined;
     } & {
         [k: string]: unknown;
     };
-    onCut: "error" | "drop" | "clip";
+    onCut: "clip" | "drop" | "error";
+    kind: "text" | "title-card" | "image" | "sticker";
     layout: {
         x: number;
         y: number;
-        align: "center" | "left" | "right";
+        align: "left" | "center" | "right";
         safeArea: boolean;
     };
-    text?: string | undefined;
-    size?: {
-        w?: number | undefined;
-        h?: number | undefined;
-    } | undefined;
     durationS?: number | undefined;
+    text?: string | undefined;
     asset?: {
         ref: string;
     } | undefined;
     enter?: {
-        preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
         durationS: number;
+        preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
     } | undefined;
     exit?: {
-        preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
         durationS: number;
+        preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
+    } | undefined;
+    size?: {
+        w?: number | undefined;
+        h?: number | undefined;
     } | undefined;
     z?: number | undefined;
 }, {
+    id: string;
     anchor: {
         type: "words";
         source: string;
@@ -1400,9 +1017,9 @@ declare const overlaySchema: z.ZodObject<{
         edge?: "start" | "end" | undefined;
     } | {
         type: "source";
+        source: string;
         start: number;
         end: number;
-        source: string;
     } | {
         type: "output";
         at: "start" | "end" | "full" | {
@@ -1411,12 +1028,6 @@ declare const overlaySchema: z.ZodObject<{
         durationS?: number | undefined;
     };
     kind: "text" | "title-card" | "image" | "sticker";
-    id: string;
-    text?: string | undefined;
-    size?: {
-        w?: number | undefined;
-        h?: number | undefined;
-    } | undefined;
     durationS?: number | undefined;
     provenance?: {
         round?: number | null | undefined;
@@ -1426,25 +1037,30 @@ declare const overlaySchema: z.ZodObject<{
     style?: z.objectInputType<{
         preset: z.ZodOptional<z.ZodString>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
-    onCut?: "error" | "drop" | "clip" | undefined;
+    text?: string | undefined;
+    onCut?: "clip" | "drop" | "error" | undefined;
     layout?: {
         x?: number | undefined;
         y?: number | undefined;
-        align?: "center" | "left" | "right" | undefined;
+        align?: "left" | "center" | "right" | undefined;
         safeArea?: boolean | undefined;
     } | undefined;
     asset?: {
         ref: string;
     } | undefined;
     enter?: {
-        preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
         durationS: number;
+        preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
     } | undefined;
     exit?: {
-        preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
         durationS: number;
+        preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
     } | undefined;
-    z?: number | undefined;
+    size?: {
+        w?: number | undefined;
+        h?: number | undefined;
+    } | undefined;
+    z?: number | undefined;
 }>;
 declare const audioSchema: z.ZodObject<{
     id: z.ZodString;
@@ -1502,14 +1118,14 @@ declare const audioSchema: z.ZodObject<{
         end: z.ZodNumber;
     }, "strict", z.ZodTypeAny, {
         type: "source";
+        source: string;
         start: number;
         end: number;
-        source: string;
     }, {
         type: "source";
+        source: string;
         start: number;
         end: number;
-        source: string;
     }>, z.ZodObject<{
         type: z.ZodLiteral<"output">;
         at: z.ZodUnion<[z.ZodEnum<["start", "end", "full"]>, z.ZodObject<{
@@ -1550,6 +1166,12 @@ declare const audioSchema: z.ZodObject<{
         actor?: "agent" | "user" | undefined;
     }>>;
 }, "strict", z.ZodTypeAny, {
+    id: string;
+    provenance: {
+        round: number | null;
+        changeId: string | null;
+        actor: "agent" | "user";
+    };
     anchor: {
         type: "words";
         source: string;
@@ -1562,9 +1184,9 @@ declare const audioSchema: z.ZodObject<{
         edge?: "start" | "end" | undefined;
     } | {
         type: "source";
+        source: string;
         start: number;
         end: number;
-        source: string;
     } | {
         type: "output";
         at: "start" | "end" | "full" | {
@@ -1573,12 +1195,6 @@ declare const audioSchema: z.ZodObject<{
         durationS?: number | undefined;
     };
     kind: "music" | "sfx";
-    id: string;
-    provenance: {
-        round: number | null;
-        changeId: string | null;
-        actor: "agent" | "user";
-    };
     asset: {
         ref: string;
     };
@@ -1586,6 +1202,7 @@ declare const audioSchema: z.ZodObject<{
     duckToSpeech: boolean;
     fadeOutS?: number | undefined;
 }, {
+    id: string;
     anchor: {
         type: "words";
         source: string;
@@ -1598,9 +1215,9 @@ declare const audioSchema: z.ZodObject<{
         edge?: "start" | "end" | undefined;
     } | {
         type: "source";
+        source: string;
         start: number;
         end: number;
-        source: string;
     } | {
         type: "output";
         at: "start" | "end" | "full" | {
@@ -1609,7 +1226,6 @@ declare const audioSchema: z.ZodObject<{
         durationS?: number | undefined;
     };
     kind: "music" | "sfx";
-    id: string;
     asset: {
         ref: string;
     };
@@ -1623,10 +1239,13 @@ declare const audioSchema: z.ZodObject<{
     fadeOutS?: number | undefined;
 }>;
 type CutRange = z.infer<typeof cutRangeSchema>;
+type CaptionPreset = z.infer<typeof captionPresetSchema>;
+type CaptionStyle = z.infer<typeof captionStyleSchema>;
 type CaptionOverride = z.infer<typeof captionOverrideSchema>;
 type ZoomItem = z.infer<typeof zoomSchema>;
 type OverlayItem = z.infer<typeof overlaySchema>;
 type OverlayFx = z.infer<typeof overlayFxSchema>;
+type GradeSetting = z.infer<typeof gradeSettingSchema>;
 type AudioItem = z.infer<typeof audioSchema>;
 type TimelineSource = z.infer<typeof timelineSourceSchema>;
 type TimelineSettings = z.infer<typeof settingsSchema>;
@@ -1766,9 +1385,9 @@ declare const timelineV2Schema: z.ZodObject<{
                 actor?: "agent" | "user" | undefined;
             }>>;
         }, "strict", z.ZodTypeAny, {
+            source: string;
             start: number;
             end: number;
-            source: string;
             id: string;
             provenance: {
                 round: number | null;
@@ -1780,9 +1399,9 @@ declare const timelineV2Schema: z.ZodObject<{
             quote?: string | undefined;
             reason?: string | undefined;
         }, {
+            source: string;
             start: number;
             end: number;
-            source: string;
             id: string;
             grade?: string | undefined;
             beat?: string | undefined;
@@ -1796,9 +1415,9 @@ declare const timelineV2Schema: z.ZodObject<{
         }>, "many">>;
     }, "strict", z.ZodTypeAny, {
         ranges: {
+            source: string;
             start: number;
             end: number;
-            source: string;
             id: string;
             provenance: {
                 round: number | null;
@@ -1812,9 +1431,9 @@ declare const timelineV2Schema: z.ZodObject<{
         }[];
     }, {
         ranges?: {
+            source: string;
             start: number;
             end: number;
-            source: string;
             id: string;
             grade?: string | undefined;
             beat?: string | undefined;
@@ -1935,6 +1554,12 @@ declare const timelineV2Schema: z.ZodObject<{
                 actor?: "agent" | "user" | undefined;
             }>>;
         }, "strict", z.ZodTypeAny, {
+            id: string;
+            provenance: {
+                round: number | null;
+                changeId: string | null;
+                actor: "agent" | "user";
+            };
             anchor: {
                 type: "words";
                 source: string;
@@ -1946,17 +1571,12 @@ declare const timelineV2Schema: z.ZodObject<{
                 } | undefined;
                 edge?: "start" | "end" | undefined;
             };
-            id: string;
-            provenance: {
-                round: number | null;
-                changeId: string | null;
-                actor: "agent" | "user";
-            };
             op: "replace-text" | "hide" | "break-line" | "style";
             text?: string | undefined;
             color?: string | undefined;
             emphasis?: "pop" | "highlight" | undefined;
         }, {
+            id: string;
             anchor: {
                 type: "words";
                 source: string;
@@ -1968,14 +1588,13 @@ declare const timelineV2Schema: z.ZodObject<{
                 } | undefined;
                 edge?: "start" | "end" | undefined;
             };
-            id: string;
             op: "replace-text" | "hide" | "break-line" | "style";
-            text?: string | undefined;
             provenance?: {
                 round?: number | null | undefined;
                 changeId?: string | null | undefined;
                 actor?: "agent" | "user" | undefined;
             } | undefined;
+            text?: string | undefined;
             color?: string | undefined;
             emphasis?: "pop" | "highlight" | undefined;
         }>, "many">>;
@@ -1992,6 +1611,12 @@ declare const timelineV2Schema: z.ZodObject<{
         };
         enabled: boolean;
         overrides: {
+            id: string;
+            provenance: {
+                round: number | null;
+                changeId: string | null;
+                actor: "agent" | "user";
+            };
             anchor: {
                 type: "words";
                 source: string;
@@ -2003,12 +1628,6 @@ declare const timelineV2Schema: z.ZodObject<{
                 } | undefined;
                 edge?: "start" | "end" | undefined;
             };
-            id: string;
-            provenance: {
-                round: number | null;
-                changeId: string | null;
-                actor: "agent" | "user";
-            };
             op: "replace-text" | "hide" | "break-line" | "style";
             text?: string | undefined;
             color?: string | undefined;
@@ -2033,6 +1652,7 @@ declare const timelineV2Schema: z.ZodObject<{
         }, z.ZodTypeAny, "passthrough"> | undefined;
         enabled?: boolean | undefined;
         overrides?: {
+            id: string;
             anchor: {
                 type: "words";
                 source: string;
@@ -2044,14 +1664,13 @@ declare const timelineV2Schema: z.ZodObject<{
                 } | undefined;
                 edge?: "start" | "end" | undefined;
             };
-            id: string;
             op: "replace-text" | "hide" | "break-line" | "style";
-            text?: string | undefined;
             provenance?: {
                 round?: number | null | undefined;
                 changeId?: string | null | undefined;
                 actor?: "agent" | "user" | undefined;
             } | undefined;
+            text?: string | undefined;
             color?: string | undefined;
             emphasis?: "pop" | "highlight" | undefined;
         }[] | undefined;
@@ -2104,14 +1723,14 @@ declare const timelineV2Schema: z.ZodObject<{
             end: z.ZodNumber;
         }, "strict", z.ZodTypeAny, {
             type: "source";
+            source: string;
             start: number;
             end: number;
-            source: string;
         }, {
             type: "source";
+            source: string;
             start: number;
             end: number;
-            source: string;
         }>, z.ZodObject<{
             type: z.ZodLiteral<"output">;
             at: z.ZodUnion<[z.ZodEnum<["start", "end", "full"]>, z.ZodObject<{
@@ -2214,6 +1833,12 @@ declare const timelineV2Schema: z.ZodObject<{
             actor?: "agent" | "user" | undefined;
         }>>;
     }, "strict", z.ZodTypeAny, {
+        id: string;
+        provenance: {
+            round: number | null;
+            changeId: string | null;
+            actor: "agent" | "user";
+        };
         anchor: {
             type: "words";
             source: string;
@@ -2226,9 +1851,9 @@ declare const timelineV2Schema: z.ZodObject<{
             edge?: "start" | "end" | undefined;
         } | {
             type: "source";
+            source: string;
             start: number;
             end: number;
-            source: string;
         } | {
             type: "output";
             at: "start" | "end" | "full" | {
@@ -2236,13 +1861,7 @@ declare const timelineV2Schema: z.ZodObject<{
             };
             durationS?: number | undefined;
         };
-        id: string;
-        provenance: {
-            round: number | null;
-            changeId: string | null;
-            actor: "agent" | "user";
-        };
-        onCut: "error" | "drop" | "clip";
+        onCut: "clip" | "drop" | "error";
         rect: {
             w: number;
             h: number;
@@ -2264,6 +1883,7 @@ declare const timelineV2Schema: z.ZodObject<{
             scale?: number | undefined;
         } | undefined;
     }, {
+        id: string;
         anchor: {
             type: "words";
             source: string;
@@ -2276,9 +1896,9 @@ declare const timelineV2Schema: z.ZodObject<{
             edge?: "start" | "end" | undefined;
         } | {
             type: "source";
+            source: string;
             start: number;
             end: number;
-            source: string;
         } | {
             type: "output";
             at: "start" | "end" | "full" | {
@@ -2286,7 +1906,6 @@ declare const timelineV2Schema: z.ZodObject<{
             };
             durationS?: number | undefined;
         };
-        id: string;
         rect: {
             w: number;
             h: number;
@@ -2299,7 +1918,7 @@ declare const timelineV2Schema: z.ZodObject<{
             changeId?: string | null | undefined;
             actor?: "agent" | "user" | undefined;
         } | undefined;
-        onCut?: "error" | "drop" | "clip" | undefined;
+        onCut?: "clip" | "drop" | "error" | undefined;
         to?: {
             rect?: {
                 w: number;
@@ -2363,14 +1982,14 @@ declare const timelineV2Schema: z.ZodObject<{
             end: z.ZodNumber;
         }, "strict", z.ZodTypeAny, {
             type: "source";
+            source: string;
             start: number;
             end: number;
-            source: string;
         }, {
             type: "source";
+            source: string;
             start: number;
             end: number;
-            source: string;
         }>, z.ZodObject<{
             type: z.ZodLiteral<"output">;
             at: z.ZodUnion<[z.ZodEnum<["start", "end", "full"]>, z.ZodObject<{
@@ -2403,12 +2022,12 @@ declare const timelineV2Schema: z.ZodObject<{
         }, "strict", z.ZodTypeAny, {
             x: number;
             y: number;
-            align: "center" | "left" | "right";
+            align: "left" | "center" | "right";
             safeArea: boolean;
         }, {
             x?: number | undefined;
             y?: number | undefined;
-            align?: "center" | "left" | "right" | undefined;
+            align?: "left" | "center" | "right" | undefined;
             safeArea?: boolean | undefined;
         }>>;
         text: z.ZodOptional<z.ZodString>;
@@ -2432,21 +2051,21 @@ declare const timelineV2Schema: z.ZodObject<{
             preset: z.ZodEnum<["fade", "pop", "slide-up", "slide-down", "scale-in"]>;
             durationS: z.ZodNumber;
         }, "strict", z.ZodTypeAny, {
-            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
             durationS: number;
-        }, {
             preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
+        }, {
             durationS: number;
+            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
         }>>;
         exit: z.ZodOptional<z.ZodObject<{
             preset: z.ZodEnum<["fade", "pop", "slide-up", "slide-down", "scale-in"]>;
             durationS: z.ZodNumber;
         }, "strict", z.ZodTypeAny, {
-            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
             durationS: number;
-        }, {
             preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
+        }, {
             durationS: number;
+            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
         }>>;
         /** Size as canvas fractions (w of canvas width, h of canvas height). */
         size: z.ZodOptional<z.ZodObject<{
@@ -2475,6 +2094,12 @@ declare const timelineV2Schema: z.ZodObject<{
             actor?: "agent" | "user" | undefined;
         }>>;
     }, "strict", z.ZodTypeAny, {
+        id: string;
+        provenance: {
+            round: number | null;
+            changeId: string | null;
+            actor: "agent" | "user";
+        };
         anchor: {
             type: "words";
             source: string;
@@ -2487,9 +2112,9 @@ declare const timelineV2Schema: z.ZodObject<{
             edge?: "start" | "end" | undefined;
         } | {
             type: "source";
+            source: string;
             start: number;
             end: number;
-            source: string;
         } | {
             type: "output";
             at: "start" | "end" | "full" | {
@@ -2497,44 +2122,39 @@ declare const timelineV2Schema: z.ZodObject<{
             };
             durationS?: number | undefined;
         };
-        kind: "text" | "title-card" | "image" | "sticker";
-        id: string;
-        provenance: {
-            round: number | null;
-            changeId: string | null;
-            actor: "agent" | "user";
-        };
         style: {
             preset?: string | undefined;
         } & {
             [k: string]: unknown;
         };
-        onCut: "error" | "drop" | "clip";
+        onCut: "clip" | "drop" | "error";
+        kind: "text" | "title-card" | "image" | "sticker";
         layout: {
             x: number;
             y: number;
-            align: "center" | "left" | "right";
+            align: "left" | "center" | "right";
             safeArea: boolean;
         };
-        text?: string | undefined;
-        size?: {
-            w?: number | undefined;
-            h?: number | undefined;
-        } | undefined;
         durationS?: number | undefined;
+        text?: string | undefined;
         asset?: {
             ref: string;
         } | undefined;
         enter?: {
-            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
             durationS: number;
+            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
         } | undefined;
         exit?: {
-            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
             durationS: number;
+            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
+        } | undefined;
+        size?: {
+            w?: number | undefined;
+            h?: number | undefined;
         } | undefined;
         z?: number | undefined;
     }, {
+        id: string;
         anchor: {
             type: "words";
             source: string;
@@ -2547,9 +2167,9 @@ declare const timelineV2Schema: z.ZodObject<{
             edge?: "start" | "end" | undefined;
         } | {
             type: "source";
+            source: string;
             start: number;
             end: number;
-            source: string;
         } | {
             type: "output";
             at: "start" | "end" | "full" | {
@@ -2558,12 +2178,6 @@ declare const timelineV2Schema: z.ZodObject<{
             durationS?: number | undefined;
         };
         kind: "text" | "title-card" | "image" | "sticker";
-        id: string;
-        text?: string | undefined;
-        size?: {
-            w?: number | undefined;
-            h?: number | undefined;
-        } | undefined;
         durationS?: number | undefined;
         provenance?: {
             round?: number | null | undefined;
@@ -2573,23 +2187,28 @@ declare const timelineV2Schema: z.ZodObject<{
         style?: z.objectInputType<{
             preset: z.ZodOptional<z.ZodString>;
         }, z.ZodTypeAny, "passthrough"> | undefined;
-        onCut?: "error" | "drop" | "clip" | undefined;
+        text?: string | undefined;
+        onCut?: "clip" | "drop" | "error" | undefined;
         layout?: {
             x?: number | undefined;
             y?: number | undefined;
-            align?: "center" | "left" | "right" | undefined;
+            align?: "left" | "center" | "right" | undefined;
             safeArea?: boolean | undefined;
         } | undefined;
         asset?: {
             ref: string;
         } | undefined;
         enter?: {
-            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
             durationS: number;
+            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
         } | undefined;
         exit?: {
-            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
             durationS: number;
+            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
+        } | undefined;
+        size?: {
+            w?: number | undefined;
+            h?: number | undefined;
         } | undefined;
         z?: number | undefined;
     }>, "many">>;
@@ -2649,14 +2268,14 @@ declare const timelineV2Schema: z.ZodObject<{
             end: z.ZodNumber;
         }, "strict", z.ZodTypeAny, {
             type: "source";
+            source: string;
             start: number;
             end: number;
-            source: string;
         }, {
             type: "source";
+            source: string;
             start: number;
             end: number;
-            source: string;
         }>, z.ZodObject<{
             type: z.ZodLiteral<"output">;
             at: z.ZodUnion<[z.ZodEnum<["start", "end", "full"]>, z.ZodObject<{
@@ -2697,6 +2316,12 @@ declare const timelineV2Schema: z.ZodObject<{
             actor?: "agent" | "user" | undefined;
         }>>;
     }, "strict", z.ZodTypeAny, {
+        id: string;
+        provenance: {
+            round: number | null;
+            changeId: string | null;
+            actor: "agent" | "user";
+        };
         anchor: {
             type: "words";
             source: string;
@@ -2709,9 +2334,9 @@ declare const timelineV2Schema: z.ZodObject<{
             edge?: "start" | "end" | undefined;
         } | {
             type: "source";
+            source: string;
             start: number;
             end: number;
-            source: string;
         } | {
             type: "output";
             at: "start" | "end" | "full" | {
@@ -2720,12 +2345,6 @@ declare const timelineV2Schema: z.ZodObject<{
             durationS?: number | undefined;
         };
         kind: "music" | "sfx";
-        id: string;
-        provenance: {
-            round: number | null;
-            changeId: string | null;
-            actor: "agent" | "user";
-        };
         asset: {
             ref: string;
         };
@@ -2733,6 +2352,7 @@ declare const timelineV2Schema: z.ZodObject<{
         duckToSpeech: boolean;
         fadeOutS?: number | undefined;
     }, {
+        id: string;
         anchor: {
             type: "words";
             source: string;
@@ -2745,9 +2365,9 @@ declare const timelineV2Schema: z.ZodObject<{
             edge?: "start" | "end" | undefined;
         } | {
             type: "source";
+            source: string;
             start: number;
             end: number;
-            source: string;
         } | {
             type: "output";
             at: "start" | "end" | "full" | {
@@ -2756,7 +2376,6 @@ declare const timelineV2Schema: z.ZodObject<{
             durationS?: number | undefined;
         };
         kind: "music" | "sfx";
-        id: string;
         asset: {
             ref: string;
         };
@@ -2770,43 +2389,6 @@ declare const timelineV2Schema: z.ZodObject<{
         fadeOutS?: number | undefined;
     }>, "many">>;
 }, "strict", z.ZodTypeAny, {
-    audio: {
-        anchor: {
-            type: "words";
-            source: string;
-            phrase: string;
-            occurrence?: number | undefined;
-            resolved?: {
-                start: number;
-                end: number;
-            } | undefined;
-            edge?: "start" | "end" | undefined;
-        } | {
-            type: "source";
-            start: number;
-            end: number;
-            source: string;
-        } | {
-            type: "output";
-            at: "start" | "end" | "full" | {
-                after: string;
-            };
-            durationS?: number | undefined;
-        };
-        kind: "music" | "sfx";
-        id: string;
-        provenance: {
-            round: number | null;
-            changeId: string | null;
-            actor: "agent" | "user";
-        };
-        asset: {
-            ref: string;
-        };
-        gainDb: number;
-        duckToSpeech: boolean;
-        fadeOutS?: number | undefined;
-    }[];
     id: string;
     version: 2;
     sources: Record<string, {
@@ -2835,9 +2417,9 @@ declare const timelineV2Schema: z.ZodObject<{
     };
     cut: {
         ranges: {
+            source: string;
             start: number;
             end: number;
-            source: string;
             id: string;
             provenance: {
                 round: number | null;
@@ -2863,6 +2445,12 @@ declare const timelineV2Schema: z.ZodObject<{
         };
         enabled: boolean;
         overrides: {
+            id: string;
+            provenance: {
+                round: number | null;
+                changeId: string | null;
+                actor: "agent" | "user";
+            };
             anchor: {
                 type: "words";
                 source: string;
@@ -2874,12 +2462,6 @@ declare const timelineV2Schema: z.ZodObject<{
                 } | undefined;
                 edge?: "start" | "end" | undefined;
             };
-            id: string;
-            provenance: {
-                round: number | null;
-                changeId: string | null;
-                actor: "agent" | "user";
-            };
             op: "replace-text" | "hide" | "break-line" | "style";
             text?: string | undefined;
             color?: string | undefined;
@@ -2887,6 +2469,12 @@ declare const timelineV2Schema: z.ZodObject<{
         }[];
     };
     zooms: {
+        id: string;
+        provenance: {
+            round: number | null;
+            changeId: string | null;
+            actor: "agent" | "user";
+        };
         anchor: {
             type: "words";
             source: string;
@@ -2899,9 +2487,9 @@ declare const timelineV2Schema: z.ZodObject<{
             edge?: "start" | "end" | undefined;
         } | {
             type: "source";
+            source: string;
             start: number;
             end: number;
-            source: string;
         } | {
             type: "output";
             at: "start" | "end" | "full" | {
@@ -2909,13 +2497,7 @@ declare const timelineV2Schema: z.ZodObject<{
             };
             durationS?: number | undefined;
         };
-        id: string;
-        provenance: {
-            round: number | null;
-            changeId: string | null;
-            actor: "agent" | "user";
-        };
-        onCut: "error" | "drop" | "clip";
+        onCut: "clip" | "drop" | "error";
         rect: {
             w: number;
             h: number;
@@ -2938,6 +2520,12 @@ declare const timelineV2Schema: z.ZodObject<{
         } | undefined;
     }[];
     overlays: {
+        id: string;
+        provenance: {
+            round: number | null;
+            changeId: string | null;
+            actor: "agent" | "user";
+        };
         anchor: {
             type: "words";
             source: string;
@@ -2950,9 +2538,9 @@ declare const timelineV2Schema: z.ZodObject<{
             edge?: "start" | "end" | undefined;
         } | {
             type: "source";
+            source: string;
             start: number;
             end: number;
-            source: string;
         } | {
             type: "output";
             at: "start" | "end" | "full" | {
@@ -2960,53 +2548,45 @@ declare const timelineV2Schema: z.ZodObject<{
             };
             durationS?: number | undefined;
         };
-        kind: "text" | "title-card" | "image" | "sticker";
-        id: string;
-        provenance: {
-            round: number | null;
-            changeId: string | null;
-            actor: "agent" | "user";
-        };
         style: {
             preset?: string | undefined;
         } & {
             [k: string]: unknown;
         };
-        onCut: "error" | "drop" | "clip";
+        onCut: "clip" | "drop" | "error";
+        kind: "text" | "title-card" | "image" | "sticker";
         layout: {
             x: number;
             y: number;
-            align: "center" | "left" | "right";
+            align: "left" | "center" | "right";
             safeArea: boolean;
         };
+        durationS?: number | undefined;
         text?: string | undefined;
-        size?: {
-            w?: number | undefined;
-            h?: number | undefined;
-        } | undefined;
-        durationS?: number | undefined;
         asset?: {
             ref: string;
         } | undefined;
         enter?: {
-            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
             durationS: number;
+            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
         } | undefined;
         exit?: {
-            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
             durationS: number;
+            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
+        } | undefined;
+        size?: {
+            w?: number | undefined;
+            h?: number | undefined;
         } | undefined;
         z?: number | undefined;
     }[];
-}, {
-    id: string;
-    version: 2;
-    sources: Record<string, {
-        path: string;
-        durationS?: number | undefined;
-        transcriptHash?: string | undefined;
-    }>;
-    audio?: {
+    audio: {
+        id: string;
+        provenance: {
+            round: number | null;
+            changeId: string | null;
+            actor: "agent" | "user";
+        };
         anchor: {
             type: "words";
             source: string;
@@ -3019,9 +2599,9 @@ declare const timelineV2Schema: z.ZodObject<{
             edge?: "start" | "end" | undefined;
         } | {
             type: "source";
+            source: string;
             start: number;
             end: number;
-            source: string;
         } | {
             type: "output";
             at: "start" | "end" | "full" | {
@@ -3030,19 +2610,21 @@ declare const timelineV2Schema: z.ZodObject<{
             durationS?: number | undefined;
         };
         kind: "music" | "sfx";
-        id: string;
         asset: {
             ref: string;
         };
-        provenance?: {
-            round?: number | null | undefined;
-            changeId?: string | null | undefined;
-            actor?: "agent" | "user" | undefined;
-        } | undefined;
-        gainDb?: number | undefined;
-        duckToSpeech?: boolean | undefined;
+        gainDb: number;
+        duckToSpeech: boolean;
         fadeOutS?: number | undefined;
-    }[] | undefined;
+    }[];
+}, {
+    id: string;
+    version: 2;
+    sources: Record<string, {
+        path: string;
+        durationS?: number | undefined;
+        transcriptHash?: string | undefined;
+    }>;
     settings?: {
         canvas?: {
             w: number;
@@ -3064,9 +2646,9 @@ declare const timelineV2Schema: z.ZodObject<{
     } | undefined;
     cut?: {
         ranges?: {
+            source: string;
             start: number;
             end: number;
-            source: string;
             id: string;
             grade?: string | undefined;
             beat?: string | undefined;
@@ -3098,6 +2680,7 @@ declare const timelineV2Schema: z.ZodObject<{
         }, z.ZodTypeAny, "passthrough"> | undefined;
         enabled?: boolean | undefined;
         overrides?: {
+            id: string;
             anchor: {
                 type: "words";
                 source: string;
@@ -3109,19 +2692,19 @@ declare const timelineV2Schema: z.ZodObject<{
                 } | undefined;
                 edge?: "start" | "end" | undefined;
             };
-            id: string;
             op: "replace-text" | "hide" | "break-line" | "style";
-            text?: string | undefined;
             provenance?: {
                 round?: number | null | undefined;
                 changeId?: string | null | undefined;
                 actor?: "agent" | "user" | undefined;
             } | undefined;
+            text?: string | undefined;
             color?: string | undefined;
             emphasis?: "pop" | "highlight" | undefined;
         }[] | undefined;
     } | undefined;
     zooms?: {
+        id: string;
         anchor: {
             type: "words";
             source: string;
@@ -3134,9 +2717,9 @@ declare const timelineV2Schema: z.ZodObject<{
             edge?: "start" | "end" | undefined;
         } | {
             type: "source";
+            source: string;
             start: number;
             end: number;
-            source: string;
         } | {
             type: "output";
             at: "start" | "end" | "full" | {
@@ -3144,7 +2727,6 @@ declare const timelineV2Schema: z.ZodObject<{
             };
             durationS?: number | undefined;
         };
-        id: string;
         rect: {
             w: number;
             h: number;
@@ -3157,7 +2739,7 @@ declare const timelineV2Schema: z.ZodObject<{
             changeId?: string | null | undefined;
             actor?: "agent" | "user" | undefined;
         } | undefined;
-        onCut?: "error" | "drop" | "clip" | undefined;
+        onCut?: "clip" | "drop" | "error" | undefined;
         to?: {
             rect?: {
                 w: number;
@@ -3173,6 +2755,7 @@ declare const timelineV2Schema: z.ZodObject<{
         } | undefined;
     }[] | undefined;
     overlays?: {
+        id: string;
         anchor: {
             type: "words";
             source: string;
@@ -3185,9 +2768,9 @@ declare const timelineV2Schema: z.ZodObject<{
             edge?: "start" | "end" | undefined;
         } | {
             type: "source";
+            source: string;
             start: number;
             end: number;
-            source: string;
         } | {
             type: "output";
             at: "start" | "end" | "full" | {
@@ -3196,12 +2779,6 @@ declare const timelineV2Schema: z.ZodObject<{
             durationS?: number | undefined;
         };
         kind: "text" | "title-card" | "image" | "sticker";
-        id: string;
-        text?: string | undefined;
-        size?: {
-            w?: number | undefined;
-            h?: number | undefined;
-        } | undefined;
         durationS?: number | undefined;
         provenance?: {
             round?: number | null | undefined;
@@ -3211,26 +2788,68 @@ declare const timelineV2Schema: z.ZodObject<{
         style?: z.objectInputType<{
             preset: z.ZodOptional<z.ZodString>;
         }, z.ZodTypeAny, "passthrough"> | undefined;
-        onCut?: "error" | "drop" | "clip" | undefined;
+        text?: string | undefined;
+        onCut?: "clip" | "drop" | "error" | undefined;
         layout?: {
             x?: number | undefined;
             y?: number | undefined;
-            align?: "center" | "left" | "right" | undefined;
+            align?: "left" | "center" | "right" | undefined;
             safeArea?: boolean | undefined;
         } | undefined;
         asset?: {
             ref: string;
         } | undefined;
         enter?: {
-            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
             durationS: number;
+            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
         } | undefined;
         exit?: {
-            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
             durationS: number;
+            preset: "pop" | "fade" | "slide-up" | "slide-down" | "scale-in";
+        } | undefined;
+        size?: {
+            w?: number | undefined;
+            h?: number | undefined;
         } | undefined;
         z?: number | undefined;
     }[] | undefined;
+    audio?: {
+        id: string;
+        anchor: {
+            type: "words";
+            source: string;
+            phrase: string;
+            occurrence?: number | undefined;
+            resolved?: {
+                start: number;
+                end: number;
+            } | undefined;
+            edge?: "start" | "end" | undefined;
+        } | {
+            type: "source";
+            source: string;
+            start: number;
+            end: number;
+        } | {
+            type: "output";
+            at: "start" | "end" | "full" | {
+                after: string;
+            };
+            durationS?: number | undefined;
+        };
+        kind: "music" | "sfx";
+        asset: {
+            ref: string;
+        };
+        provenance?: {
+            round?: number | null | undefined;
+            changeId?: string | null | undefined;
+            actor?: "agent" | "user" | undefined;
+        } | undefined;
+        gainDb?: number | undefined;
+        duckToSpeech?: boolean | undefined;
+        fadeOutS?: number | undefined;
+    }[] | undefined;
 }>;
 type TimelineV2 = z.infer<typeof timelineV2Schema>;
 interface Diagnostic {
@@ -3247,6 +2866,7 @@ interface Diagnostics {
     /** Item ids removed by onCut:"drop" policy during compile. */
     dropped: string[];
 }
+declare function emptyDiagnostics(): Diagnostics;
 interface ParseResult {
     doc: TimelineV2 | null;
     errors: Diagnostic[];
@@ -3276,6 +2896,71 @@ declare function checkCapabilities(uses: string[], registry?: Record<string, Cap
     warnings: Diagnostic[];
 };
 
+type TokenType = "word" | "spacing" | "audio_event";
+/** A single ElevenLabs Scribe token (word-level, verbatim). */
+interface ScribeWord {
+    type?: TokenType;
+    text?: string;
+    start: number | null;
+    end: number | null;
+    speaker_id?: string | null;
+    [extra: string]: unknown;
+}
+interface ScribeTranscript {
+    language_code?: string;
+    text?: string;
+    words: ScribeWord[];
+    [extra: string]: unknown;
+}
+/** One KEEP segment in SOURCE seconds. Gaps between ranges are the cuts. */
+interface EdlRange {
+    source: string;
+    start: number;
+    end: number;
+    beat?: string;
+    quote?: string;
+    reason?: string;
+    /** Optional per-range grade override (preset name | raw ffmpeg filter | "auto"). */
+    grade?: string;
+}
+interface EdlOverlay {
+    [k: string]: unknown;
+}
+interface Edl {
+    version: number;
+    sources: Record<string, string>;
+    /** "none" | preset name | raw ffmpeg filter | "auto" */
+    grade: string;
+    ranges: EdlRange[];
+    overlays: EdlOverlay[];
+    total_duration_s: number;
+    /** Optional explicit subtitle path. */
+    subtitles?: string;
+    /** Set once the amplitude silence-trim pass has rewritten the ranges. */
+    desilenced?: boolean;
+}
+interface CutBoundary {
+    index: number;
+    output_time_s: number;
+    removed_source_gap_s: number;
+    source_before: number;
+    source_after: number;
+}
+interface VerifyJoinFinding {
+    index: number;
+    output_time_s: number;
+    duplicated_phrase?: string;
+    gap_s?: number;
+    severity: "error" | "warning" | "info";
+    detail: string;
+}
+interface VerifyResult {
+    verdict: "clean" | "needs-fixes";
+    mode: "full" | "joins";
+    joins: VerifyJoinFinding[];
+    confidence: string;
+}
+
 interface StreamWord {
     /** Index in the word stream (word tokens only, sorted by start). */
     index: number;
@@ -3341,229 +3026,721 @@ interface ResolveOptions {
  *  fuzzy suggestions. */
 declare function resolvePhrase(stream: StreamWord[], phrase: string, opts?: ResolveOptions): ResolveOutcome;
 
-interface PlanZoomOp {
-    kind: "zoom";
-    itemId: string;
-    rect: {
-        x: number;
-        y: number;
-        w: number;
-        h: number;
-    };
-    scale: number;
-    ease: {
-        in: number;
-        out: number;
-    };
-    /** Seconds relative to the segment's own start. */
-    tIn: number;
-    tOut: number;
-    /** Ramp target (zoom `to`): animate rect/scale base → target over [tIn, tOut]. */
-    toRect?: {
-        x: number;
-        y: number;
-        w: number;
-        h: number;
-    };
-    toScale?: number;
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+declare const DEFAULT_TIMEOUT_MS = 30000;
+declare const DEFAULT_DOWNLOAD_TIMEOUT_MS = 300000;
+/** base = --api-base flag → CLIPREADY_API_BASE → API_BASE → the hosted cloud. */
+declare function resolveApiBase(flag: string | undefined, env?: NodeJS.ProcessEnv): string;
+/** credential = --api-key flag → CLIPREADY_API_KEY → RUN_TOKEN. */
+declare function resolveApiKey(flag: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
+/** video id = --video-id flag → VIDEO_ID. */
+declare function resolveVideoId(flag: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
+interface CloudFlags {
+    apiBase?: string;
+    apiKey?: string;
+    videoId?: string;
 }
-type PlanVideoOp = PlanZoomOp;
-interface PlanSegment {
-    id: string;
-    source: string;
-    srcStart: number;
-    srcEnd: number;
-    outStart: number;
-    outEnd: number;
-    /** The authored cut range this segment came from (pre-desilence). */
-    rangeId: string;
-    videoOps: PlanVideoOp[];
+interface ResolvedConfig {
+    base: string;
+    credential: string;
+    videoId?: string;
 }
-interface PlanCueWord {
-    /** Offset from the cue's outStart. */
+declare function stripTrailingSlash(base: string): string;
+/** Resolve base + credential (always required) and video id (required only when
+ *  `requireVideoId`). Throws a clear, actionable Error the CLI turns into exit 1. */
+declare function resolveConfig(flags: CloudFlags, opts?: {
+    requireVideoId?: boolean;
+}, env?: NodeJS.ProcessEnv): ResolvedConfig;
+declare function rendersUrl(base: string): string;
+declare function renderUrl(base: string, renderId: string): string;
+declare function reviewUrl(base: string, videoId: string): string;
+declare function assetsUrl(base: string): string;
+declare function meUrl(base: string): string;
+declare function projectsUrl(base: string): string;
+declare function projectVideosUrl(base: string, projectId: string): string;
+declare function runUrl(base: string, runId: string): string;
+/** Chunked-upload session routes: /api/v1/uploads/multipart[/parts|complete|abort|relay|relay-complete]. */
+declare function multipartUrl(base: string, tail?: "parts" | "complete" | "abort" | "relay" | "relay-complete"): string;
+/** Authenticated relay POST for one raw sub-chunk of a multipart part
+ *  (i is the 1-based sub-chunk index, of the sub-chunk count). */
+declare function multipartRelayUrl(base: string, uploadId: string, n: number, i: number, of: number): string;
+declare function filesUrl(base: string, videoId: string, path?: string): string;
+declare function transcribeUrl(base: string, videoId: string): string;
+/** POST /videos/{id}/ingest — server-side probe + audio extraction +
+ *  transcription + screening over the uploaded source (202 {run_id}). */
+declare function ingestUrl(base: string, videoId: string): string;
+declare function compileUrl(base: string, videoId: string): string;
+declare function resolveUrl(base: string, videoId: string): string;
+declare function verifyUrl(base: string, videoId: string): string;
+declare function composeUrl(base: string, videoId: string): string;
+type RenderMode = "preview" | "final";
+type RenderStatus = "pending" | "running" | "completed" | "failed";
+interface RenderCreate {
+    renderId: string;
+    status: RenderStatus;
+}
+interface RenderState {
+    status: RenderStatus;
+    videoUrl?: string;
+    error?: unknown;
+}
+declare function parseRenderCreate(data: unknown): RenderCreate;
+declare function parseRenderState(data: unknown): RenderState;
+declare function isTerminalStatus(s: RenderStatus): boolean;
+interface ArtifactContent {
+    name: string;
+    content: unknown;
+}
+/** POST /api/v1/assets response (clipready assets route): the created asset
+ *  row id plus a presigned URL the caller PUTs the bytes to directly. */
+interface AssetCreate {
+    assetId: string;
+    uploadUrl: string;
+}
+interface QaFramesResult {
+    url: string;
+    width: number;
+    height: number;
+    frames: number;
+    tStart: number;
+    tEnd: number;
+}
+interface QaWaveWord {
     t: number;
-    d: number;
+    end: number;
     text: string;
-    /** Per-word color (op:"style" caption override). */
-    color?: string;
-    /** Per-word animated emphasis at the word's onset (op:"style" override). */
-    emphasis?: "pop" | "highlight";
 }
-interface PlanCaptionCueEvent {
-    kind: "caption-cue";
-    outStart: number;
-    outEnd: number;
-    words: PlanCueWord[];
-    /** Force a line break after this cue (break-line override). */
-    lineBreakAfter?: boolean;
-    /** Set when the cue came from a caption override. */
-    itemId?: string;
-    /** Per-word highlight sweep within the cue (captions.style.karaoke). */
-    karaoke?: boolean;
+interface QaWaveformResult {
+    url: string;
+    words: QaWaveWord[];
 }
-interface PlanOverlayEvent {
-    kind: "overlay";
-    itemId: string;
-    outStart: number;
-    outEnd: number;
-    overlay: {
-        kind: OverlayItem["kind"];
-        layout: OverlayItem["layout"];
-        text?: string;
-        style: OverlayItem["style"];
-        asset?: {
-            ref: string;
-        };
-        enter?: OverlayFx;
-        exit?: OverlayFx;
-        size?: {
-            w?: number;
-            h?: number;
-        };
-        z?: number;
-    };
+/** POST /videos/{id}/qa {kind:"inspect"} → the combined filmstrip + waveform
+ *  composite with the plan's cut regions shaded. */
+interface QaInspectResult {
+    url: string;
+    tStart: number;
+    tEnd: number;
+    cuts: Array<{
+        start: number;
+        end: number;
+    }>;
+    cached: boolean;
 }
-interface PlanAudioEvent {
-    kind: "audio";
-    itemId: string;
-    outStart: number;
-    outEnd: number;
-    audio: {
-        kind: AudioItem["kind"];
-        asset: {
-            ref: string;
-        };
-        gainDb: number;
-        duckToSpeech: boolean;
-        fadeOutS?: number;
-    };
+/** One row of the VFS listing. */
+interface VfsFileEntry {
+    path: string;
+    backend: string;
+    content_type: string | null;
+    bytes: number | null;
+    sha256: string | null;
+    status: string | null;
+    updated_at: string | null;
+    updated_by: string | null;
 }
-type PlanEvent = PlanCaptionCueEvent | PlanOverlayEvent | PlanAudioEvent;
-interface Plan {
-    version: 1;
-    fromTimeline: string;
-    timelineHash: string;
-    outputDurationS: number;
-    segments: PlanSegment[];
-    events: PlanEvent[];
-    uses: string[];
-    boundaries: CutBoundary[];
+declare function parseFileList(data: unknown): VfsFileEntry[];
+/** GET ?path= result: db-backed files carry inline `content`, bucket-backed
+ *  files carry a signed `download_url`. Exactly one of the two is set. */
+interface VfsFileContent {
+    path: string;
+    content?: string;
+    downloadUrl?: string;
+    sha256: string | null;
+    contentType: string | null;
 }
-interface CompileCtx {
-    /** Parsed word-level Scribe transcripts by source name. */
-    transcripts?: Record<string, ScribeTranscript | undefined>;
-    /** "sha256:…" hash of each source's transcript file (anchor cache key). */
-    transcriptHashes?: Record<string, string>;
-    /** Amplitude silences by source (from ffmpeg silencedetect). When omitted,
-     *  the desilence pass sees no silences and keeps ranges as authored. */
-    silencesBySource?: Record<string, SilenceInterval[]>;
-    /** Word-token spans by source for intra-word split protection. Defaults to
-     *  spans derived from `transcripts`. */
-    wordsBySource?: Record<string, SilenceInterval[]>;
-    /** Set false to skip the desilence tighten pass entirely. Default true. */
-    desilence?: boolean;
-    /** Capability registry override (tests). */
-    capabilities?: Record<string, Capability>;
-    /** Existence of referenced asset files by ref (a stat pass gathered by the
-     *  caller — see gatherCompileCtx). A ref mapped to false fails compile with
-     *  "asset-missing"; refs absent from the map are not checked. */
-    assetsPresent?: Record<string, boolean>;
+declare function parseFileContent(data: unknown): VfsFileContent;
+interface VfsPresign {
+    uploadUrl: string;
+    token: string | null;
+    expiresAt: string | null;
 }
-interface CompileResult {
-    ok: boolean;
-    plan: Plan | null;
-    legacyEdl: Edl | null;
-    diagnostics: Diagnostics;
-    uses: string[];
+declare function parseFilePresign(data: unknown): VfsPresign;
+type RunStatus = "pending" | "running" | "completed" | "failed" | "timed_out";
+interface RunEvent {
+    ts: string;
+    type: string;
+    payload: unknown;
+}
+interface RunState {
+    id: string;
+    status: RunStatus;
+    errorCode: string | null;
+    errorMessage: string | null;
+    events: RunEvent[];
+}
+declare function parseRunState(data: unknown): RunState;
+declare function isTerminalRunStatus(s: RunStatus): boolean;
+/** One requested change in the active review round (fields are nullable —
+ *  a change carries only what its kind needs). */
+interface ReviewChange {
+    id: string;
+    idx: number;
+    kind: string;
+    t: number | null;
+    t2: number | null;
+    x: number | null;
+    y: number | null;
+    text: string | null;
+    outcome: string | null;
+}
+interface ReviewRound {
+    roundId: string;
+    runId: string;
+    seq: number;
+    mode: string;
+    status: string;
+    instruction: string;
+    changes: ReviewChange[];
+}
+interface ReviewSession {
+    videoId: string;
+    title: string | null;
+    latestVersionSeq: number | null;
+    activeRound: ReviewRound | null;
+    /** Raw timeline.json object for the latest version, if any. */
+    timeline: unknown | null;
+    /** Signed download URL for the source video, if available. */
+    sourceUrl: string | null;
+}
+declare class CloudHttpError extends Error {
+    status: number;
+    body?: unknown | undefined;
+    constructor(status: number, message: string, body?: unknown | undefined);
+}
+interface ClientOptions {
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+}
+declare class CloudClient {
+    readonly cfg: ResolvedConfig;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(cfg: ResolvedConfig, opts?: ClientOptions);
+    private requireVideoId;
+    /** Same client (same fetch/timeout) bound to a video id — for flows that
+     *  create the video mid-run (init). */
+    withVideoId(videoId: string): CloudClient;
+    /** The injected fetch — for helpers outside the class (multipart part PUTs)
+     *  that need raw Response access (e.g. the ETag header). */
+    get fetch(): FetchLike;
+    /** POST a JSON body to an absolute API URL with auth — public wrapper over
+     *  the private transport for helpers living outside the class (multipart). */
+    postJson(url: string, body: unknown): Promise<unknown>;
+    /** POST raw binary bytes to an authenticated API URL (multipart relay
+     *  sub-chunks). Content-Type application/octet-stream; JSON response. */
+    postBinary(url: string, bytes: Uint8Array, timeoutMs?: number): Promise<unknown>;
+    private request;
+    createRender(mode: RenderMode): Promise<RenderCreate>;
+    getRender(renderId: string): Promise<RenderState>;
+    qaFrames(args: {
+        start: number;
+        end: number;
+        cols?: number;
+        interval?: number;
+    }): Promise<QaFramesResult>;
+    qaWaveform(args: {
+        start: number;
+        end: number;
+    }): Promise<QaWaveformResult>;
+    qaInspect(args: {
+        start: number;
+        end: number;
+        nFrames?: number;
+    }): Promise<QaInspectResult>;
+    listArtifacts(): Promise<string[]>;
+    getArtifact(name: string): Promise<ArtifactContent>;
+    /** POST /api/v1/assets: request an asset row + presigned upload URL
+     *  (clipready assets route: {kind, content_type?, video_id?, filename?} →
+     *  {asset_id, upload_url, upload_token, expires_at}). */
+    createAsset(args: {
+        kind: string;
+        contentType?: string;
+        filename?: string;
+    }): Promise<AssetCreate>;
+    /** PUT raw bytes to a presigned upload URL. No Authorization header — the
+     *  signed URL carries its own credentials and may be a different host.
+     *  Mid-stream network failures (connection resets, TLS record errors) and
+     *  5xx responses are retried with exponential backoff — the whole body is
+     *  an in-memory buffer, so every attempt is a clean full replay. */
+    upload(url: string, bytes: Uint8Array, contentType: string, timeoutMs?: number, maxAttempts?: number): Promise<void>;
+    getReview(): Promise<ReviewSession>;
+    /** POST a review-round event ({run_id, type, payload?}); expects {ok:true}. */
+    pushReview(body: {
+        run_id: string;
+        type: string;
+        payload?: unknown;
+    }): Promise<void>;
+    /** GET /v1/me — validates the credential; returns the raw payload. */
+    me(): Promise<Record<string, unknown>>;
+    createProject(title: string): Promise<{
+        projectId: string;
+    }>;
+    /** POST /v1/assets for a NEW source (no video yet): {kind:"source", ...}. */
+    createSourceAsset(args: {
+        contentType: string;
+        filename?: string;
+        videoId?: string;
+    }): Promise<AssetCreate>;
+    /** POST /v1/projects/{id}/videos {asset_id, title?, workflow:"cli"}. */
+    createVideo(projectId: string, args: {
+        assetId: string;
+        title?: string;
+    }): Promise<{
+        videoId: string;
+        projectId: string;
+    }>;
+    filesList(): Promise<VfsFileEntry[]>;
+    filesGet(path: string): Promise<VfsFileContent>;
+    /** Inline PUT (≤5MB text payloads) → {path, sha256, bytes}. */
+    filesPutInline(path: string, content: string, contentType?: string): Promise<{
+        path: string;
+        sha256: string | null;
+        bytes: number | null;
+    }>;
+    /** Presign PUT for large/binary payloads → {upload_url, token, expires_at}. */
+    filesPresign(args: {
+        path: string;
+        contentType: string;
+        bytes: number;
+        sha256: string;
+    }): Promise<VfsPresign>;
+    /** Commit a presigned upload → {path, status:"ready"}. */
+    filesCommit(path: string): Promise<void>;
+    filesDelete(path: string): Promise<void>;
+    /** POST /videos/{id}/transcribe → 202 {run_id}. */
+    transcribeStart(body: {
+        wav_path: string;
+        stem: string;
+        duration_s: number;
+        language?: string;
+        num_speakers?: number;
+    }): Promise<{
+        runId: string;
+    }>;
+    /** POST /videos/{id}/ingest {stem?} → 202 {run_id}. Server-side probe + audio
+     *  extraction + transcription + screening over the uploaded source. The stem
+     *  names every derived artifact (transcripts/<stem>.json, audio/<stem>.wav) —
+     *  omit it and the server defaults to "source". */
+    ingestStart(stem?: string): Promise<{
+        runId: string;
+    }>;
+    /** POST /videos/{id}/verify {mode?, window_s?} → 202 {run_id}. The server
+     *  sources the preview audio itself — nothing is uploaded. */
+    verifyStart(body?: {
+        mode?: string;
+        window_s?: number;
+    }): Promise<{
+        runId: string;
+    }>;
+    /** GET /runs/{id} — run status + events. */
+    getRun(runId: string): Promise<RunState>;
+    /** POST /videos/{id}/compile → {ok, plan, legacy_edl, diagnostics, uses}. */
+    compileRemote(body: {
+        timeline?: unknown;
+        silences_by_source?: Record<string, Array<{
+            start: number;
+            end: number;
+        }>>;
+        assets_present?: Record<string, boolean>;
+    }): Promise<Record<string, unknown>>;
+    /** POST /videos/{id}/resolve {phrase, source?, occurrence?}. */
+    resolveRemote(body: {
+        phrase: string;
+        source?: string;
+        occurrence?: number;
+    }): Promise<Record<string, unknown>>;
+    /** GET /videos/{id}/compose → {html, counts, media:[{src, role}]}. */
+    getCompose(): Promise<{
+        html: string;
+        counts: Record<string, unknown>;
+        media: Array<{
+            src: string;
+            role: string;
+        }>;
+    }>;
+    download(url: string, dest: string, timeoutMs?: number): Promise<{
+        path: string;
+        bytes: number;
+    }>;
 }
-/** Deterministic content hash of the (defaults-applied) doc: sha256 over a
- *  canonical (recursively key-sorted) JSON encoding. */
-declare function timelineHash(doc: TimelineV2): string;
-/** Compile an authored TimelineV2 into a render plan. Pure: never touches the
- *  filesystem; the CLI layer (io.ts) gathers ctx and writes artifacts. */
-declare function compileTimeline(doc: TimelineV2, ctx?: CompileCtx): CompileResult;
+/** Download a (signed) URL to a local path, creating parent dirs. No auth
+ *  header — signed URLs carry their own credentials and may be a different host. */
+declare function downloadTo(url: string, dest: string, opts?: {
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+}): Promise<{
+    path: string;
+    bytes: number;
+}>;
 
-interface TimelineFromEdlOptions {
-    /** Timeline id; default "tl_<uuid>". */
-    id?: string;
-    /** Known source durations (seconds) by source name. */
-    sourceDurations?: Record<string, number>;
-    /** "sha256:…" transcript hashes by source name. */
-    transcriptHashes?: Record<string, string>;
+declare const MAX_RUN_POLL_MS: number;
+interface RunPollOptions {
+    intervalMs?: number;
+    maxMs?: number;
+    /** Called once per NEW event (dedup by array position). */
+    onEvent?: (ev: RunEvent) => void;
+    /** injectable for tests */
+    sleepImpl?: (ms: number) => Promise<void>;
+    now?: () => number;
 }
-/** Lift a legacy EDL into a cut-only TimelineV2 document. */
-declare function timelineFromEdl(edl: Edl, opts?: TimelineFromEdlOptions): TimelineV2;
+/** One human line per run event ("[type] message" when the payload has one). */
+declare function formatRunEvent(ev: RunEvent): string;
+/** Poll a run until terminal (completed|failed|timed_out). Returns the final
+ *  state; the CALLER decides what a non-completed status means. */
+declare function pollRun(client: CloudClient, runId: string, opts?: RunPollOptions): Promise<RunState>;
+/** Throw a clear error when a run ended without completing. */
+declare function assertRunCompleted(state: RunState, what: string): void;
 
-/** Vertical 9:16 master geometry — matches ensureVerticalMaster's output. */
-declare const COMPOSE_WIDTH: 1080;
-declare const COMPOSE_HEIGHT: 1920;
-/** Entry HTML file name inside the composition dir. */
-declare const COMPOSE_ENTRY: "index.html";
-/** Composition-relative media paths written by the `compose` verb. */
-declare const COMPOSE_VIDEO_SRC: "media/source.mp4";
-declare const COMPOSE_AUDIO_SRC: "media/audio.m4a";
-/** The subset of a compiled plan the composition needs. */
-type ComposePlan = Pick<Plan, "segments" | "events">;
-interface ComposeHtmlOptions {
-    /** URL (composition-relative) of the proxy video. Default media/source.mp4. */
-    videoSrc?: string;
-    /** URL (composition-relative) of the CONTINUOUS cut audio — the ffmpeg-cut
-     *  track extracted from preview.mp4. Default media/audio.m4a. */
-    audioSrc?: string;
-    /** Declarative color grade (timeline settings.grade object form) — stamped
-     *  as data-color-grading on the base track-0 clips. */
-    grade?: {
-        preset: string;
-        intensity?: number;
-    };
+/** Inline PUT payload ceiling (server contract: ≤5MB inline). */
+declare const INLINE_MAX_BYTES: number;
+/** sha256 hex of bytes, normalized without any "sha256:" prefix. */
+declare function sha256Hex(bytes: Uint8Array): string;
+/** Compare two sha256 values tolerating an optional "sha256:" prefix. */
+declare function sameSha(a: string | null | undefined, b: string | null | undefined): boolean;
+/** Map a VFS path to its local path under the job dir (sanitized: no "..",
+ *  no absolute escapes). */
+declare function vfsLocalPath(jobDir: string, path: string): string;
+/** Local job-dir path → VFS path (forward slashes, jobDir-relative). */
+declare function toVfsPath(jobDir: string, localPath: string): string;
+/** Content type for a pushed file, from its extension. */
+declare function vfsContentType(path: string): string;
+interface PulledFile {
+    path: string;
+    localPath: string;
+    bytes: number;
+    skipped: boolean;
+}
+interface FilesPullResult {
+    pulled: PulledFile[];
+    missing: string[];
+}
+/** Pull the listed files (or the `only` subset) into jobDir. A file whose
+ *  local sha256 already matches the server listing is skipped untouched. */
+declare function pullFiles(client: CloudClient, jobDir: string, opts?: {
+    only?: string[];
+    prefixes?: string[];
+    onFile?: (f: PulledFile) => void;
+}): Promise<FilesPullResult>;
+interface PushedFile {
+    path: string;
+    bytes: number;
+    skipped: boolean;
+    mode: "inline" | "presign" | "skip";
+}
+/** Push local files (jobDir-relative paths) into the VFS. Unchanged files
+ *  (sha256 equal to the server listing) are skipped. Text payloads ≤5MB go
+ *  inline; larger/binary payloads go presign → upload → commit. */
+declare function pushFiles(client: CloudClient, jobDir: string, paths: string[], opts?: {
+    onFile?: (f: PushedFile) => void;
+    log?: (line: string) => void;
+}): Promise<PushedFile[]>;
+/** Upload one in-memory payload to the VFS (used for WAVs and pushed renders).
+ *  Payloads over 8MB go chunked (multipart, per-part retry) when the server
+ *  supports it; otherwise — and for small payloads — the classic presign →
+ *  single PUT → commit flow. */
+declare function uploadVfsPayload(client: CloudClient, vfsPath: string, bytes: Uint8Array, contentType: string, opts?: {
+    sha256?: string;
+    log?: (line: string) => void;
+}): Promise<void>;
+/** Back-compat alias: upload one in-memory payload to the VFS. */
+declare function uploadVfsBytes(client: CloudClient, vfsPath: string, bytes: Uint8Array, contentType: string, log?: (line: string) => void): Promise<void>;
+
+/** Payloads LARGER than this go multipart; at or below, the single-shot path. */
+declare const MULTIPART_THRESHOLD_BYTES: number;
+/** Direct part-PUT transport failures before the relay fallback kicks in. */
+declare const RELAY_DIRECT_ATTEMPTS = 3;
+/** Relay sub-chunk ceiling (3.5MB — under the API route's body limit). */
+declare const RELAY_SUBCHUNK_BYTES = 3670016;
+/** Multipart applies above the 8MB threshold. Accepts a byte count (streaming
+ *  callers stat the file) or an in-memory payload. */
+declare function shouldMultipart(sizeOrBytes: number | Uint8Array): boolean;
+/** A random-access byte source: only `len`-sized windows are ever materialized,
+ *  so uploads stay 2GB-safe (memory ≤ concurrency × part_size). */
+interface MultipartSource {
+    size: number;
+    /** Read exactly min(len, size - offset) bytes starting at offset. */
+    readSlice(offset: number, len: number): Promise<Buffer>;
+}
+/** Wrap an in-memory payload as a source (small VFS pushes). */
+declare function bytesSource(bytes: Uint8Array): MultipartSource;
+interface FileSource extends MultipartSource {
+    /** Close the underlying fd. Callers MUST close on completion AND failure. */
+    close(): Promise<void>;
+}
+/** File-backed source: fs/promises open + positional reads. Never loads the
+ *  whole file; concurrent readSlice calls are safe (positional pread). */
+declare function openFileSource(path: string): Promise<FileSource>;
+interface MultipartOptions {
+    kind: "asset" | "jobfile";
+    /** In-memory payload (small VFS pushes). Exactly one of bytes/source. */
+    bytes?: Uint8Array;
+    /** Streaming payload (init sources) — 2GB-safe. */
+    source?: MultipartSource;
+    contentType: string;
+    /** kind "asset": original filename (no video exists yet at init time). */
+    filename?: string;
+    /** kind "jobfile": owning video + VFS path (+ sha256 for integrity). */
+    videoId?: string;
+    path?: string;
+    sha256?: string;
+    log?: (line: string) => void;
+    /** Retry backoff schedule override (tests) — defaults to jitteredBackoffMs. */
+    backoffMs?: (attempt: number) => number;
 }
-/** Element counts as emitted by composeHtml (mirrors its skip rules). */
-interface ComposeCounts {
-    segments: number;
-    cues: number;
-    zooms: number;
-    overlays: number;
+/** Chunked upload of a payload (in-memory bytes OR a streaming source).
+ *  Returns "unavailable" ONLY when the server cannot do multipart at all
+ *  (503 multipart_unavailable / 404 / 405 on session create) so the caller can
+ *  fall back to the single-shot presign path. Any other failure aborts the
+ *  session (best-effort) and throws. Parts are sliced through
+ *  source.readSlice, so memory stays ≤ PART_CONCURRENCY × part_size. */
+declare function uploadMultipart(client: CloudClient, opts: MultipartOptions, timeoutMs?: number): Promise<{
+    assetId?: string;
+} | "unavailable">;
+
+interface JobFile {
+    video_id: string;
+    project_id: string;
+    api_base: string;
+    stem: string;
+    duration_s: number;
+    /** Absolute path of the original init source (used as the transcribe media
+     *  fallback and to re-bake vertical_src.mp4 on demand). Optional: job.json
+     *  files written before 2.0.1 don't have it. */
+    source_path?: string;
 }
-declare function composeCounts(plan: ComposePlan): ComposeCounts;
-/** Declarative HyperFrames composition markup — see module doc. Pure. */
-declare function composeHtml(plan: ComposePlan, options?: ComposeHtmlOptions): string;
+declare function jobJsonPath(jobDir: string): string;
+declare function writeJobFile(jobDir: string, job: JobFile): string;
+declare function readJobFile(jobDir: string): JobFile | null;
+/** Video id fallback for job-dir verbs: flag/env (already resolved) → job.json. */
+declare function videoIdFromJob(jobDir: string, resolved: string | undefined): string;
 
-declare function timelineJsonPath(jobDir: string): string;
-declare function planPath(jobDir: string): string;
-declare function diagnosticsPath(jobDir: string): string;
-interface LoadedTimeline {
+/** Sanitize a source-derived stem to the server's filename-safe charset
+ *  (letters, digits, `.` `_` `-`): every run of anything else becomes a single
+ *  `-`, leading/trailing `-` are trimmed. Apostrophes, spaces, unicode
+ *  punctuation etc. in the source filename must never leak into the stem —
+ *  the server rejects them ("stem must be a filename-safe string"). Falls back
+ *  to "source" when nothing survives. */
+declare function sanitizeStem(name: string): string;
+/** The artifact set init pulls after the ingest run completes (plus the
+ *  prompts/ prefix). probe.json carries the server-side media probe. */
+declare function ingestArtifactSet(stem: string): string[];
+/** Read duration_s out of a pulled probe.json ({duration_s, width, height,
+ *  rotation}). Throws when the file is absent or carries no usable duration. */
+declare function readProbeDuration(jobDir: string): number;
+interface InitOptions {
+    source: string;
+    jobDir?: string;
+    title?: string;
+    pollIntervalMs?: number;
+    verbose?: boolean;
+}
+interface InitResult {
+    jobDir: string;
+    jobJson: string;
+    videoId: string;
+    projectId: string;
+    stem: string;
+    durationS: number;
+    uploaded: string;
+    uploadedBytes: number;
+    runId: string;
+    pulled: FilesPullResult;
+    /** Watch/review page in the clipready web app. */
+    webUrl: string;
+}
+declare function initCloudJob(client: CloudClient, opts: InitOptions): Promise<InitResult>;
+
+interface Transcribe2Options {
+    stem: string;
+    pollIntervalMs?: number;
+    verbose?: boolean;
+}
+interface Transcribe2Result {
+    /** null when the artifacts already existed server-side (pull only). */
+    runId: string | null;
+    pulled: FilesPullResult;
+}
+/** The artifact set `transcribe` pulls (probe.json rides along since v3 —
+ *  it feeds job.json duration_s after an ingest re-run). */
+declare function transcribeArtifactSet(stem: string): string[];
+declare function transcribeCloud(client: CloudClient, jobDir: string, opts: Transcribe2Options): Promise<Transcribe2Result>;
+
+declare function timelineJsonPath2(jobDir: string): string;
+declare function planPath2(jobDir: string): string;
+declare function diagnosticsPath2(jobDir: string): string;
+interface LoadedTimeline2 {
     doc: TimelineV2 | null;
-    errors: Diagnostic[];
     raw: unknown;
+    errors: Diagnostic[];
 }
-/** Read + parse <job>/timeline.json. */
-declare function loadTimeline(jobDir: string): LoadedTimeline;
-/** Transcript file for a source name. Mirrors silence.ts loadWordsBySource:
- *  transcripts/<name>.json, else the lone transcripts/*.json (single-source
- *  jobs name the transcript by source stem). */
-declare function transcriptFileForSource(jobDir: string, name: string): string | null;
-declare function sha256File(path: string): string;
-interface GatherOptions {
-    /** Skip ffmpeg silence detection (ctx.silencesBySource stays undefined and
-     *  the compile desilence pass becomes a no-op tighten). */
-    noDetect?: boolean;
+/** Read + parse <job>/timeline.json (public mirror of io.ts loadTimeline). */
+declare function loadTimeline2(jobDir: string): LoadedTimeline2;
+/** Local (client-side) validation verdict: schema + semantic + capabilities. */
+declare function validateLocal(doc: TimelineV2): {
+    ok: boolean;
+    uses: string[];
+    errors: Diagnostic[];
+    warnings: Diagnostic[];
+};
+/** Stat pass over asset refs so the server compile can emit asset-missing. */
+declare function statAssetsForDoc(jobDir: string, doc: TimelineV2): Record<string, boolean>;
+interface CompileRemoteResult {
+    ok: boolean;
+    planPath?: string;
+    edlPath?: string;
+    diagnosticsPath: string;
+    response: Record<string, unknown>;
 }
-/** Gather the impure CompileCtx inputs for a doc: per-source transcripts +
- *  hashes, and (unless noDetect) ffmpeg silencedetect maps using the doc's
- *  desilence settings — the same detection the legacy desilence flow runs. */
-declare function gatherCompileCtx(jobDir: string, doc: TimelineV2, opts?: GatherOptions): Promise<CompileCtx>;
-interface WrittenArtifacts {
-    plan?: string;
-    diagnostics: string;
-    edl?: string;
+/** POST the raw timeline (+ local asset stats) to the server compile and
+ *  write plan/diagnostics/edl exactly as returned (verbatim JSON). The server
+ *  sources silences from the VFS — no silences_by_source from the client. */
+declare function compileRemote(client: CloudClient, jobDir: string, loaded: LoadedTimeline2): Promise<CompileRemoteResult>;
+
+interface Verify2Options {
+    full?: boolean;
+    windowS?: number;
+    pollIntervalMs?: number;
+    verbose?: boolean;
 }
-/** Write resolved/plan.json + resolved/diagnostics.json (+ legacy edl.json on
- *  success). diagnostics.json is always written, also for failed compiles. */
-declare function writeCompileArtifacts(jobDir: string, result: CompileResult): WrittenArtifacts;
-/** Update ONLY the captions block of timeline.json (enabled + preset), leaving
- *  every other byte-level detail of the authored doc as-is. */
-declare function updateCaptionsBlock(jobDir: string, preset: string): {
-    raw: Record<string, unknown>;
-};
+interface Verify2Result {
+    runId: string;
+    verifyPath: string;
+    verdict: string | null;
+    findings: number | null;
+}
+declare function verifyCloud(client: CloudClient, jobDir: string, opts?: Verify2Options): Promise<Verify2Result>;
+
+/** QA output dir: <job>/qa when a job dir is given, else ./qa in cwd. */
+declare function qaDir(jobDir?: string): string;
+declare function framesPngPath(dir: string, start: number, end: number, suffix?: string): string;
+declare function waveformPngPath(dir: string, start: number, end: number): string;
+declare function waveformWordsPath(dir: string, start: number, end: number): string;
+/** The slice of a plan segment the QA math needs. */
+interface QaPlanSegment {
+    srcStart: number;
+    srcEnd: number;
+    outStart: number;
+    outEnd: number;
+}
+/** Read the segments array out of <job>/resolved/plan.json. */
+declare function readPlanSegments(jobDir: string): QaPlanSegment[];
+/** A source-time QA window; `suffix` distinguishes multi-window requests
+ *  ("-a"/"-b"/… — empty for a single window). */
+interface QaSourceWindow {
+    start: number;
+    end: number;
+    suffix: string;
+}
+/** Source-time windows around join `i` (1-based: the boundary between plan
+ *  segments i and i+1): the last `spanS` seconds of segment i (tail, "-a")
+ *  and the first `spanS` seconds of segment i+1 (head, "-b"), each clamped
+ *  to its segment. */
+declare function joinSourceWindows(segments: QaPlanSegment[], joinIndex: number, spanS: number): QaSourceWindow[];
+/** Map an OUTPUT-time window onto source-time windows: intersect
+ *  [outStart, outEnd] with each segment's output range and shift into source
+ *  time (srcT = seg.srcStart + (outT - seg.outStart)). One window per
+ *  overlapped segment, suffixed -a/-b/… when the window crosses a join. */
+declare function outWindowToSourceWindows(segments: QaPlanSegment[], outStart: number, outEnd: number): QaSourceWindow[];
+
+declare function reviewDir2(jobDir: string): string;
+declare function roundJsonPath2(jobDir: string): string;
+declare function instructionPath2(jobDir: string): string;
+interface PullReview2Result {
+    jobDir: string;
+    round: ReviewRound | null;
+    wroteTimeline: boolean;
+    downloadedSource: string | null;
+}
+/** GET the review session and hydrate the job dir (round.json + instruction.md,
+ *  timeline.json only when absent, optional source download). */
+declare function pullReview2(client: CloudClient, jobDir: string, opts?: {
+    withSource?: boolean;
+}): Promise<PullReview2Result>;
+/** run id = flag → <job>/review/round.json run_id. */
+declare function resolveRunId2(jobDir: string, flagOverride?: string): string;
+declare const REVIEW_STAGES2: readonly ["provisioning", "transcribing", "edl", "render_preview", "qc", "render_final", "uploading", "log"];
+declare function pushStage2(client: CloudClient, runId: string, stage: string, message?: string): Promise<void>;
+declare function assetContentType2(ref: string): string;
+/** Ordered, de-duplicated asset refs from a server-compiled plan's events. */
+declare function collectPlanAssetRefs2(plan: unknown): string[];
+/** Upload the plan's referenced assets (sha-cached in review/assets.json);
+ *  returns the {ref: asset_id} manifest. */
+declare function syncAssets2(client: CloudClient, jobDir: string, plan: unknown): Promise<Record<string, string>>;
+interface Push2Failure {
+    ok: false;
+    errors: Array<{
+        path: string;
+        code: string;
+        message: string;
+    }>;
+    diagnostics: unknown | null;
+}
+interface PushTimeline2Success {
+    ok: true;
+    plan: unknown;
+    timelineHash: string | null;
+    assets: Record<string, string>;
+}
+declare function pushTimeline2(client: CloudClient, jobDir: string, runId: string): Promise<Push2Failure | PushTimeline2Success>;
+interface ChangeOutcome2 {
+    change_id: string;
+    ok: boolean;
+    note?: string;
+}
+/** Read an outcomes file (bare array or {outcomes:[...]}) — mirror of
+ *  cloud/review.ts readOutcomesFile. */
+declare function readOutcomesFile2(path: string): ChangeOutcome2[];
+interface PushComplete2Success {
+    ok: true;
+    plan: unknown;
+    durationS: number;
+    outcomes: ChangeOutcome2[] | undefined;
+    assets: Record<string, string>;
+}
+declare function pushComplete2(client: CloudClient, jobDir: string, runId: string, opts: {
+    durationS: number;
+    outcomesPath?: string;
+}): Promise<Push2Failure | PushComplete2Success>;
+
+declare const MAX_POLL_MS: number;
+declare function defaultRenderOut(jobDir: string, mode: RenderMode): string;
+interface PollOptions {
+    intervalMs?: number;
+    maxMs?: number;
+    onTick?: (state: RenderState, elapsedMs: number) => void;
+    /** injectable for tests */
+    sleepImpl?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+/** Poll GET /renders/{id} until the status is terminal (completed|failed) or the
+ *  deadline is hit. Returns the last observed state. Throws on timeout. */
+declare function pollRender(client: CloudClient, renderId: string, opts?: PollOptions): Promise<RenderState>;
+
+/** Locate the bundled skill dir. Works both in dev (tsx: src/cloud/skill.ts →
+ *  <repo>/skills) and from the built/installed package (dist/cli.js →
+ *  <pkg>/skills). Searches a few relative candidates and picks the first that
+ *  actually contains a SKILL.md. */
+declare function bundledSkillDir(): string;
+declare function defaultSkillTarget(): string;
+interface InstallResult {
+    source: string;
+    dest: string;
+    files: string[];
+}
+/** Copy the bundled skill into <target|~/.claude/skills>/video-editing,
+ *  overwriting any existing copy. Returns the installed file list (relative). */
+declare function installSkill(opts?: {
+    target?: string;
+}): InstallResult;
+
+declare function publicConfigDir(): string;
+declare function publicConfigEnvPath(): string;
+declare const MANAGED_KEYS: readonly ["CLIPREADY_API_KEY", "CLIPREADY_API_BASE"];
+type ManagedKey = (typeof MANAGED_KEYS)[number];
+/** Load CLIPREADY_* values from the config file into process.env for any that
+ *  are not already set (env always wins). Call once at CLI startup so
+ *  `config set-key` actually takes effect for every verb. */
+declare function loadPublicConfigEnv(env?: NodeJS.ProcessEnv): void;
+/** Write/update ONE managed key in the config file, preserving other lines. */
+declare function savePublicConfigKey(key: ManagedKey, value: string): string;
 
-export { type Anchor, type AudioItem, CAPABILITIES, COMPOSE_AUDIO_SRC, COMPOSE_ENTRY, COMPOSE_HEIGHT, COMPOSE_VIDEO_SRC, COMPOSE_WIDTH, type Capability, type CapabilityStatus, type CaptionOverride, CommandError, type CompileCtx, type CompileResult, type ComposeCounts, type ComposeHtmlOptions, type ComposePlan, type CutBoundary, type CutRange, DEFAULT_DESILENCE, DEFAULT_EDIT_ROOT, type DesilenceOptions, type DesilenceStats, type Diagnostic, type Diagnostics, type Edl, type EdlOverlay, type EdlRange, type FeatureKey, type FfprobeResult, type FfprobeStream, type OutputAnchor, type OverlayItem, PRESETS, type PhraseMatch, type PhraseSuggestion, type Plan, type PlanAudioEvent, type PlanCaptionCueEvent, type PlanCueWord, type PlanEvent, type PlanOverlayEvent, type PlanSegment, type PlanVideoOp, type PlanZoomOp, type Provenance, type RenderMode, type ResolveOutcome, type ReviewIssue, type ReviewJson, type ScribeTranscript, type ScribeWord, type SilenceInterval, type SourceAnchor, type SourceJson, type StreamWord, type TimelineFromEdlOptions, type TimelineSettings, type TimelineSource, type TimelineV2, type TokenType, VIDEO_EXTS, type VerifyJoinFinding, type VerifyResult, type Warning, type WordsAnchor, type ZoomItem, agentizePrompt, artifactPaths, autoGradeForClip, checkCapabilities, compileTimeline, composeCounts, composeHtml, computeEnvelope, configDir, configEnvPath, cutBoundaries, decideGradeFilter, defaultJobDir, desilenceEdl, detectSilences, diagnosticsPath, displayedDimensions, duplicatedPhrase, duplicatedPhrases, duplicatedSpans, edlPath, ensureTranscribed, ensureVerticalMaster, ffprobe, findPhrase, fuzzySuggestions, gatherCompileCtx, generateQcImages, getPreset, initJob, isoNow, learnedEditingGuardrails, loadApiKey, loadJob, loadTimeline, loadWords, loadWordsBySource, mediaDuration, normalizePhrase, normalizeToken, packTranscripts, parseSilenceDetect, parseTimeline, planPath, pyFixed, pyFixedPad, pyRound, pySpacePad, readEdl, render, requireFfmpeg, resolveJob, resolvePhrase, rotationDegrees, run, runSync, screenTakes, sha256File, shown, silenceDetectArgs, slugify, sourceFromJob, statusPayload, straddlingGap, tightenRange, tightenRanges, timelineFromEdl, timelineHash, timelineJsonPath, timelineV2Schema, timelineView, transcribeBatch, transcribeOne, transcriptFileForSource, transcriptPath, updateCaptionsBlock, usesFromDoc, validateTimeline, verify, videoStream, wordStream, writeAgentManifest, writeBoundaries, writeCompileArtifacts, writeCoverage, writeSilencePrompt, writeTranscriptArtifacts, writeVideoEditingPrompt, writeWarningsFromReview, writeWordDump };
+export { type Anchor, type AssetCreate, type AudioItem, CAPABILITIES, CAPTION_STYLE_DEFAULTS, type Capability, type CapabilityStatus, type CaptionOverride, type CaptionPreset, type CaptionStyle, type ChangeOutcome2, type ClientOptions, CloudClient, type CloudFlags, CloudHttpError, type CompileRemoteResult, type CutBoundary, type CutRange, DEFAULT_DOWNLOAD_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, type Diagnostic, type Diagnostics, type Edl, type EdlRange, type FeatureKey, type FetchLike, type FileSource, type FilesPullResult, type GradeSetting, INLINE_MAX_BYTES, type InitOptions, type InitResult, type InstallResult, type JobFile, type LoadedTimeline2, MAX_POLL_MS, MAX_RUN_POLL_MS, MULTIPART_THRESHOLD_BYTES, type MultipartOptions, type MultipartSource, type OutputAnchor, type OverlayFx, type OverlayItem, type ParseResult, type PhraseMatch, type PhraseSuggestion, type PollOptions, type Provenance, type PullReview2Result, type PulledFile, type Push2Failure, type PushComplete2Success, type PushTimeline2Success, type PushedFile, type QaPlanSegment, type QaSourceWindow, RELAY_DIRECT_ATTEMPTS, RELAY_SUBCHUNK_BYTES, REVIEW_STAGES2, type RenderCreate, type RenderMode, type RenderState, type RenderStatus, type ResolveOptions, type ResolveOutcome, type ResolvedConfig, type ReviewChange, type ReviewRound, type ReviewSession, type RunEvent, type RunPollOptions, type RunState, type RunStatus, type ScribeTranscript, type ScribeWord, type SourceAnchor, type StreamWord, type TimelineSettings, type TimelineSource, type TimelineV2, type Transcribe2Options, type Transcribe2Result, type Verify2Options, type Verify2Result, type VerifyJoinFinding, type VerifyResult, type VfsFileContent, type VfsFileEntry, type VfsPresign, type WordsAnchor, type ZoomItem, assertRunCompleted, assetContentType2, assetsUrl, bundledSkillDir, bytesSource, checkCapabilities, collectPlanAssetRefs2, compileRemote, compileUrl, composeUrl, defaultRenderOut, defaultSkillTarget, diagnosticsPath2, downloadTo, emptyDiagnostics, filesUrl, findPhrase, formatRunEvent, framesPngPath, fuzzySuggestions, ingestArtifactSet, ingestUrl, initCloudJob, installSkill, instructionPath2, isTerminalRunStatus, isTerminalStatus, jobJsonPath, joinSourceWindows, loadPublicConfigEnv, loadTimeline2, meUrl, multipartRelayUrl, multipartUrl, normalizePhrase, normalizeToken, openFileSource, outWindowToSourceWindows, parseFileContent, parseFileList, parseFilePresign, parseRenderCreate, parseRenderState, parseRunState, parseTimeline, planPath2, pollRender, pollRun, projectVideosUrl, projectsUrl, publicConfigDir, publicConfigEnvPath, pullFiles, pullReview2, pushComplete2, pushFiles, pushStage2, pushTimeline2, qaDir, readJobFile, readOutcomesFile2, readPlanSegments, readProbeDuration, renderUrl, rendersUrl, resolveApiBase, resolveApiKey, resolveConfig, resolvePhrase, resolveRunId2, resolveUrl, resolveVideoId, reviewDir2, reviewUrl, roundJsonPath2, runUrl, sameSha, sanitizeStem, savePublicConfigKey, sha256Hex, shouldMultipart, statAssetsForDoc, stripTrailingSlash, syncAssets2, timelineJsonPath2, timelineV2Schema, toVfsPath, transcribeArtifactSet, transcribeCloud, transcribeUrl, uploadMultipart, uploadVfsBytes, uploadVfsPayload, usesFromDoc, validateLocal, validateTimeline, verifyCloud, verifyUrl, vfsContentType, vfsLocalPath, videoIdFromJob, waveformPngPath, waveformWordsPath, wordStream, writeJobFile };