Dotfiles_ArchAP/docs/appearance-app-sync.md

Synchronisation des thèmes applicatifs 17G

Contrat et architecture

$XDG_STATE_HOME/labfy-appearance/effective.json est la seule source des choix applicatifs. appearance-app-sync.py reconcile consomme uniquement effectiveFlavor, effectiveAccent, effectiveDark, effectiveHighContrast, effectiveMode et revision. Il rejette un schéma absent, invalide ou incohérent avant toute modification. Il ne lit ni les coordonnées, ni les lieux sauvegardés, ni l'analyse du wallpaper.

Le synchroniseur prend un verrou app-sync.lock, relit l'état après chaque passage des adaptateurs et ne publie last-applied.json qu'avec la dernière révision observée. Le résultat contient un statut indépendant par adaptateur. Les fichiers générés sont écrits par fichier temporaire, fsync, puis os.replace. Les palettes Qt et Kitty viennent toutes de quickshell/.config/quickshell/labfy-sway/theme/catppuccin.json. Les trois fichiers de palettes générés sont ignorés par Git et recréés par le service à la réconciliation ; seuls les points d'entrée sont versionnés.

labfy-appearance-app-sync.path observe effective.json et déclenche le service one-shot. Le service est aussi voulu par la cible de session UWSM, ce qui réconcilie après login. Aucun polling ni daemon Python. Les limites de fréquence systemd sont désactivées pour accepter les rafales de révisions ; le verrou sérialise les exécutions. Une panne d'un adaptateur est enregistrée sans bloquer les suivants. last-applied.json hors Git contient la révision, les résultats et un timestamp ; il ne contient pas de lieu.

État de départ audité le 5 octobre 2026

Écosystème	État réellement constaté
GTK	gsettings demandait catppuccin-mocha-lavender-standard+default et prefer-dark. Seul ~/.themes/Catppuccin-Mocha était présent ; son index.theme et son CSS utilisent Rosewater. Le nom demandé ne correspondait pas au répertoire installé.
Qt	qt5ct et qt6ct installés, palettes Mocha fixes ; QT_QPA_PLATFORMTHEME absent de l'environnement systemd de session.
Kitty	0.49.2, instance active, include Mocha fixe, opacité implicite 1.0.
Neovim	0.12.5, plugin Catppuccin, init.lua et lualine fixés sur Mocha.
Firefox avant migration utilisateur	157.0, profil actif identifié par profiles.ini, thème intégré Dark (firefox-compact-dark@mozilla.org), contenu forcé clair par layout.css.prefers-color-scheme.content-override=1. Aucun user.js, userChrome.css ou userContent.css trouvé. Aucun profil n'est modifié par 17G.

Capacités et limites

Application	Light/Dark	Flavor exact	High Contrast	Live
GTK classique	oui via gsettings	Mocha installé avec Rosewater ; autres flavors absents, fallback Adwaita	partiel : préférence et thème clair/sombre ; aucune variante Catppuccin HC installée	nouvelles fenêtres ; recharge des fenêtres existantes selon application
GTK4/libadwaita	préférence système Light/Dark	thème custom non garanti pour libadwaita	non démontré	selon application
Qt5/Qt6	oui	quatre palettes générées Lavender	pas de palette HC distincte	nouvelles applications ; redémarrage possible des instances ouvertes
Kitty	oui	quatre flavors depuis la palette unique	fond opaque 1.0 ; déjà opaque en mode normal	SIGUSR1 documenté, envoyé aux processus Kitty du même utilisateur
Neovim	oui	quatre flavors Catppuccin	Visual/Search/StatusLine/séparateurs adaptés, sans dimming	uv.fs_event, testé sans redémarrage
Firefox actuel	oui : thème Proton 1.1 à deux palettes et apparence des sites Auto	aucun flavor Catppuccin	non	chrome sans redémarrage ; page locale actualisée lors du test

Pour GTK, Catppuccin-Mocha est le répertoire réellement présent. Latte, Frappé et Macchiato Lavender n'étaient pas installés ; l'adaptateur choisit Adwaita pour ne pas publier un nom de thème inexistant. Installer des variantes auditées de Catppuccin GTK est un travail distinct. Un thème GTK custom ne recolore pas automatiquement libadwaita.

uwsm/.config/uwsm/env exporte QT_QPA_PLATFORMTHEME=qt5ct. Sur cette machine, le plugin Qt6 expose aussi la clé qt5ct ; les deux versions ont été observées ouvrant leurs plugins et leurs palettes générées avec strace. Un nouveau login est nécessaire pour que tous les lanceurs et processus de session héritent de cette variable. L'environnement systemd/DBus courant a été mis à jour pour les nouvelles applications lancées par ces services.

