Playbook de Débogage Frontend Pryne
Symptôme→triage pour les builds de démo vanilla-JS de Pryne : pages HTML uniques pilotées par un module central window.Roll (design-demos/js/roll-*.js), un shader WebGL avec fallback 2D, une boucle de rendu rAF, un smooth-scroll Lenis embarqué et GSAP chargé async depuis un CDN en tant qu'amélioration progressive.
CONTEXTE REQUIS : superpowers:systematic-debugging détient la discipline générique de cause racine (pas de correctifs sans investigation). Suivez-la ; cette compétence ne fournit que la table de symptômes et les pièges spécifiques au projet.
Outillage : pour savoir comment piloter le navigateur, capturer les consoles, émuler le mouvement réduit et prendre des traces, utilisez pryne-browser-lab. Cette compétence suppose que vous pouvez déjà exécuter ces commandes.
Lisez d'abord le commentaire d'en-tête
Chaque démo v4 (v4-a à v4-d dans design-demos/) porte son historique d'audit sous forme de commentaire HTML tout en haut du fichier — ce qui a été trouvé cassé, ce qui a été corrigé, et pourquoi. Vérifié sur les quatre fichiers au 2026-07-22. Avant de re-diagnostiquer quoi que ce soit, faites head -30 sur la démo que vous déboguez. Plusieurs « bugs » que vous trouverez sont documentés comme des régressions déjà corrigées ; si l'un d'eux est de retour, cherchez ce qui l'a réintroduit, pas une nouvelle cause.
Connaissez aussi la structure du build (au 2026-07-22) : seul v4-d-hybrid.html utilise les modules partagés roll-*.js. v4-a/b/c sont des builds de comparaison réduits avec leur propre JS inline — les vérifications spécifiques à Roll de ce tableau ne s'appliquent pas à elles, mais les mêmes classes de défaillance s'appliquent.
Zéro erreur console est l'état de repos
La norme est zéro erreur console (la rubrique CRITIQUE dans design-demos/DECISIONS.md l'exige). v3 a été vérifié à zéro selon le journal d'état du projet ; les variantes v4 ne sont pas certifiées en attendant la campagne de direction (pryne-design-direction-decision). Toute erreur console est un défaut à trier, jamais un bruit ambiant à ignorer.
Tableau symptôme → triage
| Symptôme | Cause probable | Vérification discriminante |
|---|---|---|
| L'animation/develop-plate s'exécute (ou se termine) avant que sa section ne soit défilée dans la vue | Régression du verrouillage de visibilité. Le commentaire d'en-tête de v4-d enregistre ceci comme le correctif d'audit le plus prioritaire : les feature plates « se déclenchaient inconditionnellement depuis le chargement de la page et finissaient de se résoudre avant que quiconque ne les ait atteintes en défilant ». Le développement doit être verrouillé sur la classe .in du panneau. | Expérience 1 ci-dessous |
| L'animation de révélation clippe mal, saute ou ne se déclenche jamais | clip-path appliqué à l'élément surveillé par l'IntersectionObserver, au lieu d'un wrapper intérieur. Le correctif concept-C (reporté dans v4-d, selon son commentaire d'en-tête) : le clip-path de révélation vit sur un wrapper intérieur, jamais sur l'élément observé. | Inspectez l'élément : le nœud observé et le nœud clippé sont-ils le même nœud ? |
| Le curseur OS disparaît, aucun curseur personnalisé ne le remplace | Ne devrait pas se reproduire — corrigé le 2026-07-22 (découvert par un audit cold-test, corrigé le même jour) : le gestionnaire par événement (roll-cursor.js:17-20) et son site d'appel pointermove (roll-core.js:26-29) attrapent et restaurent maintenant tous deux (null Roll.cursorUpdate, suppriment .custom-cursor), en plus de l'attrapé initial au setup ; le z-index de #cur/#ring est passé de 50 à 70 au-dessus de #flash (60) pour que l'impulsion du climax ne puisse pas peindre sur le curseur. Si le symptôme réapparaît, l'une de ces gardes a régressé ou un nouveau code cache le curseur en dehors de ce contrat. | document.body.classList.contains('custom-cursor') vs Roll.cursorUpdate — true/null ensemble est l'état cassé ; si les deux semblent intacts, vérifiez getComputedStyle(cur).opacity et s'il disparaît seulement au flash du climax |
| Fantômes/traînées WebGL, ou mélange de couleurs incorrect par rapport à la page | Effacement par image manquant, ou incohérence de premultiplied-alpha. roll-shader.js appelle gl.clear(gl.COLOR_BUFFER_BIT) à chaque image et crée le contexte avec { alpha: true, premultipliedAlpha: false } (deux correctifs d'audit, selon le commentaire d'en-tête de v4-d). | Diff roll-shader.js par rapport à git : git diff HEAD -- design-demos/js/roll-shader.js |
| Canvas du shader vide, pas de grain du tout | (a) Mouvement réduit — GL n'est intentionnellement jamais configuré (useGL = !Roll.reduced && setupGL()) ; (b) Contexte WebGL perdu — le gestionnaire webglcontextlost met l'opacité du canvas à 0 et échoue silencieusement ; (c) Un contexte 2D a été acquis avant que WebGL ait eu sa chance (un contexte par canvas, à jamais — documenté en haut de roll-shader.js). | Roll.reduced d'abord. Pour la perte de contexte, vérifiez l'effet observable du gestionnaire : getComputedStyle(document.getElementById('tone')).opacity === '0''. Caveat : Roll.shader.useGL est un instantané pris au setup (roll-shader.js:120-121) — le gestionnaire webglcontextlost ne modifie que la variable de fermeture (roll-shader.js:130-132), donc Roll.shader.useGLrestetrue` après la perte de contexte ; ne l'utilisez pas pour exclure la perte. |
| La chorégraphie de scroll est morte mais la page s'affiche et défile correctement | Ordre de chargement des scripts ou cassure du namespace window.Roll. L'ordre des scripts est contraignant — la chaîne et les commandes de vérification se trouvent dans pryne-frontend-architecture. Chaque module est une IIFE partageant l'état uniquement via window.Roll ; une erreur lancée dans un module précoce affame tout ce qui suit. | Expérience 2 ci-dessous ; la console montrera Roll.X is undefined nommant le module affamé |
| Tout mouvement mort pour un rapport utilisateur ; fonctionne bien sur votre machine | prefers-reduced-motion est actif pour eux. C'est un comportement correct, pas un bug : roll-core.js définit Roll.reduced à partir de la media query, et chaque module se verrouille dessus (cover supprimé, plates rendues pleinement développées instantanément, Lenis sauté, shader désactivé). Ne le « corrigez » pas. | Expérience 3 ci-dessous |
| Sensation de défilement incohérente entre trackpad/molette/tactile | Variance brute du delta de défilement — la justification documentée pour utiliser Lenis embarqué (voir design-demos/DECISIONS.md). Lenis enveloppe le défilement natif, donc window.scrollY reste valide ; c'est uniquement une amélioration de sensation, nulle sous mouvement réduit. | typeof Lenis (chargé ?), puis vérifiez que la démo le construit dans son module de scroll |
| La ligne de base fonctionne mais les finitions survol/kinétique/curseur manquent | GSAP CDN a échoué ou a été bloqué. GSAP se charge async depuis jsdelivr (épinglé SRI) et bascule Roll.enhanced = true via Roll.upgradeMotion() seulement quand il arrive. L'amélioration progressive est conçue ainsi : la chorégraphie de base doit toujours fonctionner sans lui. Si la base est aussi cassée, ce n'est pas votre cause. | Expérience 4 ci-dessous |
| Audio silencieux | Muet est la valeur par défaut : roll-audio.js démarre en muet, persiste le choix dans localStorage['ch001_muted'], et ne démarre le bourdonnement ambiant qu'au clic sur #mute-toggle (un geste utilisateur, satisfaisant la politique d'autoplay). Toute la synthèse est encapsulée dans des try/catch et sans ressource. Vérifiez l'état du bouton SND avant de suspecter le code. | Roll.audio.muted, et localStorage.getItem('ch001_muted') |
| HUD fixe chevauche/obscurcit le pied de page | Régression du correctif de fondu du footer : un IntersectionObserver sur footer bascule .faded sur le beat-meter et le bouton muet (roll-scroll.js). | Défilez jusqu'au footer ; vérifiez que .faded apparaît sur #beatmeter |
Expériences discriminantes
Exécutez-les dans la console de la page ou via evaluate_script (voir pryne-browser-lab). Chacune répond à une question avant que vous touchiez au code.
1 — Le développement des plates est-il correctement verrouillé sur la visibilité ?
({ workVisible: document.getElementById('work').classList.contains('in'),
plate1: { d: Roll.featurePlate.d, done: !!Roll.featurePlate.done },
plate2: { d: Roll.featurePlate2.d, done: !!Roll.featurePlate2.done } })
Sur un chargement frais, avant de défiler vers la section work : workVisible: false et les deux valeurs d proches de 0. Si d augmente (ou done: true) alors que workVisible est false, le verrouillage a régressé.
2 — La colonne vertébrale Roll est-elle intacte ?
({ core: !!window.Roll, reduced: Roll?.reduced, enhanced: Roll?.enhanced,
shader: !!Roll?.shader, audio: !!Roll?.audio, plates: !!Roll?.plates,
cursorUpdate: Roll?.cursorUpdate === null ? 'null' : typeof Roll?.cursorUpdate })
Note sur cursorUpdate : il est initialisé à null (roll-core.js:23) et est également null avant le chargement de GSAP et sur les appareils non pointer: fine — null seul ne prouve rien. « Échec sûr » n'est indiqué que lorsque document.body.classList.contains('custom-cursor') est vrai et que cursorUpdate est null (voir la ligne du curseur dans le tableau de triage).
Tout false/undefined nomme le module qui n'a pas fini — vérifiez la console pour l'erreur qu'il a lancée, et vérifiez l'ordre des scripts dans le HTML par rapport à l'ordre contraignant ci-dessus.
3 — « Tout mouvement mort » est-il simplement le mouvement réduit ?
({ mediaQuery: matchMedia('(prefers-reduced-motion: reduce)').matches, roll: Roll.reduced })
Les deux true → fonctionne comme conçu ; reproduisez le rapport en émulant le mouvement réduit (pryne-browser-lab). mediaQuery: true mais roll: false (ou vice versa) → un module lit la mauvaise source de vérité.
4 — La couche d'amélioration GSAP s'est-elle chargée ?
({ gsapLoaded: !!window.gsap, enhanced: Roll.enhanced, reduced: Roll.reduced })
gsapLoaded: false → CDN bloqué/échoué (vérifiez le panneau réseau pour la requête jsdelivr ; une incohérence SRI arrive aussi ici). gsapLoaded: true, enhanced: false, reduced: false → upgradeMotion() n'a pas été exécuté — vérifiez le hook onload de la balise script.
Pièges qui coûtent du temps réel
| Piège | L'histoire (une ligne) | La barrière |
|---|---|---|
| « Vérifié fonctionnel » ≠ bonne direction | v3 NIGHT DRIVE était entièrement construit, zéro erreur console, vérifié — puis remplacé parce que le concept unificateur était mauvais (compte rendu complet : pryne-failure-archaeology). | Ne dépensez pas d'effort de polissage/débogage à défendre un build dont le concept n'a pas été confirmé comme la direction actuelle. Vérifiez d'abord DECISIONS.md et l'état du vault. |
| Re-diagnostiquer un correctif documenté | Chaque commentaire d'en-tête de v4 est un journal des modifications des défauts déjà trouvés et corrigés. | Lisez le commentaire d'en-tête avant d'ouvrir les devtools. Si un correctif listé semble cassé, cherchez la régression, pas le symptôme. |
| « Corriger » le mouvement réduit | L'absence totale de mouvement est le comportement conçu pour les utilisateurs avec prefers-reduced-motion, verrouillé à un seul endroit (Roll.reduced). | Exécutez l'expérience 3 avant de traiter un rapport d'absence de mouvement comme un défaut. |
| Acquérir un contexte 2D « pour tester quelque chose » | Un canvas ne peut avoir qu'un seul type de contexte ; acquérir le 2D en premier rend WebGL silencieusement impossible sur ce canvas pour toujours (documenté dans roll-shader.js). | N'appelez jamais getContext('2d') sur #tone dans des expériences console. |
Quand NE PAS utiliser cette compétence
- Discipline de débogage générique (hypothèses, changements minimaux, cause racine avant correctif) → superpowers:systematic-debugging.
- Comment piloter le navigateur/mesurer (anatomie des outils MCP, traces, Lighthouse, captures d'écran) → pryne-browser-lab.
- Décider si un comportement viole un invariant de conception (verrouillage mouvement réduit, personnalité au niveau du murmure, embarquement) → pryne-frontend-architecture.
- L'historique complet de pourquoi quelque chose a été construit/rétabli → pryne-failure-archaeology.
- Autres piles (React/framework builds, projets non Pryne) : le tableau ci-dessus est spécifique à la famille de démos
window.Roll; seule la discipline générique est transférable.
Provenance et maintenance
Exécutez scripts/verify.sh (dans le répertoire de cette compétence) pour tout vérifier d'un coup.
Faits à jour au 2026-07-22, vérifiés par rapport au dépôt ~/Documents/Coding Folder/Portfolio (test) au commit 457868a. Re-vérifiez avant de faire confiance :
- Liste des modules et tailles :
wc -l design-demos/js/*.js - Ordre de chargement des scripts :
grep -n "<script" design-demos/v4-d-hybrid.html - Quelles démos utilisent les modules partagés :
grep -l "roll-core.js" design-demos/*.html - Convention de commentaire d'en-tête toujours valide :
for f in design-demos/v4-*.html; do echo "== $f"; head -5 "$f"; done - Porte de mouvement réduit :
grep -n "prefers-reduced-motion\|Roll.reduced" design-demos/js/*.js - Verrouillage de visibilité des plates :
grep -n "classList.contains('in')" design-demos/js/roll-scroll.js - Lenis embarqué et câblé :
ls design-demos/js/vendor/ && grep -n "new Lenis" design-demos/js/roll-scroll.js - Hook d'amélioration GSAP :
grep -n "upgradeMotion" design-demos/js/roll-core.js design-demos/v4-d-hybrid.html - Valeur par défaut du muet audio et clé de stockage :
grep -n "ch001_muted" design-demos/js/roll-audio.js - Barre zéro-erreur-console :
grep -n "console errors" design-demos/DECISIONS.md