clickreel

Que fait clickreel ?

Vous créez une démo interactive de l'application réelle de l'utilisateur. Un visiteur l'ouvre sur une page d'atterrissage ou depuis un lien, clique sur l'endroit mis en évidence, et l'écran réel suivant de l'application apparaît. Il décide en moins d'une minute si l'application mérite d'être essayée. Un bon résultat parcourt une chose que l'application fait bien en 6 à 12 clics.

Vous écrivez le storyboard et jugez du résultat. Clickreel fait le reste : il ouvre l'application dans un navigateur sans tête, exécute chaque étape pour de vrai, photographie la page avant et après, et regroupe les écrans et un lecteur dans un seul fichier HTML.

La commande

Tout passe par un seul script. Il nécessite uniquement Node et un navigateur basé sur Chromium déjà installé sur la machine.

node ${CLAUDE_SKILL_DIR}/scripts/clickreel.mjs <commande>

Si ${CLAUDE_SKILL_DIR} apparaît ci-dessus en tant que texte littéral, votre agent ne l'a pas renseigné : utilisez le dossier qui contient ce SKILL.md.

Commande	Ce qu'elle fait
build <storyboard>	Exécute les étapes et écrit <nom>.html (la démo) et <nom>.stops.png (la planche contact) à côté du storyboard. Prend 10 à 30 secondes.
check <storyboard>	Exécute les étapes et écrit uniquement la planche contact, dans un dossier temporaire. Utilisez-la pour essayer un storyboard sans toucher au projet.
doctor	Vérifie que cette machine peut construire une démo. Exécutez-la en premier si quelque chose ne démarre pas.
init [fichier]	Écrit un storyboard de démarrage.

Indicateurs utiles : --out <dossier>, --json, --headed (regarder le navigateur travailler), --force.

Comment travailler

1. Décidez ce que la démo montre

Une démo, un flux. Demandez-vous quelle est la chose la plus convaincante que cette application fait, et construisez la démo autour d'elle. Si l'utilisateur a nommé une fonctionnalité ou un flux, c'est le sujet. S'il a seulement dit "fais une démo", choisissez vous-même le flux principal (ce que la première phrase du README promet) et dites lequel vous avez choisi. Ne demandez pas à l'utilisateur de choisir à moins que l'application n'ait plusieurs produits sans lien.

2. Faites fonctionner l'application et apprenez ses véritables libellés

Trouvez comment l'application démarre (scripts package.json, un README, un dossier dist/). Choisissez ensuite une option :

• Déjà en cours d'exécution ou vous pouvez la démarrer vous-même : définissez "url".
• Un site statique ou un dossier construit : définissez "serve": "./dist" et Clickreel le sert.
• Vous voulez que la construction soit reproductible plus tard : définissez "start": "npm run dev" avec "url", et Clickreel la démarre et attend.

Les étapes ciblent les éléments par les mots qu'une personne voit : le texte d'un bouton, le libellé ou le placeholder d'un champ, un aria-label. Lisez les composants pour le flux que vous avez choisi et copiez les libellés exactement. Deviner fait perdre un aller-retour.

La démo doit s'ouvrir sur un état qui mérite d'être regardé. Un écran vide de première utilisation ou un mur de connexion est une ouverture faible. Si l'application a besoin de données ou d'une session connectée, configurez-la avant le premier arrêt : utilisez le script d'amorçage de l'application, ou une étape eval qui écrit dans localStorage, ou connectez-vous avec un compte de test au début. Mettez les mots de passe et les jetons dans les variables d'environnement et référez-vous-y comme ${env:NOM} ; n'écrivez jamais un vrai secret dans le storyboard.

3. Écrivez le storyboard

Enregistrez-le sous demo.click.json à la racine du projet, sauf si l'utilisateur le veut ailleurs. Si le projet a déjà un storyboard Demoreel (*.reel.json), vous pouvez construire à partir de ce fichier tel quel.

{
  "url": "http://localhost:5173",
  "displayUrl": "acme.app",
  "demo": {
    "title": "Acme",
    "intro": "Voyez comment un projet passe de l'idée à la réalisation.",
    "cta": { "label": "Essai gratuit", "url": "https://acme.app/inscription" }
  },
  "steps": [
    { "say": "Lancez un projet en quelques secondes" },
    { "click": "Nouveau projet" },
    { "type": "Lancement du site web", "into": "Nom du projet" },
    { "click": "Créer le projet" },
    { "say": "Ajoutez des tâches aussi vite que vous tapez" },
    { "type": "Rédiger le billet d'annonce", "into": "Ajouter une tâche" },
    { "press": "Entrée" }
  ]
}

