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

60.9 KB
Raw Blame
import { musicVideoMediaMode, assertMusicVideoMediaSelections } from '../../lib/musicVideoMediaPolicy.js';
/**
 * Music Video — pure record transforms (issue #1760, Phase 1).
 *
 * Mirrors the Creative Director store split: the file backend (projectsFile.js)
 * and the PostgreSQL backend (projectsDB.js) share the SAME mutation semantics
 * and differ only in load/persist, so all storage-agnostic logic lives here.
 * Each function takes a plain project record and returns the next record (or
 * throws a ServerError on a validation failure), leaving read/write to the
 * caller.
 *
 * Peer-sync federation (#1770): the sanitize + LWW-merge decision helpers the CD
 * store carries now live here too (`sanitizeProjectForSync`, `mergeProjectRecord`),
 * shared by both backends so the merge can't drift. The soft-delete fields were
 * already on the record, so federation was purely additive (no record migration).
 */

import { remapMusicVideoDependencies, retainMusicVideoDependencies } from '../../lib/musicVideoDependencies.js';
import { randomUUID } from 'node:crypto';
import { normalizeMusicVideoProductionPolicy } from '../../lib/musicVideoMediumPlan.js';
import { ServerError } from '../../lib/errorHandler.js';
import {
  MUSIC_VIDEO_STATUSES,
  MUSIC_VIDEO_REFERENCE_USES,
  musicVideoAudioAnalysisSchema,
  musicVideoMidiTranscriptionSchema,
  musicVideoSceneCreateSchema,
  musicVideoSceneUpdateSchema,
} from '../../lib/validation.js';
import { compareNewerWins } from '../../lib/lwwTimestamp.js';
import { stripMusicVideoLocalRenderPins } from '../../lib/syncWire.js';
import { persistedRenderPinFields } from '../../lib/renderTargets.js';
import { sanitizeProjectForSync } from '../../lib/projectStoreKit.js';
import { isPerformanceScene, planShotSplit, shotSplitLimit } from '../../lib/musicVideoShotTiming.js';
import { normalizeLyricCues, normalizePhrases, invalidateTimedText } from './timedText.js';
import { normalizeLyricMarkers } from './lyricMarkers.js';
import { ensureSceneTakes, keepCodeClipWithItsClip, TAKE_SLOT } from './takes.js';
import { normalizeComposition, invalidateCompositionTiming, withStoredCompositionDocument } from './composition.js';
import { normalizeSoundBed } from './soundBed.js';
import { normalizeFilmLook } from '../../lib/filmLook.js';
import { stillMoveForCamera } from '../../lib/cameraMovements.js';
import { normalizeTitleCard } from '../../lib/musicVideoTitleCard.js';
import { normalizeStatsOutro } from '../../lib/musicVideoStatsOutro.js';
import { remapTreatmentForClone, scenesFingerprint } from './treatment.js';
import { anchorShotsToSungLyrics, carryStoryboardApproval, dropStaleStoryboardRows } from './productionReview.js';
import { cuesSungWithin, sungLyricTextWithin } from '../../lib/musicVideoLyricAnchors.js';
import { normalizeMusicVideoAutomation } from '../../lib/musicVideoAutomation.js';

export { sanitizeProjectForSync } from '../../lib/projectStoreKit.js';

// Re-exported for the PG backend's typed mirror columns (mirrors the CD store).
export { mirrorTimestamp } from '../../lib/pgTimestamp.js';

const STATUS_COLUMN_MAX = 32;

/** Safe value for the `status` mirror column — bounded, never null. */
export function mirrorStatus(status) {
  return (typeof status === 'string' && status ? status : 'draft').slice(0, STATUS_COLUMN_MAX);
}

/** Return the next record with `extra` merged and `updatedAt` freshly stamped. */
function touch(record, extra) {
  return retainMusicVideoDependencies(record, { ...record, ...extra, updatedAt: new Date().toISOString() });
}

/** safeParse a scene payload, throwing a 400 ServerError with field detail on failure. */
function parseSceneOrThrow(schema, input) {
  const parsed = schema.safeParse(input);
  if (!parsed.success) {
    throw new ServerError(
      `Scene validation failed: ${parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join(', ')}`,
      { status: 400, code: 'VALIDATION_ERROR' },
    );
  }
  return parsed.data;
}

/**
 * Normalize a validated visual specification (#8965): every reference persists
 * a stable id and explicit defaults so edits stay addressable and a peer reads
 * the same shape. `base` is the stored spec a partial patch merges onto — each
 * sub-field present in the patch replaces its stored value; absent ones keep it.
 */
function normalizeVisualSpec(patch, base = null) {
  const merged = { ...(base || {}), ...(patch || {}) };
  const references = (Array.isArray(merged.references) ? merged.references : []).map((ref) => ({
    id: typeof ref.id === 'string' && ref.id ? ref.id : `mvr-${randomUUID()}`,
    imageId: ref.imageId,
    role: ref.role || 'mood',
    label: typeof ref.label === 'string' ? ref.label : '',
    note: typeof ref.note === 'string' ? ref.note : '',
    condition: ref.condition === true,
    // #8980 — reference (default) / final-visible / motion-reference.
    use: MUSIC_VIDEO_REFERENCE_USES.includes(ref.use) ? ref.use : 'reference',
  }));
  return {
    references,
    palette: Array.isArray(merged.palette) ? merged.palette.map((c) => c.toLowerCase()) : [],
    typography: typeof merged.typography === 'string' ? merged.typography : '',
    cameraRules: typeof merged.cameraRules === 'string' ? merged.cameraRules : '',
    moodBoardId: typeof merged.moodBoardId === 'string' && merged.moodBoardId ? merged.moodBoardId : null,
  };
}

