/**
 * DocDoe Cinematic Video Engine — Strict Type System
 *
 * These types form the contract between the AI script generator and the
 * Remotion-based visual renderer. Keep them narrow and explicit — avoid `string`
 * wherever a union works.
 *
 * NO framer-motion in any component that imports from this file.
 * All animation must use Remotion's interpolate() / spring() / useCurrentFrame().
 */

// ---------------------------------------------------------------------------
// Scene type union — maps every AI-generated scene to a visual template
// ---------------------------------------------------------------------------

export type SceneType =
  | "hook"      // Opening attention grab — large, bold, dramatic
  | "explain"   // Core teaching content — hologram board, keywords, body text
  | "keyword"   // Vocabulary/definition spotlight — big term + meaning chips
  | "pyq"       // Past year question — exam paper style, marks badge, answer reveal
  | "quiz"      // Interactive check — question + choices or blank fill
  | "recap"     // Summary cards — numbered key points
  | "mentor";   // Direct-to-camera personal coaching tone — warm, close framing

// ---------------------------------------------------------------------------
// Supporting value types
// ---------------------------------------------------------------------------

export type MentorEmotion =
  | "explaining"
  | "excited"
  | "thinking"
  | "serious"
  | "recap"
  | "doubt"
  | "study";

export type CameraMotion = "dolly_in" | "dolly_out" | "pan_left" | "pan_right" | "static";

export type VisualHintType = "diagram" | "equation" | "list" | "comparison" | "none";

export type VisualHint = {
  type: VisualHintType;
  label?: string;
  items?: string[];
};

export type SubtitleSegment = {
  /** Seconds from scene start */
  start: number;
  end: number;
  text: string;
};

export type ExamFocusData = {
  question: string;
  answer: string;
  marks: number;
  exam_year?: number;
  /** How many times asked in past papers */
  frequency?: number;
};

// ---------------------------------------------------------------------------
// Core scene and plan types
// ---------------------------------------------------------------------------

export type VideoScene = {
  scene_id: number;
  type: SceneType;
  duration_seconds: number;
  /** Headline text — short, displayed large at top of board */
  title: string;
  /** Body explanation text — 1-3 sentences */
  body: string;
  /** TTS narration text — may differ from body */
  voice_text: string;
  /** Max 6 keyword chips shown as staggered tags */
  keywords: string[];
  visual_hint: VisualHint;
  subtitle_segments?: SubtitleSegment[];
  mentor_emotion?: MentorEmotion;
  camera_motion?: CameraMotion;
  /** PYQ scene data — used when type === "pyq" */
  exam_focus?: ExamFocusData;
  audio_src?: string;
  is_mock_audio?: boolean;
};

export type VideoPlan = {
  /** Stable plan identifier (used as Remotion composition key) */
  id: string;
  title: string;
  subject: string;
  chapter?: string;
  language: string;
  duration_minutes: number;
  /** Override computed total when provided by backend */
  total_duration_seconds?: number;
  scenes: VideoScene[];
  /** Whether the Nila teacher character is shown */
  show_mentor: boolean;
  /** Shows "Preview" watermark in top-right corner */
  show_preview_watermark?: boolean;
};

// ---------------------------------------------------------------------------
// Engine configuration
// ---------------------------------------------------------------------------

export type VideoEngineConfig = {
  fps: number;
  width: number;
  height: number;
  format: "16:9" | "9:16";
};

export const VIDEO_ENGINE_FPS = 30 as const;

export const DEFAULT_CONFIG: VideoEngineConfig = {
  fps: VIDEO_ENGINE_FPS,
  width: 1920,
  height: 1080,
  format: "16:9",
} as const;

export const VERTICAL_CONFIG: VideoEngineConfig = {
  fps: VIDEO_ENGINE_FPS,
  width: 1080,
  height: 1920,
  format: "9:16",
} as const;

// ---------------------------------------------------------------------------
// Interop helpers — adapt existing ExplainerScene → VideoScene
// ---------------------------------------------------------------------------

/** Minimal ExplainerScene fields needed by the interop adapter */
export type LegacySceneInput = {
  scene_id: number;
  type: string;
  duration_seconds: number;
  screen_text: string;
  voice_text: string;
  keywords: string[];
  visual_hint: string;
  subtitle_segments?: Array<{ start: number; end: number; text: string }>;
  mascot_expression?: string | null;
};