Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

98.5 KB
Raw Blame
import { MUSIC_VIDEO_MEDIA_MODES } from './musicVideoMediaPolicy.js';
import { MUSIC_VIDEO_GRADE_PRESETS, MUSIC_VIDEO_GRADE_MAX_GRAIN } from './musicVideoGrade.js';
import { filmLookSchema } from './filmLookValidation.js';
import { TITLE_CARD_FONTS, TITLE_CARD_LIMITS, TITLE_CARD_POSITIONS, TITLE_CARD_STYLES } from './musicVideoTitleCard.js';
import { STATS_OUTRO_LIMITS, STATS_OUTRO_LINES } from './musicVideoStatsOutro.js';
import { COVER_DESIGN_OPTIONS } from './musicVideoCoverOverlay.js';
import { DISTROKID_REMEMBERED_OPTIONS } from './distrokidGenres.js';
import { CROSS_LINK_EDIT_TARGETS } from './musicVideoCrossLinks.js';
/**
 * Music Video production mode — Zod schemas + shared enums (issue #1760, Phase 1).
 *
 * Validates the `musicVideoProject` db-primary record's route inputs: project
 * create/update, the per-scene create/update/reorder operations of the director
 * scene board, and the cached audio-analysis shape (produced by
 * services/musicVideo/audioAnalysis.js, Phase 0). Re-exported flat from
 * validation.js and as a namespace from server/lib/index.js.
 */

import { z } from 'zod';
import { GROK_VIDEO_DURATIONS } from './grokVideoClip.js';
import { knownFilmStyleIdSchema } from './filmStyleGrammars.js';

const makingOfId = z.string().regex(/^[A-Za-z0-9_-]{1,100}$/);
export const musicVideoMakingOfSelectionSchema = z.object({
  projects: z.array(z.object({
    projectId: makingOfId,
    snapshot: z.string().regex(/^[a-f0-9]{64}$/),
    assets: z.array(z.object({
      id: z.string().min(1).max(250),
      rights: z.enum(['unknown', 'owned', 'licensed']).default('unknown'),
      attribution: z.string().max(2000).default(''),
      ownershipConfirmed: z.boolean().default(false),
    }).strict()).max(300),
  }).strict()).min(1).max(8),
  previewDigest: z.string().regex(/^[a-f0-9]{64}$/).optional(),
}).strict().superRefine((selection, ctx) => {
  if (new Set(selection.projects.map(p => p.projectId)).size !== selection.projects.length
    || selection.projects.some(p => new Set(p.assets.map(a => a.id)).size !== p.assets.length)) {
    ctx.addIssue({ code: 'custom', message: 'Duplicate project or asset selection' });
  }
});

export const musicVideoSongDraftSchema = z.object({
  title: z.string().trim().min(1).max(80), style: z.string().trim().min(1).max(1000),
  lyrics: z.string().max(5000), instrumental: z.boolean().default(false),
}).strict().refine((v) => v.instrumental || v.lyrics.trim().length > 0, 'Lyrics are required for a vocal song');
export const musicVideoSongActionSchema = z.object({ revisionId: z.string().min(1) }).strict();
export const musicVideoSongSelectSchema = z.object({ revisionId: z.string().min(1), songId: z.string().min(1) }).strict();
// Revise the song from a library track (an imported Suno link): forks a new version on it.
export const musicVideoSongFromTrackSchema = z.object({ trackId: z.string().min(1).max(128) }).strict();
import { EFFORT_LEVELS } from './providerModels.js';
import { shotActionContractProblem } from './musicVideoActionContract.js';
import { NARRATIVE_EVENT_KINDS } from './musicVideoNarrativeEvents.js';
import { MUSIC_VIDEO_MEDIA } from './musicVideoMediumPlan.js';
import { CLIP_OFFSET_FRAMES_RANGE, CLIP_SPEED_FPS_RANGE, MUSIC_VIDEO_FRAME_FITS, MUSIC_VIDEO_LYRIC_ROLES, MUSIC_VIDEO_LYRIC_SIZES, MUSIC_VIDEO_STILL_MOVES, MUSIC_VIDEO_TEXT_ZONES, MUSIC_VIDEO_VISUAL_LAYERS } from './musicVideoLayers.js';
import { MUSIC_VIDEO_SHOT_GLITCH_LIMIT, MUSIC_VIDEO_TRANSITIONS } from './musicVideoTransitions.js';
import { BEAT_TOGGLE_OVERLAP, BEAT_TOGGLE_RATES, MUSIC_VIDEO_CUT_EFFECTS } from './musicVideoCutEffects.js';
import { IMAGE_EFFECT_SEC_RANGE, MUSIC_VIDEO_IMAGE_EFFECTS } from './musicVideoImageEffects.js';
import { CAMERA_FRAMINGS, CAMERA_MOVEMENT_VALUES, CAMERA_SPEEDS } from './cameraMovements.js';
import { CAST_ERAS } from './catalogMediaLibrary.js';
import { STORYBOARD_ID_PATTERN } from './storyboardVocabulary.js';
import { MUSIC_VIDEO_PERFORMANCE_STYLES, MUSIC_VIDEO_SHOT_MODES, SOURCE_AUDIO_LIPSYNC } from './musicVideoShotTiming.js';
import {
  MUSIC_VIDEO_AUTOMATION_BUDGET_MAX_USD,
  MUSIC_VIDEO_AUTOMATION_GUIDANCE_MAX,
  MUSIC_VIDEO_AUTOMATION_TOOL_IDS,
  MUSIC_VIDEO_LLM_STAGES,
  MUSIC_VIDEO_CHECKIN_MODES,
} from './musicVideoAutomation.js';
import {
  AUTONOMOUS_AUTO_APPROVE_STAGES,
  AUTONOMOUS_CHECKPOINT_IDS,
  AUTONOMOUS_LIMIT_BOUNDS,
  AUTONOMOUS_NAME_MAX,
  AUTONOMOUS_ORIGINS,
  AUTONOMOUS_PROMPT_MAX,
  AUTONOMOUS_SONG_SOURCES,
  LOCAL_MUSIC_CODE_LANGUAGES,
  LOCAL_MUSIC_TYPES,
  SUNO_LIMITS,
  SUNO_MODEL_PATTERN,
  SUNO_VOCAL_GENDERS,
  normalizeAutoApprove,
} from './musicVideoAutonomous.js';
import { MUSCRIPTOR_MODELS } from './muscriptorModels.js';
import { MUSIC_VIDEO_CHARACTER_STYLE_IDS } from './musicVideoCharacterStyles.js';
import { IMAGE_GEN_MODES, VIDEO_GEN_MODES } from './generationModes.js';

// A project is authored hands-on (director) or seeded by the AI planner
// (autonomous); both share the same record + scene board.
export const MUSIC_VIDEO_MODES = ['director', 'autonomous'];

// Lifecycle. `draft` → has scenes/analysis → `ready` → `rendering` → `complete`
// (or `failed`). `analyzed` marks "beat map cached but not yet arranged".
export const MUSIC_VIDEO_STATUSES = ['draft', 'analyzed', 'ready', 'rendering', 'complete', 'failed'];

// Re-read a project's song style from its Suno song link.
// Explicit cleanup keeps comparison looks unless the director opts to purge them.
export const musicVideoRenderCleanupSchema = z.object({ unusedLooks: z.boolean().optional() }).strict();

// The rendered-so-far player: `light` asks for the lighter phone copy.
export const musicVideoRenderPreviewSchema = z.object({ light: z.boolean().optional() }).strict();
export const musicVideoSongStyleSunoSchema = z.object({ url: z.string().trim().min(1).max(2000) });

// Optional global visual direction for the whole video.
export const musicVideoConceptSchema = z.object({
  prompt: z.string().max(8000).optional(),
  // The director's visual style, appended to every frame and shot prompt.
  style: z.string().max(2000).optional(),
  // The song's own style (the Suno style prompt, excluded styles included),
  // snapshotted from the track. Planning LLMs translate it into design; it
  // never reaches an image or video prompt verbatim.
  songStyle: z.string().max(2000).optional(),
  universeId: z.string().max(64).nullable().optional(),
  // Authored snapshots keep the production stable when source canon changes.
  universeStyle: z.string().max(4000).optional(),
  moodBoardStyle: z.string().max(4000).optional(),
  // A built-in character style (musicVideoCharacterStyles.js); the server
  // snapshots its text into `characterStyle` and casts its character.
  characterStyleId: z.enum(MUSIC_VIDEO_CHARACTER_STYLE_IDS).nullable().optional(),
  characterStyle: z.string().max(4000).optional(),
  subjects: z.array(z.object({
    id: z.string().min(1).max(64),
    kind: z.enum(['character', 'place', 'object']),
    name: z.string().trim().min(1).max(120),
    description: z.string().max(1000).optional(),
    role: z.enum(['protagonist', 'band', 'supporting']).optional(),
    canonId: z.string().max(64).optional(),
    // The catalog record this subject was cast from (Casting / Environments /
    // Objects). The project keeps its own name and description snapshot.
    ingredientId: z.string().max(128).optional(),
    // Kept in this video only: never offered for saving to the catalog.
    localOnly: z.boolean().optional(),
  }).strict()).max(24).optional(),
}).strict();

// Renderer settings travel with the project so reopening a director board (or
// opening it on a sync peer) cannot silently change provider/model. `modelId`
// is optional because Grok does not consume it; the video-gen route performs
// the authoritative installed-model validation when a local render starts.
export const musicVideoVideoSettingsSchema = z.object({
  renderPool: z.object({
    mode: z.enum(['local', 'peers', 'both']),
    peers: z.array(z.object({ peerId: z.string().uuid(), modelId: z.string().trim().min(1).max(256) }).strict()).max(12),
  }).strict().refine((v) => v.mode === 'local' || v.peers.length > 0, { message: 'Select at least one peer model' })
    .refine((v) => new Set(v.peers.map((p) => p.peerId)).size === v.peers.length, { message: 'Choose one model per peer' }).optional(),
  // null clears the per-project pin so this install's configured default wins.
  // 'fal' is the metered fal.ai queue REST backend (server/services/videoGen/fal.js,
  // #8968) — image-to-video only here; the audio-reactive lane stays local-only
  // (see generationMode below). 'runway' is Runway's developer API
  // (services/videoGen/runway.js), cutaways only.
  backend: z.enum(['local', 'grok', 'fal', 'runway']).nullable().optional(),
  modelId: z.string().max(64).nullable().optional(),
  grokDuration: z.union(GROK_VIDEO_DURATIONS.map((d) => z.literal(d))).optional(),
  // fal.ai clip length in seconds. Loosely bounded (not a closed enum) for the
  // same reason routes/videoGen.js's falDuration is: fal's own model catalog,
  // not PortOS, owns the set of valid durations per model. null/omitted lets
  // the backend's model default apply.
  falDuration: z.number().min(1).max(60).nullable().optional(),
  // fal.ai cutaway model (lib/falVideoModels.js) and its output resolution.
  // Loosely validated like routes/videoGen.js's falModelId/falResolution: a
  // peer on a newer catalog may pin a model this install does not curate yet,
  // and the resolution alphabet is per model — the provider resolves both (an
  // uncurated id renders on the legacy body with its cost reported unknown).
  // null/omitted = the default model (Hailuo-02 image-to-video) / its default.
  falModelId: z.string().min(1).max(200).nullable().optional(),
  falResolution: z.string().min(1).max(16).nullable().optional(),
  // Upgrade model for shots with a style-break end frame (one that takes an
  // end frame, e.g. Kling v3 Pro); null/omitted = those shots use falModelId.
  falEndFrameModelId: z.string().min(1).max(200).nullable().optional(),
  // Output resolution of a performance (lip-sync) take — fal's own alphabet
  // for the lip-sync route. null/omitted = MUSIC_VIDEO_LIPSYNC_DEFAULT_RESOLUTION.
  falLipSyncResolution: z.enum(SOURCE_AUDIO_LIPSYNC.fal.resolutions).nullable().optional(),
  // false = lip-sync to the audio alone, without the provider transcribing it
  // first (sung words it mishears turn into the wrong mouth shapes).
  falLipSyncTranscription: z.boolean().nullable().optional(),
  // Audio-to-video model and resolution for music-driven performance takes
  // (scene.performanceStyle 'music'). Loosely validated like falModelId: a peer
  // on a newer catalog may pin a model this install does not curate, which then
  // falls back to the default (OmniHuman v1.5).
  falMusicModelId: z.string().min(1).max(200).nullable().optional(),
  falMusicResolution: z.string().min(1).max(16).nullable().optional(),
  // Runway cutaway model (lib/runwayVideoModels.js), clip length and output
  // size. Loosely validated like falModelId; null/omitted = the default model,
  // the length covering each shot, that model's default size.
  runwayModelId: z.string().min(1).max(64).nullable().optional(),
  runwayDuration: z.number().min(1).max(60).nullable().optional(),
  runwayResolution: z.string().min(1).max(16).nullable().optional(),
  generationMode: z.enum(['image', 'audioReactive', 'suppliedAudio']).optional(),
  audioReactiveLora: z.string().max(255).regex(/^[^/\\]+\.safetensors$/i).nullable().optional(),
  audioReactiveScale: z.number().min(0).max(2).optional(),
}).strict();