/** Build a fresh project record from validated create input. */
export function buildProjectRecord(input, { id, now }) {
  const productionPolicy = normalizeMusicVideoProductionPolicy(input.productionPolicy || (input.mediaMode ? { strategy: 'code-first', maxGeneratedVideoPercent: input.mediaMode === 'code-images-video' ? 100 : 0 } : null));
  const {
    name, mode = 'director', trackId = null,
    uploadedAudioFilename = null, concept = null,
    videoSettings = {},
  } = input;
  return {
    id,
    name,
    version: 1,
    parentProjectId: null,
    rootProjectId: null,
    status: 'draft',
    mode,
    createdAt: now,
    updatedAt: now,
    trackId,
    uploadedAudioFilename,
    ...(input.performanceConditioningSource ? { performanceConditioningSource: input.performanceConditioningSource } : {}),
    concept,
    // #8965 — the reusable visual specification (moodboard/reference assets,
    // palette, typography, camera rules). Null until the director sets one.
    visualSpec: input.visualSpec ? normalizeVisualSpec(input.visualSpec) : null,
    ...(input.styleReferences ? { styleReferences: input.styleReferences } : {}),
    videoSettings: {
      ...(videoSettings.renderPool ? { renderPool: videoSettings.renderPool } : {}),
      backend: videoSettings.backend ?? 'local',
      modelId: videoSettings.modelId ?? null,
      grokDuration: videoSettings.grokDuration ?? 10,
      falDuration: videoSettings.falDuration ?? null,
      falModelId: videoSettings.falModelId ?? null,
      falResolution: videoSettings.falResolution ?? null,
      falEndFrameModelId: videoSettings.falEndFrameModelId ?? null,
      falLipSyncResolution: videoSettings.falLipSyncResolution ?? null,
      falMusicModelId: videoSettings.falMusicModelId ?? null,
      falMusicResolution: videoSettings.falMusicResolution ?? null,
      falLipSyncTranscription: videoSettings.falLipSyncTranscription ?? null,
      runwayModelId: videoSettings.runwayModelId ?? null,
      runwayDuration: videoSettings.runwayDuration ?? null,
      runwayResolution: videoSettings.runwayResolution ?? null,
      generationMode: videoSettings.generationMode ?? 'image',
      audioReactiveLora: videoSettings.audioReactiveLora ?? null,
      audioReactiveScale: videoSettings.audioReactiveScale ?? 1.2,
    },
    // #3231 Phase 4 — per-record image render pin for scene reference-frame
    // renders (the shared universe/series/sprite field pair). Present only
    // when set, so existing records keep their on-disk shape byte-stable.
    ...persistedRenderPinFields(input),
    // Automation-first brief (tools, guidance, budget). Present only when set,
    // so director-authored records keep their on-disk shape byte-stable.
    ...(input.automation ? { automation: normalizeMusicVideoAutomation(input.automation) } : {}),
    audioAnalysis: null,
    midiTranscription: null,
    // #8964 — editable timed lyric cues + phrase annotations (timed against
    // the current audio source) and the shot planner's pacing range.
    lyricCues: Array.isArray(input.lyricCues) ? normalizeLyricCues(input.lyricCues) : [],
    // Section headers + stage directions read off the lyric sheet, anchored to
    // cue indices (lyricMarkers.js). Present only when the sheet had any, so a
    // record without them keeps its shape.
    ...(Array.isArray(input.lyricMarkers) && input.lyricMarkers.length
      ? { lyricMarkers: normalizeLyricMarkers(input.lyricMarkers) }
      : {}),
    phrases: Array.isArray(input.phrases) ? normalizePhrases(input.phrases) : [],
    pacing: input.pacing ?? null,
    // #8984 — composition manifest (null = plain concatenation render).
    // The document pointer is set only by the import routes, never on create.
    // A code-first project authors a document; a footage project composes its shots.
    composition: input.composition || input.mediaMode ? withStoredCompositionDocument(normalizeComposition(input.composition
      || { mode: productionPolicy.strategy === 'code-first' ? 'document' : 'composed' }), null) : null,
    // #8988 — optional sound-design bed mixed under the song.
    soundBed: input.soundBed ? normalizeSoundBed(input.soundBed) : null,
    // The finishing film look every preview, render and baked still is viewed through; null = none.
    filmLook: input.filmLook ? normalizeFilmLook(input.filmLook) : null,
    // The opening title card (song, artist, year over the opener); null = none.
    titleCard: normalizeTitleCard(input.titleCard),
    // The cutting room floor outro after the song; null = off.
    statsOutro: normalizeStatsOutro(input.statsOutro),
    // #8980 — optional pre-production treatment (brief, arc, shot direction,
    // proof checklist); null until the director starts one. See treatment.js.
    treatment: null,
    mediaMode: musicVideoMediaMode(input),
    productionPolicy,
    scenes: [],
    renderHistoryId: null,
    renderError: null,
    // Soft-delete tombstone trio — kept so peer-sync federation (a follow-up)
    // is additive rather than a record-shape migration.
    deleted: false,
    deletedAt: null,
  };
}

function mintCloneSceneId(scene, sceneIdMap) {
  const next = `mvs-${randomUUID()}`;
  sceneIdMap.set(scene.sceneId, next);
  return next;
}

/** Build an independently editable next version while reusing immutable media assets. */
export function cloneProjectRecord(source, {
  id,
  now,
  name,
  includeGeneratedMedia = true,
  variant = 'revision',
}) {
  // Record metadata is independently editable; only immutable asset bytes are shared.
  source = structuredClone(source);
  const videoVariant = variant === 'video-generation';
  if (videoVariant) includeGeneratedMedia = false;
  const nameMatch = typeof source.name === 'string' ? source.name.match(/^(.*?)(?:\s+v(\d+))?$/i) : null;
  const inferredVersion = Number(nameMatch?.[2]) || 1;
  const sourceVersion = Number.isInteger(source.version) && source.version > 0
    ? source.version
    : inferredVersion;
  const version = sourceVersion + 1;
  const baseName = nameMatch?.[1]?.trim() || source.name || 'Music Video';
  const sceneIdMap = new Map();
  const scenes = (source.scenes || []).map((scene, order) => ({
    ...scene,
    sceneId: mintCloneSceneId(scene, sceneIdMap),
    order,
    referenceImageId: includeGeneratedMedia ? (scene.referenceImageId ?? null) : null,
    videoHistoryId: includeGeneratedMedia ? (scene.videoHistoryId ?? null) : null,
    endImageId: includeGeneratedMedia ? (scene.endImageId ?? null) : null,
    // Takes are immutable pointers to shared media, so a media-keeping clone
    // carries the whole candidate history; a clean clone starts empty.
    takes: includeGeneratedMedia ? ensureSceneTakes(scene, now) : [],
  }));
  for (const scene of scenes) scene.takes = scene.takes.map((take) => ({ ...take,
    ...(take.dependencies ? { dependencies: remapMusicVideoDependencies(take.dependencies, sceneIdMap) } : {}),
  }));
  const mediaReady = includeGeneratedMedia
    && scenes.length > 0
    && scenes.every((scene) => scene.referenceImageId && scene.videoHistoryId);

  const clone = {
    ...source,
    id,
    name: name?.trim() || `${baseName} v${version}`,
    version,
    parentProjectId: source.id,
    rootProjectId: source.rootProjectId || source.id,
    status: source.audioAnalysis ? (mediaReady ? 'ready' : 'analyzed') : 'draft',
    createdAt: now,
    updatedAt: now,
    scenes,
    ...(source.composition ? { composition: {
      ...source.composition,
      ...(source.composition.codeVideo ? { codeVideo: { ...source.composition.codeVideo,
        sections: source.composition.codeVideo.sections.map((section) => ({ ...section, id: sceneIdMap.get(section.id) ?? section.id })),
      } } : {}),
      ...(source.composition.reactiveSections ? { reactiveSections: source.composition.reactiveSections.map((section) => ({
        ...section, sectionId: sceneIdMap.get(section.sectionId) ?? section.sectionId,
      })) } : {}),
      ...(source.composition.grade ? { grade: { ...source.composition.grade, sections: (source.composition.grade.sections || []).map((section) => ({
        ...section, sceneId: sceneIdMap.get(section.sceneId) ?? section.sceneId,
      })) } } : {}),
    } } : {}),
    // #8980 — the treatment's shot directions and proofs follow the scenes to
    // their new ids; proof evidence the clone can't back is dropped.
    treatment: source.treatment ? remapTreatmentForClone(source.treatment, sceneIdMap, {
      includeGeneratedMedia,
      sourceRenderId: source.renderHistoryId ?? null,
      sourceScenesFingerprint: scenesFingerprint(source.scenes || []),
      cloneScenesFingerprint: scenesFingerprint(scenes),
    }) : null,
    // #8987 — a draft's section map follows the scenes to their new ids, so a
    // clone can still revise from the review notes it carried over (#8986).
    ...(Array.isArray(source.excerpts) ? {
      // A running encoder belongs only to the source project. Copying its
      // partial-file ownership would let clone recovery delete that output.
      excerpts: source.excerpts.filter((excerpt) => excerpt?.status !== 'rendering').map((excerpt) => (Array.isArray(excerpt?.sections)
        ? { ...excerpt, dependencies: remapMusicVideoDependencies(excerpt.dependencies, sceneIdMap), sections: excerpt.sections.map((s) => ({ ...s, sceneId: sceneIdMap.get(s.sceneId) ?? s.sceneId })) }
        : excerpt)),
    } : {}),
    // A revision is in-progress work against the SOURCE's takes; the clone
    // starts with none (its carried-over notes can open a fresh one).
    revisions: [],
    songRevision: null,
    songRevisionHistory: [...(source.songRevisionHistory || []), ...(source.songRevision ? [source.songRevision] : [])],
    audioTimingRevisions: [],
    // #9102: an auto-review run is tied to the SOURCE's revisions/excerpts, so a
    // clone starts with none (terminal runs too — their links are source-scoped).
    ...(Array.isArray(source.autoReviews) ? { autoReviews: [] } : {}),
    // #9066: a production run executes against the SOURCE's scenes and jobs.
    ...(Array.isArray(source.productionRuns) ? { productionRuns: [] } : {}),
    // An autonomous run executes against the SOURCE's audio, board and production.
    ...(source.autonomousRun ? { autonomousRun: null } : {}),
    // Development artifacts ride along as-is: every version is an immutable
    // file, so the clone points at the same bytes (devArtifacts.js). The Cast
    // & Sets check-in keeps its direction and images, but its dispatch pin and
    // production link belong to the source — a working stage reads as
    // interrupted on the clone and can be resumed there.
    productionReview: source.productionReview ? { feedback: source.productionReview.feedback || [], reviewedRevisions: source.productionReview.reviewedRevisions || {}, draft: { ...source.productionReview.draft, timingStatus: 'provisional',
      storyboard: (source.productionReview.draft?.storyboard || []).map(shot => ({ ...shot, sceneId: sceneIdMap.get(shot.sceneId) || shot.sceneId })),
      ...(videoVariant ? { cast: '', environments: '', visualLanguage: '', motionLanguage: '', guideArtifactId: null } : {}),
    }, approvals: {}, proof: null } : null,
    ...(source.castAndSets ? { castAndSets: { ...source.castAndSets, processId: null, productionRunId: null } } : {}),
    renderHistoryId: null,
    renderError: null,
    renderDependencies: null,
    // Publishing outputs and posted URLs belong to the source final render.
    ...(source.publishKit ? { publishKit: null } : {}),
    // Finished outside PortOS describes the source's video; the new version is made here.
    ...(source.finishedOutside ? { finishedOutside: null } : {}),
    // #9010: the source's in-flight render mark is not the clone's.
    renderingOn: null,
    renderPartialFilename: null,
    renderResume: null,
    deleted: false,
    deletedAt: null,
  };
  if (!videoVariant) return clone;
  // A footage adaptation starts with the same song and storyboard, but no
  // procedural approvals, selected takes or running work. Nothing is dispatched.
  const footageDirection = (direction) => ({ ...direction, route: 'generated',
    medium: 'generated-footage', mediumPinned: false, mediumRationale: '' });
  return {
    ...clone,
    mediaMode: 'code-images-video',
    composition: { ...clone.composition, mode: 'composed' },
    productionPolicy: normalizeMusicVideoProductionPolicy({ strategy: 'legacy' }),
    castAndSets: null,
    visualSpec: clone.visualSpec ? { ...clone.visualSpec, references: [], moodBoardId: null } : null,
    // The cast resets, so a loaded character style (which casts the protagonist) does too.
    concept: clone.concept ? { ...clone.concept, subjects: [], moodBoardStyle: '', characterStyleId: null, characterStyle: '' } : null,
    styleReferences: [],
    ...(clone.automation ? { automation: { ...clone.automation, tools: [], moodBoardId: null } } : {}),
    scenes: clone.scenes.map((scene) => ({ ...scene, visualLayer: 'footage',
      ...(scene.direction ? { direction: footageDirection(scene.direction) } : {}),
    })),
    treatment: clone.treatment ? { ...clone.treatment, appliedRevision: null, basis: null,
      shotDirections: clone.treatment.shotDirections.map(footageDirection),
    } : null,
    excerpts: [],
  };
}

