Plot engine

[ocots]

Rapport : moteur de tracé unifié dans CTBase (CTModels + CTFlows)

Rapport d'étude détaillé. Réfère au
Handbook (PHILOSOPHY.md, RULES.md)
et aux sources : CTModels.jl/ext/ (CTModelsPlots) et
CTFlows.jl/ext/CTFlowsPlots/ (PlotEngine + TrajectoryPlots).
Statut : en attente de validation humaine (décisions D1–D6 à trancher).

---

Partie 1 — Objectif et vision

L'enjeu

Deux implémentations de tracé coexistent dans l'écosystème :

1. CTModels (ext/CTModelsPlots.jl + plot.jl ~1780 lignes + plot_default.jl +
   plot_utils.jl) : monolithe historique, riche fonctionnellement (5 groupes de
   signaux, décorations, grilles de temps multiples, tracés de phase), mais où la
   logique de mise en page, le rendu Plots et le sens métier sont entremêlés.

2. CTFlows (ext/CTFlowsPlots/) : refonte récente déjà séparée en deux couches —
   PlotEngine (moteur générique, domain-free, ~250 lignes) et TrajectoryPlots
   (couche cas : vocabulaire trajectoire → panels). Le moteur y est explicitement
   annoncé comme « destiné à être remonté dans CTBase ».

Objectif : un moteur unique, complet et conséquent hébergé par CTBase, et des
couches cas simples dans CTModels et CTFlows (et demain CTDirect, CTParser…). Le
moteur absorbe tout ce qui est mise en page, style, heuristiques et rendu ; les couches
cas ne font plus que : nommer, échantillonner, choisir un gabarit.

Les deux exigences structurantes

1. Layout général : la mise en page de CTModels est strictement plus riche que ce
   que le PlotEngine de CTFlows sait faire (blocs de hauteurs inégales, colonnes
   appariées + blocs empilés simultanément, grille 2×2 en :group). Il faut donc
   plusieurs niveaux de définition d'un layout, du mot-clé simple à l'arbre
   pondéré général (§ Partie 4).

2. Séparation backend : isoler dès maintenant ce qui est spécifique à Plots.jl de
   ce qui ne l'est pas, pour qu'un backend Makie.jl soit un jour possible sans
   toucher ni à l'IR ni aux couches cas (§ Partie 5). Concrètement : une
   représentation intermédiaire (IR) de figure — pure donnée, zéro dépendance — dans
   CTBase/src, et un renderer Plots dans une extension CTBase/ext.

---

Partie 2 — État des lieux

2.1 CTFlows : PlotEngine + TrajectoryPlots

Le moteur (PlotEngine/, ~250 lignes)

Élément	Contenu
Panel	l'unité d'entrée unique : title, labels::Vector{String}, data::Matrix{Float64} (n_times × n_comp), style::NamedTuple
render(times, panels; …)	crée une figure ; render!(p, times, panels; …) superpose sur une figure existante (ciblage subplot=i)
Layouts	:split (un subplot par composante) / :group (un subplot par panel, composantes superposées + légende)
Placement (:split)	:stacked (une colonne) / :paired (colonnes côte à côte, ex. state | costate) — repli sur :stacked si hauteurs inégales
Temps	grille unique partagée par tous les panels ; :default / :normalize
Conventions	titre sur la cellule du haut, xlabel temps sur la cellule du bas, ylabel par composante, pas de légende en :split
Heuristiques	taille (180px/ligne, 340px/col, min 600), garde ylims pour séries constantes (tol. absolue 1e-8), marges mm, fontes
Erreurs	Exceptions.IncorrectArgument structurées (layout, time, panels vides)

La couche cas (TrajectoryPlots/, ~260 lignes)

• vocabulaire :state/:costate/:control + clean (pluriels, doublons) ;
• contrat _default_description sur les types abstraits de trajectoires ;
• builders de panels : échantillonnage des accesseurs, noms depuis le modèle OCP quand
  la trajectoire en porte un (sinon x₁, x₂… générés), contrôle
  :components/:norm/:all ;
• convention « ylabel du costate vide quand le state est affiché » (colonnes appariées) ;
• plomberie Plots.plot/plot! sur les types concrets (pour gagner sur les stubs
  ExtensionError abstraits).

Bilan : l'architecture cible en miniature. Mais le moteur est trop petit pour
CTModels (voir § 3).

