From 374cfbb1923aee89a1431ced896332306ac5d910 Mon Sep 17 00:00:00 2001
From: Nicolas <nicolaslef53@gmail.com>
Date: Sat, 19 Sep 2026 15:43:46 +0200
Subject: [PATCH] feat: recherche YouTube globale, avec defilement infini

Nouveau formulaire "Recherche YouTube" (mots-cles + limite optionnelle),
branche sur la zone de resultats existante (miniatures, bouton "Ajouter"
par ligne ; pas de "Tout ajouter", comme demande).

- Avec une limite : tous les resultats d'un coup (une seule page).
- Sans limite : defilement infini. Un element sentinelle en fin de liste,
  observe par un IntersectionObserver (racine = la liste, marge 300 px),
  charge la page suivante ; il est rearme apres chaque page, affiche
  chargement / erreur avec "Reessayer" / "Fin des resultats", et une page
  en echec ne fait pas perdre les precedentes.

Serveur (GET/POST/DELETE /api/search) : une "session" = un seul yt-dlp
(--flat-playlist --lazy-playlist -j -- ytsearch1000:<requete>) servi page
par page depuis un tampon. Pourquoi pas un appel yt-dlp par page - mesure
avec le vrai yt-dlp : l'ordre des resultats de YouTube n'est pas
deterministe meme pour deux appels identiques (5/20 aux memes positions,
69 % de recouvrement sur 100), donc paginer en relancant la recherche
donnait 15 a 30 % de doublons des la 3e-4e page et des trous ; YouTube
s'arrete vers ~590 resultats ; ~7 % de doublons internes (dedoublonnes a
l'ingestion) ; sans --lazy-playlist yt-dlp n'imprime rien avant la fin
(~23 s), avec il emet au fil des pages (20 en ~2,3 s).

Le parcours n'avance qu'a la demande : quand le tampon a 20 resultats
d'avance, la lecture de stdout est suspendue (nouvelle option onSpawn de
runYtDlp) ; le tube se remplit et yt-dlp bloque (mesure : plus aucune
ligne pendant 10 s de pause). On n'aspire donc pas ~590 resultats, et ~30
requetes vers YouTube, quand l'utilisateur ne defile pas.

Cycle de vie : 4 sessions simultanees max (la moins recemment utilisee est
fermee), expiration a 10 min d'inactivite / 30 min de vie, fermeture des
que la derniere page est servie, sur DELETE (liste remplacee cote client),
au pagehide du client, et a l'arret du serveur. Requete validee (1 a 200
caracteres, sans caractere de controle) et transmise en un seul argument
ytsearchN:<requete>, jamais interpretable comme une option.

Mise en page : ce troisieme formulaire laissait a la liste ~104 px (une
ligne) a 1366x650. Une liste non vide garde min-height 13rem et la colonne
du formulaire defile au lieu de rogner (la page ne defile toujours pas).

Verifie : contre le vrai yt-dlp (page tamponnee en 4 ms, page 200 apres
12 s d'inactivite en ~4 s : la suspension tient ; 29 pages -> 576 videos,
576 uniques ; processus fermes a la fin / sur DELETE / au plafond) et dans
le navigateur (580 resultats sans doublon jusqu'a "Fin des resultats",
requetes de page uniques malgre deux signaux simultanes, echec + reprise,
session expiree, remplacement de la recherche, mode limite, ajout d'un
resultat a la file, pagehide, playlist et chaine en non-regression). Le
volet IntersectionObserver a ete pilote par un observateur factice : le
panneau de navigation n'affichait plus de frames (rAF/IO natifs muets).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 README.md                                     |   1 +
 client/src/api/searchApi.ts                   | 126 +++++++
 client/src/api/videoDto.ts                    |   8 +
 client/src/searchLimit.ts                     |  16 +
 client/src/styles/base.scss                   |   1 +
 .../src/views/downloadForm/DownloadForm.html  |  13 +
 .../src/views/downloadForm/DownloadForm.scss  |  37 ++
 client/src/views/downloadForm/DownloadForm.ts | 344 ++++++++++++++++--
 client/test/searchLimit.test.ts               |  27 ++
 server/src/index.ts                           |   2 +
 server/src/routes/search.ts                   | 128 +++++++
 server/src/services/SearchService.ts          | 210 +++++++++++
 server/src/services/SearchSession.ts          | 272 ++++++++++++++
 server/src/services/searchQuery.ts            |  60 +++
 server/src/services/ytDlpRunner.ts            |  12 +-
 server/test/fakeYtDlp.ts                      |  94 +++++
 server/test/searchQuery.test.ts               | Bin 0 -> 1311 bytes
 server/test/searchRoute.test.ts               | 181 +++++++++
 server/test/searchService.test.ts             | 189 ++++++++++
 server/test/searchSession.test.ts             | 251 +++++++++++++
 server/test/ytDlpRunner.test.ts               |  30 ++
 spec/architecture.md                          |  19 +-
 22 files changed, 1991 insertions(+), 30 deletions(-)
 create mode 100644 client/src/api/searchApi.ts
 create mode 100644 client/src/searchLimit.ts
 create mode 100644 client/test/searchLimit.test.ts
 create mode 100644 server/src/routes/search.ts
 create mode 100644 server/src/services/SearchService.ts
 create mode 100644 server/src/services/SearchSession.ts
 create mode 100644 server/src/services/searchQuery.ts
 create mode 100644 server/test/fakeYtDlp.ts
 create mode 100644 server/test/searchQuery.test.ts
 create mode 100644 server/test/searchRoute.test.ts
 create mode 100644 server/test/searchService.test.ts
 create mode 100644 server/test/searchSession.test.ts

