fix(sfx): no enviar letras residuales de Speech/Music en generation.sfx

[cursor]

Resumen ejecutivo

Qué cambia

Studio SFX ya no admite las letras residuales de Speech o Music cuando la caja de SFX está vacía. Generate y Wizard start_generation fallan cerrados en vez de generar el guión anterior como efecto de sonido.

Para qué sirve

Speech, Music y SFX comparten el mismo mapa de params. El textarea de SFX escribe solo MMAudio_prompt. Al cambiar de pestaña, las letras quedaban en prompt. startGeneration hacía MMAudio_prompt ?? prompt y el comando cerrado generation.sfx aceptaba ese residuo como descripción.

Impacto para el usuario

Tras escribir letra en Speech o Music y pasar a SFX con la caja vacía, Generate pide una descripción literal en vez de encolar el texto anterior. Un MCP que envíe solo prompt sigue admitiéndose.

Riesgo

• Bajo
• Medio
• Alto

Estado

• En desarrollo
• Listo para revisión
• Bloqueado por CI o revisión
• Requiere migración o acción manual

Summary

SfxControls reads/writes only MMAudio_prompt. setAudioSubMode does not stash per-tab text, so Speech lyrics or Music lyrics remain in params.prompt. startGeneration did params.prompt = params.MMAudio_prompt ?? params.prompt. When the SFX box was never filled, MMAudio_prompt is undefined and the leftover script became the closed-command sound description.

Concrete trigger:

1. Studio → Audio → Music (or Speech), write lyrics, duration ≤ 20 s.
2. Switch to SFX. The SFX textarea is empty; the slider may still show a valid short duration.
3. Click Generate.
4. Before this fix, generation.sfx admitted the leftover lyrics and queued MMAudio.

neutralizeStudioSfxFormResidue runs on the Studio form snapshot before the closed builder:

• if MMAudio_prompt is blank, drop leftover prompt
• if MMAudio_prompt is authored, sync prompt to it so aliases match

startGeneration no longer falls back to leftover prompt.

The closed MCP/Wizard envelope path is unchanged: a prompt-only direct command still admits.

Overview

1. User writes Speech or Music text in the shared Studio form.
2. Switches to Audio → SFX without typing in the SFX box.
3. Submission now strips leftover prompt, then builds generation.sfx.
4. Empty SFX box fails closed (“A literal sound description is required”).
5. Authored MMAudio_prompt and MCP prompt-only envelopes still work.

Detailed changes

Backend

No server contract change. The native SFX schema already required a non-blank prompt or MMAudio_prompt.

UI and Wizard

• sfxGenerationSpec.ts: export neutralizeStudioSfxFormResidue.
• sfxCommandSubmission.ts: run it after form projection.
• useStore.ts: SFX branch copies only MMAudio_prompt into prompt.

Data, provenance and compatibility

No sidecar format change. Direct MCP envelopes that supply only prompt still validate.

Files and ownership

• ui/src/features/studio/sfxGenerationSpec.ts — residue helper
• ui/src/features/studio/sfxCommandSubmission.ts — call site
• ui/src/stores/useStore.ts — Generate snapshot
• ui/tests/sfxGenerationCommands.test.ts — leftover vs authored vs MCP prompt-only
• ui/tests/studioSfxCommandPresentation.test.tsx — submission rejects leftover Speech
• Left untouched: setAudioSubMode text stash, SFX duration display clamp (Math.min(duration, 20) without writing back)

Validation

• Date (UTC): 2026-09-09

• Base SHA: 94ab006 (feat/shared-tool-commands)

• Head SHA: 2a848df

• Validation scope: focused

• python scripts/verify_clean_repo.py

• python -m compileall -q app/services app/launch.py scripts

• Focused Python tests: N/A (UI-only)

• cd ui && npm run i18n:check

• UI tests: npx tsx --tsconfig tsconfig.app.json --import ./tests/setupI18n.ts --test tests/sfxGenerationCommands.test.ts tests/studioSfxCommandPresentation.test.tsx — 11 passed

• UI tests: npx tsx --tsconfig tsconfig.app.json --import ./tests/setupI18n.ts --test tests/studioSfxAction.test.mjs — 17 passed

• cd ui && npm run lint -- --max-warnings=0

• cd ui && npm run build

• git diff --check

• E2E/smoke checks: N/A (no live generation; provider-free command tests only)

Code quality

• Score: pending CI
• Complexity trend: pending CI
• Production LOC trend: pending CI
• Regression versus main: pending CI
• Ratchet: pending CI

CI and review

• CI of this HEAD: pending

• Independent agent review of this HEAD: pending

• Human merge click (operational, not code review): pending

• Reviewed at current HEAD

• Earlier review; HEAD has changed since (stale)

• Pending

• Unavailable

Coste de la tarea

• Tests simulados: 0 tokens externos
• Tests reales: N/A
• Llamadas LLM externas: 0
• Tokens de prompt: N/A
• Tokens de respuesta: N/A
• Tokens totales: N/A
• Generaciones de imágenes/audio/vídeo: 0
• Tiempo transcurrido: N/A
• Proveedores/modelos: N/A

Notes and limitations

Does not stash lyrics/caption across Speech↔Music↔SFX tabs. Does not clamp durationSeconds when the SFX slider displays Math.min(duration, 20) while the store still holds a Speech/Music value above 20 s — that path already fail-closes on the text-only 20 s cap.

Follow-up work

• Audio sub-tab stash for lyrics/caption/SFX text (data loss when switching tabs).
• Write the displayed SFX duration back into the store so a leftover 120 s Music value cannot disagree with the 20 s slider.
• Speech residue in Music remains in open PR test(studio): proteger referencias Music con voces Speech guardadas #283.

Checklist

• The executive summary is understandable without reading the code.
• The detailed Summary/Overview has not been removed or shortened.
• Tests and their actual results are recorded.
• Generated assets, secrets and local-only files are not committed.
• Required CI and Cursor/Bugbot review are complete, or the PR is clearly marked as waiting for them.