ADR-026 — Contrat 1.0 d’`air-tui` : UI texte riche, cellulaire, capability-gated

Statut : Accepté. Document fondateur de design pré-implémentation.

Catégorie : Architecture (couche 4 — framework TUI).

Contexte

L’ADR-008 acte qu’air-tui supporte trois backends d’exécution : air-console en bypass complet, terminal Air en protocole privé, et terminal tiers/SSH en mode dégradé. L’ADR-009 acte que l’API framework d’Air est exclusivement déclarative et n’expose ni pixels ni cellules à l’application. L’ADR-018 acte que le mode console d’Air reste nativement cellulaire, contrairement au mode graphique qui suit un modèle vectoriel.

Ces trois décisions donnent la direction générale, mais elles laissent ouverte une question décisive pour air-base : qu’est-ce qu’une UI texte riche Air au juste, et quel contrat minimal est garanti à une application TUI ?

Sans ce contrat, air-tui risquerait de dériver soit vers un simple wrapper de terminal ANSI, soit vers une tentative confuse de reproduire une GUI dans un milieu cellulaire. Aucune de ces deux directions n’est acceptable.

Décision

Air définit air-tui comme un framework keyboard-first, cellulaire natif, orienté commandes sémantiques, capable de se dégrader prédictiblement selon les capacités du backend d’exécution.

La décision se décompose en huit points.

1. Le mode texte riche d’Air reste strictement cellulaire

air-tui ne poursuit pas un objectif de rendu pixel-perfect ni de layout libre en coordonnées physiques. Son modèle de sortie est une scène cellulaire :

cellules adressables logiquement ;
glyphes stylés ;
attributs de cellule ;
régions sales et invalidation incrémentale ;
curseurs, sélections et zones de focus modélisés explicitement.

L’application ne manipule pas directement ces cellules ; elle déclare des vues et le renderer air-ui-render-tui résout la scène finale.

Conséquence ferme : aucune primitive publique air-tui ne dépend d’un positionnement absolu en pixels ou en colonnes/lignes.

2. L’API publique est orientée layout logique, jamais physique

Le layout s’exprime exclusivement par des contraintes logiques compatibles avec ADR-009 :

piles verticales et horizontales ;
grilles logiques ;
panneaux fractionnés ;
contraintes min / ideal / max ;
alignement, spacing, padding ;
règles d’élision, wrapping et scroll.

air-tui refuse les APIs du style move_to(x, y) ou draw_at(col, row) dans sa surface publique stable. De telles opérations peuvent exister dans des couches internes ou expérimentales, jamais comme contrat applicatif de premier rang.

3. Le framework fournit un noyau réduit de primitives TUI stables

Le set minimal de primitives 1.0 est volontairement restreint. Il couvre les cas d’usage productifs du mode texte sans chercher l’exhaustivité :

Text et Span stylé ;
Block / Panel ;
List ;
Table ;
Tree ;
Input ;
Editor ;
ScrollView ;
Tabs ;
StatusBar ;
Dialog ;
CommandPalette ;
Progress ;
Chart textuel simple.

Les widgets 1.0 sont pensés pour être :

navigables intégralement au clavier ;
rendables proprement en cellule ;
sérialisables en arbre logique pour inspection et test ;
dégradables sans rupture fonctionnelle majeure.

4. Le modèle d’événements repose sur des événements structurés, pas sur des séquences terminal brutes

air-tui standardise un modèle d’événements sémantiques commun à tous les backends. Le backend traduit son environnement local vers ce modèle :

KeyDown
KeyUp
ModifiersChanged
MouseDown
MouseUp
MouseMove
Scroll
FocusGained
FocusLost
Resize
Paste
ImeCommit quand disponible
Command pour les actions résolues

Dans les backends dégradés où certaines informations n’existent pas nativement, l’événement manquant est signalé comme indisponible par le système de capacités, jamais simulé de manière mensongère.

5. Les commandes sémantiques sont first-class

Le contrat d’interaction d’air-tui n’est pas fondé uniquement sur les touches brutes. Le framework introduit un niveau de résolution explicite :

input brut -> binding -> commande sémantique -> dispatch

Exemples de commandes sémantiques :

app.quit
scene.confirm
collection.move_next
editor.save
scene.open_palette
pane.focus_left

Cette décision répond à trois objectifs :

rebindabilité des raccourcis ;
accessibilité et introspection cohérentes ;
dégradation plus propre entre backends riches et terminaux tiers.

6. Les capacités sont déclarées explicitement en trois niveaux

L’API Capabilities d’ADR-008 est précisée en trois profils conceptuels.

Profil A — Full Console

Exécution sous air-console, avec bypass complet :

couleurs riches ;
souris native ;
KeyDown et KeyUp garantis ;
modifiers complets ;
Resize fiable ;
Unicode sérieux ;
focus structuré ;
clipboard et IME selon disponibilité système.

Profil B — Air Terminal

Exécution dans un terminal Air parlant le protocole privé du framework :

