feat(import): add episode match-mode toggle (TVDB id vs season/episode)

The importer resolves episodes by their TVDB id by default (exact, survives
season/episode renumbering). But some episodes have no TVDB id in Trakt yet,
so id-matching drops them. Give users a fallback: a toggle in the import
summary to match episodes by show + season/episode number instead.

- EpisodeMatchMode ('id' | 'positional'), default 'id'; threaded through
  syncToTrakt into buildHistoryPayload
- buildHistoryPayload: positional mode routes every episode with a positional
  key by show + season/number (incl. id-carrying ones); id mode keeps the id
  path with positional as fallback
- ImportSummary shows the toggle only when the import contains episodes, with
  a hint that the default is recommended and positional results vary per show

TVDB-id stays the default and recommended path. Positional is opt-in for the
still-null episodes while episode tvdb_id backfill catches up.

Author: vladjerca

projects/client/i18n/meta/en.json

@@ -5168,6 +5168,14 @@
         }
       }
     },
+    "import_match_toggle_label": {
+      "default": "Match episodes by season and episode number",
+      "description": "Label for the import toggle that switches episode matching from the episode's TVDB id (default) to show + season/episode number."
+    },
+    "import_match_toggle_hint": {
+      "default": "We recommend the default (match by TVDB id). Turn this on only if some episodes land on the wrong entry - results vary from show to show.",
+      "description": "Helper text under the episode-match toggle explaining the default is recommended and that positional matching results vary."
+    },
     "import_complete_synced": {
       "default": "{count} items synced successfully.",
       "description": "Text shown at the end of a successful import showing the count of synced items.",

projects/client/src/lib/sections/settings/_internal/RawImport.svelte

@@ -16,7 +16,9 @@
   import { slide } from "svelte/transition";
   import {
     type AmbiguousImportItem,
+    DEFAULT_EPISODE_MATCH_MODE,
     DEFAULT_IMPORT_SOURCE,
+    type EpisodeMatchMode,
     IMPORT_SOURCE_CONFIGS,
     type ImportAction,
     type ImportActionSelection,
@@ -61,6 +63,7 @@
   type ImportUIState = SyncState<ImportStatus> & {
     selectedSource: ImportSource;
     selectedActions: ImportActionSelection;
+    episodeMatch: EpisodeMatchMode;
     parsedItems: ReadonlyArray<UniversalImportItem>;
     errorCount: number;
     unresolved: ReadonlyArray<UniversalImportItem>;
@@ -73,6 +76,7 @@
   const state = $state<ImportUIState>({
     selectedSource: DEFAULT_IMPORT_SOURCE,
     selectedActions: defaultSelectedActions(),
+    episodeMatch: DEFAULT_EPISODE_MATCH_MODE,
     status: "idle",
     parsedItems: [],
     processedCount: 0,
@@ -104,6 +108,9 @@
     list: state.selectedActions.list ? counts.list : 0,
   });
   const selectedTotalCount = $derived(selectedItems.length);
+  const hasEpisodes = $derived(
+    state.parsedItems.some((item) => item.type === "episode"),
+  );
 
   const sourceConfig = $derived(IMPORT_SOURCE_CONFIGS[state.selectedSource]);
   const isGuideCollapsed = $derived(
@@ -123,6 +130,7 @@
 
     state.parseError = null;
     state.selectedActions = defaultSelectedActions();
+    state.episodeMatch = DEFAULT_EPISODE_MATCH_MODE;
     state.status = "parsing";
 
     try {
@@ -173,6 +181,7 @@
         itemsToImport,
         {
           signal: abortController.signal,
+          episodeMatch: state.episodeMatch,
           onMatchProgress: (processed, total) => {
             state.matchProcessedCount = processed;
             state.matchTotalCount = total;
@@ -235,6 +244,7 @@
       abortController = new AbortController();
       const { errorCount } = await syncToTrakt(picked, {
         signal: abortController.signal,
+        episodeMatch: state.episodeMatch,
         onProgress: () => {},
         onError: (message) => {
           // FIXME: properly deal with this when tackling https://github.com/trakt/trakt-web/issues/2055
@@ -257,6 +267,7 @@
     abortController?.abort();
     state.status = "idle";
     state.selectedActions = defaultSelectedActions();
+    state.episodeMatch = DEFAULT_EPISODE_MATCH_MODE;
     state.parsedItems = [];
     state.processedCount = 0;
     state.errorCount = 0;
@@ -300,6 +311,10 @@
       [action]: isIncluded,
     };
   }
+
+  function onMatchChange(mode: EpisodeMatchMode) {
+    state.episodeMatch = mode;
+  }
 </script>
 
 {#snippet importRow()}
@@ -327,7 +342,10 @@
             {counts}
             selectedActions={state.selectedActions}
             source={state.selectedSource}
+            episodeMatch={state.episodeMatch}
+            showMatchToggle={hasEpisodes}
             onactionchange={onActionChange}
+            onmatchchange={onMatchChange}
             onstart={startImport}
             onreset={reset}
           />

projects/client/src/lib/sections/settings/_internal/import/ImportSummary.spec.ts

@@ -1,6 +1,7 @@
 import { fireEvent, render, screen } from '@testing-library/svelte';
 import { of } from 'rxjs';
 import { describe, expect, it, vi } from 'vitest';
+import type { EpisodeMatchMode } from '../../import/ImportTypes.ts';
 import ImportSummary from './ImportSummary.svelte';
 
 vi.mock('$lib/features/auth/stores/useUser.ts', () => ({
@@ -18,20 +19,30 @@ describe('ImportSummary', () => {
     list: 1,
   };
 
-  it('should show an enabled switch for every import action with items', () => {
-    render(ImportSummary, {
+  const allSelected = {
+    history: true,
+    watchlist: true,
+    ratings: true,
+    list: true,
+  };
+
+  function baseProps(overrides: Record<string, unknown> = {}) {
+    return {
       counts,
-      selectedActions: {
-        history: true,
-        watchlist: true,
-        ratings: true,
-        list: true,
-      },
-      source: 'tvtime',
+      selectedActions: allSelected,
+      source: 'tvtime' as const,
+      episodeMatch: 'id' as EpisodeMatchMode,
+      showMatchToggle: false,
       onactionchange: vi.fn(),
+      onmatchchange: vi.fn(),
       onstart: vi.fn(),
       onreset: vi.fn(),
-    });
+      ...overrides,
+    };
+  }
+
+  it('should show an enabled switch for every import action with items', () => {
+    render(ImportSummary, baseProps());
 
     expect(screen.getByRole('switch', { name: '2 items for History' }))
       .toBeChecked();
@@ -45,19 +56,7 @@ describe('ImportSummary', () => {
   it('should request skipping an import action when its switch is clicked', async () => {
     const onactionchange = vi.fn();
 
-    render(ImportSummary, {
-      counts,
-      selectedActions: {
-        history: true,
-        watchlist: true,
-        ratings: true,
-        list: true,
-      },
-      source: 'tvtime',
-      onactionchange,
-      onstart: vi.fn(),
-      onreset: vi.fn(),
-    });
+    render(ImportSummary, baseProps({ onactionchange }));
 
     await fireEvent.click(
       screen.getByRole('switch', { name: '3 items for Watchlist' }),
@@ -67,24 +66,49 @@ describe('ImportSummary', () => {
   });
 
   it('should disable start import when all import actions are skipped', () => {
-    render(ImportSummary, {
-      counts,
-      selectedActions: {
-        history: false,
-        watchlist: false,
-        ratings: false,
-        list: false,
-      },
-      source: 'tvtime',
-      onactionchange: vi.fn(),
-      onstart: vi.fn(),
-      onreset: vi.fn(),
-    });
+    render(
+      ImportSummary,
+      baseProps({
+        selectedActions: {
+          history: false,
+          watchlist: false,
+          ratings: false,
+          list: false,
+        },
+      }),
+    );
 
     expect(
       screen.getByRole('button', {
         name: 'Start importing your data into Trakt.',
       }),
     ).toBeDisabled();
   });
+
+  it('should not render the match toggle when there are no episodes', () => {
+    render(ImportSummary, baseProps({ showMatchToggle: false }));
+
+    expect(
+      screen.queryByRole('switch', {
+        name: 'Match episodes by season and episode number',
+      }),
+    ).toBeNull();
+  });
+
+  it('should request positional matching when the match toggle is turned on', async () => {
+    const onmatchchange = vi.fn();
+
+    render(
+      ImportSummary,
+      baseProps({ showMatchToggle: true, episodeMatch: 'id', onmatchchange }),
+    );
+
+    await fireEvent.click(
+      screen.getByRole('switch', {
+        name: 'Match episodes by season and episode number',
+      }),
+    );
+
+    expect(onmatchchange).toHaveBeenCalledWith('positional');
+  });
 });

projects/client/src/lib/sections/settings/_internal/import/ImportSummary.svelte

@@ -6,6 +6,7 @@
   import UpsellCta from "$lib/features/upsell/UpsellCta.svelte";
   import { slide } from "svelte/transition";
   import type {
+    EpisodeMatchMode,
     ImportAction,
     ImportActionSelection,
     ImportCounts,
@@ -16,7 +17,10 @@
     counts: ImportCounts;
     selectedActions: ImportActionSelection;
     source: ImportSource;
+    episodeMatch: EpisodeMatchMode;
+    showMatchToggle: boolean;
     onactionchange: (action: ImportAction, isIncluded: boolean) => void;
+    onmatchchange: (mode: EpisodeMatchMode) => void;
     onstart: () => void;
     onreset: () => void;
   };
@@ -25,7 +29,10 @@
     counts,
     selectedActions,
     source,
+    episodeMatch,
+    showMatchToggle,
     onactionchange,
+    onmatchchange,
     onstart,
     onreset,
   }: ImportSummaryProps = $props();
@@ -104,6 +111,23 @@
     {/each}
   </div>
 
+  {#if showMatchToggle}
+    <div class="import-summary-match">
+      <span class="import-summary-switch">
+        <Switch
+          label={m.import_match_toggle_label()}
+          checked={episodeMatch === "positional"}
+          onclick={() =>
+          onmatchchange(episodeMatch === "positional" ? "id" : "positional")}
+        />
+      </span>
+      <div class="match-copy">
+        <p aria-hidden="true">{m.import_match_toggle_label()}</p>
+        <p class="secondary match-hint">{m.import_match_toggle_hint()}</p>
+      </div>
+    </div>
+  {/if}
+
   {#if isVipLimitExceeded}
     <UpsellCta source="import" variant="small">
       {m.import_vip_limit_exceeded({ count: selectedTotalItems })}
@@ -178,6 +202,23 @@
     }
   }
 
+  .import-summary-match {
+    display: grid;
+    grid-template-columns: var(--ni-44) minmax(0, 1fr);
+    align-items: start;
+    gap: var(--gap-xs);
+  }
+
+  .match-copy {
+    display: flex;
+    flex-direction: column;
+    gap: var(--gap-xxs);
+  }
+
+  .match-hint {
+    font-size: var(--font-size-tag);
+  }
+
   .import-summary-actions {
     display: flex;
     align-items: center;

projects/client/src/lib/sections/settings/import/ImportTypes.ts

@@ -13,6 +13,15 @@ export type ImportAction = 'history' | 'watchlist' | 'ratings' | 'list';
 
 export type ImportActionSelection = Record<ImportAction, boolean>;
 
+// How watched episodes are matched to Trakt on import:
+// - 'id' (default, recommended): the episode's own TVDB id - exact, survives
+//   season/episode renumbering.
+// - 'positional': show + season/episode number - a fallback for episodes whose
+//   TVDB id Trakt doesn't have, at the cost of numbering-divergence mismatches.
+export type EpisodeMatchMode = 'id' | 'positional';
+
+export const DEFAULT_EPISODE_MATCH_MODE: EpisodeMatchMode = 'id';
+
 export type ImportType = 'movie' | 'show' | 'episode';
 
 export type ImportStatus =

projects/client/src/lib/sections/settings/import/engine/buildHistoryPayload.spec.ts

@@ -223,6 +223,40 @@ describe('buildHistoryPayload', () => {
       expect(result.shows).toHaveLength(0);
     });
 
+    it('should resolve positionally over the episode id in positional mode', () => {
+      const item: UniversalImportItem = {
+        action: 'history',
+        type: 'episode',
+        ids: { tvdb: 4321 },
+        showTvdb: 9001,
+        season: 2,
+        episode: 1,
+        watched_at,
+      };
+
+      const result = buildHistoryPayload([item], 'positional');
+
+      expect(result.episodes).toHaveLength(0);
+      expect(result.shows).toEqual([{
+        ids: { tvdb: 9001 },
+        seasons: [{ number: 2, episodes: [{ number: 1, watched_at }] }],
+      }]);
+    });
+
+    it('should fall back to the episode id in positional mode when no positional key', () => {
+      const item: UniversalImportItem = {
+        action: 'history',
+        type: 'episode',
+        ids: { tvdb: 4321 },
+        watched_at,
+      };
+
+      const result = buildHistoryPayload([item], 'positional');
+
+      expect(result.episodes).toEqual([{ ids: { tvdb: 4321 }, watched_at }]);
+      expect(result.shows).toHaveLength(0);
+    });
+
     it('should add an episode by its id when not positionally resolvable', () => {
       const item: UniversalImportItem = {
         action: 'history',