Kitty inclut generated-appearance.conf ; le synchroniseur envoie SIGUSR1 après chaque publication. La documentation locale Kitty 0.49.2 confirme ce signal de rechargement. Le synchroniseur n'ouvre aucun socket de contrôle. L'opacité normale préexistante était 1.0 ; Sun Light et Sun Dark restent à 1.0.

Neovim lit l'état avant de choisir son premier colorscheme, puis surveille le répertoire de effective.json pour les renommages atomiques. Un état absent ou invalide retombe sur Mocha sans bloquer l'éditeur. Le watcher est fermé à VimLeavePre. lazy-lock.json préexistant reste hors chantier.

Firefox consulte la préférence système/portail quand le thème actif prend en charge les deux palettes et que le contenu est configuré sur Auto. Le portail existant xdg-desktop-portal-gtk a renvoyé 1 en sombre et 2 en Sun Light. La source Mozilla définit l'override contenu 0=Dark, 1=Light, 2=Auto. La migration doit être faite dans l'interface Firefox : choisir un thème compatible avec les deux palettes, dont le thème intégré System ou le Proton 1.1 audité, et l'apparence des sites Automatic, puis vérifier localement matchMedia('(prefers-color-scheme: dark)').matches en Mocha, Sun Light et Sun Dark. Le chrome et le contenu doivent être contrôlés séparément. Aucune écriture de prefs.js, base SQLite ou fichier d'extensions n'est permise pendant que Firefox est ouvert.

Avant la migration, une page HTML locale a été ouverte dans le profil actif et a affiché light en Mocha, Sun Light et Sun Dark. Ce test confirme que le contenu ne suivait alors pas la préférence système. La fenêtre de test a été fermée.

Validation de migration du 5 octobre 2026

Après les changements manuels dans Firefox, le profil actif découvert par profiles.ini indique proton-theme@mozilla.org, et ne contient plus de préférence layout.css.prefers-color-scheme.content-override : la valeur par défaut Auto vaut 2. Le thème intégré System n'est donc pas le thème actif, malgré le choix annoncé dans l'interface. Le manifeste local du thème Proton 1.1 possède theme et dark_theme. Les essais réels ont montré que son chrome suit la préférence du portail : sombre en Mocha normal, clair en Sun Light, sombre en Sun Dark, sans redémarrage. La page HTML locale a rendu dark, light, dark ; lors du premier passage en Sun Light, un rechargement a accéléré l'observation de light. Lors du second passage, la page déjà ouverte a basculé après un délai sans rechargement. Le portail a rendu respectivement 1, 2, 1. L'adaptateur accepte donc ce thème précis comme intégration Light/Dark système, tout en signalant son identifiant réel. Il ne lit que profiles.ini et prefs.js et n'écrit aucun fichier Firefox. Le thème Proton n'est pas littéralement le thème intégré System ; cette nuance n'empêche pas la synchronisation Light/Dark observée.

Vérification et retour arrière

Les transitions Mocha → Latte → Sun Light → Sun Dark → Frappé → Macchiato → Mocha ont produit des résultats indépendants pour les cinq adaptateurs. GTK a basculé prefer-dark/prefer-light, Qt et Kitty ont généré les bonnes palettes, Neovim a basculé live vers Latte, et le portail a publié 1/2. Des captures de Thunar GTK3, qt5ct, qt6ct, Kitty, Neovim et Firefox en Mocha et Sun Light ainsi que des vues globales sont conservées dans ~/.local/state/labfy-appearance/captures/17g/ avec permissions privées. Thunar et les fenêtres de configuration Qt montrent le basculement visuel clair/sombre ; Kitty et Neovim montrent Latte. Une trace d'ouverture GTK4 confirme que ~/.themes/Catppuccin-Mocha/gtk-4.0/gtk.css est réellement lu en Mocha. Avant la migration, Firefox conservait le chrome sombre en Sun Light ; après la migration, il passe au chrome clair. La validation de lisibilité physique en extérieur reste à faire par l'utilisateur ; une capture ne la remplace pas.

Validation automatisée finale : 63 tests Python, py_compile, luac -p, démarrage Neovim headless, qmllint sur 52 QML, systemd-analyze --user verify et git diff --check. L'instance Neovim ouverte est passée à Latte via fs_event. Une rafale de six changements a laissé le .path actif avec la dernière révision publiée. Une réconciliation mesurée a duré environ 73 ms sur cette machine.

Pour désactiver :

systemctl --user disable --now labfy-appearance-app-sync.path labfy-appearance-app-sync.service

Réappliquer l'état courant après une installation ou un redémarrage :

~/.local/bin/appearance-app-sync.py reconcile

Les configurations générées restent utilisables sans le service. Pour retrouver les chemins initiaux, rétablir l'include Kitty kitty-themes/themes/mocha.conf, les deux color_scheme_path vers catppuccin-mocha-lavender.conf, supprimer l'export UWSM et choisir explicitement Mocha dans Neovim. Réactiver le service se fait avec systemctl --user enable --now pour les deux unités.