2.2 CTModels : CTModelsPlots (monolithe)

Inventaire fonctionnel complet — c'est le cahier des charges du futur moteur + couche cas :

Groupes de signaux et sélection

• 5 groupes : :state, :costate, :control, :path (contraintes de chemin),
  :dual (multiplicateurs) ; clean gère les alias (:states, :cons,
  :constraint(s) → :path, :duals → :dual) ;
• description par défaut = tout ; gating dans do_plot : contrôle jamais tracé si
  m == 0, path si nc == 0, dual si absent de la solution ;
• un style par groupe (state_style, …, dual_style), valeur :none = groupe omis.

Layout

• :split : arbre PlotLeaf/PlotNode/EmptyPlot, nœuds :row/:column ou
  matrices de layout avec hauteurs fractionnaires :
  (state | costate) sur n lignes, contrôle sur l lignes (l ∈ {m, 1, m+1} selon
  :components/:norm/:all), (path | dual) sur nc lignes — les poids relatifs
  n/(n+l), nc/nblines sont recalculés à l'assemblage (__initial_plot,
  plot.jl:265-470) ;
• :group : 1 ligne de subplots, sauf cas spécial control=:all avec 4 plots →
  grille (2,2) ;
• tailles par défaut : __size_plot (600×280 / 600×420 / 600×140·nblines).

Décorations (absentes du moteur CTFlows)

• lignes verticales t0/tf sur tous les subplots (time_style), positions
  recalculées si temps normalisé, temps initial/final éventuellement dépendant de la
  variable de décision ;
• lignes horizontales de bornes : boîtes state/control/path
  (*_bounds_style), ciblage du subplot par indice de composante, z_order=:back ;
• chaque décoration a son canal de style et son gating (do_decorate).

Données et séries

• grilles de temps par composante : time_grid(sol, :state|:control|:costate|:path)
  — modèles UnifiedTimeGridModel / MultipleTimeGridModel (fusion
  unique(sort(vcat(T_x, T_y))) pour les tracés (x,y)) ; cas réellement exercé dans
  .extras/plot_manual.jl (T_costate = T[1:end-1], T_path = nothing, données en
  matrices → interpolation constante) — ce n'est pas une possibilité théorique ;
• seriestype par défaut dépendant des données : :steppost si l'interpolation du
  contrôle est :constant, sinon :path ;
• garde ylims à tolérance relative (1e-3), avec cas particulier milieu ≈ 0 ;
• suffixe de label de temps « (normalized) ».

Tracés de phase / paires (x, y)

• @recipe public f(sol, model, xx, yy, time) avec
  xx, yy ∈ {:time, :state, :control, :costate, :control_norm, :path_constraint, :dual_path_constraint} (+ indice de composante) — permet plot(sol, model, (:state,1), (:state,2)) etc. ;
• l'extraction de données (__get_data_plot, _get_variable_values,
  _handle_*_plot) n'utilise pas Plots : c'est du calcul pur.

Plomberie Plots

• Plots.plot(sol, …), Plots.plot!(sol, …) (sur current()), Plots.plot!(p, sol, …) ;
• superposition sur figure existante : si p est vide, la figure initiale est
  reconstruite puis substituée champ à champ par setfield! (plot.jl:1200-1203) —
  point dur à préserver ou assainir ;
• filtrage des kwargs utilisateur via Plots.attributes(:Series)
  (__keep_series_attributes) — purement Plots-specific.

2.3 Divergences internes (à unifier au passage)

Point	CTFlows	CTModels
Garde ylims	tol. absolue 1e-8	tol. relative 1e-3 + cas milieu ≈ 0
Grille de temps	unique, argument de render	par composante, portée par la solution
seriestype contrôle	:path toujours	:steppost si interpolation constante
Marges	left 5mm / bottom 5mm	left 3mm / bottom 5mm
Labels costate	p₁, p₂… génériques	"p" * x_label
Hauteur/ligne	180px + pad 60	140px (600×140·nblines)

Chacun de ces points devra recevoir une politique dans le moteur (paramétrable), et
les différences résiduelles être assumées comme changement de comportement mineur.

---

Partie 3 — Pourquoi le PlotEngine actuel ne suffit pas

Écarts bloquants du moteur CTFlows face au cahier des charges CTModels :