Chaque étape devient un arrêt (quelque chose que le visiteur fait) ou rien :

Étape	Dans la démo
{ "click": "Nouveau projet" }	Un point chaud sur l'élément. Le visiteur clique et voit le résultat réel.
{ "type": "bonjour", "into": "Email" }	Un point chaud sur le champ. Cliquer joue la saisie du texte. Omettez into pour continuer la saisie dans le champ focalisé.
{ "press": "Entrée" }	Des touches à cliquer, ou le visiteur appuie sur la vraie touche. "Mod+K" est Cmd sur macOS et Ctrl ailleurs.
{ "hover": "Graphique" }	Un point chaud qui réagit au survol, ou à un tap sur un téléphone.
{ "select": "Pro", "in": "Forfait" }	Un point chaud sur une liste déroulante native.
{ "say": "Une courte ligne" }	La légende affichée pendant les arrêts après elle. Elle reste jusqu'au prochain say. Un say sans arrêt ensuite devient une carte avec un bouton Suivant.
{ "zoom": "Total" }	Une note : l'élément est éclairé, le reste de la page est assombri, et une carte montre la légende avec un bouton Suivant.
{ "scroll": 600 }, { "goto": "/parametres" }, { "wait": 800 }, { "waitFor": "Rapport prêt" }, { "eval": "..." }	Pas d'arrêt. La démo les traverse toute seule. Utilisez-les pour la configuration et pour arriver au bon endroit.

Les mots à côté de chaque point chaud sont écrits pour vous : Cliquez sur "Nouveau projet", Tapez "Lancement du site web", Appuyez sur avec les touches. Ajoutez "hint": "Ouvrir les paramètres" à une étape pour la dire à votre façon. Faites-le quand une étape utilise un sélecteur qui n'a pas de nom lisible (le défaut est alors "Cliquez ici").

Les cibles sont appariées par rapport aux noms visibles, correspondance exacte d'abord. Quand un nom est ambigu, ajoutez "nth": 2, ou utilisez un sélecteur : "css=.sidebar button", "#save", "testid=submit". Ajoutez "optional": true à une étape qui peut n'avoir rien sur quoi agir, comme fermer une bannière de cookies.

La liste complète des étapes, options, styles et cadres se trouve dans references/storyboard.md. Lisez-la avant d'utiliser quelque chose qui n'est pas montré ici.

4. Construisez

node ${CLAUDE_SKILL_DIR}/scripts/clickreel.mjs build demo.click.json

Une étape qui ne peut pas être effectuée arrête la construction et vous dit exactement ce qui ne va pas :

Étape 4 (cliquez sur "Créer projet") a échoué : Impossible de trouver "Créer projet" à cliquer.
  Vouliez-vous dire : "Créer le projet" ?
  À l'écran maintenant : "Annuler", "Créer le projet", "Nom du projet"
  Capture d'écran de la page à ce moment : /tmp/clickreel/demo-123/step-04-failed.jpg

Corrigez l'étape et reconstruisez. Si le projet a déjà un <nom>.html que Clickreel n'a pas écrit, la construction refuse de le remplacer : définissez "name" dans le storyboard ou passez --out <dossier>.

Une construction qui réussit peut encore imprimer des notes. Lisez-les. Note : L'étape 4 (...) n'a rien changé de visible sur la page signifie que l'étape a trouvé quelque chose sur quoi agir, mais la page avait la même apparence après : cela a presque toujours trouvé le mauvais élément, et son arrêt dans la démo ne fait rien. Corrigez la cible (un nom plus exact, nth, ou un sélecteur) et reconstruisez.

5. Regardez le résultat avant de le signaler

build écrit une planche contact, <nom>.stops.png : une image par arrêt, avec le point chaud dessiné dessus et l'étape et la légende en dessous, puis le dernier écran. Ouvrez-la et regardez chaque image. C'est ainsi que vous vérifiez votre propre démo.

Vérifiez chaque image pour :

