yavsc/doc/architecture/postit.md
Paul Schneider 0ac6970e9d
All checks were successful
Forgejo Release / release (push) Successful in 10m4s
Dotnet build and test / build (pull_request) Successful in 15m16s
feat(postit): keep sessions online and replace banner with auth modal
Remove the sticky session banner, keep the app connected when possible, restore sessions silently on startup, and show a blocking authentication modal with login, register, and forgot-password actions when auto-reconnect cannot resume the session. Add targeted auth and responsive-layout regressions and update the architecture notes to match the session lifecycle.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-13 12:32:58 +00:00

38 KiB

PostIt — Topologie, navigation, DI

Récapitulatif : PostIt est le client Avalonia du projet Yavsc. C'est un code-base unique (src/PostIt/PostIt/PostIt.csproj) multi-cible vers trois front-ends distincts (PostIt.Desktop, Postit.Android, PostIt.Browser). Cette fiche couvre la topologie des projets, le DI, le ViewLocator custo et la navigation — c'est-à-dire tout ce que la fiche postit-oidc.md ne détaille pas déjà (l'OIDC, le flow d'auth, la persistance des tokens). Détail dans cette page, racine de l'architecture : Architecture.md.

Surface : un code-base, trois front-ends

Le projet Android active EmbedAssembliesIntoApk par défaut, y compris en Debug : un APK installé directement doit contenir les assemblies .NET, sans dépendre des fichiers de Fast Deployment sous files/.__override__. Sans elles, le runtime Android abandonne avant de charger l'interface avec « No assemblies found ». Le Makefile conserve également ce réglage explicite pour ses commandes de compilation.

                       ┌────────────────────────┐
                       │ PostIt (lib)           │
                       │ src/PostIt/PostIt/     │
                       │ Pages, ViewModels,     │
                       │ Services, ViewLocator  │
                       │ (aucun rendu natif)    │
                       └──────┬───┬─────┬───────┘
                              │   │     │
              ┌───────────────┘   │     └────────────────┐
              │                   │                      │
   ┌──────────▼────────┐ ┌────────▼─────────┐ ┌──────────▼────────┐
   │ PostIt.Desktop    │ │ PostIt.Android   │ │ PostIt.Browser    │
   │ Avalonia.Desktop  │ │ Avalonia.Android │ │ Avalonia.Browser  │
   │ Linux/Windows     │ │ APK              │ │ WASM              │
   │ + custom scheme   │ │ + Chrome Custom  │ │ (no native proc)  │
   │   postit://       │ │   Tabs           │ │                   │
   │ + IBrowser custo  │ │ + IBrowser custo │ │                   │
   └───────────────────┘ └──────────────────┘ └───────────────────┘

Le code partagé vit dans PostIt/. Chaque front-end est un projet Satellite SDK Avalonia qui ne contient que le Program.Main, le Platform.CreateBrowser, et les manifestes spécifiques (IntentFilter Android, app.manifest Desktop). Toute la logique (VM, services, navigation, settings, OIDC) est dans le code-base partagé.

Abonnements PayPal

La page native Mon abonnement PayPal est accessible depuis l'accueil, le profil et « À propos ». Elle utilise ResourceSubscriptionsApiClient avec l'autorité OIDC configurée pour charger les offres, l'abonnement en cours et le solde. Les prix HT/TTC, la TVA et les droits proviennent du serveur. La création ou reprise de souscription utilise la session bearer de PostIt ; seule l'approbation est ouverte dans le navigateur, sur un domaine PayPal HTTPS. Après approbation ou abandon, l'utilisateur revient dans PostIt et utilise Actualiser les paiements et mon solde. Ni l'ouverture du navigateur ni la page de retour ne prouvent un paiement : seul le rapprochement serveur des transactions vérifiées accorde les droits. La résiliation demande une confirmation explicite et conserve les droits des périodes déjà payées. La configuration serveur et les routes sont décrites dans INSTALL.md.

Reprise Android

IActivityApplicationLifetime.MainViewFactory crée une nouvelle MainView pour chaque activité Android. Avant de remplacer la racine, PostIt relève les types et les modèles de vue des pages de la pile précédente, puis recrée ces pages dans le même ordre, sans animation. Les contrôles de l'ancienne activité ne sont pas réutilisés ; les modèles de vue conservent les sélections et brouillons en mémoire. Une nouvelle racine sans historique reçoit la page d'accueil, même si l'initialisation de session a déjà eu lieu. Le rafraîchissement silencieux de session reste unique par processus. Cette restauration couvre la recréation d'activité dans le même processus, pas la destruction du processus par Android.