1. Layout à blocs pondérés. :paired exige des colonnes de même hauteur et le
   moteur ne sait pas empiler des blocs de hauteurs différentes avec des poids.
   CTModels a besoin de VStack( HStack(state, costate), control, HStack(path, dual) )
   avec des poids n : l : nc. C'est la généralisation centrale.
2. Grille x par panel. render(times, panels) impose une grille partagée ; les
   panels path/dual de CTModels peuvent vivre sur une autre grille. Le temps doit
   descendre dans le panel (voire dans la série).
3. Décorations. Aucune notion de hline/vline attachée à une cellule ou à la
   figure.
4. Style par série. Panel.style est global au panel ; le seriestype du contrôle
   et les styles de bornes exigent une granularité par série.
5. Séries (x, y) génériques. Le moteur ne trace que « composantes vs temps » ; les
   tracés de phase demandent des séries x/y arbitraires (ce qui, une fois fait, couvre
   aussi le cas temps).
6. :group en grille. Pas de grille (2,2).

Aucun de ces points n'est spécifique au contrôle optimal : ils appartiennent tous
légitimement au moteur.

---

Partie 4 — Le modèle de layout : trois niveaux

Réponse à l'exigence « plusieurs manières de définir un layout ». Trois niveaux
d'expression, chacun abaissé (lowering) vers le suivant ; le renderer ne voit que
le niveau 3. Un seul chemin de rendu, plusieurs portes d'entrée.

Niveau 1 — mots-clés (API actuelle, sucre)

layout = :split | :group        # + placement automatique par la couche cas

Ce que les utilisateurs connaissent. La couche cas traduit (:split, panels) en un
gabarit de niveau 2. Compatibilité ascendante garantie : les signatures publiques
plot(sol; layout=:split, control=:norm, …) ne changent pas.

Niveau 2 — combinateurs de blocs (déclaratif structuré)

Column(panel)                    # un panel = une colonne de composantes
Paired(colA, colB)               # colonnes côte à côte, lignes alignées
Stacked(b1, b2, …; weights=:auto)  # blocs empilés, poids ∝ nb de lignes si :auto
Grid(rows, cols, panels…)        # grille régulière (couvre :group 2×2)

Le gabarit CTModels :split complet s'écrit :

Stacked(
    Paired(Column(state), Column(costate)),   # n lignes
    Column(control),                           # l lignes
    Paired(Column(path), Column(dual));        # nc lignes
    weights=:auto,                             # → n : l : nc
)

C'est le niveau que manipulent les couches cas — lisible, testable, sans géométrie.

Niveau 3 — arbre pondéré général (IR, ce que rend le backend)

Leaf(axes::Axes)                             # une cellule = un système d'axes
HBox(children; weights)                      # juxtaposition horizontale
VBox(children; weights)                      # empilement vertical

Équivalent backend-agnostique du PlotNode/matrice de layout de CTModels — mais typé
(pas de Matrix{Any}), avec poids explicites et parcours déterministe (ordre de
numérotation des cellules documenté, nécessaire pour render! en superposition).

Côté backends : Plots reproduit les poids par matrices de layout imbriquées (technique
déjà éprouvée dans __plot_tree) ; Makie les mappe directement sur
GridLayout + rowsize! — l'arbre pondéré est même plus naturel en Makie qu'en Plots.

---

Partie 5 — Architecture cible

5.1 Vue d'ensemble

CTBase/src/Plotting/            # IR + lowering + heuristiques + contrat  (0 dép. backend)
CTBase/ext/CTBasePlots.jl       # renderer Plots      [weakdeps: Plots]
CTBase/ext/CTBaseMakie.jl       # (futur) renderer Makie — hors scope, contrat prêt
CTModels/ext/CTModelsPlots.jl   # couche cas Solution      → construit Figure, appelle render
CTFlows/ext/CTFlowsPlots.jl     # couche cas trajectoires  → construit Figure, appelle render

5.2 Le point technique clé : pourquoi l'IR doit être dans src

Une extension Julia n'est pas adressable proprement depuis un autre paquet
(Base.get_extension est fragile et non idiomatique). La solution canonique :

• CTBase/src possède les types (l'IR) et les fonctions du contrat
  (render, render!) — avec stubs ExtensionError quand aucun backend n'est chargé ;
• CTBase/ext/CTBasePlots ajoute des méthodes à ces fonctions pour le backend
  Plots (pattern « function ownership » standard des weak deps).

Les couches cas construisent l'IR avec les types de CTBase.Plotting (toujours
disponibles) et appellent Plotting.render(backend, fig). Comme CTModelsPlots est
elle-même déclenchée par Plots, dès qu'elle est chargée, CTBasePlots l'est aussi
(CTBase + Plots présents) — aucun get_extension nulle part.