• Le point chaud. La boîte est-elle sur l'élément que vous vouliez, et cet élément est-il visible ? Une boîte sur la mauvaise chose signifie que le nom a correspondu à autre chose : utilisez nth ou un sélecteur.
• La vérité. L'image montre-t-elle l'application en fonctionnement ? Recherchez les messages d'erreur, les états vides, les spinners qui n'ont jamais fini, le texte de placeholder. Chaque image est ce que le visiteur voit avant de cliquer, donc l'image après montre ce que son clic a fait.
• Les légendes. La légende sous l'image décrit-elle ce qui s'y passe ?
• La dernière image. Elle se trouve derrière la carte de fin. Elle devrait être l'état le plus beau de l'application.

Corrigez le storyboard et reconstruisez. Deux ou trois tours est normal. Arrêtez quand la planche semble correcte.

6. Remettez-la

Dites à l'utilisateur où se trouve le fichier, sa taille, combien d'arrêts il a et quel flux il montre. Donnez-lui la ligne d'intégration que build a imprimée :

<iframe src="demo.html" title="Acme : démo interactive" loading="lazy" allowfullscreen style="width:100%;aspect-ratio:1372/889;border:0;border-radius:12px"></iframe>

Dites clairement ce qu'est le fichier : un fichier HTML avec des images de son application à l'intérieur, qui fonctionne à partir du disque et de tout hébergeur web, et ne charge rien depuis le réseau. Signalez toutes les notes que Clickreel a imprimées (erreurs de page, éléments couverts, fichier volumineux). Si vous n'avez pas réussi à faire fonctionner une étape et que vous l'avez supprimée, dites-le.

Un README GitHub ne peut pas exécuter un fichier HTML. Pour un README, liez la démo là où elle est hébergée (GitHub Pages sert bien docs/), ou utilisez un GIF de Demoreel.

Écrire une bonne démo, en bref

• Six à douze arrêts. Chaque arrêt est un clic que le visiteur doit faire. Supprimez la configuration, ou faites-la avec eval avant le premier arrêt.
• Les légendes sont des titres. Sept mots ou moins, sur l'avantage ("Cochez les choses au fur et à mesure"), pas sur l'action ("Maintenant cliquez sur la case à cocher"). L'indice dit déjà quoi cliquer. Trois à cinq légendes dans une démo.
• Tapez des choses réelles. "Lancement du site web", pas "test" ou "asdf". Le texte tapé fait partie du discours.
• Ouvrez et fermez bien. Définissez demo.title et un demo.intro d'une ligne pour la carte de début. Terminez sur le meilleur état de l'application et définissez demo.cta là où le visiteur devrait aller ensuite.
• Choisissez la taille en fonction de l'endroit où elle sera placée. La fenêtre d'affichage desktop par défaut convient à une page d'atterrissage. Pour une application web mobile, utilisez "viewport": "phone". Une fenêtre d'affichage plus petite fait paraître l'application plus grande dans une intégration de petite taille.

Plus d'informations sur la structure, les notes, la lecture automatique et l'écoute des événements de la démo : references/writing.md.

Confidentialité et honnêteté

• Tout s'exécute sur cette machine. Clickreel n'ouvre aucune connexion réseau propre ; le navigateur charge uniquement l'application que vous lui pointez. Le fichier final ne fait aucune requête et ne traque rien.
• La démo est faite d'images de tout ce qui se trouvait sur la page, et elle est destinée à être publiée. Utilisez des comptes de test et des données fictives. Ne capturez pas de vraies données clients, de vraies adresses e-mail ou des URL internes sans l'accord de l'utilisateur.
• Montrez l'application telle qu'elle est. N'utilisez pas eval pour simuler une fonctionnalité, masquer une vraie erreur, ou faire paraître quelque chose plus rapide qu'il ne l'est. Amorcer des données et masquer les superpositions de développement est acceptable ; inventer un comportement ne l'est pas.

Ce qu'il ne peut pas faire

Applications web uniquement. Les écrans sont des images, donc un visiteur ne peut pas faire défiler à l'intérieur d'un arrêt, sélectionner du texte ou sortir du chemin que vous avez choisi. Une étape drag se joue lorsque son point chaud est cliqué. Il ne suit pas les liens qui ouvrent un nouvel onglet, ne peut pas atteindre l'intérieur des iframes, et ne peut pas télécharger de fichiers. Les boîtes de dialogue alert() et confirm() natives sont acceptées automatiquement et n'apparaissent pas. Si le flux dépend de l'un d'eux, dites-le et construisez la partie qui fonctionne.

Quand quelque chose échoue d'une manière que le message d'erreur n'explique pas, consultez references/troubleshooting.md.