/**
 * Mograph — style-locked motion-graphics lane. Shared types for the
 * motion-sheet / motion-pack artifacts and the render plan.
 *
 * Design contract: docs/design/specs/2026-07-13-mograph-native-port.md.
 * Canonical artifact shapes: schemas/video/artifacts/motion-sheet.schema.json
 * and motion-pack.schema.json.
 */

export type MographPriority = 'P1' | 'P2' | 'P3';

export type MographBlockMode =
  | 't2v'
  | 'ref2v'
  | 'v2v-stylize'
  | 'v2v-overlay'
  | 'v2v-transition'
  | 'v2v-inset';

export type CoveragePlan = 'generated' | 'v2v' | 'talking-head' | 'screen-rec' | 'reuse';

export interface MotionSheetStage {
  mode: 'locked' | 'free';
  description?: string;
}

export interface MotionSheetRefImage {
  path: string;
  version: number;
  approvedAt?: string;
}

export interface MotionSheetLogoRef {
  brand: string;
  path: string;
  source?: string;
}

export interface MotionSheetPaletteEntry {
  name: string;
  hex: string;
  role?: string;
}

export interface MotionSheetTypeRole {
  role: string;
  treatment: string;
}

/**
 * The film's hero object (a product, a mark, a building) and its ONE identity
 * anchor — the design feature the generator must keep in every frame. Code
 * stacks it above every block prompt, so a split film restates it in full
 * without the author re-typing it (and without tripping the hand-restate lint).
 */
export interface MotionSheetHero {
  descriptor: string;
  /** A feature, never a material or a colour: "one copper ring under the cap". */
  anchor: string;
}

/**
 * Style-lock word budget. `fleet` (default) is sized for ~100 clips where every
 * word is paid N times; `film` lifts the cap for a 2–4 block launch/product
 * film whose lock must also carry the hero, palette roles and render rules.
 */
export type MotionSheetBudget = 'fleet' | 'film';

export interface MotionSheetArtifact {
  schemaVersion: 1;
  projectSlug: string;
  sheetId: string;
  family: string;
  generatedAt: string;
  canonicalDescription?: string;
  masterImagePrompt?: string;
  /** ≤120 words, attached VERBATIM to every clip prompt. */
  styleLock: string;
  /** Always ends with the five audio bans (see AUDIO_BAN_TAIL). */
  negative: string;
  audioIdentity?: string;
  energy?: string;
  stage?: MotionSheetStage;
  hero?: MotionSheetHero;
  budget?: MotionSheetBudget;
  refImage?: MotionSheetRefImage;
  refImageHistory?: MotionSheetRefImage[];
  logoRefs?: MotionSheetLogoRef[];
  palette?: MotionSheetPaletteEntry[];
  typeRoles?: MotionSheetTypeRole[];
  components?: string[];
  gotchas?: string[];
  locked?: boolean;
  version?: number;
}

export interface MotionPackCoverageRow {
  segment: string;
  t0Sec: number;
  t1Sec: number;
  voGist?: string;
  plan: CoveragePlan;
  blockIds?: string[];
}

export interface MotionPackBlock {
  /** Stable id, `B###` (optional trailing letter for post-render inserts). */
  id: string;
  t0Sec: number;
  t1Sec: number;
  priority: MographPriority;
  mode: MographBlockMode;
  /** The exact transcript clause the clip sits under (never sent to the model). */
  vo?: string;
  /** 2-4 sound-design cues, diegetic to the motion. Never music or narration. */
  sfx?: string[];
  /** Extra per-block reference images (logos, product shots) — paths. */
  refs?: string[];
  loop?: boolean;
  /** Required for every v2v-* mode: the source footage path. */
  videoSource?: string;
  /** Pure choreography, ≤90 words, no style vocabulary. */
  action: string;
}

export interface MotionPackArtifact {
  schemaVersion: 1;
  projectSlug: string;
  video: string;
  sheetId: string;
  generatedAt: string;
  route?: string;
  model?: string;
  aspect: string;
  durationSec: number;
  timing: 'draft' | 'final';
  logoRefs?: string[];
  /**
   * Every on-screen string in the film, once, verbatim — the copy-list
   * contract. `*word*` marks the one accent word of a headline. When present,
   * a quoted string in any block that is not listed here is a lint error.
   */
  copyList?: string[];
  coverage?: MotionPackCoverageRow[];
  blocks: MotionPackBlock[];
}

/** One timed transcript beat (input to pack authoring). */
export interface TranscriptBeat {
  index: number;
  t0Sec: number;
  t1Sec: number;
  text: string;
  /** True when a hard pause follows this beat (natural clip boundary). */
  pauseAfter?: boolean;
}

export interface MographLintIssue {
  code: string;
  severity: 'error' | 'warning';
  blockId?: string;
  message: string;
}

export interface MographLintResult {
  ok: boolean;
  errors: MographLintIssue[];
  warnings: MographLintIssue[];
}

/** One planned submission — the exact prompt + references a provider will get. */
export interface MographSubmission {
  blockId: string;
  priority: MographPriority;
  mode: MographBlockMode;
  prompt: string;
  /** Reference images, sheet ref first. */
  refs: string[];
  videoSource?: string;
  durationSec: number;
  aspect: string;
  route: string;
}