Prévisualisation et orientation des Podcasts

« Prévisualiser la caméra » ouvre un aperçu local avant « Démarrer le direct », sans exiger de titre. Cette phase ne crée aucune émission côté serveur, n'enregistre aucun segment et n'ouvre pas le microphone. Le choix de caméra est verrouillé pendant l'aperçu ; l'arrêter pour changer de caméra. Le microphone sélectionné n'est ouvert qu'au démarrage du direct.

« Arrêter la prévisualisation », la sortie de page et la déconnexion libèrent la caméra. Le passage au direct ferme d'abord l'aperçu, puis ouvre la capture avec les périphériques sélectionnés : les images d'essai ne sont pas publiées. Sous Android, un aperçu seul s'arrête aussi au passage en arrière-plan, sans lancer de service de capture ni de notification de direct. Les Podcasts en direct conservent leur service caméra/microphone existant.

Le chemin Android partage le rendu Camera2/EGL entre aperçu seul et encodage. L'arrêt de l'aperçu détache ses callbacks via le SurfaceHolder conservé, avant la destruction différée du contrôle natif ; le nettoyage ne relit pas la propriété Holder d'une SurfaceView dont le wrapper Java peut être libéré. La rotation physique utilise l'orientation du capteur, la caméra avant/arrière et la rotation de l'écran. Camera2 peut déjà inclure la rotation du capteur dans la matrice SurfaceTexture, ainsi qu'un miroir pour la caméra avant : seule la rotation restante est appliquée, dans le sens inverse si la matrice contient un miroir, afin de ne pas tourner l'image deux fois. Un changement de rotation d'écran recalcule ce rendu pendant la capture. L'aperçu conserve les proportions ; les dimensions encodées restent celles du démarrage du direct, avec des bandes noires si la nouvelle orientation l'exige, pour ne pas modifier le format HLS/SRTP en cours d'émission.

Les tests partagés couvrent l'aperçu sans appel API, le passage au direct, les arrêts et une sortie de page pendant l'ouverture de caméra. L'activité Debug CameraFrameRotationTestActivity vérifie les quatre rotations avec encodage, puis l'aperçu sans encodeur et ses changements de rotation. Une validation physique caméra avant/arrière en portrait et paysage reste nécessaire : les tests synthétiques ne vérifient pas le comportement du HAL de chaque téléphone.

Administration et profil personnel

Le quota disque renvoyé par le profil est le quota effectif : Découverte donne deux fois et Premium cinq fois le quota gratuit standard durant la mensualité confirmée payée, y compris après résiliation jusqu'à son échéance UTC. Ensuite, ou après remboursement, le quota habituel reprend sans suppression des fichiers. Les téléversements dépassant l'espace disponible sont refusés avant écriture. La taille maximale par fichier et les quotas podcast restent inchangés.

L'accueil présente un seul accès Administration, visible et exécutable uniquement pour le rôle exact Administrator. SessionStatusViewModel.RefreshAsync lit les rôles dans GET account/me après le rafraîchissement de session ; une erreur de lecture masque l'accès et affiche une erreur sur l'accueil. La déconnexion invalide aussi les vérifications de droits encore en vol.

AdministrationPage regroupe sept onglets : utilisateurs, usages globaux, rôles, clients OIDC, scopes API, courriels et données. Les en-têtes se répartissent sur plusieurs lignes sur les écrans étroits. Le détail d'un utilisateur associe son usage par UserId, sans dépendre du nom affiché. Les erreurs ne déclenchent pas de repli sur l'usage personnel. Le backend réserve aussi les listes aux administrateurs, sous la politique AdministratorOnly. Le rôle Moderator seul n'ouvre plus l'administration de PostIt. L'autorisation serveur reste indispensable, indépendamment de la visibilité du bouton dans PostIt.

Mon profil réutilise la page de gestion du compte existante et les endpoints account/me pour lire et enregistrer les informations personnelles. Elle affiche aussi resource-usage/me, sans appeler la liste des usages globaux. Une indisponibilité de l'usage n'empêche pas la gestion du profil. La consommation est chargée avant le profil, pour rester consultable même si une opération de gestion reçoit un refus de quota. L'administration charge également les usages avant ses autres outils et les conserve sur un refus HTTP 429, tant que le rôle administrateur est toujours présent.

