coach-ios/docs/widgets-runbook-mac.md

Runbook Mac — widgets natifs iPhone (Séance du jour + Score de forme)

⚠️ Fixes audit iOS 2026-06-29 — à finir sur le Mac

• ✅ capacitor.config.json réaligné sur capacitor.config.ts (contentInset never, fonds #000000, StatusBar LIGHT) — corrige la régression visuelle bottom-nav ré-embarquée. NB : au prochain npx cap sync ios, ne pas laisser cap sync ré-écraser avec d'anciennes valeurs — vérifier que le .ts reste la source. (Idéalement : ajouter un check CI .ts vs .json.)
• ⏳ aps-environment dans ios/App/App/App.entitlements = development → push cassés en prod/TestFlight. NON modifié depuis Linux (flipper en production casserait les builds dev locaux ; le bon fix est par configuration Release sur le Mac, ou via la capability « Push Notifications » qui le gère automatiquement). À traiter sur le Mac AVANT toute distribution utilisant le push distant.
• ⏳ Entitlements widget + cible Watch : cf. sections plus bas (App Group / CODE_SIGN_ENTITLEMENTS / Target Membership) — c'est aussi un finding de l'audit (widgets muets sans App Group câblé).

Pour le Claude « Cowork » (Mac) / Sylvain. Le code Swift + entitlements + le hook web sont écrits côté coach_sportif/coach-ios par le Claude dev (Linux). Il reste les étapes Mac/portail Apple ci-dessous — elles ne peuvent pas se faire depuis Linux (provisioning + ajout de fichiers aux cibles dans Xcode).

Ce qui est déjà fait (committé)

coach-ios (natif) :

• ios/App/App/CoachWidgetSnapshot.swift — modèle partagé App ↔ extension (App Group).
• ios/App/App/CoachWidgetBridge.swift — plugin Capacitor setSnapshot/clear + WidgetCenter.reloadAllTimelines().
• ios/App/CoachLiveActivity/CoachWidgets.swift — 2 widgets (TimelineProvider + vues SwiftUI).
• ios/App/CoachLiveActivity/CoachLiveActivityBundle.swift — widgets ajoutés au WidgetBundle.
• ios/App/App/MainViewController.swift — plugin enregistré dans capacitorDidLoad().
• ios/App/App/App.entitlements — App Group group.ch.hypnotruck.coach ajouté.
• ios/App/CoachLiveActivity/CoachLiveActivity.entitlements — créé avec l'App Group.

coach_sportif (web, déjà en prod via webhook) :

• web/static/widget-bridge.js + include dans _layout.html — pousse today (depuis /api/today) + forme (recovery_score). No-op hors app native.
• web/templates/home.html — data-form-score exposé sur le hero.

Étapes Mac à faire (dans l'ordre)

1. App Group sur le portail Apple

developer.apple.com → Certificates, IDs & Profiles → Identifiers → App Groups → créer group.ch.hypnotruck.coach (si pas déjà créé).

2. Activer la capability sur les 2 cibles (Xcode)

⚠️ Quitter puis git pull d'abord (règle COWORK : jamais de pull Xcode ouvert). Ouvrir ios/App/App.xcworkspace, puis pour App ET CoachLiveActivity :

• onglet Signing & Capabilities → + Capability → App Groups → cocher group.ch.hypnotruck.coach.
• Vérifier que CODE_SIGN_ENTITLEMENTS pointe bien sur le bon .entitlements (App → App/App.entitlements ; CoachLiveActivity → CoachLiveActivity/CoachLiveActivity.entitlements, à régler si Xcode ne l'a pas pris).

3. Ajouter les nouveaux fichiers aux bonnes cibles (Target Membership)

Les fichiers existent sur disque mais doivent être référencés par le projet :

• CoachWidgetSnapshot.swift → cocher App ET CoachLiveActivity (fichier partagé).
• CoachWidgetBridge.swift → cible App uniquement.
• CoachWidgets.swift → cible CoachLiveActivity uniquement.
• CoachLiveActivity.entitlements → pas une source (référencé par le build setting).

Méthode : clic droit sur le dossier de la cible → Add Files to "App"… (décocher Copy items, cocher la bonne cible), ou sélectionner le fichier → inspecteur de droite → Target Membership.

4. Build + test device

• Clean Build Folder (Cmd+Shift+K) → Run sur l'iPhone.
• Ouvrir l'app (charge la prod) une fois pour que widget-bridge.js pousse le snapshot.
• Écran d'accueil → ajouter les widgets Coach : « Séance du jour » (small/medium) et « Score de forme » (small).
• Vérifier qu'ils affichent les vraies données du jour. Tap → ouvre /calendar resp. /forme.

5. Debug si le widget reste vide

• Vérifier le snapshot écrit : Safari → Développement → iPhone → console → await Capacitor.Plugins.CoachWidgetBridge.setSnapshot({today:{sport:"running",title:"Test",done:false}}) puis long-press l'écran d'accueil → le widget doit se mettre à jour.
• Si rien : l'App Group n'est pas partagé (étape 2) → UserDefaults(suiteName:) renvoie nil.

Modèle de données (contrat web ↔ widget)

{
  "today": { "sport": "running", "title": "Sortie longue", "subtitle": "90 min · Z2", "done": false },
  "forme": { "score": 72, "label": "Prêt" }   // null si pas de score
}

sport ∈ running | cycling | strength | mobility | hiking | walking | rest.

Complication Apple Watch (code écrit — reste la target Xcode)

⚠️ Rappel archi : l'App Group n'est PAS partagé entre iPhone et Watch (conteneurs distincts). Le flux est : iPhone CoachWidgetBridge.pushToWatch → updateApplicationContext → CoachWatch/ConnectivityManager reçoit → écrit dans l'App Group de la MONTRE → la complication lit ce conteneur. Tout ce code est déjà écrit & committé.

Déjà fait (committé)

• iPhone : CoachWidgetBridge.pushToWatch() envoie le snapshot via WCSession (sans être delegate).
• Watch : CoachWatch/ConnectivityManager gère didReceiveApplicationContext/didReceiveUserInfo → CoachWidgetStore.save + WidgetCenter.reloadAllTimelines().
• ios/App/CoachWatchWidgets/CoachWatchComplications.swift — 2 complications (Forme : circular/corner ; Séance : rectangular/inline) + @main WidgetBundle.

Étapes Mac

1. Créer la target : File → New → Target → Widget Extension (plateforme watchOS), nom CoachWatchWidgets, embarquée dans l'app Watch CoachWatch. Supprimer le fichier template généré, puis Add Files CoachWatchComplications.swift à cette target.
2. Target Membership de CoachWidgetSnapshot.swift : cocher CoachWatch (l'app Watch, pour ConnectivityManager) ET CoachWatchWidgets (l'extension complication).
3. App Group group.ch.hypnotruck.coach : activer la capability sur CoachWatch ET CoachWatchWidgets (même ID que l'iPhone ; conteneur physique distinct côté montre).
4. Build la target Watch + extension, lancer sur la montre. Ajouter les complications sur un cadran (Forme = circular ; Séance = rectangular). Ouvrir l'app iPhone une fois pour pousser le 1er snapshot (l'app Watch doit être installée & appairée).
5. Si la complication reste vide : vérifier que updateApplicationContext arrive (log widgetSnapshot reçu de l'iPhone côté watch) et que l'App Group est bien partagé sur les deux targets watch.

Suite possible (backlog)

• Lockscreen widgets iPhone (accessoryRectangular / accessoryCircular) — ajouter les familles aux widgets iOS.
• transferCurrentComplicationUserInfo (réveil complication, budget ~50/j) si besoin de fraîcheur en arrière-plan.
• Background refresh iPhone (App Background Tasks) pour un widget à jour sans ouvrir l'app.