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

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

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.

Suite possible (backlog)

• Complication Watch (nouvelle target widget watchOS — à créer dans Xcode).
• Lockscreen widgets (accessoryRectangular / accessoryCircular) — ajouter les familles.
• Background refresh (App Background Tasks) si on veut un widget à jour sans ouvrir l'app.