garanties proches du profil A ;
transport indirect mais sémantique quasi équivalente ;
même contrat applicatif par défaut.

Profil C — Compatible Terminal

Exécution sur terminal tiers ou SSH via Kitty keyboard protocol ou ANSI :

clavier potentiellement réduit ;
souris optionnelle ;
KeyUp non garanti ;
rendu Unicode dépendant du terminal ;
paste, resize et modifiers parfois partiels.

Le développeur consomme une seule API, mais le framework expose clairement les capacités garanties, optionnelles, ou absentes.

7. La dégradation doit être visuelle d’abord, fonctionnelle le moins possible

Air impose une règle de design ferme :

la dégradation visuelle est acceptable ;
la dégradation ergonomique est acceptable si elle est prévisible ;
la dégradation fonctionnelle critique n’est pas acceptable silencieusement.

Exemples de dégradations acceptées :

palette moins ornée ;
couleurs réduites ;
souris absente ;
panneaux repliés ;
scroll plus grossier ;
widget avancé remplacé par variante plus simple.

Exemples de dégradations interdites en silence :

action essentielle inaccessible ;
focus incohérent ;
raccourci critique perdu sans alternative ;
affichage corrompu ;
faux support déclaré pour une capacité absente.

8. `air-tui` ne vise ni l’émulation parfaite des terminaux historiques ni la copie d’une GUI

Les non-objectifs 1.0 sont explicites :

pas de promesse de compatibilité exhaustive avec tous les comportements ANSI historiques ;
pas de placement libre au pixel ;
pas d’animations lourdes comme fondation du framework ;
pas de dépendance primaire à la souris ;
pas de modèle d’imagerie vectoriel en console ;
pas de tentative de transformer le mode texte en sous-Wayland.

air-tui vise un médium texte moderne, pas un compromis flou entre terminal legacy et GUI.

Justifications

`air-base` doit être un produit complet, pas une absence de GUI

L’ADR-006 pose air-base comme profil premier rang. Cela impose un framework texte capable de produire des applications confortables, structurées et productives, et non une simple collection de flux ANSI.

Le mode texte a des forces propres qu’il faut assumer

Le mode texte excelle en densité informationnelle, en latence, en robustesse, en navigation clavier, et en fonctionnement distant. Le framework doit renforcer ces qualités au lieu de les dissoudre dans un imaginaire graphique mal adapté.

Le capability-gating est la seule manière honnête de concilier local riche et remote dégradé

Le même code applicatif doit pouvoir viser air-console, terminal Air, et terminal tiers. Cette ambition n’est tenable que si le framework nomme explicitement les garanties de chaque backend au lieu de prétendre qu’ils sont équivalents.

Le modèle par commandes sémantiques prépare la stabilité et l’accessibilité

Un framework fondé uniquement sur les touches brutes dérive vite vers des comportements ad hoc, difficiles à remapper, difficiles à exposer aux aides techniques, et difficiles à stabiliser sur dix ans.

Conséquences

Bénéfices

contrat clair pour les développeurs TUI ;
meilleure cohérence entre air-console et air-tui ;
dégradations prévisibles entre local riche et terminal tiers ;
base saine pour accessibilité, tests d’interface et introspection ;
différenciation nette d’Air face aux simples stacks terminales POSIX.

Coûts

davantage de travail initial qu’une bibliothèque ANSI classique ;
nécessité de concevoir tôt un vrai modèle de focus, de commandes et de capacités ;
maintenance d’un backend dégradé compatible sans laisser ce backend dicter la qualité du design principal.

Risques assumés

certains outils terminal historiques s’intègreront moins naturellement au modèle air-tui que des applications Air natives ;
une partie des attentes héritées du monde ANSI devra être explicitement rejetée ;
le framework devra résister à la tentation d’ajouter trop vite des widgets ou escape hatches non cohérents avec le modèle cellulaire.

Articulation avec les autres ADRs

ADR-006 — air-base est un profil premier rang, ce qui justifie un framework TUI ambitieux.
ADR-007 — air-console fournit le backend local riche qui rend ce contrat réaliste.
ADR-008 — cet ADR précise le contrat applicatif sous-jacent aux trois backends déjà actés.
ADR-009 — le layout reste déclaratif, sans coordonnées physiques publiques.
ADR-016 — Unicode, bidi et IME restent des exigences transverses ; leur niveau de garantie dépend des capacités du backend.
ADR-017 — commandes sémantiques, focus explicite et arborescence logique facilitent l’accessibilité.
ADR-018 — confirme le caractère strictement cellulaire du mode console.

Statut futur

ADR immuable dans son intention.

Les détails de surface API (noms exacts de types, modules, traits, enums, widgets additionnels) relèveront des futures specs d’implémentation de air-tui, mais devront respecter ce contrat.

Licence du document : MPL 2.0 Statut : Document fondateur. Édition directe autorisée en phase de design pré-ouverture publique ; immuable après ouverture publique (toute évolution via RFC, cf. ADR-015).

Keyboard shortcuts

Air — Documentation de conception