export const PREVIEW_PORTAL_SURFACES = [
  'edit',
  'review',
  'client-review',
  'preview',
  'compare',
  'index',
  // The live run dashboard: per-generation status badges + contract/diff cards +
  // playable in-progress clips + an event log, auto-refreshing against on-disk
  // state. Driven by show-bible (Show › Episode › Generation), scene-candidates
  // (status), run-contract (the diff-vs-contract alarm baseline), and
  // events.jsonl (the log).
  'run',
] as const;

export const PREVIEW_PORTAL_STATUSES = [
  'draft',
  'editor-review',
  'changes-requested',
  'client-review',
  'client-declined',
  'client-approved',
  'final',
  'published',
  'archived',
] as const;

export const PREVIEW_PORTAL_TEMPLATES = [
  'music-video',
  'story-film',
  'documentary',
  'product-ad',
  'sports-recap',
  'generic-video',
] as const;

export type PreviewPortalSurface = typeof PREVIEW_PORTAL_SURFACES[number];
export type PreviewPortalStatus = typeof PREVIEW_PORTAL_STATUSES[number];
export type PreviewPortalTemplateId = typeof PREVIEW_PORTAL_TEMPLATES[number];

export interface PreviewPortalTemplate {
  id: PreviewPortalTemplateId;
  name: string;
  heroLabel: string;
  primaryAssetLabel: string;
  sectionOrder: string[];
  sectionLabels: Record<string, string>;
}

export interface PreviewPortalAsset {
  id: string;
  path: string;
  kind: 'image' | 'video' | 'audio' | 'html' | 'json' | 'text' | 'other';
  label: string;
  section: string;
  sizeBytes?: number;
  exists: boolean;
  /** ISO timestamp of when the file was created/downloaded on disk (file mtime).
   * Rendered on each card so the operator sees when an asset landed. */
  createdAt?: string;
  /** Scene index for keyframe/generation-input assets, used to pair them with
   * their storyboard beat. Carried through from the asset-manifest. */
  sceneIndex?: number;
  /** Real pixel dimensions probed at discovery (ffprobe for video, header parse
   * for stills). Drive PER-ASSET card sizing: a 9:16 deliverable must render in
   * a portrait card even inside a 16:9 project. Unset when probing fails. */
  width?: number;
  height?: number;
  orientation?: 'portrait' | 'square' | 'landscape';
}

export interface PreviewPortalBriefMetadata {
  platform?: string;
  executionProfile?: {
    aspectRatio?: string;
    quality?: string;
    resolution?: string;
    generateAudio?: boolean;
    outputCount?: number;
  };
  [key: string]: unknown;
}

/** Brief artifact subset rendered in the preview header. */
export interface PreviewPortalBrief {
  title: string;
  intent: string;
  metadata?: PreviewPortalBriefMetadata;
}

export interface PreviewPortalScene {
  sceneIndex: number;
  description: string;
  characters?: string[];
  scenePrompt?: {
    imagePrompt?: string;
    animationPrompt?: string;
    cameraMove?: string;
    styleFooter?: string;
  };
  /**
   * The exact provider submit text for this scene — the resolved
   * `filmmaking-prompts.json` seedance packet (`seedancePackets[].promptText`,
   * the 10-block Joey master prompt) matched by sceneIndex. This is the
   * "what the model actually receives" contract; when present it is the
   * authoritative prompt rendered in the scene card, above the lighter
   * storyboard `scenePrompt` fields.
   */
  renderPrompt?: string;
  /**
   * The reference slots this scene will submit (`seedancePackets[].references`),
   * each with its role, ready/pending status, and — for character-sheet slots —
   * the bound `Asset://` URI resolved from `seedance-assets.json`. Surfacing this
   * lets the operator confirm identity-lock (which avatar locks which scene, and
   * whether every required reference is ready) before any render spend.
   */
  referenceSlots?: PreviewPortalReferenceSlot[];
  /**
   * Optional narrative color-language state for this scene (the grade id, e.g.
   * `cool-steel` / `crimson-threat` / `electric-blue`). Rendered as a swatched
   * chip in the contract card so the operator sees the intended look per scene,
   * and applied as the per-segment grade at assemble time.
   */
  colorState?: string;
  dialogue?: string;
  durationSeconds?: number;
  /**
   * Project-relative path to this scene's rendered clip
   * (`outputs/scene-<sceneIndex>.mp4`), present only when the file exists on disk.
   * When set, the storyboard card renders an inline `<video>` plus an
   * Image/Video toggle (keyframe shown by default, clip on demand). Absent → the
   * card renders byte-identically to before (keyframe image + download only).
   */
  clipPath?: string;
}