// Timed lyric cues (#8964). Editable, user-owned text: a cue carries its line
// and optional timing against the project's CURRENT audio source. `startSec`
// null means "not yet timed" (plain pasted lyrics, or timings invalidated by an
// audio-source change — see projectsLogic.applyProjectPatch). The id is
// optional on input; the server mints one so edits stay addressable.
// `words` (#9074) is derived karaoke timing. Absent on older records and on
// peers that have not aligned; cleared with the line times when the audio changes.
const timedSec = z.number().min(0).max(36000).nullable().optional();
const lyricWordSchema = z.object({
  w: z.string().min(1).max(80),
  startSec: z.number().min(0).max(36000),
  endSec: z.number().min(0).max(36000),
  conf: z.enum(['matched', 'interpolated']),
}).strict().refine((word) => word.endSec >= word.startSec, {
  message: 'word endSec must be >= startSec',
});
export const musicVideoLyricCueSchema = z.object({
  id: z.string().min(1).max(64).optional(),
  text: z.string().max(500),
  startSec: timedSec,
  endSec: timedSec,
  words: z.array(lyricWordSchema).max(400).optional(),
  matched: z.number().min(0).max(1).optional(),
  suspect: z.boolean().optional(),
}).strict();

// A musical-phrase annotation: a span of the song with an optional visual
// intent (what the picture should do there). Phrase edges are preferred cut
// points for the shot planner and the intent is handed to the prompt seeder.
export const musicVideoPhraseSchema = z.object({
  id: z.string().min(1).max(64).optional(),
  label: z.string().max(120).optional(),
  startSec: timedSec,
  endSec: timedSec,
  intent: z.string().max(2000).optional(),
}).strict();

// Shot pacing for the planner. `maxShotSec` is capped at the renderer's clip
// capacity (one generated clip); `hookSec` bounds the opening shot so the video opens on a cut.
export const musicVideoPacingSchema = z.object({
  minShotSec: z.number().min(0.5).max(60).optional(),
  maxShotSec: z.number().min(1).max(120).optional(),
  hookSec: z.number().min(0.5).max(60).optional(),
}).strict();

// Lyric-sheet structure: a section header (`[Chorus]`) or a stage direction
// (`[Spoken, close]`) anchored to the index of the lyric line it precedes.
// `kind` is the normalized section part or delivery (see
// services/musicVideo/lyricMarkers.js); a free string so a newer peer's
// vocabulary still validates here.
export const musicVideoLyricMarkerSchema = z.object({
  type: z.enum(['section', 'direction']),
  label: z.string().trim().min(1).max(120),
  kind: z.string().max(32).optional(),
  line: z.number().int().min(0).max(2000),
}).strict();

const lyricCueList = z.array(musicVideoLyricCueSchema).max(2000);
const lyricMarkerList = z.array(musicVideoLyricMarkerSchema).max(500);
const phraseList = z.array(musicVideoPhraseSchema).max(500);

// ---- Visual specification + scene takes (#8965) ----------------------------

// A gallery image basename (under data/images). Every generated, uploaded, or
// imported still lands there, so this is the one reference vocabulary the image
// route's `referenceImageFiles` and the peer-sync `image` asset kind share.
const galleryImageName = z.string().min(1).max(256)
  .regex(/^[^/\\]+\.(png|jpg|jpeg|webp)$/i, 'must be a gallery image basename (png/jpg/jpeg/webp)');
// A video-history id (the scene clip vocabulary `videoHistoryId` already uses).
const videoHistoryIdSchema = z.string().min(1).max(64).regex(/^[A-Za-z0-9._-]+$/, 'must be a video history id');

// Built-in character style routes (routes/musicVideoCharacterStyles.js).
export const musicVideoCharacterStyleParamsSchema = z.object({ id: z.enum(MUSIC_VIDEO_CHARACTER_STYLE_IDS) }).strict();
// null clears this install's character sheet for the style.
export const musicVideoCharacterStyleReferenceSchema = z.object({ imageId: galleryImageName.nullable() }).strict();

export const MUSIC_VIDEO_REFERENCE_ROLES = ['mood', 'character', 'wardrobe', 'set', 'prop', 'style'];
// How a reference is meant to be used (#8980): `reference` guides the look
// (style/character conditioning), `final-visible` is supplied media meant to
// appear in the finished video as-is, and `motion-reference` is scaffolding
// footage/stills for a hand-drawn or code-rendered pass — never final picture.
export const MUSIC_VIDEO_REFERENCE_USES = ['reference', 'final-visible', 'motion-reference'];
// The image backends accept at most four reference images for most models
// (imageGen/prepareParams.js referenceCap), so a project conditions each
// reference frame on at most this many of its flagged references.
export const MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES = 4;

// One moodboard/reference asset. `condition: true` sends the image to frame
// generation as a real conditioning input (`referenceImageFiles`) rather than
// only describing it in prose.
export const musicVideoVisualReferenceSchema = z.object({
  id: z.string().min(1).max(64).optional(),
  imageId: galleryImageName,
  role: z.enum(MUSIC_VIDEO_REFERENCE_ROLES).optional(),
  label: z.string().max(120).optional(),
  note: z.string().max(1000).optional(),
  condition: z.boolean().optional(),
  use: z.enum(MUSIC_VIDEO_REFERENCE_USES).optional(),
}).strict();

export const musicVideoStyleReferencesSchema = z.array(z.object({
  imageId: galleryImageName,
  caption: z.string().trim().max(500).optional(),
}).strict()).max(8);

