fix(downloads): a site the downloader no longer understands says so, and offers a retry

yt-dlp asks for a bug report on an extraction failure it did not expect: the site answered in a way its extractor does not read (measured on a TikTok link: fails on every attempt under yt-dlp 2026.07.04, downloads under 2026.08.19). That failure read as "Something went wrong" with no retry; it is now its own category, site_changed, with a Retry in the failure window. A contract test holds every failure category to its copy in both languages.

frontend/src/components/downloadModals.error.dom.test.tsx

@@ -0,0 +1,39 @@
+// @vitest-environment jsdom
+//
+// The failure window offers a Retry only where a retry can help: a transient failure, or a site the
+// downloader did not understand (an update on the server cures it). Never for an unclassified one.
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import type { DownloadJob } from "../lib/api";
+import { ErrorModal } from "./downloadModals";
+
+vi.mock("react-i18next", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react-i18next")>()),
+  useTranslation: () => ({
+    i18n: { language: "en" },
+    t: (key: string | string[]) => (Array.isArray(key) ? key[0] : key),
+  }),
+}));
+
+afterEach(cleanup);
+
+function open(error_code: string) {
+  const onRetry = vi.fn();
+  const job = { id: 1, status: "error", error: "ERROR: x", error_code } as unknown as DownloadJob;
+  render(<ErrorModal job={job} onRetry={onRetry} onClose={() => {}} />);
+  return onRetry;
+}
+
+describe("ErrorModal", () => {
+  it("offers a retry when the site changed under the downloader", () => {
+    const onRetry = open("site_changed");
+    expect(screen.getByText("downloads.errors.fail.cat.site_changed.short")).toBeTruthy();
+    fireEvent.click(screen.getByRole("button", { name: "downloads.actions.retry" }));
+    expect(onRetry).toHaveBeenCalledOnce();
+  });
+
+  it("offers none for an unclassified failure", () => {
+    open("unknown");
+    expect(screen.queryByRole("button", { name: "downloads.actions.retry" })).toBeNull();
+  });
+});

frontend/src/components/downloadModals.tsx

@@ -106,7 +106,9 @@ export function MetaEditModal({ job, onClose }: { job: DownloadJob; onClose: ()
 // retry control regardless. `unknown` is deliberately NOT here: an unclassified failure is most often an
 // auth wall we couldn't parse (a login-walled Facebook post reads as a bare "no format"), so a
 // prominent Retry would mislead; force-retrying from the row stays available for genuine transients.
-const RETRYABLE_ERRORS = ["postprocess", "network", "convert_failed"];
+// `site_changed` is here: the site answered in a way the downloader did not understand, which a
+// downloader update on the server cures — the same link then goes through on a retry.
+const RETRYABLE_ERRORS = ["postprocess", "network", "convert_failed", "site_changed"];
 
 // A readable "why did this fail" window for a failed job: a category headline + plain explanation,
 // the raw yt-dlp/ffmpeg text behind a disclosure, and a Retry when the failure may be transient.

frontend/src/i18n/backendIds.contract.test.ts

@@ -86,6 +86,18 @@ const failDetails = [
   ...new Set([...backend("downloads/errors.py").matchAll(/detail="([\w.]+)"/g)].map((m) => m[1]!)),
 ];
 const DETAIL = "downloads.errors.fail.catalog.";
+// Every category `classify` / the catalog can give a failure → `downloads.errors.fail.cat.<code>`. A
+// category without copy never fails loudly: the row falls back to the "unknown" sentence.
+const failCategories = [
+  ...new Set([
+    ...[
+      ...(backend("downloads/errors.py").split("_RULES: tuple")[1] ?? "")
+        .split("\n)\n")[0]!
+        .matchAll(/,\s*"(\w+)"\),/g),
+    ].map((m) => m[1]!),
+    ...[...backend("downloads/errors.py").matchAll(/code="(\w+)"/g)].map((m) => m[1]!),
+  ]),
+];
 
 // What a structured 404 says is gone → `errors.notFound.<what>`: every `not_found("x")` and every
 // `owned_or_404(..., what="x")` / `get_or_404(..., what="x")` under routes/, read from the sources.
@@ -317,6 +329,18 @@ describe("backend ids have their names in both languages", () => {
       );
     });
 
+    it(`${lang}: every download failure category`, () => {
+      expect(failCategories.length).toBeGreaterThan(5);
+      expect(
+        missing(
+          failCategories.flatMap((c) => [
+            `downloads.errors.fail.cat.${c}.short`,
+            `downloads.errors.fail.cat.${c}.body`,
+          ]),
+        ),
+      ).toEqual([]);
+    });
+
     it(`${lang}: every download failure-catalog entry`, () => {
       expect(
         missing(failDetails.flatMap((d) => [`${DETAIL}${d}.short`, `${DETAIL}${d}.body`])),

frontend/src/i18n/locales/en/downloads.json

@@ -294,6 +294,10 @@
           "short": "Source unavailable",
           "body": "The original download this clip is based on is no longer available."
         },
+        "site_changed": {
+          "short": "The site has changed",
+          "body": "The site answered in a way the downloader doesn't understand yet – it has probably changed. An update of the downloader on the server usually fixes this, so try again later."
+        },
         "network": {
           "short": "Network error",
           "body": "A network error interrupted the download. A retry usually fixes this."

frontend/src/i18n/locales/hu/downloads.json

@@ -294,6 +294,10 @@
           "short": "A forrás nem elérhető",
           "body": "Az eredeti letöltés, amelyből ez a vágás készült, már nem érhető el."
         },
+        "site_changed": {
+          "short": "Az oldal megváltozott",
+          "body": "Az oldal olyan választ adott, amit a letöltő még nem ért – valószínűleg megváltozott. Ezt általában a szerveren futó letöltő frissítése javítja, ezért próbáld újra később."
+        },
         "network": {
           "short": "Hálózati hiba",
           "body": "Hálózati hiba szakította meg a letöltést. Újrapróbálásra általában megjavul."