@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

package/src/docs/misc/publisher-get-immutability-docs-recheck.json

@@ -0,0 +1,13 @@
+{
+  "generatedAt": "2026-10-29T14:46:01.703Z",
+  "baseA": "https://127.0.0.1:3010",
+  "baseB": "https://127.0.0.1:3011",
+  "pageCount": 43,
+  "pagesWithDiffs": 0,
+  "diffs": [],
+  "summary": {
+    "errors": [],
+    "warns": [],
+    "infos": []
+  }
+}

package/src/docs/misc/publisher-get-immutability-study.md

@@ -0,0 +1,229 @@
+# Étude — immutabilité DataProvider / `get()` (REDMINE-79567)
+
+> **Nature :** étude d’opportunité + ADR de direction.  
+> Branche : `79567_publisher_get_immutability_study`.  
+> **Recadrage (oct. 2026) :** la cible n’est plus un empilement de gardes opt-in, mais un **store immutable** clair.
+
+## 0. Décision de direction (ADR)
+
+### Contrat cible
+
+> **Le publisher possède les données. On ne mute jamais. On remplace.**
+
+| API | Comportement |
+|-----|----------------|
+| `set(value)` / `update(recipe)` | Ownership à l’entrée : copie (clone / Immer `produce`), commit, puis **freeze** (ou équivalent) de la valeur stockée |
+| `get()` | Vue **lecture seule** de la valeur commitée — muter → erreur nette |
+| Écritures | Uniquement `set` / `setIn` / `update` — plus de patch in-place de `_value_` |
+| Comportement | **Un seul** en prod (pas de mode « soft » comme design final) |
+
+### Ce qu’on ne garde pas comme design produit
+
+Empiler `DeepReadonly` + `strictGet` warn/throw + clone parfois = **pansements** autour d’un moteur encore mutable. Utile en **radar de migration**, pas comme architecture cible.
+
+### Conséquence technique
+
+Refonte du moteur `PublisherProxy` : plus de `_value_[k] = …` / `delete _value_[k]` / sync parent par mutation. Updates **immutables** (Immer ou `setIn` maison) sur tout chemin d’écriture (y compris traps Proxy / sous-proxies).
+
+---
+
+## 1. Problème (rappel)
+
+Aujourd’hui `get()` renvoie la **référence live** de `_value_`. Une mutation locale (`cart.items.push…`) contourne `set` et les listeners → état partagé / UI désynchronisés.
+
+Écritures « officielles » (`set`, sous-proxies, `publisher.clé = …`) notifient ; le trou est **get + mutation** et **réutilisation de la ref passée à `set`**.
+
+Fichier central : `src/core/utils/PublisherProxy.ts`.
+
+---
+
+## 2. Alternatives évaluées
+
+| | Approche | Verdict |
+|---|----------|---------|
+| A | Freeze live **sans** refonte `set` | **Non** — casse le moteur actuel |
+| B | Clone / Proxy readonly à chaque `get()` | **Non** comme défaut — cher, identité cassée |
+| C | Clone défensif seul sans freeze | **Insuffisant** — n’enseigne pas le contrat |
+| D | `strictGet` opt-in warn/throw | **Outil de migration** seulement |
+| E | Lint / convention seule | **Complément**, pas une garantie |
+| F | **Store immutable** (set ownership + get readonly + updates immutables) | **Cible** |
+
+### Perf (ordre de grandeur)
+
+1. Status quo / typage seul — 0 runtime  
+2. Proxy `strictGet` — faible, sur `get`  
+3. Freeze **après** commit immutable — lectures cheap ; coût sur **écritures**  
+4. Deep clone à chaque `get` — à éviter  
+5. Freeze live + mute in-place — incompatible  
+
+Le modèle F met le coût là où il est acceptable (écritures), avec une sémantique nette.
+
+---
+
+## 3. Cible — store immutable (détail)
+
+### 3.1 Moteur Concorde à réécrire
+
+- `set` / traps Proxy / sync parent-enfant : **immutable updates** uniquement.  
+- Après commit : freeze deep (ou structure déjà immutable).  
+- `get()` / `onAssign` : renvoient la valeur frozen (même ref tant que le commit n’a pas changé → `get() === get()` OK entre deux `set`).  
+- API `update(draft => { … })` (Immer) recommandée pour les updates nested ergonomiques.  
+- Valeurs non clonables (`EventSource`, instances, fonctions) : **hors store** ou wrappers documentés (ex. Mercure / laqueue).
+
+### 3.2 Surface apps
+
+- Interdit : muter après `get`, muter la ref passée à `set`, `.sort()` in-place dans `onAssign`.  
+- Obligatoire : `const next = …; set(next)` ou `update(draft => …)`.
+
+### 3.3 Rôle du spike actuel sur cette branche
+
+Déjà présent (ne pas confondre avec la cible) :
+
+- `DeepReadonly` sur `get` / `onAssign` (typage).  
+- `PublisherManager.strictGet = "off" | "warn" | "throw"` (Proxy sur le résultat de `get`, **sans** freeze de `_value_`).
+
+→ **Radar** pour lister les mutations pendant la migration vers F. Destiné à disparaître ou à se réduire une fois le moteur immutable en place.
+
+---
+
+## 4. Canal de livraison — dist-tag npm (reco)
+
+Oui : publier le chantier sur un **dist-tag npm dédié**, pas sur `latest`, le temps d’un usage approfondi.
+
+### Pourquoi c’est adapté ici
+
+- Breaking **moteur + contrat** : les apps ne doivent pas le prendre par un bump semver « normal » par erreur.  
+- Billetterie / smart-belt / lecovoit / laqueue peuvent opter **explicitement** :  
+  `"@supersoniks/concorde": "npm:@supersoniks/concorde@immutable"`  
+  ou version `5.x.x-immutable.n` + tag `immutable`.  
+- CI / smokes sur le tag sans bloquer prod `latest`.  
+- Feedback réel (perf panier, Mercure, placement) avant major.
+
+### Proposition de tags
+
+| Tag | Usage |
+|-----|--------|
+| `latest` | Ligne stable actuelle (mutable + éventuellement radar `strictGet` si un jour mergé à part) |
+| `immutable` (ou `next-immutable`) | Ligne de dev du store immutable — **usage approfondi** |
+| (plus tard) `latest` major | Quand la migration Billetterie + checklist sont vertes |
+
+Versions du type `6.0.0-immutable.1`, `.2`, … (prerelease) : claires dans le lockfile, republish fréquentes OK.
+
+### Ce qu’il ne faut pas faire
+
+- Remplacer `latest` trop tôt.  
+- Multiplier les tags flous (`test`, `julien`, …) — **un** tag métier `immutable`.  
+- Laisser `strictGet` opt-in comme « la » release : ce n’est pas le produit final.
+
+### Avis
+
+**Go dist-tag `immutable`.** C’est le bon niveau de netteté : chantier puissant isolé, adoption volontaire, mesure avant major. Le spike `strictGet` peut vivre sur la même branche/tag comme aide à la migration, documenté comme temporaire.
+
+---
+
+## 5. Impact consommateurs (rappel audit)
+
+| Projet | Volume / note | Priorité migration |
+|--------|----------------|-------------------|
+| **la-billetterie** | ~860 fichiers dp, ~216 get / ~392 set ; cart, AC, placing, forms | **P0** |
+| smart-belt-drive | Peu de get ; `onAssign` + `.sort()` in-place | P1 |
+| lecovoit | Peu de get, surtout set | P2 |
+| laqueue | Très peu ; Mercure / non-clonables à traiter | P2 |
+| link / starter | Faible | P3 |
+
+Zones Billetterie chaudes : `access-control/**`, `utils/cart.ts` + `components/cart/**`, `placing/**`, subscription / tarifs, forms, ~300 `onAssign`, legacy `lb_placement` JS.
+
+---
+
+## 6. Plan recadré
+
+```
+Phase 0  Étude + ADR direction immutable ✅
+Phase 1  Radar DeepReadonly + strictGet ✅
+Phase 2  Moteur immutable sur branche ✅ → publish npm tag `immutable`
+Phase 3  App pilote sur le tag
+Phase 4  Billetterie (puis SBD, lecovoit, laqueue) sur le tag
+Phase 5  Major Concorde sur `latest` quand go-live OK
+```
+
+### Critères go-live major
+
+- Smokes Billetterie (panier, placing, AC, forms, abonnements, submit, localStorage) verts sur le tag.  
+- Pas de régression perf au-delà du seuil convenu sur écritures panier / scan.  
+- Doc dataFlow = contrat immutable uniquement.  
+- Stratégie explicite pour non-clonables.  
+- `strictGet` retiré ou réduit à un assert interne inutile en prod.
+
+---
+
+## 7. Verdict
+
+| Question | Réponse |
+|----------|---------|
+| Problème de contrat réel ? | **Oui** |
+| Design cible ? | **Store immutable** (F), pas la pile de gardes |
+| Freeze live sans refonte ? | **Non** |
+| Clone à chaque `get` ? | **Non** |
+| `strictGet` / `DeepReadonly` ? | **Radar de migration**, pas la cible |
+| Publier sur un tag npm dédié pendant le dev ? | **Oui — `immutable`** |
+| Ce ticket 79567 | Étude + direction ; chantier moteur = ticket(s) d’implémentation + tag |
+
+## 8. Suite immédiate
+
+1. Publish dist-tag npm `immutable` depuis cette branche.  
+2. App pilote (starter / module Billetterie borné).  
+3. Migration Billetterie + smokes.  
+4. Major sur `latest` quand critères § go-live OK.
+
+## 9. Implémenté sur la branche
+
+- Helpers : `src/core/utils/immutableValue.ts` (`takeOwnership`, `deepFreeze`, `setAtKey`, `deleteAtKey`)
+- `PublisherProxy.set` : ownership + freeze ; sync parent immutable (plus de `_value_[k] =`)
+- Traps Proxy `set` / `deleteProperty` : via `set` / rebuild
+- `get()` : valeur frozen (même ref jusqu’au prochain `set`)
+- Non-clonable : warn + stocké tel quel sans freeze
+- Specs : `immutableValue.spec.ts`, `publisherImmutable.spec.ts`, etc.
+- Correctifs doc/runtime déjà livrés sur la branche : boucle `sonic-list` / `_metadata_`, clone SDUI, shallow-copy submit, `sameValueAs` en dot-notation
+
+## 10. Crawl docs rendu — branche vs `master` (29 oct. 2026)
+
+Comparaison automatisée des pages de la nav docs : **A** = branche `79567_publisher_get_immutability_study`, **B** = `master`.
+
+Métriques : `bodyChars`, sections `h2`, blocs `sonic-code` (radios/inputs/lists/sdui + hauteurs interactives), `docs-lit-demo`, erreurs console (hors bruit SW 404).
+
+Artefacts JSON (bruts) :
+
+- `src/docs/misc/publisher-get-immutability-docs-crawl.json` — 68 pages (crawl parallèle initial)
+- `src/docs/misc/publisher-get-immutability-docs-recheck.json` — 43 pages à risque (crawl séquentiel)
+
+### Résultat
+
+| Passe | Pages | Diffs structurantes (error) | Notes |
+|-------|------:|----------------------------:|-------|
+| Recheck séquentiel | 43 | **0** | Pas de contrôle disparu, pas de preview collapsée, pas d’erreur freeze |
+| Crawl parallèle 68 | 68 | **0** error | 5 pages avec diffs info/warn uniquement |
+
+### Diffs relevés (pas de régression immutable)
+
+| Page | Nature | Action |
+|------|--------|--------|
+| `/core/components/ui/form/radio` | Section **Nested keys** ajoutée sur la branche | Doc volontaire — à garder ou retirer selon review doc |
+| `/core/components/ui/form/input` | Idem Nested keys + `sameValueAs` dot-notation | Idem |
+| `/docs/directives/t` | Contenu plus riche sur A (sections Import/Usage/…) | Hors immutable — écart de contenu markdown ; vérifier si attendu sur la branche |
+| `/docs/misc/dataProviderKey` | Faux positif crawl parallèle (`bodyChars: 0`) | **Revalidé OK** au recheck / visite manuelle (2615 chars, 9 codes) |
+| `/docs/misc/html-integration` | Console `498` ponctuelle au crawl parallèle | **Revalidé OK** (même rendu A/B, 838 chars) — bruit réseau, pas un gel publisher |
+
+### Correctifs déjà faits (hors crawl, signalés avant)
+
+- `sonic-list` boucle infinie (`_metadata_`)
+- SDUI mute sur descripteur frozen
+- Submit `delete` sur `get()` frozen
+
+### À corriger ultérieurement (backlog crawl)
+
+1. **Décider** du sort des sections Nested keys radio/input (ajoutées pendant le debug) — doc only.  
+2. **Vérifier** l’écart markdown `docs/directives/t` vs `master` (pas lié au store).  
+3. Rejouer le crawl séquentiel après les prochains correctifs moteur avant publish tag `immutable`.  
+4. Optionnel : intégrer le script de crawl dans un smoke CI docs (ports dédiés + Chromium system).
+
+**Verdict crawl :** pas de régression de rendu docs imputable au store immutable sur l’échantillon recheck (43 pages). Les seuls écarts stables sont documentaires (Nested keys, éventuellement `t`).

