[Yoldark34]

First step of the Repair epic, #1080. Also covers the Repair item of #1077.

Every rule the screen applies is written out in the epic, in the "Rules (the front's business logic)" block of this step: search priority, search rules, results and their tags, picking, buttons, automatic actions and shortcuts, disabled controls, states, selection, repairing, the results step and the layout. This description sums them up.

Why

A book already in the library can point at the wrong Audible record: another edition, another volume, or the same book in another region's catalog. Rescan metadata can't fix it, because it keeps rescanning that record. This PR adds the buttons to point a book at the right record.

Find Match is affected too

Repair and Library Import's Find Match now use the same component, a book card (BookMatchCard.vue), because they do the same thing: find the Audible record a book should point at. Find Match shows the folder's book in that card, without the checkbox, and "Use this match" takes the record found. It always opens with the same search, from the folder's scan, in the configured region, whatever match the folder already has: that match only shows as Current. When the scan found an ASIN, it is in the ASIN field and searched as an ASIN, as Start Matching does ("No record for … in Audible France" when the region doesn't sell it), with the scan's title and author ready for a search without it; otherwise the scan's title and author are searched. A pick from an ASIN search carries the record's series, genres and dates (Add New's ASIN search now keeps them from the record), so the book is imported with them. Everything below about the card applies to Find Match as well.

Change

Where

• A Repair button on the book page, and "Repair Selected (n)" in the library, both orange, open the Repair dialog.

Three steps, each named in the dialog's title: "Repair Books - Matching - Step 1/3", "Repair Books - Repair process - Step 2/3", then the Organize dialog opened from it, "Repair Books - Organize - Step 3/3".

Step 1, matching: each book is a card