/** Merge a project metadata patch, validating status. Returns the next record. */
export function applyProjectPatch(project, patch) {
  if (patch.status && !MUSIC_VIDEO_STATUSES.includes(patch.status)) {
    throw new ServerError(`Invalid status: ${patch.status}`, { status: 400, code: 'VALIDATION_ERROR' });
  }
  // A `concept` patch merges into the existing concept sub-fields rather than
  // replacing the whole object — mirrors applySceneUpdate's per-field scene merge
  // below, so a caller sending only the sub-field it edited (e.g. { style: '…' })
  // can't clobber a sibling sub-field (e.g. prompt) set concurrently by another
  // sync peer (#3168). An explicit `concept: null` still clears it outright.
  // Edited cue/phrase lists replace the stored list whole, normalized so every
  // entry persists a stable id and a forward time range (timedText.js). A
  // `visualSpec` patch merges per sub-field the same way (#8965).
  const timedPatch = {
    ...patch,
    ...(patch.productionPolicy ? { productionPolicy: normalizeMusicVideoProductionPolicy(patch.productionPolicy, project.productionPolicy) } : {}),
    ...(patch.visualSpec ? { visualSpec: normalizeVisualSpec(patch.visualSpec, project.visualSpec) } : {}),
    // Automation brief merges per sub-field; null clears it.
    ...('automation' in patch ? {
      automation: patch.automation ? normalizeMusicVideoAutomation(patch.automation, project.automation) : null,
    } : {}),
    ...(Array.isArray(patch.lyricCues) ? { lyricCues: normalizeLyricCues(patch.lyricCues).map((cue) => {
      const previous = project.lyricCues?.find((entry) => entry.id === cue.id);
      if (previous && previous.text !== cue.text) {
        delete cue.matched;
        delete cue.suspect;
      }
      return cue;
    }) } : {}),
    ...(Array.isArray(patch.lyricMarkers) ? { lyricMarkers: normalizeLyricMarkers(patch.lyricMarkers) } : {}),
    ...(Array.isArray(patch.phrases) ? { phrases: normalizePhrases(patch.phrases) } : {}),
    // #8984 — a manifest carrying its `mode` replaces the stored one whole
    // (the editors send the full manifest, so an omitted key clears it); null
    // clears it all. One without `mode` is a partial patch and merges over the
    // stored manifest, so `{ style }` cannot silently reset mode and cutting.
    // The composition document pointer is owned by the import routes: a PATCH
    // that echoes (or omits, or forges) it keeps the stored one.
    ...('composition' in patch ? { composition: withStoredCompositionDocument(normalizeComposition(
      patch.composition && typeof patch.composition === 'object' && !('mode' in patch.composition) && project.composition
        ? { ...project.composition, ...patch.composition } : patch.composition), project.composition) } : {}),
    // #8988 — an explicitly chosen sound-design bed; null clears it.
    ...('soundBed' in patch ? { soundBed: normalizeSoundBed(patch.soundBed) } : {}),
    // The film look is replaced whole (one bounded record); null clears it.
    ...('filmLook' in patch ? { filmLook: normalizeFilmLook(patch.filmLook) } : {}),
    // The title card is replaced whole (one bounded record); null clears it.
    ...('titleCard' in patch ? { titleCard: normalizeTitleCard(patch.titleCard) } : {}),
    // The outro after the song is replaced whole; null turns it off.
    ...('statsOutro' in patch ? { statsOutro: normalizeStatsOutro(patch.statsOutro) } : {}),
  };
  // #8988: a bed is mixed UNDER the song — the song itself can't be its bed.
  const masterTrackId = 'trackId' in patch ? patch.trackId : project.trackId;
  if (timedPatch.soundBed && masterTrackId && timedPatch.soundBed.trackId === masterTrackId) {
    throw new ServerError('The sound-design bed must be a different track from the song', { status: 422, code: 'SOUND_BED_IS_MASTER' });
  }
  const conceptMergedPatch = ('concept' in timedPatch && timedPatch.concept && project.concept)
    ? { ...timedPatch, concept: { ...project.concept, ...timedPatch.concept } }
    : timedPatch;
  // Renderer settings are edited independently in the UI. Merge a partial
  // change so picking a model cannot discard the provider or Grok duration.
  const mergedPatch = ('videoSettings' in conceptMergedPatch && conceptMergedPatch.videoSettings)
    ? {
      ...conceptMergedPatch,
      videoSettings: {
        backend: 'local',
        modelId: null,
        grokDuration: 10,
        falDuration: null,
        falModelId: null,
        falResolution: null,
        falEndFrameModelId: null,
        falLipSyncResolution: null,
        falMusicModelId: null,
        falMusicResolution: null,
        generationMode: 'image',
        audioReactiveLora: null,
        audioReactiveScale: 1.2,
        ...project.videoSettings,
        ...conceptMergedPatch.videoSettings,
      },
    }
    : conceptMergedPatch;
  // Changing the audio source invalidates the cached beat/tempo analysis —
  // it was computed from the OLD track. AI Plan / Auto-arrange / BeatTimeline
  // gate on `audioAnalysis` truthiness, and the render's beat-snap step reads
  // its `beats` array; a stale analysis would silently apply the previous
  // song's beat grid to the new audio (#1945 — both the manual "Change
  // track" picker and the YouTube-import attach PATCH through here). Any
  // scene already marked `beatAligned` also stops being true — its saved
  // startSec/endSec were snapped to the OLD song's beat positions, and
  // `beatSnapClips` honors a beat-aligned scene's saved bounds outright
  // (skipping re-derivation against the new, absent beat grid), so leaving
  // the flag set would render the old song's cut points against new audio.
  const trackChanged = ('trackId' in patch && patch.trackId !== project.trackId)
    || ('uploadedAudioFilename' in patch && patch.uploadedAudioFilename !== project.uploadedAudioFilename);
  if ('mediaMode' in patch || patch.visualSpec || patch.styleReferences) assertMusicVideoMediaSelections({ ...project, ...mergedPatch });
  if (!trackChanged) return touch(project, mergedPatch);
  // A planned section belongs to the old audio too; clear its provenance so
  // the renderer does not preserve that plan's timing on the replacement song.
  const scenes = (project.scenes || []).map((s) => (s.beatAligned || s.sectionIndex != null
    ? { ...s, beatAligned: false, sectionIndex: null } : s));
  // Clearing audioAnalysis means the project must be re-analyzed before it can be
  // planned/arranged/rendered, so a status that implies analysis existed
  // (`analyzed`/`ready`/`rendering`/`complete`) is now stale. Regress it to `draft` —
  // the inverse of setAudioAnalysis's draft→analyzed flip — unless the caller set an
  // explicit status in this same patch. `draft`/`failed` already imply no usable
  // analysis, so leave those untouched.
  const regressStatus = !patch.status && !['draft', 'failed'].includes(project.status);
  const statusPatch = regressStatus ? { status: 'draft' } : {};
  // The MIDI transcription was produced from the OLD audio too — clear it with
  // the analysis so a stale .mid can't masquerade as the new track's score.
  // Lyric-cue and phrase timings were aligned to the OLD audio as well: keep the
  // director's text but clear the times and word timings (#8964, #9074), unless
  // this same patch supplied fresh lists of its own.
  return touch(project, {
    ...invalidateTimedText(project),
    // Composition cue times and the poster frame were set against the old
    // song too: keep the text, clear the timings (#8984).
    ...(project.composition ? { composition: invalidateCompositionTiming(project.composition) } : {}),
    // A vocal stem is a bounce of the OLD song; conditioning a performance on
    // it against the new master would sing the wrong words (#8977).
    ...(project.vocalStemFilename ? { vocalStemFilename: null } : {}),
    performanceConditioningSource: 'master',
    ...mergedPatch,
    ...statusPatch,
    audioAnalysis: null,
    midiTranscription: null,
    scenes,
  });
}