diff --git a/README.md b/README.md
index aa3c831..f9e9a51 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,7 @@ Ce projet reprend et remplace une série de scripts `.cmd` (téléchargement vid
 
 - **Parcourir une chaîne** : recherche par chaîne (URL ou `@handle`), liste de ses vidéos/streams avec filtre par mots-clés dans le titre.
 - **Ajout par URL** : ajout direct d'une ou plusieurs URLs YouTube.
+- **Recherche YouTube** : recherche globale par mots-clés, avec une limite de résultats optionnelle ; sans limite, la liste se prolonge en défilant jusqu'à la fin des résultats de YouTube.
 - **Playlists** : coller un lien de playlist (`youtube.com/playlist?list=...`) affiche toutes ses vidéos, à ajouter une par une ou d'un coup (« Tout ajouter à la file »).
 - **File d'attente** : chaque élément ajouté est configurable individuellement :
   - **Vidéo** : qualité, sous-titres (fr/en), miniature intégrée, métadonnées.
diff --git a/client/src/api/searchApi.ts b/client/src/api/searchApi.ts
new file mode 100644
index 0000000..9bb5b44
--- /dev/null
+++ b/client/src/api/searchApi.ts
@@ -0,0 +1,126 @@
+import type { VideoPage } from './videoDto';
+
+/** Recherche ouverte côté serveur : son identifiant et sa première page. */
+export interface SearchStart extends VideoPage {
+	/** Identifiant à fournir pour lire les pages suivantes et fermer la recherche. */
+	id: string;
+}
+
+/**
+ * Extrait le message d'erreur d'une réponse HTTP en échec, avec un message
+ * de repli si le corps n'est pas un JSON exploitable.
+ *
+ * @param response - Réponse HTTP dont le statut n'est pas OK.
+ * @param fallback - Message à utiliser si le corps ne fournit pas d'erreur.
+ * @returns Le message d'erreur à afficher.
+ */
+async function readErrorMessage(response: Response, fallback: string): Promise<string> {
+	try {
+		const body = (await response.json()) as { error?: string };
+		return body.error ?? fallback;
+	} catch {
+		return fallback;
+	}
+}
+
+/**
+ * Ouvre une recherche YouTube via `POST /api/search` et retourne sa première
+ * page. Le serveur garde la recherche ouverte pour servir les pages suivantes
+ * (voir {@link fetchSearchPage}) ; la fermer avec {@link closeSearch}.
+ *
+ * @param query - Mots-clés de la recherche.
+ * @param max - Nombre maximal de résultats au total, ou `null` pour aucune limite.
+ * @param limit - Taille de la première page.
+ * @returns L'identifiant de la recherche et sa première page.
+ * @throws {Error} Si la requête échoue ou si le serveur répond une erreur.
+ */
+export async function startSearch(
+	query: string,
+	max: number | null,
+	limit: number,
+): Promise<SearchStart> {
+	let response: Response;
+	try {
+		response = await fetch('/api/search', {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({ query, limit, max: max ?? undefined }),
+		});
+	} catch (error) {
+		throw new Error('Impossible de contacter le serveur.', { cause: error });
+	}
+
+	if (!response.ok) {
+		throw new Error(
+			await readErrorMessage(response, `Échec de la recherche (${response.status}).`),
+		);
+	}
+
+	try {
+		return (await response.json()) as SearchStart;
+	} catch (error) {
+		throw new Error('Réponse du serveur invalide.', { cause: error });
+	}
+}
+
+/**
+ * Lit une page d'une recherche ouverte, via `GET /api/search/:id`.
+ *
+ * @param id - Identifiant retourné par {@link startSearch}.
+ * @param offset - Position du premier résultat de la page (le `nextOffset` précédent).
+ * @param limit - Nombre de résultats demandés.
+ * @returns La page et la position de la suivante.
+ * @throws {Error} Si la requête échoue, ou si la recherche a expiré côté serveur.
+ */
+export async function fetchSearchPage(
+	id: string,
+	offset: number,
+	limit: number,
+): Promise<VideoPage> {
+	const params = new URLSearchParams({ offset: String(offset), limit: String(limit) });
+
+	let response: Response;
+	try {
+		response = await fetch(`/api/search/${encodeURIComponent(id)}?${params.toString()}`);
+	} catch (error) {
+		throw new Error('Impossible de contacter le serveur.', { cause: error });
+	}
+
+	if (!response.ok) {
+		throw new Error(
+			await readErrorMessage(response, `Échec du chargement des résultats (${response.status}).`),
+		);
+	}
+
+	try {
+		return (await response.json()) as VideoPage;
+	} catch (error) {
+		throw new Error('Réponse du serveur invalide.', { cause: error });
+	}
+}
+
+/**
+ * Ferme une recherche côté serveur (`DELETE /api/search/:id`), ce qui libère
+ * son processus yt-dlp. Une recherche déjà fermée ou expirée (`404`) n'est
+ * pas une erreur.
+ *
+ * @param id - Identifiant de la recherche à fermer.
+ * @throws {Error} Si le serveur est injoignable ou répond une erreur autre que « introuvable ».
+ */
+export async function closeSearch(id: string): Promise<void> {
+	let response: Response;
+	try {
+		response = await fetch(`/api/search/${encodeURIComponent(id)}`, {
+			method: 'DELETE',
+			keepalive: true,
+		});
+	} catch (error) {
+		throw new Error('Impossible de contacter le serveur.', { cause: error });
+	}
+
+	if (!response.ok && response.status !== 404) {
+		throw new Error(
+			await readErrorMessage(response, `Échec de la fermeture (${response.status}).`),
+		);
+	}
+}
diff --git a/client/src/api/videoDto.ts b/client/src/api/videoDto.ts
index fadc70f..d9cd5e4 100644
--- a/client/src/api/videoDto.ts
+++ b/client/src/api/videoDto.ts
@@ -13,3 +13,11 @@ export interface VideoDto {
 	/** Date de mise en ligne au format `YYYYMMDD`, si connue. */
 	uploadDate: string | null;
 }
+
+/** Une page de vidéos, avec la position de la suivante (miroir du DTO serveur). */
+export interface VideoPage {
+	/** Vidéos de la page. */
+	videos: VideoDto[];
+	/** Position à demander pour la page suivante, ou `null` s'il n'y a plus de résultats. */
+	nextOffset: number | null;
+}
diff --git a/client/src/searchLimit.ts b/client/src/searchLimit.ts
new file mode 100644
index 0000000..560f0c4
--- /dev/null
+++ b/client/src/searchLimit.ts
@@ -0,0 +1,16 @@
+/**
+ * Lit le champ « Limite » du formulaire de recherche.
+ *
+ * @param raw - Contenu brut du champ.
+ * @returns Le nombre maximal de résultats voulu (entier >= 1), ou `null`
+ * quand il n'y a pas de limite (champ vide, ou valeur qui n'est pas un
+ * entier positif) - la recherche défile alors à l'infini.
+ */
+export function parseSearchLimit(raw: string): number | null {
+	const trimmed = raw.trim();
+	if (!/^\d+$/.test(trimmed)) {
+		return null;
+	}
+	const value = Number.parseInt(trimmed, 10);
+	return value >= 1 ? value : null;
+}
diff --git a/client/src/styles/base.scss b/client/src/styles/base.scss
index 9626016..e3082ff 100644
--- a/client/src/styles/base.scss
+++ b/client/src/styles/base.scss
@@ -73,6 +73,7 @@ button {
 
 input[type='text'],
 input[type='url'],
+input[type='number'],
 select {
 	border: 1px solid var(--color-border);
 	border-radius: var(--radius);
diff --git a/client/src/views/downloadForm/DownloadForm.html b/client/src/views/downloadForm/DownloadForm.html
index 28e27cc..066fdfc 100644
--- a/client/src/views/downloadForm/DownloadForm.html
+++ b/client/src/views/downloadForm/DownloadForm.html
@@ -34,6 +34,19 @@
 
 	<hr />
 
+	<form class="download-form__form" data-form="search">
+		<label class="download-form__field">
+			Recherche YouTube
+			<input type="text" name="query" placeholder="Mots-clés" maxlength="200" required />
+		</label>
+		<label class="download-form__field download-form__field--narrow">
+			Limite (optionnel)
+			<input type="number" name="limit" min="1" max="1000" step="1" inputmode="numeric" placeholder="Illimité" />
+		</label>
+		<button type="submit">Rechercher</button>
+	</form>
+	<p class="download-form__error" data-role="search-error" hidden></p>
+
 	<form class="download-form__form" data-form="channel">
 		<label class="download-form__field">
 			Chaîne (@handle ou URL)
diff --git a/client/src/views/downloadForm/DownloadForm.scss b/client/src/views/downloadForm/DownloadForm.scss
index c93274c..50adfbc 100644
--- a/client/src/views/downloadForm/DownloadForm.scss
+++ b/client/src/views/downloadForm/DownloadForm.scss
@@ -4,6 +4,11 @@
 	gap: 0.85rem;
 	height: 100%;
 	min-height: 0;
+	// Filet de sécurité pour les écrans courts : quand les formulaires et la
+	// liste (hauteur minimale, voir __results) ne tiennent plus, la colonne
+	// défile au lieu de rogner la liste ou des champs, la page elle-même ne
+	// défilant jamais. Sans effet tant que tout tient.
+	overflow-y: auto;
 
 	// Par défaut, aucun enfant direct ne grandit/rétrécit (taille fixée à
 	// son contenu) - seul __results (règle plus bas, même spécificité
@@ -75,6 +80,12 @@
 		flex: 1 1 160px;
 	}
 
+	// Champ étroit (ex. une limite numérique) : ne prend que la place utile
+	// au lieu de se partager la ligne à parts égales.
+	&__field--narrow {
+		flex: 0 1 8rem;
+	}
+
 	&__error {
 		color: var(--color-danger-text);
 		font-size: 0.85rem;
@@ -120,6 +131,32 @@
 		flex: 1 1 0;
 		min-height: 0;
 		overflow-y: auto;
+
+		// Une liste qui contient des résultats garde au moins ~2 lignes de
+		// hauteur, même si les formulaires au-dessus prennent presque toute la
+		// place (c'est alors la colonne qui défile, voir .download-form).
+		&:not(:empty) {
+			min-height: 13rem;
+		}
+	}
+
+	// Dernier élément d'une liste à défilement infini : sa visibilité
+	// déclenche le chargement de la suite, et il affiche l'état du chargement
+	// (en cours, erreur avec « Réessayer », fin des résultats).
+	&__results-sentinel {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		gap: 0.6rem;
+		min-height: 2.4rem;
+		flex: 0 0 auto;
+		font-size: 0.8rem;
+		color: var(--color-text-muted);
+
+		button {
+			font-size: 0.8rem;
+			padding: 0.3rem 0.65rem;
+		}
 	}
 
 	&__result {
diff --git a/client/src/views/downloadForm/DownloadForm.ts b/client/src/views/downloadForm/DownloadForm.ts
index a4f6a48..cf77d64 100644
--- a/client/src/views/downloadForm/DownloadForm.ts
+++ b/client/src/views/downloadForm/DownloadForm.ts
@@ -1,9 +1,11 @@
 import { type ChannelSection, searchChannel } from '../../api/channelApi';
 import { type PlaylistDto, fetchPlaylist } from '../../api/playlistApi';
 import { type EnqueueMode, enqueueItem } from '../../api/queueApi';
-import type { VideoDto } from '../../api/videoDto';
+import { closeSearch, fetchSearchPage, startSearch } from '../../api/searchApi';
+import type { VideoDto, VideoPage } from '../../api/videoDto';
 import { formatDuration, formatUploadDate } from '../../format';
 import { isPlaylistUrl } from '../../playlistUrl';
+import { parseSearchLimit } from '../../searchLimit';
 import downloadFormTemplate from './DownloadForm.html';
 import './DownloadForm.scss';
 
@@ -21,7 +23,7 @@ interface ResultRow {
 	readonly button: HTMLButtonElement;
 }
 
-/** Options d'affichage d'une liste de résultats. */
+/** Options d'affichage d'une liste de résultats complète. */
 interface ShowVideosOptions {
 	/** Message de statut affiché au-dessus de la liste (ex. « 12 résultat(s). »). */
 	readonly status: string;
@@ -29,18 +31,60 @@ interface ShowVideosOptions {
 	readonly allowAddAll: boolean;
 }
 
-/** Zone de résultats partagée entre la recherche de chaîne et le chargement d'une playlist. */
+/** Options d'affichage d'une liste paginée en défilement infini. */
+interface ShowPagedOptions {
+	/** Première page, déjà chargée. */
+	readonly firstPage: VideoPage;
+	/** Charge la page qui commence à la position `offset` (le `nextOffset` de la page précédente). */
+	readonly loadMore: (offset: number) => Promise<VideoPage>;
+	/** Message de statut pour `count` vidéos affichées ; `hasMore` indique qu'il en reste à charger. */
+	readonly formatStatus: (count: number, hasMore: boolean) => string;
+	/**
+	 * Appelé une seule fois quand la liste est remplacée ou vidée alors qu'il
+	 * restait des pages à charger (ex. pour libérer la recherche côté
+	 * serveur). Jamais appelé si tout tenait dans la première page.
+	 */
+	readonly onClose: () => void;
+}
+
+/** Défilement infini de la liste actuellement affichée. */
+interface Pager {
+	/** Options fournies par l'appelant. */
+	readonly options: ShowPagedOptions;
+	/** Dernier élément de la liste : sa visibilité déclenche le chargement de la suite. */
+	readonly sentinel: HTMLLIElement;
+	/** Observateur de visibilité de {@link Pager.sentinel} dans la zone de défilement. */
+	readonly observer: IntersectionObserver;
+	/** Position de la prochaine page, ou `null` quand tout est chargé. */
+	nextOffset: number | null;
+	/** Une page est en cours de chargement. */
+	loading: boolean;
+}
+
+/** État affiché par l'élément de fin de liste d'un défilement infini. */
+type SentinelState =
+	| { readonly kind: 'idle' }
+	| { readonly kind: 'loading' }
+	| { readonly kind: 'end' }
+	| { readonly kind: 'error'; readonly message: string; readonly onRetry: () => void };
+
+/** Zone de résultats partagée entre la recherche de chaîne, de playlist et globale. */
 interface ResultsView {
 	/** Vide la liste et affiche un message d'attente. */
 	showLoading: (message: string) => void;
 	/** Vide et masque toute la zone de résultats. */
 	clear: () => void;
-	/** Affiche les vidéos fournies, avec leur message de statut. */
+	/** Affiche les vidéos fournies d'un coup, avec leur message de statut. */
 	showVideos: (videos: readonly VideoDto[], options: ShowVideosOptions) => void;
+	/** Affiche une première page, puis charge la suite au fil du défilement. */
+	showPaged: (options: ShowPagedOptions) => void;
 }
 
 const ADD_ALL_LABEL = 'Tout ajouter à la file';
 
+/** Nombre de résultats demandés par page pour une recherche sans limite. */
+const SEARCH_PAGE_SIZE = 20;
+
 /**
  * Récupère un élément du gabarit, en échouant franchement s'il manque : le
  * gabarit est statique, son absence est une erreur de programmation, pas un
@@ -200,10 +244,44 @@ function renderResultItem(video: VideoDto): {
 	return { element, button };
 }
 
+/**
+ * Affiche l'état d'un élément de fin de liste (chargement en cours, erreur
+ * avec « Réessayer », fin des résultats, ou rien).
+ *
+ * @param sentinel - Élément de fin de liste.
+ * @param state - État à afficher.
+ */
+function renderSentinel(sentinel: HTMLElement, state: SentinelState): void {
+	sentinel.replaceChildren();
+
+	switch (state.kind) {
+		case 'idle':
+			return;
+		case 'loading':
+			sentinel.textContent = 'Chargement…';
+			return;
+		case 'end':
+			sentinel.textContent = 'Fin des résultats.';
+			return;
+		case 'error': {
+			const message = document.createElement('span');
+			message.textContent = state.message;
+			const retry = document.createElement('button');
+			retry.type = 'button';
+			retry.className = 'secondary';
+			retry.textContent = 'Réessayer';
+			retry.addEventListener('click', state.onRetry);
+			sentinel.append(message, retry);
+			return;
+		}
+	}
+}
+
 /**
  * Câble la zone de résultats partagée : liste de vidéos avec un bouton
- * « Ajouter » par ligne, et, quand la liste le permet (playlist), un bouton
- * « Tout ajouter à la file ».
+ * « Ajouter » par ligne, un bouton « Tout ajouter à la file » quand la liste
+ * le permet (playlist), et un chargement de la suite au fil du défilement
+ * quand la liste est paginée (recherche globale sans limite).
  *
  * @param root - Racine du formulaire monté.
  * @param callbacks - Rappels du formulaire.
@@ -217,13 +295,29 @@ function createResultsView(root: HTMLElement, callbacks: DownloadFormCallbacks):
 	const list = requireElement<HTMLElement>(root, '[data-role="results"]');
 
 	let rows: ResultRow[] = [];
-	// Incrémenté à chaque remplacement de la liste : une opération d'ajout
-	// encore en cours sur l'ancienne liste ne doit plus toucher à l'affichage
-	// (bouton, message d'erreur) de la nouvelle.
+	let pager: Pager | null = null;
+	// Incrémenté à chaque remplacement de la liste : une opération encore en
+	// cours sur l'ancienne liste (ajout groupé, chargement d'une page) ne doit
+	// plus toucher à l'affichage (bouton, message, lignes) de la nouvelle.
 	let generation = 0;
 
+	const logUnexpected = (error: unknown): void => {
+		console.error('Erreur inattendue dans la liste de résultats', error);
+	};
+
+	const closePager = (): void => {
+		if (!pager) {
+			return;
+		}
+		const closing = pager;
+		pager = null;
+		closing.observer.disconnect();
+		closing.options.onClose();
+	};
+
 	const clear = (): void => {
 		generation += 1;
+		closePager();
 		rows = [];
 		list.replaceChildren();
 		addAllButton.hidden = true;
@@ -308,14 +402,10 @@ function createResultsView(root: HTMLElement, callbacks: DownloadFormCallbacks):
 		});
 	});
 
-	const showVideos = (videos: readonly VideoDto[], options: ShowVideosOptions): void => {
-		clear();
-		setMessage(statusEl, options.status);
-		header.hidden = false;
-		addAllButton.hidden = !options.allowAddAll;
-		addAllButton.disabled = false;
-		addAllButton.textContent = ADD_ALL_LABEL;
-
+	/**
+	 * Ajoute des lignes en fin de liste (avant l'élément de fin s'il y en a un).
+	 */
+	const appendRows = (videos: readonly VideoDto[]): void => {
 		const fragment = document.createDocumentFragment();
 		for (const video of videos) {
 			const { element, button } = renderResultItem(video);
@@ -326,10 +416,118 @@ function createResultsView(root: HTMLElement, callbacks: DownloadFormCallbacks):
 			rows.push(row);
 			fragment.append(element);
 		}
-		list.replaceChildren(fragment);
+
+		if (pager) {
+			pager.sentinel.before(fragment);
+		} else {
+			list.append(fragment);
+		}
 	};
 
-	return { showLoading, clear, showVideos };
+	const showVideos = (videos: readonly VideoDto[], options: ShowVideosOptions): void => {
+		clear();
+		setMessage(statusEl, options.status);
+		header.hidden = false;
+		addAllButton.hidden = !options.allowAddAll;
+		addAllButton.disabled = false;
+		addAllButton.textContent = ADD_ALL_LABEL;
+		appendRows(videos);
+	};
+
+	const refreshPagedStatus = (): void => {
+		if (pager) {
+			setMessage(statusEl, pager.options.formatStatus(rows.length, pager.nextOffset !== null));
+		}
+	};
+
+	const loadNextPage = async (): Promise<void> => {
+		const current = pager;
+		if (!current || current.loading || current.nextOffset === null) {
+			return;
+		}
+
+		const startedIn = generation;
+		current.loading = true;
+		renderSentinel(current.sentinel, { kind: 'loading' });
+
+		let page: VideoPage;
+		try {
+			page = await current.options.loadMore(current.nextOffset);
+		} catch (error) {
+			if (startedIn === generation) {
+				current.loading = false;
+				renderSentinel(current.sentinel, {
+					kind: 'error',
+					message: describeError(error, 'Échec du chargement.'),
+					onRetry: () => {
+						loadNextPage().catch(logUnexpected);
+					},
+				});
+			}
+			return;
+		}
+		if (startedIn !== generation) {
+			return;
+		}
+
+		appendRows(page.videos);
+		current.nextOffset = page.nextOffset;
+		current.loading = false;
+		refreshPagedStatus();
+
+		if (current.nextOffset === null) {
+			renderSentinel(current.sentinel, { kind: 'end' });
+			current.observer.disconnect();
+			return;
+		}
+		renderSentinel(current.sentinel, { kind: 'idle' });
+		// Si la fin de liste est encore visible (la page n'a pas suffi à remplir
+		// la zone), l'observateur ne signalerait plus rien : on le réarme.
+		current.observer.unobserve(current.sentinel);
+		current.observer.observe(current.sentinel);
+	};
+
+	const showPaged = (options: ShowPagedOptions): void => {
+		if (options.firstPage.nextOffset === null) {
+			// Tout tient dans la première page : rien à paginer ni à libérer.
+			showVideos(options.firstPage.videos, {
+				status: options.formatStatus(options.firstPage.videos.length, false),
+				allowAddAll: false,
+			});
+			return;
+		}
+
+		clear();
+		header.hidden = false;
+		addAllButton.hidden = true;
+
+		const sentinel = document.createElement('li');
+		sentinel.className = 'download-form__results-sentinel';
+		list.append(sentinel);
+
+		const observer = new IntersectionObserver(
+			(observed) => {
+				if (observed.some((entry) => entry.isIntersecting)) {
+					loadNextPage().catch(logUnexpected);
+				}
+			},
+			// Les résultats se chargent un peu avant d'atteindre la fin de liste.
+			{ root: list, rootMargin: '0px 0px 300px 0px' },
+		);
+
+		pager = {
+			options,
+			sentinel,
+			observer,
+			nextOffset: options.firstPage.nextOffset,
+			loading: false,
+		};
+		appendRows(options.firstPage.videos);
+		refreshPagedStatus();
+		observer.observe(sentinel);
+	};
+
+	return { showLoading, clear, showVideos, showPaged };
 }
 
 /**
@@ -345,6 +543,22 @@ function describePlaylist(playlist: PlaylistDto): string {
 		: `${name} : ${playlist.videos.length} vidéo(s).`;
 }
 
+/**
+ * Décrit l'avancement d'une recherche pour la ligne de statut de la liste.
+ *
+ * @param count - Nombre de vidéos affichées.
+ * @param hasMore - `true` s'il reste des résultats à charger en défilant.
+ * @returns Un texte du type « 40 résultat(s) - d'autres se chargent en défilant. ».
+ */
+function describeSearchProgress(count: number, hasMore: boolean): string {
+	if (count === 0) {
+		return 'Aucun résultat.';
+	}
+	return hasMore
+		? `${count} résultat(s) — d'autres se chargent en défilant.`
+		: `${count} résultat(s).`;
+}
+
 /**
  * Charge une playlist et affiche ses vidéos dans la zone de résultats.
  *
@@ -426,6 +640,93 @@ function wireUrlForm(
 	});
 }
 
+/**
+ * Câble le formulaire de recherche YouTube globale. Avec une limite, les
+ * résultats arrivent d'un coup ; sans limite, la liste se prolonge au fil du
+ * défilement jusqu'à la fin des résultats de YouTube.
+ *
+ * @param root - Racine du formulaire monté.
+ * @param results - Zone de résultats partagée.
+ */
+function wireSearchForm(root: HTMLElement, results: ResultsView): void {
+	const form = root.querySelector<HTMLFormElement>('form[data-form="search"]');
+	const errorEl = root.querySelector<HTMLElement>('[data-role="search-error"]');
+	if (!form) {
+		return;
+	}
+
+	// Recherche gardée ouverte côté serveur pour ses pages suivantes : libérée
+	// quand la liste est remplacée (voir onClose), ou ici quand la page se
+	// ferme ou se recharge - sans quoi son yt-dlp resterait suspendu jusqu'à
+	// l'expiration côté serveur.
+	let openSearchId: string | null = null;
+	window.addEventListener('pagehide', () => {
+		if (openSearchId) {
+			closeSearch(openSearchId).catch(() => {
+				// Meilleur effort : la page se ferme, personne pour lire une erreur.
+			});
+		}
+	});
+
+	const handleSubmit = async (event: SubmitEvent): Promise<void> => {
+		event.preventDefault();
+		const formData = new FormData(form);
+		const query = String(formData.get('query') ?? '').trim();
+		const limit = parseSearchLimit(String(formData.get('limit') ?? ''));
+		if (!query) {
+			return;
+		}
+
+		setMessage(errorEl, null);
+		results.showLoading('Recherche en cours...');
+		const submitButton = form.querySelector<HTMLButtonElement>('button[type="submit"]');
+		if (submitButton) {
+			submitButton.disabled = true;
+		}
+
+		try {
+			if (limit !== null) {
+				// Limite fixée : tous les résultats en une fois, pas de défilement infini.
+				const search = await startSearch(query, limit, limit);
+				results.showVideos(search.videos, {
+					status: describeSearchProgress(search.videos.length, false),
+					allowAddAll: false,
+				});
+			} else {
+				const search = await startSearch(query, null, SEARCH_PAGE_SIZE);
+				if (search.nextOffset !== null) {
+					// Sinon le serveur a déjà refermé la recherche : rien à libérer.
+					openSearchId = search.id;
+				}
+				results.showPaged({
+					firstPage: search,
+					loadMore: (offset) => fetchSearchPage(search.id, offset, SEARCH_PAGE_SIZE),
+					formatStatus: describeSearchProgress,
+					onClose: () => {
+						openSearchId = null;
+						closeSearch(search.id).catch((error: unknown) => {
+							console.warn('Échec de la fermeture de la recherche', error);
+						});
+					},
+				});
+			}
+		} catch (error) {
+			results.clear();
+			setMessage(errorEl, describeError(error, 'Échec de la recherche.'));
+		} finally {
+			if (submitButton) {
+				submitButton.disabled = false;
+			}
+		}
+	};
+
+	form.addEventListener('submit', (event) => {
+		handleSubmit(event).catch((error: unknown) => {
+			console.error('Erreur inattendue lors de la recherche YouTube', error);
+		});
+	});
+}
+
 /**
  * Câble le formulaire de recherche de chaîne.
  *
@@ -480,8 +781,8 @@ function wireChannelForm(root: HTMLElement, results: ResultsView): void {
 }
 
 /**
- * Monte le formulaire d'ajout (URL directe ou de playlist, et recherche de
- * chaîne) dans l'élément racine fourni.
+ * Monte le formulaire d'ajout (URL directe ou de playlist, recherche YouTube
+ * globale, et recherche de chaîne) dans l'élément racine fourni.
  *
  * @param root - Élément DOM dans lequel injecter le formulaire.
  * @param callbacks - Rappels invoqués sur les actions du formulaire.
@@ -491,5 +792,6 @@ export function mountDownloadForm(root: HTMLElement, callbacks: DownloadFormCall
 	const results = createResultsView(root, callbacks);
 	wireModeToggle(root);
 	wireUrlForm(root, results, callbacks);
+	wireSearchForm(root, results);
 	wireChannelForm(root, results);
 }
diff --git a/client/test/searchLimit.test.ts b/client/test/searchLimit.test.ts
new file mode 100644
index 0000000..6c4f879
--- /dev/null
+++ b/client/test/searchLimit.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { parseSearchLimit } from '../src/searchLimit';
+
+describe('parseSearchLimit', () => {
+	it.each([
+		['25', 25],
+		['1', 1],
+		['  40  ', 40],
+		['1000', 1000],
+		['007', 7],
+	])('lit %j comme une limite de %i résultats', (raw, expected) => {
+		expect(parseSearchLimit(raw)).toBe(expected);
+	});
+
+	it.each([
+		['un champ vide', ''],
+		['des espaces', '   '],
+		['zéro', '0'],
+		['un nombre négatif', '-5'],
+		['un nombre décimal', '2.5'],
+		['du texte', 'beaucoup'],
+		['un nombre suivi de texte', '25 vidéos'],
+		['une notation exponentielle', '1e3'],
+	])('ne voit aucune limite dans %s', (_label, raw) => {
+		expect(parseSearchLimit(raw)).toBeNull();
+	});
+});
diff --git a/server/src/index.ts b/server/src/index.ts
index 76ebebb..7b8ce8c 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -5,6 +5,7 @@ import { channelRoutes } from './routes/channel.js';
 import { healthRoutes } from './routes/health.js';
 import { playlistRoutes } from './routes/playlist.js';
 import { createQueueRoutes } from './routes/queue.js';
+import { searchRoutes } from './routes/search.js';
 
 /**
  * Construit et configure l'instance Fastify de l'application : fichiers
@@ -24,6 +25,7 @@ async function buildServer(config: ServerConfig): Promise<FastifyInstance> {
 		await app.register(healthRoutes);
 		await app.register(channelRoutes);
 		await app.register(playlistRoutes);
+		await app.register(searchRoutes);
 		await app.register(createQueueRoutes(config));
 	} catch (error) {
 		app.log.error({ err: error }, "Échec de l'enregistrement des plugins Fastify");
diff --git a/server/src/routes/search.ts b/server/src/routes/search.ts
new file mode 100644
index 0000000..158df4b
--- /dev/null
+++ b/server/src/routes/search.ts
@@ -0,0 +1,128 @@
+import type { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest } from 'fastify';
+import { MAX_SEARCH_RESULTS, SearchService } from '../services/SearchService.js';
+import { InvalidSearchQueryError, MAX_QUERY_LENGTH } from '../services/searchQuery.js';
+
+/** Taille de page par défaut. */
+const DEFAULT_PAGE_SIZE = 20;
+
+/** Corps de requête accepté par `POST /api/search`. */
+interface StartSearchBody {
+	/** Requête de recherche YouTube. */
+	query: string;
+	/** Nombre maximal de résultats au total ; absent = sans limite (jusqu'à la fin des résultats de YouTube). */
+	max?: number;
+	/** Taille de la première page. */
+	limit?: number;
+}
+
+/** Paramètres d'URL des routes `/api/search/:id`. */
+interface SearchParams {
+	/** Identifiant de la recherche, retourné par `POST /api/search`. */
+	id: string;
+}
+
+/** Paramètres de requête acceptés par `GET /api/search/:id`. */
+interface SearchPageQuerystring {
+	/** Position du premier résultat de la page ; 0 par défaut. */
+	offset?: number;
+	/** Nombre de résultats demandés. */
+	limit?: number;
+}
+
+const startSearchBodySchema = {
+	type: 'object',
+	required: ['query'],
+	properties: {
+		query: { type: 'string', minLength: 1, maxLength: MAX_QUERY_LENGTH },
+		max: { type: 'integer', minimum: 1, maximum: MAX_SEARCH_RESULTS },
+		limit: { type: 'integer', minimum: 1, maximum: MAX_SEARCH_RESULTS },
+	},
+} as const;
+
+const searchParamsSchema = {
+	type: 'object',
+	required: ['id'],
+	properties: {
+		id: { type: 'string', minLength: 1, maxLength: 64 },
+	},
+} as const;
+
+const searchPageQuerystringSchema = {
+	type: 'object',
+	properties: {
+		offset: { type: 'integer', minimum: 0 },
+		limit: { type: 'integer', minimum: 1, maximum: MAX_SEARCH_RESULTS },
+	},
+} as const;
+
+const NOT_FOUND_MESSAGE = 'Recherche introuvable ou expirée : relancez-la.';
+const FAILURE_MESSAGE = 'Échec de la recherche YouTube (yt-dlp).';
+
+/**
+ * Plugin Fastify exposant la recherche YouTube globale, paginée :
+ * `POST /api/search` ouvre une recherche et retourne sa première page,
+ * `GET /api/search/:id` retourne les pages suivantes, et `DELETE
+ * /api/search/:id` libère la recherche.
+ *
+ * @param app - Instance Fastify sur laquelle enregistrer les routes.
+ */
+export const searchRoutes: FastifyPluginAsync = async (app: FastifyInstance): Promise<void> => {
+	const searchService = new SearchService(app.log);
+
+	app.addHook('onClose', async () => {
+		searchService.closeAll();
+	});
+
+	app.post<{ Body: StartSearchBody }>(
+		'/api/search',
+		{ schema: { body: startSearchBodySchema } },
+		async (request: FastifyRequest<{ Body: StartSearchBody }>, reply: FastifyReply) => {
+			const { query, max = MAX_SEARCH_RESULTS, limit = DEFAULT_PAGE_SIZE } = request.body;
+
+			try {
+				const { id, page } = await searchService.start(query, max, limit);
+				return reply.status(201).send({ id, ...page });
+			} catch (error) {
+				if (error instanceof InvalidSearchQueryError) {
+					return reply.status(400).send({ error: error.message });
+				}
+				// La requête est validée avant tout appel à yt-dlp : toute autre
+				// erreur vient forcément du parcours (binaire absent, code de
+				// sortie non nul...), déjà journalisée par la session.
+				return reply.status(502).send({ error: FAILURE_MESSAGE });
+			}
+		},
+	);
+
+	app.get<{ Params: SearchParams; Querystring: SearchPageQuerystring }>(
+		'/api/search/:id',
+		{ schema: { params: searchParamsSchema, querystring: searchPageQuerystringSchema } },
+		async (
+			request: FastifyRequest<{ Params: SearchParams; Querystring: SearchPageQuerystring }>,
+			reply: FastifyReply,
+		) => {
+			const { offset = 0, limit = DEFAULT_PAGE_SIZE } = request.query;
+
+			try {
+				const page = await searchService.page(request.params.id, offset, limit);
+				if (!page) {
+					return reply.status(404).send({ error: NOT_FOUND_MESSAGE });
+				}
+				return page;
+			} catch {
+				return reply.status(502).send({ error: FAILURE_MESSAGE });
+			}
+		},
+	);
+
+	app.delete<{ Params: SearchParams }>(
+		'/api/search/:id',
+		{ schema: { params: searchParamsSchema } },
+		async (request: FastifyRequest<{ Params: SearchParams }>, reply: FastifyReply) => {
+			if (!searchService.dispose(request.params.id)) {
+				return reply.status(404).send({ error: NOT_FOUND_MESSAGE });
+			}
+			return reply.status(204).send();
+		},
+	);
+};
diff --git a/server/src/services/SearchService.ts b/server/src/services/SearchService.ts
new file mode 100644
index 0000000..3549392
--- /dev/null
+++ b/server/src/services/SearchService.ts
@@ -0,0 +1,210 @@
+import type { FastifyBaseLogger } from 'fastify';
+import { SEARCH_DEPTH, type SearchPage, SearchSession } from './SearchSession.js';
+import { assertValidSearchQuery } from './searchQuery.js';
+
+/** Nombre maximal de résultats qu'une recherche peut renvoyer (la profondeur demandée à yt-dlp). */
+export const MAX_SEARCH_RESULTS = SEARCH_DEPTH;
+
+/** Réglages du service de recherche (surchargeables en test). */
+export interface SearchServiceOptions {
+	/** Nombre maximal de recherches simultanées ; la moins récemment utilisée est fermée au-delà. */
+	readonly maxSessions: number;
+	/** Durée d'inactivité (ms) au-delà de laquelle une recherche est fermée. */
+	readonly idleTtlMs: number;
+	/** Durée de vie maximale (ms) d'une recherche, active ou non. */
+	readonly maxLifetimeMs: number;
+	/** Intervalle (ms) du balayage des recherches expirées. */
+	readonly sweepIntervalMs: number;
+	/** Nombre de résultats d'avance sur la demande au-delà duquel yt-dlp est suspendu. */
+	readonly readAhead: number;
+}
+
+const DEFAULT_OPTIONS: SearchServiceOptions = {
+	maxSessions: 4,
+	idleTtlMs: 10 * 60_000,
+	maxLifetimeMs: 30 * 60_000,
+	sweepIntervalMs: 30_000,
+	readAhead: 20,
+};
+
+/**
+ * Service de recherche YouTube globale : ouvre des recherches (un yt-dlp
+ * chacune, voir {@link SearchSession}) et les sert page par page.
+ *
+ * Chaque recherche ouverte garde un processus yt-dlp vivant (suspendu tant
+ * que l'utilisateur ne défile pas), d'où un nombre de sessions borné, une
+ * expiration par inactivité, et une fermeture dès que la dernière page a été
+ * servie.
+ */
+export class SearchService {
+	private readonly logger: FastifyBaseLogger;
+	private readonly options: SearchServiceOptions;
+	private readonly sessions = new Map<string, SearchSession>();
+	private sweeper: NodeJS.Timeout | null = null;
+
+	/**
+	 * @param logger - Logger utilisé pour tracer les recherches.
+	 * @param options - Réglages ; les valeurs par défaut conviennent hors tests.
+	 */
+	public constructor(logger: FastifyBaseLogger, options: Partial<SearchServiceOptions> = {}) {
+		this.logger = logger;
+		this.options = { ...DEFAULT_OPTIONS, ...options };
+	}
+
+	/**
+	 * Ouvre une recherche et retourne sa première page.
+	 *
+	 * @param query - Requête de recherche (validée ici).
+	 * @param max - Nombre maximal de résultats ; le parcours s'arrête dès qu'il est atteint.
+	 * @param limit - Taille de la première page.
+	 * @returns L'identifiant de la recherche et sa première page.
+	 * @throws {InvalidSearchQueryError} Si la requête est vide, trop longue ou invalide.
+	 * @throws {Error} Si yt-dlp échoue avant de produire le moindre résultat.
+	 */
+	public async start(
+		query: string,
+		max: number,
+		limit: number,
+	): Promise<{ id: string; page: SearchPage }> {
+		const validQuery = assertValidSearchQuery(query);
+		this.evictIfFull();
+
+		const session = new SearchSession(this.logger, {
+			query: validQuery,
+			max,
+			readAhead: this.options.readAhead,
+			lifetimeMs: this.options.maxLifetimeMs,
+		});
+		this.sessions.set(session.id, session);
+		this.ensureSweeper();
+
+		try {
+			const page = await session.page(0, limit);
+			this.closeIfComplete(session, page);
+			return { id: session.id, page };
+		} catch (error) {
+			this.close(session.id, 'échec de la première page');
+			throw error;
+		}
+	}
+
+	/**
+	 * Retourne une page d'une recherche ouverte.
+	 *
+	 * @param id - Identifiant retourné par {@link start}.
+	 * @param offset - Position du premier résultat de la page.
+	 * @param limit - Nombre de résultats demandés.
+	 * @returns La page, ou `null` si la recherche est inconnue ou expirée.
+	 * @throws {Error} Si yt-dlp a échoué sans produire de résultat.
+	 */
+	public async page(id: string, offset: number, limit: number): Promise<SearchPage | null> {
+		const session = this.sessions.get(id);
+		if (!session) {
+			return null;
+		}
+
+		try {
+			const page = await session.page(offset, limit);
+			this.closeIfComplete(session, page);
+			return page;
+		} catch (error) {
+			this.close(id, 'échec de la page');
+			throw error;
+		}
+	}
+
+	/**
+	 * Ferme une recherche (tue son yt-dlp).
+	 *
+	 * @param id - Identifiant de la recherche.
+	 * @returns `true` si la recherche existait, `false` sinon.
+	 */
+	public dispose(id: string): boolean {
+		return this.close(id, 'fermée par le client');
+	}
+
+	/** Ferme toutes les recherches et arrête le balayage (arrêt du serveur). */
+	public closeAll(): void {
+		for (const id of [...this.sessions.keys()]) {
+			this.close(id, 'arrêt du serveur');
+		}
+		this.stopSweeperIfIdle();
+	}
+
+	/**
+	 * Ferme une recherche dont la dernière page vient d'être servie : plus
+	 * rien ne pourra lui être demandé, inutile de garder son processus.
+	 *
+	 * @param session - Session concernée.
+	 * @param page - Page qui vient d'être servie.
+	 */
+	private closeIfComplete(session: SearchSession, page: SearchPage): void {
+		if (page.nextOffset === null) {
+			this.close(session.id, 'dernière page servie');
+		}
+	}
+
+	/**
+	 * @param id - Identifiant de la recherche à fermer.
+	 * @param reason - Raison de la fermeture, pour les logs.
+	 * @returns `true` si la recherche existait.
+	 */
+	private close(id: string, reason: string): boolean {
+		const session = this.sessions.get(id);
+		if (!session) {
+			return false;
+		}
+		this.sessions.delete(id);
+		session.dispose(reason);
+		this.stopSweeperIfIdle();
+		return true;
+	}
+
+	/** Ferme la recherche la moins récemment utilisée si la limite de sessions est atteinte. */
+	private evictIfFull(): void {
+		while (this.sessions.size >= this.options.maxSessions) {
+			let oldest: SearchSession | null = null;
+			for (const session of this.sessions.values()) {
+				if (!oldest || session.lastAccess < oldest.lastAccess) {
+					oldest = session;
+				}
+			}
+			if (!oldest) {
+				return;
+			}
+			this.close(oldest.id, 'limite de recherches simultanées atteinte');
+		}
+	}
+
+	/** Ferme les recherches inactives ou trop anciennes. */
+	private sweep(): void {
+		const now = Date.now();
+		for (const session of [...this.sessions.values()]) {
+			if (now - session.lastAccess > this.options.idleTtlMs) {
+				this.close(session.id, 'inactivité');
+			} else if (now - session.createdAt > this.options.maxLifetimeMs) {
+				this.close(session.id, 'durée de vie maximale atteinte');
+			}
+		}
+	}
+
+	/** Démarre le balayage périodique s'il ne tourne pas déjà. */
+	private ensureSweeper(): void {
+		if (this.sweeper) {
+			return;
+		}
+		this.sweeper = setInterval(() => {
+			this.sweep();
+		}, this.options.sweepIntervalMs);
+		// Le balayage ne doit jamais empêcher le processus de se terminer.
+		this.sweeper.unref();
+	}
+
+	/** Arrête le balayage quand plus aucune recherche n'est ouverte. */
+	private stopSweeperIfIdle(): void {
+		if (this.sweeper && this.sessions.size === 0) {
+			clearInterval(this.sweeper);
+			this.sweeper = null;
+		}
+	}
+}
diff --git a/server/src/services/SearchSession.ts b/server/src/services/SearchSession.ts
new file mode 100644
index 0000000..204c9ce
--- /dev/null
+++ b/server/src/services/SearchSession.ts
@@ -0,0 +1,272 @@
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import type { FastifyBaseLogger } from 'fastify';
+import { type VideoSummary, summarizeEntry } from './videoSummary.js';
+import { runYtDlp } from './ytDlpRunner.js';
+
+/**
+ * Profondeur demandée à yt-dlp (`ytsearchN:`). YouTube s'arrête de lui-même
+ * vers ~590 résultats même quand on en demande 1000 (mesuré) : ce n'est donc
+ * qu'un plafond de sécurité, jamais atteint en pratique.
+ */
+export const SEARCH_DEPTH = 1000;
+
+/** Une page de résultats d'une recherche. */
+export interface SearchPage {
+	/** Vidéos de la page, dans l'ordre du parcours (sans doublon). */
+	readonly videos: VideoSummary[];
+	/** Position à demander pour la page suivante, ou `null` s'il n'y a plus de résultats. */
+	readonly nextOffset: number | null;
+}
+
+/** Réglages d'une session de recherche. */
+export interface SearchSessionOptions {
+	/** Requête déjà validée (voir `assertValidSearchQuery`). */
+	readonly query: string;
+	/** Nombre maximal de résultats (sans doublon) : le parcours s'arrête dès qu'il est atteint. */
+	readonly max: number;
+	/** Nombre de résultats d'avance sur la demande au-delà duquel on suspend yt-dlp. */
+	readonly readAhead: number;
+	/** Durée de vie maximale du processus yt-dlp, en millisecondes. */
+	readonly lifetimeMs: number;
+}
+
+/**
+ * Un parcours de recherche YouTube, servi page par page.
+ *
+ * Pourquoi une session plutôt qu'un appel yt-dlp par page : l'ordre des
+ * résultats de YouTube n'est pas stable d'un appel à l'autre, même pour une
+ * requête identique (mesuré : 5 résultats sur 20 à la même position entre
+ * deux appels identiques). Paginer en relançant la recherche donnerait des
+ * doublons et des trous. Ici un seul yt-dlp parcourt la recherche
+ * (`--lazy-playlist` : il émet ses résultats au fil des pages YouTube au lieu
+ * d'attendre la fin) et les pages sont servies depuis son tampon.
+ *
+ * Le parcours n'avance qu'à la demande : dès que le tampon a
+ * {@link SearchSessionOptions.readAhead} résultats d'avance sur ce qui a été
+ * demandé, la lecture de stdout est suspendue. Le tube se remplit alors et
+ * yt-dlp bloque sur son écriture (mesuré : plus aucune ligne pendant 10 s de
+ * pause), ce qui évite d'aspirer ~590 résultats - et ~30 requêtes vers
+ * YouTube - quand l'utilisateur ne défile pas.
+ */
+export class SearchSession {
+	/** Identifiant opaque de la session. */
+	public readonly id = randomUUID();
+	/** Date de création de la session (ms depuis l'epoch). */
+	public readonly createdAt = Date.now();
+
+	private readonly logger: FastifyBaseLogger;
+	private readonly options: SearchSessionOptions;
+	private readonly entries: VideoSummary[] = [];
+	private readonly seenIds = new Set<string>();
+	private readonly waiters = new Set<() => void>();
+	private readonly abortController = new AbortController();
+	private child: ChildProcessWithoutNullStreams | null = null;
+	private suspended = false;
+	private finished = false;
+	private disposed = false;
+	private failure: unknown = null;
+	private wantedUpTo = 0;
+	private lastAccessAt = Date.now();
+
+	/**
+	 * Lance immédiatement le parcours yt-dlp.
+	 *
+	 * @param logger - Logger utilisé pour tracer le cycle de vie de la session.
+	 * @param options - Réglages de la session.
+	 */
+	public constructor(logger: FastifyBaseLogger, options: SearchSessionOptions) {
+		this.logger = logger;
+		this.options = options;
+
+		this.logger.info(
+			{ sessionId: this.id, query: options.query, max: options.max },
+			'Recherche : session ouverte',
+		);
+
+		runYtDlp(
+			[
+				'--flat-playlist',
+				'--lazy-playlist',
+				'-j',
+				'--',
+				`ytsearch${SEARCH_DEPTH}:${options.query}`,
+			],
+			{
+				timeoutMs: options.lifetimeMs,
+				signal: this.abortController.signal,
+				onSpawn: (child) => {
+					this.child = child;
+				},
+				onStdoutLine: (line) => {
+					this.ingest(line);
+				},
+			},
+		)
+			.catch((error: unknown) => {
+				// Une annulation de notre part (plafond atteint, session fermée)
+				// n'est pas un échec.
+				if (this.abortController.signal.aborted) {
+					return;
+				}
+				this.failure = error;
+				this.logger.error(
+					{ err: error, sessionId: this.id },
+					'Recherche : échec du parcours yt-dlp',
+				);
+			})
+			.finally(() => {
+				this.finished = true;
+				this.notify();
+			});
+	}
+
+	/** Date du dernier accès à la session (ms depuis l'epoch), pour l'expiration par inactivité. */
+	public get lastAccess(): number {
+		return this.lastAccessAt;
+	}
+
+	/**
+	 * Retourne une page de résultats, en attendant au besoin que le parcours
+	 * ait produit assez de résultats (ou soit terminé).
+	 *
+	 * @param offset - Position du premier résultat de la page.
+	 * @param limit - Nombre de résultats demandés.
+	 * @returns La page, et la position de la suivante (`null` en fin de résultats).
+	 * @throws {Error} Si le parcours a échoué avant de produire le moindre résultat.
+	 */
+	public async page(offset: number, limit: number): Promise<SearchPage> {
+		this.lastAccessAt = Date.now();
+		this.wantedUpTo = Math.max(this.wantedUpTo, offset + limit);
+		this.resumeReading();
+
+		try {
+			await this.waitUntil(() => this.entries.length >= offset + limit || this.finished);
+		} catch (error) {
+			this.logger.error(
+				{ err: error, sessionId: this.id, offset, limit },
+				'Recherche : attente de résultats interrompue',
+			);
+			throw error;
+		}
+		this.lastAccessAt = Date.now();
+
+		if (this.entries.length === 0 && this.failure !== null) {
+			throw this.failure;
+		}
+
+		const videos = this.entries.slice(offset, offset + limit);
+		const end = offset + videos.length;
+		const hasMore = end < this.entries.length || !this.finished;
+
+		this.logger.info(
+			{ sessionId: this.id, offset, limit, served: videos.length, buffered: this.entries.length },
+			'Recherche : page servie',
+		);
+		return { videos, nextOffset: hasMore ? end : null };
+	}
+
+	/**
+	 * Arrête la session : tue yt-dlp et libère les appels en attente.
+	 * Idempotent.
+	 *
+	 * @param reason - Raison de la fermeture, pour les logs.
+	 */
+	public dispose(reason: string): void {
+		if (this.disposed) {
+			return;
+		}
+		this.disposed = true;
+		this.finished = true;
+		this.abortController.abort();
+		// Un flux suspendu qui a encore des données n'émet jamais `close` : on
+		// le relance pour qu'il se vide et se ferme, sans quoi le descripteur
+		// resterait ouvert.
+		this.resumeReading();
+		this.notify();
+		this.logger.info(
+			{ sessionId: this.id, reason, buffered: this.entries.length },
+			'Recherche : session fermée',
+		);
+	}
+
+	/**
+	 * Intègre une ligne de sortie de yt-dlp (une entrée JSON) au tampon, puis
+	 * suspend la lecture si le tampon a assez d'avance sur la demande.
+	 *
+	 * @param line - Ligne complète reçue sur stdout.
+	 */
+	private ingest(line: string): void {
+		if (this.finished) {
+			return;
+		}
+
+		let summary: VideoSummary | null = null;
+		try {
+			summary = summarizeEntry(JSON.parse(line));
+		} catch {
+			// Ligne non JSON : ignorée, comme une entrée inexploitable.
+		}
+
+		// YouTube répète parfois une même vidéo dans ses résultats (mesuré : ~7 %
+		// de doublons sur 300 résultats).
+		if (summary && !this.seenIds.has(summary.id)) {
+			this.seenIds.add(summary.id);
+			this.entries.push(summary);
+		}
+
+		if (this.entries.length >= this.options.max) {
+			this.finished = true;
+			this.abortController.abort();
+			this.resumeReading();
+		} else if (this.entries.length >= this.wantedUpTo + this.options.readAhead) {
+			this.suspendReading();
+		}
+		this.notify();
+	}
+
+	/** Suspend la lecture de stdout : yt-dlp bloque quand le tube est plein. */
+	private suspendReading(): void {
+		if (this.suspended || !this.child) {
+			return;
+		}
+		this.suspended = true;
+		this.child.stdout.pause();
+	}
+
+	/** Reprend la lecture de stdout, si elle était suspendue. */
+	private resumeReading(): void {
+		if (!this.suspended || !this.child) {
+			return;
+		}
+		this.suspended = false;
+		this.child.stdout.resume();
+	}
+
+	/**
+	 * @param predicate - Condition à attendre, réévaluée à chaque nouveau résultat ou fin de parcours.
+	 * @returns Une promesse résolue dès que `predicate` est vraie.
+	 */
+	private waitUntil(predicate: () => boolean): Promise<void> {
+		return new Promise((resolve) => {
+			if (predicate()) {
+				resolve();
+				return;
+			}
+			const check = (): void => {
+				if (predicate()) {
+					this.waiters.delete(check);
+					resolve();
+				}
+			};
+			this.waiters.add(check);
+		});
+	}
+
+	/** Réveille les appels en attente pour qu'ils réévaluent leur condition. */
+	private notify(): void {
+		for (const check of [...this.waiters]) {
+			check();
+		}
+	}
+}
diff --git a/server/src/services/searchQuery.ts b/server/src/services/searchQuery.ts
new file mode 100644
index 0000000..b9d761f
--- /dev/null
+++ b/server/src/services/searchQuery.ts
@@ -0,0 +1,60 @@
+/** Longueur maximale (en caractères) d'une requête de recherche. */
+export const MAX_QUERY_LENGTH = 200;
+
+/**
+ * Erreur levée quand la requête de recherche fournie est vide, trop longue
+ * ou contient des caractères de contrôle.
+ */
+export class InvalidSearchQueryError extends Error {
+	/**
+	 * @param reason - Raison du refus, lisible par l'utilisateur.
+	 */
+	public constructor(reason: string) {
+		super(`Requête de recherche invalide : ${reason}`);
+		this.name = 'InvalidSearchQueryError';
+	}
+}
+
+/**
+ * @param text - Texte à inspecter.
+ * @returns `true` si `text` contient un caractère de contrôle (code < 0x20 ou DEL).
+ */
+function hasControlCharacter(text: string): boolean {
+	for (const char of text) {
+		const code = char.codePointAt(0) ?? 0;
+		if (code < 0x20 || code === 0x7f) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Valide et nettoie une requête de recherche YouTube.
+ *
+ * La requête est transmise à yt-dlp sous la forme `ytsearchN:<requête>`, un
+ * seul argument qui commence toujours par `ytsearch` : elle ne peut donc
+ * jamais être prise pour une option, ni faire récupérer une autre URL (le
+ * préfixe restreint yt-dlp à la recherche YouTube). Les caractères de
+ * contrôle (retours à la ligne, NUL...) n'ont aucun sens dans une requête et
+ * sont refusés par prudence.
+ *
+ * @param query - Requête fournie par l'appelant.
+ * @returns La requête, débarrassée des espaces superflus.
+ * @throws {InvalidSearchQueryError} Si la requête est vide, trop longue ou contient un caractère de contrôle.
+ */
+export function assertValidSearchQuery(query: string): string {
+	const trimmed = query.trim();
+
+	if (trimmed.length === 0) {
+		throw new InvalidSearchQueryError('elle est vide.');
+	}
+	if (trimmed.length > MAX_QUERY_LENGTH) {
+		throw new InvalidSearchQueryError(`elle dépasse ${MAX_QUERY_LENGTH} caractères.`);
+	}
+	if (hasControlCharacter(trimmed)) {
+		throw new InvalidSearchQueryError('elle contient un caractère de contrôle.');
+	}
+
+	return trimmed;
+}
diff --git a/server/src/services/ytDlpRunner.ts b/server/src/services/ytDlpRunner.ts
index d921d41..cf4f0dc 100644
--- a/server/src/services/ytDlpRunner.ts
+++ b/server/src/services/ytDlpRunner.ts
@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import { type ChildProcessWithoutNullStreams, spawn } from 'node:child_process';
 
 /**
  * Erreur levée quand le processus yt-dlp se termine en échec (code de
@@ -30,6 +30,13 @@ export interface RunYtDlpOptions {
 	readonly onStdoutLine?: (line: string) => void;
 	/** Signal d'annulation : le processus est tué si ce signal se déclenche. */
 	readonly signal?: AbortSignal;
+	/**
+	 * Rappelé une fois, juste après le lancement du processus, avec le
+	 * processus lui-même : permet à l'appelant d'en piloter les flux (ex.
+	 * suspendre la lecture de stdout pour freiner un yt-dlp qui produit plus
+	 * vite qu'on ne consomme).
+	 */
+	readonly onSpawn?: (child: ChildProcessWithoutNullStreams) => void;
 }
 
 /**
@@ -84,10 +91,11 @@ class LineSplitter {
  */
 export function runYtDlp(args: readonly string[], options: RunYtDlpOptions = {}): Promise<string> {
 	const ytDlpPath = process.env.YTDLP_PATH ?? 'yt-dlp';
-	const { timeoutMs = 30_000, onStdoutLine, signal } = options;
+	const { timeoutMs = 30_000, onStdoutLine, signal, onSpawn } = options;
 
 	return new Promise((resolve, reject) => {
 		const child = spawn(ytDlpPath, [...args], { shell: false, timeout: timeoutMs, signal });
+		onSpawn?.(child);
 
 		let stdout = '';
 		let stderr = '';
diff --git a/server/test/fakeYtDlp.ts b/server/test/fakeYtDlp.ts
new file mode 100644
index 0000000..ff66b58
--- /dev/null
+++ b/server/test/fakeYtDlp.ts
@@ -0,0 +1,94 @@
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+import { type Mock, type MockedFunction, vi } from 'vitest';
+import type { RunYtDlpOptions, runYtDlp } from '../src/services/ytDlpRunner.js';
+
+/** Un appel simulé à yt-dlp, pilotable depuis le test. */
+export interface FakeYtDlpRun {
+	/** Arguments reçus par `runYtDlp`. */
+	readonly args: readonly string[];
+	/** Options reçues par `runYtDlp`. */
+	readonly options: RunYtDlpOptions;
+	/** Espions sur les méthodes de stdout du faux processus. */
+	readonly stdout: { pause: Mock; resume: Mock };
+	/** `true` dès que le signal d'annulation fourni à `runYtDlp` a été déclenché. */
+	readonly aborted: boolean;
+	/** Émet une ligne de stdout, comme le ferait le processus. */
+	emit: (line: string) => void;
+	/** Émet `count` entrées valides supplémentaires (numérotées à la suite des précédentes). */
+	emitEntries: (count: number) => void;
+	/** Termine le processus avec succès. */
+	finish: () => void;
+	/** Termine le processus en échec. */
+	fail: (error: Error) => void;
+}
+
+/**
+ * @param index - Numéro de l'entrée (à partir de 1).
+ * @returns Une ligne `yt-dlp --flat-playlist -j` valide pour cette entrée.
+ */
+export function entryLine(index: number): string {
+	return JSON.stringify({
+		id: `id${index}`,
+		title: `Vidéo ${index}`,
+		url: `https://www.youtube.com/watch?v=id${index}`,
+		duration: 60,
+		thumbnails: [{ url: `https://i.ytimg.com/vi/id${index}/hq.jpg` }],
+	});
+}
+
+/**
+ * Remplace `runYtDlp` par un faux qui reste « en cours » tant que le test ne
+ * le termine pas, et dont le test pilote la sortie ligne par ligne.
+ *
+ * @param mockedRunYtDlp - Le `runYtDlp` mocké du module testé.
+ * @returns La liste (alimentée au fil des appels) des exécutions simulées.
+ */
+export function installFakeYtDlp(mockedRunYtDlp: MockedFunction<typeof runYtDlp>): FakeYtDlpRun[] {
+	const runs: FakeYtDlpRun[] = [];
+
+	mockedRunYtDlp.mockImplementation((args, options = {}) => {
+		const stdout = { pause: vi.fn(), resume: vi.fn() };
+		let settle: { resolve: (value: string) => void; reject: (reason: unknown) => void } | null =
+			null;
+		const promise = new Promise<string>((resolve, reject) => {
+			settle = { resolve, reject };
+		});
+		let emitted = 0;
+
+		const run: FakeYtDlpRun = {
+			args,
+			options,
+			stdout,
+			get aborted() {
+				return options.signal?.aborted ?? false;
+			},
+			emit: (line) => {
+				options.onStdoutLine?.(line);
+			},
+			emitEntries: (count) => {
+				for (let i = 0; i < count; i += 1) {
+					emitted += 1;
+					options.onStdoutLine?.(entryLine(emitted));
+				}
+			},
+			finish: () => {
+				settle?.resolve('');
+			},
+			fail: (error) => {
+				settle?.reject(error);
+			},
+		};
+
+		options.signal?.addEventListener('abort', () => {
+			const error = new Error('yt-dlp annulé');
+			error.name = 'AbortError';
+			settle?.reject(error);
+		});
+		options.onSpawn?.({ stdout } as unknown as ChildProcessWithoutNullStreams);
+
+		runs.push(run);
+		return promise;
+	});
+
+	return runs;
+}
diff --git a/server/test/searchQuery.test.ts b/server/test/searchQuery.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..113783b46f5ed426f11aeda2f49a7dca74e37266
GIT binary patch
literal 1311
zcmah}U279T6!mrYS6nKxyX2$vxl~XLD%3)?6{Rg@GJBg$nB7_L%*2#Z^k0Y|;)`I4
z|04gyhvLuhPO?o+NZOaMnS0N<cg{Jxs;CS(xPTn3B-O<x;HX0BnxGt9!Wo$YlA&^F
zU9ugkx;>6wmP4Uc{sslf{=P>#?+_Vk#?h-M?@sp*JFnlL?soQ`AH3irVJ(t-y98*)
zH~j7PrX{(_O+zKo^2409J+M4CzF99#R&ymyNHf@Z3>R^vTpNY#r$=!V9VNa*ApGDb
zR}R7Q1vGMVVk^WPq*g^&mAw@wC%iYqc`%@@1g{0wS4d~t+t3cMNC9v+iI5UY$7GJR
z2L0#rS6?b=^654#zR-ftCu27m!}XV+*WZ5sz4{&~*Vg{q(4H4vqj^PXJP95XfU?nm
z4d<O9g?a;8`DEPnj;ru+>)v`z?n`ircxU8?sf6i36hc|3DE#m^2nw6ZDN|;Fw$;KB
z${i{e|I7*b@}}&0WMm;mst_7Eb3(eQ5+Z36Rw!J$oTH4n@2Cd;lZ^AhI#+D<qo6^0
zsznzyhq<ggXL^=x%x|I+%?{Glp-QKyENeUS6w^6&JB}_h&g4?ihHB<zQs4AU@LK~p
z8(rro=m8v)y6(tSwG^SU{%X*Gt*i!#AxajU6YYZZlOLc3Xw@rkLw#J%Q@t7_`+}5l
zVdyl%$Fv53;6&GJ5v;xKc5Avp3St*0zX)OPaCZ)Pu(JPI=eFb1LPs!>aDa~0TX=a_
bIJ)fP>>F^en+JU|AJa9TFt&E;Z}9jZ*BP~K

literal 0
HcmV?d00001

diff --git a/server/test/searchRoute.test.ts b/server/test/searchRoute.test.ts
new file mode 100644
index 0000000..3b686c3
--- /dev/null
+++ b/server/test/searchRoute.test.ts
@@ -0,0 +1,181 @@
+import Fastify, { type FastifyInstance } from 'fastify';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('../src/services/ytDlpRunner.js', async (importOriginal) => {
+	const actual = await importOriginal<typeof import('../src/services/ytDlpRunner.js')>();
+	return { ...actual, runYtDlp: vi.fn() };
+});
+
+import { searchRoutes } from '../src/routes/search.js';
+import { runYtDlp } from '../src/services/ytDlpRunner.js';
+import { type FakeYtDlpRun, installFakeYtDlp } from './fakeYtDlp.js';
+import { waitFor } from './helpers.js';
+
+let runs: FakeYtDlpRun[];
+let app: FastifyInstance;
+
+/**
+ * Ouvre une recherche via l'API, en faisant produire `entries` résultats au yt-dlp simulé.
+ *
+ * @param entries - Nombre de résultats à produire.
+ * @param body - Corps de la requête `POST /api/search`.
+ * @returns La réponse de l'API et le yt-dlp simulé de la recherche.
+ */
+async function openSearch(entries: number, body: Record<string, unknown> = { query: 'test' }) {
+	const responsePromise = app.inject({ method: 'POST', url: '/api/search', payload: body });
+	await waitFor(() => runs.length > 0);
+	const run = runs.at(-1) as FakeYtDlpRun;
+	run.emitEntries(entries);
+	return { response: await responsePromise, run };
+}
+
+beforeEach(async () => {
+	vi.mocked(runYtDlp).mockReset();
+	runs = installFakeYtDlp(vi.mocked(runYtDlp));
+	app = Fastify();
+	await app.register(searchRoutes);
+});
+
+afterEach(async () => {
+	await app.close();
+});
+
+describe('POST /api/search', () => {
+	it('ouvre une recherche et retourne son identifiant et sa première page', async () => {
+		const { response } = await openSearch(30, { query: 'speed climbing', limit: 5 });
+
+		expect(response.statusCode).toBe(201);
+		const body = response.json();
+		expect(body.id).toEqual(expect.any(String));
+		expect(body.videos).toHaveLength(5);
+		expect(body.videos[0]).toEqual({
+			id: 'id1',
+			title: 'Vidéo 1',
+			url: 'https://www.youtube.com/watch?v=id1',
+			thumbnailUrl: 'https://i.ytimg.com/vi/id1/hq.jpg',
+			durationSeconds: 60,
+			uploadDate: null,
+		});
+		expect(body.nextOffset).toBe(5);
+	});
+
+	it('utilise une page de 20 par défaut', async () => {
+		const { response } = await openSearch(50);
+
+		expect(response.json().videos).toHaveLength(20);
+	});
+
+	it('avec un plafond (max), retourne tout d’un coup et signale la fin', async () => {
+		const { response, run } = await openSearch(50, { query: 'test', max: 12, limit: 12 });
+
+		const body = response.json();
+		expect(body.videos).toHaveLength(12);
+		expect(body.nextOffset).toBeNull();
+		expect(run.aborted).toBe(true);
+	});
+
+	it.each([
+		['une requête d’espaces', { query: '   ' }],
+		['une requête vide', { query: '' }],
+		['une requête trop longue', { query: 'a'.repeat(201) }],
+		['une requête absente', {}],
+		['une limite hors bornes', { query: 'x', limit: 5000 }],
+		['un plafond nul', { query: 'x', max: 0 }],
+		['un plafond non entier', { query: 'x', max: 1.5 }],
+	])('renvoie 400 pour %s, sans lancer yt-dlp', async (_label, body) => {
+		const response = await app.inject({ method: 'POST', url: '/api/search', payload: body });
+
+		expect(response.statusCode).toBe(400);
+		expect(runs).toHaveLength(0);
+	});
+
+	it('renvoie 502 (pas 500) quand yt-dlp échoue avant le moindre résultat', async () => {
+		const responsePromise = app.inject({
+			method: 'POST',
+			url: '/api/search',
+			payload: { query: 'test' },
+		});
+		await waitFor(() => runs.length > 0);
+		runs[0]?.fail(new Error('spawn yt-dlp ENOENT'));
+
+		const response = await responsePromise;
+
+		expect(response.statusCode).toBe(502);
+	});
+});
+
+describe('GET /api/search/:id', () => {
+	it('retourne les pages suivantes', async () => {
+		const { response } = await openSearch(60, { query: 'test', limit: 10 });
+		const { id } = response.json();
+
+		const second = await app.inject({ method: 'GET', url: `/api/search/${id}?offset=10&limit=10` });
+
+		expect(second.statusCode).toBe(200);
+		expect(second.json().videos.map((video: { id: string }) => video.id)).toEqual(
+			Array.from({ length: 10 }, (_, i) => `id${i + 11}`),
+		);
+		expect(second.json().nextOffset).toBe(20);
+	});
+
+	it('renvoie 404 pour une recherche inconnue', async () => {
+		const response = await app.inject({ method: 'GET', url: '/api/search/inconnue?offset=0' });
+
+		expect(response.statusCode).toBe(404);
+	});
+
+	it.each([
+		['un offset négatif', 'offset=-1'],
+		['un offset non numérique', 'offset=abc'],
+		['une limite nulle', 'limit=0'],
+		['une limite hors bornes', 'limit=5000'],
+	])('renvoie 400 pour %s', async (_label, query) => {
+		const response = await app.inject({ method: 'GET', url: `/api/search/quelconque?${query}` });
+
+		expect(response.statusCode).toBe(400);
+	});
+
+	it('renvoie 404 une fois la dernière page servie (la recherche est fermée)', async () => {
+		const responsePromise = app.inject({
+			method: 'POST',
+			url: '/api/search',
+			payload: { query: 'test', limit: 10 },
+		});
+		await waitFor(() => runs.length > 0);
+		runs[0]?.emitEntries(3);
+		runs[0]?.finish();
+		const { id, nextOffset } = (await responsePromise).json();
+
+		expect(nextOffset).toBeNull();
+		const response = await app.inject({ method: 'GET', url: `/api/search/${id}?offset=0` });
+		expect(response.statusCode).toBe(404);
+	});
+});
+
+describe('DELETE /api/search/:id', () => {
+	it('ferme la recherche (yt-dlp annulé), puis renvoie 404', async () => {
+		const { response, run } = await openSearch(30, { query: 'test', limit: 5 });
+		const { id } = response.json();
+
+		const deleted = await app.inject({ method: 'DELETE', url: `/api/search/${id}` });
+		expect(deleted.statusCode).toBe(204);
+		expect(run.aborted).toBe(true);
+
+		const again = await app.inject({ method: 'DELETE', url: `/api/search/${id}` });
+		expect(again.statusCode).toBe(404);
+		const page = await app.inject({ method: 'GET', url: `/api/search/${id}?offset=5` });
+		expect(page.statusCode).toBe(404);
+	});
+});
+
+describe('arrêt du serveur', () => {
+	it('ferme les recherches ouvertes (aucun yt-dlp ne survit à l’arrêt)', async () => {
+		const { run } = await openSearch(30, { query: 'test', limit: 5 });
+		expect(run.aborted).toBe(false);
+
+		await app.close();
+
+		expect(run.aborted).toBe(true);
+		// afterEach rappelle app.close() : il doit rester sans effet.
+	});
+});
diff --git a/server/test/searchService.test.ts b/server/test/searchService.test.ts
new file mode 100644
index 0000000..3e9503a
--- /dev/null
+++ b/server/test/searchService.test.ts
@@ -0,0 +1,189 @@
+import type { FastifyBaseLogger } from 'fastify';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('../src/services/ytDlpRunner.js', async (importOriginal) => {
+	const actual = await importOriginal<typeof import('../src/services/ytDlpRunner.js')>();
+	return { ...actual, runYtDlp: vi.fn() };
+});
+
+import { SearchService, type SearchServiceOptions } from '../src/services/SearchService.js';
+import { InvalidSearchQueryError } from '../src/services/searchQuery.js';
+import { runYtDlp } from '../src/services/ytDlpRunner.js';
+import { type FakeYtDlpRun, installFakeYtDlp } from './fakeYtDlp.js';
+
+const noopLogger = { info: () => {}, error: () => {} } as unknown as FastifyBaseLogger;
+
+let runs: FakeYtDlpRun[];
+
+/**
+ * @param overrides - Réglages à surcharger.
+ * @returns Un service de test.
+ */
+function createService(overrides: Partial<SearchServiceOptions> = {}): SearchService {
+	return new SearchService(noopLogger, overrides);
+}
+
+/**
+ * Ouvre une recherche dont le yt-dlp simulé produit `entries` résultats.
+ *
+ * @param service - Service concerné.
+ * @param entries - Nombre de résultats à faire produire au yt-dlp simulé.
+ * @param limit - Taille de la première page.
+ * @returns L'identifiant de la recherche, sa première page, et son yt-dlp simulé.
+ */
+async function openSearch(
+	service: SearchService,
+	entries: number,
+	limit = 5,
+): Promise<{ id: string; run: FakeYtDlpRun; nextOffset: number | null }> {
+	const started = service.start('speed climbing', 1000, limit);
+	const run = runs.at(-1);
+	if (!run) {
+		throw new Error('yt-dlp simulé non lancé');
+	}
+	run.emitEntries(entries);
+	const { id, page } = await started;
+	return { id, run, nextOffset: page.nextOffset };
+}
+
+beforeEach(() => {
+	vi.mocked(runYtDlp).mockReset();
+	runs = installFakeYtDlp(vi.mocked(runYtDlp));
+});
+
+afterEach(() => {
+	vi.useRealTimers();
+});
+
+describe('SearchService', () => {
+	it('ouvre une recherche et retourne son identifiant et sa première page', async () => {
+		const service = createService();
+
+		const { id, run, nextOffset } = await openSearch(service, 20, 5);
+
+		expect(id).toEqual(expect.any(String));
+		expect(nextOffset).toBe(5);
+		expect(run.args.at(-1)).toBe('ytsearch1000:speed climbing');
+		service.closeAll();
+	});
+
+	it('sert les pages suivantes d’une recherche ouverte', async () => {
+		const service = createService();
+		const { id } = await openSearch(service, 20, 5);
+
+		const page = await service.page(id, 5, 5);
+
+		expect(page?.videos.map((video) => video.id)).toEqual(['id6', 'id7', 'id8', 'id9', 'id10']);
+		expect(page?.nextOffset).toBe(10);
+		service.closeAll();
+	});
+
+	it('retourne null pour une recherche inconnue', async () => {
+		const service = createService();
+
+		await expect(service.page('inconnue', 0, 5)).resolves.toBeNull();
+	});
+
+	it('rejette une requête invalide sans jamais lancer yt-dlp', async () => {
+		const service = createService();
+
+		await expect(service.start('   ', 100, 5)).rejects.toBeInstanceOf(InvalidSearchQueryError);
+		expect(runs).toHaveLength(0);
+	});
+
+	it('ferme la recherche dès que sa dernière page a été servie', async () => {
+		const service = createService();
+		const started = service.start('speed climbing', 1000, 5);
+		runs[0]?.emitEntries(3);
+		runs[0]?.finish(); // fin des résultats : la première page est aussi la dernière
+		const { id, page } = await started;
+
+		expect(page.nextOffset).toBeNull();
+		await expect(service.page(id, 0, 5)).resolves.toBeNull();
+	});
+
+	it('dispose ferme la recherche (yt-dlp annulé) et n’existe plus ensuite', async () => {
+		const service = createService();
+		const { id, run } = await openSearch(service, 20, 5);
+
+		expect(service.dispose(id)).toBe(true);
+
+		expect(run.aborted).toBe(true);
+		expect(service.dispose(id)).toBe(false);
+		await expect(service.page(id, 5, 5)).resolves.toBeNull();
+	});
+
+	it('ferme la recherche et relance l’erreur quand la première page échoue', async () => {
+		const service = createService();
+		const started = service.start('speed climbing', 1000, 5);
+		runs[0]?.fail(new Error('boom'));
+
+		await expect(started).rejects.toThrow('boom');
+		expect(runs[0]?.aborted).toBe(true);
+	});
+
+	it('ferme la moins récemment utilisée quand la limite de recherches simultanées est atteinte', async () => {
+		const service = createService({ maxSessions: 2 });
+		const first = await openSearch(service, 20);
+		const second = await openSearch(service, 20);
+
+		// La première est la moins récemment utilisée : consulter la seconde le confirme.
+		await service.page(second.id, 5, 5);
+		const third = await openSearch(service, 20);
+
+		expect(first.run.aborted).toBe(true);
+		expect(second.run.aborted).toBe(false);
+		expect(third.run.aborted).toBe(false);
+		await expect(service.page(first.id, 5, 5)).resolves.toBeNull();
+		service.closeAll();
+	});
+
+	it('ferme les recherches inactives, et arrête son balayage quand il n’en reste plus', async () => {
+		vi.useFakeTimers();
+		const service = createService({ idleTtlMs: 1000, sweepIntervalMs: 500 });
+		const { run } = await openSearch(service, 20);
+		expect(vi.getTimerCount()).toBe(1); // le balayage tourne
+
+		await vi.advanceTimersByTimeAsync(2000);
+
+		expect(run.aborted).toBe(true);
+		expect(vi.getTimerCount()).toBe(0); // plus rien à balayer
+	});
+
+	it('ne ferme pas une recherche encore active', async () => {
+		vi.useFakeTimers();
+		const service = createService({ idleTtlMs: 1000, sweepIntervalMs: 500 });
+		const { id, run } = await openSearch(service, 40, 5);
+
+		for (let offset = 5; offset <= 25; offset += 5) {
+			await vi.advanceTimersByTimeAsync(800); // toujours sous le délai d'inactivité
+			await service.page(id, offset, 5);
+		}
+
+		expect(run.aborted).toBe(false);
+		service.closeAll();
+	});
+
+	it('ferme une recherche qui dépasse sa durée de vie maximale, même active', async () => {
+		vi.useFakeTimers();
+		const service = createService({ idleTtlMs: 10_000, maxLifetimeMs: 2000, sweepIntervalMs: 500 });
+		const { id, run } = await openSearch(service, 40, 5);
+
+		await vi.advanceTimersByTimeAsync(1000);
+		await service.page(id, 5, 5); // activité récente...
+		await vi.advanceTimersByTimeAsync(1500); // ...mais durée de vie dépassée
+
+		expect(run.aborted).toBe(true);
+	});
+
+	it('closeAll ferme toutes les recherches', async () => {
+		const service = createService();
+		const first = await openSearch(service, 20);
+		const second = await openSearch(service, 20);
+
+		service.closeAll();
+
+		expect(first.run.aborted).toBe(true);
+		expect(second.run.aborted).toBe(true);
+	});
+});
diff --git a/server/test/searchSession.test.ts b/server/test/searchSession.test.ts
new file mode 100644
index 0000000..701c81e
--- /dev/null
+++ b/server/test/searchSession.test.ts
@@ -0,0 +1,251 @@
+import type { FastifyBaseLogger } from 'fastify';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('../src/services/ytDlpRunner.js', async (importOriginal) => {
+	const actual = await importOriginal<typeof import('../src/services/ytDlpRunner.js')>();
+	return { ...actual, runYtDlp: vi.fn() };
+});
+
+import {
+	SEARCH_DEPTH,
+	SearchSession,
+	type SearchSessionOptions,
+} from '../src/services/SearchSession.js';
+import { runYtDlp } from '../src/services/ytDlpRunner.js';
+import { type FakeYtDlpRun, entryLine, installFakeYtDlp } from './fakeYtDlp.js';
+
+let runs: FakeYtDlpRun[];
+let logger: { info: ReturnType<typeof vi.fn>; error: ReturnType<typeof vi.fn> };
+
+/**
+ * @param overrides - Réglages à surcharger.
+ * @returns Des réglages de session de test (plafond large, longue avance).
+ */
+function options(overrides: Partial<SearchSessionOptions> = {}): SearchSessionOptions {
+	return { query: 'speed climbing', max: 1000, readAhead: 20, lifetimeMs: 60_000, ...overrides };
+}
+
+/**
+ * @param overrides - Réglages à surcharger.
+ * @returns Une session ouverte avec le logger de test (son yt-dlp simulé est `runs.at(-1)`).
+ */
+function open(overrides: Partial<SearchSessionOptions> = {}): SearchSession {
+	return new SearchSession(logger as unknown as FastifyBaseLogger, options(overrides));
+}
+
+/** Laisse s'exécuter les micro-tâches et les callbacks en attente. */
+const flush = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0));
+
+beforeEach(() => {
+	vi.mocked(runYtDlp).mockReset();
+	runs = installFakeYtDlp(vi.mocked(runYtDlp));
+	logger = { info: vi.fn(), error: vi.fn() };
+});
+
+describe('SearchSession', () => {
+	it('lance yt-dlp en mode paresseux, avec la requête (préfixe ytsearch) et la durée de vie demandée', () => {
+		open({ query: 'escalade été', lifetimeMs: 12_345 });
+
+		expect(runs).toHaveLength(1);
+		expect(runs[0]?.args).toEqual([
+			'--flat-playlist',
+			'--lazy-playlist',
+			'-j',
+			'--',
+			`ytsearch${SEARCH_DEPTH}:escalade été`,
+		]);
+		expect(runs[0]?.options.timeoutMs).toBe(12_345);
+	});
+
+	it('attend d’avoir assez de résultats avant de répondre à une page', async () => {
+		const session = open();
+		let settled = false;
+		const pagePromise = session.page(0, 3).then((page) => {
+			settled = true;
+			return page;
+		});
+
+		runs[0]?.emitEntries(2);
+		await flush();
+		expect(settled).toBe(false);
+
+		runs[0]?.emitEntries(1);
+		const page = await pagePromise;
+
+		expect(page.videos.map((video) => video.id)).toEqual(['id1', 'id2', 'id3']);
+		expect(page.nextOffset).toBe(3);
+	});
+
+	it('sert les pages suivantes depuis le tampon, sans relancer yt-dlp', async () => {
+		const session = open();
+		const first = session.page(0, 2);
+		runs[0]?.emitEntries(6);
+		await first;
+
+		const second = await session.page(2, 2);
+		const third = await session.page(4, 2);
+
+		expect(second.videos.map((video) => video.id)).toEqual(['id3', 'id4']);
+		expect(third.videos.map((video) => video.id)).toEqual(['id5', 'id6']);
+		expect(runs).toHaveLength(1);
+	});
+
+	it('ignore les doublons, les lignes illisibles et les entrées incomplètes', async () => {
+		const session = open();
+		const pagePromise = session.page(0, 10);
+
+		runs[0]?.emit(entryLine(1));
+		runs[0]?.emit(entryLine(1)); // doublon : YouTube répète parfois une vidéo
+		runs[0]?.emit('ceci n’est pas du JSON');
+		runs[0]?.emit(JSON.stringify({ id: 'sans-url', title: 'Incomplète' }));
+		runs[0]?.emit(entryLine(2));
+		runs[0]?.finish();
+		const page = await pagePromise;
+
+		expect(page.videos.map((video) => video.id)).toEqual(['id1', 'id2']);
+	});
+
+	it('signale la fin des résultats : page partielle et nextOffset null', async () => {
+		const session = open();
+		const pagePromise = session.page(0, 5);
+
+		runs[0]?.emitEntries(2);
+		runs[0]?.finish();
+		const page = await pagePromise;
+
+		expect(page.videos).toHaveLength(2);
+		expect(page.nextOffset).toBeNull();
+	});
+
+	it('signale la fin par une page vide quand la dernière page tombe pile sur le dernier résultat', async () => {
+		const session = open();
+		const first = session.page(0, 4);
+
+		runs[0]?.emitEntries(4);
+		const firstPage = await first;
+		// yt-dlp n'a pas encore signalé sa fin au moment où la page est pleine :
+		// une suite reste possible, la page suivante tranche.
+		expect(firstPage.videos).toHaveLength(4);
+		expect(firstPage.nextOffset).toBe(4);
+
+		runs[0]?.finish();
+		const next = await session.page(4, 4);
+
+		expect(next).toEqual({ videos: [], nextOffset: null });
+	});
+
+	it('renvoie une page vide et la fin quand on demande au-delà des résultats', async () => {
+		const session = open();
+		const first = session.page(0, 2);
+		runs[0]?.emitEntries(2);
+		runs[0]?.finish();
+		await first;
+
+		const beyond = await session.page(50, 10);
+
+		expect(beyond).toEqual({ videos: [], nextOffset: null });
+	});
+
+	it('s’arrête au plafond : annule yt-dlp, ignore la suite et signale la fin', async () => {
+		const session = open({ max: 3 });
+		const pagePromise = session.page(0, 10);
+
+		runs[0]?.emitEntries(5);
+		const page = await pagePromise;
+
+		expect(page.videos.map((video) => video.id)).toEqual(['id1', 'id2', 'id3']);
+		expect(page.nextOffset).toBeNull();
+		expect(runs[0]?.aborted).toBe(true);
+		expect(logger.error).not.toHaveBeenCalled();
+	});
+
+	it('suspend la lecture quand le tampon a assez d’avance, et la reprend à la demande', async () => {
+		const session = open({ readAhead: 2 });
+		const first = session.page(0, 2); // demande : 2 résultats
+		runs[0]?.emitEntries(3);
+		await first;
+		expect(runs[0]?.stdout.pause).not.toHaveBeenCalled(); // 3 < 2 + 2
+
+		runs[0]?.emitEntries(1); // 4 >= 2 + 2 : assez d'avance
+		expect(runs[0]?.stdout.pause).toHaveBeenCalledTimes(1);
+		expect(runs[0]?.stdout.resume).not.toHaveBeenCalled();
+
+		const next = await session.page(2, 2); // servi depuis le tampon...
+		expect(next.videos.map((video) => video.id)).toEqual(['id3', 'id4']);
+		expect(runs[0]?.stdout.resume).toHaveBeenCalledTimes(1); // ...et le parcours repart
+	});
+
+	it('ne suspend qu’une fois tant qu’il n’a pas été relancé', async () => {
+		const session = open({ readAhead: 1 });
+		const first = session.page(0, 1);
+		runs[0]?.emitEntries(2); // suspend
+		await first;
+		runs[0]?.emitEntries(3); // encore des lignes déjà dans le tube au moment de la pause
+
+		expect(runs[0]?.stdout.pause).toHaveBeenCalledTimes(1);
+	});
+
+	it('lève l’erreur quand yt-dlp échoue avant le moindre résultat', async () => {
+		const session = open();
+		const pagePromise = session.page(0, 5);
+
+		runs[0]?.fail(new Error('boom'));
+
+		await expect(pagePromise).rejects.toThrow('boom');
+		expect(logger.error).toHaveBeenCalled();
+	});
+
+	it('sert ce qu’il a et signale la fin quand yt-dlp échoue après des résultats', async () => {
+		const session = open();
+		const pagePromise = session.page(0, 10);
+
+		runs[0]?.emitEntries(2);
+		runs[0]?.fail(new Error('réseau coupé'));
+		const page = await pagePromise;
+
+		expect(page.videos).toHaveLength(2);
+		expect(page.nextOffset).toBeNull();
+		expect(logger.error).toHaveBeenCalled();
+	});
+
+	it('dispose : annule yt-dlp sans le compter comme un échec, et libère les appels en attente', async () => {
+		const session = open();
+		const pending = session.page(0, 5);
+
+		session.dispose('test');
+		const page = await pending;
+		await flush();
+
+		expect(runs[0]?.aborted).toBe(true);
+		expect(page).toEqual({ videos: [], nextOffset: null });
+		expect(logger.error).not.toHaveBeenCalled();
+	});
+
+	it('dispose relance un flux suspendu pour qu’il puisse se vider et se fermer', async () => {
+		const session = open({ readAhead: 1 });
+		const first = session.page(0, 1);
+		runs[0]?.emitEntries(2); // suspend
+		await first;
+		expect(runs[0]?.stdout.pause).toHaveBeenCalledTimes(1);
+
+		session.dispose('test');
+
+		expect(runs[0]?.stdout.resume).toHaveBeenCalledTimes(1);
+	});
+
+	it('dispose est idempotent', () => {
+		const session = open();
+
+		session.dispose('premier');
+		session.dispose('second');
+
+		expect(logger.info).toHaveBeenCalledWith(
+			expect.objectContaining({ reason: 'premier' }),
+			expect.any(String),
+		);
+		expect(logger.info).not.toHaveBeenCalledWith(
+			expect.objectContaining({ reason: 'second' }),
+			expect.any(String),
+		);
+	});
+});
diff --git a/server/test/ytDlpRunner.test.ts b/server/test/ytDlpRunner.test.ts
index a270d94..c2f2727 100644
--- a/server/test/ytDlpRunner.test.ts
+++ b/server/test/ytDlpRunner.test.ts
@@ -45,6 +45,36 @@ describe('runYtDlp', () => {
 		expect(lines).toEqual(['sans-newline']);
 	});
 
+	it('donne le processus lancé à onSpawn, avant toute sortie', async () => {
+		process.env.YTDLP_PATH = process.execPath;
+		const spawns: Array<{
+			pid: number | undefined;
+			canPause: boolean;
+			canResume: boolean;
+			linesSoFar: number;
+		}> = [];
+		let lines = 0;
+
+		await runYtDlp(['-e', "console.log('a')"], {
+			onSpawn: (child) => {
+				spawns.push({
+					pid: child.pid,
+					canPause: typeof child.stdout.pause === 'function',
+					canResume: typeof child.stdout.resume === 'function',
+					linesSoFar: lines,
+				});
+			},
+			onStdoutLine: () => {
+				lines += 1;
+			},
+		});
+
+		expect(spawns).toEqual([
+			{ pid: expect.any(Number), canPause: true, canResume: true, linesSoFar: 0 },
+		]);
+		expect(lines).toBe(1);
+	});
+
 	it("rejette avec une AbortError quand le signal d'annulation se déclenche", async () => {
 		process.env.YTDLP_PATH = process.execPath;
 		const controller = new AbortController();
diff --git a/spec/architecture.md b/spec/architecture.md
index ccd185f..801d96f 100644
--- a/spec/architecture.md
+++ b/spec/architecture.md
@@ -19,32 +19,36 @@ Pas de `docker-compose.yml` pour l'instant (une seule image, pas encore de dépe
 - Fastify 5, TypeScript strict, ESM (`"type": "module"`, imports relatifs en `.js`, résolution `NodeNext`).
 - `src/index.ts` : bootstrap (plugins, écoute, arrêt propre SIGINT/SIGTERM).
 - `src/config.ts` : configuration runtime depuis l'environnement (`PORT`, `HOST`, `CLIENT_DIST_PATH`, `TMP_DIR`, `MAX_CONCURRENT_DOWNLOADS`). Les valeurs par défaut de `CLIENT_DIST_PATH`/`TMP_DIR` sont résolues depuis l'emplacement du module (`import.meta.url`), pas `process.cwd()` : reste correct quel que soit le répertoire depuis lequel le process est lancé (ex. `npm --prefix server run dev` depuis la racine du dépôt, utilisé par `.claude/launch.json` pour la prévisualisation - non versionné, voir `.gitignore`).
-- `src/routes/` : routes Fastify enregistrées comme plugins (`health.ts`, `channel.ts`, `playlist.ts`, `queue.ts`). Chaque domaine métier suit le même principe : un plugin de route fin sous `src/routes/`, qui délègue à un service sous `src/services/`.
+- `src/routes/` : routes Fastify enregistrées comme plugins (`health.ts`, `channel.ts`, `playlist.ts`, `search.ts`, `queue.ts`). Chaque domaine métier suit le même principe : un plugin de route fin sous `src/routes/`, qui délègue à un service sous `src/services/`.
 - `src/services/` :
-  - `ytDlpRunner.ts` : exécution bas niveau de yt-dlp (`node:child_process.spawn`, jamais de shell - arguments toujours passés en tableau, jamais concaténés dans une chaîne, pour exclure toute injection de commande). Supporte le suivi ligne par ligne de stdout (`onStdoutLine`, pour la progression) et l'annulation via `AbortSignal`.
+  - `ytDlpRunner.ts` : exécution bas niveau de yt-dlp (`node:child_process.spawn`, jamais de shell - arguments toujours passés en tableau, jamais concaténés dans une chaîne, pour exclure toute injection de commande). Supporte le suivi ligne par ligne de stdout (`onStdoutLine`, pour la progression), l'annulation via `AbortSignal`, et `onSpawn` (reçoit le processus lancé, pour en piloter les flux - utilisé par la recherche pour suspendre stdout).
   - `ChannelDiscoveryService.ts` : liste les vidéos/streams d'une chaîne (`yt-dlp --flat-playlist -j`), filtre par mots-clés sur le titre. Valide strictement le handle/URL de chaîne en entrée (premier caractère forcément alphanumérique) et ajoute un séparateur `--` avant l'URL passée à yt-dlp, en défense en profondeur contre l'injection d'options. Une ligne de sortie = une entrée, convertie par `videoSummary.ts`.
   - `PlaylistDiscoveryService.ts` : liste les vidéos d'une playlist (`yt-dlp --flat-playlist -J -- <url canonique>`, délai de 120 s : ~1600 vidéos mesurées en ~11 s, YouTube pagine par centaines). `-J` (un seul objet JSON `{title, entries: [...]}`) plutôt que `-j` (une ligne par entrée, comme pour les chaînes) : le titre de la playlist n'existe qu'à la racine, et une playlist vide reste un résultat valide avec son titre. Les entrées sont converties par le même `videoSummary.ts` que pour les chaînes.
   - `playlistUrl.ts` : valide qu'un lien est bien une playlist YouTube (`youtube.com/playlist?list=<id>`, domaines `youtube.com`/`www.`/`m.`/`music.`, https, sans port ni identifiants) et retourne l'URL **canonique** reconstruite depuis le seul identifiant validé (`[\w-]{2,64}` - longueur variable selon le type de playlist) : rien d'autre de ce que l'appelant a fourni n'est jamais transmis à yt-dlp. Même garde anti-SSRF que `videoUrl.ts`. Un lien de vidéo portant un paramètre `list` (`watch?v=...&list=...`) n'est volontairement **pas** une playlist : il désigne une vidéo (et `downloadPlan.ts` passe déjà `--no-playlist`, donc seule cette vidéo est téléchargée).
-  - `videoSummary.ts` : type `VideoSummary` et `summarizeEntry()`, conversion partagée d'une entrée `--flat-playlist` (chaîne ou playlist) en résumé de vidéo ; retourne `null` pour une entrée inexploitable plutôt que d'interrompre le reste. Miniature (`thumbnailUrl`) lue en priorité sur `thumbnail` (champ singulier), sinon sur le dernier élément de `thumbnails` (tableau) : en `--flat-playlist`, l'extracteur YouTube ne renseigne quasiment jamais le champ singulier, seulement le tableau (trié par résolution croissante) - un bug réel (miniatures jamais affichées) passé inaperçu en test tant que le mock ne reproduisait que la forme théorique (`thumbnail`) et jamais la forme réelle. `upload_date` est absent en pratique des entrées `--flat-playlist` (il n'y a qu'un `timestamp`) : `uploadDate` vaut donc `null`.
+  - `SearchService.ts` / `SearchSession.ts` / `searchQuery.ts` : recherche YouTube globale (`ytsearchN:`), paginée. Une **session** (`SearchSession`) = un seul processus yt-dlp (`--flat-playlist --lazy-playlist -j -- ytsearch1000:<requête>`) dont les pages sont servies depuis un tampon ; `SearchService` gère le parc de sessions (4 simultanées max - la moins récemment utilisée est fermée au-delà ; expiration après 10 min d'inactivité ou 30 min de vie, balayage toutes les 30 s ; fermeture dès que la dernière page est servie, sur `DELETE`, et à l'arrêt du serveur via le hook `onClose`). Pourquoi une session plutôt qu'un appel yt-dlp par page - **mesuré avec le vrai yt-dlp** : (1) l'ordre des résultats de YouTube n'est **pas déterministe, même pour deux appels identiques** (5 résultats sur 20 à la même position, 69 % de recouvrement sur 100) : paginer en relançant la recherche et en tranchant (`offset`/`limit`) donnait 15 à 30 % de doublons dès la 3e-4e page et des résultats jamais montrés ; (2) YouTube s'arrête de lui-même vers **~590 résultats** même si on en demande 1000 ; (3) environ 7 % des résultats sont des doublons d'une même vidéo (dédoublonnés à l'ingestion, donc le décalage `offset` reste cohérent) ; (4) sans `--lazy-playlist`, yt-dlp matérialise toute la liste avant d'imprimer la première ligne (~23 s pour 1000) : avec, les résultats arrivent au fil des pages (20 en ~2,3 s). **Le parcours n'avance qu'à la demande** : dès que le tampon a 20 résultats d'avance sur ce qui a été demandé, la lecture de stdout est suspendue (`child.stdout.pause()` via `onSpawn`) ; le tube se remplit et yt-dlp bloque sur son écriture (mesuré : plus aucune ligne pendant 10 s de pause, reprise au rythme normal ensuite) - on n'aspire donc pas ~590 résultats (et ~30 requêtes vers YouTube) quand l'utilisateur ne défile pas. Vérifié en boîte noire : une page déjà tamponnée répond en ~4 ms, une page 200 demandée après 12 s d'inactivité en ~4 s. `max` plafonne le nombre de résultats (au plafond, yt-dlp est annulé) : c'est ainsi que fonctionne le mode « limite ». Un échec de yt-dlp avant tout résultat lève une erreur ; après des résultats, on sert le tampon et on signale la fin. Sous Windows, tuer le parent d'un exécutable PyInstaller n'arrête pas son enfant, qui finit son parcours puis s'arrête seul (~30 s, transitoire, dev seulement) ; sous Linux (production) le lanceur transmet SIGTERM à l'enfant, comme pour l'annulation de téléchargements. `searchQuery.ts` valide la requête (1 à 200 caractères, sans caractère de contrôle) : elle est transmise sous la forme d'un unique argument `ytsearchN:<requête>`, qui ne peut jamais être pris pour une option ni faire récupérer une autre URL.
+  - `videoSummary.ts` : type `VideoSummary` et `summarizeEntry()`, conversion partagée d'une entrée `--flat-playlist` (chaîne, playlist ou recherche) en résumé de vidéo ; retourne `null` pour une entrée inexploitable plutôt que d'interrompre le reste. Miniature (`thumbnailUrl`) lue en priorité sur `thumbnail` (champ singulier), sinon sur le dernier élément de `thumbnails` (tableau) : en `--flat-playlist`, l'extracteur YouTube ne renseigne quasiment jamais le champ singulier, seulement le tableau (trié par résolution croissante) - un bug réel (miniatures jamais affichées) passé inaperçu en test tant que le mock ne reproduisait que la forme théorique (`thumbnail`) et jamais la forme réelle. `upload_date` est absent en pratique des entrées `--flat-playlist` (il n'y a qu'un `timestamp`) : `uploadDate` vaut donc `null`.
   - `videoUrl.ts` : valide qu'une URL de vidéo est bien sur `youtube.com`/`youtu.be` (formats `watch`/`shorts`/`live`/court) avant de la transmettre à yt-dlp. N'accepte aucun autre domaine : yt-dlp sait suivre des centaines de sites via un extracteur générique capable de récupérer une URL quelconque, ce qui en ferait un relais SSRF si cette validation n'existait pas.
   - `downloadPlan.ts` : fonctions pures construisant les arguments yt-dlp selon le mode (vidéo/audio/miniature) et parsant la progression (`[download]  42.0% ...`) depuis stdout. Toujours un séparateur `--` avant l'URL (même défense qu'au-dessus).
   - `QueueService.ts` : file d'attente en mémoire, exécution avec concurrence bornée (`MAX_CONCURRENT_DOWNLOADS`, défaut 2). Chaque élément a son propre sous-dossier sous `TMP_DIR`, supprimé après échec/annulation ou après livraison du fichier au client (`consumeCompletedFile`/`consumeAllCompletedFiles` -> `onSent`, logique de livraison partagée via `buildDelivery`) : le serveur ne conserve jamais durablement les fichiers. `title`/`thumbnailUrl` sont de simples informations transmises par l'appelant à `enqueue()` (purement informatif, jamais utilisés pour construire la commande yt-dlp) et renvoyées telles quelles dans la vue publique.
 - Le serveur sert aussi les fichiers statiques de `client/dist` via `@fastify/static`.
-- Tests : Vitest (`server/test/`). Trois niveaux : fonctions pures testées directement (`downloadPlan.ts`, `videoUrl.ts`), services testés avec `ytDlpRunner` mocké mais un vrai système de fichiers temporaire (`QueueService.test.ts`, plus réaliste qu'un mock fs), et routes testées via `app.inject()`. Les trois niveaux comptent : un test de service avec un exemple d'entrée mal choisi avait laissé passer une regex de validation trop permissive (`--exec` accepté), repérée seulement par le test de route avec un autre exemple (voir `channelDiscoveryService.test.ts`/`channelRoute.test.ts`). Les mocks de sortie yt-dlp doivent reproduire la **forme réelle** observée, pas la forme théorique (voir le bug des miniatures ci-dessus) : les fixtures de `playlistDiscoveryService.test.ts` reprennent la sortie réelle de `yt-dlp --flat-playlist -J` (yt-dlp 2026.07.04) - relevée en lançant le vrai binaire (`downloader/yt-dlp.exe`, non versionné) via une entrée locale de `.claude/launch.json` (`YTDLP_PATH`), aussi utilisée pour vérifier la fonctionnalité de bout en bout dans le navigateur. Helpers communs (`waitFor`, `extractOutputDir`) factorisés dans `test/helpers.ts` - `waitFor` accepte un prédicat sync ou async (un prédicat async passé à une version qui n'attendait que du sync serait toujours vu comme "vrai" immédiatement, puisqu'un objet Promise est truthy).
+- Tests : Vitest (`server/test/`). Trois niveaux : fonctions pures testées directement (`downloadPlan.ts`, `videoUrl.ts`), services testés avec `ytDlpRunner` mocké mais un vrai système de fichiers temporaire (`QueueService.test.ts`, plus réaliste qu'un mock fs), et routes testées via `app.inject()`. Les trois niveaux comptent : un test de service avec un exemple d'entrée mal choisi avait laissé passer une regex de validation trop permissive (`--exec` accepté), repérée seulement par le test de route avec un autre exemple (voir `channelDiscoveryService.test.ts`/`channelRoute.test.ts`). Les mocks de sortie yt-dlp doivent reproduire la **forme réelle** observée, pas la forme théorique (voir le bug des miniatures ci-dessus) : les fixtures de `playlistDiscoveryService.test.ts` reprennent la sortie réelle de `yt-dlp --flat-playlist -J` (yt-dlp 2026.07.04) - relevée en lançant le vrai binaire (`downloader/yt-dlp.exe`, non versionné) via une entrée locale de `.claude/launch.json` (`YTDLP_PATH`), aussi utilisée pour vérifier la fonctionnalité de bout en bout dans le navigateur. `test/fakeYtDlp.ts` simule un yt-dlp en flux (le test émet les lignes une à une et espionne `pause`/`resume` d'un faux stdout) pour tester `SearchSession`/`SearchService`/la route sans réseau ; le comportement du tube réel (une pause arrête bel et bien yt-dlp) n'est **pas** testé automatiquement - un enfant `node` écrit de façon synchrone dans un tube sous POSIX mais asynchrone sous Windows, donc un tel test ne serait pas portable - il a été mesuré à la main avec le vrai yt-dlp. Helpers communs (`waitFor`, `extractOutputDir`) factorisés dans `test/helpers.ts` - `waitFor` accepte un prédicat sync ou async (un prédicat async passé à une version qui n'attendait que du sync serait toujours vu comme "vrai" immédiatement, puisqu'un objet Promise est truthy).
 
 ## Frontend (`client/`)
 
 - TypeScript vanilla, pas de framework. Chaque vue = un dossier avec `Vue.ts` / `Vue.html` / `Vue.scss` (gabarit importé comme chaîne brute, style Sass importé et compilé).
 - Build via `build.mjs` (esbuild), pas d'outil de build plus lourd (Vite, webpack) : le script compile `src/app.ts` en bundle ESM, copie `src/index.html`, et compile/regroupe les `.scss` importés en un `app.css` voisin (plugin esbuild maison qui délègue au paquet `sass`). Cible ES2022 (nécessaire pour `Error.cause`, utilisé dans `api/`).
 - Pas de router : `src/shell/Shell.ts` monte deux vues fixes côte à côte (`views/downloadForm/`, `views/queuePanel/`), reliées par un callback simple (`onItemQueued`) plutôt qu'un bus d'événements généraliste - au-delà de deux vues qui coexistent sur un seul écran, un vrai routeur deviendrait nécessaire.
-- `src/api/` : clients fetch vers le backend (`channelApi.ts`, `playlistApi.ts`, `queueApi.ts`), avec leurs propres types DTO (`videoDto.ts` pour la vidéo listée, commune aux chaînes et aux playlists) - pas de paquet de types partagé avec `server/` (monorepo simple, pas de workspace npm).
+- `src/api/` : clients fetch vers le backend (`channelApi.ts`, `playlistApi.ts`, `searchApi.ts`, `queueApi.ts`), avec leurs propres types DTO (`videoDto.ts` pour la vidéo listée et la page de vidéos, communes aux chaînes, playlists et recherches) - pas de paquet de types partagé avec `server/` (monorepo simple, pas de workspace npm).
+- `src/searchLimit.ts` : `parseSearchLimit()`, fonction pure qui lit le champ « Limite » du formulaire de recherche (entier >= 1, sinon « pas de limite »).
 - `src/playlistUrl.ts` : `isPlaylistUrl()`, fonction pure qui aiguille la saisie (lien de playlist -> parcourir ses vidéos, sinon -> ajouter la vidéo). Les mêmes domaines que le serveur, qui reste l'autorité de validation ; un lien `watch?v=...&list=...` n'est volontairement pas une playlist (comme côté serveur).
-- `src/views/downloadForm/` : formulaire d'ajout, deux entrées possibles partageant un même sélecteur de mode (vidéo/audio/miniature + options) : (1) un champ « URL (vidéo ou playlist) » - un lien de vidéo est ajouté directement à la file, un lien de playlist charge ses vidéos via `GET /api/playlist` ; (2) la recherche de chaîne via `GET /api/channel`. Les deux alimentent **une même zone de résultats** (`createResultsView`) : statut, une ligne par vidéo avec son bouton « Ajouter », et pour une playlist seulement un bouton « Tout ajouter à la file ». Le mode courant est lu depuis le DOM à l'ajout, pas stocké en état séparé (lu **une seule fois** au début d'un ajout groupé, pour ne pas mélanger les modes au sein d'un lot).
+- `src/views/downloadForm/` : formulaire d'ajout, trois entrées possibles partageant un même sélecteur de mode (vidéo/audio/miniature + options) : (1) un champ « URL (vidéo ou playlist) » - un lien de vidéo est ajouté directement à la file, un lien de playlist charge ses vidéos via `GET /api/playlist` ; (2) la recherche YouTube globale (mots-clés + « Limite » optionnelle) via `/api/search` ; (3) la recherche de chaîne via `GET /api/channel`. Toutes alimentent **une même zone de résultats** (`createResultsView`) : statut, une ligne par vidéo avec son bouton « Ajouter », et pour une playlist seulement un bouton « Tout ajouter à la file » (volontairement absent des recherches : demandé ainsi, et une recherche peut compter des centaines de résultats).
+  - Recherche globale : avec une **limite** renseignée, tous les résultats arrivent d'un coup (`max` = `limit` = N, une seule page) ; **sans limite**, la liste défile à l'infini (`showPaged`) : un élément « sentinelle » en fin de liste, observé par un `IntersectionObserver` dont la racine est la liste elle-même (marge de 300 px pour charger un peu avant la fin), déclenche le chargement de la page suivante (`nextOffset` fourni par le serveur, pages de 20). Après chaque page l'observateur est **réarmé** (`unobserve` puis `observe`) : sans cela, une page trop courte pour remplir la zone laisserait la sentinelle visible sans qu'aucun nouveau signal ne soit émis. La sentinelle affiche l'état : chargement, erreur avec « Réessayer » (une page en échec ne fait pas perdre celles déjà affichées, et rien ne boucle tout seul), ou « Fin des résultats ». Un indicateur de chargement en cours empêche deux requêtes de page simultanées, et le compteur de « génération » écarte une réponse arrivée après le remplacement de la liste. La recherche reste ouverte côté serveur tant qu'il reste des pages : elle est fermée (`DELETE /api/search/:id`) quand la liste est remplacée ou vidée (rappel `onClose`) et au `pagehide` (fermeture ou rechargement de l'onglet, `fetch` avec `keepalive`) ; à défaut, l'expiration serveur (10 min) s'en charge. Le mode courant est lu depuis le DOM à l'ajout, pas stocké en état séparé (lu **une seule fois** au début d'un ajout groupé, pour ne pas mélanger les modes au sein d'un lot).
   - « Tout ajouter à la file » enchaîne des `POST /api/queue` **séquentiels** côté client (pas d'endpoint groupé : un corps de plusieurs milliers d'éléments dépasserait la limite par défaut de Fastify, et le rythme séquentiel conserve l'ordre de la playlist dans la file). Les lignes déjà ajoutées (bouton désactivé) sont ignorées, donc aucun doublon ; un échec sur une vidéo n'interrompt pas les suivantes - en fin de lot le nombre d'échecs et le premier message d'erreur sont affichés, seules les lignes en échec redeviennent ajoutables, et relancer le bouton ne réajoute que celles-là. Un compteur de « génération » (incrémenté à chaque remplacement de la liste) empêche un lot encore en cours sur une ancienne liste de modifier l'affichage de la nouvelle. Pas de boîte de confirmation : le nombre de vidéos est affiché dans le statut juste à côté du bouton.
   - Miniatures de résultats en `loading="lazy"` : une playlist ou une chaîne peut compter des centaines de vidéos (1607 mesurées), sans quoi chaque miniature serait demandée d'un coup. Pas appliqué dans la file d'attente, dont la liste est reconstruite à chaque sondage.
 - `src/views/queuePanel/` : sonde `GET /api/queue` toutes les 1,5s (pas de push temps réel pour l'instant, voir Statut) et affiche chaque élément (miniature si connue, titre ou URL à défaut, statut, barre de progression, erreur). Un même bouton retire l'élément quel que soit son état - libellé "Annuler" s'il est en attente/en cours, "Supprimer" une fois terminé (`DELETE /api/queue/:id` gère les deux cas côté serveur). Lien "Télécharger" natif uniquement si un fichier est encore disponible ; bouton "Tout télécharger (.zip)" dans l'en-tête (visible dès qu'au moins un fichier est prêt) qui déclenche un unique téléchargement zip via `GET /api/queue/download-all` - remplace une première version qui déclenchait un téléchargement par fichier avec un décalage entre chacun (fonctionnait, mais le zip évite complètement le blocage navigateur sur téléchargements multiples plutôt que de le contourner). Tous les liens de téléchargement (individuel et groupé) portent `target="_blank" rel="noopener"` : filet de sécurité si jamais rien n'est disponible côté serveur au moment du clic (état changé entre le rendu et le clic), l'éventuelle réponse d'erreur s'ouvre dans un nouvel onglet plutôt que de remplacer l'application. Expose `refresh()` pour un rafraîchissement immédiat après un ajout.
 - Piège CSS relevé en testant dans un vrai navigateur (pas seulement les tests) : un attribut `hidden` combiné à une règle `display: flex` sur le même sélecteur se fait écraser par cette règle (même spécificité, la feuille de l'auteur gagne sur celle du user-agent) - toujours ajouter `&[hidden] { display: none; }` quand un conteneur togglé porte aussi un `display` explicite.
 - Layout en hauteur pleine page (`html`/`body`/`.shell` à `height:100%`/`100vh`, `overflow:hidden` sur `body`) : la page elle-même ne défile jamais, seules `download-form__results` et `queue-panel__list` le font (chacune `flex:1 1 0; min-height:0; overflow-y:auto` dans un parent qui propage `height:100%`/`min-height:0` depuis `.shell__panel`). `min-height: 0` est nécessaire à *chaque* niveau flex descendant - un enfant flex ne rétrécit jamais sous la taille de son contenu par défaut, ce qui ferait déborder la page entière au lieu de faire défiler juste la liste. Chaque vue neutralise le grow/shrink de ses enfants directs non-scrollables via `> * { flex: 0 0 auto; }`, puis la règle plus spécifique de l'élément scrollable (même spécificité, déclarée après donc prioritaire) le fait remplir l'espace restant.
+  - Filet pour les écrans courts (ajouté avec le troisième formulaire, dont les ~65 px de plus laissaient à la liste ~104 px, soit une seule ligne, à 1366x650) : une liste non vide (`&:not(:empty)`) garde `min-height: 13rem` (~2 lignes), et `.download-form` passe en `overflow-y: auto`, de sorte que sur un écran trop court c'est **la colonne du formulaire qui défile** au lieu de rogner la liste ou des champs (la page, elle, ne défile toujours jamais). Sans effet tant que tout tient. Mesuré (DOM) : 1920x950 -> liste de 406 px, colonne fixe ; 1366x650 -> liste de 208 px, colonne défilante ; 800x450 -> idem, tout reste atteignable. Si trois entrées empilées deviennent trop gourmandes, des onglets (URL / recherche / chaîne) libéreraient ~130 px.
 - Tests : Vitest (`client/test/`), uniquement sur les fonctions pures (`format.ts`) pour l'instant - pas de configuration jsdom, le câblage DOM (formulaires, rendu de liste) est vérifié manuellement dans le navigateur plutôt que testé automatiquement.
 - `src/styles/base.scss` : palette et styles de base partagés (custom properties CSS sur `:root`, pas de `$variables` Sass - une variable Sass ne traverserait pas les fichiers, chaque vue étant compilée/importée séparément ; une custom property CSS si, puisqu'elle se résout à l'exécution dans le navigateur une fois tout le CSS regroupé par esbuild). Importé une fois depuis `app.ts`. Thème sombre/clair automatique selon `prefers-color-scheme` (pas de bascule manuelle) : un unique bloc `@media (prefers-color-scheme: dark)` redéfinit les mêmes custom properties dans `:root` - fonctionne partout car aucune autre feuille ne code de couleur en dur (vérifié : toutes passent par `var(--color-*)`).
 
@@ -52,6 +56,7 @@ Pas de `docker-compose.yml` pour l'instant (une seule image, pas encore de dépe
 
 - `GET /health` : statut du service (utilisé par le `HEALTHCHECK` Docker).
 - `GET /api/channel?channel=<@handle|URL>&section=<videos|streams>&keywords=<a,b>` : liste les vidéos/streams d'une chaîne, filtrés par mots-clés (ET, insensible à la casse) sur le titre. `section` par défaut `videos`. Réponses : `200 { videos: [...] }`, `400` si `channel` est absent/invalide, `502` si yt-dlp échoue.
+- `POST /api/search` (`{ query, max?, limit? }`), `GET /api/search/:id?offset=&limit=`, `DELETE /api/search/:id` : recherche YouTube globale paginée (voir `SearchSession`). `POST` ouvre une recherche et retourne `201 { id, videos, nextOffset }` (première page, `limit` par défaut 20 ; `max` plafonne le nombre total de résultats, absent = jusqu'à la fin de ceux de YouTube, ~590) ; `GET` retourne `200 { videos, nextOffset }` pour la page qui commence à `offset` ; `nextOffset` vaut `null` en fin de résultats (la dernière page peut être vide : la page pleine qui tombe pile sur le dernier résultat ne sait pas encore que yt-dlp a fini). La recherche est **refermée par le serveur** dès que la dernière page a été servie. Réponses d'erreur : `400` (requête vide, de plus de 200 caractères ou avec caractère de contrôle ; `limit`/`max`/`offset` hors bornes), `404` (recherche inconnue, expirée ou déjà refermée - message « relancez-la »), `502` (yt-dlp échoue avant le moindre résultat). `DELETE` répond `204` (ou `404` si déjà refermée).
 - `GET /api/playlist?url=<lien de playlist>` : liste les vidéos d'une playlist YouTube, dans l'ordre de la playlist. Réponses : `200 { title, videos: [...] }` (`title` vaut `null` si inconnu, `videos` est vide pour une playlist vide - même forme de vidéo que `/api/channel`), `400` si `url` est absent ou n'est pas un lien de playlist YouTube (y compris un lien de vidéo, même avec un paramètre `list`), `502` si yt-dlp échoue (playlist introuvable ou privée, binaire absent, sortie illisible).
 - `POST /api/queue` : ajoute un élément (`{ url, title?, thumbnailUrl?, mode: "video"|"audio"|"thumbnail", subtitles?, embedThumbnail?, audioFormat? }`). `title`/`thumbnailUrl` sont purement informatifs (affichage), jamais utilisés pour construire la commande yt-dlp. `201 { item }`, `400` si l'URL n'est pas une URL de vidéo YouTube reconnue.
 - `GET /api/queue` : liste tous les éléments (`{ items: [...] }`), avec leur `status` (`pending`/`running`/`completed`/`failed`/`cancelled`), `progress` (0-100, best-effort) et `error`.
@@ -72,5 +77,5 @@ Biome.js à la racine (`biome.json`), applique aux deux paquets (`server/src`, `
 
 ## Statut
 
-- Fait : infrastructure (serveur, Docker, CI), découverte de chaîne (`GET /api/channel`) et de playlist (`GET /api/playlist`, ajout par vidéo ou d'un coup), file d'attente + téléchargement vidéo/audio/miniature avec concurrence bornée (`/api/queue*`), frontend complet (formulaire d'ajout + file d'attente, sondage 1,5s).
+- Fait : infrastructure (serveur, Docker, CI), découverte de chaîne (`GET /api/channel`) et de playlist (`GET /api/playlist`, ajout par vidéo ou d'un coup), recherche YouTube globale paginée en défilement infini (`/api/search*`), file d'attente + téléchargement vidéo/audio/miniature avec concurrence bornée (`/api/queue*`), frontend complet (formulaire d'ajout + file d'attente, sondage 1,5s).
 - À venir (PR successives) : notifications temps réel (WebSocket, progression poussée plutôt que sondage), tests client sur le câblage DOM (jsdom), sélection de qualité vidéo (actuellement fixe : meilleur mp4 disponible).
-- 
2.45.2