Files
karaoke-gen/docs/archive/2026-03-08-step2-song-suggestions.plan.md
Andrew Beveridge ☄️andClaude Opus 4.6 93823b8a20 Move song suggestions to Step 2 with fuzzy typo correction (#512)
@coderabbitai ignore

## Summary

- **Simplified Step 1 (Song Info)**: Removed autocomplete — plain text
inputs for artist/title so users aren't confused by autocomplete
behavior
- **Step 2 song suggestions**: Catalog lookup + community version check
fire in parallel with audio search. Results appear as a "Song found in
our database" panel (exact match) or correction suggestion panel while
the user waits
- **Fuzzy "Did you mean?" correction**: When audio search returns poor
results (Tier 3) and catalog has no exact title match, fetches the
artist's discography and fuzzy-matches against the user's title. Shows
amber banner with one-click correction + expandable alternatives list.
Title-based fallback with artist tiebreaker handles garbled artist
fields
- **Visibility step reworked**: Action buttons at top for one-click
select+continue, "change later" note, removed Recommended badge
- **Minor UI polish**: Warning icon on community banner, "Recommended
Audio" heading, YouTube icon on community links, filename above release
in pick card

## Test plan

- [x] 70 new tests added (fuzzy matching, SongInfoStep, AudioSourceStep,
VisibilityStep, CommunityVersionBanner)
- [x] All 677 tests pass
- [x] Manual testing via Playwright: "Fox Stevenson / ruises" typo → Did
you mean Bruises; "fox stevenson bruises / bruises" garbled artist →
correct Fox Stevenson suggestion
- [x] CodeRabbit review completed, issues fixed

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

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-08 04:40:35 -04:00

4.6 KiB

Plan: Move Song DB Suggestions from Step 1 to Step 2

Created: 2026-03-08 Branch: feat/sess-20260308-0139-step2-song-suggestions Status: Implemented

Overview

The autocomplete on Step 1's title field is confusing — users don't know why they should wait for it or select a suggestion. Instead, we'll remove autocomplete from Step 1 (making it a simple text entry) and show song DB suggestions in Step 2 while the audio search is loading. This uses the ~15-30s wait time productively and presents suggestions with clear context about what they are and why.

Requirements

  • Remove AutocompleteInput from Step 1 title field → plain <Input>
  • Keep community version check in Step 1 (non-blocking, useful)
  • Fire api.searchCatalogTracks() in parallel with api.searchStandalone() on Step 2 mount
  • Show catalog results in Step 2 as a "song name correction" panel
  • Clicking a suggestion updates artist/title (the search artist/title used for job creation)
  • Panel is dismissible, doesn't appear if no results
  • Catalog search failure is silent (doesn't affect audio search)
  • Works well on mobile

Technical Approach

No new API endpoints needed — we already have api.searchCatalogTracks().

Data flow change: In Step 2, AudioSourceStep gets two new props:

  • onArtistTitleCorrection(artist: string, title: string) — called when user picks a suggestion
  • The parent (GuidedJobFlow) updates artist/title state, which re-renders the "Searching for X - Y" header

Key decision: When the user corrects artist/title via catalog suggestion, this updates the search artist/title (used in createJobFromSearch). It does NOT restart the audio search — that would be confusing and waste time. The audio search already happened with the original terms.

Implementation Steps

Step 1: Simplify SongInfoStep (remove autocomplete)

  1. Replace AutocompleteInput with plain <Input> for the title field
  2. Remove fetchTrackSuggestions callback and AutocompleteInput import
  3. Keep all other functionality (community check, tips, form validation)

Step 2: Add catalog search to AudioSourceStep

  1. Add onArtistTitleCorrection prop to AudioSourceStepProps
  2. Add state: catalogResults, catalogLoading, catalogDismissed
  3. Fire api.searchCatalogTracks(title, artist, 5) in parallel with doSearch() in the mount effect
  4. Build SongSuggestionPanel inline component showing results

Step 3: Wire up GuidedJobFlow

  1. Add handler in GuidedJobFlow that updates artist/title when catalog suggestion selected
  2. Pass handler to AudioSourceStep as onArtistTitleCorrection

Step 4: Testing

  1. Run existing E2E tests to verify no regressions
  2. Manual visual check in dev server

Files to Create/Modify

File Action Description
frontend/components/job/steps/SongInfoStep.tsx Modify Remove AutocompleteInput, use plain Input for title
frontend/components/job/steps/AudioSourceStep.tsx Modify Add parallel catalog search + suggestion panel
frontend/components/job/GuidedJobFlow.tsx Modify Add artist/title correction handler, pass to Step 2

SongSuggestionPanel Design

┌─────────────────────────────────────────────┐
│ 🔍 Found matching songs                     │
│ Click to use the official formatting:        │
│                                              │
│  ┌─ Fox Stevenson - Don't Care Crown ──── ┐ │
│  └──────────────────────────────────────── ┘ │
│  ┌─ Fox Stevenson - Don't Care Crown... ─ ┐ │
│  └──────────────────────────────────────── ┘ │
│                                    Dismiss ↗ │
└─────────────────────────────────────────────┘
  • Appears between the "Searching for X - Y" header and the loading spinner
  • Uses existing design language (card with border, muted colors)
  • Each result is a clickable row showing Artist - Track with a subtle "Use" button
  • When selected: row highlights briefly, artist/title update, panel auto-dismisses
  • "Dismiss" link at bottom to hide permanently
  • If already matches exactly, skip showing that result

Rollback Plan

Revert the branch. No backend changes, no data migrations.