/**
 * Cache the offline beat/tempo/section analysis on the project. Flips a `draft`
 * project to `analyzed`; leaves any later status untouched (re-analysis of a
 * ready/rendering project shouldn't regress its lifecycle). The analysis shape
 * is validated so a hand-edited/legacy record can't store a malformed map.
 */
export function setAudioAnalysis(project, analysis, sourceProject) {
  if (sourceProject && (project.trackId !== sourceProject.trackId || project.uploadedAudioFilename !== sourceProject.uploadedAudioFilename)) {
    throw new ServerError('The audio changed during analysis. Analyze the selected master again.', { status: 409, code: 'MUSIC_VIDEO_AUDIO_CHANGED' });
  }
  const validated = musicVideoAudioAnalysisSchema.parse(analysis);
  const status = project.status === 'draft' ? 'analyzed' : project.status;
  return touch(project, { audioAnalysis: validated, status });
}

/**
 * Cache the MuScriptor audio → MIDI transcription pointer on the project (a
 * .mid basename under /api/uploads). Validated so a hand-edited/legacy record
 * can't store a malformed pointer; doesn't touch the lifecycle status — the
 * MIDI is a parsing artifact, not an arrangement step.
 */
export function setMidiTranscription(project, midi) {
  const validated = musicVideoMidiTranscriptionSchema.parse(midi);
  return touch(project, { midiTranscription: validated });
}

/** Default runtime fields for a scene the director (or planner) didn't supply. */
function buildScene(input, { order }) {
  return {
    sceneId: `mvs-${randomUUID()}`,
    order,
    label: input.label ?? '',
    sectionLabel: input.sectionLabel ?? null,
    startSec: input.startSec ?? null,
    endSec: input.endSec ?? null,
    beatAligned: input.beatAligned ?? false,
    prompt: input.prompt ?? '',
    framePrompt: input.framePrompt ?? null,
    // #8964: a new shot never silently repeats its clip to fill a span — looping
    // is an explicit choice. (Pre-#8964 scenes carry no `loop` key and keep the
    // legacy loop-to-fill render; see render.js#sceneLoops.)
    loop: input.loop ?? false,
    sectionIndex: input.sectionIndex ?? null,
    lyricText: input.lyricText ?? null,
    visualIntent: input.visualIntent ?? null,
    ...(input.frameReferenceIds ? { frameReferenceIds: input.frameReferenceIds } : {}),
    ...(input.characterVariant ? { characterVariant: input.characterVariant } : {}),
    // #8985: what a composed render shows for this span (render.js#sceneLayer).
    visualLayer: input.visualLayer ?? 'footage',
    stillMove: input.stillMove ?? 'hold',
    // #10589: the planned camera move (absent on hand-added and pre-#10589 shots).
    ...(input.camera ? { camera: input.camera } : {}),
    cardText: input.cardText ?? null,
    ...(input.codeOverlay ? { codeOverlay: true } : {}),
    ...(input.codeClip ? { codeClip: true } : {}),
    ...(input.frameFit ? { frameFit: input.frameFit } : {}),
    ...(input.speedFps ? { speedFps: input.speedFps } : {}),
    ...(input.offsetFrames ? { offsetFrames: input.offsetFrames } : {}),
    ...(input.reverse ? { reverse: true } : {}),
    ...(input.holdLastFrame ? { holdLastFrame: true } : {}),
    ...(input.filmLook ? { filmLook: normalizeFilmLook(input.filmLook) } : {}),
    ...(input.transitionIn ? { transitionIn: input.transitionIn } : {}),
    ...(input.transitionOut ? { transitionOut: input.transitionOut } : {}),
    ...(input.glitches?.length ? { glitches: input.glitches } : {}),
    ...(input.cutEffect ? { cutEffect: input.cutEffect } : {}),
    ...(input.imageEffect ? { imageEffect: input.imageEffect } : {}),
    ...(input.imageEffectSec ? { imageEffectSec: input.imageEffectSec } : {}),
    cardColor: input.cardColor ?? null,
    ...(input.textZone ? { textZone: input.textZone } : {}),
    ...(input.lyricRole ? { lyricRole: input.lyricRole } : {}),
    ...(input.lyricSize ? { lyricSize: input.lyricSize } : {}),
    // #8977: cutaway (any image-to-video lane) unless the director asks for a
    // lip-synced performance shot, which only a source-audio provider renders.
    shotMode: input.shotMode ?? 'cutaway',
    ...(input.performanceSpeaker ? { performanceSpeaker: input.performanceSpeaker } : {}),
    ...(input.performanceStyle === 'music' ? { performanceStyle: 'music' } : {}),
    ...(input.panelId ? { panelId: input.panelId, panelRev: input.panelRev ?? null, panelArt: input.panelArt ?? null } : {}),
    referenceImageId: null,
    videoHistoryId: null,
    // #8965 — immutable candidate takes; the two slot fields above are the
    // director's selection among them (see takes.js).
    takes: [],
  };
}

/** Where a new scene goes: before the first timed scene that starts after it; untimed scenes go last. */
function insertByTime(scenes, scene) {
  const at = scene.startSec;
  const idx = typeof at === 'number' ? scenes.findIndex((s) => typeof s.startSec === 'number' && s.startSec > at) : -1;
  return idx < 0 ? [...scenes, scene] : [...scenes.slice(0, idx), scene, ...scenes.slice(idx)];
}