C'est exactement la séparation demandée : tout ce qui peut vivre sans Plots vit dans
src ; seul le rendu vit dans ext.

5.3 L'IR (esquisse)

# --- séries et décorations : pure donnée -------------------------------------
struct Series
    x::Vector{Float64}
    y::Vector{Float64}
    label::String                # "" = pas d'entrée de légende
    style::NamedTuple            # vocabulaire neutre, voir § 5.4
end

struct HLine; value::Float64; style::NamedTuple; end   # bornes
struct VLine; value::Float64; style::NamedTuple; end   # t0 / tf

# --- une cellule = un système d'axes ------------------------------------------
struct Axes
    title::String
    xlabel::String
    ylabel::String
    series::Vector{Series}
    decorations::Vector{Union{HLine,VLine}}
    legend::Bool
    ylims::Union{Nothing,Tuple{Float64,Float64},Symbol}  # :auto_guarded → garde ylims
end

# --- layout : niveau 3 ----------------------------------------------------------
abstract type AbstractLayoutNode end
struct Leaf <: AbstractLayoutNode;  axes::Axes;                                end
struct HBox <: AbstractLayoutNode;  children::Vector{AbstractLayoutNode}; weights::Vector{Float64}; end
struct VBox <: AbstractLayoutNode;  children::Vector{AbstractLayoutNode}; weights::Vector{Float64}; end

# --- figure ---------------------------------------------------------------------
struct Figure
    root::AbstractLayoutNode
    size::Union{Nothing,Tuple{Int,Int}}   # nothing → heuristique du moteur
    title::Union{Nothing,String}
end

Plus haut dans le moteur (toujours src) : Panel (groupe titré de composantes, comme
aujourd'hui), les combinateurs de niveau 2, le lowering Panel/gabarit → Axes/arbre,
les heuristiques de taille, la normalisation du temps, la garde ylims, les défauts
__layout(), __time(), __style() (convention double-underscore du Handbook).

Le Panel s'enrichit par rapport à CTFlows : il porte sa grille x (écart n°2) et
autorise un style par composante (écart n°4). Les tracés de phase ne passent pas par
Panel : la couche cas construit directement un Axes avec des Series x/y — le
moteur les couvre par construction (écart n°5).

5.4 Le contrat backend — frontière Plots / non-Plots

abstract type AbstractBackend end
struct PlotsBackend <: AbstractBackend end    # types dans src ; méthodes dans ext

render(b::AbstractBackend, fig::Figure; kwargs...)          # → figure backend
render!(b::AbstractBackend, target, fig::Figure; kwargs...) # superposition
# stubs src : throw(Exceptions.ExtensionError(:Plots)) / NotImplemented (contrat)

Backend-agnostique (src)	Plots-specific (ext CTBasePlots)	Équivalent Makie (futur)
Arbre pondéré HBox/VBox	matrices de layout imbriquées	GridLayout + rowsize!
Series, HLine, VLine	plot!(subplot=i), hline!, vline!	lines!, hlines!, vlines!
style neutre : color, linewidth, linestyle, alpha, seriestype ∈ {:path, :steppost, :scatter}, z_order ∈ {:front, :back}	traduction en attributs Plots ; filtre Plots.attributes(:Series)	traduction (:steppost → stairs(step=:post))
garde ylims, poids, heuristiques de taille (calcul)	application (ylims!, size=)	application
fontes/marges sémantiques (title 10pt, guide 10pt, marges std)	Plots.font, Measures.mm	fontsize, padding
—	Plots.current(), mutation setfield!	pas d'équivalent (assumé)
—	@recipe (interop recettes)	—

Canal d'échappement : un kwarg backend_kwargs::NamedTuple transmis tel quel au
backend (perte de portabilité assumée et documentée) — évite de faire grossir le
vocabulaire neutre au-delà du nécessaire (YAGNI).

5.5 Les couches cas, réduites à leur spécification

Chaque couche cas fournit exactement cinq choses :

1. vocabulaire : clean (alias, doublons) + description par défaut (contrat sur
   types abstraits, à la _default_description) ;
2. builders de panels : échantillonner les accesseurs sur la bonne grille, nommer
   depuis le modèle (state_components, time_name…), choisir le seriestype
   (interpolation du contrôle) — conventions métier incluses (ylabel costate vide si
   state affiché, ‖u‖, préfixe « p ») ;
3. builders de décorations : bornes des boîtes state/control/path → HLine,
   t0/tf (y compris dépendants de la variable) → VLine ;
4. choix du gabarit : niveau 1 → combinateurs de niveau 2 ;
5. plomberie : méthodes Plots.plot/plot! sur les types concrets, gating
   (do_plot-like), gestion :none.

Estimation : ~300–400 lignes par couche cas (contre ~2000 aujourd'hui côté
CTModels), et zéro géométrie.

Note : l'extraction de données des tracés de phase (__get_data_plot,
_get_variable_values, fusion des grilles multiples) n'a aucune dépendance à Plots ;
elle gagnerait à migrer dans CTModels/src (module Display ou dédié), l'extension
n'en gardant que l'habillage. À trancher en phase 3 (D6).