export interface PreviewPortalReferenceSlot {
  slot: string;
  role: string;
  label: string;
  status: 'ready' | 'pending';
  path?: string;
  characterName?: string;
  /** Bound Asset Library URI (e.g. `Asset://...`) for character-sheet slots,
   * resolved from seedance-assets.json by character name. Absent until the
   * character's avatar is registered via `vclaw video seedance-register-assets`. */
  assetUri?: string;
}

/** Storyboard artifact subset rendered as scene cards paired with keyframes. */
export interface PreviewPortalStoryboard {
  scenes: PreviewPortalScene[];
}

/** Per-generation live status code (= storyboard scene), derived from
 * scene-candidates + execution-report + outputs/ on disk. */
export type PreviewPortalGenerationStatus = 'done' | 'rendering' | 'failed' | 'pending' | 'unknown';

/**
 * One "generation" on the live run dashboard: a storyboard scene's runtime
 * STATUS (badge + provider job id + error), its rendered clip (when complete),
 * and the diff-vs-contract alarm (whether the submitted payload diverged from
 * the current contract). Hung off the scene by sceneIndex in discovery; absent
 * fields degrade gracefully (a scene never submitted has status 'pending').
 */
export interface PreviewPortalGeneration {
  sceneIndex: number;
  status: PreviewPortalGenerationStatus;
  /** Provider job id for the latest candidate (or the single-job legacy id). */
  externalJobId?: string;
  /** Provider/blocker error text surfaced on a failed generation. */
  error?: string;
  /** Project-relative path to the rendered clip (outputs/scene-N.mp4 or a
   * candidate output) when one exists on disk. */
  clipPath?: string;
  /** True when the submitted payload diverged from the current contract — the
   * @tag-hijack alarm. Only set once a scene was submitted (has a run-contract
   * entry). */
  contractDiverged?: boolean;
  /** Human reason + the diverged field names, for the red alarm body. */
  divergenceReason?: string;
  divergedFields?: string[];
}

/** One row in the run dashboard's event log (from events/events.jsonl). */
export interface PreviewPortalRunEvent {
  recordedAt: string;
  type: string;
  /** Compact one-line payload summary (job id / scene / status), already
   * stringified at discovery so the renderer stays pure. */
  summary?: string;
}

/**
 * The show registry header (from artifacts/show-bible.json) driving the run
 * dashboard's Show › Episode › Generation nav. Absent → the dashboard degrades
 * to a single flat generation grid for the current project.
 */
export interface PreviewPortalShow {
  showTitle: string;
  premise?: string;
  style?: string;
  episodes: Array<{ id: string; title: string; logline?: string }>;
}

/** Spend estimate chip on the run dashboard (from cost-estimate + telemetry). */
export interface PreviewPortalSpend {
  estimateUsd: number;
  estimateSource: 'static-default' | 'historical-telemetry';
  wallTimeMinutes: number;
  /** Summed actual USD across completed telemetry entries, when any exist. */
  actualUsd?: number;
}

/** The discovered live-run state backing the `run` surface. */
export interface PreviewPortalRunState {
  generations: PreviewPortalGeneration[];
  events: PreviewPortalRunEvent[];
  show?: PreviewPortalShow;
  spend?: PreviewPortalSpend;
  /** Auto-refresh interval (seconds) baked into the run `<head>` meta tag. */
  refreshSeconds: number;
}

export interface PreviewPortalCard {
  id: string;
  kind: 'character' | 'scene' | 'clip' | 'final' | 'version' | 'asset' | 'run';
  title: string;
  subtitle?: string;
  assetIds: string[];
  reviewable: boolean;
}

export interface PreviewPortalRun {
  runId: string;
  label: string;
  status: PreviewPortalStatus;
  createdAt: string;
  updatedAt: string;
  publishedAt?: string | null;
  approvedAt?: string | null;
  declinedAt?: string | null;
}

/** One palette entry surfaced from brand-definition.json, in role order. */
export interface PreviewPortalBrandColor {
  role: string;
  hex: string;
  name?: string;
}

/**
 * The client's locked brand system (subset of `artifacts/brand-definition.json`)
 * used to theme the preview + client-review surfaces: accent/glow from the
 * palette, header wordmark/logo, hero tagline, and the brand-book annex.
 * Absent → the portal renders its stock theme, visually unchanged.
 */
export interface PreviewPortalBrand {
  brandName: string;
  positioning?: string;
  taglines?: { functional?: string; emotional?: string; community?: string };
  palette: PreviewPortalBrandColor[];
  typography: Array<{ level: string; font: string; weight: string }>;
  /** Project-relative path to a discovered client logo (assets/brand/logo.*). */
  logoPath?: string;
}

/**
 * One locked identity in the production: a registered Flow Character (from
 * `artifacts/flow-characters.json`) or a reference character (from
 * `characters/characters.json`). Surfaced as the portal's Cast section so the
 * client can see who/what is identity-locked across every shot.
 */