L'indicateur est exprimé en points selon les coefficients effectifs du backend, présentés dans les CGU. Le stockage correspond aux volumes instrumentés ajoutés, moins les volumes individuellement suivis supprimés ou remplacés. Les anciens fichiers sans suivi ne sont pas remboursés. La suppression reste disponible au seuil ; CPU, appels API et transferts ne sont pas remboursés. Les renommages conservent le suivi individuel. Le profil et les vues d'administration affichent le seuil effectif, le solde et l'atteinte du quota, indépendamment de l'estimation financière. La section serveur ResourceUsage configure les coefficients et les seuils individuels ; voir INSTALL.md. Le contrôle admet les coûts connus puis constate les coûts restants : il bloque les opérations suivantes, sans interrompre strictement celles déjà en cours.

Au franchissement de 50 %, 75 %, 90 %, 95 % ou 99 % de la limite personnelle, le serveur enregistre une notification privée user/{UserId}, visible dans les notifications de l'accueil lors de leur prochain chargement. Le calcul porte sur le total pondéré net des crédits, pas sur chaque compteur séparé. Une mise à jour franchissant plusieurs paliers ne produit que l'avertissement du plus haut palier atteint ; rester au-dessus ne répète pas l'alerte. Après une baisse sous un palier (crédit ou suppression de stockage suivi), un nouveau franchissement produit une nouvelle notification, même si la précédente a été fermée. Les notifications et le comptage sont enregistrés ensemble ; aucune migration de schéma n'est nécessaire. La lecture et la fermeture des notifications restent accessibles au quota atteint et ne consomment pas de points. Aucun email ni push immédiat n'est envoyé.

La page À propos ouvre les CGU dédiées de PostIt et de Yavsc sur Home/CGU auprès de l'autorité configurée, y compris sans session. Cette page publique présente les coefficients réellement configurés, la période cumulée, le seuil et les limites de la mesure. Mon profil et À propos proposent aussi un lien vers ResourceSubscription sur cette même autorité. La souscription mensuelle et la résiliation PayPal utilisent la session Web et des formulaires antiforgery ; PostIt ne stocke ni identifiant marchand ni secret PayPal. Le profil affiche la consommation brute, l'usage effacé et le crédit reporté, en plus de l'indicateur net. Les crédits Découverte/Premium ne suppriment pas les compteurs : les paiements confirmés sont rapprochés par Yavsc.Org et leur déduction est appliquée aussi au quota API/Blogs.

Outils d'administration du site

Les outils portés correspondent aux contrôleurs de Yavsc.Org/Controllers/Administration ; le site web existant est conservé. Les nouvelles routes vivent dans Yavsc.Api sous api/v1/administration. Les données passent par des records dédiés de Yavsc.Abstract et par AdministrationApiClient, jamais par les entités EF.

Routes Fonction
summary, roles, roles/ensure Statistiques, informations du runtime, rôles standards
roles/{id}/members[/{userId}] Membres, inscription et exclusion
clients[/{id}] Paramètres scalaires des clients OAuth/OIDC
clients/{id}/collections/{collection}[/{rowId}] Redirect URIs, post-logout URIs, scopes, grant types, CORS, restrictions IdP, claims et propriétés
clients/{id}/secrets[/regenerate], clients/{id}/secrets/{secretId} Ajout, rotation et suppression des secrets
scopes[/{id}] Création, consultation, modification et suppression des scopes API
mailing-criteria, mailing-templates[/{id}] Critères de diffusion et modèles de courriels
transfer Export par GET, import transactionnel par POST

Les formulaires de clients, scopes et modèles sont construits à partir des propriétés de leurs DTO typés, afin de conserver tous les champs de l'interface web. Les booléens et énumérations disposent de contrôles dédiés ; les valeurs numériques et annotations de validation sont vérifiées avant l'envoi puis à nouveau côté serveur.

Un nouveau client démarre avec authorization_code, PKCE et les scopes openid et profile. Les autres types d'autorisation restent configurables dans ses collections. Une rotation remplace tous les secrets précédents et expire par défaut après 90 jours. Le serveur conserve uniquement le SHA-256 du secret partagé ; les lectures ne rendent que les métadonnées. PostIt efface la valeur nouvellement créée au changement de client, à la prochaine opération et au détachement de la page. Une réponse de création de secret reçue après déconnexion est ignorée ; un rafraîchissement sans droits efface les données d'administration précédemment chargées. Supprimer un objet, exclure un membre, remplacer les secrets ou importer demande une confirmation explicite. Le serveur refuse l'exclusion du dernier administrateur.

