journey-demo

Journey demo

Écrivez un parcours, testez-le, découpez-le. Claude exécute un parcours utilisateur dans Chrome, sauvegarde chaque écran sous forme de page HTML figée, dispose les images sur un storyboard que la personne édite dans son navigateur, et seulement après approbation, génère un MP4 avec HyperFrames. Rien n'est enregistré depuis l'écran, donc n'importe quel mot sur n'importe quel écran peut être changé ultérieurement sans relancer le parcours.

Source de vérité : STORYBOARD.md + snapshots/*.html dans le dossier de la démo. Tout le reste est généré.

Prérequis

• Chrome avec l'extension Claude dans Chrome (pour exécuter le parcours et capturer)
• Node 18+, et npx hyperframes (images fixes et le rendu ; aucune étape d'installation)
• Scripts dans cette compétence : scripts/freeze.js (capture), scripts/demo.mjs (construction et le tableau éditable). Exécutez-les par chemin : node <chemin_compétence>/scripts/demo.mjs …

Le dossier de la démo

docs/demos/<slug>/ dans le dépôt de la personne, sauf si elle en nomme un autre :

STORYBOARD.md        le plan : images, légendes, clics, minutage, notes           (éditer)
snapshots/*.html     les écrans capturés                                        (texte uniquement)
index.html scenes/ boards/ .build/    généré par demo.mjs                       (ne jamais éditer)
out/<slug>.mp4       le rendu

Suggérez d'ajouter scenes/ .build/ boards/stills/ out/ au fichier .gitignore.

1. Le parcours

Utilisez un fichier de parcours quand il en existe un (docs/journeys/*.md : Start:, étapes numérotées, vérifications Expect:, lignes > Note:). Si la compétence browser-journeys est installée, elle possède ce format et ses règles d'exécution, et vous les suivez. Pas encore de parcours ? Écrivez-en d'abord un avec la personne : la démo n'est aussi bonne que les étapes.

Avant d'exécuter, demandez en un message, avec votre recommandation pour chacun :

• Hôte : local ou staging ; jamais la production sauf si la personne le dit.
• Branche : lorsque le parcours propose un choix (copier depuis une bibliothèque ou écrire un nouveau, fiche sauvegardée ou nouvelle fiche), quel chemin la démo montre. Par défaut : le chemin heureux le plus court.
• Valeurs : les valeurs de test du parcours ("Test de parcours — veuillez ignorer") ou des valeurs adaptées à la démo que vous proposez. Par défaut : proposez des valeurs adaptées à la démo, et utilisez-les partout où elles apparaissent.
• Message et public : rédigez les deux à partir du parcours ; ils confirment.
• Effets de bord : dites ce que l'exécution crée sur cet hôte (comptes, commandes, offres) et le nettoyage du parcours, s'il en a un.

Un parcours écrit pour un autre hôte (Start: local, commandes d'initialisation, codes lus depuis un journal de développement) ? Ses lignes de configuration appartiennent à cet hôte : demandez les équivalents sur celui-ci, ne devinez jamais.

2. Exécutez-le et capturez

1. resize_window à 1440×900 et conservez cette taille pour toute l'exécution : chaque image doit partager un seul viewport, et la construction refuse les tailles mélangées.
2. Faites chaque étape comme le dit le parcours. Vérifiez chaque Expect: ; en cas d'échec, arrêtez et signalez. Une démo n'est jamais construite sur un flux cassé. Une exécution de capture n'a pas besoin d'aller à un rythme visible : attendez seulement que la page se soit stabilisée avant chaque gel.
3. La connexion et les changements de persona sont à la charge de la personne. Dites "Connectez-vous en tant que et dites-moi quand vous avez fini", attendez, puis continuez. Un code que le parcours imprime dans un journal de développement que vous avez démarré peut être saisi par vous ; jamais un mot de passe ou un code provenant de la boîte de réception de quelqu'un. Ne gèlez pas les écrans de connexion (ils montrent des emails) : le storyboard passe d'avant la connexion à après.
4. Choisissez les images : un clic par image. Une image est l'écran juste avant un clic que le spectateur doit suivre pour comprendre le flux. La saisie, le cochage et le choix ont lieu avant le gel, donc l'image les montre effectués ; lorsque l'image doit montrer un champ vide, gèlez avant de taper. Un écran atteint par URL ou sans rien à presser est une image sans click (elle apparaît en fondu). Sautez la configuration et la connexion. Visez 4 à 8 images, et gèlez toujours le dernier écran.
5. Geler : collez l'intégralité de scripts/freeze.js dans la page avec javascript_tool (une fois par chargement de page ; typeof window.__freeze vous le dit), puis await window.__freeze('03-ouvrir-lorbite') (ordre à deux chiffres, puis un slug). Comparez le viewport qu'il renvoie avec celui de la première image ; s'il diffère (un téléchargement ou une barre d'information s'est ouverte), fermez la barre et gèlez à nouveau.
6. Chaque gel télécharge <nom>.html dans ~/Downloads. Déplacez-les dans snapshots/ lorsque l'exécution se termine. Geler à nouveau un même nom fait que Chrome enregistre <nom> (1).html : supprimez d'abord l'ancien téléchargement. Si Chrome demande l'autorisation pour plusieurs téléchargements, la personne clique sur Autoriser.

3. Écrire STORYBOARD.md

Format de storyboard d'HyperFrames. Une image par écran figé :

---
message : Ouvrir un Orbit en moins d'une minute
audience : Créateurs YouTube qui hésitent à essayer ShoutOrbit
parcours : docs/journeys/creer-un-orbit.md (étapes 4–5, staging, 2026-11-13)
url : staging.shoutorbit.com
statut : brouillon
---

## Image 3 : Ouvrir l'Orbit (8-12s)
- durée : 4s
- instantané : 03-ouvrir-lorbite.html
- clic : Ouvrir l'Orbit
- scène : Les dates et l'offre se remplissent automatiquement

Le bas du formulaire, dates déjà remplies. Le curseur appuie sur "Ouvrir l'Orbit".
Question ouverte : le champ titre affiche encore son espace réservé. Le taper à l'écran, ou le garder ?

• clic : le libellé complet de l'élément, exactement : son texte visible, sa valeur, son espace réservé ou son aria-label ("Enchérir · 25 €", pas "Enchérir"). La construction le trouve à chaque exécution et échoue bruyamment si elle ne le trouve pas. Omettez-le sur une image sans clic.
• durée : secondes à l'écran, 3–5 ; 4s si omis.
• scène : la légende à l'écran : courte, sur ce que le spectateur obtient ("Les dates se remplissent toutes seules"), pas sur ce qu'il presse.
• Lignes de plan : ce que l'image montre et ce que le curseur fait, en termes simples.
• Question ouverte : une ligne par chose que la personne doit décider. Examinez chaque écran figé pour : données de test ou poubelles à l'écran ; données personnelles (emails, vrais noms, numéros de compte) ; espaces réservés là où les vraies valeurs doivent être ; une légende que l'écran contredit ("en direct" au-dessus de "Pas encore d'enchères") ; dates obsolètes. Soulevez-les ; ne les corrigez jamais en silence.

4. Construire et remettre le tableau

node <chemin_compétence>/scripts/demo.mjs serve docs/demos/<slug> --port 4321   # exécuter en arrière-plan

Il construit, puis sert http://127.0.0.1:4321/. Ouvrez-le pour la personne (Chrome ou open) et arrêtez. Sur le tableau, ils peuvent changer les légendes, les clics, les secondes, les titres et l'ordre, supprimer des images, écrire des notes pour Claude, retaper des mots sur la page capturée elle-même (Modifier le texte de la page ; renommer l'élément cliqué emporte le clic avec lui), et appuyer sur Approuver pour rendu. Chaque sauvegarde reconstruit les images fixes.

5. Agir sur les notes

Lorsqu'ils disent avoir laissé des notes, lisez STORYBOARD.md. Pour chaque ligne > Note: :

Ils demandent	Changer
Légende, minutage, ordre, clic	Les clés de l'image dans STORYBOARD.md
Mots différents sur la page	Texte dans ce snapshots/*.html (texte uniquement : gardez les balises et les classes)
Un écran qui n'a pas été capturé, ou un état différent	Exécutez à nouveau cette étape du parcours et gelez-la
Quelque chose que le flux ne peut pas montrer	Dites-le ; proposez la version vraie la plus proche

Puis transformez la note en > Fait : <ce qui a changé> (le tableau les montre comme faits), mettez statut : brouillon dans le frontmatter (seule la personne approuve), exécutez node <chemin_compétence>/scripts/demo.mjs build docs/demos/<slug>, et dites-leur de rafraîchir le tableau. Le serveur peut continuer à tourner.

6. Rendu

Seulement lorsque le frontmatter dit statut : approuvé, ou que la personne dit d'y aller dans le chat :

cd docs/demos/<slug> && npx hyperframes check && npx hyperframes render -o out/<slug>.mp4

Des avertissements check concernant les sous-compositions, la densité des pistes et un film silencieux sont attendus. Ouvrez le MP4 pour eux. Si l'interface change plus tard, exécutez à nouveau le parcours, re-gélez les images dont les écrans ont changé, conservez le storyboard, et rendez : c'est toute la mise à jour.

Erreurs courantes

Symptôme	Cause et correctif
Le curseur atterrit en dessous ou à côté de sa cible	Images capturées à des tailles de fenêtre différentes, ou la page était en cours de défilement. Recapturez à une seule taille.
rien nommé "…" de la construction	Le texte clic ne correspond pas exactement à l'écran (casse, espace, un →). Copiez-le depuis la page.
le viewport de la sonde était …	Le chrome de la fenêtre de Chrome sans tête a changé ; ajustez CHROME_UI dans demo.mjs.
Une image montre un champ vide	Gelé avant la saisie. Remplissez, puis gelez.
Images ou polices manquantes dans une image	Servies depuis une origine croisée sans CORS, donc freeze.js a conservé l'URL ; elles ne se chargent que tant que cet hôte est actif. Notez-le comme une question ouverte.
Stripe ou autres iframes vides	freeze.js supprime les iframes. Geler l'écran avant ou après eux, ou dites ce qui manque.
Chrome non trouvé	Définissez CHROME=/chemin/vers/chrome.

Confidentialité

Un instantané contient tout ce qui était à l'écran, avec les images intégrées. Avant que quiconque partage le tableau, le dossier ou la vidéo, vérifiez les images pour des données personnelles, et soulevez ce que vous trouvez comme questions ouvertes.