/**
 * Add a scene to the board at its time. Validates the input, assigns a sceneId and
 * renumbers order. Returns `{ project, scene }`. A thin single-item wrapper
 * over `addScenes` so the validate/build/order logic lives in exactly one
 * place.
 */
export function addScene(project, sceneInput) {
  const { project: next, scenes } = addScenes(project, [sceneInput]);
  return { project: next, scene: scenes[0] };
}

/**
 * Add several scenes to the board in one pass (the autonomous planner,
 * #1855) — a single `touch`/persist instead of N sequential addScene calls, so
 * a 10-section plan is one write (and one peer-sync emit) instead of ten.
 * A timed scene goes in at its time, so the board stays in song order; an
 * untimed one is appended. Returns `{ project, scenes }` (the newly-created
 * scenes, in input order).
 */
export function addScenes(project, sceneInputs) {
  const list = Array.isArray(sceneInputs) ? sceneInputs : [];
  let scenes = project.scenes || [];
  const ids = [];
  for (const input of list) {
    const data = parseSceneOrThrow(musicVideoSceneCreateSchema, input);
    const scene = buildScene(data, { order: 0 });
    ids.push(scene.sceneId);
    scenes = insertByTime(scenes, scene);
  }
  scenes = scenes.map((s, i) => (s.order === i ? s : { ...s, order: i }));
  const next = touch(project, { scenes });
  return { project: next, scenes: ids.map((id) => scenes.find((s) => s.sceneId === id)) };
}

/**
 * Replace the whole board with freshly planned scenes (AI Plan "Replace").
 * A new shot whose time span matches an old scene (within 10 ms) inherits that
 * scene's id, direction, reference frame, selected clip and takes, so the
 * generated work and treatment direction keyed to the id survive the re-plan.
 * Returns `{ project, scenes, replaced }` (`replaced` = the old scene count).
 */
export function replaceScenes(project, sceneInputs) {
  const list = Array.isArray(sceneInputs) ? sceneInputs : [];
  const existing = project.scenes || [];
  const claimed = new Set();
  const sameSpan = (a, b) => typeof a === 'number' && typeof b === 'number' && Math.abs(a - b) < 0.01;
  const scenes = list.map((input, order) => {
    const fresh = buildScene(parseSceneOrThrow(musicVideoSceneCreateSchema, input), { order });
    const prior = existing.find((old) => !claimed.has(old.sceneId)
      && sameSpan(old.startSec, fresh.startSec) && sameSpan(old.endSec, fresh.endSec));
    if (!prior) return fresh;
    claimed.add(prior.sceneId);
    return {
      ...fresh,
      sceneId: prior.sceneId,
      referenceImageId: prior.referenceImageId ?? null,
      videoHistoryId: prior.videoHistoryId ?? null,
      ...(prior.endImageId ? { endImageId: prior.endImageId } : {}),
      ...(prior.endFramePrompt ? { endFramePrompt: prior.endFramePrompt } : {}),
      ...(prior.frameFit ? { frameFit: prior.frameFit } : {}),
      ...(prior.speedFps ? { speedFps: prior.speedFps } : {}),
      ...(prior.offsetFrames ? { offsetFrames: prior.offsetFrames } : {}),
      ...(prior.reverse ? { reverse: true } : {}),
      ...(prior.holdLastFrame ? { holdLastFrame: true } : {}),
      ...(prior.filmLook ? { filmLook: prior.filmLook } : {}),
      ...(prior.transitionIn ? { transitionIn: prior.transitionIn } : {}),
      ...(prior.transitionOut ? { transitionOut: prior.transitionOut } : {}),
      ...(prior.glitches?.length ? { glitches: prior.glitches } : {}),
      ...(prior.cutEffect ? { cutEffect: prior.cutEffect } : {}),
      // A still playing an image effect stays one: the effect is the shot's picture.
      ...(prior.imageEffect && prior.visualLayer === 'still' ? { visualLayer: 'still', imageEffect: prior.imageEffect,
        ...(prior.imageEffectSec ? { imageEffectSec: prior.imageEffectSec } : {}) } : {}),
      takes: prior.takes || [],
      ...(prior.direction ? { direction: prior.direction } : {}),
    };
  });
  // Rows bound to shots the new plan dropped go with them.
  return { project: dropStaleStoryboardRows(touch(project, { scenes })), scenes, replaced: existing.length };
}

// Scene fields a director edits within an approved shot (its span, wording, selected
// takes, and whether it plays as a clip or its still with an image effect) without
// adding a shot or lyric the storyboard approval did not cover.
const SCENE_SHOT_EDIT_FIELDS = ['startSec', 'endSec', 'beatAligned', 'label', 'prompt', 'framePrompt', 'visualIntent',
  'referenceImageId', 'videoHistoryId', 'endImageId', 'codeClip', 'frameFit', 'speedFps', 'offsetFrames', 'reverse', 'holdLastFrame', 'filmLook', 'transitionIn', 'transitionOut', 'glitches', 'cutEffect',
  'visualLayer', 'stillMove', 'imageEffect', 'imageEffectSec', 'frameReferenceIds', 'characterVariant', 'panelId', 'panelRev', 'panelArt'];

/**
 * Apply a patch to a single scene. Returns `{ project, updated }`. Throws if the
 * scene id is unknown.
 */
export function applySceneUpdate(project, sceneId, patch) {
  const parsed = parseSceneOrThrow(musicVideoSceneUpdateSchema, patch);
  // A shot's own look is stored complete; null returns it to the video's look.
  const data = 'filmLook' in parsed ? { ...parsed, filmLook: parsed.filmLook ? normalizeFilmLook(parsed.filmLook) : null } : parsed;
  const scenes = project.scenes || [];
  const idx = scenes.findIndex((s) => s.sceneId === sceneId);
  if (idx < 0) throw new ServerError('Scene not found', { status: 404, code: 'NOT_FOUND' });
  const kept = 'codeClip' in data ? { ...scenes[idx], ...data } : keepCodeClipWithItsClip(scenes[idx], { ...scenes[idx], ...data });
  // A shot turning into a still takes the nearest move to its planned camera (#10589) unless
  // it already has one; from then on its Move picker owns how the still moves.
  const becomesStill = data.visualLayer === 'still' && scenes[idx].visualLayer !== 'still' && !('stillMove' in data) && (kept.stillMove ?? 'hold') === 'hold';
  const seeded = becomesStill ? stillMoveForCamera(kept.camera) : null;
  const merged = seeded ? { ...kept, stillMove: seeded } : kept;
  // Setting a slot directly (an older client, or a hand edit) still records the
  // asset as a take so the candidate list stays a superset of the selection.
  const touchesSlot = Object.values(TAKE_SLOT).some((field) => typeof data[field] === 'string');
  const updated = touchesSlot ? { ...merged, takes: ensureSceneTakes(merged, undefined, 'manual') } : merged;
  // The partial-patch schema can't enforce endSec >= startSec (the paired value
  // may be unchanged on the record), so validate the merged range here.
  if (updated.startSec != null && updated.endSec != null && updated.endSec < updated.startSec) {
    throw new ServerError('endSec must be >= startSec', { status: 400, code: 'VALIDATION_ERROR' });
  }
  // A retimed shot shows, and anchors, the lyric lines now sung over it.
  const retimed = (('startSec' in data && data.startSec !== scenes[idx].startSec) || ('endSec' in data && data.endSec !== scenes[idx].endSec))
    && (project.lyricCues || []).some((cue) => typeof cue?.startSec === 'number');
  if (retimed && !('lyricText' in data)) {
    updated.lyricText = sungLyricTextWithin(project.lyricCues, updated.startSec, updated.endSec);
  }
  assertMusicVideoMediaSelections({ ...project, scenes: [updated], visualSpec: null });
  const nextScenes = scenes.slice();
  nextScenes[idx] = updated;
  const next = retimed ? anchorShotsToSungLyrics(touch(project, { scenes: nextScenes }), [sceneId]) : touch(project, { scenes: nextScenes });
  // Retiming or rewording a shot, or picking another take, keeps the storyboard approval it was judged on.
  const shotEdit = Object.keys(data).every((key) => SCENE_SHOT_EDIT_FIELDS.includes(key));
  return { project: shotEdit ? carryStoryboardApproval(project, next, 'Edited a shot') : next, updated };
}