Le transfert JSON version 1 comprend les informations métier des comptes (identifiant, nom, e-mail, nom complet, avatar, calendrier et limites de stockage), les billets (contenu, auteur, publication, cercles et étiquettes) et les paramètres des activités. Ce n'est pas une sauvegarde complète de la base : fichiers, sessions, mots de passe, jetons, rôles, moyens de paiement, adresses et historique d'audit ne sont pas transférés. L'e-mail d'un compte existant, clé alternative du modèle actuel, ne peut pas être changé par import. Les nouveaux comptes n'ont ni mot de passe ni e-mail confirmé.

Les identifiants des billets sont préservés et la séquence PostgreSQL est réajustée après l'import. Tous les auteurs et cercles doivent exister et les parents d'activités doivent former un graphe sans cycle. Une erreur annule l'ensemble de l'import ; aucun repli n'élargit les permissions d'un billet. Les fichiers importés et requêtes sont limités à 16 Mio ; les gros exports doivent être répartis en plusieurs transferts de même schéma. Si plusieurs étiquettes portent déjà le même nom, l'import réutilise celle ayant le plus petit identifiant sans supprimer les autres.

L'initialisation du premier administrateur reste le mécanisme web existant, et n'est pas proposée aux utilisateurs non administrateurs par PostIt. En développement, /openapi/administration.json décrit uniquement ces outils, avec accès AdministratorOnly. Les requêtes de référence sont dans Administration.http ; l'adresse locale d'exemple est celle du serveur de tests, à adapter au déploiement.

Lecture des billets et fichiers utilisateur

La page des blogs affiche par défaut une vue de lecture : titre, login de l'auteur, date de modification et contenu Markdown dans une zone défilante de largeur limitée. Modifier ouvre l'éditeur existant et Nouveau billet initialise explicitement un brouillon. Lire affiche le contenu enregistré sans effacer les modifications non enregistrées ; un nouveau billet ne peut pas remplacer un brouillon modifié non sauvé.

La base des ressources est dérivée de Settings.Authentication.Authority (le déploiement Yavsc.Org), jamais de BlogsApiUrl : https://<hôte Org>/files/<Author.UserName>/. Le repli sur AuthorId conserve la compatibilité avec les anciens DTO dépourvus d'auteur détaillé. Un lien photo.jpg ou blogs/42/video.mp4 est relatif à ce répertoire ; un lien /files/paul/photo.jpg conserve son chemin depuis la racine Org. Les liens absolus ne sont pas réécrits. Les images Markdown ![texte](url) sont affichées dans le billet et leur résolveur n'accepte que HTTP(S), sans accès aux fichiers locaux du poste. Le résolveur charge chaque image dans un flux mémoire repositionnable initialement à la position zéro, nécessaire au décodage du lecteur Markdown.

Le lecteur utilise Markdown.Avalonia.Tight 12.0.0-a3 (version compatible Avalonia 12) pour déléguer les hyperliens à une commande PostIt. L'éditeur conserve MarkdownViewer.Core : son gestionnaire intégré ouvre le navigateur avant d'émettre l'événement de lien et ne permet donc pas ce routage.

Au clic sur un fichier sous /files/<login>/... de la même origine Org (schéma, hôte et port), BlogResourceService sonde Content-Type avec HEAD, puis un GET limité par Range: bytes=0-0 si le serveur refuse HEAD (405/501). Le corps n'est pas téléchargé pour la détection. Une extension connue sert de repli uniquement en l'absence de type exploitable (type absent ou application/octet-stream). Les erreurs HTTP/réseau sont affichées dans la barre de statut, sans les masquer par une déduction MIME.