package/src/docs/mock-api/api-config-mock.ts

@@ -15,6 +15,11 @@ export const DOCS_MOCK_EVENTS_API_TOKEN = "docs-mock-events-token";
 const WORDING_CATALOG: Record<string, Record<string, string>> = {
   "api-config.greeting": { fr: "Bonjour", en: "Hello" },
   "api-config.farewell": { fr: "Au revoir", en: "Goodbye" },
+  "flight.boarding": { fr: "Embarquement immédiat", en: "Now boarding" },
+  "flight.gate": {
+    fr: "Rendez-vous porte <strong>B12</strong>",
+    en: "Please proceed to gate <strong>B12</strong>",
+  },
   "api-config.hint": {
     fr: "Libellés servis par le mock /wording/labels",
     en: "Labels served by mock /wording/labels",

package/src/docs/mock-api/fixtures.ts

@@ -97,281 +97,3 @@ export const DOCS_GEO_COMMUNES: GeoCommuneRow[] = [
   { nom: "Montpellier", code: "34172" },
   { nom: "Rennes", code: "35238" },
 ];
-
-/** JokeAPI-style content flags (checkbox / radio / switch blacklist demos). */
-export type DocsJokeFlagKey =
-  | "nsfw"
-  | "religious"
-  | "political"
-  | "racist"
-  | "sexist"
-  | "explicit";
-
-/** Forme proche de JokeAPI v2 (`key="jokes"` sur sonic-queue / list). */
-export type DocsJokeItem = {
-  categories: string[];
-  createdAt: string;
-  id: number;
-  joke: string;
-  lang: "fr" | "en";
-  flags: Record<DocsJokeFlagKey, boolean>;
-  safe: boolean;
-  type: string;
-  setup?: string;
-  delivery?: string;
-};
-
-const jokeFlags = (
-  partial: Partial<Record<DocsJokeFlagKey, boolean>> = {},
-): Record<DocsJokeFlagKey, boolean> => ({
-  nsfw: false,
-  religious: false,
-  political: false,
-  racist: false,
-  sexist: false,
-  explicit: false,
-  ...partial,
-});
-
-export type DocsJokeApiResponse = {
-  error: boolean;
-  amount: number;
-  jokes: DocsJokeItem[];
-};
-
-const SAMPLE_JOKES: DocsJokeItem[] = [
-  {
-    categories: ["Programming"],
-    createdAt: "2020-01-01 00:00:00",
-    id: 1,
-    lang: "en",
-    joke: "Why do programmers prefer dark mode? Because light attracts bugs.",
-    flags: jokeFlags(),
-    safe: true,
-    type: "single",
-  },
-  {
-    categories: ["Misc"],
-    createdAt: "2020-01-02 00:00:00",
-    id: 2,
-    lang: "en",
-    joke: "I told my computer I needed a break — it said: no problem, I'll go to sleep.",
-    flags: jokeFlags({ nsfw: true }),
-    safe: false,
-    type: "single",
-  },
-  {
-    categories: ["Pun"],
-    createdAt: "2020-01-03 00:00:00",
-    id: 3,
-    lang: "en",
-    joke: "Concorde docs run offline: even the API is a local joke.",
-    flags: jokeFlags(),
-    safe: true,
-    type: "single",
-  },
-  {
-    categories: ["Animals"],
-    createdAt: "2020-01-04 00:00:00",
-    id: 4,
-    lang: "en",
-    joke: "The dog ate my homework and my pull request.",
-    flags: jokeFlags({ political: true }),
-    safe: true,
-    type: "single",
-  },
-  {
-    categories: ["Animals", "Pun"],
-    createdAt: "2020-01-05 00:00:00",
-    id: 5,
-    lang: "fr",
-    joke: "Quel est le chien préféré des développeurs ? Le labrador Retriever.",
-    flags: jokeFlags(),
-    safe: true,
-    type: "single",
-  },
-  {
-    categories: ["Animals"],
-    createdAt: "2020-01-06 00:00:00",
-    id: 6,
-    lang: "fr",
-    joke: "Un chat et un chien discutent de TypeScript : le chien dit « woof », le chat compile.",
-    flags: jokeFlags({ racist: true }),
-    safe: false,
-    type: "single",
-  },
-  {
-    categories: ["Misc"],
-    createdAt: "2020-01-07 00:00:00",
-    id: 7,
-    lang: "fr",
-    joke: "Pourquoi les blagues offline sont-elles fiables ? Parce qu'elles passent par le Service Worker.",
-    flags: jokeFlags({ religious: true }),
-    safe: true,
-    type: "single",
-  },
-  {
-    categories: ["Programming"],
-    createdAt: "2020-01-08 00:00:00",
-    id: 8,
-    lang: "fr",
-    joke: "Mon compilateur et mon chien : tous deux ignorent mes commandes jusqu'au build.",
-    flags: jokeFlags({ sexist: true }),
-    safe: false,
-    type: "single",
-  },
-  {
-    categories: ["Misc"],
-    createdAt: "2020-01-09 00:00:00",
-    id: 9,
-    lang: "en",
-    joke: "A SQL query walks into a bar, walks up to two tables and asks: Can I join you?",
-    flags: jokeFlags({ explicit: true }),
-    safe: false,
-    type: "single",
-  },
-  {
-    categories: ["Pun"],
-    createdAt: "2020-01-10 00:00:00",
-    id: 10,
-    lang: "fr",
-    joke: "J'ai cherché « chien » dans la doc : le mock API a répondu.",
-    flags: jokeFlags(),
-    safe: true,
-    type: "single",
-  },
-  {
-    categories: ["Misc"],
-    createdAt: "2020-01-11 00:00:00",
-    id: 11,
-    lang: "en",
-    joke: "There are only two hard things in Computer Science: cache invalidation and naming things.",
-    flags: jokeFlags({ political: true, explicit: true }),
-    safe: false,
-    type: "single",
-  },
-  {
-    categories: ["Animals"],
-    createdAt: "2020-01-12 00:00:00",
-    id: 12,
-    lang: "fr",
-    joke: "Le golden retriever a récupéré la donnée du publisher.",
-    flags: jokeFlags({ racist: true, sexist: true }),
-    safe: false,
-    type: "two-liner",
-    setup: "Pourquoi le chien aime Concorde ?",
-    delivery: "Parce qu'il sait fetch.",
-  },
-  {
-    categories: ["Misc"],
-    createdAt: "2020-01-13 00:00:00",
-    id: 13,
-    lang: "en",
-    joke: "My code and my conscience: both have too many warnings.",
-    flags: jokeFlags(),
-    safe: true,
-    type: "single",
-  },
-  {
-    categories: ["Programming"],
-    createdAt: "2020-01-14 00:00:00",
-    id: 14,
-    lang: "en",
-    joke: "Git blame is just a mirror.",
-    flags: jokeFlags({ religious: true, political: true }),
-    safe: false,
-    type: "single",
-  },
-];
-
-/** `blacklistFlags` from queue filter form (comma-separated or repeated param). */
-export function parseBlacklistFlags(url: URL): DocsJokeFlagKey[] {
-  const keys = new Set<DocsJokeFlagKey>();
-  const valid: DocsJokeFlagKey[] = [
-    "nsfw",
-    "religious",
-    "political",
-    "racist",
-    "sexist",
-    "explicit",
-  ];
-  const add = (raw: string) => {
-    raw
-      .split(",")
-      .map((s) => s.trim().toLowerCase())
-      .forEach((part) => {
-        if (valid.includes(part as DocsJokeFlagKey)) keys.add(part as DocsJokeFlagKey);
-      });
-  };
-  url.searchParams.getAll("blacklistFlags").forEach(add);
-  const single = url.searchParams.get("blacklistFlags");
-  if (single) add(single);
-  return [...keys];
-}
-
-/** Exclude jokes that match any blacklisted flag (JokeAPI-style). */
-export function applyJokeBlacklist(
-  jokes: DocsJokeItem[],
-  blacklist: DocsJokeFlagKey[],
-): DocsJokeItem[] {
-  if (!blacklist.length) return jokes;
-  return jokes.filter(
-    (j) => !blacklist.some((flag) => j.flags[flag] === true),
-  );
-}
-
-/** Filtre doc joke queue (`contains`, `lang`, `blacklistFlags` via `dataFilterProvider`). */
-export function filterDocsJokes(
-  jokes: DocsJokeItem[],
-  url: URL,
-): DocsJokeItem[] {
-  let pool = jokes;
-  const contains = url.searchParams.get("contains")?.trim().toLowerCase();
-  if (contains) {
-    pool = pool.filter((j) => {
-      const haystack = [j.joke, j.setup, j.delivery, ...j.categories]
-        .filter(Boolean)
-        .join(" ")
-        .toLowerCase();
-      return haystack.includes(contains);
-    });
-  }
-  const lang = url.searchParams.get("lang")?.trim().toLowerCase();
-  if (lang === "fr" || lang === "en") {
-    pool = pool.filter((j) => j.lang === lang);
-  }
-  pool = applyJokeBlacklist(pool, parseBlacklistFlags(url));
-  return pool;
-}
-
-/**
- * Réponse type JokeAPI v2.
- * - `amount` : taille du lot si pas de `offset`
- * - `offset` + `limit` / `per_page` : pagination (sonic-queue lazy)
- * - `contains`, `lang`, `blacklistFlags` : filtres formulaire (queue « Remove following jokes »)
- */
-export function buildJokeApiResponse(url: URL): DocsJokeApiResponse {
-  const pool = filterDocsJokes(SAMPLE_JOKES, url);
-  const amount = Math.max(
-    1,
-    parseInt(url.searchParams.get("amount") || "10", 10),
-  );
-  const hasOffset = url.searchParams.has("offset");
-  const limit = Math.max(
-    1,
-    parseInt(
-      url.searchParams.get("limit") ||
-        url.searchParams.get("per_page") ||
-        String(amount),
-      10,
-    ),
-  );
-  const offset = Math.max(0, parseInt(url.searchParams.get("offset") || "0", 10));
-  const start = hasOffset ? offset : 0;
-  const count = hasOffset ? limit : amount;
-  const jokes = pool.slice(start, start + count).map((j, i) => ({
-    ...j,
-    id: start + i + 1,
-  }));
-  return { error: false, amount: jokes.length, jokes };
-}

package/src/docs/mock-api/flights.ts

@@ -0,0 +1,89 @@
+/** Fictional flight board for list / queue filter demos (`key="flights"`). */
+export type DocsFlightStatus =
+  | "on-time"
+  | "boarding"
+  | "delayed"
+  | "landed"
+  | "cancelled";
+
+export type DocsFlight = {
+  id: number;
+  code: string;
+  direction: "departures" | "arrivals";
+  airport: string;
+  city: string;
+  time: string;
+  gate: string;
+  status: DocsFlightStatus;
+};
+
+const row = (
+  code: string,
+  direction: DocsFlight["direction"],
+  airport: string,
+  city: string,
+  time: string,
+  gate: string,
+  status: DocsFlightStatus,
+): Omit<DocsFlight, "id"> => ({
+  code,
+  direction,
+  airport,
+  city,
+  time,
+  gate,
+  status,
+});
+
+const FLIGHTS: Omit<DocsFlight, "id">[] = [
+  row("CN 001", "departures", "JFK", "New York", "08:15", "B12", "boarding"),
+  row("CN 014", "departures", "LHR", "London", "08:40", "A03", "on-time"),
+  row("CN 102", "departures", "GIG", "Rio de Janeiro", "09:05", "C21", "delayed"),
+  row("CN 220", "departures", "DKR", "Dakar", "09:30", "C07", "on-time"),
+  row("CN 305", "departures", "IAD", "Washington", "10:10", "B04", "cancelled"),
+  row("CN 412", "departures", "BAH", "Bahrain", "10:45", "D02", "delayed"),
+  row("CN 518", "departures", "SIN", "Singapore", "11:20", "D14", "on-time"),
+  row("CN 633", "departures", "YUL", "Montreal", "12:00", "A11", "on-time"),
+  row("CN 002", "arrivals", "JFK", "New York", "07:50", "B10", "landed"),
+  row("CN 015", "arrivals", "LHR", "London", "08:25", "A05", "landed"),
+  row("CN 103", "arrivals", "GIG", "Rio de Janeiro", "09:15", "C20", "delayed"),
+  row("CN 221", "arrivals", "DKR", "Dakar", "09:55", "C08", "on-time"),
+  row("CN 306", "arrivals", "IAD", "Washington", "10:35", "B06", "on-time"),
+  row("CN 413", "arrivals", "BAH", "Bahrain", "11:05", "D03", "cancelled"),
+  row("CN 519", "arrivals", "SIN", "Singapore", "11:40", "D15", "delayed"),
+  row("CN 634", "arrivals", "YUL", "Montreal", "12:30", "A12", "on-time"),
+];
+
+/**
+ * `GET /flights` — filters:
+ * - `direction`: `departures` · `arrivals`
+ * - `q`: substring on code / city / airport
+ * - `status`: comma-separated statuses to keep (`all` or empty = no filter)
+ * - `offset` + `limit`: pagination for sonic-queue
+ */
+export function buildFlightsResponse(url: URL): { flights: DocsFlight[] } {
+  const p = url.searchParams;
+  let pool = FLIGHTS.map((f, i) => ({ ...f, id: i + 1 }));
+
+  const direction = p.get("direction");
+  if (direction === "departures" || direction === "arrivals") {
+    pool = pool.filter((f) => f.direction === direction);
+  }
+  const q = p.get("q")?.trim().toLowerCase();
+  if (q) {
+    pool = pool.filter((f) =>
+      [f.code, f.city, f.airport].join(" ").toLowerCase().includes(q),
+    );
+  }
+  const statuses = (p.get("status") || "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s && s !== "all");
+  if (statuses.length) {
+    pool = pool.filter((f) => statuses.includes(f.status));
+  }
+
+  const offset = Math.max(0, parseInt(p.get("offset") || "0", 10));
+  const limit = Math.max(1, parseInt(p.get("limit") || "20", 10));
+  return { flights: pool.slice(offset, offset + limit) };
+}

package/src/docs/mock-api/router.ts

@@ -1,8 +1,8 @@
 import { handleApiConfigMockRequest } from "./api-config-mock";
+import { buildFlightsResponse } from "./flights";
 import {
   DOCS_GEO_COMMUNES,
   DOCS_REQRES_USERS,
-  buildJokeApiResponse,
   filterDocsUsers,
   type GeoCommuneRow,
   type ReqresUserResponse,
@@ -291,9 +291,8 @@ export async function handleDocsMockApiRequest(
     });
   }
 
-  const jokeMatch = subPath.match(/^\/jokes\/joke\/([^/]+)$/);
-  if (jokeMatch) {
-    return json(buildJokeApiResponse(url));
+  if (subPath === "/flights") {
+    return json(buildFlightsResponse(url));
   }
 
   return json({ error: "Not found", path: subPath }, { status: 404 });

package/src/docs/mock-api/urls.ts

@@ -7,5 +7,4 @@ export const DOCS_MOCK_REQRES_SERVICE = DOCS_MOCK_API_BASE;
 /** Remplace https://geo.api.gouv.fr/ — chemins `communes?…`. */
 export const DOCS_MOCK_GEO_SERVICE = `${DOCS_MOCK_API_BASE}/geo/`;
 
-/** Remplace https://v2.jokeapi.dev — chemins `joke/Any?…`. */
-export const DOCS_MOCK_JOKES_SERVICE = `${DOCS_MOCK_API_BASE}/jokes`;
+