Files
karaoke-gen/frontend/hooks/useAutoCorrect.ts
T
Andrew Beveridge ☄️andClaude Opus 5.5 f4f0f6af77 feat(review): only show the review button once the job is fully prepared (v0.298.0) (#1273)
## Summary

The review button now appears only once a job is fully prepared: stems
separated, auto-approval re-scored with them, AI lyric corrections
generated and applied on the server, and review audio + waveforms
cached. The browser no longer applies AI corrections by itself, so there
is one code path.

Prompted by job ae995697 (a Made For You order): the review button
showed at 18:29, but the stems, backing verdict and vocal waveform only
existed from 18:32, and the server pre-apply had aborted on a
duplicate-word check, leaving the browser to apply corrections on load.

## Changes

- **Hold every job until stems land**
(`review_gate.route_after_scoring`). Before, only jobs whose lyrics
would auto-ship were held, so Made For You and lyrics-gated jobs opened
review early. Same kill switch (`AUTO_APPROVAL_AUDIO_HOLD_ENABLED`) and
20-minute backstop.
- **Generate AI suggestions on the API service before parking.** The
hold is released inside the audio-separation job, which has no LLM
credentials, so that job only applies an existing cache.
- **`enter_human_review` prepares everything before AWAITING_REVIEW**:
pre-apply (generating on a cache miss), then
`review_assets.prepare_review_assets` (OGG transcodes, backing waveform,
vocal peak envelope), then the transition.
- **Non-strict pre-apply for human review**
(`build_applied_segments(strict=False)`): what "Accept All" produces.
Stale/duplicate signals are recorded as `warnings`. The auto-ship path
stays strict.
- **Removed the browser's on-load auto-run/auto-apply** from
`useAutoCorrect`.
- **Job card shows "[5/10] Preparing review"** while held (new summary
field + 33 locales).
- Docs: ARCHITECTURE review-gate step,
`docs/archive/2026-11-19-review-ready-gate.md`.

Trade-off: Made For You and lyrics-gated jobs reach review (and send the
review-ready notification) ~3 minutes later.

## Testing

- Backend unit suite: 7294 passed. Locally failing: 8
emulator-integration tests (something unrelated listens on :8080 so they
don't skip; CI runs them against real emulators) and 1 locale test that
tripped on a gitignored translation snapshot (passes once removed).
- New/updated tests: review gate (review-verdict jobs held, kill switch,
prepare-before-transition order, suggestions generated before parking,
no double wait, missing job), non-strict apply, duplicate-word pre-apply
(ae995697 case), review_assets.
- Frontend Jest: 1834 passed; no type errors in touched files.
- Local CodeRabbit: 2 minor findings fixed, re-review clean.

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_012RYLVVdAxGitbw1FhYP4e4

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 16:12:58 -05:00

379 lines
13 KiB
TypeScript

'use client'
/**
* State machine for the opt-in AI auto-correct suggestions feature.
*
* Nothing runs unless the reviewer explicitly triggers it; suggestions are a
* pending layer that never mutates the working data until individually (or
* bulk) accepted. Every accept/reject/undo lands in the edit log so we can
* measure real-world accept rates per category over time.
*/
import { useCallback, useEffect, useRef, useState } from 'react'
import {
AiSuggestion,
AutoCorrectApiError,
AutoCorrectSettings,
DEFAULT_AUTO_CORRECT_SETTINGS,
fetchAutoCorrectSuggestions,
} from '@/lib/api/autoCorrect'
import {
applySuggestion,
revertSuggestion,
isSuggestionStale,
fromServerUndoInfo,
SuggestionUndoInfo,
ServerSuggestionUndoInfo,
} from '@/lib/lyrics-review/utils/autoCorrectApply'
import {
getConflictSiblings,
pickAcceptAllWinners,
} from '@/lib/lyrics-review/utils/autoCorrectConflicts'
import { addEditEntry } from '@/lib/lyrics-review/utils/editLog'
import type { CorrectionData, EditLog } from '@/lib/lyrics-review/types'
export type SuggestionDecision = 'pending' | 'accepted' | 'rejected' | 'stale'
export type AutoCorrectStatus = 'idle' | 'running' | 'reviewing' | 'error'
interface UseAutoCorrectArgs {
jobId?: string
data: CorrectionData
updateDataWithHistory: (newData: CorrectionData, desc?: string) => void
editLog: EditLog
getAuthToken: () => string | undefined
/** Server-side pre-apply (C2): when the backend already applied the AI
* corrections before the review-ready notification, the working `data` is the
* final state. The hook then seeds the panel in read-only "already applied"
* mode. The browser never runs or applies suggestions on load by itself:
* the backend applies them before the job reaches review
* (backend/services/auto_approval/pre_apply.py). Without this, the panel
* starts idle and the reviewer can run it by hand. */
preApplied?: {
suggestions: AiSuggestion[]
appliedIds: string[]
rejectedIds: string[]
/** Per-suggestion undo info computed server-side at apply time (see
* ``backend/services/auto_approval/apply.py``), keyed by suggestion id.
* Seeds ``undoInfos`` so pre-applied suggestions stay individually
* undoable even though the browser never applied them itself. Missing
* entries (older jobs processed before this existed) simply can't be
* undone — same as a stale suggestion. */
undoInfo?: Record<string, ServerSuggestionUndoInfo>
} | null
}
export function useAutoCorrect({
jobId,
data,
updateDataWithHistory,
editLog,
getAuthToken,
preApplied = null,
}: UseAutoCorrectArgs) {
const [status, setStatus] = useState<AutoCorrectStatus>('idle')
const [suggestions, setSuggestions] = useState<AiSuggestion[]>([])
const [decisions, setDecisions] = useState<Record<string, SuggestionDecision>>({})
const [model, setModel] = useState<string>('')
const [cached, setCached] = useState(false)
const [error, setError] = useState<string | null>(null)
const undoInfos = useRef<Record<string, SuggestionUndoInfo>>({})
const abortRef = useRef<AbortController | null>(null)
const hasReferences = Object.keys(data.reference_lyrics ?? {}).length > 0
// Abort any in-flight request on unmount so no state updates land after.
useEffect(() => {
return () => {
abortRef.current?.abort()
}
}, [])
const run = useCallback(
async (settings: AutoCorrectSettings = DEFAULT_AUTO_CORRECT_SETTINGS) => {
if (!jobId) return
setStatus('running')
setError(null)
abortRef.current?.abort()
const ac = new AbortController()
abortRef.current = ac
try {
const response = await fetchAutoCorrectSuggestions(
jobId,
{
segments: data.corrected_segments,
referenceLyrics: data.reference_lyrics ?? {},
artist: data.metadata?.artist,
title: data.metadata?.title,
settings,
},
ac.signal,
getAuthToken(),
)
setSuggestions(response.suggestions)
setDecisions(
Object.fromEntries(response.suggestions.map((s) => [s.id, 'pending'])),
)
undoInfos.current = {}
setModel(response.model)
setCached(response.cached)
setStatus('reviewing')
addEditEntry(editLog, 'ai_suggestion_run', {
details: {
model: response.model,
cached: response.cached,
suggestion_count: response.suggestions.length,
elapsed_seconds: response.elapsed_seconds,
settings: response.settings_applied as unknown as Record<string, unknown>,
},
})
} catch (err) {
if ((err as Error).name === 'AbortError') {
setStatus('idle')
return
}
const message =
err instanceof AutoCorrectApiError
? err.message
: 'Unexpected error generating suggestions'
setError(message)
setStatus('error')
}
},
[jobId, data, editLog, getAuthToken],
)
const cancel = useCallback(() => {
abortRef.current?.abort()
}, [])
// Pre-applied mode (C2): the backend already applied the corrections and the
// working `data` is the final state. Seed the panel to show what was applied
// (read-only) WITHOUT running the network call or re-applying. One-shot.
const isPreApplied = Boolean(preApplied)
const preAppliedSeededRef = useRef(false)
useEffect(() => {
if (!preApplied || preAppliedSeededRef.current) return
if (status !== 'idle') return
preAppliedSeededRef.current = true
const applied = new Set(preApplied.appliedIds)
const seeded: Record<string, SuggestionDecision> = {}
for (const s of preApplied.suggestions) {
seeded[s.id] = applied.has(s.id) ? 'accepted' : 'rejected'
}
// Seed undoInfos from the server-computed undo data so applied suggestions
// stay individually undoable even though the browser never applied them.
for (const [id, raw] of Object.entries(preApplied.undoInfo ?? {})) {
undoInfos.current[id] = fromServerUndoInfo(id, raw)
}
setSuggestions(preApplied.suggestions)
setDecisions(seeded)
setCached(true)
setStatus('reviewing')
}, [preApplied, status])
const logDecision = useCallback(
(s: AiSuggestion, op: 'ai_suggestion_accept' | 'ai_suggestion_reject' | 'ai_suggestion_undo') => {
addEditEntry(editLog, op, {
segment_id: s.segment_ids[0] ?? null,
word_ids_before: s.word_ids,
text_before: s.original_text,
text_after: s.new_text,
details: {
suggestion_id: s.id,
op: s.op,
category: s.category,
confidence: s.confidence,
reason: s.reason,
model,
models: s.models,
consensus: s.consensus,
total_models: s.total_models,
conflict_group: s.conflict_group,
},
})
},
[editLog, model],
)
const accept = useCallback(
(id: string) => {
const s = suggestions.find((x) => x.id === id)
if (!s || decisions[id] !== 'pending') return
const result = applySuggestion(data.corrected_segments, s)
if (!result) {
setDecisions((d) => ({ ...d, [id]: 'stale' }))
return
}
undoInfos.current[id] = result.undo
updateDataWithHistory(
{ ...data, corrected_segments: result.segments },
'accept AI suggestion',
)
// Accepting one variant of a conflict group rejects the others —
// they target the same words with a different outcome.
const siblingUpdates: Record<string, SuggestionDecision> = {}
for (const sibling of getConflictSiblings(suggestions, id)) {
if (decisions[sibling.id] === 'pending') {
siblingUpdates[sibling.id] = 'rejected'
logDecision(sibling, 'ai_suggestion_reject')
}
}
setDecisions((d) => ({ ...d, ...siblingUpdates, [id]: 'accepted' }))
logDecision(s, 'ai_suggestion_accept')
},
[suggestions, decisions, data, updateDataWithHistory, logDecision],
)
const reject = useCallback(
(id: string) => {
const s = suggestions.find((x) => x.id === id)
if (!s || decisions[id] !== 'pending') return
setDecisions((d) => ({ ...d, [id]: 'rejected' }))
logDecision(s, 'ai_suggestion_reject')
},
[suggestions, decisions, logDecision],
)
const undoAccept = useCallback(
(id: string): boolean => {
const s = suggestions.find((x) => x.id === id)
const undo = undoInfos.current[id]
if (!s || decisions[id] !== 'accepted' || !undo) return false
const reverted = revertSuggestion(data.corrected_segments, undo)
if (!reverted) return false
delete undoInfos.current[id]
updateDataWithHistory(
{ ...data, corrected_segments: reverted },
'undo AI suggestion',
)
setDecisions((d) => ({ ...d, [id]: 'pending' }))
logDecision(s, 'ai_suggestion_undo')
return true
},
[suggestions, decisions, data, updateDataWithHistory, logDecision],
)
const acceptAll = useCallback(
() => {
let segments = data.corrected_segments
const newDecisions: Record<string, SuggestionDecision> = { ...decisions }
// In conflict groups only the winner (highest consensus, then
// confidence) is applied; the losing variants are rejected.
const winners = new Set(
pickAcceptAllWinners(suggestions.filter((s) => newDecisions[s.id] === 'pending')),
)
let applied = 0
for (const s of suggestions) {
if (newDecisions[s.id] !== 'pending') continue
if (!winners.has(s.id)) {
newDecisions[s.id] = 'rejected'
logDecision(s, 'ai_suggestion_reject')
continue
}
const result = applySuggestion(segments, s)
if (!result) {
newDecisions[s.id] = 'stale'
continue
}
segments = result.segments
undoInfos.current[s.id] = result.undo
newDecisions[s.id] = 'accepted'
logDecision(s, 'ai_suggestion_accept')
applied += 1
}
if (applied > 0) {
updateDataWithHistory({ ...data, corrected_segments: segments }, 'accept all AI suggestions')
}
setDecisions(newDecisions)
},
[suggestions, decisions, data, updateDataWithHistory, logDecision],
)
// Revert every applied auto-correction back to the original transcription
// words (in one undo step), leaving any manual edits to other words intact.
const revertAll = useCallback(() => {
let segments = data.corrected_segments
const newDecisions: Record<string, SuggestionDecision> = { ...decisions }
let reverted = 0
// Reverse order: later applies may sit after earlier ones in a segment.
for (let i = suggestions.length - 1; i >= 0; i--) {
const s = suggestions[i]
if (decisions[s.id] !== 'accepted') continue
const undo = undoInfos.current[s.id]
if (!undo) continue
const result = revertSuggestion(segments, undo)
if (!result) continue
segments = result
delete undoInfos.current[s.id]
newDecisions[s.id] = 'pending'
logDecision(s, 'ai_suggestion_undo')
reverted += 1
}
if (reverted > 0) {
updateDataWithHistory(
{ ...data, corrected_segments: segments },
'revert all AI suggestions',
)
}
setDecisions(newDecisions)
}, [suggestions, decisions, data, updateDataWithHistory, logDecision])
const rejectAll = useCallback(() => {
const newDecisions: Record<string, SuggestionDecision> = { ...decisions }
for (const s of suggestions) {
if (newDecisions[s.id] !== 'pending') continue
newDecisions[s.id] = 'rejected'
logDecision(s, 'ai_suggestion_reject')
}
setDecisions(newDecisions)
}, [suggestions, decisions, logDecision])
const dismiss = useCallback(() => {
abortRef.current?.abort()
setStatus('idle')
setSuggestions([])
setDecisions({})
undoInfos.current = {}
setError(null)
}, [])
/** Recompute staleness for pending suggestions against the latest data. */
const isPendingAndStale = useCallback(
(s: AiSuggestion) =>
decisions[s.id] === 'pending' &&
isSuggestionStale(data.corrected_segments, s),
[decisions, data.corrected_segments],
)
/** Whether an accepted suggestion actually has undo info available — false
* for older pre-applied jobs processed before the server persisted it. */
const canUndo = useCallback((id: string) => Boolean(undoInfos.current[id]), [])
const pendingCount = suggestions.filter((s) => decisions[s.id] === 'pending').length
const acceptedCount = suggestions.filter((s) => decisions[s.id] === 'accepted').length
return {
status,
suggestions,
decisions,
model,
cached,
error,
hasReferences,
isPreApplied,
pendingCount,
acceptedCount,
run,
cancel,
accept,
reject,
undoAccept,
acceptAll,
revertAll,
rejectAll,
dismiss,
isPendingAndStale,
canUndo,
}
}
export type AutoCorrectController = ReturnType<typeof useAutoCorrect>