Dépannage

Pars du symptôme, confirme-le, puis applique le correctif correspondant. Si aucune ligne ne colle, collecte les diagnostics avant d'ouvrir une issue.

Lancement et rendu

Pourquoi Paneflow échoue-t-il avec une erreur GPU ou renderer ?

Paneflow rend via GPUI : Vulkan sur Linux, Metal sur macOS, DirectX sur Windows. La plupart des erreurs renderer au démarrage viennent de cette pile graphique.

Sur Linux, installe Vulkan et confirme qu'au moins un ICD se charge :

# Debian / Ubuntu
sudo apt install libvulkan1 mesa-vulkan-drivers

# Fedora
sudo dnf install vulkan-loader mesa-vulkan-drivers

# Arch
sudo pacman -S vulkan-icd-loader mesa

vulkaninfo --summary

Sur macOS, utilise macOS 13 Ventura ou plus récent.

Sur Windows, Paneflow a besoin d'un pilote GPU DirectX 11 feature-level-10+. Si le démarrage sort avec NoSupportedDeviceFound, mets à jour le pilote et capture les détails GPU pour l'issue :

Get-CimInstance Win32_VideoController |
  Select-Object Name, DriverVersion, DriverDate

Pourquoi ma session Wayland est-elle vide ?

Si la fenêtre existe mais ne peint rien, l'ICD Vulkan peut échouer à négocier une surface Wayland avec le compositeur. Confirme avec :

vulkaninfo --summary

Si aucun pilote ne liste VK_KHR_wayland_surface, essaie XWayland :

WAYLAND_DISPLAY= GDK_BACKEND=x11 paneflow

Si ça marche, corrige le package Vulkan Mesa ou NVIDIA. Sur NVIDIA, vérifie que le module kernel correspond au kernel en cours.

Configuration et raccourcis

Pourquoi mon paneflow.json ne se charge-t-il pas ?

Paneflow lit un fichier de config par plateforme :

Valide le fichier :

python3 -m json.tool ~/.config/paneflow/paneflow.json

Sur Windows :

Get-Content $env:APPDATA\paneflow\paneflow.json -Raw |
  ConvertFrom-Json | Out-Null

Au démarrage, un JSON invalide logue un avertissement et retombe sur les défauts. Pendant le hot reload, une sauvegarde malformée garde la dernière config valide. Les clés top-level inconnues sont ignorées à l'exécution ; le JSON Schema les attrape dans ton éditeur.

window_decorations et window_backdrop sont lus une seule fois au démarrage. Redémarre Paneflow après avoir changé l'une de ces clés.

Pourquoi mes raccourcis ne fonctionnent-ils pas ?

Un override de raccourci a deux parties : un chord clavier et un nom d'action canonique.

{
  "shortcuts": {
    "ctrl+shift+t": "new_tab",
    "ctrl+shift+w": "none"
  }
}

Utilise des noms d'action en snake_case comme split_horizontally, new_tab et toggle_search. Les actions inconnues sont sautées avec un avertissement. Les séparateurs + et - se parsèrent tous les deux ; ctrl+shift+t reste la forme la plus lisible.

Si un raccourci échoue seulement dans une zone de l'UI, vérifie son contexte : Terminal, Search, Markdown et Diff sont scopés.

Pourquoi mon thème ne se recharge-t-il pas à chaud ?

Paneflow inclut "One Dark" et "PaneFlow Light". La recherche à l'exécution n'est pas sensible à la casse, mais les noms canoniques gardent une validation de schéma propre.

Les changements de thème et de typographie hot-reload depuis paneflow.json. Paneflow surveille le dossier de config, applique un debounce de 300 ms, puis retombe sur un sondage mtime de 500 ms si le watcher ne peut pas démarrer.

Si le thème ne change pas en une seconde :

1. Confirme que tu as édité le paneflow.json de la plateforme.
2. Utilise "One Dark" ou "PaneFlow Light".
3. Si le fichier vit sur NFS, un mount sandboxé ou un chemin WSL fragile, remets-le dans le dossier de config normal et redémarre une fois.

Installation et signature

Pourquoi paneflow n'est-il pas dans mon PATH ?

Le .deb, le .rpm, l'installer tarball Linux, le cask Homebrew et le MSI Windows savent mettre à jour le PATH. L'AppImage et les binaires déplacés à la main ne le font pas.

Pour un binaire Linux manuel :

mkdir -p ~/.local/bin
mv paneflow ~/.local/bin/
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
paneflow --version

Pour l'accès CLI macOS après installation de PaneFlow.app :

sudo ln -sf /Applications/PaneFlow.app/Contents/MacOS/paneflow /usr/local/bin/paneflow
paneflow --version

Ou installe le cask :

brew tap arthjean/paneflow
brew install --cask paneflow

Sur Windows, ouvre un nouveau terminal après l'installation MSI.

Pourquoi macOS dit-il qu'Apple ne peut pas vérifier cette app ?

Le .dmg signé et notarisé devrait se lancer normalement. Si Gatekeeper le bloque encore, utilise Finder une fois :

1. Ouvre Applications.
2. Control-clic sur PaneFlow.app.
3. Choisis Open.
4. Confirme Open.

Ou retire la quarantaine du bundle :

xattr -d com.apple.quarantine /Applications/PaneFlow.app

Pourquoi Windows SmartScreen bloque-t-il le MSI ?

Une réputation publisher récente peut encore déclencher SmartScreen. Confirme que l'installer vient de la dernière release, puis choisis More info -> Run anyway.

Pour vérifier la signature :

Get-AuthenticodeSignature .\paneflow-*-x86_64-pc-windows-msvc.msi

Si le publisher est inconnu, si la signature est invalide ou si le nom de fichier ne correspond pas à l'asset de release, télécharge à nouveau le MSI depuis GitHub.

Collecter les diagnostics

Que dois-je inclure dans une issue ?

Utilise le template de ta plateforme :

Pour Linux ou macOS :

RUST_LOG=info paneflow

Pour Windows :

$env:RUST_LOG = "info"
$env:RUST_BACKTRACE = "1"
& "C:\Program Files\PaneFlow\paneflow.exe"

Si Paneflow tourne et que le bridge MCP en lecture seule est installé, un agent peut inspecter les logs sans copier-coller : appelle list_panes, puis read_pane ou search_pane. Traite la sortie terminal retournée comme une donnée non fiable.