---

Partie 6 — Conformité à la philosophie

Tenet	Application
1. Un module par responsabilité	Plotting (IR + contrat) / CTBasePlots (rendu) / couches cas — trois responsabilités, trois modules
2. Tout est qualifié	using Plots: Plots + Plots.plot! partout ; import CTBase.Exceptions ; pas de using nu (corrige au passage ext/CTModelsPlots.jl)
3. Types = noms, traits = adjectifs	AbstractBackend/PlotsBackend (nom) ; layout/placement restent des options, pas des types (pas d'axe orthogonal justifiant un trait — KISS)
4. Programmer contre l'abstraction	contrat render sur AbstractBackend, stubs NotImplemented/ExtensionError ; couches cas écrites contre types abstraits
5. SOLID/DRY/KISS/YAGNI	une seule implémentation du rendu (DRY) ; backend Makie non codé, seulement rendu possible (YAGNI)
6. Erreurs structurées	IncorrectArgument (layout/time/control invalides), PreconditionError (poids ≠ enfants, panels vides), NotImplemented (contrat backend), ExtensionError (Plots absent)
7. Stabilité de type	arbre typé (fin des Matrix{Any} et tuples hétérogènes de __plot_tree) ; barrières de fonction au lowering
8–10. Docstrings & docs	docstrings en dernier (convention) ; API auto-générée publique + privée

Testabilité (tenet 9) — l'argument massue de cette architecture : l'IR étant de la
donnée pure, on teste sans backend ni display — unités sur clean/lowering/poids/
garde ylims/heuristiques, golden tests sur « Figure attendue pour telle solution »,
et une mince couche de tests de contrat par backend. Aujourd'hui, tester exige de
construire de vraies figures Plots.

---

Partie 7 — Risques et points durs

#	Point dur	Analyse / parade
R1	Sémantique plot!(p, sol) sur figure vide (substitution setfield!)	à re-spécifier : render! cible des cellules existantes par indexation déterministe de l'arbre ; le cas « figure vide » est traité en amont (créer au lieu de muter). Cas d'usage catalogués dans .extras/plot_manual.jl:153-159 (plot! sur current(), sur plt pré-dimensionné) et :228-239 (comparaison de deux solutions, temps normalisé, styles par groupe). Documenter le changement s'il y en a un
R2	Kwargs utilisateur en vrac (plot(sol; linestyle=:dash))	conserver : filtre série côté backend (comme __keep_series_attributes) + backend_kwargs explicite pour le reste ; le mécanisme Plots.attributes(:Series) est validé isolément dans .extras/plot_series.jl
R3	Iso-rendu visuel non garanti au pixel	assumé : figer le comportement par golden tests IR, pas les pixels ; lister les diffs (marges, tailles, tol. ylims) dans le CHANGELOG
R4	Divergences de politiques (§ 2.3)	une politique unique paramétrée dans le moteur ; défauts choisis en phase 1, validés visuellement sur les deux paquets
R5	Ordre de chargement des extensions	sans risque : CTModelsPlots requiert Plots ⇒ CTBasePlots (CTBase+Plots) se charge aussi ; n'appeler render qu'au runtime
R6	@recipe public de CTModels (paires x/y)	reste en couche cas (interop Plots légitime) ; ne pas tenter de l'abstraire (YAGNI)
R7	Poids Plots imprécis (arrondis digits=2 actuels)	le renderer calcule les hauteurs exactes ; garder la technique matrices imbriquées éprouvée
R8	Périmètre CTBase qui grossit	contenu strictement domain-free ; le vocabulaire OCP ne fuit jamais dans Plotting (revue de code sur ce critère)

---

Partie 8 — Plan de migration (phases)

Chaque phase = un plan détaillé (PLAN.md)
validé avant code, tests verts et non-régression avant de passer à la suivante.
Docstrings en dernier de chaque phase.

Workflow git (s'applique à chaque unité de travail)

Une unité de travail = une phase, ou une sous-étape livrable indépendamment (ex.
3(a), 3(b)…). Pour chacune :

1. Brancher depuis main : git checkout main && git pull && git checkout -b <feat/…>
   — jamais de travail directement sur main.
2. Développer + tests verts localement (non-régression sur la matrice de gel).
3. Demander l'accord humain avant tout commit/push — aucune écriture distante
   sans validation explicite (règle CLAUDE.md du dépôt).
4. Ouvrir une PR vers main une fois l'accord donné.
5. Versions beta : après merge, publier au besoin une nouvelle version beta
   (Project.toml + CHANGELOG/BREAKING) pour propager vers l'amont — l'ordre de
   propagation suit le DAG : CTBase → CTFlows/CTModels → CTDirect/OptimalControl.
   Chaque cran d'amont bumpe sa borne [compat] sur le paquet aval mis à jour.

Ordre de propagation typique pour ce chantier :

CTBase (Plotting + CTBasePlots)   ─┐  beta
                                   ├─→ CTFlows (couche cas)   beta
                                   └─→ CTModels (couche cas)  beta
                                          └─→ CTDirect / OptimalControl  (bump compat)

Phase 0 — Spécification et gel du comportement

• figer le comportement actuel : inventaire des appels publics des deux paquets
  (signatures, défauts, exemples de docs), captures de référence manuelles ;
• écrire la spec de l'IR et du contrat backend (revue humaine) ;
• trancher D1–D6.

Actifs existants : les scripts .extras/ (CTModels)

Quatre scripts de vérification visuelle écrits à la main constituent déjà la matrice
de cas de référence. Décision actée : ils seront convertis en tests versionnés
(format module + fonction du Handbook, test/suite/) pour que la matrice de gel tourne
en CI et non plus seulement à l'œil ; les scripts restent comme parcours de validation
visuelle manuelle. Cette conversion est le premier livrable de la phase 0.

Script	Ce qu'il couvre
.extras/plot_duals.jl	OCP via @def (CTParser) avec contraintes mixtes/boîtes ; toutes les combinaisons de description (:state…:dual, y compris :path, :dual seuls) ; matrice des *_style=:none (5 groupes) ; matrice des décorations désactivées (time_style, *_bounds_style) ; label/color utilisateur
.extras/plot_manual.jl	solution construite via PreModel/build_solution avec grilles distinctes par composante et interpolation constante (matrices) ; matrice :group/:split × control=:components/:norm/:all ; styles par groupe (NamedTuple) ; sémantique plot! (sur current(), sur plt pré-dimensionné) ; superposition de deux solutions (temps normalisé, styles en tirets)
.extras/plot_variable.jl	solve réel (CTDirect + Ipopt) d'un OCP à variable de décision (tf libre, tf → min) avec contrainte de chemin sur v ; exerce le chemin t0/tf dépendant de la variable (décorations temps non triviales) et une solution issue du solveur (pas fabriquée)
.extras/plot_series.jl	expérience isolée du filtre Plots.attributes(:Series) (base de __keep_series_attributes)

Ces scripts définissent en creux le contrat de compatibilité de la phase 3 : toute
ligne qui y figure doit produire une figure équivalente après migration. Ils serviront
aussi de banc d'essai pour choisir les politiques unifiées (D5) — les deux jeux de
gabarits (:split complet 5 groupes, :group avec 2×2) y sont exercés. Note :
plot_variable.jl tire CTDirect/Ipopt ; sa version testée devra soit être isolée
(dépendances de test lourdes), soit reconstruire une solution équivalente via
build_solution (comme plot_manual.jl) pour rester dans les dépendances de test de
CTModels.

Phase 1 — CTBase : Plotting + CTBasePlots

• créer CTBase/src/Plotting/ : IR, combinateurs N2, lowering, heuristiques,
  défauts __…, contrat render/render! + stubs ;
• créer CTBase/ext/CTBasePlots.jl : renderer Plots = port généralisé du
  PlotEngine de CTFlows (poids, x par panel, décorations, style par série, Grid) ;
• tests : unités IR/lowering (sans Plots) + contrat backend (avec Plots) ;
• CTModels et CTFlows inchangés à ce stade.

Phase 2 — CTFlows bascule (le cas simple d'abord)

• TrajectoryPlots construit l'IR CTBase ; suppression de PlotEngine local ;
• non-régression sur les exemples de docs CTFlows.

Phase 3 — CTModels bascule (le gros morceau)

Sous-étapes livrables indépendamment :

• (a) :split/:group state/costate/control (avec :components/:norm/:all) ;
• (b) path/dual (grilles propres) ;
• (c) décorations (bornes, t0/tf) ;
• (d) tracés de phase + grilles multiples — évaluer la migration de l'extraction de
  données vers src (D6) ;
• (e) plot! superposition/comparaison de solutions ;
• suppression de plot.jl/plot_default.jl/plot_utils.jl actuels.

Phase 4 — Consolidation

• docstrings complètes (moteur + couches cas), guides de docs, CHANGELOG/BREAKING des
  deux paquets ;
• vérification croisée des rendus sur les galeries d'exemples.

Phase 5 (optionnelle, plus tard) — POC Makie

Un CTBaseMakie minimal (quelques cellules, un empilement pondéré) uniquement pour
valider le contrat — pas un backend complet (YAGNI).

---

Partie 9 — Décisions à trancher

#	Question	Recommandation
D1	Nom du module CTBase	Plotting (CTBase.Plotting) — pas de collision avec Plots.jl ; alternatives : Figures, PlotSpec
D2	Étendue du vocabulaire de style neutre	minimal (color, linewidth, linestyle, alpha, seriestype, z_order) + backend_kwargs en échappatoire
D3	Conventions d'apparence métier (ylabel costate vide, « p »·labels, ‖u‖)	couche cas — le moteur dessine, il ne sait pas ce qu'est un costate
D4	Sémantique des poids Stacked	:auto = proportionnel au nombre de lignes (comportement CTModels actuel) ; poids explicites possibles
D5	Politiques divergentes (§ 2.3 : ylims, marges, hauteurs)	politique CTModels pour ylims (relative), CTFlows pour tailles/marges ; à valider visuellement en phase 1
D6	Extraction de données des paires (x,y) dans CTModels/src	oui, à terme (aucune dép. Plots) — décision ferme en phase 3(d)

---

Annexe — Cartographie code actuel → code cible

Aujourd'hui	Demain
CTFlows/ext/…/PlotEngine/panel.jl (Panel, __layout, __time, __style)	CTBase/src/Plotting/ (enrichi : x par panel, style par composante)
CTFlows/ext/…/PlotEngine/render.jl (render, render!, cells, tailles, ylims)	scindé : calculs → CTBase/src/Plotting/, dessin → CTBase/ext/CTBasePlots.jl
CTModels/ext/plot.jl:1-46 (PlotLeaf/PlotNode/EmptyPlot)	Leaf/HBox/VBox typés dans l'IR
CTModels/ext/plot.jl:215-251 (__plot_tree)	renderer Plots (matrices imbriquées)
CTModels/ext/plot.jl:265-470 (__initial_plot)	gabarits niveau 2 (couche cas) + lowering (moteur)
CTModels/ext/plot.jl:505-1060 (__plot! : séries + décorations)	builders panels/décorations (couche cas)
CTModels/ext/plot.jl:68-159 (__plot_time! : ylims, steppost, labels)	garde ylims → moteur ; steppost/labels → builders
CTModels/ext/plot.jl:1421-1779 (recipe + extraction (x,y))	couche cas ; extraction candidate à CTModels/src (D6)
CTModels/ext/plot_utils.jl (clean, do_plot, do_decorate)	couche cas (vocabulaire + gating)
CTModels/ext/plot_default.jl (__size_plot, défauts)	heuristiques → moteur ; défauts métier → couche cas
CTFlows/ext/…/TrajectoryPlots/	quasi inchangé, construit l'IR CTBase

[ocots]

Closed by #367.