export interface PreviewPortalCastMember {
  name: string;
  source: 'flow-character' | 'character';
  /** Stable id (entityId for Flow Characters) shown beneath the name. */
  ref?: string;
  /** Project-relative still matched to this name (else a monogram renders). */
  stillPath?: string;
  /** e.g. 'product master' when the name reads as the brand master asset. */
  role?: string;
}

export interface PreviewPortalProject {
  client?: string | null;
  slug: string;
  title: string;
  template: PreviewPortalTemplateId;
  status: PreviewPortalStatus;
  projectDir: string;
  run: PreviewPortalRun;
  summary?: string;
  /** Optional locked brand system — themes the client-facing surfaces. */
  brand?: PreviewPortalBrand;
  /** Registered cast / identity locks (Flow Characters + reference characters). */
  cast?: PreviewPortalCastMember[];
  /** Optional brief artifact, rendered as the preview's Brief header. */
  brief?: PreviewPortalBrief;
  /** Optional storyboard artifact, rendered as scene cards paired with keyframes. */
  storyboard?: PreviewPortalStoryboard;
  /**
   * Optional live-run state backing the `run` dashboard surface: per-generation
   * status + diff-vs-contract alarm, the event log, the show-bible nav header,
   * and the spend estimate. Discovered only when the run surface is being
   * generated (it is the heavier discovery path) — absent on the
   * review/preview/compare surfaces, which never read it.
   */
  runState?: PreviewPortalRunState;
  assets: PreviewPortalAsset[];
  cards: PreviewPortalCard[];
  /**
   * Optional project soundtrack/score. When present, the polished `preview`
   * showcase renders an `<audio controls preload="none">` player; when absent,
   * no audio element is emitted. Discovered from an audio asset (.mp3/.m4a/.wav)
   * or a `soundtrack`/`audio` manifest field.
   */
  soundtrack?: PreviewPortalSoundtrack;
  /**
   * Optional cloned-voice references, keyed by the character they belong to,
   * discovered from `artifacts/voice-clones.json`. When a scene casts a character
   * with a matching voice clone, the per-scene review contract renders a Voice
   * design block (a labeled, playable `<audio>` per voice) and the exact-submit
   * JSON's `videoAssetId`/`videoAssetId2` fields. Absent → no voice block and
   * byte-identical output.
   */
  voiceClones?: PreviewPortalVoiceClone[];
}

/**
 * One cloned-voice reference bound to a character, projected from
 * `artifacts/voice-clones.json`. `src` is the playable URL (the durable hosted
 * URL when present, else the local clip path). Rendered in the per-scene Voice
 * design contract block.
 */
export interface PreviewPortalVoiceClone {
  /** Character the voice belongs to (the scene-cast match key, case-insensitive). */
  character: string;
  /** Human-readable label for the voice row (name/character/description). */
  label: string;
  /** Playable audio source: the hosted URL when present, else the local clip path. */
  src: string;
  /** Optional clip length in seconds (from durationMs), shown in the label. */
  durationSeconds?: number;
}

export interface PreviewPortalSoundtrack {
  /** Project-relative path to the headline (selected, or sole) audio file. */
  path: string;
  /** Human-readable label for the headline track. */
  label: string;
  /**
   * Optional A/B candidate list (from soundtrack.json). When present and longer
   * than one entry, the preview renders an audio player per candidate so a human
   * can compare/pick; the candidate matching `path` is the headline. Absent for
   * legacy single-soundtrack projects (no soundtrack.json).
   */
  candidates?: PreviewPortalSoundtrackCandidate[];
}

export interface PreviewPortalSoundtrackCandidate {
  /** Backend that produced the candidate (e.g. 'suno', 'lyria'). */
  backendId: string;
  /** Project-relative path to the candidate audio file. */
  path: string;
  /** Human-readable label for the candidate. */
  label: string;
  /** True when this is the human-selected headline candidate. */
  selected: boolean;
}

export interface PreviewPortalRenderOptions {
  surface: PreviewPortalSurface;
  project: PreviewPortalProject;
  compareProjects?: PreviewPortalProject[];
}

export interface PreviewPortalIndexRenderOptions {
  projects: PreviewPortalProject[];
  client?: string | null;
  title?: string;
  generatedAt?: string;
  linkPrefix?: string;
  linkMode?: 'local' | 'published-run';
}

export interface PreviewPortalAuditEvent {
  timestamp: string;
  event:
    | 'surface.generated'
    | 'surface.published'
    | 'client.feedback.copied'
    | 'editor.review.copied'
    | 'run.created'
    | 'run.promoted';
  client?: string | null;
  project: string;
  run: string;
  surface?: PreviewPortalSurface;
  template?: PreviewPortalTemplateId;
  output?: string;
  assetCount?: number;
  url?: string;
  htmlHash?: string;
  status?: PreviewPortalStatus;
}