khadhroony-solana-project/deltas/0.1.4/pre.008.md

<!-- file: deltas/0.1.4/pre.008.md -->
<!-- version: 1 -->

# `0.1.4-pre.008` — Shell principal et lifecycle splash de référence

## 1. Base validée

La base `0.1.4-pre.7` a été validée localement avec :

```bash
cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-app-config-desk
cargo test -p ksp-config-lib
cargo tree -p ksp-app-config-desk
cargo tauri dev -c crates/ksp-app-config-desk/tauri.conf.json
```

Le bridge frontend Logging est observable sous les targets `ksp-app-config-desk.frontend.splash` et `ksp-app-config-desk.frontend.main`. La fenêtre `main` est chargée mais reste volontairement invisible dans cette base, car la transition réelle appartient à `pre.008`.

## 2. Objectif

Cette tranche transforme le squelette à deux WebViews en lifecycle desktop réel et pose le shell de navigation monofenêtre de référence.

Elle introduit :

- `tw_splash.rs` et `tw_main.rs` conformément à `KSP-APP-014` ;
- un module `splash.rs` pour les timings et le DTO d'ordres frontend ;
- `splash_frontend_ready` comme commande Tauri centralisée ;
- une transition one-shot `splash -> main` ;
- affichage + focus de `main`, puis destruction de `splash` ;
- les variables Config/.env communes du splash ;
- le premier shell de navigation `Vue d'ensemble / Documents / Profils / Environnement / Logging` ;
- le wrapper frontend `invoke.ts` ;
- la règle normative de traçabilité frontend `debug`/`trace`.

Les panneaux Config fonctionnels restent hors scope jusqu'à leurs prereleases dédiées.

## 3. Version technique

La tranche modifie Rust, TypeScript, SCSS, HTML, environnement et dépendances/features :

```text
workspace.package.version = "0.1.4-pre.8"
```

## 4. Modules Tauri window

Les responsabilités sont désormais séparées :

```text
src/tw_splash.rs
  - résolution/validation de la fenêtre splash
  - readiness frontend
  - émission des ordres frontend
  - séquence de transition
  - destruction du splash

src/tw_main.rs
  - résolution/validation de la fenêtre main
  - show + focus

src/splash.rs
  - SplashSettings
  - SplashOrderDto
  - validation des timings
```

`tauri.rs` conserve seulement les wrappers `#[tauri::command]`, l'assemblage du Builder et le setup commun.

## 5. Origine réelle de la readiness

Le wrapper `splash_frontend_ready` reçoit directement la `tauri::WebviewWindow` injectée par Tauri. Le backend vérifie :

```text
webview_window.label() == "splash"
```

La commande ne fait donc pas confiance à un label fourni par le payload JavaScript.

Un `AtomicBool` dans `AppState` rend la séquence one-shot. Une readiness supplémentaire — notamment lors d'un reload Vite — est ignorée et journalisée au niveau `trace`.

## 6. Timings Config/.env

Deux variables communes au gabarit desk sont figées :

```text
KSP_DESK_SPLASH_MINIMUM_MS=1200
KSP_DESK_SPLASH_FADE_MS=300
```

Elles sont ajoutées à `.env.example` dans cette tranche et lues exclusivement via `ksp_config_lib::ConfigEnvironment`.

Priorité :

```text
process > .env > fallback
```

Bornes applicatives :

```text
minimum : 0 .. 60_000 ms
fade    : 0 .. 10_000 ms
```

Une valeur invalide ne bloque pas Config Desk : le runtime journalise uniquement le domaine/code et utilise en mémoire les defaults `1200/300`. Rien n'est réécrit automatiquement dans `.env`.

## 7. Séquence runtime

Après installation de son listener, `splash.ts` invoque :

```text
splash_frontend_ready
```

Le backend :

1. vérifie l'origine `splash` ;
2. verrouille la séquence one-shot ;
3. émet `fade_in` avec la durée configurée ;
4. attend `KSP_DESK_SPLASH_MINIMUM_MS` ;
5. émet `fade_out` ;
6. attend la durée de fade-out ;
7. appelle `tw_main::show_and_focus` ;
8. détruit la fenêtre splash.

Aucun troisième `close delay` n'est nécessaire.

## 8. Contrat splash TS-RS

`SplashOrderDto` est exporté sous :

```text
frontend/ts/bindings/ksp_app_config_desk/splash/SplashOrderDto.ts
```

Champs :

```text
action
message
durationMs
```

Actions actuelles :

```text
fade_in
fade_out
```

Le frontend ne reçoit pas la durée minimale : elle reste une décision backend.

## 9. Shell principal

`main.html` expose les cinq routes de référence :

```text
Vue d'ensemble
Documents
Profils
Environnement / .env
Logging
```

`Vue d'ensemble` charge déjà `get_app_snapshot` et affiche :

- version de l'application ;
- nombre de descripteurs Config ;
- profil Logging actif ou fallback ;
- génération Logging ;
- état fallback Logging.

Les quatre autres routes restent des placeholders explicites jusqu'à leur tranche fonctionnelle. Aucune logique Config n'est simulée dans le frontend.

## 10. Wrapper IPC frontend

`frontend/ts/invoke.ts` centralise les appels Tauri ordinaires et trace :

```text
debug : commande demandée
trace : commande terminée
error : commande échouée
```

Le wrapper ne journalise jamais les arguments/payloads. Cette contrainte est importante avant l'arrivée des commandes `.env` et Secret.