• ASIN, Title, Author and Region, then Search; erase buttons in the fields. Current and New under them (ASIN - Title: Subtitle - Authors - Region), with room kept for their usual lines. Once a record is picked, New shows in green the parts that change, and Current in orange the parts they replace (the same record picked again, to read its metadata anew, highlights nothing).
• The results' header line is always there: "No search request done" until a search, then Results for … in France (FR) - Request: 1.23 s (or - Cached results), or No results for … (orange when nothing was found or the search was canceled, red when it failed).
• Why there are no results is said in the middle of the empty list, once the spinner is gone: the request's error (red), "No record for … in Audible …", "Search canceled" or "Not an ASIN …" (orange). An ASIN that isn't one empties the results like a failed search. The New line only ever shows a picked record, or its default text.
• Results tags: Current (green, the book's ASIN in its region), Other region (grey, the same ASIN in another catalogue, with a tooltip), and each record's language (green when it is the preferred search language, grey otherwise or unknown).
• No layout shift: a card alone in its dialog (Find Match, Repair of one book) keeps the list's room from the start; with several books, a first search opens an empty list at least one result high, measured on an unseen result with every line a result can have, so a short answer doesn't move what is under the book; a failed or canceled search empties the results and leaves an empty list of the same height.

Searching

• Add New's search, in the chosen region only, without a language filter (Audible France also sells English editions; each result shows its language).
• A filled ASIN has priority, otherwise the title and author: Search, Enter in any field and a region change all follow that priority. Typing never searches; changing the region is the one automatic search (the happy path: the right ASIN in the wrong region).
• Answered searches are kept while the dialog is open, shared by its books: the same values again are served without a request. Search becomes Retry after every search until a field changes; Retry always asks Audible again.
• Loading and reveal: while a search runs, the previous results are greyed out under a spinner saying what they wait for, and can't be picked. Once results arrive, "Found 3 results" stays readable for 300 ms, then fades out over 200 ms; picking unlocks after it.
• One search at a time (a known limit, addressed later in [Epic] Repair books that point at the wrong Audible record #1080): every other card is locked and its results greyed out ("Waiting: a search is running on another book"). Cancel search stops a search; it times out after 30 seconds.
• Only the books it was opened for last: opened again for other books while the previous ones still load (the library keeps one dialog), it shows only the last ones and loads until they are in; closed while loading, nothing that answers later fills it.
• A book that can't be loaded doesn't block the others: books load one at a time; one that fails (deleted since it was selected, a request timing out) gets its own card in the error state, saying why ("Not found: deleted since it was selected", "Couldn't be loaded: …"), which can't be ticked and counts as skipped. Load again reads it anew, except a deleted book. When none can be loaded, the dialog says why.
• Repair asks first ("Repair 3 books?", Cancel or Repair 3), since a repair can't be undone: each book takes its new record as a whole (its details replaced, what the record lacks emptied), changes made by hand are lost, the files, folder and the book's settings stay. Cancel, or Escape, goes back to step 1 as it was. Retry doesn't ask again. If the page is left while it asks (browser Back, a redirect), the question goes with the dialog and nothing is repaired.
• Escape on a confirmation shown over the dialog answers it only (this question, or leaving the page): every open dialog heard it, so Repair Books closed too, losing the picks or step 2's results.
• A record without an ASIN (when Audible has nothing, the server adds records from another source, OpenLibrary): Find Match can pick and use it, as canary did, and Library Import adds the book from it. Repair can't: it points a book at a record a metadata provider can read again (an Audible record today), so such a result is greyed, tagged "No ASIN", with the reason, and can't be picked.
• A card alone in its dialog keeps the room its results fit in (Find Match, Repair with one book): the room left by the rest of the dialog, at least two results high (the list scrolls inside past that), measured when the card shows and when the window is resized, before any search answers, so the dialog doesn't scroll and nothing moves when results arrive. With several books, the results open under each book as before.
• One book: no Selection block: its own checkbox says it all (several books keep "n of m book(s) to repair" with Select All and Clear).

States: a bar along each card's bottom (grey ignored, green matched, orange invalid, red error, blue breathing while searching), with the legend in the footer, centred on the dialog, moved aside only as far as Cancel and Repair need, and on its own line above them (still centred) when the line is too short (the cards then take the narrow layout). The dialog's bottom bar is unseen on step 1, its room kept.

Step 2, the repair process

• Only matched books are repaired, opening on "Repair 0"; picking a record ticks the book. Repair moves to step 2 at once, which holds only the books to repair (the unticked ones stay behind) and keeps the Selection section, now for Organize.
• Each book's row keeps its height: its title, then the record it points at (the one it is to get while it waits, the one it got once repaired, its old one when the repair failed or was canceled), then where its repair is: a spinner with "Waiting to be repaired" or "Repairing…", then "Repaired in 0.5 s", "The new ASIN is saved, but the metadata rescan failed …" (orange) or "Repair failed …" (red). Show details / Hide details (same size either way) opens the Old and New records, the replaced parts in orange and the new ones in green; its tooltip gives both records on two lines without opening.
• A repaired book takes its record as a whole: the rescan only writes what the record has, so the book's details (series and number, subtitle, description, publisher, dates, language, version, edition, narrators, genres, ISBNs) are emptied first, on every repair (a rescan of the same record too), then the rescan fills what the record has. The title, authors, cover and runtime are always read again, so they stay until then: a failed rescan never leaves a book without a title. When a repair stops part way, its row says what was saved ("The new ASIN is saved and its details emptied, but the metadata rescan failed …", "Its details are emptied, but …", "The new ASIN is saved, but its old details couldn't be emptied …"). Without it, a book kept the old record's series and Organize filed it under it. The server should do this itself: [Epic] Book metadata: what the provider manages, what the user manages, and when a book is rescanned #1125 (book metadata epic).
• The ASIN a book is repaired away from is dropped, whatever its source: the server stores every ASIN a repair saves as Manual, so an earlier repair's would stay as a fallback the rescan reads. Other Manual identifiers (an ASIN added for another region, an ISBN typed by hand) stay.
• Once the rescan has answered, the book is repaired: the book the rescan answers with is shown when the answer holds it (Metadata rescan: answer with the saved book, so callers don't have to read it back #1128), with no other request; until then the book is read back, and a read that fails only leaves the row showing the picked record ("Repaired in 1.2 s; the book couldn't be read back to show it: …"), still green and ticked for Organize. The row shows the subtitle and authors the server has. Before, a failed read was reported as a failed rescan, in orange.
• A rescan refused for coming too soon waits: the server rescans a book once every 15 s, and 5 times in 10 minutes. The row counts down ("Waiting 12 s: a book can be rescanned once every 15 s"), then the rescan is asked once more; a longer wait fails at once, saying when to retry ("too many rescans of this book, retry in about 8 min"). Cancel also stops a book waiting there.
• A rescan that read another record than the picked one says so: when the picked record fails, the server reads the book's other identifiers (its other ASINs, then ISBNs). The row then ends in orange, "The rescan read another record (ASIN - Region) than the one picked: check the book", and the book isn't ticked for Organize.
• One repair at a time: each row's bar breathes blue while its book is repaired, then turns green, orange or red. The dialog's bottom bar fills as each repair ends, breathing until the last one; legend for the rows' bars on its own line above the buttons.
• Any problem turns the bottom bar orange and is said between Close and the skipped count ("Not all repaired: 1 failed, 1 repaired in part, 1 canceled"), in a place kept from the start of step 2 (above the buttons when its longest text doesn't fit).
• Cancel is red while the repairs run: the book being repaired ends first, the ones still waiting are canceled at once. Rolling back what a repair changed is a later step of [Epic] Repair books that point at the wrong Audible record #1080. Organize waits for the repairs to end; a repaired book is ticked for it as soon as it is done.
• Leaving the page while the repairs run asks first ("Leave while books are repaired?", Leave or Stay), shown on top of the Repair dialog (the shared confirm dialog now sits above any dialog that asks it: it came under it), since they run in the browser. The repairs hold while it asks: the book being repaired ends, the next one waits for the answer. Stay goes on with them; Leave cancels the books still waiting, as Cancel does. Closing or reloading the tab gets the browser's own warning; if the dialog goes anyway, the waiting books are left out, so nothing keeps running unseen. Leave chosen after the last repair ended under the question leaves nothing paused: if the page then stays (its navigation failed, e.g. the page's code couldn't load after an update), the next Repair runs normally. Only Cancel stops a book waiting for the rescan cooldown (its row says so, with Retry); Leave, or the dialog going, lets it finish its rescan, as the question promises.
• Retry at the bottom right of a failed row, or of one done in part, repairs that book again (red Cancel and Organize waiting meanwhile). It sits in room the row always keeps free, so showing it moves nothing.
• An unexpected error ends the run: the books not repaired yet end failed ("Repair stopped: …"), shown on step 2 and retryable; the dialog never stays repairing.
• Back, once the repairs are over (in place of Close, the same size as Cancel): step 1 loaded as when the dialog opens, each book as the repairs left it. Closing the dialog after a repair saved something refreshes the page behind, even from step 1.
• No shift: the message at the top keeps the height of its longest version; with one book, step 2 keeps step 1's height (an empty room under the row).

Step 3, Organize: "Organize n" opens the Organize dialog, titled as Repair's step 3, on the ticked repaired books (their files were organized with the old metadata, which the message at the top of step 2 says). Its Cancel is Back there: step 2 again, as it was left. It opens at once: Organize reads its previews from the server, and the page behind (the library, or the book, kept shown) is refreshed meanwhile. Before, it waited for the whole library to be read again, with no dialog in between.

Known limit: the repairs run in the browser tab. No lock between tabs (another tab goes stale; the same book repaired in two tabs keeps the last save), and a tab closed mid-repair, past the browser's warning, may leave the book being repaired done in part, which a Rescan finishes. The "Repairs as backend tasks" step of #1080 removes it.

Known limit: one book at a time, in the browser. Books are loaded, then repaired, one after the other (no backend task yet), so a large selection takes a while, and a selection of hundreds of books makes a dialog with hundreds of cards. Repair is meant for the odd book that points at the wrong record, not for the whole library. The "Repairs as backend tasks" step of #1080 lifts it.

Known limit: Repair trusts the server's rescan. When Audible gives an empty record for the picked ASIN at the time of the rescan, the server still answers success and the book keeps its old metadata, so the row says Repaired: #1124.

Known issue, from Add New's search: a title or author holding "Series:", "Author:", "Title:", "ISBN:" or "ASIN:" is searched wrongly (#1127). The cards search exactly like Add New, whose search splits such a title on that word as if it were a search keyword ("The Wheel of Time Series: Book 1" is searched as the series "Book 1"). Canary's Find Match sent the title and author apart, so this PR brings the problem there; it is the price of one shared search instead of three, which also makes the move to the backend search (#1076) one change. Fixing Add New's search fixes Add New, Find Match and Repair at once.

Known issue, already on canary: the page scrolls behind an open dialog (the shared Modal doesn't lock it). Not caused nor fixed here; it needs its own issue and a fix in the shared Modal.

Not in this PR

• The "Broken books" group is its own draft PR, [Step][#1080] Library: a temporary "Broken books" group, with the server's reasons #1082.
• The Issues screen: its first draft, [Step][#1080] Issues: a page listing the books to repair #1081, was closed after the direction changed; the step stays in [Epic] Repair books that point at the wrong Audible record #1080 and will be rewritten from scratch.
• Add New's search box for the card: [Step][#1080] Search: Add New's search box and search rules for Repair and Find Match #1086, a draft stacked on an earlier state of this PR, paused for now.
• The backend book search will be its own PR under [Discussion] One backend book search, and searches/lookups as backend jobs over SignalR #1076.

Tests

RepairBooksModal.spec.ts, LibraryImportSearchModal.spec.ts and FindMatchResults.spec.ts cover the rules above: search priority and its triggers, the answered searches and Retry, the header line and its sources, loading and reveal timings (fake clock), placeholders and kept heights, the tags, one search at a time, the footer layout, the highlighted parts, step 2 (one repair at a time, Cancel, Retry, Back, the warning, details, the kept heights, leaving the page and the repairs held while it asks, the rescan cooldown, a rescan that read another record, only the latest load, a book that can't be loaded, the details emptied, the question before repairing, Escape on a question over the dialog) and Organize's step 3 (its title, Back). Frontend: 828 passed; type-check, eslint and prettier are clean. No backend change.

End to end, on a real instance: five scenarios drive the real app in Chrome (Playwright), on a throwaway Listenarr with its library on local storage and real Audible searches; the checks read the API and the files on disk. The sample library is generated by m4bard/listenarr-testdata (commit bd59f6f, seed 1): five real public-domain books with verified ASINs, as silent one-second files carrying genuine tags (two of them in 40 chapters), in an author/title layout. The instance has French settings. A seed runs a real Library Import and is snapshotted (database, library, import folder); every other scenario restores it first. All five pass on this branch (full run about 2.5 min). Every repair accepts the question "Repair n books?" first. An earlier run found one bug, fixed here: the "Leave while books are repaired?" confirmation opened under the Repair dialog, unseen and unclickable (the shared confirm dialog's overlay is now above the dialog that asks it, ConfirmDialog.vue).

Scenario	What it checks	Result
00 Seed: Library Import	Scan 5 folders, Start Matching (only Vingt mille lieues sous les mers is sold in France: matched to its French record), Find Match points it by mistake at the English Twenty Thousand Leagues Under the Sea (US) and finds the three US books in the US, import 4 books with Move; 82 audio files in the library, A Princess of Mars left in the import folder	Pass, 30 s
10 Repair from the book page	Vingt mille lieues searched in France, its French record picked; the question "Repair 1 book?" canceled, then dismissed with Escape: step 1 as it was; then accepted, repaired, organized as step 3; primary ASIN B0F48KS3BX/fr, the French title, no series left (the English record's Captain Nemo #1), its 40 files in the new folder (not under Captain Nemo), no audio left in the old one	Pass, 50 s
11 Repair several from the library	Dr Jekyll and Mr Hyde left out ("3 skipped" → "1 skipped"), Pride and Prejudice on its Current record, Vingt mille lieues on its French record; Organize 1 with Pride and Prejudice unticked, Back to step 2 as it was left, Back to step 1 loaded afresh; the two others unchanged	Pass, 8 s
12 Leaving during repairs	Browser Back during "Repair 3" asks, the confirmation on top; Stay: all three done, still on the page; Back once over leaves without asking; again with Leave: the book still waiting is not repaired	Pass, 38 s
13 Find Match on a matched folder	A Princess of Mars matched in the US, Find Match opened again: the scan's ASIN in the ASIN field, France, the scan's search, the US match only on Current	Pass, 4 s

Every step, its expected result, and what the runs showed

00 Seed

1. Scan "Import local" → "Last scanned … 5 unmatched".
2. Start Matching → Vingt mille lieues on its French record (B0F48KS3BX); the US books "No match found" (not sold in France).
3. Find Match on Vingt mille lieues: region US, ASIN emptied, title Twenty Thousand Leagues Under the Sea, author Jules Verne, pick B01FKWL15A, Use this match: the wrong record, on purpose.
4. Find Match on Robinson Crusoe, Dr Jekyll and Mr Hyde and Pride and Prejudice: region US (searches the scan's ASIN by itself), pick the result with that ASIN, Use this match.
5. Import 4 Books with Move into the library folder → the library holds 4 books.
6. API and disk → the four ASINs; 82 audio files in the library (40 + 40 + 1 + 1); 1 left in the import folder.

10 Repair from the book page

1. Repair from Vingt mille lieues' page → the card opens; the book is B01FKWL15A/us.
2. ASIN cleared, title Vingt mille lieues sous les mers, author Jules Verne, region France, pick B0F48KS3BX → "Repair 1".
3. Repair 1 → "Repair 1 book? … This can't be undone."; Cancel → step 1, "Repair 1", nothing changed; Repair 1 again, Escape → the same.
4. Repair 1, accepted → step 2 ends, the book done.
5. Organize 1 (step 3), Done.
6. API and disk → B0F48KS3BX/fr; the French title; no series (it was Captain Nemo Basic Functionality #1); a new folder, not under Captain Nemo; its 40 files exist; no audio in the old folder.

11 Repair several from the library

1. Tick Dr Jekyll and Mr Hyde, Pride and Prejudice, Vingt mille lieues; Repair Selected (3) → three cards, "3 skipped".
2. Pride and Prejudice: Current picked; Vingt mille lieues: its French record picked → "Repair 2", "1 skipped".
3. Repair 2 → both done; Dr Jekyll and Mr Hyde not on step 2.
4. Untick Pride and Prejudice, Organize 1, Back → step 2 as it was left, "Organize 1".
5. Back → step 1 afresh: Vingt mille lieues' Current is B0F48KS3BX, "Repair 0".
6. API → B0F48KS3BX/fr; the two others unchanged.

12 Leaving during repairs

1. Library Import, then Audiobooks by the sidebar; Pride and Prejudice and Robinson Crusoe on Current, Vingt mille lieues on its French record, last → "Repair 3".
2. Repair 3, browser Back → "Leave while books are repaired?", the element at its centre is its own, it says the waiting ones are not repaired.
3. Stay → all three done; still on Audiobooks; B0F48KS3BX/fr.
4. Back once over → Library Import, nothing asked.
5. Same three, Vingt mille lieues pointed back at the English record; Repair 3, Back, Leave → Library Import.
6. 20 s later → still B0F48KS3BX/fr: its repair, waiting when Leave was chosen, never ran.

13 Find Match on a matched folder

1. Scan what is left, Start Matching → "1 unmatched", matching ends.
2. Find Match on A Princess of Mars: region US (searches the scan by itself), pick B008DFUGCQ, Use this match → its row shows it.
3. Find Match again → the scan's ASIN (B008DFUGCQ) in the ASIN field, region France, the scan's search, the US match only on Current, results "in France (FR)".

What the runs showed

• The bug above: step 2 of scenario 12 failed before the fix (the confirmation was under the Repair dialog), passed after it.
• Not covered here: closing the tab and two tabs at once (the known limit above), and what the unit specs and the captures below cover.

How it looks

Every interaction, step by step: the real dialogs (this branch's components and styles) in a browser over a simulated API, so the timings and failures show. Every repair answers "Repair n books?" first. Click a group to open it.

Step 1, matching (13)

A title search revealing its results; a record picked (ticked, New with the changes in green, Current with the replaced parts in orange, bar green), clicked again to unpick it, another one picked.

Typing only prepares: Enter or Search runs the search, Search becomes Retry, a changed field makes it Search again; an erase button.

A region change searches there; back to a region already searched: Cached results; Retry asks Audible again.

A filled ASIN searched on its own: no record in the new region (orange), a typed ASIN found and picked, an ASIN that isn't one.

A slow search (3 s): the bar breathing blue, the spinner over the list; Cancel search, then Retry.

A failed request: the empty list with the reason in red in its middle; Retry.

Revert: the fields back as they were, the pick dropped.

One search at a time: the other book waits, greyed out; nothing moves when the first answers.

A matched book unticked (skipped), Clear, Select All.

The legend centred on the dialog, moved aside, then above the buttons.

Cancel closes the dialog.

Three books selected: one deleted since (its card says so, nothing to load again), one whose load timed out (Load again reads it); the others stay repairable.

A record without an ASIN (Audible has nothing, the server adds one from OpenLibrary): greyed, tagged "No ASIN", and it can't be picked: a repair needs a record a metadata provider can read again.

Step 2, the repair process (15)

Repair asks first, since it can't be undone: Cancel, then Escape, both leave step 1 as it was; asked again and accepted, the repair runs.

One book, a slow repair: step 2 at once, the dialog keeping step 1's height.

A fast repair.

Three books, one repair at a time; the bottom bar filling.

A failed repair and one done in part: the bottom bar orange, the warning.

Cancel during the repair: the running one ends, the others are canceled.

Show details / Hide details: Old with the replaced parts in orange, New with the changes in green.

What to organize: a book unticked, Clear, Select All.

Step 2's footer as the dialog narrows: the warning's place going above the buttons.

Back, once the repairs are over: step 1 loaded afresh, each book as it was repaired.

Retry on a failed repair: that book repaired again, the warning gone once it works.

Leaving the page during the repairs (browser Back, shown by the label): the confirmation on top of the dialog, the repairs held while it asks (the running book ends, the next one waits); Stay, and they go on to the end.

The same, then Leave: the book being repaired ends, the ones still waiting are not repaired, and the page changes.

A rescan refused for coming too soon (the server's 15 s cooldown): the row counts down, then the book is repaired.

The rescan read another record than the picked one (the server fell back to the book's other ASIN): the row ends in orange, naming it, and the book isn't ticked for Organize.

Step 3, Organize (2)

Organize 2 opens the Organize dialog as Repair's step 3, then organizes.

Back from Organize: step 2 as it was left.

Find Match (Library Import) (12)

Opens searching the folder's title and author; pick, unpick, pick another, then Use this match.

Typing only prepares; Enter searches; an erased author, Search; nothing changed, Retry.

A region change searches there; back to a region already searched: Cached results; Retry asks again.

An ASIN in the folder's files: in the ASIN field and looked up on open, its record offered (not picked), then used.

A typed ASIN looked up with Enter and offered; one that isn't an ASIN said without a request.

The search on open is slow: Cancel search (orange), then Retry, answered.

The search on open fails: the reason in red; Retry, then pick and use.

Revert: the fields back to what the files said, the pick dropped.

Already matched (the French Vol. 7): it opens with the same search as any folder, from its scan, its match only shown as Current; in France its own record is tagged Current, nothing to use; back to the US (cached), the English one used.

A record picked, then a new search: Use this match waits for it, and the pick is dropped.

Closed during the search on open: the dialog goes, nothing sent back.

A book Audible doesn't have: the search adds an OpenLibrary record, without an ASIN; Find Match can pick it and use it (Library Import adds the book from it), as canary did.

🤖 Generated with Claude Code