/** Remove a scene and re-sequence the remaining scenes' `order`. Returns the next record. */
export function removeScene(project, sceneId) {
  const scenes = project.scenes || [];
  if (!scenes.some((s) => s.sceneId === sceneId)) {
    throw new ServerError('Scene not found', { status: 404, code: 'NOT_FOUND' });
  }
  const nextScenes = scenes
    .filter((s) => s.sceneId !== sceneId)
    .map((s, i) => ({ ...s, order: i }));
  const extra = { scenes: nextScenes };
  // The removed shot's storyboard row goes with it, so the board has no row bound to a missing scene.
  const draft = project.productionReview?.draft;
  if (Array.isArray(draft?.storyboard) && draft.storyboardSource !== 'document') {
    extra.productionReview = { ...project.productionReview,
      draft: { ...draft, storyboard: draft.storyboard.filter((shot) => shot?.sceneId !== sceneId) } };
  }
  // Cutting a shot adds nothing the approval did not cover, so a current storyboard approval stays.
  return carryStoryboardApproval(project, touch(project, extra), 'Cut a shot');
}

// What a board position owns rather than the shot placed in it: the span of
// the song, its section, and the lyric sung there. A reorder leaves these on
// their positions and moves only the shot (prompts, frames, clips, takes,
// direction, camera), so swapping two shots keeps the song timing intact.
const SCENE_SLOT_FIELDS = ['startSec', 'endSec', 'beatAligned', 'sectionIndex', 'sectionLabel', 'lyricText', 'lyricRole', 'lyricSize'];
const DRAFT_SHOT_SLOT_FIELDS = ['startSec', 'endSec', 'lyricCueIds'];
const pickSlot = (record, fields) => Object.fromEntries(fields.filter((k) => k in record).map((k) => [k, record[k]]));
const withoutSlot = (record, fields) => Object.fromEntries(Object.entries(record).filter(([k]) => !fields.includes(k)));

/**
 * Reorder the board to the given sceneId order. `orderedIds` must be exactly the
 * project's current scene ids (a permutation) — a missing/extra/unknown id is a
 * 400 so a stale client can't silently drop scenes. Each board position keeps
 * its song slot (SCENE_SLOT_FIELDS) and the shots move between the slots; the
 * lyric-timed storyboard draft's shots follow their scenes into the new slots,
 * and a revised song's per-shot lyric verdicts stay with their slots.
 * The storyboard and proof approvals hash scene timing and content, so they go
 * stale on their own. Returns the next record.
 */
export function reorderScenes(project, orderedIds) {
  const scenes = project.scenes || [];
  const byId = new Map(scenes.map((s) => [s.sceneId, s]));
  if (orderedIds.length !== scenes.length || !orderedIds.every((id) => byId.has(id)) || new Set(orderedIds).size !== orderedIds.length) {
    throw new ServerError('Reorder must list each existing scene id exactly once', { status: 400, code: 'VALIDATION_ERROR' });
  }
  // The scene whose slot each moved scene now fills.
  const slotOwner = new Map(orderedIds.map((id, i) => [id, scenes[i]]));
  const nextScenes = orderedIds.map((id, i) => ({
    ...withoutSlot(byId.get(id), SCENE_SLOT_FIELDS), ...pickSlot(scenes[i], SCENE_SLOT_FIELDS), order: i,
  }));
  const extra = { scenes: nextScenes };
  // A revised song's verdicts are about the lyric in a slot, so they stay with it.
  const sceneReview = project.songRevision?.sceneReview;
  if (sceneReview && typeof sceneReview === 'object') {
    const holder = new Map(scenes.map((s, i) => [s.sceneId, orderedIds[i]]));
    extra.songRevision = { ...project.songRevision,
      sceneReview: Object.fromEntries(Object.entries(sceneReview).map(([id, verdict]) => [holder.get(id) ?? id, verdict])) };
  }
  const draft = project.productionReview?.draft;
  if (!Array.isArray(draft?.storyboard) || draft.storyboardSource === 'document') return touch(project, extra);
  const draftShots = new Map(draft.storyboard.filter((shot) => shot?.sceneId).map((shot) => [shot.sceneId, shot]));
  const storyboard = draft.storyboard.map((shot) => {
    const owner = shot?.sceneId && slotOwner.get(shot.sceneId);
    if (!owner || owner.sceneId === shot.sceneId) return shot;
    // The owner's own draft shot carries that slot's lyric anchors; without one,
    // take the slot's timing and let the storyboard check ask for anchors.
    const slot = draftShots.get(owner.sceneId);
    return slot ? { ...shot, ...pickSlot(slot, DRAFT_SHOT_SLOT_FIELDS) }
      : { ...shot, startSec: owner.startSec ?? shot.startSec, endSec: owner.endSec ?? shot.endSec, lyricCueIds: [] };
  });
  return touch(project, { ...extra, productionReview: { ...project.productionReview, draft: { ...draft, storyboard } } });
}

// Label suffix budget: the scene label schema caps at 120 characters.
const SCENE_LABEL_MAX = 120;

/**
 * Split a shot longer than its backend can render in one take (#8977) into
 * contiguous scenes on musical boundaries (lib/musicVideoShotTiming.js
 * `planShotSplit`): a performance shot at its lip-sync provider's audio
 * window, a Grok cutaway at the longest Grok clip. `backend` is the lane the
 * director will render with ('' / null = the project's pinned backend).
 *
 * The original scene keeps its id and takes and becomes the first piece (a
 * performance's lip-synced clip selection is cleared — see below). Each later
 * piece is a new scene placed right after it, carrying the shot's direction
 * and the selected reference frame (as a take, so the frame is ready to
 * animate) but no clip — the old clip was generated for the whole span. Each
 * piece's `lyricText` is the timed lines sung inside it. `atSec` instead cuts
 * the shot in two at that song time, whatever the backend. Returns `{ project, scenes }` (all pieces, in
 * order); throws 400 when the shot is untimed, already fits one take, or `atSec` falls outside it.
 */