Les types video/* ouvrent VideoPage via App.PushPageAsync sur desktop. Cette page contient un LibVLCSharp.Avalonia.VideoView, lecture/pause et une action d'ouverture externe. Le lecteur et ses ressources natives sont arrêtés et libérés à la sortie de la page. La lecture utilise directement new LibVLC(), new MediaPlayer(libVlc) et Play(media), sans options spécifiques à Linux ni détection VAAPI/VDPAU. Le média est libéré après Play comme dans l'exemple officiel ; le lecteur conserve sa référence native. LibVLC doit être installé sur le poste (par exemple libvlc5 et les plugins VLC sur Linux ; les bibliothèques natives adaptées sont nécessaires sous Windows/macOS). Une absence de LibVLC ou une erreur de décodage est signalée dans la page. Le navigateur ne s'ouvre que sur demande explicite, jamais en repli automatique. Après la navigation, TryUpdateNativeControlPosition() synchronise la surface native à la priorité Loaded, une fois la mise en page effectuée : les transformations de transition ne déclenchent pas de changement de Bounds. Le rappel est ignoré si le lecteur a été libéré ou remplacé entre-temps. Sur Android et Browser, où ce contrôle natif desktop n'est pas disponible, les vidéos sont ouvertes dans le navigateur, comme les autres fichiers (images liées, PDF, téléchargements) et les liens externes.

ViewLocator custo

Le ViewLocator (cf. src/PostIt/PostIt/ViewLocator.cs) est un IDataTemplate Avalonia explicitement câblé sur le IServiceProvider :

public Control Build(object? data) => data switch
{
    MainPageViewModel   => _services.GetRequiredService<MainPage>(),
    Settings            => _services.GetRequiredService<SettingsPage>(),
    HomePageViewModel   => _services.GetRequiredService<HomePage>(),
    SignaturePageViewModel => _services.GetRequiredService<SignaturePage>(),
    null                => new TextBlock { Text = "No view for <null>" },
    _                   => new TextBlock { Text = $"No view for {data.GetType().Name}" }
};
public bool Match(object? data) => data is ViewModelBase;

Pourquoi un custo, et pas le ViewLocatorBase par défaut d'Avalonia.Mvvm ? Pour deux raisons :

  1. Sortie du Activator.CreateInstance — les pages PostIt sont enregistrées dans le DI et peuvent avoir des dépendances (par construction, aujourd'hui aucune, mais l'extension future est ouverte). Le ViewLocatorBase historique fait new View(), ce qui rend impossible l'injection et complique les tests.
  2. Filtrage par ViewModelBase — Match n'accepte que les types dérivés de ViewModelBase. Toute tentative d'afficher un objet métier (par ex. un DTO de l'API Yavsc) tombe sur le TextBlock "No view for X", pas sur un crash Avalonia.

Le ViewLocator est ajouté aux DataTemplates de l'app dans App.OnFrameworkInitializationCompleted :

DataTemplates.Clear();
DataTemplates.Add(new ViewLocator(provider));

Conséquence pratique : pour qu'une nouvelle page soit affichée par un ContentControl qui binde un ViewModel, il faut deux enregistrements : la page en AddTransient (ou AddSingleton) dans le DI, et une case dans le switch de ViewLocator.Build. Si l'un manque, l'app affiche "No view for X" sans crash.

Podcasts : capture, direct et replay

PodcastsPageViewModel est accessible depuis l'accueil Desktop Windows/Linux. CameraStreamer detecte les cameras DirectShow/V4L2 et les microphones (DirectShow sous Windows, source PulseAudio par defaut sous Linux). PodcastBroadcaster utilise uniquement LibVLC : encodage H.264/AAC, sortie livehttp, segments MPEG-TS d'environ deux secondes. Un segment n'est envoye que lorsque l'index local LibVLC le declare complet.

PodcastApiClient reutilise le transport bearer et son rafraichissement des jetons. Les PUT sont numerotes a partir de zero ; une nouvelle tentative doit avoir exactement les memes octets et la meme duree. Le client supprime un segment local seulement apres acquittement, et envoie le dernier segment ferme par LibVLC avant de terminer le direct. La navigation et la deconnexion arretent la camera. Les erreurs restent visibles ; les fichiers non envoyes restent disponibles localement pour recuperation manuelle.

ILiveProcessor est un singleton dans Yavsc.Api. Il stocke les metadonnees et empreintes SHA-256 dans un index JSON remplace atomiquement, avec des segments immuables accessibles uniquement via les endpoints authentifies. Deux receptions au plus sont tamponnees en parallele ; les validations de sequence, de proprietaire et de quota sont serialisees avant commit. Un index ne reference jamais un segment en cours d'ecriture.

Route sous api/v1/podcasts Role
GET /, POST / Catalogue ou creation d'une emission
GET /{id} Metadonnees et segments ordonnes
PUT /{id}/segments/{sequence}?duration=... Ingestion video/mp2t, auteur uniquement
POST /{id}/complete Finalisation idempotente du replay
GET /{id}/index.m3u8 Playlist HLS EVENT, ENDLIST apres fin/interruption
GET /{id}/segments/{sequence}.ts Segment engage, lecture authentifiee
DELETE /{id} Suppression d'une emission terminee, auteur uniquement

Toutes les routes requierent la politique ApiScope. La lecture est ouverte a tous les utilisateurs authentifies avec ce scope, pas seulement a l'auteur. PodcastMediaInput alimente LibVLC en octets MPEG-TS via les requetes authentifiees existantes, sans transmettre de jeton dans une URL ou un processus externe. Les rappels natifs ne laissent echapper aucune exception : l'erreur est remontee a la page de lecture.

Un direct inactif devient Interrupted lors de la prochaine lecture de l'index ; au redemarrage, tous les anciens directs sont interrompus. Les segments engages constituent le replay, sans transcodage serveur. Le stockage exige un seul processus par racine et les quotas podcast sont independants de ceux des fichiers utilisateur. Voir INSTALL.md pour les limites et le deploiement ; Podcast.http pour les requetes. Le document OpenAPI dedie est /openapi/podcasts.json, accessible en developpement aux administrateurs comme les autres documents de l'API.

Composition root (App.axaml.cs)

App.OnFrameworkInitializationCompleted est le seul endroit où le DI est construit. Ordre, dans cet ordre :

  1. new Settings() + settings.Load() — lit ~/.config/PostIt/postit-settings.json (ou le fallback embarqué dans PostIt.dll).
  2. new TokenStore(...) + new YavscApiClient(settings, tokenStore).
  3. new ServiceCollection() + enregistrements en bloc.
  4. services.BuildServiceProvider().
  5. Settings.BindToServiceProvider(provider) — pose le singleton statique pour les helpers hors-DI (Settings.GetCurrent(), Settings.RequireCurrent()).
  6. DataTemplates.Add(new ViewLocator(provider)).
  7. Branche IClassicDesktopStyleApplicationLifetime / ISingleViewApplicationLifetime (Browser/Android).

Enregistrements DI

Service Lifetime Pourquoi
Settings Singleton État partagé (Loaded, IsDirty, Authentication) — doit être unique.
YavscApiClient Singleton Porte le TokenStore et le cache de tokens ; un seul par process.
BlogApiClient Singleton Mapper stateless, partagé.
SettingsPage Singleton Une seule instance pour la vie de l'app : le DataContext est câblé une fois au boot, le push est idempotent (cf. section Garde anti-empilement ci-dessous).
MainPage / HomePage / SignaturePage Transient Résolution à la demande par le ViewLocator.
MainPageViewModel / HomePageViewModel / SignaturePageViewModel Transient VM reconstruites à chaque navigation ; pas d'état partagé à conserver.
SessionStatusViewModel Singleton État partagé de session ; la modale de MainView survit fonctionnellement à la navigation et à la recréation d'activité via ce VM.

Invariant : Settings est uniquement un singleton. Un AddTransient<Settings>() supplémentaire (qui réécrase le singleton dans le container) ferait que chaque push de SettingsPage crée une instance vide, casse les bindings Authority/ClientId, et perd toute édition. Si tu dois toucher à cette table, ne pas ajouter de registration pour Settings ailleurs que la ligne AddSingleton(settings).

Défilement de la page des billets

La page BlogsPage utilise une grille à hauteur contrainte : l'en-tête et les commandes restent visibles, tandis que la liste des billets et l'éditeur se partagent l'espace disponible. Un GridSplitter permet de modifier cette répartition. La liste et l'article défilent séparément.

Lorsque la largeur de la fenêtre atteint ou dépasse sa hauteur, le lecteur ou l'éditeur passe à gauche (deux tiers de la largeur par défaut), et l'en-tête, la recherche et la liste passent à droite ; les commandes restent dans la barre de navigation. Le séparateur devient vertical. En portrait, la disposition verticale revient sans recréer les contrôles ni perdre le brouillon. Le seuil utilise les dimensions clientes de la fenêtre, indépendamment de la hauteur occupée par la navigation et la bannière de session.

La page applique NavigationPage.BarHeightOverride à 36 en mode large ; le NavRoot de MainView conserve ainsi le bouton Retour, sans changer les autres pages. En portrait, la hauteur de navigation par défaut revient. Les commandes ont un contexte de données explicite pour conserver leurs liaisons, y compris lorsqu'elles passent dans le menu de débordement.

Dans MarkdownEditorControl, AvaloniaEdit gère son propre défilement ; l'aperçu Markdown est placé dans un ScrollViewer. Ne pas limiter la hauteur du MarkdownViewer lui-même : son contenu doit pouvoir dépasser le viewport pour que les barres automatiques s'activent. Ne pas placer cette grille dans un StackPanel vertical ou un ScrollViewer de page, qui lui donnerait une hauteur de mesure illimitée.

Après un redimensionnement de la zone de texte (notamment à l'ouverture du clavier Android avec AdjustResize), l'éditeur remet le curseur dans son viewport après la mise en page, uniquement s'il garde le focus. Un toucher dans la zone éditable demande aussi le clavier via le pont natif Android, sans retirer puis redonner le focus ni modifier la sélection. Les autres plateformes conservent leur gestion habituelle du clavier.

MainView compose les marges de TopLevel.InsetsManager (barres système et découpes) avec le recouvrement réel indiqué par TopLevel.InputPane, car le clavier ne redimensionne pas toujours la fenêtre Android en mode edge-to-edge. Si AdjustResize a déjà réduit la fenêtre, cette réserve ne soustrait pas une seconde fois la hauteur du clavier. La racine gère explicitement ces marges et désactive TopLevel.AutoSafeAreaPadding pour éviter deux propriétaires du même padding. Ne pas remplacer les marges système par un padding contenant uniquement la hauteur du clavier. En disposition large, tant que le clavier est ouvert et que l'article garde le focus, son titre et ses pièces jointes passent dans une colonne à côté du texte. La barre de commandes, la bannière de session et le statut restent visibles. La disposition habituelle revient à la fermeture du clavier ou au changement de focus, sans recréer le brouillon. Sous Android uniquement, le champ du titre est masqué pendant la saisie compacte avec le clavier ouvert, en portrait comme en paysage ; il réapparaît à la fermeture du clavier ou quand le focus quitte l'article. Sa valeur n'est jamais effacée.

En Debug Android, fr.pschneider.postit.MarkdownEditorTestActivity ouvre un billet synthétique local, vérifie au moins trois lignes visibles et le bas de l'éditeur au-dessus des insets natifs du clavier et les contrôles en dehors des barres système, ferme puis rouvre le clavier par toucher sans perte de focus. Le résultat est écrit dans files/markdown-editor-test-result.txt. Ce test nécessite Android 11 ou plus pour vérifier les insets du clavier ; il ne publie aucun billet et retire sa page à la fin. L'extra booléen landscape=true force le paysage pendant le test et restaure l'orientation demandée précédemment à la fin.

Navigation

Le host de navigation est un NavigationPage x:Name="NavRoot" posé sur MainWindow.axaml. La pile est gérée par deux mécanismes distincts :

  1. Nav utilisateur (VM-first) : un ViewModel (souvent dans une commande [RelayCommand]) appelle await ((App)App.Current!).PushPageAsync(targetVm).ConfigureAwait(true);. App.PushPageAsync (src/PostIt/PostIt/App.axaml.cs) résout la Control correspondante via le ViewLocator enregistré dans Application.DataTemplates, l'identifie comme Page, lui assigne le VM comme DataContext, et appelle NavRoot.PushAsync(page). C'est le seul chemin pour les boutons de la toolbar, les OpenSettings / OpenCircles / ManageAcl / OpenSignatureDev, et toute autre nav déclenchée par un ViewModel.

  2. Signaux de cycle de vie : le SessionStatusViewModel lève des événements consommés dans App.OnFrameworkInitializationCompleted pour orchestrer la nav de boot :

    Événement Effet
    LoginSucceeded PushAsync(MainPage) au-dessus de HomePage (post-login).
    LogoutCompleted PopToRootAsync() (revient à HomePage).

    Ces events ne sont pas un canal de nav utilisateur ; ils portent une transition d'état applicatif (authentification établie / perdue) et c'est App qui choisit d'en faire une transition de pile.

Garde anti-empilement

NavigationPage.PushAsync n'est pas idempotent : pousser deux fois la même instance l'empile deux fois, et l'utilisateur doit taper Retour N fois pour sortir. La garde est implémentée dans App.PushPageAsync (et consommée par tous les chemins de nav utilisateur) :

var stack = window.NavRoot.NavigationStack;
if (stack.Count > 0 && ReferenceEquals(stack[stack.Count - 1], page))
{
    return Task.CompletedTask;  // déjà au sommet, no-op silencieux
}
return window.NavRoot.PushAsync(page);

La comparaison est par référence, pas par type : on ne veut empêcher qu'un push de cette instance particulière, pas celui d'une éventuelle autre SettingsPage (il n'en existe qu'une, mais l'invariant est plus clair comme ça). La garde repose sur le fait que SettingsPage est un singleton ; si on repassait en Transient, ReferenceEquals resterait correct mais la pertinence de la garde s'évaporerait (chaque push apporterait une nouvelle instance et l'anti-empilement reposerait sur l'invariant « la même est déjà au sommet », qui ne tiendrait plus).

ViewModels et invariants d'état

  • Settings est un objet-modèle exposé comme DataContext des pages. Il n'hérite pas de ViewModelBase (c'est un POCO [ObservableProperty]-généré par CommunityToolkit.Mvvm). Le fait qu'il soit utilisé comme DataContext est un raccourci de composition acceptable ici, pas un pattern à généraliser.

  • SessionStatusViewModel est le seul VM avec une durée de vie process-entière (singleton). Il survit à toutes les navigations, expose HasValidSession en continu, et porte les événements de cycle de vie consommés par App pour orchestrer la nav de boot (LoginSucceeded, LogoutCompleted). La nav utilisateur déclenchée par l'utilisateur passe par App.PushPageAsync(vm), pas par un événement du SessionStatusViewModel.

  • MainPageViewModel / HomePageViewModel / SignaturePageViewModel sont Transient — une nouvelle instance est créée à chaque push, l'ancienne est libérée quand la page est dépilée. Pas d'état partagé entre occurrences ; pour passer une donnée d'une page à l'autre, on passe par un singleton (souvent YavscApiClient ou Settings).

Bindings XAML : conventions de nommage

Pour les [RelayCommand] (cf. CommunityToolkit.Mvvm), le binding XAML reprend le nom exact de la méthode, sans suffixe :

Méthode C# Binding XAML
Save() {Binding Save}
SaveAsync() {Binding SaveAsync}
LoginCommand() {Binding LoginCommand} (nom littéral, pas de suffixe ajouté)
Clear() {Binding Clear}
CaptureAsync() {Binding CaptureAsync}

JAMAIS SaveCommand, SaveCmd, DoSave, etc. Le source generator [RelayCommand] émet une propriété ICommand du même nom que la méthode. Un binding qui pointe vers une propriété inexistante casse l'app au moment du câblage (le bouton ne se câble pas, et selon la version ça peut faire planter l'init de la page).

Référence canonique : AGENTS.md, section "Avalonia + CommunityToolkit.Mvvm : conventions de binding pour [RelayCommand]".

Pages et leurs rôles

Page DataContext Rôle
MainWindow HomePageViewModel (initial) Host de la NavigationPage.
Modale de MainView SessionStatusViewModel Connexion requise : login, inscription et mot de passe oublié. Navigation bloquée jusqu'à la reprise de session ; aucune barre d'état persistante.
HomePage HomePageViewModel Page d'accueil publique.
MainPage MainPageViewModel Éditeur de post de blog (après login).
SignaturePage SignaturePageViewModel Capture de signature (estimateur).
SettingsPage Settings Édition de Authority / ClientId / Scopes / URLs API / Dark mode. Sauver via Save (RelayCommand).

Conséquences pratiques

  • Ajouter une page : créer la View + le ViewModel + enregistrer les deux dans le DI et dans le switch de ViewLocator.Build. Oublier le ViewLocator est silencieux (juste un TextBlock "No view for X"), pas une exception.
  • Ajouter un événement global de navigation (par ex. "Push après payment success") : ne pas capturer MainWindow ni NavigationPage depuis le VM. La nav passe par App.PushPageAsync(vm) dans tous les cas : soit le VM appelle la méthode directement depuis une commande ([RelayCommand]), soit un handler abonné à un événement d'un singleton (cf. SessionStatusViewModel) l'appelle. Garder les VMs découplés du IClassicDesktopStyleApplicationLifetime.
  • Modifier l'OIDC : la fiche à lire est postit-oidc.md, pas celle-ci. Cette fiche ne ré-explique ni le flow, ni le pipe, ni le custom scheme.
  • Modifier les Settings : ne pas casser le singleton (cf. invariant ci-dessus). Toute propriété présentationnelle ajoutée (par ex. ScopeListText) doit porter [JsonIgnore] pour ne pas polluer le format sur disque.

Voir aussi