// The project's reusable visual specification. A patch merges per sub-field
// (like `concept`), and `references` / `palette` replace their list whole.
export const musicVideoVisualSpecSchema = z.object({
  references: z.array(musicVideoVisualReferenceSchema).max(24).optional(),
  palette: z.array(z.string().regex(/^#[0-9a-f]{6}$/i, 'palette colors are #rrggbb')).max(12).optional(),
  typography: z.string().max(1000).optional(),
  cameraRules: z.string().max(2000).optional(),
  // An existing Mood Board this project draws inspiration from (display link).
  moodBoardId: z.string().max(64).nullable().optional(),
}).strict().refine(
  (spec) => (spec.references || []).filter((ref) => ref.condition).length <= MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES,
  { message: `at most ${MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES} references can condition frames`, path: ['references'] },
);

// `endImage` (#11173): a candidate for the scene's optional style-break end frame.
export const MUSIC_VIDEO_TAKE_KINDS = ['image', 'video', 'endImage'];
export const MUSIC_VIDEO_TAKE_STATUSES = ['candidate', 'rejected'];
// A take's intended use (#8980). A `motion-reference` take is scaffolding (e.g.
// generated footage to trace a hand-drawn pass over): it is kept as a candidate
// but never fills the scene's timeline slot automatically.
export const MUSIC_VIDEO_TAKE_USES = ['final', 'motion-reference'];

// Provider label for provenance — free text so a new external tool needs no
// schema change, but bounded to a slug so it can't smuggle a URL or a secret.
const providerSlug = z.string().min(1).max(40).regex(/^[a-z0-9][a-z0-9._-]*$/i, 'provider must be a short slug');

// A candidate asset offered for a scene slot outside the media-job hooks: an
// external-tool import, or a synchronous-lane render the client already holds.
// `assetId` is validated against its kind (gallery basename / history id) and
// then existence-checked by the route before it can reach the record.
export const musicVideoTakeInputSchema = z.object({
  kind: z.enum(MUSIC_VIDEO_TAKE_KINDS),
  assetId: z.string().min(1).max(256),
  // `trimmed`: a clip take cut from a later start frame of another (the shot card's "Start clip here").
  source: z.enum(['generated', 'imported', 'trimmed']).optional(),
  provider: providerSlug.optional(),
  originalName: z.string().max(255).optional(),
  sourceImageId: galleryImageName.optional(),
  inputAssets: z.array(z.object({ role: z.enum(['crop', 'mask']), assetId: galleryImageName, revision: z.number().int().min(1).max(1000000) }).strict()).max(4).optional(),
  use: z.enum(MUSIC_VIDEO_TAKE_USES).optional(),
}).strict().superRefine((take, ctx) => {
  const check = take.kind === 'video' ? videoHistoryIdSchema : galleryImageName;
  const parsed = check.safeParse(take.assetId);
  if (!parsed.success) ctx.addIssue({ code: 'custom', path: ['assetId'], message: parsed.error.issues[0].message });
});

/** One still or clip in a video's media pool, as the asset manager names it. */
const musicVideoPoolAssetSchema = z.object({
  kind: z.enum(['image', 'video']),
  assetId: z.string().min(1).max(256),
}).strict().superRefine((input, ctx) => {
  const parsed = (input.kind === 'video' ? videoHistoryIdSchema : galleryImageName).safeParse(input.assetId);
  if (!parsed.success) ctx.addIssue({ code: 'custom', path: ['assetId'], message: parsed.error.issues[0].message });
});

/** A search over a video's media pool by the prompts its stills and clips were made from. */
export const musicVideoPoolSearchQuerySchema = z.object({
  q: z.string().trim().min(1).max(200),
}).strict();

/** ★ ingredient (good, not placed) or ✕ bad (to clean up); null clears the mark. */
export const musicVideoPoolMarkSchema = z.object({
  items: z.array(musicVideoPoolAssetSchema).min(1).max(500),
  mark: z.enum(['ingredient', 'bad']).nullable(),
}).strict();

/** Delete unused stills and clips from the media library (the asset manager's "Delete bad"). */
export const musicVideoPoolDeleteSchema = z.object({
  items: z.array(musicVideoPoolAssetSchema).min(1).max(500),
}).strict();

/** File another music video's whole pool (an earlier draft) into this video's collection. */
export const musicVideoPoolImportSchema = z.object({
  fromProjectId: z.string().min(1).max(200),
}).strict();

/** Search the whole media library for stills and clips to add to a video's assets. */
export const musicVideoLibrarySearchQuerySchema = z.object({
  q: z.string().trim().min(1).max(200),
}).strict();

/** File stills and clips from the media library into a video's assets. */
export const musicVideoPoolAddSchema = z.object({
  items: z.array(musicVideoPoolAssetSchema).min(1).max(500),
}).strict();

// Put an unused still or clip from the project's pool on a shot; `withAssetId` is its partner (a still's clip, a clip's still).
// `endImage` puts a still on the shot's end frame; only a start still pairs with a clip.
export const musicVideoPoolUseSchema = z.object({
  kind: z.enum(['image', 'video', 'endImage']),
  assetId: z.string().min(1).max(256),
  withAssetId: z.string().min(1).max(256).optional(),
}).strict().superRefine((input, ctx) => {
  if (input.kind === 'endImage' && input.withAssetId !== undefined) {
    ctx.addIssue({ code: 'custom', path: ['withAssetId'], message: 'An end frame is placed on its own' });
  }
  const [still, clip] = input.kind === 'video' ? [input.withAssetId, input.assetId] : [input.assetId, input.withAssetId];
  for (const [value, schema, path] of [[still, galleryImageName, input.kind === 'video' ? 'withAssetId' : 'assetId'], [clip, videoHistoryIdSchema, input.kind === 'video' ? 'assetId' : 'withAssetId']]) {
    if (value === undefined) continue;
    const parsed = schema.safeParse(value);
    if (!parsed.success) ctx.addIssue({ code: 'custom', path: [path], message: parsed.error.issues[0].message });
  }
});

// Review a take: reject/restore it and/or leave a note for regeneration.
export const musicVideoTakeReviewSchema = z.object({
  status: z.enum(MUSIC_VIDEO_TAKE_STATUSES).optional(),
  note: z.string().max(1000).nullable().optional(),
}).strict().refine((r) => r.status !== undefined || r.note !== undefined, { message: 'status or note is required' });

// Import externally generated assets (e.g. a Midjourney handoff). Each item is
// an asset the client already stored through the existing gallery upload
// routes; `sceneId` is optional when `originalName` carries the scene file tag
// from the exported handoff manifest.
export const musicVideoHandoffImportSchema = z.object({
  provider: providerSlug,
  items: z.array(z.object({
    kind: z.enum(MUSIC_VIDEO_TAKE_KINDS),
    assetId: z.string().min(1).max(256),
    sceneId: z.string().min(1).max(64).optional(),
    originalName: z.string().max(255).optional(),
    use: z.enum(MUSIC_VIDEO_TAKE_USES).optional(),
  }).strict()).min(1).max(200),
}).strict();

// Import lyric cues from pasted text: LRC (`[mm:ss.xx] line`), SRT/WebVTT
// cue blocks, or plain lines (untimed). `auto` sniffs the format.
export const musicVideoLyricsImportSchema = z.object({
  format: z.enum(['auto', 'lrc', 'srt', 'text']).optional(),
  text: z.string().max(200000),
  mode: z.enum(['replace', 'append']).optional(),
}).strict();

// Import the linked track's lyric sheet. `replace` swaps the project's lines
// for the sheet; `if-empty` (the autopilot kickoff) imports only when the
// project has no lines yet, so a re-run never overwrites the director's edits.
export const musicVideoLyricsImportTrackSchema = z.object({
  mode: z.enum(['replace', 'if-empty']).optional(),
}).strict();

// Word alignment (#9074) runs only when the director clicks. `cueId` re-aligns
// that line; omitted, every line is aligned.
export const musicVideoLyricsAlignSchema = z.object({
  cueId: z.string().min(1).max(64).optional(),
  separateVocals: z.boolean().optional(),
  // A revised song: analyze, separate, align and carry the board across in one job.
  retimeSong: z.boolean().optional(),
}).strict();

// ---- Composition manifest (#8984, part of #8966) ---------------------------

// A composed render lays timed text cues over the cut footage; `concat` (and a
// project with no manifest) is the plain clip concatenation. `code` draws the
// whole song as a seekable composition instead of generated footage. Cue text
// is the director's own, rendered as an independent typography layer — never
// baked into generated pixels. See services/musicVideo/composition.js.
// `document` renders a project-owned HTML composition document (its own
// folder under data/music-video/<projectId>/composition/) seeked over the
// song; see services/musicVideo/compositionDocument.js and documentRender.js.
export const MUSIC_VIDEO_COMPOSITION_MODES = ['concat', 'composed', 'code', 'document', 'eidoverse'];
// #9290: 'scene' cuts once per planned shot; 'intercut' re-cuts on section energy and sung words.
export const MUSIC_VIDEO_CUTTING_MODES = ['scene', 'intercut'];
// Shipped starting points a project can copy into its document folder.
export const MUSIC_VIDEO_DOCUMENT_TEMPLATES = ['layered'];
export const MUSIC_VIDEO_DOCUMENT_SOURCES = ['zip', 'directory', 'template', 'generated'];
// One immutable document version: data/music-video/<projectId>/composition/<versionId>.
export const MUSIC_VIDEO_DOCUMENT_DIRECTORY = /^music-video\/[A-Za-z0-9_-]{1,100}\/composition\/[A-Za-z0-9_-]{1,100}$/;
// One section function. Reject the calls that would make a frame depend on
// the clock, entropy, or the network — the preview and the render both seek.
export const MUSIC_VIDEO_CODE_SOURCE_MAX = 20000;
export const MUSIC_VIDEO_CODE_NONDETERMINISTIC = /\bMath\s*\.\s*random\b|\bDate\s*\.\s*now\b|\bperformance\s*\.\s*now\b|\bgetRandomValues\b|\bfetch\s*\(|\bXMLHttpRequest\b|\bWebSocket\b|\bimport\s*\(|\brequire\s*\(/;
export const isDeterministicCodeSource = (source) => typeof source === 'string'
  && source.length > 0
  && source.length <= MUSIC_VIDEO_CODE_SOURCE_MAX
  && !MUSIC_VIDEO_CODE_NONDETERMINISTIC.test(source);
// 'build' (#9291) lays a line down word by word on its sung onsets, the newest word in the accent color.
export const MUSIC_VIDEO_TYPOGRAPHY_TEMPLATES = ['fade', 'rise', 'typewriter', 'pop', 'build'];
export const MUSIC_VIDEO_TYPOGRAPHY_PLACEMENTS = ['upper', 'center', 'lower'];
export const MUSIC_VIDEO_TYPOGRAPHY_EMPHASES = ['subtitle', 'hero'];
export const MUSIC_VIDEO_TYPOGRAPHY_FONTS = ['sans', 'serif', 'mono'];

export const musicVideoTextCueSchema = z.object({
  id: z.string().min(1).max(64).optional(),
  text: z.string().max(500),
  startSec: timedSec,
  endSec: timedSec,
  template: z.enum(MUSIC_VIDEO_TYPOGRAPHY_TEMPLATES).optional(),
  placement: z.enum(MUSIC_VIDEO_TYPOGRAPHY_PLACEMENTS).optional(),
  emphasis: z.enum(MUSIC_VIDEO_TYPOGRAPHY_EMPHASES).optional(),
  // Sung word onsets for the 'build' template (#9291).
  words: z.array(z.object({ w: z.string().min(1).max(60), atSec: z.number().min(0).max(36000) }).strict()).max(80).optional(),
}).strict();

const codeSectionSource = z.string().min(1).max(MUSIC_VIDEO_CODE_SOURCE_MAX)
  .refine(isDeterministicCodeSource, 'section source must be deterministic and offline');

export const musicVideoCodeVideoSchema = z.object({
  providerId: z.string().max(120).nullable().optional(),
  model: z.string().max(200).nullable().optional(),
  generatedAt: z.string().max(40).nullable().optional(),
  sections: z.array(z.object({
    id: z.string().min(1).max(64),
    source: codeSectionSource,
  }).strict()).max(40),
}).strict();

export const musicVideoCodeGenerateSchema = z.object({
  providerId: z.string().max(120).optional(),
  model: z.string().max(200).optional(),
  effort: z.enum(EFFORT_LEVELS).optional(),
}).strict();

// Where the project's composition document lives. Set only by the import
// routes; a PATCH that carries it back is ignored (the stored pointer wins).
export const musicVideoCompositionDocumentSchema = z.object({
  directory: z.string().max(300).regex(MUSIC_VIDEO_DOCUMENT_DIRECTORY, 'directory is a composition document version folder'),
  entry: z.literal('index.html').optional(),
  updatedAt: z.string().max(40).nullable().optional(),
  source: z.object({
    kind: z.enum(MUSIC_VIDEO_DOCUMENT_SOURCES),
    name: z.string().max(200).nullable().optional(),
  }).strict().nullable().optional(),
  files: z.number().int().min(0).max(4096).optional(),
  bytes: z.number().int().min(0).optional(),
}).strict();

// The optional HUD block a composition document may draw (the shipped
// layered template reads it from PORTOS_MV.composition.overlay).
export const musicVideoCompositionOverlaySchema = z.object({
  enabled: z.boolean().optional(),
  titleLines: z.array(z.string().max(120)).max(4).optional(),
  meter: z.object({
    label: z.string().max(40).optional(),
    // [songSec, percent] pairs, eased between.
    keyframes: z.array(z.tuple([z.number().min(0).max(36000), z.number().min(0).max(100)])).max(200).optional(),
  }).strict().nullable().optional(),
  ticker: z.array(z.string().max(200)).max(40).optional(),
  timecode: z.boolean().optional(),
  timecodeStartSec: z.number().min(0).max(86400).optional(),
}).strict();

export const musicVideoNarrativeEventSchema = z.object({
  id: z.string().min(1).max(64),
  name: z.string().min(1).max(120),
  kind: z.enum(NARRATIVE_EVENT_KINDS),
  anchor: z.discriminatedUnion('kind', [
    z.object({ kind: z.literal('time'), atSec: z.number().min(0).max(36000), offsetSec: z.number().min(-900).max(900).optional() }).strict(),
    z.object({ kind: z.literal('onset'), band: z.enum(['low', 'mid', 'high']), index: z.number().int().min(0).max(100000), offsetSec: z.number().min(-900).max(900).optional() }).strict(),
    z.object({ kind: z.literal('word'), cueId: z.string().min(1).max(64), wordIndex: z.number().int().min(0).max(1000), offsetSec: z.number().min(-900).max(900).optional() }).strict(),
  ]).nullable(),
  durationSec: z.number().positive().max(900),
  narrativeFunction: z.string().min(1).max(1000),
  mediumRationale: z.string().min(1).max(1000),
  text: z.string().max(500).optional(),
  motif: z.string().max(120).optional(),
  before: z.string().max(120).optional(),
  after: z.string().max(120).optional(),
  fromValue: z.number().finite().min(-1000000).max(1000000).optional(),
  toValue: z.number().finite().min(-1000000).max(1000000).optional(),
}).strict();
export const musicVideoReactiveSectionSchema = z.object({
  sectionId: z.string().min(1).max(64),
  gain: z.number().min(0).max(1),
  maxGain: z.number().min(0).max(1),
}).strict();

// Scene code is data until the isolated Eidoverse container renders it. No
// executable, host path, output path or remote asset can be selected here.
export const musicVideoEidoverseSceneSchema = z.object({
  inlineScript: z.string().trim().min(1).max(100000),
  assets: z.record(z.string().regex(/^[A-Za-z0-9_-]{1,80}$/),
    z.string().max(300).regex(/^eidoverse\/assets\/(?:[A-Za-z0-9_-][A-Za-z0-9_.-]*\/)*[A-Za-z0-9_-][A-Za-z0-9_.-]*$/))
    .refine(assets => Object.keys(assets).length <= 32, 'At most 32 assets').optional(),
}).strict();

// Replaced whole by a project PATCH (the editor sends the full manifest).
export const musicVideoCompositionSchema = z.object({
  version: z.literal(1).optional(),
  mode: z.enum(MUSIC_VIDEO_COMPOSITION_MODES).optional(),
  authoringRenderer: z.enum(['canvas', 'three']).optional(),
  // Curated film style grammar the document authoring prompt follows (#10254).
  styleGrammarId: knownFilmStyleIdSchema.optional(),
  cutting: z.enum(MUSIC_VIDEO_CUTTING_MODES).optional(),
  grade: z.object({
    preset: z.enum(MUSIC_VIDEO_GRADE_PRESETS).optional(),
    grain: z.number().min(0).max(MUSIC_VIDEO_GRADE_MAX_GRAIN).optional(),
    sections: z.array(z.object({
      sceneId: z.string().min(1).max(120),
      preset: z.enum(MUSIC_VIDEO_GRADE_PRESETS),
    }).strict()).max(1000).optional(),
  }).strict().nullable().optional(),
  textCues: z.array(musicVideoTextCueSchema).max(1000).optional(),
  style: z.object({
    color: z.string().regex(/^#[0-9a-f]{6}$/i, 'color is #rrggbb').optional(),
    font: z.enum(MUSIC_VIDEO_TYPOGRAPHY_FONTS).optional(),
    accentColor: z.string().regex(/^#[0-9a-f]{6}$/i, 'accentColor is #rrggbb').optional(),
  }).strict().optional(),
  posterSec: timedSec,
  eidoverseScene: musicVideoEidoverseSceneSchema.nullable().optional(),
  codeVideo: musicVideoCodeVideoSchema.nullable().optional(),
  document: musicVideoCompositionDocumentSchema.nullable().optional(),
  documentDraft: musicVideoCompositionDocumentSchema.nullable().optional(),
  overlay: musicVideoCompositionOverlaySchema.nullable().optional(),
  narrativeEvents: z.array(musicVideoNarrativeEventSchema).max(200).refine((events) => new Set(events.map((event) => event.id)).size === events.length, 'event ids must be unique').optional(),
  reactiveSections: z.array(musicVideoReactiveSectionSchema).max(40).refine((sections) => new Set(sections.map((section) => section.sectionId)).size === sections.length, 'section ids must be unique').optional(),
}).strict();

// A relative folder inside data/ to copy a composition document from.
export const musicVideoDocumentDirectoryImportSchema = z.object({
  directory: z.string().min(1).max(1024).refine((value) => !value.startsWith('/') && !value.includes('\\') && !value.includes(':')
    && !value.includes('\0') && !value.split('/').some((part) => part === '..' || part === '.' || !part), 'directory must be a relative path inside data'),
}).strict();

export const musicVideoDocumentFileQuerySchema = z.object({
  path: z.string().min(1).max(512),
  draft: z.literal('1').optional(),
}).strict();

export const musicVideoDocumentDraftQuerySchema = z.object({ draft: z.literal('1').optional() }).strict();
export const musicVideoDocumentCandidateSchema = z.object({
  directory: z.string().regex(MUSIC_VIDEO_DOCUMENT_DIRECTORY),
}).strict();
export const musicVideoMixedMediaRegenerateSchema = musicVideoCodeGenerateSchema.extend({
  expectedDraft: z.string().regex(MUSIC_VIDEO_DOCUMENT_DIRECTORY),
}).strict();

export const musicVideoDocumentTemplateSchema = z.object({
  template: z.enum(MUSIC_VIDEO_DOCUMENT_TEMPLATES).optional(),
}).strict();

// #10589: a shot's structured camera move — a shared camera-movement id
// (lib/cameraMovements.js) with optional speed, end framing, downbeat landing
// and, for a still camera, the reason it holds. Feeds the i2v camera block and
// the layered template's camera rig. `null` clears it.
export const musicVideoSceneCameraSchema = z.object({
  move: z.enum(CAMERA_MOVEMENT_VALUES),
  speed: z.enum(CAMERA_SPEEDS).optional(),
  endFraming: z.enum(CAMERA_FRAMINGS).optional(),
  onBeat: z.boolean().optional(),
  reason: z.string().trim().max(300).optional(),
}).strict();

// #12763: the Casting cast member a shot features and the variant (age, era, look) its
// frames should show. Conditioning leads with that member's render guides; null clears it.
export const musicVideoSceneCharacterVariantSchema = z.object({
  ingredientId: z.string().min(1).max(128),
  age: z.number().int().min(0).max(150).optional(),
  era: z.enum(CAST_ERAS).optional(),
  wardrobeId: z.string().trim().min(1).max(59).optional(),
}).strict();

// Per-scene visual layer (#8985) — footage, a moved still, or a title card;
// see musicVideoLayers.js. Only a composed render honors a non-footage layer.
const sceneLayerFields = {
  // The references (visual spec ids) sent with this shot's frame renders; absent or null = the automatic set.
  frameReferenceIds: z.array(z.string().min(1).max(128)).max(MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES).nullable().optional(),
  characterVariant: musicVideoSceneCharacterVariantSchema.nullable().optional(),
  camera: musicVideoSceneCameraSchema.nullable().optional(),
  visualLayer: z.enum(MUSIC_VIDEO_VISUAL_LAYERS).optional(),
  stillMove: z.enum(MUSIC_VIDEO_STILL_MOVES).optional(),
  // How a clip of another shape fills the video's frame (musicVideoLayers.js).
  frameFit: z.enum(MUSIC_VIDEO_FRAME_FITS).optional(),
  // A footage clip played faster or slower by whole frames a second, and slid against the song by whole frames; null clears it.
  speedFps: z.number().int().min(CLIP_SPEED_FPS_RANGE.min).max(CLIP_SPEED_FPS_RANGE.max).nullable().optional(),
  offsetFrames: z.number().int().min(CLIP_OFFSET_FRAMES_RANGE.min).max(CLIP_OFFSET_FRAMES_RANGE.max).nullable().optional(),
  // The clip plays backwards (a footage shot; never a lip-sync performance).
  reverse: z.boolean().nullable().optional(),
  // A clip shorter than its shot holds its last frame for the rest of the shot; null clears it.
  holdLastFrame: z.boolean().nullable().optional(),
  // The shot's own film look (lib/filmLook.js), kept when the video's look changes; null follows the video's.
  filmLook: filmLookSchema.nullable().optional(),
  // A VHS glitch over the cut into / out of this shot (musicVideoTransitions.js); null clears it.
  transitionIn: z.enum(MUSIC_VIDEO_TRANSITIONS).nullable().optional(),
  transitionOut: z.enum(MUSIC_VIDEO_TRANSITIONS).nullable().optional(),
  // Glitches at moments inside the shot: `atSec` from the shot's start, `lengthSec` stretching the style; null clears them.
  glitches: z.array(z.object({
    atSec: z.number().min(0).max(3600),
    style: z.enum(MUSIC_VIDEO_TRANSITIONS),
    lengthSec: z.number().positive().max(4).nullable().optional(),
  })).max(MUSIC_VIDEO_SHOT_GLITCH_LIMIT).nullable().optional(),
  // An effect across the cut out of this shot (musicVideoCutEffects.js), kept with its settings while switched off; null clears it.
  cutEffect: z.object({
    style: z.enum(MUSIC_VIDEO_CUT_EFFECTS),
    enabled: z.boolean().optional(),
    overlapSec: z.number().min(BEAT_TOGGLE_OVERLAP.min).max(BEAT_TOGGLE_OVERLAP.max).optional(),
    rate: z.enum(BEAT_TOGGLE_RATES).optional(),
  }).nullable().optional(),
  // A code-drawn effect a still shot plays instead of a clip (musicVideoImageEffects.js) and how long
  // it takes to finish; null clears it.
  imageEffect: z.enum(MUSIC_VIDEO_IMAGE_EFFECTS).nullable().optional(),
  imageEffectSec: z.number().min(IMAGE_EFFECT_SEC_RANGE.min).max(IMAGE_EFFECT_SEC_RANGE.max).nullable().optional(),
  cardText: z.string().max(500).nullable().optional(),
  // #10302: footage that the composition also draws code over; still counts as footage.
  codeOverlay: z.boolean().optional(),
  // Footage whose clip was rendered from code (an uploaded code render): the board labels it Code.
  codeClip: z.boolean().optional(),
  cardColor: z.string().regex(/^#[0-9a-f]{6}$/i, 'card color is #rrggbb').nullable().optional(),
  // #10583: where a composition document's lyric type may sit in this shot, and the role of its lines.
  textZone: z.enum(MUSIC_VIDEO_TEXT_ZONES).nullable().optional(),
  lyricRole: z.enum(MUSIC_VIDEO_LYRIC_ROLES).nullable().optional(),
  lyricSize: z.enum(MUSIC_VIDEO_LYRIC_SIZES).nullable().optional(),
};

// ---- Pre-production treatment (#8980) --------------------------------------

// The treatment sits between the director's concept/visual spec and the timed
// shot planner: a structured brief, a compiled whole-song arc, per-shot
// direction keyed to the board's real scene ids, and a proof checklist. Its own
// routes edit it (never the generic project PATCH) so every write carries the
// revision it was based on. See services/musicVideo/treatment.js.
export const MUSIC_VIDEO_ASPECT_RATIOS = ['16:9', '9:16', '1:1', '4:5', '2.39:1'];
export const MUSIC_VIDEO_BEAT_ROLES = ['opening', 'build', 'contrast', 'payoff', 'release'];
// Treatment shot categories (the arc's balance axis). Distinct from the scene's
// render-facing `shotMode` (#8977: cutaway | performance) — Apply maps a
// performance direction onto it when the backend can lip-sync.
export const MUSIC_VIDEO_TREATMENT_SHOT_MODES = ['performance', 'cutaway', 'graphic'];
export const MUSIC_VIDEO_SHOT_ROUTES = ['generated', 'supplied-asset', 'code-2d'];
export const MUSIC_VIDEO_NEGATIVE_SPACE = ['none', 'upper', 'center', 'lower'];
export const MUSIC_VIDEO_TYPOGRAPHY_ROLES = ['none', 'subtitle', 'hero'];
export const MUSIC_VIDEO_PROOF_CHECKS = ['identity-continuity', 'readable-text', 'cut-continuity', 'audio-alignment', 'continuous-motion', 'lip-sync'];
export const MUSIC_VIDEO_PROOF_STATUSES = ['proposed', 'passed', 'failed'];

// A manually supplied reference note/URL. The URL is provenance the director
// typed — PortOS never fetches it, and its text is treated as untrusted data.
const referenceUrl = z.string().max(2000).regex(/^https?:\/\/\S+$/i, 'reference URLs must be http(s)');
export const musicVideoTreatmentReferenceNoteSchema = z.object({
  id: z.string().min(1).max(64).optional(),
  note: z.string().max(1000).optional(),
  url: referenceUrl.nullable().optional(),
}).strict();

// Every brief field is optional; a patch merges per field.
export const musicVideoTreatmentBriefSchema = z.object({
  audience: z.string().max(500).optional(),
  destination: z.string().max(200).optional(),
  aspectRatio: z.enum(MUSIC_VIDEO_ASPECT_RATIOS).nullable().optional(),
  emotion: z.string().max(500).optional(),
  premise: z.string().max(2000).optional(),
  hookObjective: z.string().max(1000).optional(),
  graphicLanguage: z.string().max(1000).optional(),
  mustHave: z.string().max(2000).optional(),
  avoid: z.string().max(2000).optional(),
  referenceNotes: z.array(musicVideoTreatmentReferenceNoteSchema).max(20).optional(),
}).strict();

const treatmentText = (max) => z.string().max(max).optional();

export const musicVideoTreatmentMotifSchema = z.object({
  id: z.string().min(1).max(64).optional(),
  name: z.string().max(120),
  description: treatmentText(1000),
  evolution: treatmentText(1000),
  rationale: treatmentText(1000),
}).strict();

export const musicVideoProductionPolicySchema = z.object({
  strategy: z.enum(['legacy', 'code-first']).optional(),
  maxGeneratedVideoPercent: z.number().min(0).max(100).optional(),
}).strict();

export const musicVideoActionContractSchema = z.custom((value) => value != null && !shotActionContractProblem(value), { message: 'Invalid shot action contract' });

export const musicVideoShotDirectionPatchSchema = z.object({
  sceneId: z.string().min(1).max(64),
  actionContract: musicVideoActionContractSchema.nullable().optional(),
  medium: z.enum(MUSIC_VIDEO_MEDIA).optional(),
  mediumRationale: treatmentText(1000),
  mediumPinned: z.boolean().optional(),
  mode: z.enum(MUSIC_VIDEO_TREATMENT_SHOT_MODES).optional(),
  route: z.enum(MUSIC_VIDEO_SHOT_ROUTES).optional(),
  focalSubject: treatmentText(500),
  framing: treatmentText(500),
  negativeSpace: z.enum(MUSIC_VIDEO_NEGATIVE_SPACE).optional(),
  typographyRole: z.enum(MUSIC_VIDEO_TYPOGRAPHY_ROLES).optional(),
  emphasis: treatmentText(500),
  transitionIn: treatmentText(300),
  transitionOut: treatmentText(300),
  rationale: treatmentText(1000),
  suggestedFramePrompt: treatmentText(2000),
  suggestedPrompt: treatmentText(2000),
}).strict();

// PATCH /:id/treatment. `baseRevision` is the treatment revision the edit was
// made against (0 before a treatment exists); a mismatch is a 409 so a stale tab
// or a peer's older copy can never overwrite a newer edit. `rebase` accepts the
// project's CURRENT visual spec / lyrics / scene set as the treatment's basis
// without recompiling (an audio change still needs a recompile).
export const musicVideoTreatmentUpdateSchema = z.object({
  baseRevision: z.number().int().min(0),
  brief: musicVideoTreatmentBriefSchema.optional(),
  beats: z.array(z.object({
    id: z.string().min(1).max(64),
    objective: treatmentText(1000),
    rationale: treatmentText(1000),
  }).strict()).max(200).optional(),
  motifs: z.array(musicVideoTreatmentMotifSchema).max(12).optional(),
  shotDirections: z.array(musicVideoShotDirectionPatchSchema).max(500).optional(),
  rebase: z.boolean().optional(),
}).strict();

// POST /:id/treatment/compile — an explicit user action. `useAi: false` drafts
// the deterministic treatment only (no provider call at all).
export const musicVideoTreatmentCompileSchema = z.object({
  baseRevision: z.number().int().min(0),
  useAi: z.boolean().optional(),
  providerId: z.string().max(64).optional(),
  model: z.string().max(200).optional(),
}).strict();

// POST /:id/treatment/apply. Manually edited scene prompts are kept unless the
// director explicitly lists the scene in `overwrite` with the fingerprint of
// the prompts they reviewed — a prompt edited after the review stays kept.
export const musicVideoTreatmentApplySchema = z.object({
  revision: z.number().int().min(0),
  overwrite: z.array(z.object({
    sceneId: z.string().min(1).max(64),
    promptFingerprint: z.string().min(1).max(64),
  }).strict()).max(500).optional(),
  addTextCues: z.boolean().optional(),
}).strict();

// Record a proof-checklist review. Evidence names a real artifact of this
// project (a scene's clip or frame take, or the final render).
export const musicVideoTreatmentProofReviewSchema = z.object({
  baseRevision: z.number().int().min(0),
  status: z.enum(MUSIC_VIDEO_PROOF_STATUSES),
  evidence: z.object({
    videoHistoryId: z.string().min(1).max(64).regex(/^[A-Za-z0-9._-]+$/, 'must be a video history id').optional(),
    imageId: galleryImageName.optional(),
    note: z.string().max(2000).optional(),
  }).strict().optional(),
}).strict();

// ---- Draft excerpt render (#8986) -------------------------------------------
// A director-chosen `[startSec, endSec)` window re-rendered through the same
// composed pipeline as a full render, plus a cut/cue contact sheet and
// timecoded review notes against the excerpt's OWN timeline (0 = its start).
// See services/musicVideo/excerpt.js / excerptRender.js.
export const MUSIC_VIDEO_EXCERPT_NOTE_VERDICTS = ['flagged', 'approved'];

export const musicVideoExcerptRequestSchema = z.object({
  startSec: z.number().min(0).max(36000),
  endSec: z.number().min(0).max(36000),
  // #9280: a social cut renders at another frame and fades its audio edges.
  aspect: z.enum(['16:9', '9:16', '1:1']).optional(),
  fade: z.boolean().optional(),
}).strict().refine((r) => r.endSec > r.startSec, { message: 'endSec must be greater than startSec' });

// #9280: hook-window suggestions for social cuts.
export const musicVideoSocialCutsQuerySchema = z.object({
  count: z.coerce.number().int().min(1).max(10).optional(),
  minSec: z.coerce.number().min(3).max(120).optional(),
  maxSec: z.coerce.number().min(5).max(180).optional(),
}).strict().refine((q) => q.minSec == null || q.maxSec == null || q.maxSec >= q.minSec, { message: 'maxSec must be at least minSec' });

// #9281: publishing kit — per-platform copy edits, the copy draft request, the chosen thumbnail.
const kitText = (max) => z.string().max(max);
export const musicVideoPublishCopyPatchSchema = z.object({
  youtube: z.object({ title: kitText(100), description: kitText(5000), tags: z.array(kitText(60)).max(30) }).partial().strict().optional(),
  shorts: z.object({ title: kitText(100), description: kitText(5000) }).partial().strict().optional(),
  x: z.object({ hook: kitText(280), story: kitText(25000) }).partial().strict().optional(),
  linkedin: z.object({ post: kitText(3000) }).partial().strict().optional(),
  facebook: z.object({ post: kitText(63206) }).partial().strict().optional(),
  tiktok: z.object({ caption: kitText(2200) }).partial().strict().optional(),
  instagram: z.object({ caption: kitText(2200) }).partial().strict().optional(),
  reddit: z.object({ title: kitText(300), body: kitText(40000) }).partial().strict().optional(),
  stackerNews: z.object({ title: kitText(80), body: kitText(40000) }).partial().strict().optional(),
  substack: z.object({ title: kitText(100), subtitle: kitText(250), body: kitText(40000) }).partial().strict().optional(),
  notes: kitText(8000).optional(),
  // The draft inputs save as they are edited, not only when Draft runs; '' clears a link.
  links: z.object({ youtube: z.union([z.string().url().max(500), z.literal('')]), song: z.union([z.string().url().max(500), z.literal('')]) }).partial().strict().optional(),
  draftOptions: z.object({
    include: z.object({ title: z.boolean(), lyrics: z.boolean(), spend: z.boolean(), chapters: z.boolean(), hashtags: z.boolean() }).partial().strict().optional(),
    length: z.enum(['short', 'full']).optional(),
  }).strict().optional(),
}).strict();
export const musicVideoPublishCopyDraftSchema = z.object({
  providerId: z.string().max(200).nullable().optional(),
  model: z.string().max(200).nullable().optional(),
  notes: kitText(8000).optional(),
  links: z.object({ youtube: z.string().url().max(500), song: z.string().url().max(500) }).partial().strict().optional(),
  // What the draft may use beyond the notes and links; omitted keys keep their defaults (title on, the rest off).
  include: z.object({ title: z.boolean(), lyrics: z.boolean(), spend: z.boolean(), chapters: z.boolean(), hashtags: z.boolean() }).partial().strict().optional(),
  length: z.enum(['short', 'full']).optional(),
  // The director agreed to replace posts written or edited by hand since the last draft.
  replaceEdited: z.boolean().optional(),
}).strict();
// Plan the promotion as scheduled steps for the artist (Review Hub › Actions).
export const musicVideoPromotionPlanSchema = z.object({
  providerId: z.string().max(200).nullable().optional(),
  model: z.string().max(200).nullable().optional(),
  goal: z.string().trim().max(1500).optional(),
  audience: z.string().trim().max(1000).optional(),
  days: z.number().int().min(1).max(30).optional(),
}).strict();
export const musicVideoPublishThumbnailSchema = z.object({ filename: z.string().min(1).max(300) }).strict();

// Release cover art: a source (a kit thumbnail or a gallery image) composed
// with the title and artist tag, or a fresh source image from a backend.
const coverArtSourceSchema = z.object({ kind: z.enum(['thumbnail', 'image']), filename: z.string().min(1).max(300) }).strict();
export const musicVideoCoverArtComposeSchema = z.object({
  source: coverArtSourceSchema.optional(),
  title: z.string().max(60).optional(),
  tag: z.string().max(24).optional(),
  focusX: z.number().min(0).max(1).optional(),
  // false = a finished cover from elsewhere: squared and sized, no title or tag set on it.
  lettering: z.boolean().optional(),
}).strict();
// The YouTube thumbnail: a source composed 16:9 with the title in the cover's lettering.
export const musicVideoYoutubeThumbnailComposeSchema = z.object({
  source: coverArtSourceSchema.optional(),
  title: z.string().max(60).optional(),
  focusX: z.number().min(0).max(1).optional(),
  focusY: z.number().min(0).max(1).optional(),
  lettering: z.boolean().optional(),
}).strict();
// "Paint the title": the image model restyles a frame with the title drawn in. Preview takes no source.
export const musicVideoYoutubeThumbnailPaintPreviewSchema = z.object({
  title: z.string().trim().min(1).max(60),
  notes: z.string().max(1500).optional(),
}).strict();
export const musicVideoYoutubeThumbnailPaintSchema = musicVideoYoutubeThumbnailPaintPreviewSchema.extend({ source: coverArtSourceSchema }).strict();
export const musicVideoCoverArtDesignSchema = z.object({
  direction: z.string().max(1500).optional(),
  providerId: z.string().min(1).max(200).optional(),
  model: z.string().min(1).max(200).optional(),
}).strict();
// #10345: the Lettering controls. A design is every COVER_DESIGN_OPTIONS field
// plus tracking, colors and the rule; any subset is a patch over the song's
// current design. `typeface` is a free string here (a built-in name or a
// `font:<id>` for an uploaded font) and is resolved against the uploaded fonts
// when the design is normalized.
const coverHex = z.string().regex(/^#[0-9a-f]{6}$/i);
const coverDesignFields = Object.fromEntries(Object.entries(COVER_DESIGN_OPTIONS)
  .map(([key, list]) => [key, key === 'typeface' ? z.string().min(1).max(60) : z.enum(list)]));
export const musicVideoCoverDesignSchema = z.object({
  ...coverDesignFields,
  tracking: z.number().min(-0.05).max(0.3),
  titleColor: coverHex,
  accentColor: coverHex,
  rule: z.boolean(),
}).partial().strict();
export const musicVideoCoverDesignSaveSchema = z.object({ design: musicVideoCoverDesignSchema }).strict();
export const musicVideoArtistStyleSaveSchema = z.object({
  name: z.string().trim().min(1).max(60),
  design: musicVideoCoverDesignSchema,
}).strict();
export const musicVideoArtistStyleDeleteSchema = z.object({ name: z.string().trim().min(1).max(60) }).strict();
export const musicVideoCoverArtGenerateSchema = z.object({
  notes: z.string().max(1500).optional(),
  reference: z.object({ kind: z.literal('image'), filename: z.string().min(1).max(300) }).strict().optional(),
}).strict();

// #9282: posting to a platform through the PortOS Browser. One strict options
// object covers every target; each target's payload builder reads only its own.
export const MUSIC_VIDEO_PUBLISH_TARGETS = Object.freeze(['youtube', 'shorts', 'tiktok', 'instagram', 'x', 'linkedin', 'facebook', 'reddit', 'stackerNews', 'substack', 'suno', 'sunoHook', 'distrokid']);
export const musicVideoPublishTargetSchema = z.enum(MUSIC_VIDEO_PUBLISH_TARGETS);
const publishUrl = z.string().url().max(500);
// #9287: which platforms the director posts to (opt-in), the account for each,
// and a post's link, reception and notes.
const publishPlatformEntry = z.object({ enabled: z.boolean(), account: z.string().max(100).nullable() }).partial().strict();
// DistroKid also keeps the release answers that repeat on every project ('' or null forgets one).
const rememberedAnswer = z.string().max(100).nullable();
const distrokidPlatformEntry = publishPlatformEntry.extend({
  defaults: z.object(Object.fromEntries(DISTROKID_REMEMBERED_OPTIONS.map((k) => [k, rememberedAnswer]))).partial().strict(),
}).partial().strict();
export const musicVideoPublishPlatformsPatchSchema = z.object(Object.fromEntries(MUSIC_VIDEO_PUBLISH_TARGETS
  .map((t) => [t, (t === 'distrokid' ? distrokidPlatformEntry : publishPlatformEntry).optional()]))).strict();
export const musicVideoPublishPostSchema = z.object({
  url: publishUrl.nullable(),
  // Marks the platform done without a link (a DistroKid upload has none until the stores go live).
  posted: z.literal(true),
  reception: z.enum(['good', 'mixed', 'poor']).nullable(),
  notes: z.string().max(2000).nullable(),
  // The release's other posts this one now links to (cross-links), added to what it linked already.
  links: z.array(musicVideoPublishTargetSchema).max(MUSIC_VIDEO_PUBLISH_TARGETS.length),
}).partial().strict().refine((b) => Object.keys(b).length > 0, { message: 'url, posted, reception, notes or links is required' });
// Whether new drafts list the release's other posts, and which posted platform gets its missing links.
export const musicVideoPublishCrossLinksSchema = z.object({ enabled: z.boolean() }).strict();
export const musicVideoCrossLinkTargetSchema = z.enum(CROSS_LINK_EDIT_TARGETS);
export const musicVideoCrossLinkEditSchema = z.object({}).strict();
export const musicVideoPublishPrepareSchema = z.object({
  subreddit: z.string().max(40),
  kind: z.enum(['self', 'link', 'video']),
  url: publishUrl,
  flairId: z.string().max(100),
  flairText: z.string().max(64),
  firstComment: kitText(10000),
  // LinkedIn, Facebook: put the full video and song links in a first comment (default on).
  linksComment: z.boolean(),
  // Facebook: turn on the post's AI label (default on).
  aiLabel: z.boolean(),
  territory: z.string().max(40),
  // Substack: the publication (name.substack.com or a custom domain); defaults to the account under Where you post.
  publication: z.string().trim().min(1).max(200),
  songUrl: publishUrl,
  pin: z.boolean(),
  // Suno Hook: keep the page's lyric overlay (default off: the cut carries its own).
  showLyrics: z.boolean(),
  prompt: kitText(25000),
  storyImage: z.string().min(1).max(300),
  cutId: z.string().min(1).max(100),
  // Fill a draft for a platform the release was already posted to.
  again: z.boolean(),
  // DistroKid (the song as a Spotify single): who it is by and the store flags.
  artistName: z.string().trim().min(1).max(100),
  songwriterFirst: z.string().trim().min(1).max(100),
  songwriterLast: z.string().trim().min(1).max(100),
  releaseDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
  explicit: z.boolean(),
  instrumental: z.boolean(),
  aiLyrics: z.boolean(),
  aiMusic: z.boolean(),
  aiVocals: z.boolean(),
  genre: z.string().trim().min(1).max(60),
  secondaryGenre: z.string().trim().min(1).max(60),
  language: z.string().trim().min(1).max(60),
  songwriterRole: z.enum(['music', 'lyrics', 'both']),
  newArtistProfile: z.boolean(),
  preserveCaps: z.boolean(),
  performerName: z.string().trim().min(1).max(100),
  performerRole: z.string().trim().min(1).max(60),
  producerName: z.string().trim().min(1).max(100),
  previewStartSec: z.number().min(0).max(3600),
}).partial().strict();

export const musicVideoExcerptNoteSchema = z.object({
  atSec: z.number().min(0).max(36000),
  note: z.string().min(1).max(2000),
  verdict: z.enum(MUSIC_VIDEO_EXCERPT_NOTE_VERDICTS).nullable().optional(),
}).strict();

export const musicVideoExcerptNoteUpdateSchema = z.object({
  atSec: z.number().min(0).max(36000).optional(),
  note: z.string().min(1).max(2000).optional(),
  verdict: z.enum(MUSIC_VIDEO_EXCERPT_NOTE_VERDICTS).nullable().optional(),
}).strict().refine((r) => r.atSec !== undefined || r.note !== undefined || r.verdict !== undefined, { message: 'atSec, note or verdict is required' });

// ---- Selective section revision (#8987) -------------------------------------
// Reject the flagged sections of a reviewed draft excerpt and regenerate only
// those. `sceneIds` names the sections explicitly; omitted, every section
// holding a `flagged` note is revised. See services/musicVideo/revision.js.
export const musicVideoDependencyRepairSchema = z.object({ basis: z.string().min(1).max(128) }).strict();

export const musicVideoRevisionStartSchema = z.object({
  sceneIds: z.array(z.string().min(1).max(200)).min(1).max(500).optional(),
}).strict();

// ---- Opt-in automatic review/retries (#8988) --------------------------------
// Every limit is required: a run never picks its own budget. `maxAttempts`
// bounds the reviews (provider calls); `maxGenerations` is the spend limit on
// paid scene-generation jobs. See services/musicVideo/autoReview.js.
export const musicVideoAutoReviewLimitsSchema = z.object({
  maxAttempts: z.number().int().min(1).max(10),
  maxGenerations: z.number().int().min(0).max(100),
}).strict();

export const musicVideoAutoReviewStartSchema = z.object({
  startSec: z.number().min(0).max(36000),
  endSec: z.number().min(0).max(36000),
  limits: musicVideoAutoReviewLimitsSchema,
  providerId: z.string().min(1).max(200).nullable().optional(),
  model: z.string().min(1).max(200).nullable().optional(),
}).strict().refine((r) => r.endSec > r.startSec, { message: 'endSec must be greater than startSec' });

// Resume may RAISE either limit (never below what the run already used).
export const musicVideoAutoReviewResumeSchema = z.object({
  limits: musicVideoAutoReviewLimitsSchema.partial().optional(),
}).strict();

// ---- Server-owned production run (#9066) -----------------------------------
// The allowed pool: explicit image/video render backends (and models) the run
// may dispatch to — re-checked for eligibility and capability at every
// dispatch. Every limit but the dollar cap is required; the cap is accepted
// only when every metered route has a known price (services/musicVideo/production.js).
const musicVideoProductionRouteSchema = z.discriminatedUnion('kind', [
  z.object({ kind: z.literal('image'), mode: z.enum(IMAGE_GEN_MODES), model: z.string().trim().min(1).max(200).nullable().optional() }).strict(),
  z.object({ kind: z.literal('video'), mode: z.enum(VIDEO_GEN_MODES), model: z.string().trim().min(1).max(200).nullable().optional() }).strict(),
]);

export const musicVideoProductionLimitsSchema = z.object({
  maxGenerations: z.number().int().min(1).max(500),
  maxReviewAttempts: z.number().int().min(1).max(10),
  spendCapUsd: z.number().min(0).max(100000).nullable().optional(),
}).strict();

// A code-authoring provider pin: both ids are required, effort is optional.
const musicVideoAuthoringSchema = z.object({
  providerId: z.string().min(1).max(200),
  model: z.string().min(1).max(200),
  effort: z.enum(EFFORT_LEVELS).nullable().optional(),
}).strict();

export const musicVideoProductionStartSchema = z.object({
  directive: z.string().max(4000).optional(),
  pool: z.array(musicVideoProductionRouteSchema).max(12),
  limits: musicVideoProductionLimitsSchema,
  authoring: musicVideoAuthoringSchema.optional(),
  providerId: z.string().min(1).max(200).nullable().optional(),
  model: z.string().min(1).max(200).nullable().optional(),
  // 'clips': make every still, then stop as `awaiting-video` before any clip.
  stopBefore: z.enum(['clips']).nullable().optional(),
}).strict();

// Resume may RAISE a limit; `acceptBasis` continues against a changed creative setup;
// `pool` replaces the allowed routes (e.g. swaps a refused video model), validated like Start.
export const musicVideoProductionResumeSchema = z.object({
  limits: musicVideoProductionLimitsSchema.partial().optional(),
  acceptBasis: z.boolean().optional(),
  pool: z.array(musicVideoProductionRouteSchema).max(12).optional(),
  // null goes on to the clips; omitted keeps a running stills-only stop (a finished one goes on).
  stopBefore: z.enum(['clips']).nullable().optional(),
}).strict();

// ---- Fully-autonomous run: one prompt → lyrics → Suno song → video --------------
// Suno's Advanced-form options. `excludeStyles: ''` clears the field Suno keeps
// from its last draft; null (resume only) clears a stored option.
const musicVideoSunoOptionsSchema = z.object({
  excludeStyles: z.string().trim().max(SUNO_LIMITS.excludeStyles).nullable().optional(),
  vocalGender: z.enum(SUNO_VOCAL_GENDERS).nullable().optional(),
  model: z.string().trim().regex(SUNO_MODEL_PATTERN, 'A Suno model version such as v6 or v6-wild').nullable().optional(),
  maxMode: z.boolean().nullable().optional(),
}).strict();

// Local Music Studio options: model (with optional engine) or code (with chosen language).
export const musicVideoLocalMusicOptionsSchema = z.object({
  type: z.enum(LOCAL_MUSIC_TYPES).optional(),
  engine: z.string().trim().max(64).nullable().optional(),
  language: z.enum(LOCAL_MUSIC_CODE_LANGUAGES).nullable().optional(),
}).strict();

// A provider/model/effort pin for a Music Video text stage. Effort is the union
// of every accepted level; the runner clamps it to the chosen provider's ladder.
export const musicVideoLlmSchema = z.object({
  providerId: z.string().trim().min(1).max(200),
  model: z.string().trim().min(1).max(200).nullable().optional(),
  effort: z.enum(EFFORT_LEVELS).nullable().optional(),
}).strict();

// Per-stage pins (MUSIC_VIDEO_LLM_STAGES): an absent stage keeps its stored pin
// (or, on a start request, uses the direction pin); null clears that stage.
export const musicVideoLlmStagesSchema = z.object(Object.fromEntries(
  MUSIC_VIDEO_LLM_STAGES.map((stage) => [stage, musicVideoLlmSchema.nullable().optional()]),
)).strict();

// Production review stages the run may approve by itself (de-duplicated, in
// review order). A non-empty list is approval authority, so the request must
// use an authenticated session (checked by the route); an
// empty list on resume clears the grant.
const musicVideoAutoApproveFields = {
  autoApprove: z.array(z.enum(AUTONOMOUS_AUTO_APPROVE_STAGES)).max(AUTONOMOUS_AUTO_APPROVE_STAGES.length * 4)
    .transform(normalizeAutoApprove).optional(),
  password: z.string().min(1).max(1024).optional(),
};

// The alternate entry point: no track, style or board is picked up front. Tool
// ids are the same catalog the autopilot brief uses; `checkpoints` names the
// stages that park for approval (none = fully unattended).
export const musicVideoAutonomousStartSchema = z.object({
  prompt: z.string().trim().min(1).max(AUTONOMOUS_PROMPT_MAX),
  name: z.string().trim().min(1).max(AUTONOMOUS_NAME_MAX).optional(),
  mediaMode: z.enum(MUSIC_VIDEO_MEDIA_MODES).optional(),
  songSource: z.enum(AUTONOMOUS_SONG_SOURCES).optional(),
  localFallback: z.boolean().optional(),
  localMusic: musicVideoLocalMusicOptionsSchema.nullable().optional(),
  instrumental: z.boolean().optional(),
  guidance: z.string().max(4000).optional(),
  tools: z.array(z.enum(MUSIC_VIDEO_AUTOMATION_TOOL_IDS)).max(MUSIC_VIDEO_AUTOMATION_TOOL_IDS.length).optional(),
  // Per-tool model pin, e.g. { 'image:local': 'flux-dev' }; absent = the install default.
  models: z.partialRecord(z.enum(MUSIC_VIDEO_AUTOMATION_TOOL_IDS), z.string().trim().min(1).max(200)).optional(),
  budgetUsd: z.number().min(0).max(MUSIC_VIDEO_AUTOMATION_BUDGET_MAX_USD).nullable().optional(),
  limits: z.object({
    maxGenerations: z.number().int().min(AUTONOMOUS_LIMIT_BOUNDS.maxGenerations.min).max(AUTONOMOUS_LIMIT_BOUNDS.maxGenerations.max).optional(),
    maxReviewAttempts: z.number().int().min(AUTONOMOUS_LIMIT_BOUNDS.maxReviewAttempts.min).max(AUTONOMOUS_LIMIT_BOUNDS.maxReviewAttempts.max).optional(),
  }).strict().optional(),
  checkpoints: z.array(z.enum(AUTONOMOUS_CHECKPOINT_IDS)).max(AUTONOMOUS_CHECKPOINT_IDS.length).optional(),
  // Reuse this existing mood board instead of generating one from the prompt.
  moodBoardId: z.string().trim().min(1).max(64).nullable().optional(),
  // Start on this project's song: its audio, analysis and lyric timing are copied,
  // so the run writes no lyrics, makes no song and skips re-analysis.
  fromProjectId: z.string().trim().min(1).max(80).optional(),
  // A built-in character style (musicVideoCharacterStyles.js) cast as protagonist from the start.
  characterStyleId: z.enum(MUSIC_VIDEO_CHARACTER_STYLE_IDS).nullable().optional(),
  // The LLM that writes the brief and lyrics (blank = an eligible TUI provider, else the
  // install's active provider — see services/musicVideo/llmRoute.js).
  providerId: z.string().trim().min(1).max(200).nullable().optional(),
  model: z.string().trim().min(1).max(200).nullable().optional(),
  effort: z.enum(EFFORT_LEVELS).nullable().optional(),
  // The separate code-authoring provider a code-rendered video needs.
  authoring: musicVideoAuthoringSchema.optional(),
  // A provider/model/effort per LLM stage; an unpinned stage uses the direction LLM above.
  llmStages: musicVideoLlmStagesSchema.nullable().optional(),
  // Review and revise the lyric draft with a second pass (the `lyricsReview` stage
  // pin when set, else the direction LLM). Pinning `llmStages.lyricsReview` implies it.
  lyricsReview: z.boolean().optional(),
  // Orchestrated mode: this provider/model/effort clears every review point a
  // director would (no checkpoints). Approval authority — the route requires a
  // signed-in session for it.
  orchestrator: musicVideoLlmSchema.optional(),
  // Make and review every still, then wait for the director before any clip.
  stopBeforeVideo: z.boolean().optional(),
  origin: z.object({
    kind: z.enum(AUTONOMOUS_ORIGINS).optional(),
    ideaId: z.string().max(80).nullable().optional(),
    ideaTitle: z.string().max(200).nullable().optional(),
  }).strict().optional(),
  suno: musicVideoSunoOptionsSchema.nullable().optional(),
  ...musicVideoAutoApproveFields,
}).strict();

// Resume a parked/failed run, or approve the checkpoint it is waiting on.
export const musicVideoAutonomousResumeSchema = z.object({
  // Change course mid-run: the brief's prompt and guidance, which production plans shots from.
  prompt: z.string().trim().min(1).max(AUTONOMOUS_PROMPT_MAX).optional(),
  guidance: z.string().max(4000).optional(),
  // Replace the stage output the director edited at a checkpoint.
  lyrics: z.string().max(20000).optional(),
  style: z.string().max(AUTONOMOUS_PROMPT_MAX).optional(),
  // Patch the brief's Suno options, key by key (null clears one).
  suno: musicVideoSunoOptionsSchema.optional(),
  // Patch the brief's local Music Studio options.
  localMusic: musicVideoLocalMusicOptionsSchema.nullable().optional(),
  // At the song checkpoint: discard the song and generate a new one.
  retakeSong: z.boolean().optional(),
  // Swap a tool's model (null clears the pin) and raise or lower the run's limits. A changed
  // model at the produce stage starts a new production run with the new pool.
  models: z.partialRecord(z.enum(MUSIC_VIDEO_AUTOMATION_TOOL_IDS), z.string().trim().min(1).max(200).nullable()).optional(),
  limits: z.object({
    maxGenerations: z.number().int().min(AUTONOMOUS_LIMIT_BOUNDS.maxGenerations.min).max(AUTONOMOUS_LIMIT_BOUNDS.maxGenerations.max).optional(),
    maxReviewAttempts: z.number().int().min(AUTONOMOUS_LIMIT_BOUNDS.maxReviewAttempts.min).max(AUTONOMOUS_LIMIT_BOUNDS.maxReviewAttempts.max).optional(),
  }).strict().optional(),
  // Add tools to the brief (e.g. a video tool once the stills are approved); the production pool follows.
  addTools: z.array(z.enum(MUSIC_VIDEO_AUTOMATION_TOOL_IDS)).max(MUSIC_VIDEO_AUTOMATION_TOOL_IDS.length).optional(),
  // Replace the brief's auto-approve grant ("auto-approve the rest").
  ...musicVideoAutoApproveFields,
}).strict();

// A generation kickoff that failed before reaching the queue (#9011) — names
// the rejected section whose claim should clear so the next resume can hand
// it out again immediately instead of waiting out GENERATION_CLAIM_LEASE_MS.
export const musicVideoRevisionReleaseSchema = z.object({
  sceneId: z.string().min(1).max(200),
}).strict();

// Optional sound-design bed (#8988): one explicitly chosen music-library track
// mixed UNDER the song. null (or omitted) keeps the song as the sole audio
// master. See services/musicVideo/soundBed.js.
export const musicVideoSoundBedSchema = z.object({
  trackId: z.string().min(1).max(64),
  volume: z.number().min(0.05).max(1).optional(),
}).strict();

// Automation-first brief: which render tools the agent may use, the director's
// free-text guidance, and a spend cap (null = no cap). A patch merges per
// sub-field; `tools` replaces its list whole. See musicVideoAutomation.js.
export const musicVideoAutomationSchema = z.object({
  tools: z.array(z.enum(MUSIC_VIDEO_AUTOMATION_TOOL_IDS)).max(MUSIC_VIDEO_AUTOMATION_TOOL_IDS.length).optional(),
  guidance: z.string().max(MUSIC_VIDEO_AUTOMATION_GUIDANCE_MAX).optional(),
  budgetUsd: z.number().min(0).max(MUSIC_VIDEO_AUTOMATION_BUDGET_MAX_USD).nullable().optional(),
  // Check-in gates: `review` stops the autopilot for the director, `auto`
  // approves and continues. Absent = review.
  checkins: z.object({
    castAndSets: z.enum(MUSIC_VIDEO_CHECKIN_MODES).optional(),
  }).strict().optional(),
  // The direction/planning LLM (#9545): absent keeps the stored pin, null clears
  // it back to Auto (an eligible TUI provider, else the active provider).
  llm: musicVideoLlmSchema.nullable().optional(),
  // Per-stage LLM pins: merged per stage, a stage set to null clears it.
  llmStages: musicVideoLlmStagesSchema.nullable().optional(),
}).strict();

// ---- Development artifacts ("ingredients") ----------------------------------
// Reviewable development files attached to a project (a Cast & Sets sheet, an
// animatic, a treatment, a storyboard). Bytes live on disk; see
// services/musicVideo/devArtifacts.js.
export const MUSIC_VIDEO_DEV_ARTIFACT_KINDS = ['cast-sets', 'animatic', 'treatment', 'storyboard', 'other'];
export const MUSIC_VIDEO_DEV_ARTIFACT_STATUSES = ['pending', 'approved', 'changes-requested'];

const devArtifactNoteText = z.string().trim().min(1).max(2000);
const devArtifactNoteTarget = z.string().trim().max(120).nullable().optional();

// The text fields of a multipart import (the file itself is the `file` part).
// `artifactId` adds a version to that artifact; otherwise kind + title create
// one. `notes` is a JSON array of strings or `{ text, target }` objects.
export const musicVideoDevArtifactImportSchema = z.object({
  artifactId: z.string().min(1).max(64).optional(),
  kind: z.enum(MUSIC_VIDEO_DEV_ARTIFACT_KINDS).optional(),
  title: z.string().trim().min(1).max(200).optional(),
  status: z.enum(MUSIC_VIDEO_DEV_ARTIFACT_STATUSES).optional(),
  notes: z.preprocess((v) => {
    if (typeof v !== 'string') return v;
    try { return JSON.parse(v); } catch { return v; }
  }, z.array(z.union([
    devArtifactNoteText,
    z.object({ text: devArtifactNoteText, target: devArtifactNoteTarget }).strict(),
  ])).max(50)).optional(),
}).strict().refine((b) => b.artifactId || b.kind, { message: 'kind is required for a new artifact', path: ['kind'] });

export const musicVideoDevArtifactNoteSchema = z.object({
  text: devArtifactNoteText,
  target: devArtifactNoteTarget,
}).strict();

export const musicVideoDevArtifactNoteUpdateSchema = z.object({
  resolved: z.boolean(),
}).strict();

export const musicVideoDevArtifactReviewSchema = z.object({
  status: z.enum(MUSIC_VIDEO_DEV_ARTIFACT_STATUSES),
  note: z.string().trim().max(2000).optional(),
}).strict();

export const musicVideoDevArtifactFileQuerySchema = z.object({
  version: z.coerce.number().int().min(1).max(1000).optional(),
}).strict();

// ---- Cast & Sets check-in -----------------------------------------------------
// Start / resume take an optional provider pin for the direction call.
export const musicVideoCastAndSetsStartSchema = z.object({
  providerId: z.string().min(1).max(64).optional(),
  model: z.string().min(1).max(200).optional(),
  effort: z.enum(EFFORT_LEVELS).optional(),
}).strict();

// Regenerate with notes. Omitted notes = the open notes on the sheet. A
// `target` names an image (`character`, `expressions`, `looks`, `cast:<id>`, `set:<id>`,
// `test:<n>`); any other note revises the direction.
export const musicVideoCastAndSetsRegenerateSchema = z.object({
  notes: z.array(z.object({
    text: devArtifactNoteText,
    target: devArtifactNoteTarget,
  }).strict()).min(1).max(50).optional(),
  providerId: z.string().min(1).max(64).optional(),
  model: z.string().min(1).max(200).optional(),
  effort: z.enum(EFFORT_LEVELS).optional(),
}).strict();

// Plain-text feedback on a Cast & Sets sheet. No target = the whole sheet
// (standing feedback the direction keeps honoring); a target names one image.
export const musicVideoCastAndSetsFeedbackSchema = z.object({
  text: devArtifactNoteText,
  target: devArtifactNoteTarget,
  providerId: z.string().min(1).max(64).optional(),
  model: z.string().min(1).max(200).optional(),
  effort: z.enum(EFFORT_LEVELS).optional(),
}).strict();

// Direct edits to a procedural direction. A present text field replaces the
// current value (empty clears it); an absent one keeps it.
const castSetsText = (max) => z.string().max(max);
export const musicVideoCastAndSetsDirectionEditSchema = z.object({
  protagonist: z.object({
    construction: castSetsText(1000).optional(),
    shapeLanguage: castSetsText(500).optional(),
    materials: castSetsText(500).optional(),
    palette: castSetsText(300).optional(),
    movement: castSetsText(1000).optional(),
    expressions: z.array(castSetsText(300)).max(8).optional(),
  }).strict().optional(),
  world: z.object({
    layout: castSetsText(1000).optional(),
    depth: castSetsText(500).optional(),
    lighting: castSetsText(500).optional(),
    camera: castSetsText(500).optional(),
    transitions: castSetsText(500).optional(),
  }).strict().optional(),
  sets: z.array(z.object({
    id: z.string().min(1).max(64),
    imageRole: z.enum(['background', 'texture', 'decoration', 'cutout']),
  }).strict()).max(8).optional(),
}).strict();

// The cutting room floor outro (lib/musicVideoStatsOutro.js): an optional scene
// after the song tallying the director's choices; null on the project = off.
export const musicVideoStatsOutroSchema = z.object({
  enabled: z.boolean().optional(),
  durationSec: z.number().min(STATS_OUTRO_LIMITS.durationMin).max(STATS_OUTRO_LIMITS.durationMax).optional(),
  title: z.string().max(STATS_OUTRO_LIMITS.textMax).optional(),
  subtitle: z.string().max(STATS_OUTRO_LIMITS.textMax).optional(),
  hidden: z.array(z.enum(STATS_OUTRO_LINES.map((line) => line.key))).max(STATS_OUTRO_LINES.length).optional(),
}).strict();

// The opening title card (lib/musicVideoTitleCard.js): song title, artist, year
// in a corner over the opener. Every field is optional (the normalizer fills
// defaults); null on the project = none.
export const musicVideoTitleCardSchema = z.object({
  enabled: z.boolean().optional(),
  title: z.string().max(TITLE_CARD_LIMITS.textMax).optional(),
  artist: z.string().max(TITLE_CARD_LIMITS.textMax).optional(),
  year: z.string().max(TITLE_CARD_LIMITS.yearMax).optional(),
  extra: z.string().max(TITLE_CARD_LIMITS.textMax).optional(),
  quoteTitle: z.boolean().optional(),
  startSec: z.number().min(0).max(TITLE_CARD_LIMITS.startMax).optional(),
  endSec: z.number().min(0).max(TITLE_CARD_LIMITS.startMax + 60).optional(),
  fadeSec: z.number().min(0).max(TITLE_CARD_LIMITS.fadeMax).optional(),
  position: z.enum(TITLE_CARD_POSITIONS).optional(),
  font: z.enum(TITLE_CARD_FONTS).optional(),
  size: z.number().min(TITLE_CARD_LIMITS.sizeMin).max(TITLE_CARD_LIMITS.sizeMax).optional(),
  color: z.string().regex(/^#[0-9a-f]{6}$/i, 'color is #rrggbb').optional(),
  style: z.enum(TITLE_CARD_STYLES).optional(),
  // '' = the look's own colour.
  titleColor: z.union([z.literal(''), z.string().regex(/^#[0-9a-f]{6}$/i, 'titleColor is #rrggbb')]).optional(),
  accentColor: z.union([z.literal(''), z.string().regex(/^#[0-9a-f]{6}$/i, 'accentColor is #rrggbb')]).optional(),
  // The optional second showing at the end of the video (null = not timed yet).
  outro: z.boolean().optional(),
  outroStartSec: z.number().min(0).max(TITLE_CARD_LIMITS.outroMax).nullable().optional(),
  outroEndSec: z.number().min(0).max(TITLE_CARD_LIMITS.outroMax + 60).nullable().optional(),
}).strict();

export const musicVideoProjectCreateSchema = z.object({
  mediaMode: z.enum(MUSIC_VIDEO_MEDIA_MODES).optional(),
  productionPolicy: musicVideoProductionPolicySchema.optional(),
  name: z.string().min(1).max(200),
  mode: z.enum(MUSIC_VIDEO_MODES).optional(),
  // The source audio: either a music-library track or an uploaded file basename
  // under data/music/. At least one is needed before analysis, but a project can
  // be created empty and have the track set later via PATCH.
  trackId: z.string().max(64).nullable().optional(),
  uploadedAudioFilename: z.string().max(256).nullable().optional(),
  performanceConditioningSource: z.enum(['master', 'vocal-stem', 'clean-singer-stem']).nullable().optional(),
  concept: musicVideoConceptSchema.nullable().optional(),
  visualSpec: musicVideoVisualSpecSchema.optional(),
  styleReferences: musicVideoStyleReferencesSchema.optional(),
  videoSettings: musicVideoVideoSettingsSchema.optional(),
  automation: musicVideoAutomationSchema.nullable().optional(),
  lyricCues: lyricCueList.optional(),
  lyricMarkers: lyricMarkerList.optional(),
  phrases: phraseList.optional(),
  pacing: musicVideoPacingSchema.nullable().optional(),
  composition: musicVideoCompositionSchema.nullable().optional(),
  soundBed: musicVideoSoundBedSchema.nullable().optional(),
  // The finishing film look (lib/filmLook.js); null = none.
  filmLook: filmLookSchema.nullable().optional(),
  // The opening title card (lib/musicVideoTitleCard.js); null = none.
  titleCard: musicVideoTitleCardSchema.nullable().optional(),
  // The cutting room floor outro after the song (lib/musicVideoStatsOutro.js); null = off.
  statsOutro: musicVideoStatsOutroSchema.nullable().optional(),
}).strict();

export const musicVideoProjectUpdateSchema = z.object({
  mediaMode: z.enum(MUSIC_VIDEO_MEDIA_MODES).optional(),
  productionPolicy: musicVideoProductionPolicySchema.optional(),
  name: z.string().min(1).max(200).optional(),
  mode: z.enum(MUSIC_VIDEO_MODES).optional(),
  status: z.enum(MUSIC_VIDEO_STATUSES).optional(),
  trackId: z.string().max(64).nullable().optional(),
  uploadedAudioFilename: z.string().max(256).nullable().optional(),
  performanceConditioningSource: z.enum(['master', 'vocal-stem', 'clean-singer-stem']).nullable().optional(),
  concept: musicVideoConceptSchema.nullable().optional(),
  visualSpec: musicVideoVisualSpecSchema.optional(),
  styleReferences: musicVideoStyleReferencesSchema.optional(),
  videoSettings: musicVideoVideoSettingsSchema.optional(),
  automation: musicVideoAutomationSchema.nullable().optional(),
  renderHistoryId: z.string().max(64).nullable().optional(),
  renderError: z.string().max(2000).nullable().optional(),
  lyricCues: lyricCueList.optional(),
  lyricMarkers: lyricMarkerList.optional(),
  phrases: phraseList.optional(),
  pacing: musicVideoPacingSchema.nullable().optional(),
  composition: musicVideoCompositionSchema.nullable().optional(),
  soundBed: musicVideoSoundBedSchema.nullable().optional(),
  // The finishing film look (lib/filmLook.js); null = none.
  filmLook: filmLookSchema.nullable().optional(),
  // The opening title card (lib/musicVideoTitleCard.js); null = none.
  titleCard: musicVideoTitleCardSchema.nullable().optional(),
  // The cutting room floor outro after the song (lib/musicVideoStatsOutro.js); null = off.
  statsOutro: musicVideoStatsOutroSchema.nullable().optional(),
  // The Create › Storyboards board this video is planned from; null unlinks.
  storyboardId: z.string().regex(STORYBOARD_ID_PATTERN, 'storyboardId must be a storyboard id').nullable().optional(),
}).strict();

// Mark a project finished outside PortOS (or clear the marker). The server
// stamps `markedAt`; the note says where it was made (musicVideoFinishedOutside.js).
export const musicVideoFinishedOutsideSchema = z.object({
  finished: z.boolean(),
  note: z.string().trim().max(500).optional(),
}).strict();

// Fork a project into its next editable version. The server derives lineage and
// version numbers from the source; callers may only override the display name
// and choose whether generated scene media should remain attached. A video
// variant always clears selected media and starts independent creative setup.
export const musicVideoProjectCloneSchema = z.object({
  name: z.string().min(1).max(200).optional(),
  includeGeneratedMedia: z.boolean().optional(),
  variant: z.enum(['revision', 'video-generation']).optional(),
}).strict();

// Review content is editable; approval records are server-owned and never PATCHable.
export const musicVideoProductionDraftSchema = z.object({
  storyboardSource: z.enum(['board', 'document']).optional(),
  cast: z.string().max(12000), environments: z.string().max(12000),
  visualLanguage: z.string().max(12000), motionLanguage: z.string().max(12000),
  implementationPlan: z.string().max(16000).optional(),
  guideArtifactId: z.string().max(64).nullable(),
  sourceArtifactId: z.string().max(64).nullable().optional(),
  lyricsMode: z.enum(['vocal', 'instrumental']), timingStatus: z.enum(['provisional', 'verified']),
  timingNotes: z.string().max(4000),
  storyboard: z.array(z.object({
    id: z.string().max(64).optional(), startSec: timedSec, endSec: timedSec,
    sceneId: z.string().max(64).nullable(), lyricCueIds: z.array(z.string().max(64)).max(2000),
    action: z.string().max(4000), staging: z.string().max(4000),
    camera: z.string().max(4000), transition: z.string().max(4000),
  }).strict()).max(2000),
}).strict();
export const musicVideoAlignmentReviewSchema = z.object({
  basis: z.string().min(1).max(128), notes: z.string().trim().max(4000).default(''),
}).strict();
export const musicVideoDocumentShotsSchema = z.object({
  documentDirectory: z.string().min(1).max(500), audioBasis: z.string().min(1).max(128),
  sourceFile: z.string().min(1).max(200),
  shots: musicVideoProductionDraftSchema.shape.storyboard.min(1),
}).strict().superRefine((value, ctx) => {
  const ids = new Set();
  for (const shot of value.shots) {
    if (!shot.id?.trim() || ids.has(shot.id) || shot.sceneId != null
      || !Number.isFinite(shot.startSec) || !(shot.endSec > shot.startSec)) {
      ctx.addIssue({ code: 'custom', message: 'Document shots need unique source IDs, positive timing and no Board scene binding' });
    }
    ids.add(shot.id);
  }
});
// Start a shot from the previous shot's on-screen out-frame; optionally keep
// the current start frame as its end frame.
export const musicVideoContinueShotSchema = z.object({ keepStillAsEnd: z.boolean().optional() }).strict();
export const musicVideoProductionImportSchema = z.object({ source: z.string().min(2).max(250000) }).strict();
export const musicVideoShotLockSchema = z.object({
  sceneIds: z.array(z.string().min(1).max(200)).min(1).max(500),
  locked: z.boolean(),
  // A video shot locks its still first (ready to render), then its clip.
  stage: z.enum(['still', 'video']).optional(),
}).strict();
export const musicVideoProductionApprovalSchema = z.object({
  stage: z.enum(['art', 'storyboard', 'proof']), basis: z.string().min(1).max(128),
  password: z.string().max(1024).optional(),
  proofReview: z.object({
    method: z.enum(['playback', 'machine']).optional(),
    watchedWithAudio: z.boolean(),
    machineEvidence: z.object({
      visualReview: z.string().trim().min(40).max(8000),
      audioReview: z.string().trim().min(40).max(8000),
      limitations: z.string().trim().min(1).max(4000),
    }).strict().optional(),
    excerptId: z.string().min(1).max(200), filename: z.string().min(1).max(200),
    energyComparison: z.string().trim().max(4000).optional(),
    timecodedNotes: z.string().trim().max(4000).optional(),
  }).strict().optional(),
}).strict();
export const musicVideoProductionProofSchema = z.object({
  kind: z.enum(['proof', 'prototype']).optional(),
  startSec: z.number().min(0), endSec: z.number().positive(),
}).strict();

// A scene on the director board. `startSec`/`endSec` place it on the timeline;
// `prompt` drives the shot's video; `framePrompt`/`referenceImageId` are the
// reference-frame inputs the i2v generation (Phase 1b) will consume.
// The linked storyboard panel a shot was fitted from (Fit to song), and a
// fingerprint of the panel as it was then, so a later panel edit shows on the shot.
const scenePanelFields = {
  panelId: z.string().regex(/^panel-[A-Za-z0-9-]{1,80}$/, 'Invalid panel id').nullable().optional(),
  panelRev: z.string().regex(/^[0-9a-z]{1,16}$/, 'Invalid panel revision').nullable().optional(),
  panelArt: z.string().regex(/^[^/\\]+\.(png|jpe?g|webp)$/i, 'Panel art must be a gallery image').nullable().optional(),
};

export const musicVideoSceneCreateSchema = z.object({
  label: z.string().max(120).optional(),
  sectionLabel: z.string().max(120).nullable().optional(),
  prompt: z.string().max(8000).optional(),
  framePrompt: z.string().max(8000).nullable().optional(),
  startSec: z.number().min(0).max(36000).nullable().optional(),
  endSec: z.number().min(0).max(36000).nullable().optional(),
  beatAligned: z.boolean().optional(),
  // #8964: shot-planning fields. `loop` is an explicit, deliberate choice to
  // repeat the source clip across a longer authored span; a scene with no
  // `loop` key is a pre-#8964 record and keeps the legacy loop-to-fill render.
  loop: z.boolean().optional(),
  sectionIndex: z.number().int().min(0).max(10000).nullable().optional(),
  lyricText: z.string().max(2000).nullable().optional(),
  visualIntent: z.string().max(2000).nullable().optional(),
  ...sceneLayerFields,
  // #8977: `performance` = a lip-synced singer that must follow the master
  // recording (only a verified source-audio provider can render it); absent or
  // `cutaway` = the ordinary image-to-video shot. See lib/musicVideoShotTiming.js.
  shotMode: z.enum(MUSIC_VIDEO_SHOT_MODES).optional(),
  performanceSpeaker: z.string().trim().max(120).nullable().optional(),
  // How a performance follows the song: lip-sync (absent/null) or music-driven motion.
  performanceStyle: z.enum(MUSIC_VIDEO_PERFORMANCE_STYLES).nullable().optional(),
  ...scenePanelFields,
}).strict().refine(
  (s) => s.startSec == null || s.endSec == null || s.endSec >= s.startSec,
  { message: 'endSec must be >= startSec', path: ['endSec'] },
);

// The last render failure persisted on a scene by the scene image/video hooks
// (#10154): which lane failed, why (one bounded line), and when.
export const musicVideoSceneLastFailureSchema = z.object({
  lane: z.enum(['image', 'video']),
  error: z.string().max(300),
  at: z.string().max(64),
}).strict();

// Times are nullable here so clearing a Start/End input (the UI sends `null`)
// is accepted. The endSec >= startSec invariant can't be checked on the partial
// patch alone (the paired value may live on the existing record), so the merged
// range is validated in projectsLogic.applySceneUpdate instead.
export const musicVideoSceneUpdateSchema = z.object({
  label: z.string().max(120).optional(),
  sectionLabel: z.string().max(120).nullable().optional(),
  prompt: z.string().max(8000).optional(),
  framePrompt: z.string().max(8000).nullable().optional(),
  startSec: z.number().min(0).max(36000).nullable().optional(),
  endSec: z.number().min(0).max(36000).nullable().optional(),
  beatAligned: z.boolean().optional(),
  // #8964: shot-planning fields. `loop` is an explicit, deliberate choice to
  // repeat the source clip across a longer authored span; a scene with no
  // `loop` key is a pre-#8964 record and keeps the legacy loop-to-fill render.
  loop: z.boolean().optional(),
  sectionIndex: z.number().int().min(0).max(10000).nullable().optional(),
  lyricText: z.string().max(2000).nullable().optional(),
  visualIntent: z.string().max(2000).nullable().optional(),
  ...sceneLayerFields,
  // #8977: `performance` = a lip-synced singer that must follow the master
  // recording (only a verified source-audio provider can render it); absent or
  // `cutaway` = the ordinary image-to-video shot. See lib/musicVideoShotTiming.js.
  shotMode: z.enum(MUSIC_VIDEO_SHOT_MODES).optional(),
  performanceSpeaker: z.string().trim().max(120).nullable().optional(),
  // How a performance follows the song: lip-sync (absent/null) or music-driven motion.
  performanceStyle: z.enum(MUSIC_VIDEO_PERFORMANCE_STYLES).nullable().optional(),
  referenceImageId: z.string().max(256).nullable().optional(),
  videoHistoryId: z.string().max(64).nullable().optional(),
  // #11173: an optional style-break end frame (the selected `endImage` take)
  // and the prompt that renders it from the start frame.
  endImageId: z.string().max(256).nullable().optional(),
  endFramePrompt: z.string().max(8000).nullable().optional(),
  // #10154: the last generation failure the render hooks persisted. The board
  // may send `null` to dismiss it; a full object is accepted so a client that
  // round-trips the scene doesn't 400.
  lastFailure: musicVideoSceneLastFailureSchema.nullable().optional(),
  ...scenePanelFields,
}).strict();

// Reorder the board: the full set of scene ids in their new order.
export const musicVideoSceneReorderSchema = z.object({
  sceneIds: z.array(z.string().min(1).max(64)).min(1).max(500),
}).strict();

// Split an over-long shot on lyric/phrase boundaries (#8977). `backend` is
// the lane the director will render with; omitted/null = the project's pin.
export const musicVideoSceneSplitSchema = z.object({
  backend: z.enum(['local', 'grok', 'fal', 'runway']).nullable().optional(),
  // Split the shot in two at this song time instead of by the backend's longest take.
  atSec: z.number().finite().nonnegative().optional(),
}).strict();

// Move where a shot starts; the shot before it ends there too, so the cut moves and nothing gaps or overlaps.
export const musicVideoSceneStartSchema = z.object({
  startSec: z.number().finite().nonnegative(),
}).strict();

// Autonomous shot planner (#1855): propose a scene per analyzed audio section.
// `seedPrompts` (default true) additionally asks the active/given AI provider
// for a first-pass framePrompt/prompt per scene — best-effort, never fails the
// plan itself (see services/musicVideo/planner.js). `providerId`/`model` mirror
// the optional override shape used elsewhere (mediaPromptRefiner, universe
// builder) so a caller can pin a specific provider instead of the active one.
export const musicVideoPlanRequestSchema = z.object({
  seedPrompts: z.boolean().optional(),
  providerId: z.string().max(64).optional(),
  model: z.string().max(200).optional(),
  effort: z.enum(EFFORT_LEVELS).optional(),
  // Required once the board has scenes (409 PLAN_MODE_REQUIRED otherwise).
  mode: z.enum(['replace', 'append']).optional(),
}).strict();

// Manual-tempo fallback (see services/musicVideo/audioAnalysis.js for why bpm
// can come back null from auto-detection). `bpm` range is loosened from the
// detector's own search window for manual entry (20-300 covers everything
// from a ballad to hardcore/gabber); `offsetSec` is the first downbeat, by ear.
export const musicVideoManualAnalysisSchema = z.object({
  bpm: z.number().min(20).max(300),
  offsetSec: z.number().min(0).max(600).default(0),
}).strict();

// MuScriptor audio → MIDI transcription request (services/audioMidiTranscription.js).
// `model` picks the MuScriptor size tier; the service clamps unknown values to
// its default, this only types the field.
export const musicVideoTranscribeMidiRequestSchema = z.object({
  model: z.enum(MUSCRIPTOR_MODELS).optional(),
}).strict();

// The persisted MIDI-transcription pointer (a .mid basename under data/music/,
// produced by the MuScriptor sidecar from the project's source audio; it lives
// with the master audio so the peer-sync asset manifest federates it). Cleared
// alongside audioAnalysis when the audio source changes — it was transcribed
// from the OLD track.
export const musicVideoMidiTranscriptionSchema = z.object({
  filename: z.string().min(1).max(256),
  model: z.string().max(32).optional(),
  createdAt: z.string().max(64).optional(),
}).strict();

// The cached beat/tempo/section map (audioAnalysis.js output). Validated when a
// record round-trips so a hand-edited/legacy project can't carry a malformed
// analysis; the analyzer itself produces this shape.
// Per-band loudness envelopes (0..1 on a fixed fps grid) and onset times for
// the seekable song feature track (#9073). `null`/absent means "not analyzed"
// (an analysis cached before the feature track existed); an empty array is
// never used as that sentinel.
const envelopeSeriesSchema = z.array(z.number().min(0).max(1)).max(200000);
const onsetTimesSchema = z.array(z.number().min(0)).max(100000);
export const musicVideoSongFeaturesSchema = z.object({
  envelopes: z.object({
    fps: z.number().positive(),
    rms: envelopeSeriesSchema,
    low: envelopeSeriesSchema,
    mid: envelopeSeriesSchema,
    high: envelopeSeriesSchema,
  }).strict(),
  onsets: z.object({
    low: onsetTimesSchema,
    mid: onsetTimesSchema,
    high: onsetTimesSchema,
  }).strict(),
  // Set when the decode was capped, so the tracks stop before the song does.
  truncatedAtSec: z.number().min(0).nullable().optional(),
}).strict();

export const musicVideoAudioAnalysisSchema = z.object({
  // Shape version: absent = 1 (pre feature track), 2 = carries `features`.
  version: z.number().int().min(1).optional(),
  features: musicVideoSongFeaturesSchema.nullable().optional(),
  bpm: z.number().nullable(),
  beats: z.array(z.number()),
  downbeats: z.array(z.number()),
  // Compact normalized loudness envelope for the director timeline. Optional
  // so cached analyses from older installs remain readable.
  waveform: z.array(z.number().min(0).max(1)).max(1024).optional(),
  sections: z.array(z.object({
    label: z.string(),
    startSec: z.number(),
    endSec: z.number(),
    // Normalized 0..1 section loudness used by the energy-weighted auto-arranger
    // (#1915). Additive + optional so older cached analyses still validate.
    energy: z.number().min(0).optional(),
    // Set when the label came from the aligned lyric sheet ("Chorus") rather
    // than the detector ("Section 3"); `analysisLabel` keeps the detector's
    // label so a later pass can restore it. Additive, so older analyses validate.
    labelSource: z.enum(['analysis', 'lyrics']).optional(),
    analysisLabel: z.string().max(120).optional(),
  })),
  durationSec: z.number(),
  // Explain whether the beat grid came from the full track, consensus among
  // later rhythmic windows, or the director's manual tap/entry fallback.
  tempoSource: z.enum(['full', 'windowed', 'manual']).nullable().optional(),
  tempoConfidence: z.number().min(0).max(1).nullable().optional(),
  tempoWindow: z.object({
    startSec: z.number().min(0),
    endSec: z.number().min(0),
  }).nullable().optional(),
}).strict();

export const musicVideoPerformanceRepairSchema = z.object({
  excerptId: z.string().min(1).max(200),
  sourceAssetId: z.string().min(1).max(200),
  boundarySec: z.number().finite().min(0).max(36000),
}).strict();


// Preserved intervals have equal duration: insertions/deletions are gaps, never stretch.
export const musicVideoAudioTimingPreviewSchema = z.object({
  targetTrackId: z.string().min(1).max(128),
  intervals: z.array(z.object({
    oldStartSec: z.number().finite().min(0).max(36000),
    oldEndSec: z.number().finite().min(0).max(36000),
    newStartSec: z.number().finite().min(0).max(36000),
  }).strict()).min(1).max(200),
}).strict();
export const musicVideoAudioTimingApplySchema = musicVideoAudioTimingPreviewSchema.extend({
  basis: z.string().regex(/^[a-f0-9]{32}$/),
});

export const musicVideoProductionFeedbackSchema = z.object({
  stage: z.enum(['art', 'storyboard', 'proof']), basis: z.string().min(1).max(128),
  target: z.string().trim().min(1).max(300), text: z.string().trim().min(1).max(8000),
  decision: z.enum(['comment', 'structure-accepted', 'request-changes']),
}).strict();
// Act on the shots a song revision flagged (songRevision.js resolveSongRevisionScenes).
export const musicVideoSongSceneActionSchema = musicVideoCastAndSetsStartSchema.extend({
  revisionId: z.string().min(1).max(128),
  action: z.enum(['replan', 'remove', 'dismiss']),
  sceneIds: z.array(z.string().min(1).max(64)).min(1).max(2000).optional(),
}).strict();
export const musicVideoProductionReviseSchema = musicVideoCastAndSetsStartSchema.extend({
  stage: z.enum(['art', 'storyboard', 'proof']),
}).strict();
// The input label a stale approval names (`concept`, `scene 3 prompt`, …) — the server finds its stored value.
export const musicVideoProductionRevertSchema = z.object({
  stage: z.enum(['art', 'storyboard', 'proof', 'castAndSets']), field: z.string().trim().min(1).max(100),
}).strict();
// Anchor these storyboard shots (every flagged shot when absent) to the lyric lines sung over them.
export const musicVideoLyricAnchorSyncSchema = z.object({
  sceneIds: z.array(z.string().min(1).max(64)).min(1).max(2000).optional(),
}).strict();
export const musicVideoProductionFeedbackResolutionSchema = z.object({
  feedbackId: z.string().min(1).max(128), resolution: z.string().trim().max(8000).default(''), password: z.string().max(1024).optional(),
}).strict();

// GET /api/music-video query (#10169). Passthrough strings, like the other list
// queries: `parsePagination` clamps `limit`/`offset`, and a malformed `cursor`
// (an offset the summary page issued) falls back to the first page.
export const musicVideoProjectListQuerySchema = z.object({
  summary: z.enum(['1', 'true', '0', 'false']).optional(),
  limit: z.string().optional(),
  offset: z.string().optional(),
  cursor: z.string().max(64).optional(),
});