export function splitScene(project, sceneId, { backend = null, atSec = null } = {}) {
  const scenes = project.scenes || [];
  const idx = scenes.findIndex((s) => s.sceneId === sceneId);
  if (idx < 0) throw new ServerError('Scene not found', { status: 404, code: 'NOT_FOUND' });
  const scene = scenes[idx];
  const plan = atSec != null ? splitAtTime(scene, atSec) : planShotSplit({
    startSec: scene.startSec,
    endSec: scene.endSec,
    maxSec: splitLimitOrThrow(project, scene, backend),
    lyricCues: project.lyricCues,
    phrases: project.phrases,
    beats: project.audioAnalysis?.beats,
  });
  if (!plan.ok) throw new ServerError(plan.message, { status: 400, code: plan.code });

  const now = new Date().toISOString();
  const count = plan.pieces.length;
  // Re-splitting a piece numbers it afresh rather than stacking suffixes.
  const baseLabel = (scene.label || scene.sectionLabel || `Scene ${idx + 1}`).replace(/ · \d+\/\d+$/, '');
  const pieceLabel = (i) => {
    const suffix = ` · ${i + 1}/${count}`;
    return `${baseLabel.slice(0, SCENE_LABEL_MAX - suffix.length)}${suffix}`;
  };
  const hasTimedCues = (project.lyricCues || []).some((cue) => typeof cue?.startSec === 'number');
  const pieceLyrics = (piece) => (hasTimedCues ? sungLyricTextWithin(project.lyricCues, piece.startSec, piece.endSec) : scene.lyricText ?? null);

  const pieces = plan.pieces.map((piece, i) => {
    const timing = { label: pieceLabel(i), startSec: piece.startSec, endSec: piece.endSec, lyricText: pieceLyrics(piece) };
    if (i === 0) {
      const takes = ensureSceneTakes(scene, now);
      // A lip-synced take was generated for the old interval and the render
      // refuses it as re-timed, so the selection is cleared (the take stays a
      // candidate) and "Generate missing" fills it. A cutaway clip still starts
      // where the first piece does, so it stays selected and is trimmed.
      return isPerformanceScene(scene)
        ? { ...scene, ...timing, takes, videoHistoryId: null }
        : { ...scene, ...timing, takes };
    }
    const fresh = buildScene({
      ...parseSceneOrThrow(musicVideoSceneCreateSchema, {
        sectionLabel: scene.sectionLabel ?? null,
        prompt: scene.prompt ?? '',
        framePrompt: scene.framePrompt ?? null,
        beatAligned: scene.beatAligned ?? false,
        loop: scene.loop ?? false,
        sectionIndex: scene.sectionIndex ?? null,
        visualIntent: scene.visualIntent ?? null,
        visualLayer: scene.visualLayer ?? 'footage',
        ...(scene.stillMove ? { stillMove: scene.stillMove } : {}),
        shotMode: scene.shotMode ?? 'cutaway',
        performanceSpeaker: scene.performanceSpeaker ?? null,
        performanceStyle: scene.performanceStyle ?? null,
        ...(scene.camera ? { camera: scene.camera } : {}),
        ...(scene.panelId ? { panelId: scene.panelId, panelRev: scene.panelRev ?? null, panelArt: scene.panelArt ?? null } : {}),
        ...timing,
      }),
    }, { order: 0 });
    const seeded = {
      ...fresh,
      ...(scene.direction ? { direction: structuredClone(scene.direction) } : {}),
      referenceImageId: scene.referenceImageId ?? null,
    };
    return { ...seeded, takes: ensureSceneTakes(seeded, now, 'manual') };
  });

  const nextScenes = [...scenes.slice(0, idx), ...pieces, ...scenes.slice(idx + 1)]
    .map((s, i) => ({ ...s, order: i }));
  const extra = { scenes: nextScenes };
  // The shot's storyboard row follows its first piece; each later piece gets a
  // copy of the row's direction, all anchored to the lines sung over them.
  const draft = project.productionReview?.draft;
  const row = Array.isArray(draft?.storyboard) && draft.storyboardSource !== 'document'
    ? draft.storyboard.find((shot) => shot?.sceneId === sceneId) : null;
  if (row) {
    const anchored = (piece) => cuesSungWithin(project.lyricCues, piece.startSec, piece.endSec).map((cue) => cue.id);
    const span = (piece) => ('startSec' in row || 'endSec' in row ? { startSec: piece.startSec, endSec: piece.endSec } : {});
    const rows = pieces.map((piece, i) => ({ ...row, ...(i ? { id: `shot-${piece.sceneId}`, sceneId: piece.sceneId } : {}),
      ...span(piece), lyricCueIds: anchored(piece) }));
    const storyboard = draft.storyboard.flatMap((shot) => (shot === row ? rows : [shot]));
    extra.productionReview = { ...project.productionReview, draft: { ...draft, storyboard } };
  }
  const next = carryStoryboardApproval(project, touch(project, extra), 'Split a shot');
  return { project: next, scenes: nextScenes.slice(idx, idx + count) };
}

const timedSec = (v) => typeof v === 'number' && Number.isFinite(v);

function splitLimitOrThrow(project, scene, backend) {
  const maxSec = shotSplitLimit(scene, backend || project.videoSettings?.backend || null, project.videoSettings);
  if (maxSec == null) {
    throw new ServerError('This backend renders the shot at any length — there is nothing to split.', { status: 400, code: 'MUSIC_VIDEO_SPLIT_NOT_NEEDED' });
  }
  return maxSec;
}

/** Shortest piece a split at a chosen time may leave. */
const MIN_SPLIT_PIECE_SEC = 0.1;

/** Two pieces cut at `atSec`, which must fall inside the timed shot. */
function splitAtTime(scene, atSec) {
  const { startSec, endSec } = scene;
  if (!timedSec(startSec) || !timedSec(endSec)) {
    return { ok: false, code: 'MUSIC_VIDEO_SPLIT_UNTIMED', message: 'Give this shot a start and end time before splitting it.' };
  }
  if (atSec < startSec + MIN_SPLIT_PIECE_SEC || atSec > endSec - MIN_SPLIT_PIECE_SEC) {
    return { ok: false, code: 'MUSIC_VIDEO_SPLIT_OUT_OF_RANGE', message: `Split inside the shot, between ${startSec + MIN_SPLIT_PIECE_SEC}s and ${endSec - MIN_SPLIT_PIECE_SEC}s.` };
  }
  return { ok: true, pieces: [{ startSec, endSec: atSec }, { startSec: atSec, endSec }] };
}

/**
 * Join a scene with the one after it — the inverse of `splitScene`. The first
 * scene keeps its id, takes and selections and stretches to the next scene's
 * end; the lyric lines are joined; the next scene is removed and `order`
 * renumbered; a board-sourced storyboard draft merges the matching shots.
 * A selected clip survives (the director's cut was one continuous clip), but a
 * performance's lip-synced clip was generated for the old interval, so its
 * selection is cleared as in a split. When the second scene selects the same
 * video asset as the first, its take for that asset is kept too. Refuses when
 * the joined span exceeds the backend's longest take (`shotSplitLimit`) and for
 * a document composition, whose shot order lives in the shot manifest.
 * Returns `{ project, scene }`.
 */
export function mergeNextScene(project, sceneId, { backend = null } = {}) {
  const scenes = project.scenes || [];
  const idx = scenes.findIndex((s) => s.sceneId === sceneId);
  if (idx < 0) throw new ServerError('Scene not found', { status: 404, code: 'NOT_FOUND' });
  if (!scenes[idx + 1]) throw new ServerError('This is the last scene — there is no next scene to merge.', { status: 400, code: 'MUSIC_VIDEO_MERGE_NO_NEXT' });
  return joinScenes(project, idx, { keep: 'first', backend });
}

/**
 * Merge a scene over the one before it, the mirror of `mergeNextScene`: this
 * scene keeps its id, takes and selections and starts where the previous scene
 * started, and the previous scene is removed. Same refusals and clip rules.
 * Returns `{ project, scene }`.
 */
export function mergePreviousScene(project, sceneId, { backend = null } = {}) {
  const scenes = project.scenes || [];
  const idx = scenes.findIndex((s) => s.sceneId === sceneId);
  if (idx < 0) throw new ServerError('Scene not found', { status: 404, code: 'NOT_FOUND' });
  if (idx === 0) throw new ServerError('This is the first scene — there is no previous scene to merge over.', { status: 400, code: 'MUSIC_VIDEO_MERGE_NO_PREVIOUS' });
  return joinScenes(project, idx - 1, { keep: 'second', backend });
}