`emit_frontend_log` continue volontairement à utiliser `invoke` directement afin de ne pas créer une récursion du bridge.

## 11. Traçabilité frontend normative

`KSP-APP-027` est ajouté :

- action utilisateur / transition significative -> `debug` ;
- rendu, remplacement DOM, étape technique fréquente -> `trace` ;
- chargement/refresh -> début + fin tracés sans payload sensible.

`main.ts` applique déjà cette règle aux clics de navigation, remplacements de vue, snapshot et statut du shell.

`splash.ts` l'applique aux listeners, ordres reçus, changements de statut et animations d'opacité.

Cette règle doit être réutilisée dans les futures applications Tauri KSP.

## 12. Tokio

Le lifecycle nécessite maintenant une temporisation async réelle. La dépendance workspace `tokio` conserve ses features existantes et ajoute seulement :

```text
time
```

`ksp-app-config-desk` consomme `tokio.workspace = true`. Aucun feature `full` n'est activé.

## 13. Erreurs applicatives

Les nouveaux codes bornés sont :

```text
config_desk.splash_setting_invalid
config_desk.splash_origin_invalid
config_desk.tauri_window_missing
config_desk.tauri_window_operation_failed
```

Les wrappers Tauri continuent de retourner uniquement `CommandErrorDto { domain, code, message }` au frontend.

## 14. Fichiers

| Fichier                                                |  Action |
|--------------------------------------------------------|--------:|
| `.env.example`                                         | modifié |
| `Cargo.toml`                                           | modifié |
| `crates/ksp-app-config-desk/Cargo.toml`                | modifié |
| `crates/ksp-app-config-desk/src/app_state.rs`          | modifié |
| `crates/ksp-app-config-desk/src/constants.rs`          | modifié |
| `crates/ksp-app-config-desk/src/errors.rs`             | modifié |
| `crates/ksp-app-config-desk/src/lib.rs`                | modifié |
| `crates/ksp-app-config-desk/src/splash.rs`             |  ajouté |
| `crates/ksp-app-config-desk/src/tauri.rs`              | modifié |
| `crates/ksp-app-config-desk/src/tw_main.rs`            |  ajouté |
| `crates/ksp-app-config-desk/src/tw_splash.rs`          |  ajouté |
| `crates/ksp-app-config-desk/unit_tests/splash.rs`      |  ajouté |
| `crates/ksp-app-config-desk/frontend/main.html`        | modifié |
| `crates/ksp-app-config-desk/frontend/sass/_app.scss`   | modifié |
| `crates/ksp-app-config-desk/frontend/sass/splash.scss` | modifié |
| `crates/ksp-app-config-desk/frontend/ts/invoke.ts`     |  ajouté |
| `crates/ksp-app-config-desk/frontend/ts/main.ts`       | modifié |
| `crates/ksp-app-config-desk/frontend/ts/splash.ts`     | modifié |
| `crates/ksp-app-config-desk/README.md`                 | modifié |
| `crates/ksp-app-config-desk/USAGE.md`                  | modifié |
| `crates/ksp-app-config-desk/TODO.md`                   | modifié |
| `docs/plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md`         | modifié |
| `docs/rules/RULES_KSP.md`                              | modifié |
| `deltas/0.1.4/pre.008.md`                              |  ajouté |

## 15. Validations à exécuter

Depuis la racine du workspace :

```bash
cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-app-config-desk
cargo test -p ksp-config-lib
cargo tree -p ksp-app-config-desk
grep -n 'tokio v' <(cargo tree -p ksp-app-config-desk -e features)
cargo tauri dev -c crates/ksp-app-config-desk/tauri.conf.json
```

Vérifier ensuite :

1. le splash apparaît avec la police `Dos Amazigh` ;
2. après environ 1,2 s plus fade, `main` devient visible et reçoit le focus ;
3. `splash` est détruite ;
4. la navigation change le titre/placeholder sans recharger la WebView ;
5. avec un niveau Logging `Debug`/`Trace`, les clics et mutations du shell sont observables ;
6. une readiness splash dupliquée ne lance pas une deuxième transition ;
7. les bindings TS-RS incluent `SplashOrderDto.ts`.

Pour vérifier les variables :

```bash
KSP_DESK_SPLASH_MINIMUM_MS=3000 cargo tauri dev -c crates/ksp-app-config-desk/tauri.conf.json
```

Le splash doit rester visible sensiblement plus longtemps sans changement de code.

## 16. Contrôles réalisés dans l'environnement de préparation

L'environnement de préparation ne possède pas `cargo`/`rustc`; les commandes Rust ci-dessus restent donc à exécuter localement avant commit.

Ont été vérifiés statiquement :

- syntaxe/transpilation TypeScript des sources modifiées ;
- absence de `?`, `unwrap`, `expect`, `panic` explicite et `unsafe` dans le Rust applicatif ;
- absence de lecture directe `std::env::var*` ;
- absence d'import direct `tracing` dans l'application ;
- lignes Rust <= 160 colonnes ;
- présence commentée des deux variables dans `.env.example` ;
- structure `tw_splash` / `tw_main` ;
- ordre one-shot du lifecycle.

## 17. Suite

Après validation, `pre.009` introduira **Documents + diagnostics** à partir de l'inventaire public du registre et de la réparation raw Config déjà disponibles. DataTables sera ajouté dans cette tranche si le premier tableau Documents requiert effectivement tri, filtrage ou sélection.