/** Join scenes `idx` and `idx + 1` into one spanning both, keeping the `first` or `second` scene's id and media. */
function joinScenes(project, idx, { keep, backend }) {
  const scenes = project.scenes || [];
  const [first, second] = [scenes[idx], scenes[idx + 1]];
  const [kept, removed] = keep === 'first' ? [first, second] : [second, first];
  if (project.composition?.mode === 'document') {
    throw new ServerError("This video's shot order comes from its composition document — merge the shots in the shot manifest instead.", { status: 400, code: 'MUSIC_VIDEO_MERGE_DOCUMENT' });
  }
  const lane = backend || project.videoSettings?.backend || null;
  const startSec = first.startSec;
  const endSec = timedSec(second.endSec) ? second.endSec : first.endSec;
  if (timedSec(startSec) && timedSec(endSec) && (endSec <= startSec || (timedSec(first.endSec) && endSec < first.endSec))) {
    throw new ServerError('The next scene ends before this one does — put the scenes in song order before merging them.', { status: 400, code: 'MUSIC_VIDEO_MERGE_OUT_OF_ORDER' });
  }
  const maxSec = shotSplitLimit(kept, lane, project.videoSettings);
  if (maxSec != null) {
    if (!timedSec(startSec) || !timedSec(endSec)) {
      throw new ServerError('Both scenes need a start and end time before they can be merged on this backend.', { status: 400, code: 'MUSIC_VIDEO_MERGE_UNTIMED' });
    }
    if (endSec - startSec > maxSec + 1e-6) {
      throw new ServerError(`The merged shot would run ${(endSec - startSec).toFixed(2)}s, longer than this backend renders in one take (${maxSec.toFixed(2)}s).`, { status: 400, code: 'MUSIC_VIDEO_MERGE_TOO_LONG' });
    }
  }

  const now = new Date().toISOString();
  let takes = ensureSceneTakes(kept, now);
  const sharedClip = kept.videoHistoryId && kept.videoHistoryId === removed.videoHistoryId;
  if (sharedClip && !takes.some((t) => t.kind === 'video' && t.assetId === kept.videoHistoryId)) {
    const shared = ensureSceneTakes(removed, now).find((t) => t.kind === 'video' && t.assetId === kept.videoHistoryId);
    if (shared) takes = [...takes, shared];
  }
  const lyricText = [first.lyricText, second.lyricText].filter((t) => typeof t === 'string' && t.trim()).join(' / ').slice(0, 2000) || null;
  const merged = {
    ...kept, startSec, endSec, lyricText, takes,
    ...(isPerformanceScene(kept) ? { videoHistoryId: null } : {}),
  };

  const nextScenes = [...scenes.slice(0, idx), merged, ...scenes.slice(idx + 2)].map((s, i) => ({ ...s, order: i }));
  const extra = { scenes: nextScenes };
  const sceneReview = project.songRevision?.sceneReview;
  if (sceneReview && typeof sceneReview === 'object' && removed.sceneId in sceneReview) {
    extra.songRevision = { ...project.songRevision,
      sceneReview: Object.fromEntries(Object.entries(sceneReview).filter(([id]) => id !== removed.sceneId)) };
  }
  const draft = project.productionReview?.draft;
  if (Array.isArray(draft?.storyboard) && draft.storyboardSource !== 'document') {
    const rowOf = (scene) => draft.storyboard.find((shot) => shot?.sceneId === scene.sceneId);
    const [firstRow, secondRow] = [rowOf(first), rowOf(second)];
    const gone = rowOf(removed);
    const storyboard = draft.storyboard
      .filter((shot) => shot?.sceneId !== removed.sceneId)
      .map((shot) => {
        if (shot?.sceneId !== kept.sceneId) return shot;
        const cueIds = [...new Set([...(firstRow?.lyricCueIds || []), ...(secondRow?.lyricCueIds || [])])];
        return { ...shot,
          ...(keep === 'second' ? { startSec: timedSec(gone?.startSec) ? gone.startSec : startSec ?? shot.startSec } : {}),
          endSec: timedSec(secondRow?.endSec) ? secondRow.endSec : endSec ?? shot.endSec, lyricCueIds: cueIds };
      });
    extra.productionReview = { ...project.productionReview, draft: { ...draft, storyboard } };
  }
  // Joining two shots keeps their prompts and lyrics, so a current storyboard approval stays.
  return { project: carryStoryboardApproval(project, touch(project, extra), 'Merged two shots'), scene: nextScenes[idx] };
}

// ---- peer-sync federation (#1770) -----------------------------------------
// Mirrors the Creative Director store (creativeDirector/projectsLogic.js): a
// project is a whole-record LWW kind (no item-union, no ephemeral flag), so the
// wire form is the record with normalized soft-delete fields and the merge is a
// straight `updatedAt` newest-wins decision. Both backends call through here so
// the file and PG paths can't diverge.

/**
 * Wire-safe / merge-safe projection of a peer-supplied project record. Rejects a
 * non-object or one missing an id (the receiver could never apply it), and
 * normalizes the timestamps + soft-delete pair so a legacy/hand-edited payload
 * converges byte-for-byte with a freshly-written one. Returns null when unusable.
 */
/**
 * LWW merge decision for one incoming peer record against the local copy.
 * Returns `{ next, inserted, remoteWins, changed }`:
 *   - malformed remote → `{ next: null, ... }` (caller drops it)
 *   - no local copy → insert the remote
 *   - otherwise newest-`updatedAt`-wins; `changed` is false when the winner is
 *     byte-identical to local (a same-`updatedAt` re-push no-ops, no churn).
 * Tombstone-aware purely via `updatedAt`: deleteProject stamps a fresh
 * `updatedAt`, so a tombstone beats an older live copy and can't be resurrected.
 */
export function mergeProjectRecord(local, remoteRaw) {
  let remote = sanitizeProjectForSync(remoteRaw);
  if (!remote) return { next: null, inserted: false, remoteWins: false, changed: false };
  // An older peer can still send the fields that newer peers strip. Project
  // sync remains schema-v1 compatible, so apply the same projection inbound
  // before either inserting or restoring this machine's local choices.
  remote = stripMusicVideoLocalRenderPins(remote);
  if (!local) return { next: remote, inserted: true, remoteWins: true, changed: true };
  // Render pins are install-capability choices and therefore wire-local
  // (#3245). sanitizeRecordForWire omits them from peer payloads; restore this
  // machine's values before a newer remote record wholesale-replaces local.
  // Key-presence checks preserve an intentional local empty/null value instead
  // of confusing it with a missing field.
  remote = { ...remote };
  if (Object.hasOwn(local, 'imageMode')) remote.imageMode = local.imageMode;
  if (Object.hasOwn(local, 'imageModelId')) remote.imageModelId = local.imageModelId;
  // #9066: this install's production-run checkpoint survives a newer remote.
  if (Object.hasOwn(local, 'productionRuns')) remote.productionRuns = local.productionRuns;
  // Development artifacts and the Cast & Sets checkpoint are wire-local too:
  // their files and jobs exist only on this install.
  if (Object.hasOwn(local, 'devArtifacts')) remote.devArtifacts = local.devArtifacts;
  delete remote.productionReview;
  if (Object.hasOwn(local, 'productionReview')) remote.productionReview = local.productionReview;
  if (Object.hasOwn(local, 'castAndSets')) remote.castAndSets = local.castAndSets;
  if (Object.hasOwn(local, 'autonomousRun')) remote.autonomousRun = local.autonomousRun;
  if (Object.hasOwn(local, 'renderError')) remote.renderError = local.renderError;
  // Song revisions hold this install's paid-generation recovery checkpoint,
  // candidate files and provenance; an unrelated peer edit must not erase them.
  if (Object.hasOwn(local, 'songRevision')) remote.songRevision = local.songRevision;
  if (Object.hasOwn(local, 'songRevisionHistory')) remote.songRevisionHistory = local.songRevisionHistory;
  // The composition document's files live only on this install as well
  // (compositionDocument.js), so its pointer survives a newer remote body.
  if (local.composition?.document || local.composition?.documentDraft) {
    const sharedComposition = remote.composition && typeof remote.composition === 'object' && !Array.isArray(remote.composition)
      ? remote.composition : {};
    remote.composition = {
      ...sharedComposition,
      ...(local.composition.document ? { document: local.composition.document } : {}),
      ...(local.composition.documentDraft ? { documentDraft: local.composition.documentDraft } : {}),
    };
  }
  if (local.videoSettings && typeof local.videoSettings === 'object'
    && !Array.isArray(local.videoSettings) && ['backend', 'renderPool'].some((key) => Object.hasOwn(local.videoSettings, key))) {
    const remoteVideoSettings = remote.videoSettings && typeof remote.videoSettings === 'object'
      && !Array.isArray(remote.videoSettings) ? remote.videoSettings : {};
    remote.videoSettings = { ...remoteVideoSettings,
      ...Object.fromEntries(['backend', 'renderPool'].filter((key) => Object.hasOwn(local.videoSettings, key)).map((key) => [key, local.videoSettings[key]])) };
  }
  const remoteWins = compareNewerWins(remote.updatedAt, local.updatedAt);
  const next = remoteWins ? remote : local;
  const changed = JSON.stringify(next) !== JSON.stringify(local);
  return { next, inserted: false, remoteWins, changed };
}